HAL

Modules
	Analogin hal functions
	Analogout hal functions
	Hardware CRC
	The Hardware CRC HAL API provides a low-level interface to the Hardware CRC module of a target platform.
	Critical Section HAL functions
	Flash HAL API
	GPIO HAL functions
	GPIO IRQ HAL functions
	I2C Events Macros
	I2C Configuration Functions
	Synchronous I2C Hardware Abstraction Layer for slave
	Asynchronous I2C Hardware Abstraction Layer
	Instrumented Trace Macrocell HAL API
	Low Power Ticker
	Low level interface to the low power ticker of a target.
	MPU hal
	The MPU hal provides a simple MPU API to enhance device security by preventing execution from ram.
	Port HAL functions
	Pwmout hal functions
	QSPI HAL
	ResetReason HAL API
	Low-level interface to the ResetReason of a target.
	RTC hal
	The RTC hal provides a low level interface to the Real Time Counter (RTC) of a target.
	Serial TX Events Macros
	Serial RX Events Macros
	Serial Configuration Functions
	Asynchronous Serial Hardware Abstraction Layer
	sleep hal requirements
	Low level interface to the sleep mode of a target.
	SPI Events Macros
	SPI Configuration Functions
	Synchronous SPI Hardware Abstraction Layer
	Asynchronous SPI Hardware Abstraction Layer
	Ticker HAL functions
	TRNG hal functions
	Microsecond Ticker
	Low level interface to the microsecond ticker of a target.
	Watchdog HAL API
	Low-level interface to the Independent Watchdog Timer of a target.

Data Structures
struct	buffer_s
	Generic buffer structure. More...
struct	can_pinmap_t
struct	CAN_Message
	Holder for single CAN message. More...
struct	CANFD_Message
struct	crc_mbed_config
struct	i2c_t
	Asynch I2C HAL structure. More...
struct	i2c_pinmap_t
class	LowPowerTickerWrapper
struct	PinMap
struct	PinList
struct	PeripheralList
struct	serial_t
	Asynch serial HAL structure. More...
struct	serial_pinmap_t
struct	serial_fc_pinmap_t
struct	spi_t
	Asynch SPI HAL structure. More...
struct	spi_pinmap_t
struct	spi_capabilities_t
	Describes the capabilities of a SPI peripherals. More...
struct	ticker_event_s
	Ticker's event structure. More...
struct	ticker_info_t
	Information about the ticker implementation. More...
struct	ticker_interface_t
	Ticker's interface structure - required API for a ticker. More...
struct	ticker_event_queue_t
	Ticker's event queue structure. More...
struct	ticker_data_t
	Ticker's data structure. More...

Typedefs
typedef struct analogin_s	analogin_t
	Analogin hal structure.
typedef struct dac_s	dac_t
	Analogout hal structure.
typedef struct buffer_s	buffer_t
	Generic buffer structure.
typedef enum crc_polynomial	crc_polynomial_t
	CRC Polynomial value.
typedef struct gpio_irq_s	gpio_irq_t
	GPIO IRQ HAL structure.
typedef struct port_s	port_t
	Port HAL structure.
typedef struct pwmout_s	pwmout_t
	Pwmout hal structure.
typedef uint32_t	timestamp_t
	Legacy format representing a timestamp in us.
typedef uint64_t	us_timestamp_t
	A us timestamp stored in a 64 bit integer.
typedef struct ticker_event_s	ticker_event_t
	Ticker's event structure.
typedef struct trng_s	trng_t
	TRNG HAL structure.

Enumerations
enum	CANFormat
	Values that represent CAN Format. More...
enum	CANType
	Values that represent CAN Type. More...
enum	crc_polynomial {   POLY_7BIT_SD = 0x09 , POLY_8BIT_CCITT = 0x07 , POLY_16BIT_CCITT = 0x1021 , POLY_16BIT_IBM = 0x8005 ,   POLY_32BIT_ANSI = 0x04C11DB7 }
	CRC Polynomial value. More...
enum	DMAUsage { DMA_USAGE_NEVER = 0 , DMA_USAGE_OPPORTUNISTIC , DMA_USAGE_ALWAYS , DMA_USAGE_TEMPORARY_ALLOCATED , DMA_USAGE_ALLOCATED }
	Enumeration of possible DMA usage hints. More...
enum	gpio_irq_event
	GPIO IRQ events. More...
enum	SerialIrq { RxIrq , TxIrq }
	Serial interrupt sources. More...

Functions
void	can_init (can_t *obj, PinName rd, PinName td)
	Initialize the CAN peripheral.
void	can_init_direct (can_t *obj, const can_pinmap_t *pinmap)
	Initialize the CAN peripheral.
