1 /* 2 * Copyright (c) 2021 Nordic Semiconductor ASA 3 * 4 * SPDX-License-Identifier: Apache-2.0 5 */ 6 7 #ifndef ZEPHYR_INCLUDE_IPC_SERVICE_IPC_SERVICE_BACKEND_H_ 8 #define ZEPHYR_INCLUDE_IPC_SERVICE_IPC_SERVICE_BACKEND_H_ 9 10 #include <zephyr/ipc/ipc_service.h> 11 #include <zephyr/kernel.h> 12 #include <stdio.h> 13 14 #ifdef __cplusplus 15 extern "C" { 16 #endif 17 18 /** 19 * @brief IPC service backend 20 * @defgroup ipc_service_backend IPC service backend 21 * @ingroup ipc 22 * @{ 23 */ 24 25 /** @brief IPC backend configuration structure. 26 * 27 * This structure is used for configuration backend during registration. 28 */ 29 struct ipc_service_backend { 30 /** @brief Pointer to the function that will be used to open an instance 31 * 32 * @param[in] instance Instance pointer. 33 * 34 * @retval -EALREADY when the instance is already opened. 35 * 36 * @retval 0 on success 37 * @retval other errno codes depending on the implementation of the 38 * backend. 39 */ 40 int (*open_instance)(const struct device *instance); 41 42 /** @brief Pointer to the function that will be used to close an instance 43 * 44 * @param[in] instance Instance pointer. 45 * 46 * @retval -EALREADY when the instance is not already inited. 47 * 48 * @retval 0 on success 49 * @retval other errno codes depending on the implementation of the 50 * backend. 51 */ 52 int (*close_instance)(const struct device *instance); 53 54 /** @brief Pointer to the function that will be used to send data to the endpoint. 55 * 56 * @param[in] instance Instance pointer. 57 * @param[in] token Backend-specific token. 58 * @param[in] data Pointer to the buffer to send. 59 * @param[in] len Number of bytes to send. 60 * 61 * @retval -EINVAL when instance is invalid. 62 * @retval -ENOENT when the endpoint is not registered with the instance. 63 * @retval -EBADMSG when the message is invalid. 64 * @retval -EBUSY when the instance is busy or not ready. 65 * @retval -ENOMEM when no memory / buffers are available. 66 * 67 * @retval bytes number of bytes sent. 68 * @retval other errno codes depending on the implementation of the 69 * backend. 70 */ 71 int (*send)(const struct device *instance, void *token, 72 const void *data, size_t len); 73 74 /** @brief Pointer to the function that will be used to register endpoints. 75 * 76 * @param[in] instance Instance to register the endpoint onto. 77 * @param[out] token Backend-specific token. 78 * @param[in] cfg Endpoint configuration. 79 * 80 * @retval -EINVAL when the endpoint configuration or instance is invalid. 81 * @retval -EBUSY when the instance is busy or not ready. 82 * 83 * @retval 0 on success 84 * @retval other errno codes depending on the implementation of the 85 * backend. 86 */ 87 int (*register_endpoint)(const struct device *instance, 88 void **token, 89 const struct ipc_ept_cfg *cfg); 90 91 /** @brief Pointer to the function that will be used to deregister endpoints 92 * 93 * @param[in] instance Instance from which to deregister the endpoint. 94 * @param[in] token Backend-specific token. 95 * 96 * @retval -EINVAL when the endpoint configuration or instance is invalid. 97 * @retval -ENOENT when the endpoint is not registered with the instance. 98 * @retval -EBUSY when the instance is busy or not ready. 99 * 100 * @retval 0 on success 101 * @retval other errno codes depending on the implementation of the 102 * backend. 103 */ 104 int (*deregister_endpoint)(const struct device *instance, void *token); 105 106 /** @brief Pointer to the function that will return the TX buffer size 107 * 108 * @param[in] instance Instance pointer. 109 * @param[in] token Backend-specific token. 110 * 111 * @retval -EINVAL when instance is invalid. 112 * @retval -ENOENT when the endpoint is not registered with the instance. 113 * @retval -ENOTSUP when the operation is not supported. 114 * 115 * @retval size TX buffer size on success. 116 * @retval other errno codes depending on the implementation of the 117 * backend. 118 */ 119 int (*get_tx_buffer_size)(const struct device *instance, void *token); 120 121 /** @brief Pointer to the function that will return an empty TX buffer. 122 * 123 * @param[in] instance Instance pointer. 124 * @param[in] token Backend-specific token. 125 * @param[out] data Pointer to the empty TX buffer. 126 * @param[in,out] len Pointer to store the TX buffer size. 127 * @param[in] wait Timeout waiting for an available TX buffer. 128 * 129 * @retval -EINVAL when instance is invalid. 130 * @retval -ENOENT when the endpoint is not registered with the instance. 131 * @retval -ENOTSUP when the operation or the timeout is not supported. 132 * @retval -ENOBUFS when there are no TX buffers available. 133 * @retval -EALREADY when a buffer was already claimed and not yet released. 134 * @retval -ENOMEM when the requested size is too big (and the size parameter 135 * contains the maximum allowed size). 136 * 137 * @retval 0 on success 138 * @retval other errno codes depending on the implementation of the 139 * backend. 140 */ 141 int (*get_tx_buffer)(const struct device *instance, void *token, 142 void **data, uint32_t *len, k_timeout_t wait); 143 144 /** @brief Pointer to the function that will drop a TX buffer. 145 * 146 * @param[in] instance Instance pointer. 147 * @param[in] token Backend-specific token. 148 * @param[in] data Pointer to the TX buffer. 149 * 150 * @retval -EINVAL when instance is invalid. 151 * @retval -ENOENT when the endpoint is not registered with the instance. 152 * @retval -ENOTSUP when this function is not supported. 153 * @retval -EALREADY when the buffer was already dropped. 154 * 155 * @retval 0 on success 156 * @retval other errno codes depending on the implementation of the 157 * backend. 158 */ 159 int (*drop_tx_buffer)(const struct device *instance, void *token, 160 const void *data); 161 162 /** @brief Pointer to the function that will be used to send data to 163 * the endpoint when the TX buffer has been obtained using @ref 164 * ipc_service_get_tx_buffer 165 * 166 * @param[in] instance Instance pointer. 167 * @param[in] token Backend-specific token. 168 * @param[in] data Pointer to the buffer to send. 169 * @param[in] len Number of bytes to send. 170 * 171 * @retval -EINVAL when instance is invalid. 172 * @retval -ENOENT when the endpoint is not registered with the instance. 173 * @retval -EBADMSG when the data is invalid (i.e. invalid data format, 174 * invalid length, ...) 175 * @retval -EBUSY when the instance is busy or not ready. 176 * 177 * @retval bytes number of bytes sent. 178 * @retval other errno codes depending on the implementation of the 179 * backend. 180 */ 181 int (*send_nocopy)(const struct device *instance, void *token, 182 const void *data, size_t len); 183 184 /** @brief Pointer to the function that will hold the RX buffer 185 * 186 * @param[in] instance Instance pointer. 187 * @param[in] token Backend-specific token. 188 * @param[in] data Pointer to the RX buffer to hold. 189 * 190 * @retval -EINVAL when instance is invalid. 191 * @retval -ENOENT when the endpoint is not registered with the instance. 192 * @retval -EALREADY when the buffer data has been already hold. 193 * @retval -ENOTSUP when this function is not supported. 194 * 195 * @retval 0 on success 196 * @retval other errno codes depending on the implementation of the 197 * backend. 198 */ 199 int (*hold_rx_buffer)(const struct device *instance, void *token, 200 void *data); 201 202 /** @brief Pointer to the function that will release the RX buffer. 203 * 204 * @param[in] instance Instance pointer. 205 * @param[in] token Backend-specific token. 206 * @param[in] data Pointer to the RX buffer to release. 207 * 208 * @retval -EINVAL when instance is invalid. 209 * @retval -ENOENT when the endpoint is not registered with the instance. 210 * @retval -EALREADY when the buffer data has been already released. 211 * @retval -ENOTSUP when this function is not supported. 212 * 213 * @retval 0 on success 214 * @retval other errno codes depending on the implementation of the 215 * backend. 216 */ 217 int (*release_rx_buffer)(const struct device *instance, void *token, 218 void *data); 219 }; 220 221 /** 222 * @} 223 */ 224 225 #ifdef __cplusplus 226 } 227 #endif 228 229 #endif /* ZEPHYR_INCLUDE_IPC_SERVICE_IPC_SERVICE_BACKEND_H_ */ 230
