Re: [PATCH v3 07/20] sg: move header to uapi section

[Douglas Gilbert <dgilbert@interlog.com>]

On 2019-08-12 10:24 a.m., Christoph Hellwig wrote:
> [note: question for the linux-spdx audience below]
> 
>> -
>>   #ifdef __KERNEL__
>>   extern int sg_big_buff; /* for sysctl */
>>   #endif
> 
> FYI, these __KERNEL__ ifdefs in non-uapi headers should go away.

Yes, that could be removed, but perhaps not yet, see below.

>> +/*
>> + * In version 3.9.01 of the sg driver, this file was spilt in two, with the
>> + * bulk of the user space interface being placed in the file being included
>> + * in the following line.
>> + */
>> +#include <uapi/scsi/sg.h>
> 
> Splitting uapi headers is standard practive, no need for the comment,
> especially not with a meaningless driver version number.

The "meaningless driver version number" is in the sg (and bsg and
generalized ioctl(SG_IO)) API via ioctl(SG_GET_VERSION_NUM). All
versions of Windows have driver version numbers. So no, one kernel
version number doesn't tell the full story. FreeBSD implements a
subset of the sg driver, and I hope to expand that. The driver version
number will be useful to differentiate the driver API there too.

My libsgutils library which is under the sg3_utils, sdparm and ddpt
packages now acts on that version number when run on Linux. When it
is between 4.0.0 and 4.0.29 then the driver API as per the end of
this patchset is assumed. If the driver version number is 4.0.30
or above the sg interface as defined here:
http://sg.danny.cz/sg/sg_v40.html  is assumed.

Also version numbers are more human friendly and convey an ordering
unlike git with its handles, for example:
   c578603bab2ec27dd6bb2d38ad4c3fc44423c570
which obviously is this patch.


That comment is a heads up to the GNU library folks who need to
be careful when the publicly visible part of an API is moved from
say include/scsi/sg.h to include/uapi/scsi/sg.h . After that move
and without that __KERNEL__ conditional then user code will break in
compilation if the former (non-uapi) header is accidentally included.
Lack of that conditional will also catch out those who include:
    /lib/modules/<kernel_version>/build/include/scsi/sg.h

Doug Gilbert

>> diff --git a/include/uapi/scsi/sg.h b/include/uapi/scsi/sg.h
>> new file mode 100644
>> index 000000000000..072b45bd732f
>> --- /dev/null
>> +++ b/include/uapi/scsi/sg.h
>> @@ -0,0 +1,329 @@
>> +/* SPDX-License-Identifier: GPL-2.0 */
> 
> This needs the syscall noticed for uapi headers.  FYI, what is our
> stance of just adding that notice to headers newly moved to UAPI?
> Do we need agreement from everyone who touched the file?  Or just
> after we started the split and SPDX annotations, as in this case
> this header used to be available to user programs?
>