You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@nuttx.apache.org by ac...@apache.org on 2021/02/07 11:39:03 UTC
[incubator-nuttx] branch master updated: Documentation: introduce
hardware platforms documentation
This is an automated email from the ASF dual-hosted git repository.
acassis pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/incubator-nuttx.git
The following commit(s) were added to refs/heads/master by this push:
new 87596d7 Documentation: introduce hardware platforms documentation
87596d7 is described below
commit 87596d74ddc32ee7f559384cb9555da3e277973c
Author: Matias N <ma...@protobits.dev>
AuthorDate: Sat Feb 6 22:31:17 2021 -0300
Documentation: introduce hardware platforms documentation
---
Documentation/boards/index.rst | 14 --
Documentation/conf.py | 6 +-
Documentation/index.rst | 2 +-
Documentation/platforms/arm/index.rst | 11 ++
.../arm/nrf52/boards/nrf52832-mdk/index.rst | 45 +++++
.../arm/nrf52/boards/nrf52832-mdk/pinout.webp | Bin 0 -> 125938 bytes
Documentation/platforms/arm/nrf52/index.rst | 181 +++++++++++++++++++++
Documentation/platforms/index.rst | 13 ++
Documentation/platforms/risc-v/bl602/index.rst | 12 ++
Documentation/platforms/risc-v/index.rst | 11 ++
Documentation/platforms/xtensa/esp32/index.rst | 14 ++
Documentation/platforms/xtensa/index.rst | 11 ++
NOTICE | 6 +
boards/arm/nrf52/nrf52832-mdk/README.txt | 6 -
14 files changed, 308 insertions(+), 24 deletions(-)
diff --git a/Documentation/boards/index.rst b/Documentation/boards/index.rst
deleted file mode 100644
index 7c3f711..0000000
--- 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 </introduction/supported_platforms>`).
-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 b1780a0..fef4b07 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 832c250..e6240b3 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 0000000..bb7d542
--- /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 0000000..b8d29ee
--- /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 <https://wiki.makerdiary.co/nrf52832-mdk>`_.
+
+.. 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 0000000..52683a3
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 0000000..fee6e80
--- /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 <https://developer.nordicsemi.com/nRF_Connect_SDK/doc/latest/nrfxlib/softdevice_controller/README.html>`_, 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 0000000..5915230
--- /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 0000000..3e3b017
--- /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 0000000..fea13cd
--- /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 0000000..c6ccd60
--- /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 0000000..fcf2f5a
--- /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 43aaa58..b7f4c94 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 a58e091..0000000
--- 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
-
-