explain what the current and new numbering practice are.

share/man/man9/versioningsyscalls.9

@@ -1,4 +1,4 @@
-.\"	$NetBSD: versioningsyscalls.9,v 1.5 2023/07/14 09:03:37 rillig Exp $
+.\"	$NetBSD: versioningsyscalls.9,v 1.6 2024/05/20 17:12:41 christos Exp $
 .\"
 .\" Copyright (c) 2023 The NetBSD Foundation, Inc.
 .\" All rights reserved.
@@ -27,7 +27,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 .\" POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd June 23, 2023
+.Dd May 20, 2024
 .Dt VERSIONINGSYSCALLS 9
 .Os
 .
@@ -89,7 +89,7 @@ The version of the syscall that will become standard in the next release.
 .El
 .Pp
 Additionally,
-.Ar XYZ
+.Ar CNUM
 always represents the last
 .Nx
 release where the current
@@ -115,6 +115,42 @@ will be versioned.
 If not versioning a struct, passages that mention
 .Ft my_struct
 can be ignored.
+.Pp
+The syscall version suffix
+.Dv VNUM
+indicates the first release of
+.Nx
+the system call will appear in.
+The compat version 
+.Dv CNUM
+is the last version of
+.Nx the old system call was used.
+Typically VNUM = CNUM + 1 .
+.Pp
+For example if you are versioning
+.Xr getcontext 2
+just after
+.Nx 11 
+was released, and the original system call was called
+.Fn getcontext ,
+the system call will become
+.Fn __getcontext12
+and the compat entry point will become
+.Fn compat_11_getcontext .
+.Pp
+Next time
+.Xr getcontext 2
+needs versioning, for example just after
+.Nx 15
+was released, it will become
+.Fn __getcontext16
+and the compat entry will become
+.Fn compat_15___getcontext12 .
+.Pp
+Please note that the historical practice up to
+.Nx 11
+has been that the syscall suffix matched the version when the syscall
+was last used.
 .
 .Ss Versioning structs
 To version
@@ -122,7 +158,7 @@ To version
 first make a copy of
 .Ft my_struct
 renamed to
-.Ft my_structXYZ
+.Ft my_structCNUM
 in an equivalent header in
 .Pa sys/compat/sys .
 After that, you can freely modify
@@ -131,14 +167,14 @@ as desired.
 .
 .Ss Versioning the entry point
 The stub for the next version of the syscall will be
-.Fn __my_syscallXYZ ,
+.Fn __my_syscallVNUM ,
 and will have entry point
-.Fn sys___my_syscallXYZ .
+.Fn sys___my_syscallVNUM .
 .
 .Ss Modifying syscalls.conf
 .Pa sys/kern/syscalls.conf
 may need to be modified to contain
-.Li compat_XYZ
+.Li compat_CNUM
 in the
 .Va compatopts
 variable.
@@ -149,20 +185,20 @@ First, add the next syscall to
 keeping
 .Fn my_syscall
 as the name, and set the (optional) compat field of the declaration to
-.Ar XYZ .
+.Ar CNUM .
 .Pp
 Next, modify the current version of the syscall, and replace the type
 field
 .Pq usually just Li STD
 with
-.Dv COMPAT_XYZ MODULAR compat_XYZ .
+.Dv COMPAT_CNUM MODULAR compat_CNUM .
 .Pp
 The keyword
 .Dv MODULAR
 indicates that the system call can be part of a kernel module.
 Even if the system call was not part of a module before, now it will be part
 of the
-.Dv COMPAT_XYZ
+.Dv COMPAT_CNUM
 module.
 .Pp
 Finally, if applicable, replace the types of the current and old versions of the
@@ -171,16 +207,16 @@ syscall with the compat type.
 Overall, the final diff should look like
 .Bd -literal
 - 123 STD                           { int|sys||my_syscall(struct my_struct *ms); }
-+ 123 COMPAT_XYZ MODULAR compat_XYZ { int|sys||my_syscall(struct my_structXYZ *ms); }
++ 123 COMPAT_CNUM MODULAR compat_CNUM { int|sys||my_syscall(struct my_structCNUM *ms); }
 \&...
