kernel_module: move character device example doc to README

Author: cirosantilli

README.adoc

@@ -2875,6 +2875,83 @@ Those commits change `BR2_LINUX_KERNEL_LATEST_VERSION` in `/linux/Config.in`.
 
 You should then look up if there is a branch that supports that kernel. Staying on branches is a good idea as they will get backports, in particular ones that fix the build as newer host versions come out.
 
+=== Pseudo filesystems
+
+==== Character device
+
+....
+/character_device.sh
+echo $?
+....
+
+Outcome: the test passes:
+
+....
+0
+....
+
+Sources:
+
+* link:rootfs_overlay/character_device.sh[]
+* link:rootfs_overlay/mknoddev.sh[]
+* link:kernel_module/character_device.c[]
+
+Charcter device files are created with:
+
+....
+mknod </dev/path_to_dev> c <major> <minor>
+....
+
+Intuitively, for physical devices like keyboards, the major number maps to which driver, and the minor number maps to which device it is.
+
+A single driver can drive multiple compatible devices.
+
+The major and minor numbers can be observed with:
+
+....
+ls -l /dev/urandom
+....
+
+Output:
+
+....
+crw-rw-rw-    1 root     root        1,   9 Jun 29 05:45 /dev/urandom
+....
+
+which means:
+
+* `c` (first letter): this is a character device. Would be `b` for a block device.
+* `1,   9`: the major number is `1`, and the minor `9`
+
+To avoid device number conflicts when registring the driver we:
+
+* ask the kernel to allocate a free major number for us with: `register_chrdev(0`
+* find ouf which number was assigned by grepping `/proc/devices` for the kernel module name
+
+Bibliography: https://unix.stackexchange.com/questions/37829/understanding-character-device-or-character-special-files/371758#371758
+
+===== Automatically create character device file on insmod
+
+And also destroy it on `rmmod`:
+
+....
+/character_device_create.sh
+echo $?
+....
+
+Outcome: the test passes:
+
+....
+0
+....
+
+Sources:
+
+* link:kernel_module/character_device_create.c[]
+* link:rootfs_overlay/character_device_create.sh[]
+
+Bibliography: https://stackoverflow.com/questions/5970595/how-to-create-a-device-node-from-the-init-module-code-of-a-linux-kernel-module/45531867#45531867
+
 === Kernel panic and oops
 
 To test out kernel panics and oops in controlled circumstances, try out the modules:

kernel_module/README.adoc

@@ -20,8 +20,6 @@
 ... link:dep2.c[]
 . Pseudo filesystems
 .. link:anonymous_inode.c[]
-.. link:character_device.c[]
-.. link:character_device_create.c[]
 .. link:debugfs.c[]
 .. link:fops.c[]
 .. link:ioctl.c[]

kernel_module/character_device.c

@@ -1,24 +1,3 @@
-/*
-Allows us to create device files with given file operations with mknod c X.
-
-Usage:
-
-	/character_device.sh
-
-The major number determines which module owns the device file.
-
-minor is to differentiate between multiple instances of the device,
-e.g. two NVIDIA GPUs using the same kernel module.
-
-We ask the kernel to automatically allocate a major number for us to avoid
-conlicts with other devices.
-
-Then we need to check /proc/devices to find out the assigned number,
-and use that for the mknod.
-
-- https://unix.stackexchange.com/questions/37829/understanding-character-device-or-character-special-files/371758#371758
-*/
-
 #include <linux/fs.h> /* register_chrdev, unregister_chrdev */
 #include <linux/module.h>
 #include <linux/seq_file.h> /* seq_read, seq_lseek, single_release */

kernel_module/character_device_create.c

@@ -1,9 +1,3 @@
-/*
-Automatically create the device under /dev on insmod, and remove on rmmod.
-
-https://stackoverflow.com/questions/5970595/how-to-create-a-device-node-from-the-init-module-code-of-a-linux-kernel-module/45531867#45531867
-*/
-
 #include <linux/cdev.h>
 #include <linux/device.h>
 #include <linux/fs.h> /* register_chrdev, unregister_chrdev */

rootfs_overlay/character_device.sh

@@ -1,5 +1,5 @@
 #!/bin/sh
-set -ex
+set -e
 insmod /character_device.ko
 /mknoddev.sh lkmc_character_device
 [ "$(cat /dev/lkmc_character_device)" = 'abcd' ]

rootfs_overlay/character_device_create.sh

@@ -1,7 +1,7 @@
 #!/bin/sh
-set -ex
+set -e
 insmod /character_device_create.ko
 dev='/dev/lkmc_character_device_create_dev'
-[ "$(cat "$dev")" = 'abcd' ]
+[ "$(cat "$dev")" = abcd ]
 rmmod character_device_create
 [ ! -e "$dev" ]