From 174011bc8a115107d9dc2746b289f4c914f16074 Mon Sep 17 00:00:00 2001
From: Aaron LI <aly@aaronly.me>
Date: Tue, 19 Jan 2021 22:41:43 +0800
Subject: [PATCH] syscall.9: Fix outdated info while add some missing info

* Update the syscall decleration (in syscalls.master) and generated
  prototype (in sysproto.h) examples to match the current syntax.
* Fix 'uap->sysmsg_result' to 'sysmsg->sysmsg_result', and be explicit
  that the function need to return 0 when the default 'sysmsg_result' is
  updated.
* Don't mention the 'SCARG' macro (to extract syscall argument) since
  it's now seldomly used in our codebase.  (Syscall argument can be
  intuitively extracted by 'uap->arg'.)
* Add a paragraph to describe the symbol exportation in libc via the
  'libc/sys/Symbol.map' file.
* Mention the syscall entry point in the kernel a bit.
* Add 'sys/sys/sysmsg.h' and 'sys/sys/sysunion.h' to the FILES section,
  while remove the obsolete 'sys/kern/syscalls.conf' (already folded
  into makesyscalls.sh).
* Some minor formatting and wording tweaks.
---
 share/man/man9/syscall.9 | 86 +++++++++++++++++++++++++++-------------
 1 file changed, 59 insertions(+), 27 deletions(-)

diff --git a/share/man/man9/syscall.9 b/share/man/man9/syscall.9
index bf791d29e2b..991b389eae3 100644
--- a/share/man/man9/syscall.9
+++ b/share/man/man9/syscall.9
@@ -23,7 +23,7 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.Dd May 22, 2020
+.Dd January 19, 2021
 .Dt SYSCALL 9
 .Os
 .Sh NAME
@@ -91,36 +91,35 @@ The function in the prototype has to be defined somewhere in
 the kernel sources as it will be used as an entry point for
 the corresponding system call.
 .Pp
-For other types the rest of the line is a comment.
+For other types, the rest of the line is a comment.
 .Pp
 To generate the header and code files from the
 .Dq master
 file,
-.Li make sysent
+.Cm make sysent
 has to be run from the directory containing the
 .Dq master
 file.
 Please mind that the string
-.Li sys_
+.Dq sys_
 is prepended to all system call names, but not to the structures
 holding the arguments.
-So, if one has added the line:
+So, if one has added this line to the system call
+.Dq master
+file:
 .Bd -literal
-503	STD	BSD	{ int mycall(int x, int y); }
+503	STD	{ int mycall(int x, int y); }
 .Ed
 .Pp
-to the system call master file, the generated prototype would be:
+the generated prototype would be:
 .Pp
 .Ft int
-.Fn sys_mycall "struct mycall_args *uap" ;
-.Pp
-It is customary to extract system call arguments with the
-.Fn SCARG uap member
-macro, which is defined in
-.Pa sys/sys/sysent.h
-file.
+.Fo sys_mycall
+.Fa "struct sysmsg *sysmsg"
+.Fa "const struct mycall_args *uap"
+.Fc
 .Pp
-Any value which the
+Any value that the
 .Fn sys_mycall
 kernel function returns ends up in
 .Va errno
@@ -133,20 +132,49 @@ is automatically -1 or 0 depending on whether
 was set or not.
 A function that needs to return a different value to userland, e.g.\& a
 file descriptor, must override the default value in
-.Fa uap->sysmsg_result ,
-as defined in
-.Pa sys/sys/sysmsg.h .
+.Fa sysmsg->sysmsg_result
+(as defined in
+.Pa sys/sys/sysmsg.h )
+and return 0.
+.Pp
+In the
+.Lb libc ,
+the assembly wrapper (as described below) will create these symbols:
+.Sy mycall ,
+.Sy _mycall
+and
+.Sy __sys_mycall .
+To export the syscall for external use, add symbol
+.Sy mycall
+to the appropriate
+.Dv DFxxx.0
+section in the
+.Pa lib/libc/sys/Symbol.map
+file.
+In addition, add symbols
+.Sy _mycall
+and
+.Sy __sys_mycall
+to the
+.Dv DFprivate_1.0
+section in the same file for internal use.
 .Sh IMPLEMENTATION NOTES
-In the kernel, a syscall is implemented by a
+In the kernel, the syscall entry point is implemented in platform-dependent
+assembly code (e.g.,
+.Pa sys/platform/pc64/x86_64/exception.S
+for x86_64 machines),
+and the syscall itself is implemented by a
 .Fn sys_syscallname
 function.
+.Pp
 In userspace, the function that executes a syscall is automatically generated
 using the description in
 .Pa syscalls.master .
 The symbols in the
 .Lb libc
 are assembly wrappers generated in
-.Pa lib/libc/${MACHINE_ARCH} Pq e.g.\& x86_64 ,
+.Pa lib/libc/${MACHINE_ARCH}
+.Pq e.g., x86_64 ,
 again using the description in
 .Pa syscalls.master .
 These wrappers use macros provided by the platform-dependent
@@ -157,22 +185,26 @@ header file which take care of putting the syscall arguments into registers
 instruction (on x86_64).
 .Sh FILES
 .Bl -tag -width sys/kern/syscalls.master -compact
+.It Pa sys/kern/syscalls.master
+the
+.Dq master
+file describing names and numbers for the system calls;
 .It Pa sys/kern/makesyscalls.sh
 a
 .Xr sh 1
-script for generating C files out of the syscall master file;
-.It Pa sys/kern/syscalls.conf
-a configuration file for the shell script above;
-.It Pa sys/kern/syscalls.master
-master files describing names and numbers for the system calls;
+script for generating C files out of the syscall master file above;
 .It Pa sys/kern/syscalls.c
 system call names lists;
 .It Pa sys/kern/init_sysent.c
 system call switch tables;
+.It Pa sys/sys/syscall.h
+system call numbers;
+.It Pa sys/sys/sysmsg.h
+system call message structure;
 .It Pa sys/sys/sysproto.h
 system call argument lists;
-.It Pa sys/sys/syscall.h
-system call numbers.
+.It Pa sys/sys/sysunion.h
+system call argument union.
 .El
 .Sh SEE ALSO
 .Xr ktrace 2 ,
-- 
2.28.0

