nrfx 2.5.0 release

NordicSemiconductor · May 5, 2021 · 7eca6c2 · 7eca6c2
1 parent c7c5127
commit 7eca6c2
Show file tree

Hide file tree

Showing 479 changed files with 7,871 additions and 4,089 deletions.
diff --git a/.gitignore b/.gitignore
@@ -1,2 +1,4 @@
 doc/html/*
+doc/html_sphinx/*
+doc/xml/*
 doc/warnings_nrfx.txt
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,6 +1,32 @@
 # Changelog
 All notable changes to this project are documented in this file.
 
+## [2.5.0] - 2021-05-05
+### Added
+- Added support for double-buffered transfers in the QSPI driver.
+- Added support for one-by-one channel configuration in the SAADC driver.
+- Added critical sections for channel allocation and deallocation in the DPPI driver.
+- Added support for generating documentation in the RST format using Sphinx tool.
+- Added high-drive pin configuration in the QSPI, TWIM, and SPIM drivers.
+- Added report period setting of 1 sample in the QDEC HAL.
+- Implemented workaround for nRF53 Series anomaly 121 in the QSPI driver.
+
+### Changed
+- Updated MDK to version 8.40.2.
+- Removed implicit channel deallocation during initialization in the GPIOTE driver.
+- Restricted pins that are supported for specific configuration on nRF5340 in the QSPI, TWIM, and SPIM drivers.
+- Aligned IRQ handler symbols to new naming scheme for nRF53 Series.
+
+### Fixed
+- Fixed register access sequence in the COMP driver.
+- Fixed memory corruption when uninitialized channel was freed in the GPIOTE driver.
+- Fixed spurious access of DCX pin for every instance of the peripheral when extended features were enabled in the SPIM driver.
+- Fixed overwrite of MCUSEL configuration in the nrf_gpio_cfg() function.
+- Fixed driver behavior for zero-length transfer in the TWIM driver.
+- Fixed internal state handling when transfer is aborted before finishing in the TWI and TWIM drivers.
+- Corrected assertions for MPS requirements in the USBD driver.
+- Corrected symbol describing maximum data payload for a full-speed isochronous endpoint in the USBD driver.
+
 ## [2.4.0] - 2020-11-13
 ### Added
 - Added the channel allocator feature in the GPIOTE driver.

diff --git a/LICENSE b/LICENSE
@@ -1,6 +1,8 @@
-Copyright (c) 2017 - 2020, Nordic Semiconductor ASA
+Copyright (c) 2017 - 2021, Nordic Semiconductor ASA
 All rights reserved.
 
+SPDX-License-Identifier: BSD-3-Clause
+
 Redistribution and use in source and binary forms, with or without
 modification, are permitted provided that the following conditions are met:
 

diff --git a/README.md b/README.md
@@ -42,6 +42,4 @@ SoCs, as well as startup and initialization files for them.
 
 nrfx documentation is available in the `doc\html` folder of the release package.
 
-You can also generate documentation yourself from the source code. To do it, install doxygen
-and run one of the scripts: `generate_html_doc.bat` or `generate_html_doc.sh`. Generated
-documentation will be stored in the `doc\html` directory. Use `index.html` to open it.
+Refer to [this guide](doc/README.md) for more details.
diff --git a/doc/README.md b/doc/README.md
@@ -0,0 +1,44 @@
+# nrfx documentation
+
+## Doxygen
+
+You can generate `doxygen` based documentation by running
+
+```shell
+doxygen nrfx.doxyfile
+```
+
+You may want to use the provided scripts `generate_html_doc.sh` or
+`generate_html_doc.bat`. The result can be viewed by opening
+`html/index.html`.
+
+## Sphinx
+
+All the necessary files to compile the Sphinx based documentation for `nrfx`
+are located under `sphinx` folder. As of today the content should match with
+the one produced using `doxygen` only.
+
+### Requirements
+
+You will need to have Python 3 installed as well as some dependencies, which can
+be installed by running:
+
+```shell
+pip install -r requirements.txt
+```
+
+### Build
+
+You may want to use the provided scripts `generate_sphinx_doc.sh` or
+`generate_sphinx_doc.bat`. The result can be viewed by opening
+`html_sphinx/index.html`.
+
+If you want to do it manually you can run the following commands from `doc`
+directory:
+
+```shell
+# compile doxygen documentation (required to generate XML metadata)
+doxygen nrfx.doxyfile
+# compile Sphinx documentation
+sphinx-build -b html sphinx html_sphinx
+```
diff --git a/doc/drv_supp_matrix.dox b/doc/drv_supp_matrix.dox
@@ -45,7 +45,6 @@ The following matrix provides a comparative overview of which drivers are suppor
 | @ref nrf_qdec    |@tagGreenTick |@tagGreenTick |@tagGreenTick      |@tagGreenTick |@tagGreenTick |@tagGreenTick |@tagGreenTick |@tagGreenTick |@tagRedCross  |
 | @ref nrf_qspi    |@tagRedCross  |@tagRedCross  |@tagRedCross       |@tagRedCross  |@tagRedCross  |@tagRedCross  |@tagGreenTick |@tagGreenTick |@tagRedCross  |
 | @ref nrf_radio   |@tagGreenTick |@tagGreenTick |@tagGreenTick      |@tagGreenTick |@tagGreenTick |@tagGreenTick |@tagGreenTick |@tagGreenTick |@tagRedCross  |
-| @ref nrf_reset   |@tagRedCross  |@tagRedCross  |@tagRedCross       |@tagRedCross  |@tagRedCross  |@tagRedCross  |@tagRedCross  |@tagGreenTick |@tagRedCross  |
 | @ref nrf_rng     |@tagGreenTick |@tagGreenTick |@tagGreenTick      |@tagGreenTick |@tagGreenTick |@tagGreenTick |@tagGreenTick |@tagGreenTick |@tagRedCross  |
 | @ref nrf_rtc     |@tagGreenTick |@tagGreenTick |@tagGreenTick      |@tagGreenTick |@tagGreenTick |@tagGreenTick |@tagGreenTick |@tagGreenTick |@tagGreenTick |
 | @ref nrf_saadc   |@tagRedCross  |@tagGreenTick |@tagGreenTick      |@tagRedCross  |@tagGreenTick |@tagGreenTick |@tagGreenTick |@tagGreenTick |@tagGreenTick |

diff --git a/doc/generate_html_doc.bat b/doc/generate_html_doc.bat
@@ -1,2 +1,2 @@
-del html\*.* /Q
+del html\*.* xml\*.* /Q
 doxygen nrfx.doxyfile
diff --git a/doc/generate_html_doc.sh b/doc/generate_html_doc.sh
@@ -1,2 +1,2 @@
-rm -rf html
+rm -rf html xml
 doxygen nrfx.doxyfile
diff --git a/doc/generate_sphinx_doc.bat b/doc/generate_sphinx_doc.bat
@@ -0,0 +1,3 @@
+del html\*.* xml\*.* html_sphinx\*.* /Q
+doxygen nrfx.doxyfile
+sphinx-build -b html sphinx html_sphinx
diff --git a/doc/generate_sphinx_doc.sh b/doc/generate_sphinx_doc.sh
@@ -0,0 +1,3 @@
+rm -rf html xml html_sphinx
+doxygen nrfx.doxyfile
+sphinx-build -b html sphinx html_sphinx
diff --git a/doc/main_page.dox b/doc/main_page.dox
@@ -37,9 +37,10 @@ In addition, the following locations should be specified as include paths
 [nrfx]/mdk
 @endcode
 
-@note nrfx API functions do not provide thread safety themselves. Users are responsible
-      for providing the proper synchronization of the nrfx function calls in a given environment
-      if those are to be used from different contexts.
+@note Unless otherwise stated, nrfx API functions do not provide thread safety
+      themselves. Users are responsible for providing the proper synchronization
+      of the nrfx function calls in a given environment if those are to be used
+      from different contexts.
 
 @section nrfx_irq_handlers IRQ handlers
 

diff --git a/doc/nrf5340.dox b/doc/nrf5340.dox
@@ -60,8 +60,6 @@ For a complete overview, see @ref nrfx_drv_supp_matrix.
 
 @ref nrf_radio
 
-@ref nrf_reset
-
 @ref nrf_rng
 
 @ref nrf_rtc

diff --git a/doc/nrfx.doxyfile b/doc/nrfx.doxyfile
@@ -40,7 +40,7 @@ PROJECT_NAME           = "nrfx"
 
 ### EDIT THIS ###
 
-PROJECT_NUMBER         = "2.4"
+PROJECT_NUMBER         = "2.5"
 
 # Using the PROJECT_BRIEF tag one can provide an optional one line description
 # for a project that appears at the top of each page and should give viewer a
@@ -235,8 +235,9 @@ TAB_SIZE               = 4
 # newlines (in the resulting output). You can put ^^ in the value part of an
 # alias to insert a newline as if a physical newline was in the original file.
 
-ALIASES                = tagGreenTick="@htmlonly<CENTER><font color=\"green\">✔</font></CENTER>@endhtmlonly" \
-                         tagRedCross="@htmlonly<CENTER><font color=\"red\">✖</font></CENTER>@endhtmlonly"
+ALIASES                = "tagGreenTick=\htmlonly<CENTER><font color=\"green\">✔</font></CENTER>\endhtmlonly \xmlonly<verbatim>embed:rst:inline :green:`✔`</verbatim>\endxmlonly" \
+                         "tagRedCross=\htmlonly<CENTER><font color=\"red\">✖</font></CENTER>\endhtmlonly \xmlonly<verbatim>embed:rst:inline :red:`✖`</verbatim>\endxmlonly" \
+                         "nRF5340pinAssignmentsURL=\"https://infocenter.nordicsemi.com/index.jsp?topic=%2Fps_nrf5340%2Fchapters%2Fpin.html\""
 
 # This tag can be used to specify a number of word-keyword mappings (TCL only).
 # A mapping has the form "name=value". For example adding "class=itcl::class"
@@ -1932,7 +1933,7 @@ MAN_LINKS              = NO
 # captures the structure of the code including all documentation.
 # The default value is: NO.
 
-GENERATE_XML           = NO
+GENERATE_XML           = YES
 
 # The XML_OUTPUT tag is used to specify where the XML pages will be put. If a
 # relative path is entered the value of OUTPUT_DIRECTORY will be put in front of

diff --git a/doc/nrfx_api.dox b/doc/nrfx_api.dox
@@ -69,8 +69,6 @@
 
 @defgroup nrf_radio RADIO
 
-@defgroup nrf_reset RESET
-
 @defgroup nrf_rng RNG
 
 @defgroup nrf_rtc RTC

diff --git a/doc/sphinx/_static/css/nrfx.css b/doc/sphinx/_static/css/nrfx.css
@@ -0,0 +1,3 @@
+:root {
+    --docset-color: #412ee8;
+}
diff --git a/doc/sphinx/api_reference.rst b/doc/sphinx/api_reference.rst
@@ -0,0 +1,7 @@
+API Reference
+=============
+
+.. toctree::
+
+    drivers/index
+    nrfx_api/index
diff --git a/doc/sphinx/changelog.rst b/doc/sphinx/changelog.rst
@@ -0,0 +1 @@
+.. mdinclude:: ../../CHANGELOG.md
diff --git a/doc/sphinx/conf.py b/doc/sphinx/conf.py
@@ -0,0 +1,51 @@
+#!/usr/bin/env python3
+
+from pathlib import Path
+import re
+
+
+CONF_DIR = Path(__file__).absolute().parent
+"""conf.py directory."""
+
+with open(CONF_DIR / ".." / "nrfx.doxyfile") as f:
+    VERSION = re.search(r'PROJECT_NUMBER\s+=\s+"(.*)"', f.read()).group(1)
+
+# General configuration --------------------------------------------------------
+
+project = "nrfx"
+copyright = "2021, Nordic Semiconductor ASA"
+author = "Nordic Semiconductor"
+version = VERSION
+
+extensions = ["breathe", "m2r2"]
+source_suffix = {
+    ".rst": "restructuredtext",
+    ".md": "markdown"
+}
+master_doc = "index"
+exclude_patterns = ["theme"]
+
+# Options for HTML output ------------------------------------------------------
+
+html_theme = "sphinx_ncs_theme"
+html_static_path = [str(CONF_DIR / "_static")]
+html_last_updated_fmt = "%b %d, %Y"
+html_show_sphinx = False
+
+# Options for Breathe ----------------------------------------------------------
+
+breathe_projects = {"nrfx": str(CONF_DIR / ".." / "xml")}
+breathe_default_project = "nrfx"
+breathe_domain_by_extension = {"h": "c", "c": "c"}
+breathe_separate_member_pages = True
+
+c_id_attributes = [
+    "NRF_STATIC_INLINE",
+    "NRFX_STATIC_INLINE",
+    "__STATIC_INLINE",
+]
+cpp_id_attributes = c_id_attributes
+
+
+def setup(app):
+    app.add_css_file("css/nrfx.css")
diff --git a/doc/sphinx/drivers/aar/hal.rst b/doc/sphinx/drivers/aar/hal.rst
@@ -0,0 +1,6 @@
+AAR HAL
+=======
+
+.. doxygengroup:: nrf_aar_hal
+   :project: nrfx
+   :members:
diff --git a/doc/sphinx/drivers/aar/index.rst b/doc/sphinx/drivers/aar/index.rst
@@ -0,0 +1,9 @@
+AAR
+===
+
+.. doxygengroup:: nrf_aar
+
+.. toctree::
+   :glob:
+
+   *
diff --git a/doc/sphinx/drivers/acl/hal.rst b/doc/sphinx/drivers/acl/hal.rst
@@ -0,0 +1,6 @@
+ACL HAL
+=======
+
+.. doxygengroup:: nrf_acl_hal
+   :project: nrfx
+   :members:
diff --git a/doc/sphinx/drivers/acl/index.rst b/doc/sphinx/drivers/acl/index.rst
@@ -0,0 +1,9 @@
+ACL
+===
+
+.. doxygengroup:: nrf_acl
+
+.. toctree::
+   :glob:
+
+   *
diff --git a/doc/sphinx/drivers/adc/driver.rst b/doc/sphinx/drivers/adc/driver.rst
@@ -0,0 +1,6 @@
+ADC driver
+==========
+
+.. doxygengroup:: nrfx_adc
+   :project: nrfx
+   :members:
diff --git a/doc/sphinx/drivers/adc/hal.rst b/doc/sphinx/drivers/adc/hal.rst
@@ -0,0 +1,6 @@
+ADC HAL
+=======
+
+.. doxygengroup:: nrf_adc_hal
+   :project: nrfx
+   :members:
diff --git a/doc/sphinx/drivers/adc/index.rst b/doc/sphinx/drivers/adc/index.rst
@@ -0,0 +1,9 @@
+ADC
+===
+
+.. doxygengroup:: nrf_adc
+
+.. toctree::
+   :glob:
+
+   *
diff --git a/doc/sphinx/drivers/bprot/hal.rst b/doc/sphinx/drivers/bprot/hal.rst
@@ -0,0 +1,6 @@
+BPROT HAL
+=========
+
+.. doxygengroup:: nrf_bprot_hal
+   :project: nrfx
+   :members:
diff --git a/doc/sphinx/drivers/bprot/index.rst b/doc/sphinx/drivers/bprot/index.rst
@@ -0,0 +1,9 @@
+BPROT
+=====
+
+.. doxygengroup:: nrf_bprot
+
+.. toctree::
+   :glob:
+
+   *
diff --git a/doc/sphinx/drivers/cache/hal.rst b/doc/sphinx/drivers/cache/hal.rst
@@ -0,0 +1,6 @@
+CACHE HAL
+=========
+
+.. doxygengroup:: nrf_cache_hal
+   :project: nrfx
+   :members:
diff --git a/doc/sphinx/drivers/cache/index.rst b/doc/sphinx/drivers/cache/index.rst
@@ -0,0 +1,9 @@
+CACHE
+=====
+
+.. doxygengroup:: nrf_cache
+
+.. toctree::
+   :glob:
+
+   *
diff --git a/doc/sphinx/drivers/ccm/hal.rst b/doc/sphinx/drivers/ccm/hal.rst
@@ -0,0 +1,6 @@
+CCM HAL
+=======
+
+.. doxygengroup:: nrf_ccm_hal
+   :project: nrfx
+   :members:
diff --git a/doc/sphinx/drivers/ccm/index.rst b/doc/sphinx/drivers/ccm/index.rst
@@ -0,0 +1,9 @@
+CCM
+===
+
+.. doxygengroup:: nrf_ccm
+
+.. toctree::
+   :glob:
+
+   *
diff --git a/doc/sphinx/drivers/clock/driver.rst b/doc/sphinx/drivers/clock/driver.rst
@@ -0,0 +1,6 @@
+CLOCK driver
+============
+
+.. doxygengroup:: nrfx_clock
+   :project: nrfx
+   :members:
diff --git a/doc/sphinx/drivers/clock/hal.rst b/doc/sphinx/drivers/clock/hal.rst
@@ -0,0 +1,6 @@
+CLOCK HAL
+=========
+
+.. doxygengroup:: nrf_clock_hal
+   :project: nrfx
+   :members:
diff --git a/doc/sphinx/drivers/clock/index.rst b/doc/sphinx/drivers/clock/index.rst
@@ -0,0 +1,10 @@
+CLOCK
+=====
+
+.. doxygengroup:: nrf_clock
+
+.. toctree::
+   :glob:
+
+   *
+   ../oscillators/hal.rst