Input / Output Driver APIs

ADC Interface

static void adc_enable(struct device *dev)

Enable ADC hardware.

This routine enables the ADC hardware block for data sampling for the specified device.

Return
N/A
Parameters
  • dev: Pointer to the device structure for the driver instance.

static void adc_disable(struct device *dev)

Disable ADC hardware.

This routine disables the ADC hardware block for data sampling for the specified device.

Return
N/A
Parameters
  • dev: Pointer to the device structure for the driver instance.

static int adc_read(struct device *dev, struct adc_seq_table *seq_table)

Set a read request.

This routine sends a read or sampling request to the ADC hardware block. A sequence table describes the read request. The routine returns once the ADC completes the read sequence. The sample data can be retrieved from the memory buffers in the sequence table structure.

Parameters
  • dev: Pointer to the device structure for the driver instance.
  • seq_table: Pointer to the structure representing the sequence table.
Return Value
  • 0: On success
  • else: Otherwise.

struct adc_seq_entry
#include <adc.h>

ADC driver Sequence entry.

This structure defines a sequence entry used to define a sample from a specific channel.

struct adc_seq_table
#include <adc.h>

ADC driver Sequence table.

This structure defines a list of sequence entries used to execute a sequence of samplings.

struct adc_driver_api
#include <adc.h>

ADC driver API.

This structure holds all API function pointers.

GPIO Interface

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

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.

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

GPIO_DIR_IN

GPIO pin to be input.

GPIO_DIR_OUT

GPIO pin to be output.

GPIO_INT

GPIO pin to trigger interrupt.

GPIO_INT_ACTIVE_LOW

GPIO pin trigger on level low or falling edge.

GPIO_INT_ACTIVE_HIGH

GPIO pin trigger on level high or rising edge.

GPIO_INT_CLOCK_SYNC

GPIO pin trigger to be synchronized to clock pulses.

GPIO_INT_DEBOUNCE

Enable GPIO pin debounce.

GPIO_INT_LEVEL

Do Level trigger.

GPIO_INT_EDGE

Do Edge trigger.

GPIO_INT_DOUBLE_EDGE

Interrupt triggers on both rising and falling edge.

GPIO_POL_NORMAL

GPIO pin polarity is normal.

GPIO_POL_INV

GPIO pin polarity is inverted.

GPIO_PUD_NORMAL

GPIO pin to have no pull-up or pull-down.

GPIO_PUD_PULL_UP

Enable GPIO pin pull-up.

GPIO_PUD_PULL_DOWN

Enable GPIO pin pull-down.

GPIO_PIN_ENABLE

Enable GPIO pin.

GPIO_PIN_DISABLE

Disable GPIO pin.

GPIO_DS_DFLT_LOW

Default drive strength standard when GPIO pin output is low.

GPIO_DS_ALT_LOW

Alternative drive strength when GPIO pin output is low. For hardware that does not support configurable drive strength use the default drive strength.

GPIO_DS_DISCONNECT_LOW

Disconnect pin when GPIO pin output is low. For hardware that does not support disconnect use the default drive strength.

GPIO_DS_DFLT_HIGH

Default drive strength when GPIO pin output is high.

GPIO_DS_ALT_HIGH

Alternative drive strength when GPIO pin output is high. For hardware that does not support configurable drive strengths use the default drive strength.

GPIO_DS_DISCONNECT_HIGH

Disconnect pin when GPIO pin output is high. For hardware that does not support disconnect use the default drive strength.

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

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

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

static int i2c_burst_read(struct device *dev, u16_t dev_addr, u8_t start_addr, u8_t *buf, u8_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, u8_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, u8_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, u8_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, u8_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, u8_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.

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_ADDR_10_BITS

Use 10-bit addressing.

I2C_MODE_MASTER

Controller to act as Master.

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

enum i2s_interface::i2s_dir

Values:

I2S_DIR_RX

Receive data

I2S_DIR_TX

Transmit data

enum i2s_interface::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_interface::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.

typedef u8_t i2s_fmt_t
typedef u8_t i2s_opt_t
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 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.

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.

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

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_BIT_CLK_INV

Invert bit clock

I2S_FMT_FRAME_CLK_INV

Invert frame clock

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.

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

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.

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

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

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

static 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

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.

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

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.

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

PWM_ACCESS_BY_PIN
PWM_ACCESS_ALL
struct pwm_driver_api
#include <pwm.h>

PWM driver API definition.

Pinmux Interface

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.

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)
PINMUX_FUNC_A
PINMUX_FUNC_B
PINMUX_FUNC_C
PINMUX_FUNC_D
PINMUX_FUNC_E
PINMUX_FUNC_F
PINMUX_PULLUP_ENABLE
PINMUX_PULLUP_DISABLE
PINMUX_INPUT_ENABLED
PINMUX_OUTPUT_ENABLED

