Add additional macos installation instruction in README.md (#157)

Signed-off-by: Cheng-En Lee <chengenl@usc.edu>

Merge pull request #156 from linD026/master

Adjust "in the mean time" description of tasklet

Adjust "in the mean time" description of tasklet

Since the init function may be interrupted. Tweak the description of
"in the mean time".

Close #152

Merge pull request #155 from linD026/master

Add more information about the CFI of timer API

Add more information about the CFI of timer API

Currently, in 13.2 Flashing keyboard LEDs, the description of the
control-flow integrity, "Furthermore, the function prototype with
unsigned long argument may be an obstacle to the control-flow integrity
.", will confuse the reader.

It may lead the reader to think about hardware-assisted CFI like Intel
CET uses the shadow stack attack for ROP (backward-edge protection). But
the description of CFI here talks about the function pointer checking
with the prototype (forward-edge protection).

So add more information to make it more clear.

Close #151

Merge pull request #154 from leovincentseles/master

module_init and module_exit are defined in module.h

module_init and module_exit are defined in module.h

Both module_init and module_exit are defined in
include/linux/module.h

CI: Bump dependency versions

Merge pull request #150 from asas1asas200/zeng-feat-attributes

Add description of sysfs attribute

Add description of sysfs attribute

The description of the attribute was added in sysfs section and referenced in vinput section.

In vinput section, just described the class_attribute and some macros about sysfs class.

Add file name at vinput-related examples begin.

Merge pull request #149 from linD026/master

Fix potential concurrent problems in chardev2.c

Fix potential concurrent problems in chardev2.c

After forking, Each file descriptor in the child refers to the same
open file description as the parent. So when calling open() before
fork(), the child can access the device file without checking by
exclusive access in device_open(). It may cause race conditions
in device_ioctl().

Because of that, it is unnecessary to check the multiple access
in device_open(). It just needs check in device_ioctl(), since
read(), write(), seek() system call are atomic [1][2].

Related discussion:
- https://github.com/sysprog21/lkmpg/issues/148

[1] https://lore.kernel.org/lkml/53022DB1.4070805@gmail.com/
[2] https://www.kernel.org/doc/html/latest/filesystems/files.html

Close #148

Merge pull request #147 from linD026/master

Fix wrong regular expression of clang-format

Fix wrong regular expression of clang-format

Merge pull request #146 from linD026/master

Fix typo

Fix typo

Merge pull request #145 from linD026/master

Introduce Virtual Input Device Driver

Introduce Virtual Input Device Driver

Add the new section of input device driver, vinput[1].

Also, update the Acknowledgements.

[1] https://github.com/sysprog21/vinput

Merge pull request #144 from henrybear327/improvement/latexmk

Use latexmk instead of pdflatex for PDF generation

Update README and Makefile for the latexmk existence check

Signed-off-by: Chun-Hung Tseng <henrybear327@gmail.com>

Tweak the style of sudoers file

Update .gitignore files to ignore latexmk tmp files

Signed-off-by: Chun-Hung Tseng <henrybear327@gmail.com>

Fix the pdf generation code in Makefile

The current Makefile is missing one more pdflatex pass.

The correct steps are : pdflatex -> bibtex -> pdflatex -> pdflatex [1]. Otherwise, bib items will not be showing properly.

[1] https://github.com/James-Yu/LaTeX-Workshop/wiki/Compile#latex-recipes

Signed-off-by: Chun-Hung Tseng <henrybear327@gmail.com>

Merge pull request #143 from linD026/master

Improve the description of finding syscall table

Improve the description of finding syscall table

Presently, the representation of showing which version will use the
method to find out the system call table is vague.

Related discussion:
* sysprog21/lkmpg: https://github.com/sysprog21/lkmpg/pull/142

Refine wording on module loading

Close #134

Merge pull request #141 from steven1lung/master

Fix grammar and typo

Fix grammar

Merge pull request #140 from steven1lung/master

Fix typo, grammar and remove duplicated words

Fix typo, grammar and remove duplicated  words

Replaced 'a' with 'an' since a vowel sound is after.

Fix a logic error in examples/ioctl.c (#137)

Change the "alloc_ret" and "cdev_ret" initial values to non-zero.
According to the source code, "alloc_chrdev_region" and "cdev_add"
return zero on success, and negative code on failure.

So, if the "alloc_chrdev_region" failed, the if condition becomes true,
then we will jump to the label "error" by goto, checking each return
value whether is a success state from both functions mentioned above
and dealing with it properly for exiting the process.

However, it checks the success state by comparing the return value
with zero (means success), and we got "cdev_ret == 0" is true from
the initial value zero, while we didn't execute "cdev_add" yet.
Hence, there was a logic error when the initial value is zero.

Co-authored-by: NOVBobLee <defru04002@gamil.com>

Fix incoherent ioctl examples (#139)

Previously ioctl.c is a userspace program for chardev2.c and chardev.h [1].
But now, this file is an independent kernel module, and the original code
disappear.
This patch adds back the original userspace code and renames it to
userspace_ioctl.c.

[1] https://tldp.org/LDP/lkmpg/2.4/html/x856.html

Add book cover (#136)

Both PDF and HTML generation are supported.

Update Makefile and Add explanation (#133)

Add `PWD := $(CURDIR)` in Makefile and the explanation about `sudo make`
when only having `PWD`.

Merge pull request #135 from RinHizakura/master

Revise chardev registration

Introduce the new method for chardev registration

Instead of using the old register_chrdev / unregister_chrdev API,
cdev interface which is newer and would be better for new driver programmers
in most cases. This commit is trying to give the brief overview for
this different interface.

modinfo does not require superuser permission

Merge pull request #130 from lyctw/master

Fix typo

Fix typo

Merge pull request #128 from sudoliyang/patch-2

Fix typo

Merge pull request #127 from sudoliyang/patch-1

Fix typo

Fix typo

Fix typo

Merge pull request #123 from fennecJ/patch

Generate contributor list as a modular inclusion

Adjust the position of Figure 1 (#126)

Add script to gen contributor list and contrib.tex

This script do mainly 2 things:
1.
Generate file `Contributors` with git log in following format:
Contributor's name,<1-st e-mail>[,<2nd e-mail>][,<3rd e-mail>]...
The 2-nd email and so on are based on file `.mailmap` in the root
directory of the repo.
Note that it will also append contributors in File `Include`; and
will NOT append contributors in File `Exclude`.
If there are new contributors, script will sort `Contributor` after
append new contributors into each file; Otherwise it do nothing.

2.
Generate contrib.tex based on `Contributors` into lib/contrib.tex in
following format:
[name], (reasonable width) % [1-st e-mail]
Which is inspired by The Not So Short Introduction to Latex 2e[1]

We need to maintain `.mailmap`, `Exclude` and `Include` manually.
All Chinese name should be converted into English/Pinyin in `.mailmap`,
otherwise we may need extra pkg for latex to parse Chinese characters.

[1] - https://tobi.oetiker.ch/lshort/lshort.pdf

Close #68

CI: Introduce Smatch for static analysis (#125)

Smatch[1][2] is a pluggable static analysis for C. It may help us find
out the potential problem of the example code.

Doing with smatch, if set the --file-output flag, it will generate the
{}.c.smatch report for each c file. This will make a little bit
complicated to collect all the report messages. So, here we stay at the
default setting, stdout for the smatch messages.

For more information, see:
- https://lwn.net/Articles/696624/
- https://elinux.org/images/d/d3/Bargmann.pdf

Also, fix the warning from Smatch:

Smatch failed: 1 warning(s), 1 error(s)
lkmpg/examples/procfs2.c:57 procfile_write() error: buffer overflow 'procfs_buffer' 1024 <= 1024
lkmpg/examples/kbleds.c:58 kbleds_init() warn: argument 5 to %lx specifier is cast from pointer

Furthermore, the effect of the write operation in procfs2.c is too
implied. So after writing, print the buffer every time.

Close #122

[1] https://github.com/error27/smatch
[2] https://repo.or.cz/w/smatch.git

Explain inode at the first occurrence (#115)

The explanation of "inode" should appear at the first occurrence to which readers
can refer.

Remove out-of-date syscall information

Close #121

Fix wording

Add Manrope variable font (#118)

Manrope is an open-source modern sans-serif font family.

Merge pull request #120 from linD026/master

CI: Introduce GCC static analysis

CI: introduce GCC static analysis

Since GCC version 10, there has been a new option -fanalyzer for
static analysis. It can make the CI pipeline more comprehensive.

Also, the static analysis updates in GCC 11, but we cannot install
the GCC 11 in ubuntu 20.04 straightforwardly right now, which is
the GitHub workflow environment (see status-check.yaml).
For this reason, we stay at the GCC 10.

Close #117

Reference
- https://gcc.gnu.org/onlinedocs/gcc-10.1.0/gcc/Static-Analyzer-Options.html
- https://developers.redhat.com/blog/2020/03/26/static-analysis-in-gcc-10
- https://lwn.net/Articles/870290/
- https://developers.redhat.com/blog/2021/01/28/static-analysis-updates-in-gcc-11
- https://github.com/torvalds/linux/commit/7d73c3e9c51400d3e0e755488050804e4d44737a

Merge pull request #119 from marconi1964/master

Improve grammar

Correct English gramma

Simplify the epilog

Always run "dmesg" with sudo

The dmesg command allows you to review the messages that are stored in the
ring buffer. Some Linux distributions have strict requirements for
dmesg, and you need to use sudo to use dmesg.

Remove unintended code block

Dump the message of hello-5 explicitly (#112)

Close #111

Merge pull request #114 from fennecJ/patch

CI: Keep workflow running even if no release tag found

Keep workflow running even if no release tag found

The action we used to delete the old release somehow cannot find the
release tag in forked repo and cause the workflow failed.
To solve this issue, simply setting `fail-if-no-release` option to false
will do the trick.

CI: Enforce status checks once pull requests received (#113)

We tend to reject the pull requests if they fail to pass coding style checks
and static analysis.

See https://www.wesleyhaakman.org/working-with-pull-requests-status-checks-arm-templates-and-github-actions/

Fix potential concurrent access problems with VFS (#108)

Since Linux v3.14, the read, write and seek operations of "struct file" are
guaranteed for thread safety [1][2]. This patch added an explanation.

Here are the potential problems:
chardev.c:
- Move the "msg_ptr" pointer into the read function to remove unnecessary usage.
- List the clear states of "already_open" by using mnemonic enumeration.

chardev2.c:
- The "buffer" in the write function is user space data. It cannot use in the
  kernel space.
- Reduce the redundant type transformation.
- List the states of "already_open". Same as chardev.c.

[1] https://lore.kernel.org/lkml/20140303210359.26624.qmail@science.horizon.com/T/#u
[2] https://github.com/torvalds/linux/commit/9c225f2655e36a470c4f58dbbc99244c5fc7f2d4

Denote LWN hyperlink

Mention the Online Books Page

Merge pull request #109 from YLowy/master

Fix typo

Typo.

Merge pull request #107 from sprowell/master

Fixed parameter name for hello-5.

Fixed parameter name for hello-5.

Parameters are case-sensitive, so myintArray is different from myintarray, and people who are running the example with copy/paste will find it doesn't work as described in the text.

Merge pull request #106 from linD026/master

CI: Integrate the Sparse into the CI pipeline

CI: Integrate the Sparse into the CI pipeline

Sparse[1] is a semantic parser for C language, it can find out the
potential problem of the example code.

[1] https://www.kernel.org/doc/html/latest/dev-tools/sparse.html

CI: Run static analysis with Cppcheck (#105)

Cppcheck[1] is integrated into CI pipeline for running static analysis.

However, Cppcheck is known to report false-positive, and we have to
suppress some warnings in advance.

[1] https://cppcheck.sourceforge.io/

Merge pull request #104 from linD026/master

ioctl: Remove unnecessary initialization

ioctl.c: Remove unnecessary initialization

The "alloc_chrdev_region" function will dynamically choose the
major number and store it at "dev". It is unnecessary to initialize
the "dev" before the "alloc_chrdev_region" function.

Trivial GitHub workflow tweak

Make CI validation more verbose

Mention Free Ebook Foundation

Merge pull request #102 from giladreti/patch-1

Fix typo

fix typo: `compatibiity -> compatibility`

Merge pull request #101 from fennecJ/patch

Enable kbleds in CI pipeline

Remove kbleds from non-working list

Since #98 has fixed the error with kbleds caused by changed timer API,
now it can work again with docker container.

Simplify the wording

Improve top-level documentation

This patch introduced the changes:
- Build instructions
- Strip duplicated commands
- Add more hyperlinks
- Mention nerdctl as Docker CLI replacement

Adapt the timer API Usage (#98)

Since v4.14 [1], the timer API has been changed to improve memory safety.
The series of improvements ended up at v4.15 [2].

Reference: https://lwn.net/Articles/735887/

Close #97

[1] https://github.com/torvalds/linux/commit/686fef928bba6be13cabe639f154af7d72b63120
[2] https://github.com/torvalds/linux/commit/841b86f3289dbe858daeceec36423d4ea286fac2

Workaround inconsistent text scaling (#100)

p + pre remains at em as we want to use the parent element here (however rem
could be used too, just requires a bigger value). I am setting it to 110% size,
otherwise some code blocks have relatively small text. The smaller code blocks
do appear bigger.

Improve readability (#96)

This new foreground + background color maintains the minimum of 7:1 contrast ratio as specified by WCAG (this has 7.36:1) and is the same colors Firefox reading mode uses when choosing the sepia theme.

Fonts are too small by default, using responsive units (em) let's me increase them, I am unsure where or if there is font-size specified for parent anywhere but it seems to have been manually decreased.

Increased max-width slightly to adjust for new size and more standard line-height, so the doc doesn't feel significantly longer, still maintains good eye travel.

suppress warning: no newline at end of file

Improve CI pipeline to automate module testing (#95)

The script executes insmod/rmmod twice with available kernel modules.

Close #72

Avoid unexpected concurrent access (#94)

In file {chardev,chardev2,sleep}.c, the variable to determine
the exclusive access was of integer type, which led to race
condition.

This patch rewrote the above with atomic CAS respectively
to eliminate the race.

Close #93

Fix the warnings raised by Sparse (#92)

Sparse[1] is a semantic parser, capable of finding out the potential
problems of Linux kernel code. This patch fixed the warnings.

[1] https://www.kernel.org/doc/html/latest/dev-tools/sparse.html

Merge pull request #91 from ccs100203/master

Fix Typo

Fix Typo

from "mask" to "masks"
from "quick" to "quickly"
from "a" to "an"

Enforce consistent style for directory "other" (#89)

Enforce Linux kernel coding style (#88)

The only exception is to indent with four spaces rather than tabs
for sticking to compact layout of source listing.

Close #87

Rewrite the descriptions about bottom half

Merge pull request #86 from linD026/master

Fix typo

Fix typo

Add GitHub buttons in rendered HTML (#85)

GitHub buttons are rendered in the generated HTML:
one is GitHub project page; another is PDF download.

Close #84

Fix disallowed cr0 write protection and close_fd (#80)

Since the commit 8dbec27a242cd3e2816eeb98d3237b9f57cf6232 [1]
(kernel version v5.3+ [2]) the sensitive CR0 bits in x86 is pinned,
we need to use the inline asm [3][4] to bypass it.

commit 8dbec27a242cd3e2816eeb98d3237b9f57cf6232 :
> With sensitive CR4 bits pinned now, it's possible that the WP bit for
> CR0 might become a target as well.
>
> Following the same reasoning for the CR4 pinning, pin CR0's WP
> bit. Contrary to the cpu feature dependend CR4 pinning this can be done
> with a constant value.

Also, getting "sys_call_table" [8] from the symbol lookup by using the address
of "close_fd" does not work for v5.11+ [5][6]. The reason is the entry of
"sys_call_table[__NR_close]" is not the address of "close_fd", actually
it is "__x64_sys_close" in x86.

Two solutions were proposed: using "kallsyms_lookup_name" [7] or just specifying
the address into the module. The symbol "kallsyms_lookup_name"  is unexported
since v5.7; the address of "sys_call_table" can be found in
"/boot/System.map" or "/proc/kallsyms".

Since v5.7, the manual symbol lookup is not guaranteed to work
because of control-flow integrity (or control-flow enforcement [9][10]) is added
[11] for x86, but it is disabled since v5.11 [12][13]. To make sure manual symbol
lookup work, it only uses up to v5.4.

Reference:
[1] https://github.com/torvalds/linux/commit/8dbec27a242cd3e2816eeb98d3237b9f57cf6232
[2] https://outflux.net/blog/archives/2019/11/14/security-things-in-linux-v5-3/
[3] https://patchwork.kernel.org/project/linux-kbuild/patch/20200903203053.3411268-3-samitolvanen@google.com/
[4] https://stackoverflow.com/questions/58512430/how-to-write-to-protected-pages-in-the-linux-kernel
[5] https://lore.kernel.org/bpf/20201120231441.29911-21-ebiederm@xmission.com/
[6] https://lore.kernel.org/bpf/87blj83ysq.fsf@x220.int.ebiederm.org/
[7] https://github.com/torvalds/linux/commit/0bd476e6c67190b5eb7b6e105c8db8ff61103281
[8] https://github.com/torvalds/linux/commit/8f27766a883149926e7c1f69d9f1d8f68efcd65f
[9] https://lore.kernel.org/lkml/20200204171425.28073-1-yu-cheng.yu@intel.com/
[10] https://lore.kernel.org/linux-doc/20201110162211.9207-1-yu-cheng.yu@intel.com/T/
[11] https://github.com/torvalds/linux/commit/5790921bc18b1eb5c0c61371e31114fd4c4b0154
[12] https://github.com/torvalds/linux/commit/20bf2b378729c4a0366a53e2018a0b70ace94bcd
[13] https://lore.kernel.org/bpf/20210128123842.c9e33949e62f504b84bfadf5@gmail.com/

print_string: Validate tty before accessing its operations

Close #81