Input / Output Driver APIs

ADC Interface

group adc_interface

ADC driver APIs.

Defines

ADC_ACQ_TIME_MICROSECONDS

Acquisition time is expressed in microseconds.

ADC_ACQ_TIME_NANOSECONDS

Acquisition time is expressed in nanoseconds.

ADC_ACQ_TIME_TICKS

Acquisition time is expressed in ADC ticks.

ADC_ACQ_TIME(unit, value)

Macro for composing the acquisition time value in given units.

ADC_ACQ_TIME_DEFAULT

Value indicating that the default acquisition time should be used.

ADC_ACQ_TIME_UNIT(time)
ADC_ACQ_TIME_VALUE(time)

Typedefs

typedef enum adc_action (*adc_sequence_callback)(struct device *dev, const struct adc_sequence *sequence, u16_t sampling_index)

Type definition of the optional callback function to be called after a requested sampling is done.

Return
Action to be performed by the driver. See adc_action.
Parameters
  • dev: Pointer to the device structure for the driver instance.
  • sequence: Pointer to the sequence structure that triggered the sampling.
  • sampling_index: Index (0-65535) of the sampling done.

typedef int (*adc_api_channel_setup)(struct device *dev, const struct adc_channel_cfg *channel_cfg)

Type definition of ADC API function for configuring a channel. See adc_channel_setup() for argument descriptions.

typedef int (*adc_api_read)(struct device *dev, const struct adc_sequence *sequence)

Type definition of ADC API function for setting a read request. See adc_read() for argument descriptions.

Enums

enum adc_gain

ADC channel gain factors.

Values:

ADC_GAIN_1_6

x 1/6.

ADC_GAIN_1_5

x 1/5.

ADC_GAIN_1_4

x 1/4.

ADC_GAIN_1_3

x 1/3.

ADC_GAIN_1_2

x 1/2.

ADC_GAIN_2_3

x 2/3.

ADC_GAIN_1

x 1.

ADC_GAIN_2

x 2.

ADC_GAIN_3

x 3.

ADC_GAIN_4

x 4.

ADC_GAIN_8

x 8.

ADC_GAIN_16

x 16.

ADC_GAIN_32

x 32.

ADC_GAIN_64

x 64.

enum adc_reference

ADC references.

Values:

ADC_REF_VDD_1

VDD.

ADC_REF_VDD_1_2

VDD/2.

ADC_REF_VDD_1_3

VDD/3.

ADC_REF_VDD_1_4

VDD/4.

ADC_REF_INTERNAL

Internal.

ADC_REF_EXTERNAL0

External, input 0.

ADC_REF_EXTERNAL1

External, input 1.

enum adc_action

Action to be performed after a sampling is done.

Values:

ADC_ACTION_CONTINUE = 0

The sequence should be continued normally.

ADC_ACTION_REPEAT

The sampling should be repeated. New samples or sample should be read from the ADC and written in the same place as the recent ones.

ADC_ACTION_FINISH

The sequence should be finished immediately.

Functions

static int adc_channel_setup(struct device *dev, const struct adc_channel_cfg *channel_cfg)

Configure an ADC channel.

It is required to call this function and configure each channel before it is selected for a read request.

Parameters
  • dev: Pointer to the device structure for the driver instance.
  • channel_cfg: Channel configuration.
Return Value
  • 0: On success.
  • -EINVAL: If a parameter with an invalid value has been provided.

static int adc_read(struct device *dev, const struct adc_sequence *sequence)

Set a read request.

Parameters
  • dev: Pointer to the device structure for the driver instance.
  • sequence: Structure specifying requested sequence of samplings.
Return Value
  • 0: On success.
  • -EINVAL: If a parameter with an invalid value has been provided.
  • -ENOMEM: If the provided buffer is to small to hold the results of all requested samplings.
  • -ENOTSUP: If the requested mode of operation is not supported.
  • -EIO: If another sampling was triggered while the previous one was still in progress. This may occur only when samplings are done with intervals, and it indicates that the selected interval was too small. All requested samples are written in the buffer, but at least some of them were taken with an extra delay compared to what was scheduled.

struct adc_channel_cfg
#include <adc.h>

Structure for specifying the configuration of an ADC channel.

struct adc_sequence_options
#include <adc.h>

Structure defining additional options for an ADC sampling sequence.

struct adc_sequence
#include <adc.h>

Structure defining an ADC sampling sequence.

struct adc_driver_api
#include <adc.h>

ADC driver API.

This is the mandatory API any ADC driver needs to expose.

DMA Interface

group DMA_interface

DMA Interface.

Enums

enum dma_channel_direction

Values:

MEMORY_TO_MEMORY = 0x0
MEMORY_TO_PERIPHERAL
PERIPHERAL_TO_MEMORY
enum dma_addr_adj

Valid values for source_addr_adj and dest_addr_adj

Values:

DMA_ADDR_ADJ_INCREMENT
DMA_ADDR_ADJ_DECREMENT
DMA_ADDR_ADJ_NO_CHANGE

Functions

static int dma_config(struct device *dev, u32_t channel, struct dma_config *config)

Configure individual channel for DMA transfer.

Parameters
  • dev: Pointer to the device structure for the driver instance.
  • channel: Numeric identification of the channel to configure
  • config: Data structure containing the intended configuration for the selected channel
Return Value
  • 0: if successful.
  • Negative: errno code if failure.

static int dma_reload(struct device *dev, u32_t channel, u32_t src, u32_t dst, size_t size)

Reload buffer(s) for a DMA channel.

Parameters
  • dev: Pointer to the device structure for the driver instance.
  • channel: Numeric identification of the channel to configure selected channel
  • src: source address for the DMA transfer
  • dst: destination address for the DMA transfer
  • size: size of DMA transfer
Return Value
  • 0: if successful.
  • Negative: errno code if failure.

int dma_start(struct device *dev, u32_t channel)

Enables DMA channel and starts the transfer, the channel must be configured beforehand.

Implementations must check the validity of the channel ID passed in and return -EINVAL if it is invalid.

Parameters
  • dev: Pointer to the device structure for the driver instance.
  • channel: Numeric identification of the channel where the transfer will be processed
Return Value
  • 0: if successful.
  • Negative: errno code if failure.

int dma_stop(struct device *dev, u32_t channel)

Stops the DMA transfer and disables the channel.

Implementations must check the validity of the channel ID passed in and return -EINVAL if it is invalid.

Parameters
  • dev: Pointer to the device structure for the driver instance.
  • channel: Numeric identification of the channel where the transfer was being processed
Return Value
  • 0: if successful.
  • Negative: errno code if failure.

static u32_t dma_width_index(u32_t size)

Look-up generic width index to be used in registers.

WARNING: This look-up works for most controllers, but may not work for yours. Ensure your controller expects the most common register bit values before using this convenience function. If your controller does not support these values, you will have to write your own look-up inside the controller driver.

Parameters
  • size: width of bus (in bytes)
Return Value
  • common: DMA index to be placed into registers.

static u32_t dma_burst_index(u32_t burst)

Look-up generic burst index to be used in registers.

WARNING: This look-up works for most controllers, but may not work for yours. Ensure your controller expects the most common register bit values before using this convenience function. If your controller does not support these values, you will have to write your own look-up inside the controller driver.

Parameters
  • burst: number of bytes to be sent in a single burst
Return Value
  • common: DMA index to be placed into registers.

struct dma_block_config
#include <dma.h>

DMA block configuration structure.

source_address is block starting address at source source_gather_interval is the address adjustment at gather boundary dest_address is block starting address at destination dest_scatter_interval is the address adjustment at scatter boundary dest_scatter_count is the continuous transfer count between scatter boundaries source_gather_count is the continuous transfer count between gather boundaries block_size is the number of bytes to be transferred for this block.

config is a bit field with the following parts: source_gather_en [ 0 ] - 0-disable, 1-enable dest_scatter_en [ 1 ] - 0-disable, 1-enable source_addr_adj [ 2 : 3 ] - 00-increment, 01-decrement, 10-no change dest_addr_adj [ 4 : 5 ] - 00-increment, 01-decrement, 10-no change source_reload_en [ 6 ] - reload source address at the end of block transfer 0-disable, 1-enable dest_reload_en [ 7 ] - reload destination address at the end of block transfer 0-disable, 1-enable fifo_mode_control [ 8 : 11 ] - How full of the fifo before transfer start. HW specific. flow_control_mode [ 12 ] - 0-source request served upon data availability 1-source request postponed until destination request happens reserved [ 13 : 15 ]

struct dma_config
#include <dma.h>

DMA configuration structure.

dma_slot [ 0 : 5 ] - which peripheral and direction (HW specific) channel_direction [ 6 : 8 ] - 000-memory to memory, 001-memory to peripheral, 010-peripheral to memory, … complete_callback_en [ 9 ] - 0-callback invoked at completion only 1-callback invoked at completion of each block error_callback_en [ 10 ] - 0-error callback enabled 1-error callback disabled source_handshake [ 11 ] - 0-HW, 1-SW dest_handshake [ 12 ] - 0-HW, 1-SW channel_priority [ 13 : 16 ] - DMA channel priority source_chaining_en [ 17 ] - enable/disable source block chaining 0-disable, 1-enable dest_chaining_en [ 18 ] - enable/disable destination block chaining. 0-disable, 1-enable reserved [ 19 : 31 ]

source_data_size [ 0 : 15 ] - width of source data (in bytes) dest_data_size [ 16 : 31 ] - width of dest data (in bytes) source_burst_length [ 0 : 15 ] - number of source data units dest_burst_length [ 16 : 31 ] - number of destination data units

block_count is the number of blocks used for block chaining, this depends on availability of the DMA controller.

callback_arg private argument from DMA client.

dma_callback is the callback function pointer. If enabled, callback function will be invoked at transfer completion or when error happens (error_code: zero-transfer success, non zero-error happens).

GPIO Interface

group gpio_interface

GPIO Driver APIs.

Defines

GPIO_DECLARE_PIN_CONFIG_IDX(_idx)
GPIO_DECLARE_PIN_CONFIG
GPIO_PIN_IDX(_idx, _controller, _pin)
GPIO_PIN(_controller, _pin)
GPIO_GET_CONTROLLER_IDX(_idx, _conf)
GPIO_GET_PIN_IDX(_idx, _conf)
GPIO_GET_CONTROLLER(_conf)
GPIO_GET_PIN(_conf)

Typedefs

typedef gpio_callback_handler_t

Define the application callback handler function signature.

Note: cb pointer can be used to retrieve private data through CONTAINER_OF() if original struct

gpio_callback is stored in another private structure.
Parameters
  • struct device *port: Device struct for the GPIO device.
  • struct gpio_callback *cb: Original struct gpio_callback owning this handler
  • u32_t pins: Mask of pins that triggers the callback handler

Functions

