Re: [PATCH ipsec-next v5 06/17] xfrm: add mode_cbs module functionality

[Christian Hopps <chopps@chopps.org>]

Sabrina Dubroca <sd@queasysnail.net> writes:

> 2024-07-14, 16:22:34 -0400, Christian Hopps wrote:
>> +struct xfrm_mode_cbs {
>
> It would be nice to add kdoc for the whole thing.

Ok, I'll move the inline comments to a kdoc. FWIW, all the other structs in this header, including the main `xfrm_state` struct use the same inline comment documentation style I copied.

>> diff --git a/net/xfrm/xfrm_input.c b/net/xfrm/xfrm_input.c
>> index 7cee9c0a2cdc..6ff05604f973 100644
>> --- a/net/xfrm/xfrm_input.c
>> +++ b/net/xfrm/xfrm_input.c
>> @@ -494,6 +497,10 @@ int xfrm_input(struct sk_buff *skb, int nexthdr, __be32 spi, int encap_type)
>>
>>  		family = x->props.family;
>>
>> +		/* An encap_type of -3 indicates reconstructed inner packet */
>
> And I think it's time to document all the encap_types above the
> function (and in particular, how xfrm_inner_mode_input/encap_type=-3
> pair together), and/or define some constants. Also, is -2 used
> anywhere (I only see -1 and -3)? If not, then why -3?

At the time this was added ISTR that there was some belief that -2 was used perhaps in an upcoming patch, so I picked -3. I can't find a -2 use case though so I will switch to -2 instead.

Re documentation: I think the inline comments where encap_type is used is sufficient documentation for the 2 negative values. There's a lot going on in this function and someone wishing to change (or understand) something is going to have to walk the code and use cases regardless of a bit of extra verbiage on the encap_value beyond what's already there. Fully documenting how xfrm_input works (in all it's use cases) seems beyond the scope of this patch to me.

Thanks,
Chris.