SPI Interface

typedef spi_api_io

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

Callback API for I/O See spi_read() and spi_write() for argument descriptions.

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

typedef int (*spi_api_io_async)(struct spi_config *config, const struct spi_buf *tx_bufs, size_t tx_count, struct spi_buf *rx_bufs, size_t rx_count, struct k_poll_signal *async)
typedef spi_api_release

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

static int spi_transceive(struct spi_config *config, const struct spi_buf *tx_bufs, size_t tx_count, struct spi_buf *rx_bufs, size_t rx_count)

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

Note: This function is synchronous.

Parameters
  • config: Pointer to a valid spi_config structure instance.
  • tx_bufs: Buffer array where data to be sent originates from, or NULL if none.
  • tx_count: Number of element in the tx_bufs array.
  • rx_bufs: Buffer array where data to be read will be written to, or NULL if none.
  • rx_count: Number of element in the rx_bufs array.
Return Value
  • 0: If successful, negative errno code otherwise.

static int spi_read(struct spi_config *config, struct spi_buf *rx_bufs, size_t rx_count)

Read the specified amount of data from the SPI driver.

Note: This function is synchronous.

Parameters
  • config: Pointer to a valid spi_config structure instance.
  • rx_bufs: Buffer array where data to be read will be written to.
  • rx_count: Number of element in the rx_bufs array.
Return Value
  • 0: If successful, negative errno code otherwise.

static int spi_write(struct spi_config *config, const struct spi_buf *tx_bufs, size_t tx_count)

Write the specified amount of data from the SPI driver.

Note: This function is synchronous.

Parameters
  • config: Pointer to a valid spi_config structure instance.
  • tx_bufs: Buffer array where data to be sent originates from.
  • tx_count: Number of element in the tx_bufs array.
Return Value
  • 0: If successful, negative errno code otherwise.

static int spi_release(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
  • config: Pointer to a valid spi_config structure instance.

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 or quad MISO lines connected to slaves. Default is single, which is the case most of the time.

SPI_LINES_DUAL
SPI_LINES_QUAD
SPI_LINES_MASK
SPI_HOLD_ON_CS

Specific SPI devices control bits.

SPI_LOCK_ON
SPI_EEPROM_MODE
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.

gpio_dev is a valid pointer to an actual GPIO device 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.

SPI configuration structure.

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. cs_hold [ 13 ] - Hold on the CS line if possible. lock_on [ 14 ] - Keep resource locked for the caller. eeprom [ 15 ] - EEPROM mode. vendor is a vendor specific bitfield 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.

Note: cs_hold, lock_on and eeprom_rx can be changed between consecutive transceive call.

config is a bit field with the following parts: mode [ 0 : 2 ] - Polarity, phase and loop mode. transfer_mode [ 3 ] - LSB or MSB first transfer mode. word_size [ 4 : 11 ] - Size of a data frame in bits. RESERVED [ 12 : 31 ] - Undefined or device-specific usage.

max_sys_freq is the clock divider supported by the the host spi controller.

struct spi_buf
#include <spi.h>

SPI buffer structure.

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_driver_api
#include <spi.h>

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

Random Interface

typedef random_get_entropy_t

Callback API to get entropy.

See random_get_entropy() for argument description

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

Get entropy from the random driver.

Fill a buffer with entropy from the random driver.

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

UART Interface

typedef uart_irq_callback_t

Define the application callback function signature for UART.

Parameters
  • port: Device struct for the UART device.

typedef uart_irq_config_func_t

For configuring IRQ on each individual UART device.

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

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

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

static void uart_irq_tx_enable(struct device *dev)

Enable TX interrupt in IER.

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

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

static void uart_irq_rx_enable(struct device *dev)

Enable RX interrupt in IER.

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

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

static void uart_irq_err_enable(struct device *dev)

Enable error interrupt in IER.

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

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

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

static 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_set(struct device *dev, uart_irq_callback_t cb)

Set the IRQ callback function pointer.

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

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

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

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.

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.

Sensor Interface

enum sensor_interface::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.

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 milli 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_ALL

All channels.

enum sensor_interface::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_interface::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.

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

static 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 fiber, so I2C or SPI operations are safe. However, the fiber’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.

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

static 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

static 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

static 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

SENSOR_G

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

SENSOR_PI

The value of constant PI in micros.

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

struct sensor_trigger
#include <sensor.h>

Sensor trigger spec.