static int gpio_pin_configure(struct device *port, u32_t pin, int flags)

Configure a single pin.

Return
0 if successful, negative errno code on failure.
Parameters
  • port: Pointer to device structure for the driver instance.
  • pin: Pin number to configure.
  • flags: Flags for pin configuration. IN/OUT, interrupt …

static int gpio_pin_write(struct device *port, u32_t pin, u32_t value)

Write the data value to a single pin.

Return
0 if successful, negative errno code on failure.
Parameters
  • port: Pointer to the device structure for the driver instance.
  • pin: Pin number where the data is written.
  • value: Value set on the pin.

static int gpio_pin_read(struct device *port, u32_t pin, u32_t *value)

Read the data value of a single pin.

Read the input state of a pin, returning the value 0 or 1.

Return
0 if successful, negative errno code on failure.
Parameters
  • port: Pointer to the device structure for the driver instance.
  • pin: Pin number where data is read.
  • value: Integer pointer to receive the data values from the pin.

static void gpio_init_callback(struct gpio_callback *callback, gpio_callback_handler_t handler, u32_t pin_mask)

Helper to initialize a struct gpio_callback properly.

Parameters
  • callback: A valid Application’s callback structure pointer.
  • handler: A valid handler function pointer.
  • pin_mask: A bit mask of relevant pins for the handler

static int gpio_add_callback(struct device *port, struct gpio_callback *callback)

Add an application callback.

Note: enables to add as many callback as needed on the same port.

Return
0 if successful, negative errno code on failure.
Parameters
  • port: Pointer to the device structure for the driver instance.
  • callback: A valid Application’s callback structure pointer.

static int gpio_remove_callback(struct device *port, struct gpio_callback *callback)

Remove an application callback.

Note: enables to remove as many callbacks as added through

gpio_add_callback().
Return
0 if successful, negative errno code on failure.
Parameters
  • port: Pointer to the device structure for the driver instance.
  • callback: A valid application’s callback structure pointer.

static int gpio_pin_enable_callback(struct device *port, u32_t pin)

Enable callback(s) for a single pin.

Note: Depending on the driver implementation, this function will enable the pin to trigger an interruption. So as a semantic detail, if no callback is registered, of course none will be called.

Return
0 if successful, negative errno code on failure.
Parameters
  • port: Pointer to the device structure for the driver instance.
  • pin: Pin number where the callback function is enabled.

static int gpio_pin_disable_callback(struct device *port, u32_t pin)

Disable callback(s) for a single pin.

Return
0 if successful, negative errno code on failure.
Parameters
  • port: Pointer to the device structure for the driver instance.
  • pin: Pin number where the callback function is disabled.

static int gpio_port_configure(struct device *port, int flags)

Configure all the pins the same way in the port. List out all flags on the detailed description.

Return
0 if successful, negative errno code on failure.
Parameters
  • port: Pointer to the device structure for the driver instance.
  • flags: Flags for the port configuration. IN/OUT, interrupt …

static int gpio_port_write(struct device *port, u32_t value)

Write a data value to the port.

Write the output state of a port. The state of each pin is represented by one bit in the value. Pin 0 corresponds to the least significant bit, pin 31 corresponds to the most significant bit. For ports with less that 32 physical pins the most significant bits which do not correspond to a physical pin are ignored.

Return
0 if successful, negative errno code on failure.
Parameters
  • port: Pointer to the device structure for the driver instance.
  • value: Value to set on the port.

static int gpio_port_read(struct device *port, u32_t *value)

Read data value from the port.

Read the input state of a port. The state of each pin is represented by one bit in the returned value. Pin 0 corresponds to the least significant bit, pin 31 corresponds to the most significant bit. Unused bits for ports with less that 32 physical pins are returned as 0.

Return
0 if successful, negative errno code on failure.
Parameters
  • port: Pointer to the device structure for the driver instance.
  • value: Integer pointer to receive the data value from the port.

static int gpio_port_enable_callback(struct device *port)

Enable callback(s) for the port.

Note: Depending on the driver implementation, this function will enable the port to trigger an interruption on all pins, as long as these are configured properly. So as a semantic detail, if no callback is registered, of course none will be called.

Return
0 if successful, negative errno code on failure.
Parameters
  • port: Pointer to the device structure for the driver instance.

static int gpio_port_disable_callback(struct device *port)

Disable callback(s) for the port.

Return
0 if successful, negative errno code on failure.
Parameters
  • port: Pointer to the device structure for the driver instance.

int gpio_get_pending_int(struct device *dev)

Function to get pending interrupts.

The purpose of this function is to return the interrupt status register for the device. This is especially useful when waking up from low power states to check the wake up source.

Parameters
  • dev: Pointer to the device structure for the driver instance.
Return Value
  • status: != 0 if at least one gpio interrupt is pending.
  • 0: if no gpio interrupt is pending.

struct gpio_callback
#include <gpio.h>

GPIO callback structure.

Used to register a callback in the driver instance callback list. As many callbacks as needed can be added as long as each of them are unique pointers of struct gpio_callback. Beware such structure should not be allocated on stack.

Note: To help setting it, see gpio_init_callback() below

I2C Interface

group i2c_interface

I2C Interface.

Defines

I2C_SPEED_STANDARD

I2C Standard Speed

I2C_SPEED_FAST

I2C Fast Speed

I2C_SPEED_FAST_PLUS

I2C Fast Plus Speed

I2C_SPEED_HIGH

I2C High Speed

I2C_SPEED_ULTRA

I2C Ultra Fast Speed

I2C_SPEED_SHIFT
I2C_SPEED_SET(speed)
I2C_SPEED_MASK
I2C_SPEED_GET(cfg)
I2C_ADDR_10_BITS

Use 10-bit addressing. DEPRECATED - Use I2C_MSG_ADDR_10_BITS instead.

I2C_MODE_MASTER

Controller to act as Master.

I2C_SLAVE_FLAGS_ADDR_10_BITS

Slave device responds to 10-bit addressing.

I2C_MSG_WRITE

Write message to I2C bus.

I2C_MSG_READ

Read message from I2C bus.

I2C_MSG_STOP

Send STOP after this message.

I2C_MSG_RESTART

RESTART I2C transaction for this message.

I2C_MSG_ADDR_10_BITS

Use 10-bit addressing for this message.

I2C_DECLARE_CLIENT_CONFIG
I2C_CLIENT(_master, _addr)
I2C_GET_MASTER(_conf)
I2C_GET_ADDR(_conf)

Functions

int i2c_configure(struct device *dev, u32_t dev_config)

Configure operation of a host controller.

Parameters
  • dev: Pointer to the device structure for the driver instance.
  • dev_config: Bit-packed 32-bit value to the device runtime configuration for the I2C controller.
Return Value
  • 0: If successful.
  • -EIO: General input / output error, failed to configure device.

int i2c_transfer(struct device *dev, struct i2c_msg *msgs, u8_t num_msgs, u16_t addr)

Perform data transfer to another I2C device.

This routine provides a generic interface to perform data transfer to another I2C device synchronously. Use i2c_read()/i2c_write() for simple read or write.

The array of message msgs must not be NULL. The number of message num_msgs may be zero,in which case no transfer occurs.

Parameters
  • dev: Pointer to the device structure for the driver instance.
  • msgs: Array of messages to transfer.
  • num_msgs: Number of messages to transfer.
  • addr: Address of the I2C target device.
Return Value
  • 0: If successful.
  • -EIO: General input / output error.

int i2c_slave_register(struct device *dev, struct i2c_slave_config *cfg)

Registers the provided config as Slave device.

Enable I2C slave mode for the ‘dev’ I2C bus driver using the provided ‘config’ struct containing the functions and parameters to send bus events. The I2C slave will be registered at the address provided as ‘address’ struct member. Addressing mode - 7 or 10 bit - depends on the ‘flags’ struct member. Any I2C bus events related to the slave mode will be passed onto I2C slave device driver via a set of callback functions provided in the ‘callbacks’ struct member.

Most of the existing hardware allows simultaneous support for master and slave mode. This is however not guaranteed.

Parameters
  • dev: Pointer to the device structure for the driver instance.
  • cfg: Config struct with functions and parameters used by the I2C driver to send bus events
Return Value
  • 0: Is successful
  • -EINVAL: If parameters are invalid
  • -EIO: General input / output error.
  • -ENOTSUP: If slave mode is not supported

int i2c_slave_unregister(struct device *dev, struct i2c_slave_config *cfg)

Unregisters the provided config as Slave device.

This routine disables I2C slave mode for the ‘dev’ I2C bus driver using the provided ‘config’ struct containing the functions and parameters to send bus events.

Parameters
  • dev: Pointer to the device structure for the driver instance.
  • cfg: Config struct with functions and parameters used by the I2C driver to send bus events
Return Value
  • 0: Is successful
  • -EINVAL: If parameters are invalid
  • -ENOTSUP: If slave mode is not supported

int i2c_slave_driver_register(struct device *dev)

Instructs the I2C Slave device to register itself to the I2C Controller.

This routine instructs the I2C Slave device to register itself to the I2C Controller.

Parameters
  • dev: Pointer to the device structure for the driver instance.
Return Value
  • 0: Is successful
  • -EINVAL: If parameters are invalid
  • -EIO: General input / output error.

int i2c_slave_driver_unregister(struct device *dev)

Instructs the I2C Slave device to unregister itself from the I2C Controller.

This routine instructs the I2C Slave device to unregister itself from the I2C Controller.

Parameters
  • dev: Pointer to the device structure for the driver instance.
Return Value
  • 0: Is successful
  • -EINVAL: If parameters are invalid

static int i2c_write(struct device *dev, u8_t *buf, u32_t num_bytes, u16_t addr)

Write a set amount of data to an I2C device.

This routine writes a set amount of data synchronously.

Parameters
  • dev: Pointer to the device structure for the driver instance.
  • buf: Memory pool from which the data is transferred.
  • num_bytes: Number of bytes to write.
  • addr: Address to the target I2C device for writing.
Return Value
  • 0: If successful.
  • -EIO: General input / output error.

static int i2c_read(struct device *dev, u8_t *buf, u32_t num_bytes, u16_t addr)

Read a set amount of data from an I2C device.

This routine reads a set amount of data synchronously.

Parameters
  • dev: Pointer to the device structure for the driver instance.
  • buf: Memory pool that stores the retrieved data.
  • num_bytes: Number of bytes to read.
  • addr: Address of the I2C device being read.
Return Value
  • 0: If successful.
  • -EIO: General input / output error.

static int i2c_burst_read(struct device *dev, u16_t dev_addr, u8_t start_addr, u8_t *buf, u32_t num_bytes)

Read multiple bytes from an internal address of an I2C device.

This routine reads multiple bytes from an internal address of an I2C device synchronously.

