Line data Source code
1 0 : /* 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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_ */
