Re: [PATCH v3 2/3] Add an optional "alias" attribute to syscall entries.

[Pedro Alves <palves@redhat.com>]

On 11/27/2018 09:53 PM, John Baldwin wrote:
> +On some operating systems, a system call name may map to more than one
> +system call number.  For example, the FreeBSD kernel allocates new
> +system call numbers when changing the ABI of an existing system call.
> +The kernel also includes a compatibility system call using the old ABI
> +and number.  FreeBSD's system call XML file includes aliases for
> +compatibility system calls that are used to catch all versions of a
> +system call.  For example, FreeBSD 12 introduced a new variant of the
> +@code{kevent} system call.  Both system calls are caught when catching
> +the @code{kevent} system call:
> +
> +@smallexample
> +(@value{GDBP}) catch syscall kevent
> +Catchpoint 1 (syscalls 'freebsd11_kevent' [363] 'kevent' [560])
> +(@value{GDBP})
> +@end smallexample
> +

I'd suggest replacing "FreeBSD's system call XML file includes" with
something else that isn't so implementor-speak.  Users needn't
be aware of the XML file.  Maybe something along the lines of
"GDB is aware of aliases for compatibility system calls that
are used to catch ..."  Or maybe remove the sentence altogether.
Maybe simplify it a bit further, as users don't really need
to be told that that's what FreeBSD does for all new syscalls,
just that some syscalls are like that.  I think.  Thus, something
like this is enough, IMHO:


On some operating systems, a system call name may map to more than one
system call number.  

For example, FreeBSD 12 introduced a new variant of the @code{kevent} system
call, and included a compatibility system call using the old ABI and number.
As convenience, both system calls are caught when catching the @code{kevent}
system call by name:

@smallexample
(@value{GDBP}) catch syscall kevent
Catchpoint 1 (syscalls 'freebsd11_kevent' [363] 'kevent' [560])
(@value{GDBP})
@end smallexample

Thanks,
Pedro Alves