Parameters
  • dev: Pointer to the device structure for the driver instance.
  • dev_addr: Address of the I2C device for reading.
  • start_addr: Internal address from which the data is being read.
  • buf: Memory pool that stores the retrieved data.
  • num_bytes: Number of bytes being read.
Return Value
  • 0: If successful.
  • -EIO: General input / output error.

static int i2c_burst_write(struct device *dev, u16_t dev_addr, u8_t start_addr, u8_t *buf, u32_t num_bytes)

Write multiple bytes to an internal address of an I2C device.

This routine writes multiple bytes to an internal address of an I2C device synchronously.

Parameters
  • dev: Pointer to the device structure for the driver instance.
  • dev_addr: Address of the I2C device for writing.
  • start_addr: Internal address to which the data is being written.
  • buf: Memory pool from which the data is transferred.
  • num_bytes: Number of bytes being written.
Return Value
  • 0: If successful.
  • -EIO: General input / output error.

static int i2c_reg_read_byte(struct device *dev, u16_t dev_addr, u8_t reg_addr, u8_t *value)

Read internal register of an I2C device.

This routine reads the value of an 8-bit internal register of an I2C device synchronously.

Parameters
  • dev: Pointer to the device structure for the driver instance.
  • dev_addr: Address of the I2C device for reading.
  • reg_addr: Address of the internal register being read.
  • value: Memory pool that stores the retrieved register value.
Return Value
  • 0: If successful.
  • -EIO: General input / output error.

static int i2c_reg_write_byte(struct device *dev, u16_t dev_addr, u8_t reg_addr, u8_t value)

Write internal register of an I2C device.

This routine writes a value to an 8-bit internal register of an I2C device synchronously.

Parameters
  • dev: Pointer to the device structure for the driver instance.
  • dev_addr: Address of the I2C device for writing.
  • reg_addr: Address of the internal register being written.
  • value: Value to be written to internal register.
Return Value
  • 0: If successful.
  • -EIO: General input / output error.

static int i2c_reg_update_byte(struct device *dev, u8_t dev_addr, u8_t reg_addr, u8_t mask, u8_t value)

Update internal register of an I2C device.

This routine updates the value of a set of bits from an 8-bit internal register of an I2C device synchronously.

Parameters
  • dev: Pointer to the device structure for the driver instance.
  • dev_addr: Address of the I2C device for updating.
  • reg_addr: Address of the internal register being updated.
  • mask: Bitmask for updating internal register.
  • value: Value for updating internal register.
Return Value
  • 0: If successful.
  • -EIO: General input / output error.

static int i2c_burst_read16(struct device *dev, u16_t dev_addr, u16_t start_addr, u8_t *buf, u32_t num_bytes)

Read multiple bytes from an internal 16 bit address of an I2C device.

This routine reads multiple bytes from a 16 bit internal address of an I2C device synchronously.

Parameters
  • dev: Pointer to the device structure for the driver instance.
  • dev_addr: Address of the I2C device for reading.
  • start_addr: Internal 16 bit address from which the data is being read.
  • buf: Memory pool that stores the retrieved data.
  • num_bytes: Number of bytes being read.
Return Value
  • 0: If successful.
  • Negative: errno code if failure.

static int i2c_burst_write16(struct device *dev, u16_t dev_addr, u16_t start_addr, u8_t *buf, u32_t num_bytes)

Write multiple bytes to a 16 bit internal address of an I2C device.

This routine writes multiple bytes to a 16 bit internal address of an I2C device synchronously.

Parameters
  • dev: Pointer to the device structure for the driver instance.
  • dev_addr: Address of the I2C device for writing.
  • start_addr: Internal 16 bit address to which the data is being written.
  • buf: Memory pool from which the data is transferred.
  • num_bytes: Number of bytes being written.
Return Value
  • 0: If successful.
  • Negative: errno code if failure.

static int i2c_reg_read16(struct device *dev, u16_t dev_addr, u16_t reg_addr, u8_t *value)

Read internal 16 bit address register of an I2C device.

This routine reads the value of an 16-bit internal register of an I2C device synchronously.

Parameters
  • dev: Pointer to the device structure for the driver instance.
  • dev_addr: Address of the I2C device for reading.
  • reg_addr: 16 bit address of the internal register being read.
  • value: Memory pool that stores the retrieved register value.
Return Value
  • 0: If successful.
  • Negative: errno code if failure.

static int i2c_reg_write16(struct device *dev, u16_t dev_addr, u16_t reg_addr, u8_t value)

Write internal 16 bit address register of an I2C device.

This routine writes a value to an 16-bit internal register of an I2C device synchronously.

Parameters
  • dev: Pointer to the device structure for the driver instance.
  • dev_addr: Address of the I2C device for writing.
  • reg_addr: 16 bit address of the internal register being written.
  • value: Value to be written to internal register.
Return Value
  • 0: If successful.
  • Negative: errno code if failure.

static int i2c_reg_update16(struct device *dev, u16_t dev_addr, u16_t reg_addr, u8_t mask, u8_t value)

Update internal 16 bit address register of an I2C device.

This routine updates the value of a set of bits from a 16-bit internal register of an I2C device synchronously.

Parameters
  • dev: Pointer to the device structure for the driver instance.
  • dev_addr: Address of the I2C device for updating.
  • reg_addr: 16 bit address of the internal register being updated.
  • mask: Bitmask for updating internal register.
  • value: Value for updating internal register.
Return Value
  • 0: If successful.
  • Negative: errno code if failure.

static int i2c_burst_read_addr(struct device *dev, u16_t dev_addr, u8_t *start_addr, const u8_t addr_size, u8_t *buf, u32_t num_bytes)

Read multiple bytes from an internal variable byte size address of an I2C device.

This routine reads multiple bytes from an addr_size byte internal address of an I2C device synchronously.

Parameters
  • dev: Pointer to the device structure for the driver instance.
  • dev_addr: Address of the I2C device for reading.
  • start_addr: Array to an internal register address from which the data is being read.
  • addr_size: Size in bytes of the register address.
  • buf: Memory pool that stores the retrieved data.
  • num_bytes: Number of bytes being read.
Return Value
  • 0: If successful.
  • Negative: errno code if failure.

static int i2c_burst_write_addr(struct device *dev, u16_t dev_addr, u8_t *start_addr, const u8_t addr_size, u8_t *buf, u32_t num_bytes)

Write multiple bytes to an internal variable bytes size address of an I2C device. This routine writes multiple bytes to an addr_size byte internal address of an I2C device synchronously.

Parameters
  • dev: Pointer to the device structure for the driver instance.
  • dev_addr: Address of the I2C device for writing.
  • start_addr: Array to an internal register address from which the data is being read.
  • addr_size: Size in bytes of the register address.
  • buf: Memory pool from which the data is transferred.
  • num_bytes: Number of bytes being written.
Return Value
  • 0: If successful.
  • Negative: errno code if failure.

static int i2c_reg_read_addr(struct device *dev, u16_t dev_addr, u8_t *reg_addr, const u8_t addr_size, u8_t *value)

Read internal variable byte size address register of an I2C device.

This routine reads the value of an addr_size byte internal register of an I2C device synchronously.

Parameters
  • dev: Pointer to the device structure for the driver instance.
  • dev_addr: Address of the I2C device for reading.
  • reg_addr: Array to an internal register address from which the data is being read.
  • addr_size: Size in bytes of the register address.
  • value: Memory pool that stores the retrieved register value.
Return Value
  • 0: If successful.
  • Negative: errno code if failure.

static int i2c_reg_write_addr(struct device *dev, u16_t dev_addr, u8_t *reg_addr, const u8_t addr_size, u8_t value)

Write internal variable byte size address register of an I2C device.

This routine writes a value to an addr_size byte internal register of an I2C device synchronously.

Parameters
  • dev: Pointer to the device structure for the driver instance.
  • dev_addr: Address of the I2C device for writing.
  • reg_addr: Array to an internal register address from which the data is being read.
  • addr_size: Size in bytes of the register address.
  • value: Value to be written to internal register.
Return Value
  • 0: If successful.
  • Negative: errno code if failure.

static int i2c_reg_update_addr(struct device *dev, u16_t dev_addr, u8_t *reg_addr, u8_t addr_size, u8_t mask, u8_t value)

Update internal variable byte size address register of an I2C device.

This routine updates the value of a set of bits from a addr_size byte internal register of an I2C device synchronously.

Parameters
  • dev: Pointer to the device structure for the driver instance.
  • dev_addr: Address of the I2C device for updating.
  • reg_addr: Array to an internal register address from which the data is being read.
  • addr_size: Size in bytes of the register address.
  • mask: Bitmask for updating internal register.
  • value: Value for updating internal register.
Return Value
  • 0: If successful.
  • Negative: errno code if failure.

struct i2c_msg
#include <i2c.h>

One I2C Message.

This defines one I2C message to transact on the I2C bus.

I2S Interface

The I2S (Inter-IC Sound) API provides support for the standard I2S interface as well as common non-standard extensions such as PCM Short/Long Frame Sync and Left/Right Justified Data Formats.

group i2s_interface

I2S (Inter-IC Sound) Interface.

The I2S API provides support for the standard I2S interface standard as well as common non-standard extensions such as PCM Short/Long Frame Sync, Left/Right Justified Data Format.

Defines

I2S_FMT_DATA_FORMAT_SHIFT

Data Format bit field position.

I2S_FMT_DATA_FORMAT_MASK

Data Format bit field mask.

I2S_FMT_DATA_FORMAT_I2S

Standard I2S Data Format.

Serial data is transmitted in two’s complement with the MSB first. Both Word Select (WS) and Serial Data (SD) signals are sampled on the rising edge of the clock signal (SCK). The MSB is always sent one clock period after the WS changes. Left channel data are sent first indicated by WS = 0, followed by right channel data indicated by WS = 1.

   -. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-.
SCK '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '
   -.                               .-------------------------------.
WS  '-------------------------------'                               '----
   -.---.---.---.---.---.---.---.---.---.---.---.---.---.---.---.---.---.
SD  |   |MSB|   |...|   |LSB| x |...| x |MSB|   |...|   |LSB| x |...| x |
   -'---'---'---'---'---'---'---'---'---'---'---'---'---'---'---'---'---'
        | Left channel                  | Right channel                 |

I2S_FMT_DATA_FORMAT_PCM_SHORT

PCM Short Frame Sync Data Format.

Serial data is transmitted in two’s complement with the MSB first. Both Word Select (WS) and Serial Data (SD) signals are sampled on the falling edge of the clock signal (SCK). The falling edge of the frame sync signal (WS) indicates the start of the PCM word. The frame sync is one clock cycle long. An arbitrary number of data words can be sent in one frame.

     .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-.
SCK -' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-
     .---.                                                       .---.
WS  -'   '-                                                     -'   '-
    -.---.---.---.---.---.---.---.---.---.---.---.---.---.---.---.---.---
