Input / Output Driver APIs¶

ADC Interface
DMA Interface
GPIO Interface
I2C Interface
I2S Interface
IPM Interface
PWM Interface
Pinmux Interface
SPI Interface
Entropy Interface
UART Interface
Flash Interface
Sensor Interface
Counter Interface

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.

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.

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_PIN_ENABLE¶

GPIO_PIN_DISABLE¶

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.

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_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.

union dev_config¶

#include <i2c.h>

Public Members

u32_t raw¶

struct dev_config::__bits bits¶

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

static 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.

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.

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 in IER.

Return

N/A

Parameters

dev: UART device structure.

void uart_irq_rx_disable(struct device *dev)¶

Disable RX interrupt in IER.

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.

static int uart_irq_tx_empty(struct device *dev)¶

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.

void uart_irq_err_enable(struct device *dev)¶

Enable error interrupt in IER.

Return

N/A

Parameters

dev: UART device structure.

void uart_irq_err_disable(struct device *dev)¶

Disable error interrupt in IER.

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)¶

Update cached contents of IIR.

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.

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_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_ACCEL_ANY = SENSOR_CHAN_ACCEL_XYZ¶

This enum value will be deprecated. Please use SENSOR_CHAN_ACCEL_XYZ instead.

Acceleration on any axis.

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_GYRO_ANY = SENSOR_CHAN_GYRO_XYZ¶

This enum value will be deprecated. Please use SENSOR_CHAN_GYRO_XYZ instead.

Angular velocity on any axis.

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_MAGN_ANY = SENSOR_CHAN_MAGN_XYZ¶

This enum value will be deprecated. Please use SENSOR_CHAN_MAGN_XYZ instead.

Magnetic field on any axis.

SENSOR_CHAN_TEMP¶: Temperature in degrees Celsius. (deprecated)

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_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

val: A pointer to a sensor_value struct.

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.