-+ 456 STD               	    { int|sys|XYZ|my_syscall(struct my_struct *ms); }
++ 456 STD               	    { int|sys|VNUM|my_syscall(struct my_struct *ms); }
 .Ed
 .
 .Ss Modifying Makefile.rump
 If the current syscall is rump,
 .Pa sys/rump/Makefile.rump
 must contain
-.Ar XYZ
+.Ar CNUM
 in the
 .Dv RUMP_NBCOMPAT
 variable.
@@ -189,7 +225,7 @@ variable.
 If versioning structs, then modify
 .Pa sys/kern/makesyscalls.sh
 by adding and entry for
-.Ft struct my_structXYZ
+.Ft struct my_structCNUM
 type to
 .Va uncompattypes .
 .Pp
@@ -223,26 +259,26 @@ and lives inside
 .
 .Ss Creating the compat current syscall
 The compat version of the current syscall has entry point
-.Fn compat_XYZ_sys_my_syscall ,
+.Fn compat_CNUM_sys_my_syscall ,
 and should be implemented in
-.Pa sys/compat/common/my_file_XYZ.c
+.Pa sys/compat/common/my_file_CNUM.c
 with the same semantics as the current syscall.
 Often this involves translating the arguments to the next syscall,
 and then calling that syscall's entry point.
 .
 .Ss Adding it to the compat module
-.Pa sys/compat/common/my_file_XYZ.c
+.Pa sys/compat/common/my_file_CNUM.c
 must contain an array of
 .Ft struct syscall_package
 that declares the mapping between syscall number and entry point,
 terminating in a zero element (see sample diff below).
 .Pp
 Additionally,
-.Pa sys/compat/common/my_file_XYZ.c
+.Pa sys/compat/common/my_file_CNUM.c
 must contain two functions,
-.Fn my_file_XYZ_init
+.Fn my_file_CNUM_init
 and
-.Fn my_file_XYZ_fini
+.Fn my_file_CNUM_fini
 that are used to initialize/clean up anything related to this syscall.
 At the minimum they must make calls to
 .Fn syscall_establish
@@ -253,38 +289,38 @@ The stubs for these functions should be located in
 .Pa sys/compat/common/compat_mod.h .
 .Pp
 Overall,
-.Pa sys/compat/common/my_file_XYZ.c
+.Pa sys/compat/common/my_file_CNUM.c
 must at the minimum contain
 .Bd -literal -offset indent
-static const struct syscall_package my_file_XYZ_syscalls[] = {
+static const struct syscall_package my_file_CNUM_syscalls[] = {
-        { SYS_compat_XYZ_my_syscall, 0,
+        { SYS_compat_CNUM_my_syscall, 0,
-            (sy_call_t *)compat_XYZ_sys_my_syscall },
+            (sy_call_t *)compat_CNUM_sys_my_syscall },
         { 0, 0, NULL },
 };
 
 int
-compat_XYZ_my_syscall(...)
+compat_CNUM_my_syscall(...)
 { /* Compat implementation goes here. */ }
 
 int
-my_file_XYZ_init(void)
+my_file_CNUM_init(void)
-{ return syscall_establish(NULL, my_file_XYZ_syscalls); }
+{ return syscall_establish(NULL, my_file_CNUM_syscalls); }
 
 int
-my_file_XYZ_fini(void)
+my_file_CNUM_fini(void)
-{ return syscall_disestablish(NULL, my_file_XYZ_syscalls); }
+{ return syscall_disestablish(NULL, my_file_CNUM_syscalls); }
 .Ed
 .Pp
 Finally,
-.Pa sys/compat/common/compat_XYZ_mod.c
+.Pa sys/compat/common/compat_CNUM_mod.c
 needs to be modified to have its
-.Fn compat_XYZ_init
+.Fn compat_CNUM_init
 and
-.Fn compat_XYZ_fini
+.Fn compat_CNUM_fini
 functions call
-.Fn my_file_XYZ_init
+.Fn my_file_CNUM_init
 and
-.Fn my_file_XYZ_fini
+.Fn my_file_CNUM_fini
 respectively.
 .
 .Ss Modifying old compat syscalls