Module Name: src
Committed By: christos
Date: Mon May 20 17:12:41 UTC 2024
Modified Files:
src/share/man/man9: versioningsyscalls.9
Log Message:
explain what the current and new numbering practice are.
To generate a diff of this commit:
cvs rdiff -u -r1.5 -r1.6 src/share/man/man9/versioningsyscalls.9
Please note that diffs are not public domain; they are subject to the
copyright notices on the relevant files.
Modified files:
Index: src/share/man/man9/versioningsyscalls.9
diff -u src/share/man/man9/versioningsyscalls.9:1.5 src/share/man/man9/versioningsyscalls.9:1.6
--- src/share/man/man9/versioningsyscalls.9:1.5 Fri Jul 14 05:03:37 2023
+++ src/share/man/man9/versioningsyscalls.9 Mon May 20 13:12:41 2024
@@ -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 bec
.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
.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[] = {
- { SYS_compat_XYZ_my_syscall, 0,
- (sy_call_t *)compat_XYZ_sys_my_syscall },
+static const struct syscall_package my_file_CNUM_syscalls[] = {
+ { SYS_compat_CNUM_my_syscall, 0,
+ (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)
-{ return syscall_establish(NULL, my_file_XYZ_syscalls); }
+my_file_CNUM_init(void)
+{ return syscall_establish(NULL, my_file_CNUM_syscalls); }
int
-my_file_XYZ_fini(void)
-{ return syscall_disestablish(NULL, my_file_XYZ_syscalls); }
+my_file_CNUM_fini(void)
+{ 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
