API Reference

group ipm_interface

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

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

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.


int ipm_send(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.

  • 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 *user_data)

Register a callback function for incoming messages.

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


Maximum possible size of a message in bytes.

  • ipmdev: Driver instance pointer.

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


Maximum possible value of a message ID.

  • ipmdev: Driver instance pointer.

int ipm_set_enabled(struct device *ipmdev, int enable)

Enable interrupts and callbacks for inbound channels.

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