Zephyr API Documentation 3.7.99
A Scalable Open Source RTOS
Loading...
Searching...
No Matches
IPM Interface

IPM Interface . More...

Data Structures

struct  ipm_driver_api
 

Typedefs

typedef void(* ipm_callback_t) (const struct device *ipmdev, void *user_data, uint32_t id, volatile void *data)
 Callback API for incoming IPM messages.
 
typedef int(* ipm_send_t) (const struct device *ipmdev, int wait, uint32_t id, const void *data, int size)
 Callback API to send IPM messages.
 
typedef int(* ipm_max_data_size_get_t) (const struct device *ipmdev)
 Callback API to get maximum data size.
 
typedef uint32_t(* ipm_max_id_val_get_t) (const struct device *ipmdev)
 Callback API to get the ID's maximum value.
 
typedef void(* ipm_register_callback_t) (const struct device *port, ipm_callback_t cb, void *user_data)
 Callback API upon registration.
 
typedef int(* ipm_set_enabled_t) (const struct device *ipmdev, int enable)
 Callback API upon enablement of interrupts.
 
typedef void(* ipm_complete_t) (const struct device *ipmdev)
 Callback API upon command completion.
 

Functions

int ipm_send (const struct device *ipmdev, int wait, uint32_t id, const void *data, int size)
 Try to send a message over the IPM device.
 
static void ipm_register_callback (const struct device *ipmdev, ipm_callback_t cb, void *user_data)
 Register a callback function for incoming messages.
 
int ipm_max_data_size_get (const struct device *ipmdev)
 Return the maximum number of bytes possible in an outbound message.
 
uint32_t ipm_max_id_val_get (const struct device *ipmdev)
 Return the maximum id value possible in an outbound message.
 
int ipm_set_enabled (const struct device *ipmdev, int enable)
 Enable interrupts and callbacks for inbound channels.
 
void ipm_complete (const struct device *ipmdev)
 Signal asynchronous command completion.
 

Detailed Description

IPM Interface .

Since
1.0
Version
1.0.0

Typedef Documentation

◆ ipm_callback_t

typedef void(* ipm_callback_t) (const struct device *ipmdev, void *user_data, uint32_t id, volatile void *data)

#include <zephyr/drivers/ipm.h>

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
ipmdevDriver instance
user_dataPointer to some private data provided at registration time.
idMessage type identifier.
dataMessage data pointer. The correct amount of data to read out must be inferred using the message id/upper level protocol.

◆ ipm_complete_t

typedef void(* ipm_complete_t) (const struct device *ipmdev)

#include <zephyr/drivers/ipm.h>

Callback API upon command completion.

See ipm_complete() for argument definitions.

◆ ipm_max_data_size_get_t

typedef int(* ipm_max_data_size_get_t) (const struct device *ipmdev)

#include <zephyr/drivers/ipm.h>

Callback API to get maximum data size.

See ipm_max_data_size_get() for argument definitions.

◆ ipm_max_id_val_get_t

typedef uint32_t(* ipm_max_id_val_get_t) (const struct device *ipmdev)

#include <zephyr/drivers/ipm.h>

Callback API to get the ID's maximum value.

See ipm_max_id_val_get() for argument definitions.

◆ ipm_register_callback_t

typedef void(* ipm_register_callback_t) (const struct device *port, ipm_callback_t cb, void *user_data)

#include <zephyr/drivers/ipm.h>

Callback API upon registration.

See ipm_register_callback() for argument definitions.

◆ ipm_send_t

typedef int(* ipm_send_t) (const struct device *ipmdev, int wait, uint32_t id, const void *data, int size)

#include <zephyr/drivers/ipm.h>

Callback API to send IPM messages.

See ipm_send() for argument definitions.

◆ ipm_set_enabled_t

typedef int(* ipm_set_enabled_t) (const struct device *ipmdev, int enable)

#include <zephyr/drivers/ipm.h>

Callback API upon enablement of interrupts.

See ipm_set_enabled() for argument definitions.

Function Documentation

◆ ipm_complete()

void ipm_complete ( const struct device * ipmdev)

#include <zephyr/drivers/ipm.h>

Signal asynchronous command completion.

Some IPM backends have an ability to deliver a command asynchronously. The callback will be invoked in interrupt context, but the message (including the provided data pointer) will stay "active" and unacknowledged until later code (presumably in thread mode) calls ipm_complete().

This function is, obviously, a noop on drivers without async support.

Parameters
ipmdevDriver instance pointer.

◆ ipm_max_data_size_get()

int ipm_max_data_size_get ( const struct device * ipmdev)

#include <zephyr/drivers/ipm.h>

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.

Parameters
ipmdevDriver instance pointer.
Returns
Maximum possible size of a message in bytes.

◆ ipm_max_id_val_get()

uint32_t ipm_max_id_val_get ( const struct device * ipmdev)

#include <zephyr/drivers/ipm.h>

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.

Parameters
ipmdevDriver instance pointer.
Returns
Maximum possible value of a message ID.

◆ ipm_register_callback()

static void ipm_register_callback ( const struct device * ipmdev,
ipm_callback_t cb,
void * user_data )
inlinestatic

#include <zephyr/drivers/ipm.h>

Register a callback function for incoming messages.

Parameters
ipmdevDriver instance pointer.
cbCallback function to execute on incoming message interrupts.
user_dataApplication-specific data pointer which will be passed to the callback function when executed.

◆ ipm_send()

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

#include <zephyr/drivers/ipm.h>

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
ipmdevDriver instance
waitIf 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
idMessage 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.
dataPointer to the data sent in the message.
sizeSize of the data.
Return values
-EBUSYIf the remote hasn't yet read the last data sent.
-EMSGSIZEIf the supplied data size is unsupported by the driver.
-EINVALIf there was a bad parameter, such as: too-large id value. or the device isn't an outbound IPM channel.
0On success.

◆ ipm_set_enabled()

int ipm_set_enabled ( const struct device * ipmdev,
int enable )

#include <zephyr/drivers/ipm.h>

Enable interrupts and callbacks for inbound channels.

Parameters
ipmdevDriver instance pointer.
enableSet to 0 to disable and to nonzero to enable.
Return values
0On success.
-EINVALIf it isn't an inbound channel.