void	can_init_freq (can_t *obj, PinName rd, PinName td, int hz, int data_hz)
	Initialize the CAN peripheral.
void	can_init_freq_direct (can_t *obj, const can_pinmap_t *pinmap, int hz, int data_hz)
	Initialize the CAN peripheral.
void	can_free (can_t *obj)
	Release the CAN peripheral, not currently invoked.
int	can_frequency (can_t *obj, int hz, int data_hz)
	Configure the CAN bus frequency.
void	can_irq_init (can_t *obj, can_irq_handler handler, uintptr_t context)
	Initialize the CAN IRQ handler.
void	can_irq_free (can_t *obj)
	Remove the CAN IRQ handler.
void	can_irq_set (can_t *obj, CanIrqType irq, uint32_t enable)
	Enable/disable the CAN IRQ event.
int	can_write (can_t *obj, CAN_Message msg)
	Write a CAN message to the bus.
int	can_read (can_t *obj, CAN_Message *msg, int handle)
	Read a CAN message from the bus.
int	can_mode (can_t *obj, CanMode mode)
	Change CAN operation to the specified mode.
int	can_filter (can_t *obj, uint32_t id, uint32_t mask, CANFormat format, int32_t handle)
	Filter out incomming messages.
void	can_reset (can_t *obj)
	Reset CAN interface.
unsigned char	can_rderror (can_t *obj)
	Detects read errors - Used to detect read overflow errors.
unsigned char	can_tderror (can_t *obj)
	Detects write errors - Used to detect write overflow errors.
void	can_monitor (can_t *obj, int silent)
	Puts or removes the CAN interface into silent monitoring mode.
int	canfd_write (can_t *obj, CANFD_Message msg)
	Write a CAN FD Message to the bus.
int	canfd_read (can_t *obj, CANFD_Message *msg, int handle)
	Read a Classical CAN or CAN FD Message from the bus.
const PinMap *	can_rd_pinmap (void)
	Get the pins that support CAN RD.
const PinMap *	can_td_pinmap (void)
	Get the pins that support CAN TD.
void	lp_ticker_wrapper_irq_handler (ticker_irq_handler_type handler)
	Interrupt handler for the wrapped lp ticker.
const ticker_data_t *	get_lp_ticker_wrapper_data (const ticker_data_t *data)
	Get wrapped lp ticker data.
void	lp_ticker_wrapper_suspend (void)
	Suspend the wrapper layer code.
void	lp_ticker_wrapper_resume (void)
	Resume the wrapper layer code.
bool	pinmap_find_peripheral_pins (const PinList *whitelist, const PinList *blacklist, int per, const PinMap *const *maps, PinName **pins, uint32_t count)
	Find a combination of pins suitable for use given the constraints.
bool	pinmap_list_has_pin (const PinList *list, PinName pin)
	Check if the pin is in the list.
bool	pinmap_list_has_peripheral (const PeripheralList *list, int peripheral)
	Check if the peripheral is in the list.
const PeripheralList *	pinmap_uart_restricted_peripherals (void)
	Get the pin list of peripherals per interface to avoid during testing.
const PinList *	pinmap_gpio_restricted_pins (void)
	Get the pin list of pins to avoid during GPIO/GPIO_IRQ testing.
USBPhy *	get_usb_phy ()
	Return a the USBPhy instance for this hardware.

Detailed Description

Typedef Documentation

analogin_t

typedef struct analogin_s analogin_t

Analogin hal structure.

analogin_s is declared in the target's hal

Definition at line 34 of file analogin_api.h.

dac_t

typedef struct dac_s dac_t

Analogout hal structure.

dac_s is declared in the target's hal

Definition at line 34 of file analogout_api.h.

buffer_t

typedef struct buffer_s buffer_t

Generic buffer structure.

crc_polynomial_t

typedef enum crc_polynomial crc_polynomial_t

CRC Polynomial value.

Different polynomial values supported

gpio_irq_t

typedef struct gpio_irq_s gpio_irq_t

GPIO IRQ HAL structure.

gpio_irq_s is declared in the target's HAL

Definition at line 42 of file gpio_irq_api.h.

port_t

typedef struct port_s port_t

Port HAL structure.

port_s is declared in the target's HAL

Definition at line 33 of file port_api.h.

pwmout_t

typedef struct pwmout_s pwmout_t

Pwmout hal structure.

pwmout_s is declared in the target's hal

Definition at line 34 of file pwmout_api.h.

timestamp_t

typedef uint32_t timestamp_t

Legacy format representing a timestamp in us.

