diff --git a/Documentation/boards/index.rst b/Documentation/boards/index.rst deleted file mode 100644 index 7c3f711e89..0000000000 --- a/Documentation/boards/index.rst +++ /dev/null @@ -1,14 +0,0 @@ -.. todo:: - Include a full list of supported boards, organized by architecture / family / vendor. - Each board should have its own entry, a photo, brief hardware specifications, features - supported (currently working in NuttX), how to flash, special toolchains required, etc. - This will involve migrating most of the content existing currently in board README files - to RST documents here. - -Supported Boards -================ - -NuttX supports a large number of boards (see :doc:`here `). -At the moment, the documentation available is in the form of README files inside each subdirectory -of ``boards`` directory of main NuttX repository. - diff --git a/Documentation/conf.py b/Documentation/conf.py index b1780a034d..fef4b074bb 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -93,9 +93,9 @@ html_theme = 'sphinx_rtd_theme' html_show_sphinx = False -#html_theme_options = { -# 'prev_next_buttons_location': None -#} +html_theme_options = { + 'navigation_depth': 5 +} # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, diff --git a/Documentation/index.rst b/Documentation/index.rst index 832c250c89..e6240b3866 100644 --- a/Documentation/index.rst +++ b/Documentation/index.rst @@ -23,7 +23,7 @@ Last Updated: |today| introduction/index.rst quickstart/index.rst introduction/inviolables.rst - boards/index.rst + platforms/index.rst components/index.rst applications/index.rst reference/index.rst diff --git a/Documentation/platforms/arm/index.rst b/Documentation/platforms/arm/index.rst new file mode 100644 index 0000000000..bb7d542173 --- /dev/null +++ b/Documentation/platforms/arm/index.rst @@ -0,0 +1,11 @@ +=== +ARM +=== + +The following ARM SoC are supported: + +.. toctree:: + :maxdepth: 1 + :glob: + + */* diff --git a/Documentation/platforms/arm/nrf52/boards/nrf52832-mdk/index.rst b/Documentation/platforms/arm/nrf52/boards/nrf52832-mdk/index.rst new file mode 100644 index 0000000000..b8d29ee2b7 --- /dev/null +++ b/Documentation/platforms/arm/nrf52/boards/nrf52832-mdk/index.rst @@ -0,0 +1,45 @@ +======================= +MakerDiary nRF52832-MDK +======================= + +The nRF52832-MDK is a development board for the nRF52832 SoC from Nordic. It features 24 I/Os +an on-board RGB led and a chip antenna. It also includes an embedded DAPlink debugger which +allows to flash/debug and monitor UART from the USB port. + +More information about this board can be found at `MakerDiary wiki `_. + +.. figure:: pinout.webp + :align: center + + Pinout diagram + +.. tip:: Pins P0.19 and P0.20 correspond to UART RX/TX (from nRF52 perspective) which are connected + to the embedded debugger. + +Resources +========= + +The nRF52832 chip has 512K of FLASH and 64K of RAM. + +Configurations +============== + +nsh +--- + +Basic NuttShell configuration (console enabled in UART0, exposed via USB connection, at 115200 bps). + +sdc +--- + +Enables Nordic's SoftDevice controller and uses nimBLE for the host-layer. +The ``nimble`` test application can be used to enable a simple GATT server. + +Flash & Debug +============= + +Both flashing and debugging are done using the embedded DAPlink debugger. OpenOCD can be invoked +in the following way to flash:: + + openocd -f interface/cmsis-dap.cfg -f target/nrf52.cfg -c "program nuttx/nuttx.bin 0x0000000 verify reset; shutdown" + diff --git a/Documentation/platforms/arm/nrf52/boards/nrf52832-mdk/pinout.webp b/Documentation/platforms/arm/nrf52/boards/nrf52832-mdk/pinout.webp new file mode 100644 index 0000000000..52683a37bd Binary files /dev/null and b/Documentation/platforms/arm/nrf52/boards/nrf52832-mdk/pinout.webp differ diff --git a/Documentation/platforms/arm/nrf52/index.rst b/Documentation/platforms/arm/nrf52/index.rst new file mode 100644 index 0000000000..fee6e80327 --- /dev/null +++ b/Documentation/platforms/arm/nrf52/index.rst @@ -0,0 +1,181 @@ +============ +Nordic nRF52 +============ + +The nRF52 series of chips from Nordic Semiconductor are based around an ARM Cortex-M4 core running +at 64 MHz and feature Bluetooth Low Energy (BLE) support. + +Clock Configuration +=================== + +Clock settings are handled via Kconfig options, which determines whether to start external crystal +for the HFCLK, whether to start the LFCLK and which oscillator to use. + +System Timer +============ + +The clock used for providing system time can be chosen via Kconfig. You can choose to use ARM SysTick +or use RTC in tickless mode. + +Regulator Control +================= + +DC/DC regulator can be made to be enabled at boot via Kconfig. + +Peripheral Support +================== + +The following list indicates peripherals supported in NuttX: + +========== ======= ===== +Peripheral Support Notes +========== ======= ===== +GPIO Yes +GPIOTE Yes +I2S No +MWU No +NFCT No +PDM No +PPI Yes +PWM Yes +QDEC No +QSPI No +RADIO Yes Basic +RNG Yes +RTC Yes +SAADC Yes +SPIM Yes +SPIS No +TEMP No +TIMER Yes +TWIM Yes +TWIS No +UART Yes +UARTE No +USBD No +WDT Yes +========== ======= ===== + +Peripherals such as AAR, ACL, CCM, ECB are not directly used by NuttX since they +are part of BLE controller implementation (link). + +GPIO/GPIOTE +----------- + +Pins can be configured/operated using ``nrf52_gpio_*`` functions. Interrupts are +handled via the GPIOTE peripheral in one of two ways: via a GPIOTE channel or via +PORT events. The former allows for simultaneous rising/falling edge-sensitive interrupts +per-pin. However, as there are a limited number of channels (and sometimes these +are used by some drivers for specific tasks), it may not always be possible to use +this mechanism. The latter approach for pin interrupts is via the PORT event, determined +by pin state on a their corresponding GPIO port. This is related to the SENSE capability +of pins, which can only be set to either rising or falling edge sensing. + +Depending on ``CONFIG_NRF52_PER_PIN_INTERRUPTS`` option, you can set a callback for +the PORT event itself or you can set a callback for a given pin. In the latter case +the driver scans for pins with DETECT bit high and calls the configured callback +automatically. + +Finally, GPIOTE can also be used to configure a channel in *task mode*, which allows to +control pin state via tasks/events. + +ADC +--- + +The SAADC peripheral is exposed via standard ADC driver. The lower-half of this driver +is initialized by calling :c:func:`nrf52_adcinitialize`. + +I2C +--- + +I2C is supported both in polling and interrupt mode (via EasyDMA). + +.. note:: The I2C peripheral does not support sending two transfers without sending + a START nor RSTART. For this reason, this is supported via an internal buffer where + messages will be first copied to and sent together. + +The lower-half of I2C bus is initialized by :c:func:`nrf52_i2cbus_initialize`. +There's also a software (bitbang) I2C implementation for nRF52. The lower-half is +initialized via :c:func:`nrf52_i2c_bitbang_initialize`. + +SPI +--- + +SPI is supported both in polling and interrupt-based (via EasyDMA) mode. The latter +supports arbitrarily long transfers using Nordic's list-mode EasyDMA (intermediate +transfers are currently still manually started). + +It is possible to use SPI without either MOSI/MISO pin defined by simply not providing +the relevant ``BOARD_SPI*_MISO/MOSI_PIN`` definition. + +This implementation support power management hooks, which will disable SPI peripheral when +entering either SLEEP or STANDBY modes and reconfigure it when going back to NORMAL mode. + +UART +---- + +UART is implemented using polling. UARTE EasyDMA feature is not yet supported. +This may introduce a large number of interrupts which may be undesireable. + +PPI +--- + +The PPI peripheral is supported via a specific API which lets you control the EVENT +and TASKs to trigger, both for individual and grouped channels. + +When using channels, you should consider that some peripherals may use PPI internally +and some may be unavailable for further use. As a helper, if debug assertions are +enabled, calls to PPI API will check for a channel to actually be disabled when being +enabled and viceversa. This may help catch collisions in PPI use. + +PWM +--- + +PWM is supported via standard driver. This means that more advanced features such as +complex sequences or waveform modes are not yet supported. + +RNG +--- + +The RNG peripheral will be used to register a random/urandom device automatically, when +enabled. + +TIMER +----- + +The TIMER peripheral is exposed as standard timer. + +RTC +--- + +The RTC peripheral is exposed as a standard timer, since it is really a low-power +timer, without any date handling capabilities. + +WDT +--- + +The watchdog is supported via low-level API interface and also via standard watchdog +driver. The driver is written so as to handle an already running watchdog, which may +have been set by a bootloader. + +BLE Support +=========== + +BLE is supported in nRF52 using Nordic's `SoftDevice Controller `_, using HCI interface. To enable BLE support +you need to call :c:func:`nrf52_sdc_initialize` on boot, which will initialize the BLE controller. + +SDC support involves registering various high-priority zero-latency interrupts and thus requires +enabling BASEPRI and high-priority interrupt support. On supported boards, a sample ``sdc`` configuration +is provided with settings already set. + +Note that in this case, some peripherals (mostly those related to BLE) will be unavailable. Some PPI +channels will also be ocuppied (``NRF52_PPI_NUM_CONFIGURABLE_CHANNELS`` will be set accordingly in this case). + +Supported Boards +================ + +.. toctree:: + :glob: + :maxdepth: 1 + + boards/*/* diff --git a/Documentation/platforms/index.rst b/Documentation/platforms/index.rst new file mode 100644 index 0000000000..59152303a6 --- /dev/null +++ b/Documentation/platforms/index.rst @@ -0,0 +1,13 @@ +=================== +Supported Platforms +=================== + +The following is a list of architectures, System-on-Chip +series and boards supported in NuttX: + +.. toctree:: + :glob: + :maxdepth: 3 + :titlesonly: + + */* diff --git a/Documentation/platforms/risc-v/bl602/index.rst b/Documentation/platforms/risc-v/bl602/index.rst new file mode 100644 index 0000000000..3e3b01738a --- /dev/null +++ b/Documentation/platforms/risc-v/bl602/index.rst @@ -0,0 +1,12 @@ +================== +Bouffalo Lab BL602 +================== + +Toolchain +========= + +OpenOCD +------- + +Peripheral Support +================== diff --git a/Documentation/platforms/risc-v/index.rst b/Documentation/platforms/risc-v/index.rst new file mode 100644 index 0000000000..fea13cd68a --- /dev/null +++ b/Documentation/platforms/risc-v/index.rst @@ -0,0 +1,11 @@ +====== +RISC-V +====== + +The following RISC-V SoCs are supported in NuttX: + +.. toctree:: + :glob: + :maxdepth: 1 + + */* diff --git a/Documentation/platforms/xtensa/esp32/index.rst b/Documentation/platforms/xtensa/esp32/index.rst new file mode 100644 index 0000000000..c6ccd60718 --- /dev/null +++ b/Documentation/platforms/xtensa/esp32/index.rst @@ -0,0 +1,14 @@ +=============== +Espressif ESP32 +=============== + +Toolchain +========= + +OpenOCD +------- + +Peripheral Support +================== + + diff --git a/Documentation/platforms/xtensa/index.rst b/Documentation/platforms/xtensa/index.rst new file mode 100644 index 0000000000..fcf2f5af50 --- /dev/null +++ b/Documentation/platforms/xtensa/index.rst @@ -0,0 +1,11 @@ +====== +Xtensa +====== + +The following Xtensa SoC are supported: + +.. toctree:: + :maxdepth: 1 + :glob: + + */* diff --git a/NOTICE b/NOTICE index 43aaa58e02..b7f4c944fd 100644 --- a/NOTICE +++ b/NOTICE @@ -58,3 +58,9 @@ NXP Restriction for SPIFI code is used in conjunction with NXP Semiconductors microcontrollers. This copyright, permission, and disclaimer notice must appear in all copies of this code. + +Documentation +============= + +- nRF52832-MDK board pinout image is obtained from MakerDiary GitHub repository, + under the terms of the MIT license, Copyright (c) 2019 makerdiary.com diff --git a/boards/arm/nrf52/nrf52832-mdk/README.txt b/boards/arm/nrf52/nrf52832-mdk/README.txt deleted file mode 100644 index a58e091318..0000000000 --- a/boards/arm/nrf52/nrf52832-mdk/README.txt +++ /dev/null @@ -1,6 +0,0 @@ -MakerDiary nRF52832 MDK -======================= - -https://makerdiary.com/collections/frontpage/products/nrf52832-mdk-iot-micro-development-kit - -