[PATCH RFC] staging: r8188eu: comment about the chip's packet format

[PATCH RFC] staging: r8188eu: comment about the chip's packet format

[Martin Kaiser]

The structs phy_rx_agc_info and phy_status_rpt define parts of the
header data that the r8188eu chipset sends to this driver via usb.

Add a comment to clarify that we cannot modify the content of these
structures and remove seemingly unused fields.

Signed-off-by: Martin Kaiser <martin@kaiser.cx>
---

Dear all,

I experimented with "cleaning up" these structures and related code before
discovering that their content comes from usb packets we receive from the
r8188eu chipset.

Would it make sense to add a word of warning to prevent others from
repeating this exercise?

Thanks,
Martin

 drivers/staging/r8188eu/include/odm_HWConfig.h | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/drivers/staging/r8188eu/include/odm_HWConfig.h b/drivers/staging/r8188eu/include/odm_HWConfig.h
index b37962edb2ed..35a562372a1a 100644
--- a/drivers/staging/r8188eu/include/odm_HWConfig.h
+++ b/drivers/staging/r8188eu/include/odm_HWConfig.h
@@ -14,6 +14,13 @@
 
 /*  structure and define */
 
+/*
+ * Attention: struct phy_status_rpt and struct phy_rx_agc_info describe
+ * data structures that this driver receives from the r8188eu chip via usb.
+ * Do not change the content of these structures, do not remove seemingly
+ * unused entries.
+ */
+
 struct phy_rx_agc_info {
 	#ifdef __LITTLE_ENDIAN
 		u8	gain:7, trsw:1;
-- 
2.30.2

Re: [PATCH RFC] staging: r8188eu: comment about the chip's packet format

[Dan Carpenter]

On Fri, Feb 18, 2022 at 10:22:53AM +0100, Martin Kaiser wrote:
> The structs phy_rx_agc_info and phy_status_rpt define parts of the
> header data that the r8188eu chipset sends to this driver via usb.
> 
> Add a comment to clarify that we cannot modify the content of these
> structures and remove seemingly unused fields.
> 
> Signed-off-by: Martin Kaiser <martin@kaiser.cx>
> ---
> 
> Dear all,
> 
> I experimented with "cleaning up" these structures and related code before
> discovering that their content comes from usb packets we receive from the
> r8188eu chipset.
> 
> Would it make sense to add a word of warning to prevent others from
> repeating this exercise?

Just the fact that these structs are endian means they're from the
firmware or the network.

If a struct has a pointer in it, then it's rarely part of the UAPI but
if it has endian data then it probably is.

regards,
dan carpenter

Re: [PATCH RFC] staging: r8188eu: comment about the chip's packet format

[Martin Kaiser]

Thus wrote Dan Carpenter (dan.carpenter@oracle.com):

> On Fri, Feb 18, 2022 at 10:22:53AM +0100, Martin Kaiser wrote:

> > Would it make sense to add a word of warning to prevent others from
> > repeating this exercise?

> Just the fact that these structs are endian means they're from the
> firmware or the network.

> If a struct has a pointer in it, then it's rarely part of the UAPI but
> if it has endian data then it probably is.

ah, these are useful criteria, thanks. I see that the comment isn't
really necessary...

Re: [PATCH RFC] staging: r8188eu: comment about the chip's packet format

[Larry Finger]

On 2/18/22 04:22, Dan Carpenter wrote:
> On Fri, Feb 18, 2022 at 10:22:53AM +0100, Martin Kaiser wrote:
>> The structs phy_rx_agc_info and phy_status_rpt define parts of the
>> header data that the r8188eu chipset sends to this driver via usb.
>>
>> Add a comment to clarify that we cannot modify the content of these
>> structures and remove seemingly unused fields.
>>
>> Signed-off-by: Martin Kaiser <martin@kaiser.cx>
>> ---
>>
>> Dear all,
>>
>> I experimented with "cleaning up" these structures and related code before
>> discovering that their content comes from usb packets we receive from the
>> r8188eu chipset.
>>
>> Would it make sense to add a word of warning to prevent others from
>> repeating this exercise?
> 
> Just the fact that these structs are endian means they're from the
> firmware or the network.
> 
> If a struct has a pointer in it, then it's rarely part of the UAPI but
> if it has endian data then it probably is.

Additionally, do not change any struct with the __packed attribute. Most will 
have endian variables as well, but not all will.

Testing after modifying any struct is a necessity.

Larry