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

  On 11/27/18 9:13 AM, Pedro Alves wrote:
> On 11/09/2018 08:18 PM, Eli Zaretskii wrote:
>>> From: John Baldwin <jhb@FreeBSD.org>
>>> Date: Fri,  9 Nov 2018 12:04:31 -0800
>>>
>>> diff --git a/gdb/NEWS b/gdb/NEWS
>>> index ff9b192a38..ff225f361e 100644
>>> --- a/gdb/NEWS
>>> +++ b/gdb/NEWS
>>> @@ -38,6 +38,11 @@
>>>    requires the use of a keyword.  Selecting a frame by level is
>>>    unchanged.  The MI comment "-stack-select-frame" is unchanged.
>>>  
>>> +* System call catchpoints now support system call aliases.  This is
>>> +  used with the FreeBSD system call list so that system call
>>> +  catchpoints will also trigger for legacy system call numbers used by
>>> +  older FreeBSD binaries.
>>
>> IMO, this is very abstract and too vague to be useful.  Since we won't
>> have anything more detailed in the manual, would it be possible to
>> make this description more concrete?  E.g., how about using some of
>> the text and examples you used in your description of the issue:
> 
> Should we, have something in the manual?

Hmm, here's a patch I came up with for the manual:
  

> Cc: gdb-patches@sourceware.org
> From: John Baldwin <jhb@FreeBSD.org>
> Date: Tue, 27 Nov 2018 13:53:54 -0800
> 
> diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
> index 944a2c4383..ab4fad3c36 100644
> --- a/gdb/doc/gdb.texinfo
> +++ b/gdb/doc/gdb.texinfo
> @@ -4683,6 +4683,22 @@ Catchpoint 2 (syscall 764)
>  (@value{GDBP})
>  @end smallexample
>  
> +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

This text is okay, but is it likely that any other OS will use this
facility?  If not, we are better off describing it in the "Native"
section (adding a new subsection if needed), as a FreeBSD-only
feature.

Thanks.
  

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
  

On 11/28/18 4:19 AM, Pedro Alves wrote:
> 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

Yes, I think this is better as well.  Eli, I don't know if other OS's will
make use of this feature.  Given Pedro's new text above, do you think it
should still be moved into a native section or should it stay in the the
syscall section?
  

> Cc: gdb-patches@sourceware.org
> From: John Baldwin <jhb@FreeBSD.org>
> Date: Wed, 28 Nov 2018 09:22:22 -0800
> 
> Yes, I think this is better as well.  Eli, I don't know if other OS's will
> make use of this feature.  Given Pedro's new text above, do you think it
> should still be moved into a native section or should it stay in the the
> syscall section?

I question the need to make this text more general than this feature
will ever become.  But if Pedro thinks we will have similar aliases on
other OSes, then sure, do it as Pedro suggests.