CMSIS Driver  Version 1.10 - Preliminary
Middleware Driver API for microcontroller peripherals
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Peripheral Driver Interfaces

Peripheral Driver Interfaces are implementations of published APIs. The APIs are Component Groups under the Device Class of a software component. Currently the CMSIS Pack publishes the Driver API Interface with one or more *.h header files and a documentation. It is intended to standardize these Peripheral Driver Interfaces as part of a future CMSIS release.

The actual implementation of each driver is provided in the Device Family Pack available for each microcontroller family. In a Device Family Pack the Device Class contains several software component Groups with Device Drivers for physical device peripherals that are typically used by middleware libraries.

Driver.png
Device Driver Interfaces and Configuration File

The following Device Driver interfaces are defined as API:

  • Ethernet: Interface to Ethernet MAC and PHY peripheral.
  • I2C: Multimaster Serial Single-Ended Bus interface driver.
  • MCI: Memory Card Interface for SD/MMC memory.
  • NAND: NAND Flash Memory interface driver.
  • NOR: NOR Flash Memory interface driver.
  • SPI: Serial Peripheral Interface Bus driver for 8-bit Master.
  • UART: Universal Asynchronous Receiver/Transmitter interface driver.
  • USB: USB driver interface for generic USB Host and Device communication.

A specific Device Driver API does not support every potential use-case of a peripheral type. For example the Device Driver API Group Ethernet is not suitable for the Precision Time Protocol defined in IEEE1588. In a similar way the Device API Group UART does not support SmartCard interfaces. However, the defined API interfaces support a wide range of use cases. It is possible to extend a Device class with further Device API Groups to cover new use-cases.

A Device Family Pack may contain additional Peripheral Driver Interfaces to extend the standard Device Driver API Groups defined by a future CMSIS standard. For example, other supporting Peripheral Driver Interfaces for Memory BUS, GPIO, or DMA may be part of the Device Family Pack and referenced by the implementation of the standard Device Driver API Groups.

Driver Functions

The driver implementations assumes the CMSIS-RTOS functionality and may use interrupts and DMA (direct memory access) available in the device. Each peripheral type that is accessed by a Driver publishes a struct that allows to access the functions of the driver. This struct type is named ARM_DRIVER_xxx and Function Access in the documentation.

Example: Function Access of the SPI driver

typedef struct _ARM_DRIVER_SPI {
ARM_DRV_VERSION (*GetVersion) (void);
ARM_SPI_CAPABILITIES (*GetCapabilities)(void);
ARM_SPI_STATUS (*Initialize) (ARM_SPI_SignalEvent_t cb_event);
ARM_SPI_STATUS (*Uninitialize) (void);
ARM_SPI_STATUS (*PowerControl) (ARM_POWER_STATE state);
ARM_SPI_STATUS (*Configure) (ARM_SPI_FRAME_FORMAT frame_format, ARM_SPI_BIT_ORDER bit_order);
uint32_t (*BusSpeed) (uint32_t bps);
ARM_SPI_STATUS (*SlaveSelect) (ARM_SPI_SS_SIGNAL state);
uint8_t (*TransferByte) (uint8_t out);
ARM_SPI_STATUS (*SendData) (const uint8_t *buf, uint32_t len);
ARM_SPI_STATUS (*ReceiveData) (uint8_t *buf, uint32_t len, uint8_t out);
ARM_SPI_STATUS (*AbortTransfer) (void);

A device may offer several peripherals of the same type. For such devices, a driver implementation publishes multiple instances of the driver access structure. The name of each driver instance reflects the names of the peripheral available in the device.

Example: SPI driver Function Access structs for 3 SPIs in a microcontroller device.

ARM_DRIVER_SPI ARM_Driver_SPI1; // access functions for SPI1 interface
ARM_DRIVER_SPI ARM_Driver_SPI2; // access functions for SPI2 interface
ARM_DRIVER_SPI ARM_Driver_SPI3; // access functions for SPI3 interface

For a device family, the drivers are configurable and all configuration options are stored in a central file with the name RTE_Device.h. This file contains also configuration settings for the processor and peripheral clock. The RTE_Device.h may contain control strings for the MDK Configuration Wizard. However, the RTE_Device.h file may be also configured with silicon vendor specific configuration utilities.

Each Function Access struct of a driver contains these functions:

  • GetVersion: can be called at any time to obtain version information of the driver interface.
  • GetCapabilities: can be called at any time to obtain capabilities of the driver interface.
  • Initialize: must be called first. Initializes the software resources used by the interface (clear variables, allocate memory, create CMSIS-RTOS objects, ...). Initialize may also register a SignalEvent callback function. Initialize leaves the peripheral in powered-off state.
  • SignalEvent: is an optional callback function registered by Initialize that is used to indicate hardware events or the completion of data block transfer operations.
  • PowerControl: Controls the power profile of the peripheral and may be called after Initialize. Typically three power options are available:
    • ARM_POWER_FULL: Peripheral is turned on and fully operational. The driver may initialize at that point the peripheral registers.
    • ARM_POWER_LOW: (optional) Peripheral is in low power mode and partially operational; usually it can detect external events and wake-up.
    • ARM_POWER_OFF: Peripheral is turned off and not operational (it will also stop any pending operations). This is also the state of the peripheral after device reset.
  • Uninitialize: Complementary function to Initialize. It will free all software resources used by the interface (de-allocate memory, release CMSIS-RTOS objects, ...).

Additional functions are specific to each driver interface and described in the individual sections of each driver.

Function Call Sequence

The driver API functions GetVersion, GetCapabilities, Initialize, PowerControl, Uninitialize are called in the following order:

msc_inline_mscgraph_3

Revision History

Version Description
1.10 Initial release