SD   |   |MSB|   |...|   |LSB|MSB|   |...|   |LSB|MSB|   |...|   |LSB|
    -'---'---'---'---'---'---'---'---'---'---'---'---'---'---'---'---'---
         | Word 1            | Word 2            | Word 3  |  Word n |

I2S_FMT_DATA_FORMAT_PCM_LONG

PCM Long Frame Sync Data Format.

Serial data is transmitted in two’s complement with the MSB first. Both Word Select (WS) and Serial Data (SD) signals are sampled on the falling edge of the clock signal (SCK). The rising edge of the frame sync signal (WS) indicates the start of the PCM word. The frame sync has an arbitrary length, however it has to fall before the start of the next frame. An arbitrary number of data words can be sent in one frame.

     .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-.
SCK -' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-
         .--- ---.    ---.        ---.                               .---
WS      -'       '-      '-          '-                             -'
    -.---.---.---.---.---.---.---.---.---.---.---.---.---.---.---.---.---
SD   |   |MSB|   |...|   |LSB|MSB|   |...|   |LSB|MSB|   |...|   |LSB|
    -'---'---'---'---'---'---'---'---'---'---'---'---'---'---'---'---'---
         | Word 1            | Word 2            | Word 3  |  Word n |

I2S_FMT_DATA_FORMAT_LEFT_JUSTIFIED

Left Justified Data Format.

Serial data is transmitted in two’s complement with the MSB first. Both Word Select (WS) and Serial Data (SD) signals are sampled on the rising edge of the clock signal (SCK). The bits within the data word are left justified such that the MSB is always sent in the clock period following the WS transition. Left channel data are sent first indicated by WS = 1, followed by right channel data indicated by WS = 0.

     .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-.
SCK -' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-
       .-------------------------------.                               .-
WS  ---'                               '-------------------------------'
    ---.---.---.---.---.---.---.---.---.---.---.---.---.---.---.---.---.-
SD     |MSB|   |...|   |LSB| x |...| x |MSB|   |...|   |LSB| x |...| x |
    ---'---'---'---'---'---'---'---'---'---'---'---'---'---'---'---'---'-
       | Left channel                  | Right channel                 |

I2S_FMT_DATA_FORMAT_RIGHT_JUSTIFIED

Right Justified Data Format.

Serial data is transmitted in two’s complement with the MSB first. Both Word Select (WS) and Serial Data (SD) signals are sampled on the rising edge of the clock signal (SCK). The bits within the data word are right justified such that the LSB is always sent in the clock period preceding the WS transition. Left channel data are sent first indicated by WS = 1, followed by right channel data indicated by WS = 0.

     .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-.
SCK -' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-
       .-------------------------------.                               .-
WS  ---'                               '-------------------------------'
    ---.---.---.---.---.---.---.---.---.---.---.---.---.---.---.---.---.-
SD     | x |...| x |MSB|   |...|   |LSB| x |...| x |MSB|   |...|   |LSB|
    ---'---'---'---'---'---'---'---'---'---'---'---'---'---'---'---'---'-
       | Left channel                  | Right channel                 |

I2S_FMT_DATA_ORDER_MSB

Send MSB first

I2S_FMT_DATA_ORDER_LSB

Send LSB first

I2S_FMT_DATA_ORDER_INV

Invert bit ordering, send LSB first

I2S_FMT_CLK_FORMAT_SHIFT

Data Format bit field position.

I2S_FMT_CLK_FORMAT_MASK

Data Format bit field mask.

I2S_FMT_BIT_CLK_INV

Invert bit clock

I2S_FMT_FRAME_CLK_INV

Invert frame clock

I2S_FMT_CLK_NF_NB

NF represents “Normal Frame” whereas IF represents “Inverted Frame” NB represents “Normal Bit Clk” whereas IB represents “Inverted Bit clk”

I2S_FMT_CLK_NF_IB
I2S_FMT_CLK_IF_NB
I2S_FMT_CLK_IF_IB
I2S_OPT_BIT_CLK_CONT

Run bit clock continuously

I2S_OPT_BIT_CLK_GATED

Run bit clock when sending data only

I2S_OPT_BIT_CLK_MASTER

I2S driver is bit clock master

I2S_OPT_BIT_CLK_SLAVE

I2S driver is bit clock slave

I2S_OPT_FRAME_CLK_MASTER

I2S driver is frame clock master

I2S_OPT_FRAME_CLK_SLAVE

I2S driver is frame clock slave

I2S_OPT_LOOPBACK

Loop back mode.

In loop back mode RX input will be connected internally to TX output. This is used primarily for testing.

I2S_OPT_PINGPONG

Ping pong mode.

In ping pong mode TX output will keep alternating between a ping buffer and a pong buffer. This is normally used in audio streams when one buffer is being populated while the other is being played (DMAed) and vice versa. So, in this mode, 2 sets of buffers fixed in size are used. Static Arrays are used to achieve this and hence they are never freed.

Typedefs

typedef u8_t i2s_fmt_t
typedef u8_t i2s_opt_t

Enums

enum i2s_dir

I2C Direction.

Values:

I2S_DIR_RX

Receive data

I2S_DIR_TX

Transmit data

enum i2s_state

Interface state

Values:

I2S_STATE_NOT_READY

The interface is not ready.

The interface was initialized but is not yet ready to receive / transmit data. Call i2s_configure() to configure interface and change its state to READY.

I2S_STATE_READY

The interface is ready to receive / transmit data.

I2S_STATE_RUNNING

The interface is receiving / transmitting data.

I2S_STATE_STOPPING

The interface is draining its transmit queue.

I2S_STATE_ERROR

TX buffer underrun or RX buffer overrun has occurred.

enum i2s_trigger_cmd

Trigger command

Values:

I2S_TRIGGER_START

Start the transmission / reception of data.

If I2S_DIR_TX is set some data has to be queued for transmission by the i2s_write() function. This trigger can be used in READY state only and changes the interface state to RUNNING.

I2S_TRIGGER_STOP

Stop the transmission / reception of data.

Stop the transmission / reception of data at the end of the current memory block. This trigger can be used in RUNNING state only and at first changes the interface state to STOPPING. When the current TX / RX block is transmitted / received the state is changed to READY. Subsequent START trigger will resume transmission / reception where it stopped.

I2S_TRIGGER_DRAIN

Empty the transmit queue.

Send all data in the transmit queue and stop the transmission. If the trigger is applied to the RX queue it has the same effect as I2S_TRIGGER_STOP. This trigger can be used in RUNNING state only and at first changes the interface state to STOPPING. When all TX blocks are transmitted the state is changed to READY.

I2S_TRIGGER_DROP

Discard the transmit / receive queue.

Stop the transmission / reception immediately and discard the contents of the respective queue. This trigger can be used in any state other than NOT_READY and changes the interface state to READY.

I2S_TRIGGER_PREPARE

Prepare the queues after underrun/overrun error has occurred.

This trigger can be used in ERROR state only and changes the interface state to READY.

Functions

int i2s_configure(struct device *dev, enum i2s_dir dir, struct i2s_config *cfg)

Configure operation of a host I2S controller.

The dir parameter specifies if Transmit (TX) or Receive (RX) direction will be configured by data provided via cfg parameter.

The function can be called in NOT_READY or READY state only. If executed successfully the function will change the interface state to READY.

If the function is called with the parameter cfg->frame_clk_freq set to 0 the interface state will be changed to NOT_READY.

Parameters
  • dev: Pointer to the device structure for the driver instance.
  • dir: Stream direction: RX or TX as defined by I2S_DIR_*
  • cfg: Pointer to the structure containing configuration parameters.
Return Value
  • 0: If successful.
  • -EINVAL: Invalid argument.

static struct i2s_config *i2s_config_get(struct device *dev, enum i2s_dir dir)

Fetch configuration information of a host I2S controller.

Parameters
  • dev: Pointer to the device structure for the driver instance
  • dir: Stream direction: RX or TX as defined by I2S_DIR_*
Return Value
  • Pointer: to the structure containing configuration parameters, or NULL if un-configured

static int i2s_read(struct device *dev, void **mem_block, size_t *size)

Read data from the RX queue.

Data received by the I2S interface is stored in the RX queue consisting of memory blocks preallocated by this function from rx_mem_slab (as defined by i2s_configure). Ownership of the RX memory block is passed on to the user application which has to release it.

The data is read in chunks equal to the size of the memory block. If the interface is in READY state the number of bytes read can be smaller.

If there is no data in the RX queue the function will block waiting for the next RX memory block to fill in. This operation can timeout as defined by i2s_configure. If the timeout value is set to K_NO_WAIT the function is non-blocking.

Reading from the RX queue is possible in any state other than NOT_READY. If the interface is in the ERROR state it is still possible to read all the valid data stored in RX queue. Afterwards the function will return -EIO error.

Parameters
  • dev: Pointer to the device structure for the driver instance.
  • mem_block: Pointer to the RX memory block containing received data.
  • size: Pointer to the variable storing the number of bytes read.
Return Value
  • 0: If successful.
  • -EIO: The interface is in NOT_READY or ERROR state and there are no more data blocks in the RX queue.
  • -EBUSY: Returned without waiting.
  • -EAGAIN: Waiting period timed out.

int i2s_buf_read(struct device *dev, void *buf, size_t *size)

Read data from the RX queue into a provided buffer.

Data received by the I2S interface is stored in the RX queue consisting of memory blocks preallocated by this function from rx_mem_slab (as defined by i2s_configure). Calling this function removes one block from the queue which is copied into the provided buffer and then freed.

The provided buffer must be large enough to contain a full memory block of data, which is parameterized for the channel via i2s_configure().

This function is otherwise equivalent to i2s_read().

Parameters
  • dev: Pointer to the device structure for the driver instance.
  • buf: Destination buffer for read data, which must be at least the as large as the configured memory block size for the RX channel.
  • size: Pointer to the variable storing the number of bytes read.
Return Value
  • 0: If successful.
  • -EIO: The interface is in NOT_READY or ERROR state and there are no more data blocks in the RX queue.
  • -EBUSY: Returned without waiting.
  • -EAGAIN: Waiting period timed out.

static int i2s_write(struct device *dev, void *mem_block, size_t size)

Write data to the TX queue.

Data to be sent by the I2S interface is stored first in the TX queue. TX queue consists of memory blocks preallocated by the user from tx_mem_slab (as defined by i2s_configure). This function takes ownership of the memory block and will release it when all data are transmitted.

If there are no free slots in the TX queue the function will block waiting for the next TX memory block to be send and removed from the queue. This operation can timeout as defined by i2s_configure. If the timeout value is set to K_NO_WAIT the function is non-blocking.

Writing to the TX queue is only possible if the interface is in READY or RUNNING state.

