From b7f94fbf22f11bb7ba03bfecd023efdc8a1efc75 Mon Sep 17 00:00:00 2001 From: raiden00pl Date: Sun, 29 Oct 2023 16:40:32 +0100 Subject: [PATCH] Documentation: various cosmetic changes --- .../components/drivers/character/analog.rst | 2 +- Documentation/components/drivers/index.rst | 10 +++++----- Documentation/components/libs/index.rst | 1 - Documentation/contributing/index.rst | 1 + Documentation/contributing/making-changes.rst | 9 +++++---- Documentation/contributing/workflow.rst | 1 + Documentation/guides/coredump.rst | 4 ++-- Documentation/guides/cpp_cmake.rst | 7 ++++--- Documentation/guides/customapps.rst | 9 +++------ Documentation/guides/customboards.rst | 5 ++--- Documentation/guides/drivers.rst | 11 ++++++----- Documentation/guides/gdbwithpython.rst | 4 ++-- Documentation/guides/index.rst | 1 + Documentation/guides/ofloader.rst | 2 +- Documentation/guides/pysimcoder.rst | 7 ++++--- Documentation/guides/qemugdb.rst | 7 ++++--- Documentation/guides/rndis.rst | 7 ++++--- Documentation/guides/simulator.rst | 13 +++++++------ Documentation/introduction/index.rst | 1 + Documentation/introduction/resources.rst | 1 + Documentation/quickstart/configuring.rst | 7 ++++--- Documentation/reference/os/newreno.rst | 1 - Documentation/reference/user/02_task_scheduling.rst | 5 +++-- Documentation/reference/user/06_clocks_timers.rst | 3 ++- Documentation/reference/user/07_signals.rst | 3 ++- Documentation/reference/user/12_shared_memory.rst | 5 +++-- Documentation/reference/user/structures.rst | 9 +++++---- 27 files changed, 74 insertions(+), 62 deletions(-) diff --git a/Documentation/components/drivers/character/analog.rst b/Documentation/components/drivers/character/analog.rst index bbdad04e704..c8f8c754600 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 bb2c00dd3c0..03bb7cc902f 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 8ae74d32986..3ef511cc3b8 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 985fe77e14c..79ffe661b62 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 7198081a263..692402bf206 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 5c7aca86dc7..743246c455a 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 1875e442df0..a2311191988 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 5ac464ce455..71948e73008 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 03df67705f2..f2930f47044 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 d9eab5edb6d..95c21b0d5b8 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 8d7d78a4cb2..69ad84343ee 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 469d44f2b85..2f1d895b0d4 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 1eceb6c57bf..e0f1d31b41e 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 9946cd87948..743fb9d1328 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 d66c2757332..991c802363c 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 72214564bf3..488953960f6 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 58430f588b0..77813edcd01 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 17b3b5f9f1d..a7ee735c5fe 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 d61e2e7bcb0..d16efdf41bb 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 68524cca767..b4bdf950546 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 5add3d67488..4ff425885cf 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 7f238e5a60c..21a0a2b35f8 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 4d989d12a1c..3a1ae8e9660 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 d158cd1b54d..a67fc0cb2dc 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 b7338138632..185e31e7856 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 ee1eafdef7d..7d9d63faecf 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 73df918c617..872fd58066a 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[])