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

ipm_callback_t

#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

ipmdev	Driver instance
user_data	Pointer to some private data provided at registration time.
id	Message type identifier.
data	Message data pointer. The correct amount of data to read out must be inferred using the message id/upper level protocol.

ipm_complete_t

ipm_complete_t

#include <zephyr/drivers/ipm.h>

Callback API upon command completion.

See ipm_complete() for argument definitions.

ipm_max_data_size_get_t

ipm_max_data_size_get_t

#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

ipm_max_id_val_get_t

#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

ipm_register_callback_t

#include <zephyr/drivers/ipm.h>

Callback API upon registration.

See ipm_register_callback() for argument definitions.

ipm_send_t

ipm_send_t

#include <zephyr/drivers/ipm.h>

Callback API to send IPM messages.

See ipm_send() for argument definitions.

ipm_set_enabled_t

ipm_set_enabled_t

#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

ipmdev

Driver 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

ipmdev

Driver 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

ipmdev

Driver 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

ipmdev	Driver instance pointer.
cb	Callback function to execute on incoming message interrupts.
user_data	Application-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

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 values

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

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

ipmdev	Driver instance pointer.
enable	Set to 0 to disable and to nonzero to enable.

Return values

0	On success.
-EINVAL	If it isn't an inbound channel.