From 50cb67e2e280b318bd269b68d999c6def982ce4a Mon Sep 17 00:00:00 2001
From: Ciro Santilli <ciro.santilli@gmail.com>
Date: Sun, 1 Jul 2018 20:36:03 +0100
Subject: [PATCH] mmap: move doc to README

---
 README.adoc                | 38 ++++++++++++++++++++++++++++++++++++++
 kernel_module/README.adoc  |  2 --
 kernel_module/mmap.c       | 16 +---------------
 rootfs_overlay/mmap.sh     |  4 ++--
 rootfs_overlay/test_all.sh |  1 +
 5 files changed, 42 insertions(+), 19 deletions(-)

diff --git a/README.adoc b/README.adoc
index 07f2cd0..d523b80 100644
--- a/README.adoc
+++ b/README.adoc
@@ -3442,6 +3442,44 @@ Bibliography:
 * https://stackoverflow.com/questions/2264384/how-do-i-use-ioctl-to-manipulate-my-kernel-module/44613896#44613896
 * https://askubuntu.com/questions/54239/problem-with-ioctl-in-a-simple-kernel-module/926675#926675
 
+==== mmap
+
+In guest:
+
+....
+/mmap.sh
+echo $?
+....
+
+Outcome: the test passes:
+
+....
+0
+....
+
+Sources:
+
+* link:kernel_module/mmap.c[]
+* link:kernel_module/user/mmap.c[]
+* link:rootfs_overlay/mmap.sh[]
+
+The `mmap` system call allows us to share memory between user and kernel space without copying.
+
+In this example, we make a tiny 4 byte kernel buffer available to user-space, and we then modify it on userspace, and check that the kernel can see the modification.
+
+`mmap`, like most more complex <<file-operations>>, does not work with <<debugfs>> as of 4.9, so we use a <<procfs>> file for it.
+
+Example adapted from: https://coherentmusings.wordpress.com/2014/06/10/implementing-mmap-for-transferring-data-from-user-space-to-kernel-space/
+
+Bibliography:
+
+* https://stackoverflow.com/questions/10760479/mmap-kernel-buffer-to-user-space/10770582#10770582
+* https://stackoverflow.com/questions/1623008/allocating-memory-for-user-space-from-kernel-thread
+* https://stackoverflow.com/questions/6967933/mmap-mapping-in-user-space-a-kernel-buffer-allocated-with-kmalloc
+* https://github.com/jeremytrimble/ezdma
+* https://github.com/simonjhall/dma
+* https://github.com/ikwzm/udmabuf
+
 ==== Character devices
 
 In guest:
diff --git a/kernel_module/README.adoc b/kernel_module/README.adoc
index faa1c91..551ceb3 100644
--- a/kernel_module/README.adoc
+++ b/kernel_module/README.adoc
@@ -18,8 +18,6 @@
 .. Module dependencies
 ... link:dep.c[]
 ... link:dep2.c[]
-. Pseudo filesystems
-.. link:mmap.c[]
 . Asynchronous
 .. link:irq.c[]
 .. link:schedule.c[]
diff --git a/kernel_module/mmap.c b/kernel_module/mmap.c
index 140f924..85cf1c7 100644
--- a/kernel_module/mmap.c
+++ b/kernel_module/mmap.c
@@ -1,18 +1,4 @@
-/*
-Remember: mmap, like most fops, does not work with debugfs as of 4.9! https://patchwork.kernel.org/patch/9252557/
-
-Adapted from:
-https://coherentmusings.wordpress.com/2014/06/10/implementing-mmap-for-transferring-data-from-user-space-to-kernel-space/
-
-Related:
-
-- https://stackoverflow.com/questions/10760479/mmap-kernel-buffer-to-user-space/10770582#10770582
-- https://stackoverflow.com/questions/1623008/allocating-memory-for-user-space-from-kernel-thread
-- https://stackoverflow.com/questions/6967933/mmap-mapping-in-user-space-a-kernel-buffer-allocated-with-kmalloc
-- https://github.com/jeremytrimble/ezdma
-- https://github.com/simonjhall/dma
-- https://github.com/ikwzm/udmabuf
-*/
+/* https://github.com/cirosantilli/linux-kernel-module-cheat#kthreads */
 
 #include <linux/fs.h>
 #include <linux/init.h>
diff --git a/rootfs_overlay/mmap.sh b/rootfs_overlay/mmap.sh
index ead7c69..d993f10 100755
--- a/rootfs_overlay/mmap.sh
+++ b/rootfs_overlay/mmap.sh
@@ -1,5 +1,5 @@
 #!/bin/sh
-set -ex
+set -e
 insmod /mmap.ko
-/mmap.out /proc/lkmc_mmap
+/mmap.out /proc/lkmc_mmap 2>&1 1>/dev/null
 rmmod /mmap.ko
diff --git a/rootfs_overlay/test_all.sh b/rootfs_overlay/test_all.sh
index 83fdaf5..4ad9168 100755
--- a/rootfs_overlay/test_all.sh
+++ b/rootfs_overlay/test_all.sh
@@ -6,6 +6,7 @@ for test in \
   /debugfs.sh \
   /fops.sh \
   /ioctl.sh \
+  /mmap.sh \
   /procfs.sh \
   /seq_file.sh \
   /seq_file_single_open.sh \