explain what the current and new numbering practice are.
This commit is contained in:
christos
parent
146cab6498
commit
576e2cd67b
|
|
@ -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[] = {
|
||||
{ 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
|
||||
|
|
|
|||
Loading…
Reference in New Issue