1/**
2@mainpage Introduction and configuration
3
4nrfx is a standalone set of drivers for peripherals present in Nordic
5Semiconductor's SoCs. It originated as an extract from the nRF5 SDK.
6The intention was to provide drivers that can be used in various environments
7without the necessity to integrate other parts of the SDK into them.
8For the user's convenience, the drivers come with the MDK package. This package
9contains definitions of register structures and bitfields for all supported
10SoCs, as well as startup and initialization files for them.
11
12Refer to the @ref nrfx_drv_supp_matrix to check which drivers are suitable
13for a given SoC.
14
15@section nrfx_integration Integration
16
17The purpose of nrfx is to make it possible to use the same set of peripheral
18drivers in various environments, from RTOSes to bare metal applications.
19Hence, for a given host environment, a light integration layer must be provided
20that implements certain specific routines, like interrupt management, critical
21sections, assertions, or logging. This is done by filling a predefined set of
22macros with proper implementations (or keeping some empty if desired) in files
23named:
24- @ref nrfx_glue
25- @ref nrfx_log
26
27Templates of these files are provided
28in the <a href="https://github.com/NordicSemiconductor/nrfx/tree/master/templates">nrfx/templates</a> subfolder. Their customized
29versions can be placed in any location within the host environment that the
30used compiler can access via include paths.
31
32In addition, the following locations should be specified as include paths
33([nrfx] stands for the nrfx root folder location):
34@code
35[nrfx]/
36[nrfx]/drivers/include
37[nrfx]/mdk
38@endcode
39
40@note Unless otherwise stated, nrfx API functions do not provide thread safety
41      themselves. Users are responsible for providing the proper synchronization
42      of the nrfx function calls in a given environment if those are to be used
43      from different contexts.
44
45@section nrfx_irq_handlers IRQ handlers
46
47The IRQ handlers in all drivers are implemented as ordinary API functions
48named "nrfx_*_irq_handler". They can be bound to some structures or called in
49a specific way according to the requirements of the host environment.
50To install the handlers in the standard MDK way, you must only add the following
51line to the @ref nrfx_glue file:
52
53@code
54#include <soc/nrfx_irqs.h>
55@endcode
56
57This will cause the preprocessor to properly rename all the IRQ handler
58functions so that the linker could install them in the vector table.
59
60@section nrfx_configuration Configuration
61
62The drivers use both dynamic (run time) and static (compile time) configuration.
63
64Dynamic configuration is done by specifying desired options in configuration
65structures passed to the drivers during their initialization.
66Refer to the API reference for a given driver to see the members of its
67configuration structure.
68
69Static configuration allows enabling and disabling (excluding their code from
70compilation) particular drivers or in some cases their specific features,
71defining default parameters for dynamic configuration, parametrization of
72logging in particular drivers. It is done by specifying desired values of macros
73in a file named:
74
75- nrfx_config.h
76
77This file, similarly to the integration files mentioned above, can be placed
78in any suitable location within the host environment.
79The <a href="https://github.com/NordicSemiconductor/nrfx/tree/master/templates">nrfx/templates</a> subfolder contains templates of
80configuration files for all currently supported Nordic SoCs. These files are
81included through a common nrfx_config.h file, according to the selected SoC.
82Refer to the "driver configuration" section in the API reference for a given
83driver for more information regarding configuration options available for it.
84
85@section nrfx_api_change_procedure API change procedure
86
87Starting from 3.0 release, nrfx API can no longer be considered as stable for minor version updates.
88Taking into account the potential impact on the end users, APIs are changed in a few stages.
89Every deprecated API is completely removed from the code base after two minor releases,
90counting from the one making the functionality obsolete.
91Refer to the <a href="https://github.com/NordicSemiconductor/nrfx/wiki/API-change-procedure">API change procedure</a>
92for more details regarding the process.
93
94@section nrfx_additional_reqs Additional requirements
95
96Nordic SoCs are based on ARM® Cortex™-M series processors. Before you can
97start developing with nrfx, you must add the CMSIS header files to include
98paths during the compilation process. Download these files from the following
99website:
100
101-  <a href="https://github.com/ARM-software/CMSIS"> ARM® CMSIS repository</a>
102(CMSIS/Include directory)
103*/
104