diff --git a/Documentation/components/drivers/character/analog.rst b/Documentation/components/drivers/character/analog.rst index bbdad04e70..c8f8c75460 100644 --- a/Documentation/components/drivers/character/analog.rst +++ b/Documentation/components/drivers/character/analog.rst @@ -16,7 +16,7 @@ The NuttX analog drivers are split into two parts: - Common analog logic and share-able analog drivers reside in the ``drivers/analog/``. - Platform-specific drivers reside in - ``arch///src/`` directory + ``arch//src/`` directory for the specific processor ```` and for the specific ```` analog peripheral devices. diff --git a/Documentation/components/drivers/index.rst b/Documentation/components/drivers/index.rst index bb2c00dd3c..03bb7cc902 100644 --- a/Documentation/components/drivers/index.rst +++ b/Documentation/components/drivers/index.rst @@ -277,9 +277,9 @@ Skeleton Files Skeleton files are "empty" frameworks for NuttX drivers. They are provided to give you a good starting point if you want to create a new NuttX driver. -The following skeleton files are available:: +The following skeleton files are available: - drivers/lcd/skeleton.c -- Skeleton LCD driver - drivers/mtd/skeleton.c -- Skeleton memory technology device drivers - drivers/net/skeleton.c -- Skeleton network/Ethernet drivers - drivers/usbhost/usbhost_skeleton.c -- Skeleton USB host class driver +* ``drivers/lcd/skeleton.c`` Skeleton LCD driver +* ``drivers/mtd/skeleton.c`` Skeleton memory technology device drivers +* ``drivers/net/skeleton.c`` Skeleton network/Ethernet drivers +* ``drivers/usbhost/usbhost_skeleton.c`` Skeleton USB host class driver diff --git a/Documentation/components/libs/index.rst b/Documentation/components/libs/index.rst index 8ae74d3298..3ef511cc3b 100644 --- a/Documentation/components/libs/index.rst +++ b/Documentation/components/libs/index.rst @@ -34,7 +34,6 @@ container. The only real function of the ``libs/`` directory is to prevent the top-level directory from becoming cluttered with individual libraries. - .. toctree:: :maxdepth: 1 :caption: Contents: diff --git a/Documentation/contributing/index.rst b/Documentation/contributing/index.rst index 985fe77e14..79ffe661b6 100644 --- a/Documentation/contributing/index.rst +++ b/Documentation/contributing/index.rst @@ -1,3 +1,4 @@ +============ Contributing ============ diff --git a/Documentation/contributing/making-changes.rst b/Documentation/contributing/making-changes.rst index 7198081a26..692402bf20 100644 --- a/Documentation/contributing/making-changes.rst +++ b/Documentation/contributing/making-changes.rst @@ -1,6 +1,7 @@ .. include:: /substitutions.rst .. _making-changes: +======================== Making Changes Using Git ======================== @@ -65,7 +66,7 @@ Here's how to do it: $ git push Git Workflow With an Upstream Repository ----------------------------------------- +======================================== The main NuttX git repository is called an "upstream" repository - this is because it's the main source of truth, and its changes flow downstream to people who've forked that repository, like us. @@ -160,7 +161,7 @@ maybe doing that several times. Then when everything works, I get my branch read $ git push Submitting Your Changes to NuttX --------------------------------- +================================ Pull requests let you tell others about changes you've pushed to a branch in a repository on GitHub. Once a pull request is opened, you can discuss and review the potential changes with collaborators and add follow-up commits @@ -212,7 +213,7 @@ squash before submitting the Pull Request: 1 through 6. How to Include the Suggestions on Your Pull Request? ----------------------------------------------------- +==================================================== If you submitted your first PR (Pull Request) and received some feedbacks to modify your commit, then probably you already modified it and created a @@ -344,7 +345,7 @@ Now you can look at your PR at NuttX's github to confirm that this squashed commit is there. Git Resources -------------- +============= * `Git Cheat Sheet (by GitHub) `_ * `Git Book (online) `_ diff --git a/Documentation/contributing/workflow.rst b/Documentation/contributing/workflow.rst index 5c7aca86dc..743246c455 100644 --- a/Documentation/contributing/workflow.rst +++ b/Documentation/contributing/workflow.rst @@ -1,5 +1,6 @@ .. todo:: update when workflow is settled +==================== Development Workflow ==================== diff --git a/Documentation/guides/coredump.rst b/Documentation/guides/coredump.rst index 1875e442df..a231119198 100644 --- a/Documentation/guides/coredump.rst +++ b/Documentation/guides/coredump.rst @@ -1,6 +1,6 @@ -==================== +========= Core Dump -==================== +========= Overview ======== diff --git a/Documentation/guides/cpp_cmake.rst b/Documentation/guides/cpp_cmake.rst index 5ac464ce45..71948e7300 100644 --- a/Documentation/guides/cpp_cmake.rst +++ b/Documentation/guides/cpp_cmake.rst @@ -1,6 +1,7 @@ .. include:: /substitutions.rst .. _cpp_cmake: +======================= C++ Example using CMake ======================= @@ -24,7 +25,7 @@ applications using C++ language and also the cmake build tool. This document will show how to reimplement the hellocpp project using this cmake. Preparation ------------ +=========== #. Base NuttX compilation changes @@ -46,7 +47,7 @@ Preparation $ make export Creating the project --------------------- +==================== #. Create your project file structure @@ -268,7 +269,7 @@ Creating the project } Building --------- +======== To launch build, you use the cmake procedure: diff --git a/Documentation/guides/customapps.rst b/Documentation/guides/customapps.rst index 03df67705f..f2930f4704 100644 --- a/Documentation/guides/customapps.rst +++ b/Documentation/guides/customapps.rst @@ -18,9 +18,8 @@ the directory ``CustomApps`` as an example. need to run ``make clean`` and possibly even ``make distclean`` before rebuilding to ensure it works correctly. ------------------------------------------ 1. Replace The Apps/ Directory Completely ------------------------------------------ +========================================= The CustomApps directory need only to contain the minimum three files: @@ -188,9 +187,8 @@ Then build as you normally would. When you execute the custom_hello app you shou Hello, Custom World!! ---------------------------------------------------------------- 2. Extend the apps/ directory to include a new custom directory ---------------------------------------------------------------- +=============================================================== The collection of apps provided in nuttx-apps can be useful, and this method simply extends the directory structure to include your own directory structure. @@ -306,9 +304,8 @@ followed by ``make menuconfig``. If successful there will be new Kconfig entries Select the ``Custom Hello App`` and run the usual build process. If successful you can run the newly included ``custom_hello`` app. --------------------------------------------------------------------------- 3. Include an Additional Custom directory Outside of the Main Source Trees --------------------------------------------------------------------------- +========================================================================== Thia is similar to the previous approach, but places the ``CustomApps`` directory outside of the default trees. diff --git a/Documentation/guides/customboards.rst b/Documentation/guides/customboards.rst index d9eab5edb6..95c21b0d5b 100644 --- a/Documentation/guides/customboards.rst +++ b/Documentation/guides/customboards.rst @@ -17,9 +17,8 @@ Sometimes it is not appropriate, or not wanted, to add a new or custom board to the NuttX boards tree itself. If so, the board can be defined out-of-tree in a custom directory and still be built easily. ------------------- Add a Custom Board ------------------- +================== The same set of files as provided for in-tree boards is required (i.e. configs, Kconfig, scripts, etc.) but these can be placed in a directory of your choice. @@ -53,7 +52,7 @@ To build the custom board, the syntax is slightly different to in-tree boards an Refreshing... Kconfig Settings ----------------- +================ Once the board is configured, to ensure subsequent builds run correctly, there are two Kconfig settings that need to be set. These are: diff --git a/Documentation/guides/drivers.rst b/Documentation/guides/drivers.rst index 8d7d78a4cb..69ad84343e 100644 --- a/Documentation/guides/drivers.rst +++ b/Documentation/guides/drivers.rst @@ -1,6 +1,7 @@ .. include:: /substitutions.rst .. _drivers: +======= Drivers ======= @@ -10,7 +11,7 @@ you will either need to port a driver from another chip, or write one yourself. .. _drivers-porting: Porting a Driver ----------------- +================ Often support for on-chip peripherals exists in a closely related chip, or even a different family or from a different manufacturer. Many chips are made up of different Intellectual Property (IP) blocks that are licensed from vendors like @@ -144,7 +145,7 @@ modification. 200aaaa0: 0000 0000 0000 0000 ........ NuttX Drivers as a Reference ----------------------------- +============================ If you're not porting a NuttX driver from another architecture, it still helps to look at other similar NuttX drivers, if there are any. For instance, when implementing an Ethernet driver, look at other NuttX Ethernet drivers; @@ -152,7 +153,7 @@ for an SD Card driver, look at other NuttX SD Card drivers. Even if the chip-spe structure to interface with NuttX can be used. Using Chip Datasheets ---------------------- +===================== To port or write a driver, you'll have to be familiar with the information in the chip datasheet. Definitely find the datasheet for your chip, and read the sections relevant to the peripheral you're working with. Doing so ahead @@ -179,7 +180,7 @@ code implements the necessary algorithms often helps one understand how the driv examples. Logic Analyzers ---------------- +=============== For drivers that involve input and output (I/O), especially that involve complex protocols like SD Cards, SPI, I2C, etc., actually seeing the waveform that goes in and out the chip's pins is extremely helpful. `Logic Analyzers `_ @@ -187,7 +188,7 @@ can capture that information and display it graphically, allowing you to see if on the wire. DMA Debugging -------------- +============= * Dump registers before, during, and after transfer. Some NuttX drivers (``sam_sdmmc.c`` or ``imxrt_sdmmc.c`` for example) have built-in code for debugging register states, and can sample registers before, during, and diff --git a/Documentation/guides/gdbwithpython.rst b/Documentation/guides/gdbwithpython.rst index 469d44f2b8..2f1d895b0d 100644 --- a/Documentation/guides/gdbwithpython.rst +++ b/Documentation/guides/gdbwithpython.rst @@ -1,6 +1,6 @@ -==================== +=============== GDB with Python -==================== +=============== Introduction ============ diff --git a/Documentation/guides/index.rst b/Documentation/guides/index.rst index 1eceb6c57b..e0f1d31b41 100644 --- a/Documentation/guides/index.rst +++ b/Documentation/guides/index.rst @@ -1,6 +1,7 @@ .. todo:: Create "tutorial" type documentation for specific subjects not to be covered in more general terms. +====== Guides ====== diff --git a/Documentation/guides/ofloader.rst b/Documentation/guides/ofloader.rst index 9946cd8794..743fb9d132 100644 --- a/Documentation/guides/ofloader.rst +++ b/Documentation/guides/ofloader.rst @@ -3,7 +3,7 @@ Open Flash Loader ================= Introduce -===================================== +========= Open Flash loader is an implementation in NuttX that bridges the device drivers in NuttX with the programming methods of a flash loader in J-Link. diff --git a/Documentation/guides/pysimcoder.rst b/Documentation/guides/pysimcoder.rst index d66c275733..991c802363 100644 --- a/Documentation/guides/pysimcoder.rst +++ b/Documentation/guides/pysimcoder.rst @@ -1,6 +1,7 @@ .. include:: /substitutions.rst .. _pysimcoder: +================================= pysimCoder integration with NuttX ================================= @@ -16,7 +17,7 @@ This documentation describes the steps that are needed to run application genera on NuttX and also keeps the track of peripherals that are supported by pysimCoder for NuttX RTOS. Peripheral Support ------------------- +================== The following list shows the peripherals and fuctionalities supported in pysimCoder for NuttX RTOS. @@ -39,7 +40,7 @@ Please note that the actual support for NuttX peripherals can be wider that what in case this documentation was not updated when new fuctionalities were added to pysimCoder. NuttX Configuration -------------------- +=================== Several configuration options are necessary to be set in order to successfully compile pysimCoder with NuttX. The list is the following: @@ -124,7 +125,7 @@ Please note that PYSUPSICTRL variable has to be set/exported in order to success designed with pysimCoder. Using pysimCoder to design NuttX application --------------------------------------------- +============================================ After running pysimCoder, separate blocks can be selected from the library menu on the left hand side. The menu contains several libraries, NuttX specific blocks can be found in library "NuttX". It is also possible to use blocks from other diff --git a/Documentation/guides/qemugdb.rst b/Documentation/guides/qemugdb.rst index 72214564bf..488953960f 100644 --- a/Documentation/guides/qemugdb.rst +++ b/Documentation/guides/qemugdb.rst @@ -1,6 +1,7 @@ .. include:: /substitutions.rst .. _qemugdb: +===================================== How to debug NuttX using QEMU and GDB ===================================== @@ -11,7 +12,7 @@ board or architecture supported by QEMU. Start configuring and compiling the lm3s6965-ek board with qemu-flat profile. Compiling ---------- +========= #. Configure the lm3s6965-ek @@ -31,7 +32,7 @@ Compiling $ make -j Start QEMU ----------- +========== #. You need to start QEMU using the nuttx ELF file just create above: @@ -46,7 +47,7 @@ Start QEMU nsh> Start GDB to connect to QEMU ----------------------------- +============================ These steps show how to connect GDB to QEMU running NuttX: diff --git a/Documentation/guides/rndis.rst b/Documentation/guides/rndis.rst index 58430f588b..77813edcd0 100644 --- a/Documentation/guides/rndis.rst +++ b/Documentation/guides/rndis.rst @@ -1,6 +1,7 @@ .. include:: /substitutions.rst .. _rndis: +================ How to use RNDIS ================ @@ -17,7 +18,7 @@ risk and also be aware that it was tested up to Ubuntu 22.04 LTS and couldn't work in future versions. Compiling ---------- +========= #. Configure the RNDIS @@ -39,7 +40,7 @@ Compiling $ make -j Flashing --------- +======== #. Flash the generated nuttx.bin to your board: @@ -65,7 +66,7 @@ Flashing Setup RNDIS in your computer ----------------------------- +============================ These steps show how to connect your board to your Linux machine. diff --git a/Documentation/guides/simulator.rst b/Documentation/guides/simulator.rst index 17b3b5f9f1..a7ee735c5f 100644 --- a/Documentation/guides/simulator.rst +++ b/Documentation/guides/simulator.rst @@ -1,6 +1,7 @@ .. include:: /substitutions.rst .. _simulator: +========= Simulator ========= @@ -16,7 +17,7 @@ submit a PR to improve this guide! .. todo:: Windows instructions Prerequisites For macOS ------------------------ +======================= We need ``genromfs`` to build simulators(NON GUI). @@ -37,7 +38,7 @@ For GUI Applications we need X11 Libraries, libx11 can also be built using Homeb $ sudo port install xorg-server Compiling ---------- +========= #. Configure the Simulator @@ -94,7 +95,7 @@ Compiling .. _simulator_accessing_the_network: Accessing the Network ---------------------- +===================== #. Here we'll use the ``sim:tcpblaster`` configuration because it comes with networking that is ready to use. @@ -202,7 +203,7 @@ Accessing the Network Success! Testing / capturing TCP network traffic ---------------------------------------- +======================================= #. Start Wireshark (or tcpdump) on Linux and capture the appeared tap0 interface. @@ -228,7 +229,7 @@ Testing / capturing TCP network traffic #. Observe TCP network traffic in Wireshark / tcpdump on Linux. Stopping --------- +======== #. The normal way to stop: @@ -257,6 +258,6 @@ Stopping $ sudo ./tools/simhostroute.sh wlan0 off Debugging ---------- +========= You can debug the simulator like any regular Linux program. diff --git a/Documentation/introduction/index.rst b/Documentation/introduction/index.rst index d61e2e7bcb..d16efdf41b 100644 --- a/Documentation/introduction/index.rst +++ b/Documentation/introduction/index.rst @@ -1,3 +1,4 @@ +============ Introduction ============ diff --git a/Documentation/introduction/resources.rst b/Documentation/introduction/resources.rst index 68524cca76..b4bdf95054 100644 --- a/Documentation/introduction/resources.rst +++ b/Documentation/introduction/resources.rst @@ -22,4 +22,5 @@ Here's a list of Apache NuttX resources that you might find helpful: Legacy README ============= + .. mdinclude:: ../legacy_README.md diff --git a/Documentation/quickstart/configuring.rst b/Documentation/quickstart/configuring.rst index 5add3d6748..4ff425885c 100644 --- a/Documentation/quickstart/configuring.rst +++ b/Documentation/quickstart/configuring.rst @@ -1,6 +1,7 @@ .. include:: /substitutions.rst .. _configuring: +=========== Configuring =========== @@ -93,7 +94,7 @@ computer. configured in :menuselection:`Application Configuration --> NSH Library --> Message of the Day (MOTD)`. Fast configuration changes --------------------------- +========================== If you know exactly which configuration symbol you want to change, you can use the ``kconfig-tweak`` tool (comes with the ``kconfig-frontends`` package) to quickly change a setting without going into the configuration frontend. This is useful to change settings such as debug options: @@ -126,7 +127,7 @@ This is also useful to script configuration changes that you perform often: make oldconfig Reference configuration --------------------------- +======================= Defconfig supports the use of ``#include`` statements to reference other configuration files: @@ -144,7 +145,7 @@ The default header file search path includes: * ``${boards}/common/configs``; Merge configuration --------------------------- +=================== Multiple config fragments can be merged manually using the tools/merge_config.py script. diff --git a/Documentation/reference/os/newreno.rst b/Documentation/reference/os/newreno.rst index 7f238e5a60..21a0a2b35f 100644 --- a/Documentation/reference/os/newreno.rst +++ b/Documentation/reference/os/newreno.rst @@ -13,7 +13,6 @@ NewReno congestion control algorithm is used to solve the problem of network con Workflow ======== - The NewReno on the tcp sender adjusts the cwnd and ssthresh based on received ack and Retransmitted Timeout (RTO) events. Using the cwnd, together with snd_wnd, controls the number of bytes sent to the network. Here's how newreno works, as following: diff --git a/Documentation/reference/user/02_task_scheduling.rst b/Documentation/reference/user/02_task_scheduling.rst index 4d989d12a1..3a1ae8e966 100644 --- a/Documentation/reference/user/02_task_scheduling.rst +++ b/Documentation/reference/user/02_task_scheduling.rst @@ -1,5 +1,6 @@ +========================== Task Scheduling Interfaces -************************** +========================== By default, NuttX performs strict priority scheduling: Tasks of higher priority have exclusive access to the CPU until they become blocked. At @@ -29,7 +30,7 @@ compliant interface to the NuttX scheduler: - :c:func:`sched_get_rr_interval` Functions ---------- +========= .. c:function:: int sched_setparam(pid_t pid, FAR const struct sched_param *param) diff --git a/Documentation/reference/user/06_clocks_timers.rst b/Documentation/reference/user/06_clocks_timers.rst index d158cd1b54..a67fc0cb2d 100644 --- a/Documentation/reference/user/06_clocks_timers.rst +++ b/Documentation/reference/user/06_clocks_timers.rst @@ -1,5 +1,6 @@ +================= Clocks and Timers -***************** +================= - :c:func:`clock_settime` - :c:func:`clock_gettime` diff --git a/Documentation/reference/user/07_signals.rst b/Documentation/reference/user/07_signals.rst index b733813863..185e31e785 100644 --- a/Documentation/reference/user/07_signals.rst +++ b/Documentation/reference/user/07_signals.rst @@ -1,5 +1,6 @@ +================= Signal Interfaces -***************** +================= **Tasks and Signals**. NuttX provides signal interfaces for tasks and pthreads. Signals are used to alter the flow control of tasks by diff --git a/Documentation/reference/user/12_shared_memory.rst b/Documentation/reference/user/12_shared_memory.rst index ee1eafdef7..7d9d63faec 100644 --- a/Documentation/reference/user/12_shared_memory.rst +++ b/Documentation/reference/user/12_shared_memory.rst @@ -1,5 +1,6 @@ +======================== Shared Memory Interfaces -************************ +======================== Shared memory interfaces are only available with the NuttX kernel build (``CONFIG_BUILD_KERNEL=y``). These interfaces support user memory @@ -12,7 +13,7 @@ memory interfaces: - :c:func:`shmdt` Functions ---------- +========= .. c:function:: int shmget(key_t key, size_t size, int shmflg) diff --git a/Documentation/reference/user/structures.rst b/Documentation/reference/user/structures.rst index 73df918c61..872fd58066 100644 --- a/Documentation/reference/user/structures.rst +++ b/Documentation/reference/user/structures.rst @@ -1,8 +1,9 @@ +================== OS Data Structures ================== Scalar Types -************ +============ Many of the types used to communicate with NuttX are simple scalar types. These types are used to provide architecture independence of the @@ -15,7 +16,7 @@ include: .. c:type:: time_t Hidden Interface Structures -*************************** +=========================== Several of the types used to interface with NuttX are structures that are intended to be hidden from the application. From the standpoint of @@ -33,7 +34,7 @@ specific elements within these hidden structures. These hidden structures will not be described further in this user's manual. Access to the ``errno`` Variable -******************************** +================================ A pointer to the thread-specific ``errno`` value is available through a function call: @@ -61,7 +62,7 @@ function call: :return: A pointer to the thread-specific ``errno`` value. User Interface Structures -************************* +========================= .. c:type:: int (*main_t)(int argc, char *argv[])