Parameters
  • dev: Pointer to the device structure for the driver instance.
  • mem_block: Pointer to the TX memory block containing data to be sent.
  • size: Number of bytes to write. This value has to be equal or smaller than the size of the memory block.
Return Value
  • 0: If successful.
  • -EIO: The interface is not in READY or RUNNING state.
  • -EBUSY: Returned without waiting.
  • -EAGAIN: Waiting period timed out.

int i2s_buf_write(struct device *dev, void *buf, size_t size)

Write data to the TX queue from a provided buffer.

This function acquires a memory block from the I2S channel TX queue and copies the provided data buffer into it. It is otherwise equivalent to i2s_write().

Parameters
  • dev: Pointer to the device structure for the driver instance.
  • buf: Pointer to a buffer containing the data to transmit.
  • size: Number of bytes to write. This value has to be equal or smaller than the size of the channel’s TX memory block configuration.
Return Value
  • 0: If successful.
  • -EIO: The interface is not in READY or RUNNING state.
  • -EBUSY: Returned without waiting.
  • -EAGAIN: Waiting period timed out.
  • -ENOMEM: No memory in TX slab queue.
  • -EINVAL: Size parameter larger than TX queue memory block.

int i2s_trigger(struct device *dev, enum i2s_dir dir, enum i2s_trigger_cmd cmd)

Send a trigger command.

Parameters
  • dev: Pointer to the device structure for the driver instance.
  • dir: Stream direction: RX or TX.
  • cmd: Trigger command.
Return Value
  • 0: If successful.
  • -EINVAL: Invalid argument.
  • -EIO: The trigger cannot be executed in the current state or a DMA channel cannot be allocated.
  • -ENOMEM: RX/TX memory block not available.

struct i2s_config
#include <i2s.h>

Interface configuration options.

Memory slab pointed to by the mem_slab field has to be defined and initialized by the user. For I2S driver to function correctly number of memory blocks in a slab has to be at least 2 per queue. Size of the memory block should be multiple of frame_size where frame_size = (channels * word_size_bytes). As an example 16 bit word will occupy 2 bytes, 24 or 32 bit word will occupy 4 bytes.

Please check Zephyr Kernel Primer for more information on memory slabs.

Remark
When I2S data format is selected parameter channels is ignored, number of words in a frame is always 2.
Parameters
  • word_size: Number of bits representing one data word.
  • channels: Number of words per frame.
  • format: Data stream format as defined by I2S_FMT_* constants.
  • options: Configuration options as defined by I2S_OPT_* constants.
  • frame_clk_freq: Frame clock (WS) frequency, this is sampling rate.
  • mem_slab: memory slab to store RX/TX data.
  • block_size: Size of one RX/TX memory block (buffer) in bytes.
  • timeout: Read/Write timeout. Number of milliseconds to wait in case TX queue is full, RX queue is empty or one of the special values K_NO_WAIT, K_FOREVER.

IPM Interface

group ipm_interface

IPM Interface.

Typedefs

typedef ipm_callback_t

Callback API for incoming IPM messages.

These callbacks execute in interrupt context. Therefore, use only interrupt-safe APIS. Registration of callbacks is done via ipm_register_callback

Parameters
  • void *context: Arbitrary context pointer provided at registration time.
  • u32_t id: Message type identifier.
  • volatile void *data: Message data pointer. The correct amount of data to read out must be inferred using the message id/upper level protocol.

typedef ipm_send_t

Callback API to send IPM messages.

See ipm_send() for argument definitions.

typedef ipm_max_data_size_get_t

Callback API to get maximum data size.

See ipm_max_data_size_get() for argument definitions.

typedef ipm_max_id_val_get_t

Callback API to get the ID’s maximum value.

See ipm_max_id_val_get() for argument definitions.

typedef ipm_register_callback_t

Callback API upon registration.

See ipm_register_callback() for argument definitions.

typedef ipm_set_enabled_t

Callback API upon enablement of interrupts.

See ipm_set_enabled() for argument definitions.

Functions

int ipm_send(struct device *ipmdev, int wait, u32_t id, const void *data, int size)

Try to send a message over the IPM device.

A message is considered consumed once the remote interrupt handler finishes. If there is deferred processing on the remote side, or if outgoing messages must be queued and wait on an event/semaphore, a high-level driver can implement that.

There are constraints on how much data can be sent or the maximum value of id. Use the ipm_max_data_size_get and ipm_max_id_val_get routines to determine them.

The size parameter is used only on the sending side to determine the amount of data to put in the message registers. It is not passed along to the receiving side. The upper-level protocol dictates the amount of data read back.

Parameters
  • ipmdev: Driver instance
  • wait: If nonzero, busy-wait for remote to consume the message. The message is considered consumed once the remote interrupt handler finishes. If there is deferred processing on the remote side, or you would like to queue outgoing messages and wait on an event/semaphore, you can implement that in a high-level driver
  • id: Message identifier. Values are constrained by ipm_max_data_size_get since many boards only allow for a subset of bits in a 32-bit register to store the ID.
  • data: Pointer to the data sent in the message.
  • size: Size of the data.
Return Value
  • EBUSY: If the remote hasn’t yet read the last data sent.
  • EMSGSIZE: If the supplied data size is unsupported by the driver.
  • EINVAL: If there was a bad parameter, such as: too-large id value. or the device isn’t an outbound IPM channel.
  • 0: On success.

static void ipm_register_callback(struct device *ipmdev, ipm_callback_t cb, void *context)

Register a callback function for incoming messages.

Parameters
  • ipmdev: Driver instance pointer.
  • cb: Callback function to execute on incoming message interrupts.
  • context: Application-specific context pointer which will be passed to the callback function when executed.

int ipm_max_data_size_get(struct device *ipmdev)

Return the maximum number of bytes possible in an outbound message.

IPM implementations vary on the amount of data that can be sent in a single message since the data payload is typically stored in registers.

Return
Maximum possible size of a message in bytes.
Parameters
  • ipmdev: Driver instance pointer.

u32_t ipm_max_id_val_get(struct device *ipmdev)

Return the maximum id value possible in an outbound message.

Many IPM implementations store the message’s ID in a register with some bits reserved for other uses.

Return
Maximum possible value of a message ID.
Parameters
  • ipmdev: Driver instance pointer.

int ipm_set_enabled(struct device *ipmdev, int enable)

Enable interrupts and callbacks for inbound channels.

Parameters
  • ipmdev: Driver instance pointer.
  • enable: Set to 0 to disable and to nonzero to enable.
Return Value
  • 0: On success.
  • EINVAL: If it isn’t an inbound channel.

PWM Interface

group pwm_interface

PWM Interface.

Defines

PWM_ACCESS_BY_PIN
PWM_ACCESS_ALL

Typedefs

typedef pwm_pin_set_t

Callback API upon setting the pin See pwm_pin_set_cycles() for argument description.

typedef pwm_get_cycles_per_sec_t

Callback API upon getting cycles per second See pwm_get_cycles_per_sec() for argument description.

Functions

int pwm_pin_set_cycles(struct device *dev, u32_t pwm, u32_t period, u32_t pulse)

Set the period and pulse width for a single PWM output.

Parameters
  • dev: Pointer to the device structure for the driver instance.
  • pwm: PWM pin.
  • period: Period (in clock cycle) set to the PWM. HW specific.
  • pulse: Pulse width (in clock cycle) set to the PWM. HW specific.
Return Value
  • 0: If successful.
  • Negative: errno code if failure.

int pwm_get_cycles_per_sec(struct device *dev, u32_t pwm, u64_t *cycles)

Get the clock rate (cycles per second) for a single PWM output.

Parameters
  • dev: Pointer to the device structure for the driver instance.
  • pwm: PWM pin.
  • cycles: Pointer to the memory to store clock rate (cycles per sec). HW specific.
Return Value
  • 0: If successful.
  • Negative: errno code if failure.

static int pwm_pin_set_usec(struct device *dev, u32_t pwm, u32_t period, u32_t pulse)

Set the period and pulse width for a single PWM output.

Parameters
  • dev: Pointer to the device structure for the driver instance.
  • pwm: PWM pin.
  • period: Period (in micro second) set to the PWM.
  • pulse: Pulse width (in micro second) set to the PWM.
Return Value
  • 0: If successful.
  • Negative: errno code if failure.

struct pwm_driver_api
#include <pwm.h>

PWM driver API definition.

Pinmux Interface

group pinmux_interface

Pinmux Interface.

Defines

PINMUX_FUNC_A
PINMUX_FUNC_B
PINMUX_FUNC_C
PINMUX_FUNC_D
PINMUX_FUNC_E
PINMUX_FUNC_F
PINMUX_FUNC_G
PINMUX_FUNC_H
PINMUX_PULLUP_ENABLE
PINMUX_PULLUP_DISABLE
PINMUX_INPUT_ENABLED
PINMUX_OUTPUT_ENABLED

Typedefs

typedef pmux_set

Callback API upon setting a PIN’s function See pinmux_pin_set() for argument description.

typedef pmux_get

Callback API upon getting a PIN’s function See pinmux_pin_get() for argument description.

typedef pmux_pullup

Callback API upon setting a PIN’s pullup See pinmix_pin_pullup() for argument description.

typedef pmux_input

Callback API upon setting a PIN’s input function See pinmux_input() for argument description.

Functions

static int pinmux_pin_set(struct device *dev, u32_t pin, u32_t func)
static int pinmux_pin_get(struct device *dev, u32_t pin, u32_t *func)
static int pinmux_pin_pullup(struct device *dev, u32_t pin, u8_t func)
static int pinmux_pin_input_enable(struct device *dev, u32_t pin, u8_t func)

SPI Interface

group spi_interface

SPI Interface.

Defines

SPI_OP_MODE_MASTER

SPI operational mode.

SPI_OP_MODE_SLAVE
SPI_OP_MODE_MASK
SPI_OP_MODE_GET(_operation_)
SPI_MODE_CPOL

SPI Polarity & Phase Modes.

Clock Polarity: if set, clock idle state will be 1 and active state will be 0. If untouched, the inverse will be true which is the default.

SPI_MODE_CPHA

Clock Phase: this dictates when is the data captured, and depends clock’s polarity. When SPI_MODE_CPOL is set and this bit as well, capture will occur on low to high transition and high to low if this bit is not set (default). This is fully reversed if CPOL is not set.

SPI_MODE_LOOP

Whatever data is transmitted is looped-back to the receiving buffer of the controller. This is fully controller dependent as some may not support this, and can be used for testing purposes only.

SPI_MODE_MASK
SPI_MODE_GET(_mode_)
SPI_TRANSFER_MSB

SPI Transfer modes (host controller dependent)

SPI_TRANSFER_LSB
SPI_WORD_SIZE_SHIFT

SPI word size.

