nuttx/wireless/ioctl: Common IOCTL API for RF Modulation Technologies

[keever50]

Summary

This PR is a follow-up of #15856 and the mailing list proposal "Proposal: Common IOCTL API for RF Modulation Technologies"

Currently, the IOCTL API for character-driven RF devices lacks a common
interface across different modulation technologies, such as LoRa, FSK, and
OOK. As a result, driver-specific IOCTL commands are created even when they
could be shared across multiple radios. This fragmentation makes
application portability more difficult to maintain.

This PR will add a common API that can be shared across all new drivers.
Such as

• LoRa
• FSK
• OOK / ASK
• read() return struct

Impact

This change does not impact existing drivers by design.

• Legacy drivers remain unchanged but can be ported if desired.
• Experimental drivers can be freely adapted.
• New drivers must use the common API whenever possible.

The API covers the most common RF features. If additional functionality is required, new IOCTL commands can be introduced without breaking compatibility.

Documentation updates will follow after the initial approval of this commit.

Relevant to previous discussions: This update is no more a breaking change. No existing IOCTL commands have been replaced or removed.

Testing

This update is designed to be non-disruptive to existing drivers. However, some IOCTL command offsets have been adjusted.

• Tested on: SX126x driver
• Verification: The SX126x driver was tested using its driver-specific (non-common API) commands and continues to function as expected.
• Next Steps: Since no drivers currently implement this API, further testing will occur during the porting process.

[nuttxpr]

[Experimental Bot, please feedback here]

Yes, this PR generally meets the NuttX requirements, but could be improved. Here's a breakdown:

Strengths:

• Clear Summary: The summary explains the "why," "what," and "how" of the change, linking it back to the original issue and mailing list discussion.
• Impact Assessment: Addresses most impact areas, explicitly stating the lack of impact on existing drivers and the plan for documentation.
• Testing Strategy Outlined: Explains the current testing limitations due to the nature of the change (new API with no implementing drivers yet) and outlines next steps.

Areas for Improvement:

• More Specific "How": While the summary mentions a common API, it only lists a few technologies (LoRa, FSK, OOK). Providing a few specific examples of new IOCTL commands and their parameters would strengthen the description of "how" the change works. Example: "Adds IOCTL_RF_SET_FREQUENCY which takes a uint32_t frequency in Hz."
• Complete Testing Section: The testing section needs to be filled out more thoroughly. While acknowledging the limitations is good, the "Testing logs before change" and "Testing logs after change" sections are empty. Even if the new API isn't used yet, show some logs demonstrating the existing SX126x driver still works after the changes. This proves the changes haven't inadvertently broken anything. Include specific commands used and expected outputs.
• Build Host/Target Details: The "Testing" section is missing crucial details about the build host and target environments. Be specific: "Build Host: Linux (Ubuntu 20.04), x86_64, GCC 9.4.0. Target: sim:qemu-arm." This is essential for reproducibility.
• Documentation Impact Clarification: While it mentions documentation updates will follow, be more explicit. Will a new document be created, or will existing documentation be updated? If the latter, specify which files.
• Consider Security/Compatibility in More Detail: While marked "NO," briefly justify why there are no security or compatibility implications. For example: "Security Impact: NO - This change only introduces new API calls and does not alter any existing functionality, therefore no new security vulnerabilities are introduced. Compatibility Impact: NO - This change is additive and does not modify existing driver behavior. New drivers are encouraged but not required to use the new API." This demonstrates you've considered these aspects.

By addressing these points, the PR will be even stronger and more readily accepted.

[keever50]

will fix the conflict. That error did not pop up for me. Ill make sure to clean build double check everything.

[lupyuen]

Please remember to fill in the Commit Message. Just copy from the PR Summary above. Thanks :-)

• 8696cd8

[keever50]

Please remember to fill in the Commit Message. Just copy from the PR Summary above. Thanks :-)

• 8696cd8

I suggest adding a checklist contributors can fill in somewhere? In the guidelines or PR template. This makes things a bit easier for both reviewers and contributors, because less time is going into corrections, hopefully.

[lupyuen]

Yep we just updated the guidelines here :-)
https://github.com/apache/nuttx/blob/master/CONTRIBUTING.md

[keever50]

Thank you for the spelling checks. These are now corrected