Given it is modeled as a 32 bit integer, this type can represent timestamp up to 4294 seconds (71 minutes). Prefer using us_timestamp_t which store timestamp as 64 bits integer.

Definition at line 33 of file ticker_api.h.

us_timestamp_t

typedef uint64_t us_timestamp_t

A us timestamp stored in a 64 bit integer.

Can store timestamp up to 584810 years.

Definition at line 39 of file ticker_api.h.

ticker_event_t

typedef struct ticker_event_s ticker_event_t

Ticker's event structure.

trng_t

typedef struct trng_s trng_t

TRNG HAL structure.

trng_s is declared in the target's HAL

Definition at line 30 of file trng_api.h.

Enumeration Type Documentation

CANFormat

enum CANFormat

Values that represent CAN Format.

Definition at line 35 of file can_helper.h.

CANType

enum CANType

Values that represent CAN Type.

Definition at line 48 of file can_helper.h.

crc_polynomial

enum crc_polynomial

CRC Polynomial value.

Different polynomial values supported

Enumerator
POLY_7BIT_SD	x7+x3+1
POLY_8BIT_CCITT	x8+x2+x+1
POLY_16BIT_CCITT	x16+x12+x5+1
POLY_16BIT_IBM	x16+x15+x2+1
POLY_32BIT_ANSI	x32+x26+x23+x22+x16+x12+x11+x10+x8+x7+x5+x4+x2+x+1

Definition at line 30 of file crc_api.h.

DMAUsage

enum DMAUsage

Enumeration of possible DMA usage hints.

Enumerator
DMA_USAGE_NEVER	Never use DMA.
DMA_USAGE_OPPORTUNISTIC	Use DMA if possible but deallocate DMA resources when not being used.
DMA_USAGE_ALWAYS	Always use DMA when possible.

Definition at line 32 of file dma_api.h.

gpio_irq_event

enum gpio_irq_event

GPIO IRQ events.

Definition at line 34 of file gpio_irq_api.h.

SerialIrq

enum SerialIrq

Serial interrupt sources.

Enumerator
RxIrq	Receive Data Register Full.
TxIrq	Transmit Data Register Empty.

Definition at line 75 of file serial_api.h.

Function Documentation

can_init()

void can_init	(	can_t *	obj,
		PinName	rd,
		PinName	td
	)

Initialize the CAN peripheral.

It sets the default parameters for CAN peripheral, and configures its specifieds pins.

Parameters

obj	CAN object
rd	The CAN RD pin name
td	The CAN TD pin name

can_init_direct()

void can_init_direct	(	can_t *	obj,
		const can_pinmap_t *	pinmap
	)

Initialize the CAN peripheral.

It sets the default parameters for CAN peripheral, and configures its specifieds pins.

Parameters

obj	The CAN object
pinmap	pointer to structure which holds static pinmap

can_init_freq()

void can_init_freq	(	can_t *	obj,
		PinName	rd,
		PinName	td,
		int	hz,
		int	data_hz
	)

Initialize the CAN peripheral.

It sets the default parameters for CAN peripheral, and configures its specifieds pins.

Parameters

obj	CAN object
rd	The CAN RD pin name
td	The CAN TD pin name
hz	The bus frequency in classical CAN mode, or nominal phase frequency in CAN FD mode
data_hz	The data phase frequency in CAN FD mode, the CAN object is put into Classical CAN mode if this parameter is zero

can_init_freq_direct()

void can_init_freq_direct	(	can_t *	obj,
		const can_pinmap_t *	pinmap,
		int	hz,
		int	data_hz
	)

Initialize the CAN peripheral.

It sets the default parameters for CAN peripheral, and configures its specifieds pins.

Parameters

obj	CAN object
pinmap	pointer to structure which holds static pinmap
hz	The bus frequency in classical CAN mode, or nominal phase frequency in CAN FD mode
data_hz	The data phase frequency in CAN FD mode, the CAN object is put into Classical CAN mode if this parameter is zero

can_free()

void can_free

(

can_t *

obj

)

Release the CAN peripheral, not currently invoked.

It requires further resource management.

Parameters

obj	The CAN object

can_frequency()

int can_frequency	(	can_t *	obj,
		int	hz,
		int	data_hz
	)

Configure the CAN bus frequency.

Parameters

obj	The CAN object
hz	The bus frequency in classical CAN mode, or nominal phase frequency in CAN FD mode
data_hz	The data phase frequency in CAN FD mode, the CAN object is put into Classical CAN mode if this parameter is zero

can_irq_init()

void can_irq_init	(	can_t *	obj,
		can_irq_handler	handler,
		uintptr_t	context
	)

Initialize the CAN IRQ handler.

