Can we sort out the prototypes within the cifs headers?

Can we sort out the prototypes within the cifs headers?

[David Howells]

Hi Paulo, Enzo, et al.,

You may have seen my patch:

	https://lore.kernel.org/linux-cifs/20251124124251.3565566-4-dhowells@redhat.com/T/#u

to sort out the cifs header file prototypes, which are a bit of a mess: some
seem to have been placed haphazardly in the headers, some have unnamed
arguments and also sometimes the names in the .h and the .c don't match.

Now Steve specifically namechecked you two as this will affect the backporting
of patches.  Whilst this only affects the prototypes in the headers and not
the implementations in C files, it does cause chunks of the headers to move
around.

Can we agree on at least a subset of the cleanups to be made?  In order of
increasing conflictiveness, I have:

 (1) Remove 'extern'.  cifs has a mix of externed and non-externed, but the
     documented approach is to get rid of externs on prototypes.

 (2) (Re)name the arguments in the prototypes to be the same as in the
     implementations.

 (3) Adjust the layout of each prototype to match the implementation, just
     with a semicolon on the end.  My script partially does this, but moves
     the return type onto the same line as the function name.

 (4) Move SMB1-specific functions out to smb1proto.h.  Move SMB2/3-specific
     functions out to smb2proto.h.

 (5) Divide the lists of prototypes (particularly the massive one in
     cifsproto.h) up into blocks according to which .c file contains the
     implementation and preface each block with a comment that indicates the
     name of the relevant .c file.

     The comment could then be used as a key for the script to maintain the
     division in future.

 (6) Sort each block by position in the .c file to make it easier to maintain
     them.

A hybrid approach is also possible, where we run the script to do the basic
sorting and then manually correct the output.

David

Re: Can we sort out the prototypes within the cifs headers?

[Steve French]

> (4) Move SMB1-specific functions out to smb1proto.h.  Move SMB2/3-specific
     functions out to smb2proto.h.

I am generally in favor of those type of cleanup patches (as
potentially higher priority) as we want to be able to turn off/remove
SMB1 code easily and not confuse old, less secure SMB1, with modern
dialects

On Mon, Dec 1, 2025 at 7:26 AM David Howells <dhowells@redhat.com> wrote:
>
> Hi Paulo, Enzo, et al.,
>
> You may have seen my patch:
>
>         https://lore.kernel.org/linux-cifs/20251124124251.3565566-4-dhowells@redhat.com/T/#u
>
> to sort out the cifs header file prototypes, which are a bit of a mess: some
> seem to have been placed haphazardly in the headers, some have unnamed
> arguments and also sometimes the names in the .h and the .c don't match.
>
> Now Steve specifically namechecked you two as this will affect the backporting
> of patches.  Whilst this only affects the prototypes in the headers and not
> the implementations in C files, it does cause chunks of the headers to move
> around.
>
> Can we agree on at least a subset of the cleanups to be made?  In order of
> increasing conflictiveness, I have:
>
>  (1) Remove 'extern'.  cifs has a mix of externed and non-externed, but the
>      documented approach is to get rid of externs on prototypes.
>
>  (2) (Re)name the arguments in the prototypes to be the same as in the
>      implementations.
>
>  (3) Adjust the layout of each prototype to match the implementation, just
>      with a semicolon on the end.  My script partially does this, but moves
>      the return type onto the same line as the function name.
>
>  (4) Move SMB1-specific functions out to smb1proto.h.  Move SMB2/3-specific
>      functions out to smb2proto.h.
>
>  (5) Divide the lists of prototypes (particularly the massive one in
>      cifsproto.h) up into blocks according to which .c file contains the
>      implementation and preface each block with a comment that indicates the
>      name of the relevant .c file.
>
>      The comment could then be used as a key for the script to maintain the
>      division in future.
>
>  (6) Sort each block by position in the .c file to make it easier to maintain
>      them.
>
> A hybrid approach is also possible, where we run the script to do the basic
> sorting and then manually correct the output.
>
> David
>
>


-- 
Thanks,

Steve

Re: Can we sort out the prototypes within the cifs headers?

[Enzo Matsumiya]

Hi David,