SPI_WORD_SIZE_MASK
SPI_WORD_SIZE_GET(_operation_)
SPI_WORD_SET(_word_size_)
SPI_LINES_SINGLE

SPI MISO lines.

Some controllers support dual, quad or octal MISO lines connected to slaves. Default is single, which is the case most of the time.

SPI_LINES_DUAL
SPI_LINES_QUAD
SPI_LINES_OCTAL
SPI_LINES_MASK
SPI_HOLD_ON_CS

Specific SPI devices control bits.

SPI_LOCK_ON
SPI_CS_ACTIVE_HIGH

Typedefs

typedef spi_api_io

Callback API for I/O See spi_transceive() for argument descriptions.

Callback API for asynchronous I/O See spi_transceive_async() for argument descriptions.

typedef int (*spi_api_io_async)(struct device *dev, const struct spi_config *config, const struct spi_buf_set *tx_bufs, const struct spi_buf_set *rx_bufs, struct k_poll_signal *async)
typedef spi_api_release

Callback API for unlocking SPI device. See spi_release() for argument descriptions.

Functions

int spi_transceive(struct device *dev, const struct spi_config *config, const struct spi_buf_set *tx_bufs, const struct spi_buf_set *rx_bufs)

Read/write the specified amount of data from the SPI driver.

Note: This function is synchronous.

Parameters
  • dev: Pointer to the device structure for the driver instance
  • config: Pointer to a valid spi_config structure instance.
  • tx_bufs: Buffer array where data to be sent originates from, or NULL if none.
  • rx_bufs: Buffer array where data to be read will be written to, or NULL if none.
Return Value
  • 0: If successful, negative errno code otherwise. In case of slave transaction: if successful it will return the amount of frames received, negative errno code otherwise.

static int spi_read(struct device *dev, const struct spi_config *config, const struct spi_buf_set *rx_bufs)

Read the specified amount of data from the SPI driver.

Note: This function is synchronous.

Note
This function is an helper function calling spi_transceive.
Parameters
  • dev: Pointer to the device structure for the driver instance
  • config: Pointer to a valid spi_config structure instance.
  • rx_bufs: Buffer array where data to be read will be written to.
Return Value
  • 0: If successful, negative errno code otherwise.

static int spi_write(struct device *dev, const struct spi_config *config, const struct spi_buf_set *tx_bufs)

Write the specified amount of data from the SPI driver.

Note: This function is synchronous.

Note
This function is an helper function calling spi_transceive.
Parameters
  • dev: Pointer to the device structure for the driver instance
  • config: Pointer to a valid spi_config structure instance.
  • tx_bufs: Buffer array where data to be sent originates from.
Return Value
  • 0: If successful, negative errno code otherwise.

int spi_release(struct device *dev, const struct spi_config *config)

Release the SPI device locked on by the current config.

Note: This synchronous function is used to release the lock on the SPI device that was kept if, and if only, given config parameter was the last one to be used (in any of the above functions) and if it has the SPI_LOCK_ON bit set into its operation bits field. This can be used if the caller needs to keep its hand on the SPI device for consecutive transactions.

Parameters
  • dev: Pointer to the device structure for the driver instance
  • config: Pointer to a valid spi_config structure instance.

struct spi_cs_control
#include <spi.h>

SPI Chip Select control structure.

This can be used to control a CS line via a GPIO line, instead of using the controller inner CS logic.

Parameters
  • gpio_dev: is a valid pointer to an actual GPIO device. A NULL pointer can be provided to full inhibit CS control if necessary.
  • gpio_pin: is a number representing the gpio PIN that will be used to act as a CS line
  • delay: is a delay in microseconds to wait before starting the transmission and before releasing the CS line

struct spi_config
#include <spi.h>

SPI controller configuration structure.

Note
Only cs_hold and lock_on can be changed between consecutive transceive call. Rest of the attributes are not meant to be tweaked.
Parameters
  • dev: is a valid pointer to an actual SPI device
  • frequency: is the bus frequency in Hertz
  • operation: is a bit field with the following parts:
    operational mode    [ 0 ]       - master or slave.
    mode                [ 1 : 3 ]   - Polarity, phase and loop mode.
    transfer            [ 4 ]       - LSB or MSB first.
    word_size           [ 5 : 10 ]  - Size of a data frame in bits.
    lines               [ 11 : 12 ] - MISO lines: Single/Dual/Quad/Octal.
    cs_hold             [ 13 ]      - Hold on the CS line if possible.
    lock_on             [ 14 ]      - Keep resource locked for the caller.
    cs_active_high      [ 15 ]      - Active high CS logic.
    
  • slave: is the slave number from 0 to host controller slave limit.
  • cs: is a valid pointer on a struct spi_cs_control is CS line is emulated through a gpio line, or NULL otherwise.

struct spi_buf
#include <spi.h>

SPI buffer structure.

Parameters
  • buf: is a valid pointer on a data buffer, or NULL otherwise.
  • len: is the length of the buffer or, if buf is NULL, will be the length which as to be sent as dummy bytes (as TX buffer) or the length of bytes that should be skipped (as RX buffer).

struct spi_buf_set
#include <spi.h>

SPI buffer array structure.

Parameters
  • buffers: is a valid pointer on an array of spi_buf, or NULL.
  • count: is the length of the array pointed by buffers.

struct spi_driver_api
#include <spi.h>

SPI driver API This is the mandatory API any SPI driver needs to expose.

Entropy Interface

group entropy_interface

Entropy Interface.

Defines

ENTROPY_BUSYWAIT

Typedefs

typedef entropy_get_entropy_t

Callback API to get entropy.

See entropy_get_entropy() for argument description

typedef entropy_get_entropy_isr_t

Callback API to get entropy from an ISR.

See entropy_get_entropy_isr() for argument description

Functions

int entropy_get_entropy(struct device *dev, u8_t *buffer, u16_t length)

Fills a buffer with entropy. Blocks if required in order to generate the necessary random data.

Parameters
  • dev: Pointer to the entropy device.
  • buffer: Buffer to fill with entropy.
  • length: Buffer length.
Return Value
  • 0: on success.
  • -ERRNO: errno code on error.

static int entropy_get_entropy_isr(struct device *dev, u8_t *buffer, u16_t length, u32_t flags)

Fills a buffer with entropy in a non-blocking or busy-wait manner. Callable from ISRs.

Parameters
  • dev: Pointer to the device structure.
  • buffer: Buffer to fill with entropy.
  • length: Buffer length.
  • flags: Flags to modify the behavior of the call.
Return Value
  • number: of bytes filled with entropy or -error.

UART Interface

group uart_interface

UART Interface.

Defines

UART_OPTION_AFCE

Options for UART initialization.

LINE_CTRL_BAUD_RATE

Common line controls for UART.

LINE_CTRL_RTS
LINE_CTRL_DTR
LINE_CTRL_DCD
LINE_CTRL_DSR
UART_ERROR_OVERRUN

Overrun error.

UART_ERROR_PARITY

Parity error.

UART_ERROR_FRAMING

Framing error.

UART_ERROR_BREAK

Break interrupt error:

A break interrupt was received. This happens when the serial input is held at a logic ‘0’ state for longer than the sum of start time + data bits

  • parity + stop bits.

Typedefs

typedef uart_irq_callback_user_data_t

Define the application callback function signature for uart_irq_callback_user_data_set() function.

Parameters
  • user_data: Arbitrary user data.

typedef uart_irq_callback_t

Define the application callback function signature for legacy uart_irq_callback_set().

Parameters
  • port: Device struct for the UART device.

typedef uart_irq_config_func_t

For configuring IRQ on each individual UART device.

Enums

enum uart_config_parity

Parity modes.

Values:

UART_CFG_PARITY_NONE
UART_CFG_PARITY_ODD
UART_CFG_PARITY_EVEN
UART_CFG_PARITY_MARK
UART_CFG_PARITY_SPACE
enum uart_config_stop_bits

Number of stop bits.

Values:

UART_CFG_STOP_BITS_0_5
UART_CFG_STOP_BITS_1
UART_CFG_STOP_BITS_1_5
UART_CFG_STOP_BITS_2
enum uart_config_data_bits

Number of data bits.

Values:

UART_CFG_DATA_BITS_5
UART_CFG_DATA_BITS_6
UART_CFG_DATA_BITS_7
UART_CFG_DATA_BITS_8
enum uart_config_flow_control

Hardware flow control options.

With flow control set to none, any operations related to flow control signals can be managed by user with uart_line_ctrl functions. In other cases, flow control is managed by hardware/driver.

Values:

UART_CFG_FLOW_CTRL_NONE
UART_CFG_FLOW_CTRL_RTS_CTS
UART_CFG_FLOW_CTRL_DTR_DSR

Functions

int uart_err_check(struct device *dev)

Check whether an error was detected.

Parameters
  • dev: UART device structure.
Return Value
  • UART_ERROR_OVERRUN: if an overrun error was detected.
  • UART_ERROR_PARITY: if a parity error was detected.
  • UART_ERROR_FRAMING: if a framing error was detected.
  • UART_ERROR_BREAK: if a break error was detected.
  • 0: Otherwise.

int uart_poll_in(struct device *dev, unsigned char *p_char)

Poll the device for input.

Parameters
  • dev: UART device structure.
  • p_char: Pointer to character.
Return Value
  • 0: If a character arrived.
  • -1: If no character was available to read (i.e., the UART input buffer was empty).
  • -ENOTSUP: If the operation is not supported.

unsigned char uart_poll_out(struct device *dev, unsigned char out_char)

Output a character in polled mode.

This routine checks if the transmitter is empty. When the transmitter is empty, it writes a character to the data register.

To send a character when hardware flow control is enabled, the handshake signal CTS must be asserted.

Parameters
  • dev: UART device structure.
  • out_char: Character to send.
Return Value
  • char: Sent character.

int uart_configure(struct device *dev, const struct uart_config *cfg)

Set UART configuration.

Sets UART configuration using data from *cfg.

Parameters
  • dev: UART device structure.
  • cfg: UART configuration structure.
Return Value
  • -ENOTSUP: If configuration is not supported by device. or driver does not support setting configuration in runtime.
  • 0: If successful, negative errno code otherwise.

int uart_config_get(struct device *dev, struct uart_config *cfg)

Get UART configuration.

Stores current UART configuration to *cfg, can be used to retrieve initial configuration after device was initialized using data from DTS.

Parameters
  • dev: UART device structure.
  • cfg: UART configuration structure.
Return Value
  • -ENOTSUP: If driver does not support getting current configuration.
  • 0: If successful, negative errno code otherwise.

static int uart_fifo_fill(struct device *dev, const u8_t *tx_data, int size)

Fill FIFO with data.