Parameters

obj	The CAN object
handler	The handler to be attached to CAN IRQ
context	The context to be passed back to the handler (context != 0, 0 is reserved)

can_irq_free()

void can_irq_free

(

can_t *

obj

)

Remove the CAN IRQ handler.

Parameters

obj	The CAN object

can_irq_set()

void can_irq_set	(	can_t *	obj,
		CanIrqType	irq,
		uint32_t	enable
	)

Enable/disable the CAN IRQ event.

Parameters

obj	The CAN object
irq	The CAN IRQ event
enable	The enable flag

can_write()

int can_write	(	can_t *	obj,
		CAN_Message	msg
	)

Write a CAN message to the bus.

Parameters

obj	The CAN object
msg	The CAN message to write.

Returns

0 if write failed, 1 if write was successful

can_read()

int can_read	(	can_t *	obj,
		CAN_Message *	msg,
		int	handle
	)

Read a CAN message from the bus.

Parameters

obj	CAN object
msg	A CAN message to read to.
handle	message filter handle (0 for any message).

Returns

0 if no message arrived, 1 if message arrived

can_mode()

int can_mode	(	can_t *	obj,
		CanMode	mode
	)

Change CAN operation to the specified mode.

Parameters

obj	The CAN object
mode	The new operation mode (MODE_NORMAL, MODE_SILENT, MODE_TEST_LOCAL, MODE_TEST_GLOBAL, MODE_TEST_SILENT).

Returns

0 if mode change failed or unsupported, 1 if mode change was successful

can_filter()

int can_filter	(	can_t *	obj,
		uint32_t	id,
		uint32_t	mask,
		CANFormat	format,
		int32_t	handle
	)

Filter out incomming messages.

Parameters

obj	The CAN object
id	the id to filter on.
mask	the mask applied to the id.
format	format to filter on (Default CANAny).
handle	message filter handle (Optional).

Returns

0 if filter change failed or unsupported, new filter handle if successful

can_reset()

void can_reset

(

can_t *

obj

)

Reset CAN interface.

Parameters

obj	CAN object

To use after error overflow.

can_rderror()

unsigned char can_rderror

(

can_t *

obj

)

Detects read errors - Used to detect read overflow errors.

Parameters

obj	CAN object

Returns

number of read errors

can_tderror()

unsigned char can_tderror

(

can_t *

obj

)

Detects write errors - Used to detect write overflow errors.

Parameters

obj	CAN object

Returns

number of write errors

can_monitor()

void can_monitor	(	can_t *	obj,
		int	silent
	)

Puts or removes the CAN interface into silent monitoring mode.

Parameters

obj	CAN object
silent	boolean indicating whether to go into silent mode or not.

canfd_write()

int canfd_write	(	can_t *	obj,
		CANFD_Message	msg
	)

Write a CAN FD Message to the bus.

Parameters

obj	The CAN object
msg	The CAN FD Message to write.

Returns

0 if write failed, 1 if write was successful

canfd_read()

int canfd_read	(	can_t *	obj,
		CANFD_Message *	msg,
		int	handle
	)

Read a Classical CAN or CAN FD Message from the bus.

Parameters

obj	CAN object
msg	A Classical CAN or CAN FD Message to read to.
handle	message filter handle (0 for any message).

Returns

0 if no message arrived, 1 if message arrived

can_rd_pinmap()

const PinMap * can_rd_pinmap

(

void

)

Get the pins that support CAN RD.

Return a PinMap array of pins that support CAN RD. The array is terminated with {NC, NC, 0}.

Returns

PinMap array

can_td_pinmap()

const PinMap * can_td_pinmap

(

void

)

Get the pins that support CAN TD.

Return a PinMap array of pins that support CAN TD. The array is terminated with {NC, NC, 0}.

Returns

PinMap array

lp_ticker_wrapper_irq_handler()

void lp_ticker_wrapper_irq_handler

(

ticker_irq_handler_type

handler

)

Interrupt handler for the wrapped lp ticker.

Parameters

handler

the function which would normally be called by the lp ticker handler when it is not wrapped

get_lp_ticker_wrapper_data()

const ticker_data_t * get_lp_ticker_wrapper_data

(

const ticker_data_t *

data

)

Get wrapped lp ticker data.

Parameters

data	hardware low power ticker object

Returns

wrapped low power ticker object

lp_ticker_wrapper_suspend()

void lp_ticker_wrapper_suspend

(

void

)

Suspend the wrapper layer code.

Pass through all interrupts to the low power ticker and stop using the microsecond ticker.

Warning

: Make sure to suspend the LP ticker first (call ticker_suspend()), otherwise the behavior is undefined.

