Line data Source code
1 0 : /* 2 : * Copyright (c) 2022 Nordic Semiconductor ASA 3 : * 4 : * SPDX-License-Identifier: Apache-2.0 5 : */ 6 : 7 : #ifndef ZEPHYR_INCLUDE_IPC_ICMSG_H_ 8 : #define ZEPHYR_INCLUDE_IPC_ICMSG_H_ 9 : 10 : #include <stddef.h> 11 : #include <stdint.h> 12 : #include <zephyr/kernel.h> 13 : #include <zephyr/drivers/mbox.h> 14 : #include <zephyr/ipc/ipc_service.h> 15 : #include <zephyr/ipc/pbuf.h> 16 : #include <zephyr/sys/atomic.h> 17 : 18 : #ifdef __cplusplus 19 : extern "C" { 20 : #endif 21 : 22 : /** 23 : * @brief Icmsg IPC library API 24 : * @defgroup ipc_icmsg_api Icmsg IPC library API 25 : * @ingroup ipc 26 : * @{ 27 : */ 28 : 29 0 : enum icmsg_state { 30 : ICMSG_STATE_OFF, 31 : ICMSG_STATE_BUSY, 32 : ICMSG_STATE_READY, 33 : }; 34 : 35 0 : struct icmsg_config_t { 36 0 : struct mbox_dt_spec mbox_tx; 37 0 : struct mbox_dt_spec mbox_rx; 38 : }; 39 : 40 0 : struct icmsg_data_t { 41 : /* Tx/Rx buffers. */ 42 0 : struct pbuf *tx_pb; 43 0 : struct pbuf *rx_pb; 44 : #ifdef CONFIG_IPC_SERVICE_ICMSG_SHMEM_ACCESS_SYNC 45 : struct k_mutex tx_lock; 46 : #endif 47 : 48 : /* Callbacks for an endpoint. */ 49 0 : const struct ipc_service_cb *cb; 50 0 : void *ctx; 51 : 52 : /* General */ 53 0 : const struct icmsg_config_t *cfg; 54 : #ifdef CONFIG_MULTITHREADING 55 : struct k_work_delayable notify_work; 56 : struct k_work mbox_work; 57 : #endif 58 0 : atomic_t state; 59 : }; 60 : 61 : /** @brief Open an icmsg instance 62 : * 63 : * Open an icmsg instance to be able to send and receive messages to a remote 64 : * instance. 65 : * This function is blocking until the handshake with the remote instance is 66 : * completed. 67 : * This function is intended to be called late in the initialization process, 68 : * possibly from a thread which can be safely blocked while handshake with the 69 : * remote instance is being performed. 70 : * 71 : * @param[in] conf Structure containing configuration parameters for the icmsg 72 : * instance. 73 : * @param[inout] dev_data Structure containing run-time data used by the icmsg 74 : * instance. 75 : * @param[in] cb Structure containing callback functions to be called on 76 : * events generated by this icmsg instance. The pointed memory 77 : * must be preserved while the icmsg instance is active. 78 : * @param[in] ctx Pointer to context passed as an argument to callbacks. 79 : * 80 : * 81 : * @retval 0 on success. 82 : * @retval -EALREADY when the instance is already opened. 83 : * @retval other errno codes from dependent modules. 84 : */ 85 1 : int icmsg_open(const struct icmsg_config_t *conf, 86 : struct icmsg_data_t *dev_data, 87 : const struct ipc_service_cb *cb, void *ctx); 88 : 89 : /** @brief Close an icmsg instance 90 : * 91 : * Closing an icmsg instance results in releasing all resources used by given 92 : * instance including the shared memory regions and mbox devices. 93 : * 94 : * @param[in] conf Structure containing configuration parameters for the icmsg 95 : * instance being closed. Its content must be the same as used 96 : * for creating this instance with @ref icmsg_open. 97 : * @param[inout] dev_data Structure containing run-time data used by the icmsg 98 : * instance. 99 : * 100 : * @retval 0 on success. 101 : * @retval other errno codes from dependent modules. 102 : */ 103 1 : int icmsg_close(const struct icmsg_config_t *conf, 104 : struct icmsg_data_t *dev_data); 105 : 106 : /** @brief Send a message to the remote icmsg instance. 107 : * 108 : * @param[in] conf Structure containing configuration parameters for the icmsg 109 : * instance. 110 : * @param[inout] dev_data Structure containing run-time data used by the icmsg 111 : * instance. 112 : * @param[in] msg Pointer to a buffer containing data to send. 113 : * @param[in] len Size of data in the @p msg buffer. 114 : * 115 : * 116 : * @retval Number of sent bytes. 117 : * @retval -EBUSY when the instance has not finished handshake with the remote 118 : * instance. 119 : * @retval -ENODATA when the requested data to send is empty. 120 : * @retval -EBADMSG when the requested data to send is too big. 121 : * @retval -ENOBUFS when there are no TX buffers available. 122 : * @retval other errno codes from dependent modules. 123 : */ 124 1 : int icmsg_send(const struct icmsg_config_t *conf, 125 : struct icmsg_data_t *dev_data, 126 : const void *msg, size_t len); 127 : 128 : /** 129 : * @} 130 : */ 131 : 132 : #ifdef __cplusplus 133 : } 134 : #endif 135 : 136 : #endif /* ZEPHYR_INCLUDE_IPC_ICMSG_H_ */