This function is expected to be called from UART interrupt handler (ISR), if uart_irq_tx_ready() returns true. Result of calling this function not from an ISR is undefined (hardware-dependent). Likewise, not calling this function from an ISR if uart_irq_tx_ready() returns true may lead to undefined behavior, e.g. infinite interrupt loops. It’s mandatory to test return value of this function, as different hardware has different FIFO depth (oftentimes just 1).

Return
Number of bytes sent.
Parameters
  • dev: UART device structure.
  • tx_data: Data to transmit.
  • size: Number of bytes to send.

static int uart_fifo_read(struct device *dev, u8_t *rx_data, const int size)

Read data from FIFO.

This function is expected to be called from UART interrupt handler (ISR), if uart_irq_rx_ready() returns true. Result of calling this function not from an ISR is undefined (hardware-dependent). It’s unspecified whether “RX ready” condition as returned by uart_irq_rx_ready() is level- or edge- triggered. That means that once uart_irq_rx_ready() is detected, uart_fifo_read() must be called until it reads all available data in the FIFO (i.e. until it returns less data than was requested).

Return
Number of bytes read.
Parameters
  • dev: UART device structure.
  • rx_data: Data container.
  • size: Container size.

void uart_irq_tx_enable(struct device *dev)

Enable TX interrupt in IER.

Return
N/A
Parameters
  • dev: UART device structure.

void uart_irq_tx_disable(struct device *dev)

Disable TX interrupt in IER.

Return
N/A
Parameters
  • dev: UART device structure.

static int uart_irq_tx_ready(struct device *dev)

Check if UART TX buffer can accept a new char.

Check if UART TX buffer can accept at least one character for transmission (i.e. uart_fifo_fill() will succeed and return non-zero). This function must be called in a UART interrupt handler, or its result is undefined. Before calling this function in the interrupt handler, uart_irq_update() must be called once per the handler invocation.

Parameters
  • dev: UART device structure.
Return Value
  • 1: If at least one char can be written to UART.
  • 0: Otherwise.

void uart_irq_rx_enable(struct device *dev)

Enable RX interrupt.

Return
N/A
Parameters
  • dev: UART device structure.

void uart_irq_rx_disable(struct device *dev)

Disable RX interrupt.

Return
N/A
Parameters
  • dev: UART device structure.

static int uart_irq_tx_complete(struct device *dev)

Check if UART TX block finished transmission.

Check if any outgoing data buffered in UART TX block was fully transmitted and TX block is idle. When this condition is true, UART device (or whole system) can be power off. Note that this function is not useful to check if UART TX can accept more data, use uart_irq_tx_ready() for that. This function must be called in a UART interrupt handler, or its result is undefined. Before calling this function in the interrupt handler, uart_irq_update() must be called once per the handler invocation.

Parameters
  • dev: UART device structure.
Return Value
  • 1: If nothing remains to be transmitted.
  • 0: Otherwise.
  • -ENOTSUP: if this function is not supported

static int uart_irq_rx_ready(struct device *dev)

Check if UART RX buffer has a received char.

Check if UART RX buffer has at least one pending character (i.e. uart_fifo_read() will succeed and return non-zero). This function must be called in a UART interrupt handler, or its result is undefined. Before calling this function in the interrupt handler, uart_irq_update() must be called once per the handler invocation. It’s unspecified whether condition as returned by this function is level- or edge- triggered (i.e. if this function returns true when RX FIFO is non-empty, or when a new char was received since last call to it). See description of uart_fifo_read() for implication of this.

Parameters
  • dev: UART device structure.
Return Value
  • 1: If a received char is ready.
  • 0: Otherwise.
  • -ENOTSUP: if this function is not supported

void uart_irq_err_enable(struct device *dev)

Enable error interrupt.

Return
N/A
Parameters
  • dev: UART device structure.

void uart_irq_err_disable(struct device *dev)

Disable error interrupt.

Parameters
  • dev: UART device structure.
Return Value
  • 1: If an IRQ is ready.
  • 0: Otherwise.

int uart_irq_is_pending(struct device *dev)

Check if any IRQs is pending.

Parameters
  • dev: UART device structure.
Return Value
  • 1: If an IRQ is pending.
  • 0: Otherwise.

int uart_irq_update(struct device *dev)

Start processing interrupts in ISR.

This function should be called the first thing in the ISR. Calling uart_irq_rx_ready(), uart_irq_tx_ready(), uart_irq_tx_complete() allowed only after this.

The purpose of this function is:

  • For devices with auto-acknowledge of interrupt status on register read to cache the value of this register (rx_ready, etc. then use this case).
  • For devices with explicit acknowledgement of interrupts, to ack any pending interrupts and likewise to cache the original value.
  • For devices with implicit acknowledgement, this function will be empty. But the ISR must perform the actions needs to ack the interrupts (usually, call uart_fifo_read() on rx_ready, and uart_fifo_fill() on tx_ready).

Parameters
  • dev: UART device structure.
Return Value
  • 1: Always.

static void uart_irq_callback_user_data_set(struct device *dev, uart_irq_callback_user_data_t cb, void *user_data)

Set the IRQ callback function pointer.

This sets up the callback for IRQ. When an IRQ is triggered, the specified function will be called with specified user data. See description of uart_irq_update() for the requirements on ISR.

Return
N/A
Parameters
  • dev: UART device structure.
  • cb: Pointer to the callback function.
  • user_data: Data to pass to callback function.

static void uart_irq_callback_set(struct device *dev, uart_irq_callback_t cb)

Set the IRQ callback function pointer (legacy).

This sets up the callback for IRQ. When an IRQ is triggered, the specified function will be called with the device pointer.

Return
N/A
Parameters
  • dev: UART device structure.
  • cb: Pointer to the callback function.

int uart_drv_cmd(struct device *dev, u32_t cmd, u32_t p)

Send extra command to driver.

Implementation and accepted commands are driver specific. Refer to the drivers for more information.

Parameters
  • dev: UART device structure.
  • cmd: Command to driver.
  • p: Parameter to the command.
Return Value
  • 0: If successful.
  • failed: Otherwise.

struct uart_config
#include <uart.h>

UART controller configuration structure.

Parameters
  • baudrate: Baudrate setting in bps
  • parity: Parity bit, use uart_config_parity
  • stop_bits: Stop bits, use uart_config_stop_bits
  • data_bits: Data bits, use uart_config_data_bits
  • flow_ctrl: Flow control setting, use uart_config_flow_control

struct uart_device_config
#include <uart.h>

UART device configuration.

Parameters
  • port: Base port number
  • base: Memory mapped base address
  • regs: Register address
  • sys_clk_freq: System clock frequency in Hz

struct uart_driver_api
#include <uart.h>

Driver API structure.

Flash Interface

group flash_interface

FLASH Interface.

Typedefs

typedef int (*flash_api_read)(struct device *dev, off_t offset, void *data, size_t len)
typedef int (*flash_api_write)(struct device *dev, off_t offset, const void *data, size_t len)
typedef int (*flash_api_erase)(struct device *dev, off_t offset, size_t size)
typedef int (*flash_api_write_protection)(struct device *dev, bool enable)

Functions

int flash_read(struct device *dev, off_t offset, void *data, size_t len)

Read data from flash.

Return
0 on success, negative errno code on fail.
Parameters
  • dev: : flash dev
  • offset: : Offset (byte aligned) to read
  • data: : Buffer to store read data
  • len: : Number of bytes to read.

int flash_write(struct device *dev, off_t offset, const void *data, size_t len)

Write buffer into flash memory.

Prior to the invocation of this API, the flash_write_protection_set needs to be called first to disable the write protection.

Return
0 on success, negative errno code on fail.
Parameters
  • dev: : flash device
  • offset: : starting offset for the write
  • data: : data to write
  • len: : Number of bytes to write

int flash_erase(struct device *dev, off_t offset, size_t size)

Erase part or all of a flash memory.

Acceptable values of erase size and offset are subject to hardware-specific multiples of page size and offset. Please check the API implemented by the underlying sub driver, for example by using flash_get_page_info_by_offs() if that is supported by your flash driver.

Prior to the invocation of this API, the flash_write_protection_set needs to be called first to disable the write protection.

Return
0 on success, negative errno code on fail.
See
flash_get_page_info_by_offs()
See
flash_get_page_info_by_idx()
Parameters
  • dev: : flash device
  • offset: : erase area starting offset
  • size: : size of area to be erased

int flash_write_protection_set(struct device *dev, bool enable)

Enable or disable write protection for a flash memory.

This API is required to be called before the invocation of write or erase API. Please note that on some flash components, the write protection is automatically turned on again by the device after the completion of each write or erase calls. Therefore, on those flash parts, write protection needs to be disabled before each invocation of the write or erase API. Please refer to the sub-driver API or the data sheet of the flash component to get details on the write protection behavior.

Return
0 on success, negative errno code on fail.
Parameters
  • dev: : flash device
  • enable: : enable or disable flash write protection

size_t flash_get_write_block_size(struct device *dev)

Get the minimum write block size supported by the driver.

The write block size supported by the driver might differ from the write block size of memory used because the driver might implements write-modify algorithm.

Return
write block size in bytes.
Parameters
  • dev: flash device

Sensor Interface

group sensor_interface

Sensor Interface.

Defines

SENSOR_G

The value of gravitational constant in micro m/s^2.

SENSOR_PI

The value of constant PI in micros.

Typedefs

typedef sensor_trigger_handler_t

Callback API upon firing of a trigger.

Parameters
  • struct device *dev: Pointer to the sensor device
  • struct sensor_trigger *trigger: The trigger

typedef sensor_attr_set_t

Callback API upon setting a sensor’s attributes.

See sensor_attr_set() for argument description

typedef sensor_trigger_set_t

Callback API for setting a sensor’s trigger and handler.

See sensor_trigger_set() for argument description

typedef sensor_sample_fetch_t

Callback API for fetching data from a sensor.

See sensor_sample_fetch() for argument description

typedef sensor_channel_get_t

Callback API for getting a reading from a sensor.

See sensor_channel_get() for argument description

Enums

enum sensor_channel

Sensor channels.

Values:

SENSOR_CHAN_ACCEL_X

Acceleration on the X axis, in m/s^2.

SENSOR_CHAN_ACCEL_Y

Acceleration on the Y axis, in m/s^2.

SENSOR_CHAN_ACCEL_Z

Acceleration on the Z axis, in m/s^2.

SENSOR_CHAN_ACCEL_XYZ

Acceleration on the X, Y and Z axes.

SENSOR_CHAN_GYRO_X

Angular velocity around the X axis, in radians/s.

SENSOR_CHAN_GYRO_Y

Angular velocity around the Y axis, in radians/s.

SENSOR_CHAN_GYRO_Z

Angular velocity around the Z axis, in radians/s.

SENSOR_CHAN_GYRO_XYZ

Angular velocity around the X, Y and Z axes.

SENSOR_CHAN_MAGN_X

Magnetic field on the X axis, in Gauss.