On 12/01, David Howells wrote:
>Hi Paulo, Enzo, et al.,
>
>You may have seen my patch:
>
>	https://lore.kernel.org/linux-cifs/20251124124251.3565566-4-dhowells@redhat.com/T/#u
>
>to sort out the cifs header file prototypes, which are a bit of a mess: some
>seem to have been placed haphazardly in the headers, some have unnamed
>arguments and also sometimes the names in the .h and the .c don't match.
>
>Now Steve specifically namechecked you two as this will affect the backporting
>of patches.  Whilst this only affects the prototypes in the headers and not
>the implementations in C files, it does cause chunks of the headers to move
>around.
>
>Can we agree on at least a subset of the cleanups to be made?  In order of
>increasing conflictiveness, I have:
>
> (1) Remove 'extern'.  cifs has a mix of externed and non-externed, but the
>     documented approach is to get rid of externs on prototypes.
>
> (2) (Re)name the arguments in the prototypes to be the same as in the
>     implementations.
>
> (3) Adjust the layout of each prototype to match the implementation, just
>     with a semicolon on the end.  My script partially does this, but moves
>     the return type onto the same line as the function name.
>
> (4) Move SMB1-specific functions out to smb1proto.h.  Move SMB2/3-specific
>     functions out to smb2proto.h.
>
> (5) Divide the lists of prototypes (particularly the massive one in
>     cifsproto.h) up into blocks according to which .c file contains the
>     implementation and preface each block with a comment that indicates the
>     name of the relevant .c file.
>
>     The comment could then be used as a key for the script to maintain the
>     division in future.
>
> (6) Sort each block by position in the .c file to make it easier to maintain
>     them.
>
>A hybrid approach is also possible, where we run the script to do the basic
>sorting and then manually correct the output.

+1 for the cleanups, thanks for doing that.

On backports, I think points 1-3 could be done together, but in separate
commits (per header file) to minimise conflicts.

4 looks good to have.

5-6 would be most problematic (moving code around).

Not sure what else to say here, but more atomic commit are easier to
backport than big/monolithic ones.


Cheers,

Enzo

Re: Can we sort out the prototypes within the cifs headers?

[Steve French]

I don't have much objection about #1 and $2, 3 possibly if not huge,
but higher priority is 4.  Agree that 5 and 6 are lowest priority
unless part of patch that is fixing (or perf improvement etc.)
something

On Mon, Dec 1, 2025 at 11:32 AM Enzo Matsumiya <ematsumiya@suse.de> wrote:
>
> Hi David,
>
> On 12/01, David Howells wrote:
> >Hi Paulo, Enzo, et al.,
> >
> >You may have seen my patch:
> >
> >       https://lore.kernel.org/linux-cifs/20251124124251.3565566-4-dhowells@redhat.com/T/#u
> >
> >to sort out the cifs header file prototypes, which are a bit of a mess: some
> >seem to have been placed haphazardly in the headers, some have unnamed
> >arguments and also sometimes the names in the .h and the .c don't match.
> >
> >Now Steve specifically namechecked you two as this will affect the backporting
> >of patches.  Whilst this only affects the prototypes in the headers and not
> >the implementations in C files, it does cause chunks of the headers to move
> >around.
> >
> >Can we agree on at least a subset of the cleanups to be made?  In order of
> >increasing conflictiveness, I have:
> >
> > (1) Remove 'extern'.  cifs has a mix of externed and non-externed, but the
> >     documented approach is to get rid of externs on prototypes.
> >
> > (2) (Re)name the arguments in the prototypes to be the same as in the
> >     implementations.
> >
> > (3) Adjust the layout of each prototype to match the implementation, just
> >     with a semicolon on the end.  My script partially does this, but moves
> >     the return type onto the same line as the function name.
> >
> > (4) Move SMB1-specific functions out to smb1proto.h.  Move SMB2/3-specific
> >     functions out to smb2proto.h.
> >
> > (5) Divide the lists of prototypes (particularly the massive one in
> >     cifsproto.h) up into blocks according to which .c file contains the
> >     implementation and preface each block with a comment that indicates the
> >     name of the relevant .c file.
> >
> >     The comment could then be used as a key for the script to maintain the
> >     division in future.
> >
> > (6) Sort each block by position in the .c file to make it easier to maintain
> >     them.
> >
> >A hybrid approach is also possible, where we run the script to do the basic
> >sorting and then manually correct the output.
>
> +1 for the cleanups, thanks for doing that.
>
> On backports, I think points 1-3 could be done together, but in separate
> commits (per header file) to minimise conflicts.
>
> 4 looks good to have.
>
> 5-6 would be most problematic (moving code around).
>
> Not sure what else to say here, but more atomic commit are easier to
> backport than big/monolithic ones.
>
>
> Cheers,
>
> Enzo
>


-- 
Thanks,

Steve

Re: Can we sort out the prototypes within the cifs headers?

[David Howells]

Enzo Matsumiya <ematsumiya@suse.de> wrote:

> +1 for the cleanups, thanks for doing that.
> 
> On backports, I think points 1-3 could be done together, but in separate
> commits (per header file) to minimise conflicts.
> 
> 4 looks good to have.

Hi Enzo,

Could you have a look at:

https://lore.kernel.org/linux-cifs/20251222223006.1075635-1-dhowells@redhat.com/T/#t

see if you're okay with it?

Thanks,
David