lp_ticker_wrapper_resume()

void lp_ticker_wrapper_resume

(

void

)

Resume the wrapper layer code.

Resume operation of the wrapper layer. Interrupts will be filtered as normal and the microsecond timer will be used for interrupts scheduled too quickly back-to-back.

pinmap_find_peripheral_pins()

bool pinmap_find_peripheral_pins	(	const PinList *	whitelist,
		const PinList *	blacklist,
		int	per,
		const PinMap *const *	maps,
		PinName **	pins,
		uint32_t	count
	)

Find a combination of pins suitable for use given the constraints.

This function finds pins which meet these specific properties:

• The pin is part of the form factor
• The pin is not in the restricted list
• The pin is contained within the respective pinmap
• The pin belongs to the given peripheral
• Each pin found is distinct; in the example below mosi and miso will never be assigned the same pin

Example:

#include "mbed.h"
#include "pinmap.h"
 
int main()
{
    int per = spi_master_cs_pinmap()->peripheral;
    const PinList *pins_ff = pinmap_ff_default_pins();
    PinName mosi = NC;
    PinName miso = NC;
    PinName sclk = NC;
    PinName ssel = NC;
    const PinMap *maps[] = {
        spi_master_mosi_pinmap(),
        spi_master_miso_pinmap(),
        spi_master_clk_pinmap(),
        spi_master_cs_pinmap()
    };
    PinName *pins[] = {
        &mosi,
        &miso,
        &sclk,
        &ssel
    };
    if (pinmap_find_peripheral_pins(pins_ff, pins_avoid, per, maps, pins, sizeof(maps) / sizeof(maps[0]))) {
        printf("Found SPI pins to test instance %i with:\n"
               "  mosi=%s\n"
               "  miso=%s\n"
               "  sclk=%s\n"
               "  ssel=%s\n", per,
               pinmap_ff_default_pin_to_string(mosi),
               pinmap_ff_default_pin_to_string(miso),
               pinmap_ff_default_pin_to_string(sclk),
               pinmap_ff_default_pin_to_string(ssel));
    } else {
        printf("Could not find SPI combination to test %i\n", per);
    }
    return 0;
}

Parameters

whitelist	List of pins to choose from
blacklist	List of pins which cannot be used
per	Peripheral to which the pins belong
maps	An array of pin maps to select from
pins	An array of pins to find. Pins already set to a value will be left unchanged. Only pins initialized to NC will be updated by this function
count	The size of maps and pins

Returns

true if a suitable combination of pins was found and written to the pins array, otherwise false

pinmap_list_has_pin()

bool pinmap_list_has_pin	(	const PinList *	list,
		PinName	pin
	)

Check if the pin is in the list.

Parameters

list	pin list to check
pin	pin to check for in the list

Returns

true if the pin is in the list, false otherwise

pinmap_list_has_peripheral()

bool pinmap_list_has_peripheral	(	const PeripheralList *	list,
		int	peripheral
	)

Check if the peripheral is in the list.

Parameters

list	peripheral list to check
peripheral	peripheral to check for in the list

Returns

true if the peripheral is in the list, false otherwise

pinmap_uart_restricted_peripherals()

const PeripheralList * pinmap_uart_restricted_peripherals

(

void

)

Get the pin list of peripherals per interface to avoid during testing.

The restricted peripheral list is used to indicate to testing that a peripheral should be skipped due to some caveat about it. For example, using the USB serial port during tests will interfere with the test runner and should be avoided.

Targets should override the weak implementation of this function if they have peripherals which should be skipped during testing.

Note

Restricting peripheral is at the moment available for UART interface only as only STDIO UART must be skipped because it is used by Mbed. Restricting peripherals for other interfaces should be added in the future if required.

Returns

Pointer to a peripheral list of peripheral to avoid

pinmap_gpio_restricted_pins()

const PinList * pinmap_gpio_restricted_pins

(

void

)

Get the pin list of pins to avoid during GPIO/GPIO_IRQ testing.

The GPIO restricted pin list is used to indicate to testing that a pin should be skipped due to some caveat about it.

Targets should override the weak implementation of this function if they have peripherals which should be skipped during testing.

Note

This is special case only for GPIO/GPIO_IRQ tests because targets do not provide pin-maps for GPIO.

Returns

Pointer to a peripheral list of peripheral to avoid

get_usb_phy()

USBPhy * get_usb_phy

(

)

Return a the USBPhy instance for this hardware.

For details on adding support for a USBPhy see the specification in USBPhy.h.

Returns

A pointer to a USBPhy instance

Note

Calling this function on platforms without a USBPhy will result in an error