SENSOR_CHAN_MAGN_Y

Magnetic field on the Y axis, in Gauss.

SENSOR_CHAN_MAGN_Z

Magnetic field on the Z axis, in Gauss.

SENSOR_CHAN_MAGN_XYZ

Magnetic field on the X, Y and Z axes.

SENSOR_CHAN_DIE_TEMP

Device die temperature in degrees Celsius.

SENSOR_CHAN_AMBIENT_TEMP

Ambient temperature in degrees Celsius.

SENSOR_CHAN_PRESS

Pressure in kilopascal.

SENSOR_CHAN_PROX

Proximity. Adimensional. A value of 1 indicates that an object is close.

SENSOR_CHAN_HUMIDITY

Humidity, in percent.

SENSOR_CHAN_LIGHT

Illuminance in visible spectrum, in lux.

SENSOR_CHAN_IR

Illuminance in infra-red spectrum, in lux.

SENSOR_CHAN_RED

Illuminance in red spectrum, in lux.

SENSOR_CHAN_GREEN

Illuminance in green spectrum, in lux.

SENSOR_CHAN_BLUE

Illuminance in blue spectrum, in lux.

SENSOR_CHAN_ALTITUDE

Altitude, in meters

SENSOR_CHAN_PM_1_0

1.0 micro-meters Particulate Matter, in ug/m^3

SENSOR_CHAN_PM_2_5

2.5 micro-meters Particulate Matter, in ug/m^3

SENSOR_CHAN_PM_10

10 micro-meters Particulate Matter, in ug/m^3

SENSOR_CHAN_DISTANCE

Distance. From sensor to target, in meters

SENSOR_CHAN_CO2

CO2 level, in parts per million (ppm)

SENSOR_CHAN_VOC

VOC level, in parts per billion (ppb)

SENSOR_CHAN_VOLTAGE

Voltage, in volts

SENSOR_CHAN_CURRENT

Current, in amps

SENSOR_CHAN_ROTATION

Angular rotation, in degrees

SENSOR_CHAN_ALL

All channels.

enum sensor_trigger_type

Sensor trigger types.

Values:

SENSOR_TRIG_TIMER

Timer-based trigger, useful when the sensor does not have an interrupt line.

SENSOR_TRIG_DATA_READY

Trigger fires whenever new data is ready.

SENSOR_TRIG_DELTA

Trigger fires when the selected channel varies significantly. This includes any-motion detection when the channel is acceleration or gyro. If detection is based on slope between successive channel readings, the slope threshold is configured via the SENSOR_ATTR_SLOPE_TH and SENSOR_ATTR_SLOPE_DUR attributes.

SENSOR_TRIG_NEAR_FAR

Trigger fires when a near/far event is detected.

SENSOR_TRIG_THRESHOLD

Trigger fires when channel reading transitions configured thresholds. The thresholds are configured via the SENSOR_ATTR_LOWER_THRESH and SENSOR_ATTR_UPPER_THRESH attributes.

SENSOR_TRIG_TAP

Trigger fires when a single tap is detected.

SENSOR_TRIG_DOUBLE_TAP

Trigger fires when a double tap is detected.

enum sensor_attribute

Sensor attribute types.

Values:

SENSOR_ATTR_SAMPLING_FREQUENCY

Sensor sampling frequency, i.e. how many times a second the sensor takes a measurement.

SENSOR_ATTR_LOWER_THRESH

Lower threshold for trigger.

SENSOR_ATTR_UPPER_THRESH

Upper threshold for trigger.

SENSOR_ATTR_SLOPE_TH

Threshold for any-motion (slope) trigger.

SENSOR_ATTR_SLOPE_DUR

Duration for which the slope values needs to be outside the threshold for the trigger to fire.

SENSOR_ATTR_OVERSAMPLING

Oversampling factor

SENSOR_ATTR_FULL_SCALE

Sensor range, in SI units.

SENSOR_ATTR_OFFSET

The sensor value returned will be altered by the amount indicated by offset: final_value = sensor_value + offset.

SENSOR_ATTR_CALIB_TARGET

Calibration target. This will be used by the internal chip’s algorithms to calibrate itself on a certain axis, or all of them.

Functions

int sensor_attr_set(struct device *dev, enum sensor_channel chan, enum sensor_attribute attr, const struct sensor_value *val)

Set an attribute for a sensor.

Return
0 if successful, negative errno code if failure.
Parameters
  • dev: Pointer to the sensor device
  • chan: The channel the attribute belongs to, if any. Some attributes may only be set for all channels of a device, depending on device capabilities.
  • attr: The attribute to set
  • val: The value to set the attribute to

static int sensor_trigger_set(struct device *dev, struct sensor_trigger *trig, sensor_trigger_handler_t handler)

Activate a sensor’s trigger and set the trigger handler.

The handler will be called from a thread, so I2C or SPI operations are safe. However, the thread’s stack is limited and defined by the driver. It is currently up to the caller to ensure that the handler does not overflow the stack.

This API is not permitted for user threads.

Return
0 if successful, negative errno code if failure.
Parameters
  • dev: Pointer to the sensor device
  • trig: The trigger to activate
  • handler: The function that should be called when the trigger fires

int sensor_sample_fetch(struct device *dev)

Fetch a sample from the sensor and store it in an internal driver buffer.

Read all of a sensor’s active channels and, if necessary, perform any additional operations necessary to make the values useful. The user may then get individual channel values by calling sensor_channel_get.

Since the function communicates with the sensor device, it is unsafe to call it in an ISR if the device is connected via I2C or SPI.

Return
0 if successful, negative errno code if failure.
Parameters
  • dev: Pointer to the sensor device

int sensor_sample_fetch_chan(struct device *dev, enum sensor_channel type)

Fetch a sample from the sensor and store it in an internal driver buffer.

Read and compute compensation for one type of sensor data (magnetometer, accelerometer, etc). The user may then get individual channel values by calling sensor_channel_get.

This is mostly implemented by multi function devices enabling reading at different sampling rates.

Since the function communicates with the sensor device, it is unsafe to call it in an ISR if the device is connected via I2C or SPI.

Return
0 if successful, negative errno code if failure.
Parameters
  • dev: Pointer to the sensor device
  • type: The channel that needs updated

int sensor_channel_get(struct device *dev, enum sensor_channel chan, struct sensor_value *val)

Get a reading from a sensor device.

Return a useful value for a particular channel, from the driver’s internal data. Before calling this function, a sample must be obtained by calling sensor_sample_fetch or sensor_sample_fetch_chan. It is guaranteed that two subsequent calls of this function for the same channels will yield the same value, if sensor_sample_fetch or sensor_sample_fetch_chan has not been called in the meantime.

For vectorial data samples you can request all axes in just one call by passing the specific channel with _XYZ suffix. The sample will be returned at val[0], val[1] and val[2] (X, Y and Z in that order).

Return
0 if successful, negative errno code if failure.
Parameters
  • dev: Pointer to the sensor device
  • chan: The channel to read
  • val: Where to store the value

static s32_t sensor_ms2_to_g(const struct sensor_value *ms2)

Helper function to convert acceleration from m/s^2 to Gs.

Return
The converted value, in Gs.
Parameters
  • ms2: A pointer to a sensor_value struct holding the acceleration, in m/s^2.

static void sensor_g_to_ms2(s32_t g, struct sensor_value *ms2)

Helper function to convert acceleration from Gs to m/s^2.

Parameters
  • g: The G value to be converted.
  • ms2: A pointer to a sensor_value struct, where the result is stored.

static s32_t sensor_rad_to_degrees(const struct sensor_value *rad)

Helper function for converting radians to degrees.

Return
The converted value, in degrees.
Parameters
  • rad: A pointer to a sensor_value struct, holding the value in radians.

static void sensor_degrees_to_rad(s32_t d, struct sensor_value *rad)

Helper function for converting degrees to radians.

Parameters
  • d: The value (in degrees) to be converted.
  • rad: A pointer to a sensor_value struct, where the result is stored.

static double sensor_value_to_double(struct sensor_value *val)

Helper function for converting struct sensor_value to double.

Return
The converted value.
Parameters

struct sensor_value
#include <sensor.h>

Representation of a sensor readout value.

The value is represented as having an integer and a fractional part, and can be obtained using the formula val1 + val2 * 10^(-6). Negative values also adhere to the above formula, but may need special attention. Here are some examples of the value representation:

 0.5: val1 =  0, val2 =  500000
-0.5: val1 =  0, val2 = -500000
-1.0: val1 = -1, val2 =  0
-1.5: val1 = -1, val2 = -500000

struct sensor_trigger
#include <sensor.h>

Sensor trigger spec.

Counter Interface

group counter_interface

Counter Interface.

Typedefs

typedef void (*counter_callback_t)(struct device *dev, void *user_data)
typedef int (*counter_api_start)(struct device *dev)
typedef int (*counter_api_stop)(struct device *dev)
typedef u32_t (*counter_api_read)(struct device *dev)
typedef int (*counter_api_set_alarm)(struct device *dev, counter_callback_t callback, u32_t count, void *user_data)
typedef u32_t (*counter_api_get_pending_int)(struct device *dev)

Functions

int counter_start(struct device *dev)

Start counter device in free running mode.

Start the counter device. If the device is a ‘countup’ counter, the counter initial value is set to zero. If it is a ‘countdown’ counter, the initial value is set to the maximum value supported by the device.

Parameters
  • dev: Pointer to the device structure for the driver instance.
Return Value
  • 0: If successful.
  • Negative: errno code if failure.

int counter_stop(struct device *dev)

Stop counter device.

Parameters
  • dev: Pointer to the device structure for the driver instance.
Return Value
  • 0: If successful.
  • -ENODEV: if the device doesn’t support stopping the counter.

u32_t counter_read(struct device *dev)

Read current counter value.

Return
32-bit value
Parameters
  • dev: Pointer to the device structure for the driver instance.

static int counter_set_alarm(struct device *dev, counter_callback_t callback, u32_t count, void *user_data)

Set an alarm.

Parameters
  • dev: Pointer to the device structure for the driver instance.
  • callback: Pointer to the callback function. If this is NULL, this function unsets the alarm.
  • count: Number of counter ticks. This is relative value, meaning an alarm will be triggered count ticks in the future.
  • user_data: Pointer to user data.
Return Value
  • 0: If successful.
  • -ENOTSUP: if the counter was not started yet.
  • -ENODEV: if the device doesn’t support interrupt (e.g. free running counters).
  • Negative: errno code if failure.

int counter_get_pending_int(struct device *dev)

Function to get pending interrupts.

The purpose of this function is to return the interrupt status register for the device. This is especially useful when waking up from low power states to check the wake up source.

Parameters
  • dev: Pointer to the device structure for the driver instance.
Return Value
  • 1: if the counter interrupt is pending.
  • 0: if no counter interrupt is pending.