* Add `./tools/checkpatch.sh -c -u -m -g HEAD~...HEAD` example
to match checks performed by our CI.
* Add cross-reference to checkpatch.sh documentation.
Signed-off-by: Tomasz 'CeDeROM' CEDRO <tomek@cedro.info>
In Jan-Feb 2026: NuttX CI hit a [record high usage of GitHub Runners](https://github.com/apache/nuttx/issues/17914), exceeding the limit enforced by ASF Infrastructure Team. We analysed the PRs and discovered that most GitHub Runners were wasted on __(1) Failure to Download the Build Dependencies__ for DTC Device Tree, OpenAMP Messaging, MicroADB Debugger, MCUBoot Bootloader, NimBLE Bluetooth, etc __(2) Resubmitting PR Commits__:
- [Video: Analysing the Most Expensive PR](https://youtu.be/swFaxaTCEQg)
- [Video: Second Most Expensive PR](https://youtu.be/uSpQkzBogEw)
- [Video: Third Most Expensive PR](https://youtu.be/J7w1gyjwZ1w)
- [Video: Most Expensive Apps PR](https://youtu.be/182h8cRpfvI)
- [Spreadsheet: Most Expensive PRs](https://docs.google.com/spreadsheets/d/1HY7fIZzd_fs3QPyA0TX7vsYOjL86m1fNOf1Wls93luI/edit?gid=70515654#gid=70515654)
Why would __Download Failures__ waste GitHub Runners? That's because Download Failures will terminate the Entire CI Build (across All CI Jobs), requiring a restart of the CI Build. And the CI Build isn't terminated immediately upon failure: NuttX CI waits for the CI Job to complete (e.g. arm-01), before terminating the CI Build. Which means that CI Builds can get terminated 2.5 hours into the CI Build, wasting 2.5 elapsed hours x [7.4 parallel processes](https://lupyuen.org/articles/ci3#live-metric-for-full-time-runners) of GitHub Runners.
This PR proposes to __Retry the Build for Each CI Target__. NuttX CI shall rebuild each CI Target (e.g. `sim:nsh`), upon failure, up to 3 times (total 4 builds). Each rebuild will be attempted after a Randomised Delay with Exponential
Backoff, initially set to 60 seconds, then 120 seconds, 240 seconds. The rebuilds will mitigate the effects of Intermittent Download Failures that occur in GitHub Actions. (And eliminate developer frustration)
If the build fails after 3 retries: Subsequent CI Targets will __not be allowed to rebuild__ upon failure. This is to prevent cascading build failures from overloading GitHub Actions, and consuming too many GitHub Runners.
Note that NuttX CI shall retry the build for __Any Kind of Build Failure__, including Download Failures, Compile Errors and Config Errors. We designed it simplistically due to our current constraints: (1) Lack of CI Expertise (2) NuttX CI is Mission Critical (3) Legacy CI Scripts are Highly Complex. To prevent Compile Errors and Config Errors: We expect NuttX Devs to [Build and Test PRs in Our Own Repos](https://github.com/apache/nuttx/issues/18568), before submitting to NuttX.
What about __Resubmitting PR Commits__ and its wastage of GitHub Runners? We also require NuttX Devs to [Build and Test PRs in Our Own Repos](https://github.com/apache/nuttx/issues/18568), before resubmitting to NuttX. GitHub Runners will then be charged to the developer's quota, without affecting the GitHub Runners quota for Apache NuttX Project. We plan to [Kill All CI Jobs](https://youtu.be/182h8cRpfvI?si=MmAuwLISZPPMoqDq&t=1479) for PRs that have been switched to Draft Mode. We'll monitor this through the [NuttX Build Monitor](https://github.com/apache/nuttx/issues/18659).
Modified Files:
`tools/testbuild.sh`: We introduce a New Wrapper Function `retrytest` that will call the Existing Function `dotest`, to build the CI Target and retry on error.
`Documentation/components/tools/testbuild.rst`: Updated the `testbuild.sh` doc with the Retry Logic.
Signed-off-by: Lup Yuen Lee <luppy@appkaki.com>
Document the new mkpasswd-based password generation system and its
integration with the build process.
Changes:
* Add comprehensive mkpasswd tool documentation to components/tools
* Update SIM board docs to explain generated passwd workflow
* Update ESP32-C3-legacy board docs for passwd generation
* Update RX65N board docs with credential handling guidance
* Document how to configure and use BOARD_ETC_ROMFS_PASSWD_* options
* Explain security benefits of build-time generation vs static files
* Update all doc examples from default username "admin" to "root"
BREAKING CHANGE: Boards using static /etc/passwd files in ETC_ROMFS
must migrate to the new build-time generation workflow documented in
Documentation/components/tools/index.rst. The old static passwd files
are no longer present in migrated boards; boards that relied on them
will fail to build until credentials are configured via Kconfig.
Signed-off-by: Abhishek Mishra <mishra.abhishek2808@gmail.com>
debug.h is a NuttX-specific, non-POSIX header. Placing it in the
top-level include/ directory creates naming conflicts with external
projects that define their own debug.h.
This commit moves the canonical header to include/nuttx/debug.h,
following the NuttX convention for non-POSIX/non-standard headers,
and updates all in-tree references.
A backward-compatibility shim is left at include/debug.h that
emits a deprecation #warning and re-includes <nuttx/debug.h>,
allowing out-of-tree code to continue building while migrating.
Signed-off-by: Piyush Patle <piyushpatle228@gmail.com>
Add documentation for the RC/LIRC character driver subsystem covering
device registration, the LIRC interface, and usage from user space.
Remove placeholder empty files under drivers/rmt that were left over
from the rmtchar era and are no longer referenced.
Signed-off-by: Piyush Patle <piyushpatle228@gmail.com>
This adds support for PBKDF2 (SHA1 and SHA256) while leveraging
the existing infrastructure for HMAC.
Signed-off-by: Vlad Pruteanu <pruteanuvlad1611@yahoo.com>
Add USB Video Class 1.1 gadget driver supporting Bulk transport
with uncompressed YUY2 video streaming. Resolution and frame
interval are negotiated dynamically via PROBE/COMMIT control.
- uvc.h: protocol constants, streaming control struct, public API
- uvc.c: class driver with PROBE/COMMIT, bulk EP, /dev/uvc0 chardev
- Kconfig/Make.defs: USBUVC config and build rules
- boardctl.c: BOARDIOC_USBDEV_UVC standalone init path
Hardened against host disconnect:
- Removed nxmutex_lock from USB interrupt context paths
- Added 30s semaphore timeout in uvc_write with EP_CANCEL fallback
- Drain stale wrsem counts in VS_COMMIT before new stream
- Guard uvc_streaming_stop() against double EP_CANCEL race
- Handle EP_SUBMIT returning -ESHUTDOWN gracefully
Signed-off-by: wangjianyu3 <wangjianyu3@xiaomi.com>
Fix 269 occurrences of duplicate "the" word typo found in 209 files
across source code, header files, and configuration.
Signed-off-by: Huang Qi <huangqi3@xiaomi.com>
This update enhances the SDIO documentation by including a reference to the card initialization flowchart in the MMC/SD physical layer specification. This addition aims to provide implementers with a clearer understanding of the complete card initialization and command sequence.
Signed-off-by: Arjav Patel <arjav1528@gmail.com>
This update clarifies the call-flow for the SDIO lower-half driver implementation by providing a simplified example of the interaction between the MMCSD upper-half and the lower-half. It details the command sequence for handling R2 responses, improving the understanding of the expected behavior during card identification and initialization.
Signed-off-by: Arjav Patel <arjav1528@gmail.com>
This update adds a reference to the SDIO Driver Documentation for implementers of SDIO lower-half drivers, emphasizing the importance of understanding R2/CSD response handling and the correct implementation of the lower-half interface.
Signed-off-by: Arjav Patel <arjav1528@gmail.com>
This update expands the documentation for implementing an SDIO lower-half driver, detailing the required interface, call-flow, and handling of the R2 response format. It emphasizes the importance of byte-shifting when the CRC is stripped by the hardware, providing reference implementations for clarity.
Signed-off-by: Arjav Patel <arjav1528@gmail.com>
Add a new section documenting the TIOCSERGSTRUCT debug ioctl and CONFIG_SERIAL_TIOCSERGSTRUCT Kconfig option. The section covers enabling the feature, how the ioctl copies driver-internal state to user space, example usage with the 16550 UART driver, and a warning about the non-stable nature of exposed structures.
Signed-off-by: Arjav Patel <arjav1528@gmail.com>
All of the tools listed on the original documentation are now given
their own individual doc pages. This makes it much easier to
cross-reference them from other documentation locations (as many are
used in CI/for specific architectures) and it also makes it easier for
users to digest the information.
Signed-off-by: Matteo Golin <matteo.golin@gmail.com>
- Introduced Kconfig options for stdbit.h, allowing architecture-specific and generic implementations.
- Added new documentation for stdbit.h, detailing its usage and configuration.
- Updated CMake and Makefile to handle the inclusion of stdbit.h based on configuration settings.
This enhances the NuttX library with optional C23 bit manipulation utilities, improving functionality for architectures that support it.
Signed-off-by: Arjav Patel <arjav1528@gmail.com>
This commit updates the syslog.rst documentation to:
1. Add a new "Overview" section with the syslog-overview.png diagram
2. Introduce a comprehensive "Syslog Configuration Options" chapter
3. Document the CONFIG_SYSLOG_TIMESTAMP_MS option (newly added in driver code)
- Clarify its dependency on CONFIG_SYSLOG_TIMESTAMP
- Explain its function: use millisecond (ms) precision instead of default microsecond (µs)
4. Group all syslog Kconfig options by functional role (debug level, formatting, buffer, etc.)
- Basic Debug Log Level Configuration
- Message Formatting Configuration (timestamp/metadata/visual)
- (Other categories follow the syslog system architecture)
The documentation changes align with the recent driver enhancement:
- drivers/syslog: add millisecond option for syslog timestamp formatting
- Maintain consistency between driver code and documentation
- Make syslog configuration options more discoverable for developers
Signed-off-by: chao an <anchao.archer@bytedance.com>
Add a generic kmatrix lower-half with polling/debounce, STM32 board adapters, Kconfig options, a public API header, and a test example/documentation.
Signed-off-by: Felipe Moura <moura.fmo@gmail.com>
decouple kbd / keypad.
Fix some comments
add documentation
fix rule issues
Update CMakeLists.txt
update documentation.
improve documentation
Add comprehensive documentation for the Vhost framework, which serves
as the VirtIO backend implementation in NuttX for cross-core communication.
The documentation includes:
- Overview and comparison with Linux Vhost and QEMU VirtIO Device
- Three-layer architecture (Service, Framework, Transport)
- Driver/Device registration and matching workflow
- Source code directory structure
- Complete API reference (data structures, core APIs, macro APIs)
Signed-off-by: Bowen Wang <wangbowen6@xiaomi.com>
Add documentation for the RPMsg dump command, which is a diagnostic
tool for dumping RPMsg debugging information. The document covers:
- Command usage and syntax
- Output description including CPU info, endpoint list, virtqueue
dump, and buffer states
- Common debugging use cases such as TX buffer timeout issues,
communication failures, and buffer leak detection
Signed-off-by: Bowen Wang <wangbowen6@xiaomi.com>
Add comprehensive documentation for the RPMsg Ping diagnostic tool,
which is used for testing inter-processor communication and measuring
latency/throughput metrics.
The documentation includes:
- Overview and use cases
- Configuration instructions
- Command syntax and parameters
- Usage examples with sample output
- Architecture workflow diagram
- Best practices for latency and throughput testing
Signed-off-by: Bowen Wang <wangbowen6@xiaomi.com>
Add documentation for CONFIG_TIMER_WDOG, a software-based timer
implementation using the NuttX wdog subsystem.
Signed-off-by: yangsong8 <yangsong8@xiaomi.com>
Add documentation for RPMsg Port UART, a transport layer that enables
RPMsg communication between SoCs via UART when shared memory is not
available.
The documentation covers:
- Hardware requirements (UART with flow control)
- Software architecture
- Escape coding protocol for command/data separation
- Connection establishment protocol
- Data frame format
- Low power support with ping-pong wake mechanism
Signed-off-by: Bowen Wang <wangbowen6@xiaomi.com>
Add comprehensive documentation for the RPMsg Port abstract transport
layer, which supports cross-SoC communication via physical backends
like SPI and UART.
The documentation covers:
- Architecture overview and layer diagram
- Buffer management with TX/RX free and ready lists
- Buffer layout with header reservation
- Data transmission and reception flow
Signed-off-by: Bowen Wang <wangbowen6@xiaomi.com>
* Remove `tools/` from the section name.
* Generate local TOC that lists described tools.
* Update new parsetrace.py toctree location to fix indexing and display.
Signed-off-by: Tomasz 'CeDeROM' CEDRO <tomek@cedro.info>
For the following code, we need to check 'type_attr.form'.
type_attr = DIE.attributes["DW_AT_type"]
base_type_die = dwarfinfo.get_DIE_from_refaddr(xxx)
When type_attr.form==DW_FORM_ref_addr, 'type_attr.value' means
global reference (across compilation units).
When type_attr.form==DW_FORM_ref4, 'type_attr.value' means
local reference (within the same compilation unit).
Signed-off-by: yukangzhi <yukangzhi@xiaomi.com>
Add a concise RPMsg documentation covering:
- Overview of RPMsg framework for AMP systems
- Application scenarios (heterogeneous/homogeneous AMP)
- Layered architecture (Services/Framework/Transport/Physical)
- Message encapsulation process
- Workflow: channel establishment, sending and receiving
- Key design considerations (FIFO order, callback blocking)
- Transport layer comparison
All diagrams use ASCII art for portability.
Signed-off-by: Bowen Wang <wangbowen6@xiaomi.com>
This commit fixes a typo in the capture.h header file. This is a
breaking change, but the fix is trivial (replace macro with new one).
Signed-off-by: Côme VINCENT <44554692+comejv@users.noreply.github.com>
Document all supported cryptographic algorithms and their variants in the NuttX Crypto API subsystem, including:
- AES-CBC with 128/192/256-bit key sizes
- HMAC and hash functions
- AES GMAC and CMAC
- ChaCha20-Poly1305
- And other supported algorithms
This documentation provides a comprehensive reference for developers using the cryptographic services.
Signed-off-by: makejian <makejian@xiaomi.com>
[checkkconfig.py] is a tool that simulates the effects of modifying a CONFIG item,
Can be used to check whether my config changes are what I expected.
Signed-off-by: xuxin19 <xuxin19@xiaomi.com>
Add basic timer operations to the kernel, including registration,
start/stop, and callback handling. This provides a consistent timer
interface for use by kernel components and drivers.
Signed-off-by: zhaohaiyang1 <zhaohaiyang1@xiaomi.com>
Introduce a single configuration option to provide strict transmit
priority ordering based on CAN ID.
The intention is to expose the user-visible behavior (strict TX
priority ordering) rather than the underlying implementation details.
Strict priority ordering is only meaningful when hardware transmit
buffer cancellation is available, so splitting this functionality into
separate configuration options was misleading and could result in
partially effective or incorrect configurations.
Signed-off-by: zhaohaiyang1 <zhaohaiyang1@xiaomi.com>
These documentation updates correspond to commits:
- drivers/capture: add signal notification support for edge capture events
- drivers/capture: add fake capture driver for testing and development
Signed-off-by: dongjiuzhu1 <dongjiuzhu1@xiaomi.com>
This documentation helps users understand when and how to use IO expander
pins for implementing additional I2C buses in their applications.
Related commit: 06099d492e (drivers/i2c: Add IO expander-based I2C bit-bang)
Signed-off-by: dongjiuzhu1 <dongjiuzhu1@xiaomi.com>
This moves mtd.rst from special/ directory to its own special/mtd
subdirectory and adds pages for supported devices (NOR/NAND flashes and
EEPROMS) with some basic configuration and initialization description.
Signed-off-by: Michal Lenc <michallenc@seznam.cz>
This patch adds comprehensive documentation for the PTP (Precision Time
Protocol) clock driver framework in NuttX.
The documentation covers:
1. Overview and Architecture:
- IEEE 1588 PTP clock framework introduction
- Upper-half and lower-half driver architecture
- Integration with POSIX clock APIs
2. Configuration Options:
- CONFIG_PTP_CLOCK: Main framework configuration
- CONFIG_PTP_CLOCK_DUMMY: Dummy driver for testing
- CONFIG_CLOCK_ADJTIME: clock_adjtime() system call support
3. Device Interface:
- Character device interface (/dev/ptpN)
- IOCTL commands: PTP_CLOCK_GETTIME, PTP_CLOCK_SETTIME,
PTP_CLOCK_GETRES, PTP_CLOCK_ADJTIME, PTP_CLOCK_GETCAPS,
PTP_SYS_OFFSET, PTP_SYS_OFFSET_PRECISE
4. POSIX Clock API (CLOCKFD):
- Using CLOCKFD() macro to access PTP clocks
- clock_gettime(), clock_settime(), clock_getres() examples
- clock_adjtime() with various adjustment modes
- ADJ_OFFSET, ADJ_FREQUENCY, ADJ_SETOFFSET support
5. Dummy PTP Clock Driver:
- Software-based implementation for testing
- Features and initialization details
6. Example Usage:
- Basic time operations
- Frequency adjustment examples
- Time offset adjustment examples
7. Implementing Lower-Half Drivers:
- Step-by-step guide for hardware driver implementation
- Required operations and structures
- Registration process
8. Integration with PTP Daemons:
- ptp4l, timemaster, ptpd compatibility
- Standard POSIX clock API usage
9. Performance Considerations:
- Hardware timestamping requirements
- Cross-timestamping support
- Frequency adjustment resolution
10. Debugging:
- Debug configuration options
- Debug output examples
The documentation is added to:
- Documentation/components/drivers/special/ptp.rst (new file)
- Documentation/components/drivers/special/index.rst (updated)
This provides developers with complete reference material for using
and implementing PTP clock drivers in NuttX.
Signed-off-by: dongjiuzhu1 <dongjiuzhu1@xiaomi.com>
shutdown should send TCP_FIN packet.
close should send TCP_RST packet when the data in readahead has not been
read and NEW_DATA has arrived.
send TCP_FIN packet when in other cases.
Signed-off-by: zhanghongyu <zhanghongyu@xiaomi.com>
