| Version |
Description |
| 2.7.0 |
Modifications compared to Version 2.6.0:
- Added WiFi Interface API 1.0.0-beta.
- Added custom driver selection to simplify implementation of new CMSIS-Driver.
|
| 2.6.0 |
Modifications compared to Version 2.05:
- Enhanced CAN-Driver API with explicit BUSOFF state.
- Enhanced NAND-Driver API for ECC handling.
|
| 2.05 |
Modifications compared to Version 2.04:
- Changed: All typedefs related to status have been made volatile.
|
| 2.04 |
Modifications compared to Version 2.03:
- Added: template files for CAN interface driver.
|
| 2.03 |
Modifications compared to Version 2.02:
- Added: CAN API for an interface to CAN peripherals
- Added: Overview of the \ref driverValidation "CMSIS-Driver Validation" Software Pack.
- Enhanced: documentation and clarified behavior of the \ref CallSequence.
|
| 2.02 |
Modifications compared to Version 2.00:
- Minor API changes, for exact details refer to the header file of each driver.
- Added: Flash Interface, NAND interface.
|
| 2.00 |
API with non-blocking data transfer, independent of CMSIS-RTOS. |
| 1.10 |
Initial release |
*/
/*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
/**
\page theoryOperation Theory of Operation
[TOC]
This section gives an overview of the general operation of CMSIS-Drivers. It explains the \ref DriverFunctions that are
common in all CMSIS-Drivers along with the \ref CallSequence. The topic \ref Data_Xfer_Functions describes how data
read/write operations to the peripheral are implemented.
Each CMSIS-Driver defines an \ref AccessStruct for calling the various driver functions and each peripheral (that is accessed
via a CMSIS-Driver) has one \ref DriverInstances "Driver Instance".
\section DriverFunctions Common Driver Functions
Each CMSIS-Driver contains these functions:
- \b GetVersion: can be called at any time to obtain version information of the driver interface.
- \b GetCapabilities: can be called at any time to obtain capabilities of the driver interface.
- \b Initialize: must be called before powering the peripheral using \b PowerControl. This function performs the following:
- allocate I/O resources.
- register an optional \b SignalEvent callback function.
- \b SignalEvent: is an optional callback function that is registered with the \b Initialize function. This callback
function is initiated from interrupt service routines and indicates hardware events or the completion of a data block
transfer operation.
- \b PowerControl: Controls the power profile of the peripheral and needs to be called after \b Initialize. Typically, three
power options are available:
- \c ARM_POWER_FULL: Peripheral is turned on and fully operational. The driver initializes the peripheral registers, interrupts, and (optionally) DMA.
- \c ARM_POWER_LOW: (optional) Peripheral is in low power mode and partially operational; usually, it can detect
external events and wake-up.
- \c ARM_POWER_OFF: Peripheral is turned off and not operational (pending operations are terminated). This is the state
after device reset.
- \b Uninitialize: Complementary function to Initialize. Releases the I/O pin resources used by the interface.
- \b Control: Several drivers provide a control function to configure communication parameters or execute miscellaneous
control functions.
The section \ref CallSequence contains more information on the operation of each function. Additional functions are specific
to each driver interface and are described in the individual sections of each driver.
\subsection ProcessorMode Cortex-M Processor Mode
The CMSIS-Driver functions access peripherals and interrupts and are designed to execute in \b Privileged mode.
When calling CMSIS-Driver functions from RTOS threads, it should be ensure that these threads execute in \b Privileged mode.
\section CallSequence Function Call Sequence
For normal operation of the driver, the API functions \b GetVersion, \b GetCapabilities, \b Initialize, \b PowerControl, \b Uninitialize are
called in the following order:
\msc
a [label="", textcolor="indigo", linecolor="indigo", arclinecolor="indigo"],
b [label="", textcolor="blue", linecolor="blue", arclinecolor="blue"];
a rbox a [label="Middleware", linecolor="indigo"],
b rbox b [label="Driver", linecolor="blue"];
--- [label="Verify API version"];
a=>b [label="GetVersion ()", textcolor="gray", linecolor="gray"];
--- [label="Obtain driver features"];
a=>b [label="GetCapabilities (...)", textcolor="gray", linecolor="gray"];
--- [label="Setup software resources"];
a=>b [label="Initialize (...)", textcolor="red", linecolor="red"];
--- [label="Setup the peripheral"];
a=>b [label="PowerControl (ARM_POWER_FULL)", textcolor="red", linecolor="red"];
--- [label="Operate with the peripheral"];
a=>b [label="Data Transfer Functions"];
a<=b [label="SignalEvent (...)"];
--- [label="Wait for external hardware events"];
a=>b [label="PowerControl (ARM_POWER_LOW)"];
a<=b [label="SignalEvent (...)"];
--- [label="Stop working with peripheral"];
a=>b [label="PowerControl (ARM_POWER_OFF)", textcolor="red", linecolor="red"];
a=>b [label="Uninitialize (...)", textcolor="red", linecolor="red"];
\endmsc
The functions \b GetVersion and \b GetCapabilities can be called any time to obtain the required information from the driver.
These functions return always the same information.
\subsection CS_start Start Sequence
To start working with a peripheral the functions \b Initialize and \b PowerControl need to be called in this order:
\code
drv->Initialize (...); // Allocate I/O pins
drv->PowerControl (ARM_POWER_FULL); // Power up peripheral, setup IRQ/DMA
\endcode
- \b Initialize typically allocates the I/O resources (pins) for the peripheral. The function can be called multiple times;
if the I/O resources are already initialized it performs no operation and just returns with \ref ARM_DRIVER_OK.
- \b PowerControl (\c ARM_POWER_FULL) sets the peripheral registers including interrupt (NVIC) and optionally DMA.
The function can be called multiple times; if the registers are already set it performs no operation and just returns with \ref ARM_DRIVER_OK.
\subsection CS_stop Stop Sequence
To stop working with a peripheral the functions \b PowerControl and \b Uninitialize need to be called in this order:
\code
drv->PowerControl (ARM_POWER_OFF); // Terminate any pending transfers, reset IRQ/DMA, power off peripheral
drv->Uninitialize (...); // Release I/O pins
\endcode
The functions \b PowerControl and \b Uninitialize always execute and can be used to put the peripheral into a