[PATCH] staging: pi433: add docs to packet_format and tx_start_condition enum

[PATCH] staging: pi433: add docs to packet_format and tx_start_condition enum

[Paulo Miguel Almeida]

While pi433 driver deals with the nuances of the different possible
config combinations, it's hard (at first) to understand the rationale
for some of the tx/rx-related source code unless you're fairly familiar
with the rf69's inner workings.

This patch documents the expected behaviour and limits of both
packet_format and tx_start_condition enum fields.

Signed-off-by: Paulo Miguel Almeida <paulo.miguel.almeida.rodenas@gmail.com>
---
 drivers/staging/pi433/rf69_enum.h | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)

diff --git a/drivers/staging/pi433/rf69_enum.h b/drivers/staging/pi433/rf69_enum.h
index fbf56fcf5fe8..c902916a063d 100644
--- a/drivers/staging/pi433/rf69_enum.h
+++ b/drivers/staging/pi433/rf69_enum.h
@@ -109,13 +109,32 @@ enum fifo_fill_condition {
 	always
 };
 
+/*
+ * Defines the packet format used.
+ *
+ * In both modes the length of the payload is limited to 255 bytes if AES
+ * is not enabled or 64 bytes otherwise.
+ */
 enum packet_format {
+    /*
+     * Used when the size of payload is fixed in advance. This mode of
+     * operation may be of interest to minimize RF overhead by 1 byte as
+     * no length byte field is required
+     */
 	packet_length_fix,
+    /*
+     * Used when the size of payload isn't known in advance. It requires the
+     * transmitter to send the length byte in each packet so the receiver
+     * would know how to operate properly
+     */
 	packet_length_var
 };
 
+/* Defines the condition to start packet transmission */
 enum tx_start_condition {
+    /* the number of bytes in the FIFO exceeds FIFO_THRESHOLD */
 	fifo_level,
+    /* at least one byte in the FIFO */
 	fifo_not_empty
 };
 
-- 
2.25.4

Re: [PATCH] staging: pi433: add docs to packet_format and tx_start_condition enum

[Greg KH]

On Wed, Dec 29, 2021 at 10:47:13PM +1300, Paulo Miguel Almeida wrote:
> While pi433 driver deals with the nuances of the different possible
> config combinations, it's hard (at first) to understand the rationale
> for some of the tx/rx-related source code unless you're fairly familiar
> with the rf69's inner workings.
> 
> This patch documents the expected behaviour and limits of both
> packet_format and tx_start_condition enum fields.
> 
> Signed-off-by: Paulo Miguel Almeida <paulo.miguel.almeida.rodenas@gmail.com>
> ---
>  drivers/staging/pi433/rf69_enum.h | 19 +++++++++++++++++++
>  1 file changed, 19 insertions(+)
> 
> diff --git a/drivers/staging/pi433/rf69_enum.h b/drivers/staging/pi433/rf69_enum.h
> index fbf56fcf5fe8..c902916a063d 100644
> --- a/drivers/staging/pi433/rf69_enum.h
> +++ b/drivers/staging/pi433/rf69_enum.h
> @@ -109,13 +109,32 @@ enum fifo_fill_condition {
>  	always
>  };
>  
> +/*
> + * Defines the packet format used.

What "Defines"?  This is an odd sentence.

> + *
> + * In both modes the length of the payload is limited to 255 bytes if AES
> + * is not enabled or 64 bytes otherwise.

What does this have to do with the format type?

> + */
>  enum packet_format {
> +    /*
> +     * Used when the size of payload is fixed in advance. This mode of
> +     * operation may be of interest to minimize RF overhead by 1 byte as
> +     * no length byte field is required
> +     */
>  	packet_length_fix,
> +    /*
> +     * Used when the size of payload isn't known in advance. It requires the
> +     * transmitter to send the length byte in each packet so the receiver
> +     * would know how to operate properly
> +     */
>  	packet_length_var
>  };
>  
> +/* Defines the condition to start packet transmission */
>  enum tx_start_condition {
> +    /* the number of bytes in the FIFO exceeds FIFO_THRESHOLD */
>  	fifo_level,
> +    /* at least one byte in the FIFO */
>  	fifo_not_empty
>  };

Also, always run your patches through scripts/checkpatch.pl before
sending them out.  I couldn't take this patch for that reason alone :(

thanks,

greg k-h

Re: [PATCH] staging: pi433: add docs to packet_format and tx_start_condition enum

[Paulo Miguel Almeida]

On Thu, Dec 30, 2021 at 11:57:48AM +0100, Greg KH wrote:
> > +/*
> > + * Defines the packet format used.
> 
> What "Defines"?  This is an odd sentence.

Noted. I will change that.

> > + * In both modes the length of the payload is limited to 255 bytes if AES
> > + * is not enabled or 64 bytes otherwise.
> 
> What does this have to do with the format type?
> 

The rationale was that I wanted the developer to know straight away how
much info would be possible to transfer given the combination of
encryption + packet_format settings. 

But now that you mentioned it, I can see that this info/obs could be 
misplaced. I will remove it.

> > +    /* at least one byte in the FIFO */
> >  	fifo_not_empty
> >  };
> 
> Also, always run your patches through scripts/checkpatch.pl before
> sending them out.  I couldn't take this patch for that reason alone :(
>

My apologies, I will be extra careful next time.

thanks,

Paulo A.