Skip to contentSkip to conversation

staging: pi433: add docs to packet_format and tx_start_condition enum

PATCH Superseded Paulo Miguel Almeida 2 participants 3 messages Dec 29, 2021 – Dec 30, 2021 Staging

v1 of 3 Superseded Latest is v3 →

lore
Share & tools
lore
#0 lore raw

PATCH 1/1 staging: pi433: add docs to packet_format and tx_start_condition enum

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.

---
 drivers/staging/pi433/rf69_enum.h | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)
drivers/staging/pi433/rf69_enum.h +19 -0
index fbf56fcf5fe8..c902916a063d 100644
@@ -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
 };
 
Signature · 1 line
2.25.4
maintainer
#1 lore raw
Quoted 18 lines · 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.

---
 drivers/staging/pi433/rf69_enum.h | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)
drivers/staging/pi433/rf69_enum.h +0 -0
index fbf56fcf5fe8..c902916a063d 100644

drivers/staging/pi433/rf69_enum.h enum fifo_fill_condition { · line 113

Quoted 5 lines
drivers/staging/pi433/rf69_enum.h +2 -0
@@ -109,13 +109,32 @@ enum fifo_fill_condition {
 	always
 };
 
+/*
+ * Defines the packet format used.

What "Defines"? This is an odd sentence.

drivers/staging/pi433/rf69_enum.h enum fifo_fill_condition { · line 116

Quoted 3 lines
drivers/staging/pi433/rf69_enum.h +3 -0
+ *
+ * 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?

Quoted 13 lines
drivers/staging/pi433/rf69_enum.h +11 -0
+ */
 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
+     */

drivers/staging/pi433/rf69_enum.h enum fifo_fill_condition { · line 139

Quoted 10 lines
drivers/staging/pi433/rf69_enum.h +3 -0
 	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

#2 lore raw
Quoted 4 lines · Greg KH
Quoted 2 lines

+/*
+ * Defines the packet format used.

What "Defines"? This is an odd sentence.

Noted. I will change that.

Quoted 5 lines
Quoted 2 lines

+ * 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.

Quoted 7 lines

drivers/staging/pi433/rf69_enum.h enum fifo_fill_condition { · line 139

Quoted 3 lines
drivers/staging/pi433/rf69_enum.h +1 -0
+    /* 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.