Inter-Processor Mailbox (IPM)

Overview

API Reference

group ipm_interface

IPM Interface.

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.

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

Param ipmdev:

Driver instance

Param user_data:

Pointer to some private data provided at registration time.

Param id:

Message type identifier.

Param data:

Message data pointer. The correct amount of data to read out must be inferred using the message id/upper level protocol.

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.

See ipm_send() for argument definitions.

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

Callback API to get maximum data size.

See ipm_max_data_size_get() for argument definitions.

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

Callback API to get the ID’s maximum value.

See ipm_max_id_val_get() for argument definitions.

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

Callback API upon registration.

See ipm_register_callback() for argument definitions.

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

Callback API upon enablement of interrupts.

See ipm_set_enabled() for argument definitions.

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

Callback API upon command completion.

See ipm_complete() for argument definitions.

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.

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.

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

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.

int ipm_max_data_size_get(const 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.

Parameters:

  • ipmdev – Driver instance pointer.

Returns:

Maximum possible size of a message in bytes.

uint32_t ipm_max_id_val_get(const 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.

Parameters:

  • ipmdev – Driver instance pointer.

Returns:

Maximum possible value of a message ID.

int ipm_set_enabled(const 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 values:

  • 0 – On success.

  • -EINVAL – If it isn’t an inbound channel.

void ipm_complete(const struct device *ipmdev)

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.

struct ipm_driver_api
#include <ipm.h>