Jakub Grajciar | 7c5c40d | 2017-08-30 10:13:25 +0200 | [diff] [blame] | 1 | /* |
| 2 | *------------------------------------------------------------------ |
| 3 | * Copyright (c) 2017 Cisco and/or its affiliates. |
| 4 | * Licensed under the Apache License, Version 2.0 (the "License"); |
| 5 | * you may not use this file except in compliance with the License. |
| 6 | * You may obtain a copy of the License at: |
| 7 | * |
| 8 | * http://www.apache.org/licenses/LICENSE-2.0 |
| 9 | * |
| 10 | * Unless required by applicable law or agreed to in writing, software |
| 11 | * distributed under the License is distributed on an "AS IS" BASIS, |
| 12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| 13 | * See the License for the specific language governing permissions and |
| 14 | * limitations under the License. |
| 15 | *------------------------------------------------------------------ |
| 16 | */ |
| 17 | |
Dave Wallace | 6cd396c | 2018-01-23 17:47:02 -0500 | [diff] [blame] | 18 | /** @file |
Paul Vinciguerra | b5a575b | 2019-11-01 13:00:58 -0400 | [diff] [blame] | 19 | * @defgroup libmemif Example libmemif App |
Dave Wallace | 6cd396c | 2018-01-23 17:47:02 -0500 | [diff] [blame] | 20 | */ |
Jakub Grajciar | 7c5c40d | 2017-08-30 10:13:25 +0200 | [diff] [blame] | 21 | |
| 22 | #ifndef _LIBMEMIF_H_ |
| 23 | #define _LIBMEMIF_H_ |
| 24 | |
| 25 | /** Libmemif version. */ |
Jakub Grajciar | 17f2a7b | 2019-07-31 14:40:52 +0200 | [diff] [blame] | 26 | #define LIBMEMIF_VERSION "3.1" |
Jakub Grajciar | 7c5c40d | 2017-08-30 10:13:25 +0200 | [diff] [blame] | 27 | /** Default name of application using libmemif. */ |
| 28 | #define MEMIF_DEFAULT_APP_NAME "libmemif-app" |
| 29 | |
| 30 | #include <inttypes.h> |
Jakub Grajciar | 84b8377 | 2019-03-04 12:42:19 +0100 | [diff] [blame] | 31 | #include <sys/timerfd.h> |
Jakub Grajciar | 7c5c40d | 2017-08-30 10:13:25 +0200 | [diff] [blame] | 32 | |
Jakub Grajciar | 7c5c40d | 2017-08-30 10:13:25 +0200 | [diff] [blame] | 33 | /*! Error codes */ |
| 34 | typedef enum |
| 35 | { |
| 36 | MEMIF_ERR_SUCCESS = 0, /*!< success */ |
| 37 | /* SYSCALL ERRORS */ |
| 38 | MEMIF_ERR_SYSCALL, /*!< other syscall error */ |
Jakub Grajciar | 568cc46 | 2018-09-05 12:11:35 +0200 | [diff] [blame] | 39 | MEMIF_ERR_CONNREFUSED, /*!< connection refused */ |
Jakub Grajciar | 7c5c40d | 2017-08-30 10:13:25 +0200 | [diff] [blame] | 40 | MEMIF_ERR_ACCES, /*!< permission denied */ |
| 41 | MEMIF_ERR_NO_FILE, /*!< file does not exist */ |
| 42 | MEMIF_ERR_FILE_LIMIT, /*!< system open file limit */ |
| 43 | MEMIF_ERR_PROC_FILE_LIMIT, /*!< process open file limit */ |
| 44 | MEMIF_ERR_ALREADY, /*!< connection already requested */ |
| 45 | MEMIF_ERR_AGAIN, /*!< fd is not socket, or operation would block */ |
| 46 | MEMIF_ERR_BAD_FD, /*!< invalid fd */ |
| 47 | MEMIF_ERR_NOMEM, /*!< out of memory */ |
| 48 | /* LIBMEMIF ERRORS */ |
| 49 | MEMIF_ERR_INVAL_ARG, /*!< invalid argument */ |
| 50 | MEMIF_ERR_NOCONN, /*!< handle points to no connection */ |
| 51 | MEMIF_ERR_CONN, /*!< handle points to existing connection */ |
| 52 | MEMIF_ERR_CB_FDUPDATE, /*!< user defined callback memif_control_fd_update_t error */ |
Jakub Grajciar | 84b8377 | 2019-03-04 12:42:19 +0100 | [diff] [blame] | 53 | MEMIF_ERR_FILE_NOT_SOCK, /*!< file specified by socket filename |
Jakub Grajciar | 7c5c40d | 2017-08-30 10:13:25 +0200 | [diff] [blame] | 54 | exists, but it's not socket */ |
| 55 | MEMIF_ERR_NO_SHMFD, /*!< missing shm fd */ |
| 56 | MEMIF_ERR_COOKIE, /*!< wrong cookie on ring */ |
| 57 | MEMIF_ERR_NOBUF_RING, /*!< ring buffer full */ |
| 58 | MEMIF_ERR_NOBUF, /*!< not enough memif buffers */ |
| 59 | MEMIF_ERR_NOBUF_DET, /*!< memif details needs larger buffer */ |
| 60 | MEMIF_ERR_INT_WRITE, /*!< send interrupt error */ |
| 61 | MEMIF_ERR_MFMSG, /*!< malformed msg received */ |
| 62 | MEMIF_ERR_QID, /*!< invalid queue id */ |
| 63 | /* MEMIF PROTO ERRORS */ |
| 64 | MEMIF_ERR_PROTO, /*!< incompatible protocol version */ |
| 65 | MEMIF_ERR_ID, /*!< unmatched interface id */ |
| 66 | MEMIF_ERR_ACCSLAVE, /*!< slave cannot accept connection requests */ |
| 67 | MEMIF_ERR_ALRCONN, /*!< memif is already connected */ |
| 68 | MEMIF_ERR_MODE, /*!< mode mismatch */ |
| 69 | MEMIF_ERR_SECRET, /*!< secret mismatch */ |
| 70 | MEMIF_ERR_NOSECRET, /*!< secret required */ |
| 71 | MEMIF_ERR_MAXREG, /*!< max region limit reached */ |
| 72 | MEMIF_ERR_MAXRING, /*!< max ring limit reached */ |
| 73 | MEMIF_ERR_NO_INTFD, /*!< missing interrupt fd */ |
Paul Vinciguerra | f4fbfd6 | 2020-05-15 23:13:36 -0400 | [diff] [blame] | 74 | MEMIF_ERR_DISCONNECT, /*!< disconnect received */ |
Jakub Grajciar | 7c5c40d | 2017-08-30 10:13:25 +0200 | [diff] [blame] | 75 | MEMIF_ERR_DISCONNECTED, /*!< peer interface disconnected */ |
| 76 | MEMIF_ERR_UNKNOWN_MSG, /*!< unknown message type */ |
Milan Lenco | 0a47c99 | 2017-10-12 14:19:31 +0200 | [diff] [blame] | 77 | MEMIF_ERR_POLL_CANCEL, /*!< memif_poll_event() was cancelled */ |
Damjan Marion | 6d56fa4 | 2017-11-03 12:24:37 +0100 | [diff] [blame] | 78 | MEMIF_ERR_MAX_RING, /*!< too large ring size */ |
Jakub Grajciar | ab7c2b0 | 2018-03-28 10:21:05 +0200 | [diff] [blame] | 79 | MEMIF_ERR_PRIVHDR, /*!< private hdrs not supported */ |
Jakub Grajciar | 7c5c40d | 2017-08-30 10:13:25 +0200 | [diff] [blame] | 80 | } memif_err_t; |
| 81 | |
| 82 | /** |
| 83 | * @defgroup MEMIF_FD_EVENT Types of events that need to be watched for specific fd. |
Dave Wallace | 6cd396c | 2018-01-23 17:47:02 -0500 | [diff] [blame] | 84 | * @ingroup libmemif |
Jakub Grajciar | 7c5c40d | 2017-08-30 10:13:25 +0200 | [diff] [blame] | 85 | * @{ |
| 86 | */ |
| 87 | |
| 88 | /** user needs to set events that occured on fd and pass them to memif_control_fd_handler */ |
| 89 | #define MEMIF_FD_EVENT_READ (1 << 0) |
| 90 | #define MEMIF_FD_EVENT_WRITE (1 << 1) |
| 91 | /** inform libmemif that error occured on fd */ |
| 92 | #define MEMIF_FD_EVENT_ERROR (1 << 2) |
| 93 | /** if set, informs that fd is going to be closed (user may want to stop watching for events on this fd) */ |
| 94 | #define MEMIF_FD_EVENT_DEL (1 << 3) |
| 95 | /** update events */ |
| 96 | #define MEMIF_FD_EVENT_MOD (1 << 4) |
| 97 | /** @} */ |
| 98 | |
Jakub Grajciar | 17f2a7b | 2019-07-31 14:40:52 +0200 | [diff] [blame] | 99 | /** \brief Memif per thread main handle |
| 100 | Pointer of type void, pointing to internal structure. |
| 101 | Used to identify internal per thread database. |
| 102 | */ |
| 103 | typedef void *memif_per_thread_main_handle_t; |
| 104 | |
Jakub Grajciar | ecfa2aa | 2018-03-26 11:26:34 +0200 | [diff] [blame] | 105 | /** \brief Memif connection handle |
Jakub Grajciar | 7c5c40d | 2017-08-30 10:13:25 +0200 | [diff] [blame] | 106 | pointer of type void, pointing to internal structure |
| 107 | */ |
| 108 | typedef void *memif_conn_handle_t; |
Jakub Grajciar | ecfa2aa | 2018-03-26 11:26:34 +0200 | [diff] [blame] | 109 | |
Jakub Grajciar | 12df497 | 2019-07-01 14:24:48 +0200 | [diff] [blame] | 110 | /** \brief Memif socket handle |
| 111 | pointer of type void, pointing to internal structure |
| 112 | */ |
| 113 | typedef void *memif_socket_handle_t; |
| 114 | |
Jakub Grajciar | ecfa2aa | 2018-03-26 11:26:34 +0200 | [diff] [blame] | 115 | /** \brief Memif allocator alloc |
| 116 | @param size - requested allocation size |
| 117 | |
| 118 | custom memory allocator: alloc function template |
| 119 | */ |
| 120 | typedef void *(memif_alloc_t) (size_t size); |
| 121 | |
Jakub Grajciar | 93a5dd1 | 2018-08-20 14:26:32 +0200 | [diff] [blame] | 122 | |
| 123 | /** \brief Memif realloc |
| 124 | @param ptr - pointer to memory block |
| 125 | @param size - requested allocation size |
| 126 | |
| 127 | custom memory reallocation |
| 128 | */ |
| 129 | typedef void *(memif_realloc_t) (void *ptr, size_t size); |
| 130 | |
Jakub Grajciar | ecfa2aa | 2018-03-26 11:26:34 +0200 | [diff] [blame] | 131 | /** \brief Memif allocator free |
| 132 | @param size - requested allocation size |
| 133 | |
| 134 | custom memory allocator: free function template |
| 135 | */ |
| 136 | typedef void (memif_free_t) (void *ptr); |
| 137 | |
Jakub Grajciar | 7c5c40d | 2017-08-30 10:13:25 +0200 | [diff] [blame] | 138 | /** |
| 139 | * @defgroup CALLBACKS Callback functions definitions |
Dave Wallace | 6cd396c | 2018-01-23 17:47:02 -0500 | [diff] [blame] | 140 | * @ingroup libmemif |
Jakub Grajciar | 7c5c40d | 2017-08-30 10:13:25 +0200 | [diff] [blame] | 141 | * |
| 142 | * @{ |
| 143 | */ |
| 144 | |
| 145 | /** \brief Memif control file descriptor update (callback function) |
| 146 | @param fd - new file descriptor to watch |
| 147 | @param events - event type(s) to watch for |
Jakub Grajciar | 6f090fa | 2019-11-14 10:47:25 +0100 | [diff] [blame] | 148 | @param private_ctx - libmemif main private context. Is NULL for |
| 149 | libmemif main created by memif_init() |
| 150 | |
Jakub Grajciar | 7c5c40d | 2017-08-30 10:13:25 +0200 | [diff] [blame] | 151 | |
| 152 | This callback is called when there is new fd to watch for events on |
| 153 | or if fd is about to be closed (user mey want to stop watching for events on this fd). |
Jakub Grajciar | 6f090fa | 2019-11-14 10:47:25 +0100 | [diff] [blame] | 154 | Private context is taken from libmemif_main, 'private_ctx' passed to memif_per_thread_init() |
| 155 | or NULL in case of memif_init() |
Jakub Grajciar | 7c5c40d | 2017-08-30 10:13:25 +0200 | [diff] [blame] | 156 | */ |
Jakub Grajciar | 12df497 | 2019-07-01 14:24:48 +0200 | [diff] [blame] | 157 | typedef int (memif_control_fd_update_t) (int fd, uint8_t events, |
| 158 | void *private_ctx); |
Jakub Grajciar | 7c5c40d | 2017-08-30 10:13:25 +0200 | [diff] [blame] | 159 | |
| 160 | /** \brief Memif connection status update (callback function) |
| 161 | @param conn - memif connection handle |
| 162 | @param private_ctx - private context |
| 163 | |
| 164 | Informs user about connection status connected/disconnected. |
| 165 | On connected -> start watching for events on interrupt fd (optional). |
| 166 | */ |
| 167 | typedef int (memif_connection_update_t) (memif_conn_handle_t conn, |
| 168 | void *private_ctx); |
| 169 | |
| 170 | /** \brief Memif interrupt occured (callback function) |
| 171 | @param conn - memif connection handle |
| 172 | @param private_ctx - private context |
| 173 | @param qid - queue id on which interrupt occured |
| 174 | |
| 175 | Called when event is received on interrupt fd. |
| 176 | */ |
| 177 | typedef int (memif_interrupt_t) (memif_conn_handle_t conn, void *private_ctx, |
| 178 | uint16_t qid); |
Jakub Grajciar | 93a5dd1 | 2018-08-20 14:26:32 +0200 | [diff] [blame] | 179 | |
| 180 | /** @} */ |
| 181 | |
| 182 | /** |
| 183 | * @defgroup EXTERNAL_REGION External region APIs |
| 184 | * @ingroup libmemif |
| 185 | * |
| 186 | * @{ |
| 187 | */ |
| 188 | |
| 189 | /** \brief Get external buffer offset (optional) |
| 190 | @param private_ctx - private context |
| 191 | |
| 192 | Find unallocated external buffer and return its offset. |
| 193 | */ |
| 194 | typedef uint32_t (memif_get_external_buffer_offset_t) (void *private_ctx); |
| 195 | |
| 196 | /** \brief Add external region |
| 197 | @param[out] addr - region address |
| 198 | @param size - requested region size |
| 199 | @param fd[out] - file descriptor |
| 200 | @param private_ctx - private context |
| 201 | |
| 202 | Called by slave. Add external region created by client. |
| 203 | */ |
| 204 | typedef int (memif_add_external_region_t) (void * *addr, uint32_t size, |
| 205 | int *fd, void *private_ctx); |
| 206 | |
| 207 | /** \brief Get external region address |
| 208 | @param size - requested region size |
| 209 | @param fd - file descriptor |
| 210 | @param private_ctx - private context |
| 211 | |
| 212 | Called by master. Get region address from client. |
| 213 | |
| 214 | \return region address |
| 215 | */ |
| 216 | typedef void *(memif_get_external_region_addr_t) (uint32_t size, int fd, |
| 217 | void *private_ctx); |
| 218 | |
| 219 | /** \brief Delete external region |
| 220 | @param addr - region address |
| 221 | @param size - region size |
| 222 | @param fd - file descriptor |
| 223 | @param private_ctx - private context |
| 224 | |
| 225 | Delete external region. |
| 226 | */ |
| 227 | typedef int (memif_del_external_region_t) (void *addr, uint32_t size, int fd, |
| 228 | void *private_ctx); |
| 229 | |
| 230 | /** \brief Register external region |
| 231 | @param ar - add external region callback |
| 232 | @param gr - get external region addr callback |
| 233 | @param dr - delete external region callback |
| 234 | @param go - get external buffer offset callback (optional) |
| 235 | */ |
| 236 | void memif_register_external_region (memif_add_external_region_t * ar, |
| 237 | memif_get_external_region_addr_t * gr, |
| 238 | memif_del_external_region_t * dr, |
| 239 | memif_get_external_buffer_offset_t * go); |
| 240 | |
Jakub Grajciar | 17f2a7b | 2019-07-31 14:40:52 +0200 | [diff] [blame] | 241 | /** \brief Register external region |
| 242 | @param pt_main - per thread main handle |
| 243 | @param ar - add external region callback |
| 244 | @param gr - get external region addr callback |
| 245 | @param dr - delete external region callback |
| 246 | @param go - get external buffer offset callback (optional) |
| 247 | */ |
| 248 | void memif_per_thread_register_external_region (memif_per_thread_main_handle_t |
| 249 | pt_main, |
| 250 | memif_add_external_region_t * |
| 251 | ar, |
| 252 | memif_get_external_region_addr_t |
| 253 | * gr, |
| 254 | memif_del_external_region_t * |
| 255 | dr, |
| 256 | memif_get_external_buffer_offset_t |
| 257 | * go); |
| 258 | |
Jakub Grajciar | 7c5c40d | 2017-08-30 10:13:25 +0200 | [diff] [blame] | 259 | /** @} */ |
| 260 | |
| 261 | /** |
| 262 | * @defgroup ARGS_N_BUFS Connection arguments and buffers |
Dave Wallace | 6cd396c | 2018-01-23 17:47:02 -0500 | [diff] [blame] | 263 | * @ingroup libmemif |
Jakub Grajciar | 7c5c40d | 2017-08-30 10:13:25 +0200 | [diff] [blame] | 264 | * |
| 265 | * @{ |
| 266 | */ |
| 267 | |
Jakub Grajciar | ecfa2aa | 2018-03-26 11:26:34 +0200 | [diff] [blame] | 268 | #ifndef _MEMIF_H_ |
| 269 | typedef enum |
| 270 | { |
| 271 | MEMIF_INTERFACE_MODE_ETHERNET = 0, |
| 272 | MEMIF_INTERFACE_MODE_IP = 1, |
| 273 | MEMIF_INTERFACE_MODE_PUNT_INJECT = 2, |
| 274 | } memif_interface_mode_t; |
| 275 | #endif /* _MEMIF_H_ */ |
| 276 | |
Jakub Grajciar | 7c5c40d | 2017-08-30 10:13:25 +0200 | [diff] [blame] | 277 | /** \brief Memif connection arguments |
Jakub Grajciar | 17f2a7b | 2019-07-31 14:40:52 +0200 | [diff] [blame] | 278 | @param socket - Memif socket handle, if NULL default socket will be used. |
| 279 | Default socket is only supported in global database (see memif_init). |
| 280 | Custom database does not create a default socket |
| 281 | (see memif_per_thread_init). |
| 282 | Memif connection is stored in the same database as the socket. |
Paul Vinciguerra | f4fbfd6 | 2020-05-15 23:13:36 -0400 | [diff] [blame] | 283 | @param secret - optional parameter used as interface authentication |
Jakub Grajciar | 7c5c40d | 2017-08-30 10:13:25 +0200 | [diff] [blame] | 284 | @param num_s2m_rings - number of slave to master rings |
| 285 | @param num_m2s_rings - number of master to slave rings |
| 286 | @param buffer_size - size of buffer in shared memory |
| 287 | @param log2_ring_size - logarithm base 2 of ring size |
| 288 | @param is_master - 0 == master, 1 == slave |
| 289 | @param interface_id - id used to identify peer connection |
| 290 | @param interface_name - interface name |
Jakub Grajciar | 7c5c40d | 2017-08-30 10:13:25 +0200 | [diff] [blame] | 291 | @param mode - 0 == ethernet, 1 == ip , 2 == punt/inject |
| 292 | */ |
| 293 | typedef struct |
| 294 | { |
Jakub Grajciar | 12df497 | 2019-07-01 14:24:48 +0200 | [diff] [blame] | 295 | memif_socket_handle_t socket; /*!< default = /run/vpp/memif.sock */ |
Jakub Grajciar | 7c5c40d | 2017-08-30 10:13:25 +0200 | [diff] [blame] | 296 | uint8_t secret[24]; /*!< optional (interface authentication) */ |
| 297 | |
| 298 | uint8_t num_s2m_rings; /*!< default = 1 */ |
| 299 | uint8_t num_m2s_rings; /*!< default = 1 */ |
| 300 | uint16_t buffer_size; /*!< default = 2048 */ |
Jakub Grajciar | ecfa2aa | 2018-03-26 11:26:34 +0200 | [diff] [blame] | 301 | uint8_t log2_ring_size; /*!< default = 10 (1024) */ |
Jakub Grajciar | 7c5c40d | 2017-08-30 10:13:25 +0200 | [diff] [blame] | 302 | uint8_t is_master; |
| 303 | |
Jakub Grajciar | ecfa2aa | 2018-03-26 11:26:34 +0200 | [diff] [blame] | 304 | uint32_t interface_id; |
Jakub Grajciar | 7c5c40d | 2017-08-30 10:13:25 +0200 | [diff] [blame] | 305 | uint8_t interface_name[32]; |
Jakub Grajciar | 7c5c40d | 2017-08-30 10:13:25 +0200 | [diff] [blame] | 306 | memif_interface_mode_t mode:8; |
| 307 | } memif_conn_args_t; |
| 308 | |
| 309 | /*! memif receive mode */ |
| 310 | typedef enum |
| 311 | { |
| 312 | MEMIF_RX_MODE_INTERRUPT = 0, /*!< interrupt mode */ |
| 313 | MEMIF_RX_MODE_POLLING /*!< polling mode */ |
| 314 | } memif_rx_mode_t; |
| 315 | |
| 316 | /** \brief Memif buffer |
| 317 | @param desc_index - ring descriptor index |
Jakub Grajciar | 3744fc7 | 2018-03-29 13:15:10 +0200 | [diff] [blame] | 318 | @param ring - pointer to ring containing descriptor for this buffer |
| 319 | @param len - available length |
Jakub Grajciar | ecfa2aa | 2018-03-26 11:26:34 +0200 | [diff] [blame] | 320 | @param flags - memif buffer flags |
Jakub Grajciar | 7c5c40d | 2017-08-30 10:13:25 +0200 | [diff] [blame] | 321 | @param data - pointer to shared memory data |
| 322 | */ |
| 323 | typedef struct |
| 324 | { |
| 325 | uint16_t desc_index; |
Jakub Grajciar | 3744fc7 | 2018-03-29 13:15:10 +0200 | [diff] [blame] | 326 | void *ring; |
Jakub Grajciar | ecfa2aa | 2018-03-26 11:26:34 +0200 | [diff] [blame] | 327 | uint32_t len; |
Jakub Grajciar | 3744fc7 | 2018-03-29 13:15:10 +0200 | [diff] [blame] | 328 | /** next buffer present (chained buffers) */ |
Jakub Grajciar | ecfa2aa | 2018-03-26 11:26:34 +0200 | [diff] [blame] | 329 | #define MEMIF_BUFFER_FLAG_NEXT (1 << 0) |
Jakub Grajciar | 3744fc7 | 2018-03-29 13:15:10 +0200 | [diff] [blame] | 330 | /** states that buffer is from rx ring */ |
| 331 | #define MEMIF_BUFFER_FLAG_RX (1 << 1) |
Jakub Grajciar | ecfa2aa | 2018-03-26 11:26:34 +0200 | [diff] [blame] | 332 | uint8_t flags; |
Jakub Grajciar | 7c5c40d | 2017-08-30 10:13:25 +0200 | [diff] [blame] | 333 | void *data; |
| 334 | } memif_buffer_t; |
| 335 | /** @} */ |
| 336 | |
| 337 | /** |
| 338 | * @defgroup MEMIF_DETAILS Memif details structs |
Dave Wallace | 6cd396c | 2018-01-23 17:47:02 -0500 | [diff] [blame] | 339 | * @ingroup libmemif |
Jakub Grajciar | 7c5c40d | 2017-08-30 10:13:25 +0200 | [diff] [blame] | 340 | * |
| 341 | * @{ |
| 342 | */ |
| 343 | |
| 344 | /** \brief Memif queue details |
Jakub Grajciar | 93a5dd1 | 2018-08-20 14:26:32 +0200 | [diff] [blame] | 345 | @param region - region index |
Jakub Grajciar | 7c5c40d | 2017-08-30 10:13:25 +0200 | [diff] [blame] | 346 | @param qid - queue id |
Paul Vinciguerra | f4fbfd6 | 2020-05-15 23:13:36 -0400 | [diff] [blame] | 347 | @param ring_size - size of ring buffer in shared memory |
Jakub Grajciar | 8419755 | 2017-11-16 14:02:49 +0100 | [diff] [blame] | 348 | @param flags - ring flags |
| 349 | @param head - ring head pointer |
| 350 | @param tail - ring tail pointer |
Paul Vinciguerra | f4fbfd6 | 2020-05-15 23:13:36 -0400 | [diff] [blame] | 351 | @param buffer_size - buffer size on shared memory |
Jakub Grajciar | 7c5c40d | 2017-08-30 10:13:25 +0200 | [diff] [blame] | 352 | */ |
| 353 | typedef struct |
| 354 | { |
Jakub Grajciar | 93a5dd1 | 2018-08-20 14:26:32 +0200 | [diff] [blame] | 355 | uint8_t region; |
Jakub Grajciar | 7c5c40d | 2017-08-30 10:13:25 +0200 | [diff] [blame] | 356 | uint8_t qid; |
| 357 | uint32_t ring_size; |
Jakub Grajciar | 8419755 | 2017-11-16 14:02:49 +0100 | [diff] [blame] | 358 | /** if set queue is in polling mode, else in interrupt mode */ |
| 359 | #define MEMIF_QUEUE_FLAG_POLLING 1 |
| 360 | uint16_t flags; |
| 361 | uint16_t head; |
| 362 | uint16_t tail; |
Jakub Grajciar | 7c5c40d | 2017-08-30 10:13:25 +0200 | [diff] [blame] | 363 | uint16_t buffer_size; |
Jakub Grajciar | 7c5c40d | 2017-08-30 10:13:25 +0200 | [diff] [blame] | 364 | } memif_queue_details_t; |
| 365 | |
Jakub Grajciar | 93a5dd1 | 2018-08-20 14:26:32 +0200 | [diff] [blame] | 366 | /** \brief Memif region details |
| 367 | @param index - region index |
| 368 | @param addr - region address |
| 369 | @param size - region size |
| 370 | @param fd - file descriptor |
| 371 | @param is_external - if not zero then region is defined by client |
| 372 | */ |
| 373 | typedef struct |
| 374 | { |
| 375 | uint8_t index; |
| 376 | void *addr; |
| 377 | uint32_t size; |
| 378 | int fd; |
| 379 | uint8_t is_external; |
| 380 | } memif_region_details_t; |
| 381 | |
Jakub Grajciar | 7c5c40d | 2017-08-30 10:13:25 +0200 | [diff] [blame] | 382 | /** \brief Memif details |
| 383 | @param if_name - interface name |
| 384 | @param inst_name - application name |
| 385 | @param remote_if_name - peer interface name |
| 386 | @param remote_inst_name - peer application name |
| 387 | @param id - connection id |
| 388 | @param secret - secret |
| 389 | @param role - 0 = master, 1 = slave |
| 390 | @param mode - 0 = ethernet, 1 = ip , 2 = punt/inject |
Jakub Grajciar | 93a5dd1 | 2018-08-20 14:26:32 +0200 | [diff] [blame] | 391 | @param socket_filename - socket filename |
| 392 | @param regions_num - number of regions |
| 393 | @param regions - struct containing region details |
Jakub Grajciar | 7c5c40d | 2017-08-30 10:13:25 +0200 | [diff] [blame] | 394 | @param rx_queues_num - number of receive queues |
| 395 | @param tx_queues_num - number of transmit queues |
| 396 | @param rx_queues - struct containing receive queue details |
| 397 | @param tx_queues - struct containing transmit queue details |
Jakub Grajciar | 568cc46 | 2018-09-05 12:11:35 +0200 | [diff] [blame] | 398 | @param error - error string |
Jakub Grajciar | 7c5c40d | 2017-08-30 10:13:25 +0200 | [diff] [blame] | 399 | @param link_up_down - 1 = up (connected), 2 = down (disconnected) |
| 400 | */ |
| 401 | typedef struct |
| 402 | { |
| 403 | uint8_t *if_name; |
| 404 | uint8_t *inst_name; |
| 405 | uint8_t *remote_if_name; |
| 406 | uint8_t *remote_inst_name; |
| 407 | |
| 408 | uint32_t id; |
| 409 | uint8_t *secret; /* optional */ |
| 410 | uint8_t role; /* 0 = master, 1 = slave */ |
| 411 | uint8_t mode; /* 0 = ethernet, 1 = ip, 2 = punt/inject */ |
| 412 | uint8_t *socket_filename; |
Jakub Grajciar | 93a5dd1 | 2018-08-20 14:26:32 +0200 | [diff] [blame] | 413 | uint8_t regions_num; |
| 414 | memif_region_details_t *regions; |
Jakub Grajciar | 7c5c40d | 2017-08-30 10:13:25 +0200 | [diff] [blame] | 415 | uint8_t rx_queues_num; |
| 416 | uint8_t tx_queues_num; |
| 417 | memif_queue_details_t *rx_queues; |
| 418 | memif_queue_details_t *tx_queues; |
| 419 | |
Jakub Grajciar | 568cc46 | 2018-09-05 12:11:35 +0200 | [diff] [blame] | 420 | uint8_t *error; |
Jakub Grajciar | 7c5c40d | 2017-08-30 10:13:25 +0200 | [diff] [blame] | 421 | uint8_t link_up_down; /* 1 = up, 0 = down */ |
| 422 | } memif_details_t; |
| 423 | /** @} */ |
| 424 | |
| 425 | /** |
| 426 | * @defgroup API_CALLS Api calls |
Dave Wallace | 6cd396c | 2018-01-23 17:47:02 -0500 | [diff] [blame] | 427 | * @ingroup libmemif |
Jakub Grajciar | 7c5c40d | 2017-08-30 10:13:25 +0200 | [diff] [blame] | 428 | * |
| 429 | * @{ |
| 430 | */ |
| 431 | |
Jakub Grajciar | ecfa2aa | 2018-03-26 11:26:34 +0200 | [diff] [blame] | 432 | /** \brief Memif get version |
| 433 | |
| 434 | \return ((MEMIF_VERSION_MAJOR << 8) | MEMIF_VERSION_MINOR) |
| 435 | */ |
| 436 | uint16_t memif_get_version (); |
| 437 | |
Paul Vinciguerra | f4fbfd6 | 2020-05-15 23:13:36 -0400 | [diff] [blame] | 438 | /** \brief Memif get queue event file descriptor |
Jakub Grajciar | 7c5c40d | 2017-08-30 10:13:25 +0200 | [diff] [blame] | 439 | @param conn - memif connection handle |
| 440 | @param qid - queue id |
| 441 | @param[out] fd - returns event file descriptor |
| 442 | |
| 443 | \return memif_err_t |
| 444 | */ |
| 445 | |
| 446 | int memif_get_queue_efd (memif_conn_handle_t conn, uint16_t qid, int *fd); |
| 447 | |
| 448 | /** \brief Memif set rx mode |
| 449 | @param conn - memif connection handle |
| 450 | @param rx_mode - receive mode |
| 451 | @param qid - queue id |
| 452 | |
| 453 | \return memif_err_t |
| 454 | */ |
| 455 | int memif_set_rx_mode (memif_conn_handle_t conn, memif_rx_mode_t rx_mode, |
| 456 | uint16_t qid); |
| 457 | |
| 458 | /** \brief Memif strerror |
| 459 | @param err_code - error code |
| 460 | |
| 461 | Converts error code to error message. |
Jakub Grajciar | 84b8377 | 2019-03-04 12:42:19 +0100 | [diff] [blame] | 462 | |
Jakub Grajciar | 7c5c40d | 2017-08-30 10:13:25 +0200 | [diff] [blame] | 463 | \return Error string |
| 464 | */ |
| 465 | char *memif_strerror (int err_code); |
| 466 | |
| 467 | /** \brief Memif get details |
Paul Vinciguerra | f4fbfd6 | 2020-05-15 23:13:36 -0400 | [diff] [blame] | 468 | @param conn - memif connection handle |
Jakub Grajciar | 7c5c40d | 2017-08-30 10:13:25 +0200 | [diff] [blame] | 469 | @param md - pointer to memif details struct |
| 470 | @param buf - buffer containing details strings |
| 471 | @param buflen - length of buffer |
| 472 | |
| 473 | \return memif_err_t |
| 474 | */ |
| 475 | int memif_get_details (memif_conn_handle_t conn, memif_details_t * md, |
| 476 | char *buf, ssize_t buflen); |
| 477 | |
| 478 | /** \brief Memif initialization |
| 479 | @param on_control_fd_update - if control fd updates inform user to watch new fd |
Jakub Grajciar | 1941871 | 2018-03-13 13:57:50 +0100 | [diff] [blame] | 480 | @param app_name - application name (will be truncated to 32 chars) |
Paul Vinciguerra | f4fbfd6 | 2020-05-15 23:13:36 -0400 | [diff] [blame] | 481 | @param memif_alloc - custom memory allocator, NULL = default |
Jakub Grajciar | 93a5dd1 | 2018-08-20 14:26:32 +0200 | [diff] [blame] | 482 | @param memif_realloc - custom memory reallocation, NULL = default |
Jakub Grajciar | ecfa2aa | 2018-03-26 11:26:34 +0200 | [diff] [blame] | 483 | @param memif_free - custom memory free, NULL = default |
Jakub Grajciar | 7c5c40d | 2017-08-30 10:13:25 +0200 | [diff] [blame] | 484 | |
| 485 | if param on_control_fd_update is set to NULL, |
| 486 | libmemif will handle file descriptor event polling |
| 487 | if a valid callback is set, file descriptor event polling needs to be done by |
| 488 | user application, all file descriptors and event types will be passed in |
| 489 | this callback to user application |
| 490 | |
| 491 | Initialize internal libmemif structures. Create timerfd (used to periodically request connection by |
| 492 | disconnected memifs in slave mode, with no additional API call). This fd is passed to user with memif_control_fd_update_t |
| 493 | timer is inactive at this state. It activates with if there is at least one memif in slave mode. |
| 494 | |
| 495 | \return memif_err_t |
| 496 | */ |
| 497 | int memif_init (memif_control_fd_update_t * on_control_fd_update, |
Jakub Grajciar | ecfa2aa | 2018-03-26 11:26:34 +0200 | [diff] [blame] | 498 | char *app_name, memif_alloc_t * memif_alloc, |
Jakub Grajciar | 93a5dd1 | 2018-08-20 14:26:32 +0200 | [diff] [blame] | 499 | memif_realloc_t * memif_realloc, memif_free_t * memif_free); |
Jakub Grajciar | 7c5c40d | 2017-08-30 10:13:25 +0200 | [diff] [blame] | 500 | |
Jakub Grajciar | 17f2a7b | 2019-07-31 14:40:52 +0200 | [diff] [blame] | 501 | /** \brief Memif per thread initialization |
| 502 | @param pt_main - per thread main handle |
| 503 | @param private_ctx - private context |
| 504 | @param on_control_fd_update - if control fd updates inform user to watch new fd |
| 505 | @param app_name - application name (will be truncated to 32 chars) |
Paul Vinciguerra | f4fbfd6 | 2020-05-15 23:13:36 -0400 | [diff] [blame] | 506 | @param memif_alloc - custom memory allocator, NULL = default |
Jakub Grajciar | 17f2a7b | 2019-07-31 14:40:52 +0200 | [diff] [blame] | 507 | @param memif_realloc - custom memory reallocation, NULL = default |
| 508 | @param memif_free - custom memory free, NULL = default |
| 509 | |
| 510 | Per thread version of memif_init (). |
| 511 | Instead of using global database, creates and initializes unique database, |
| 512 | identified by 'memif_per_thread_main_handle_t'. |
| 513 | |
| 514 | \return memif_err_t |
| 515 | */ |
| 516 | int memif_per_thread_init (memif_per_thread_main_handle_t * pt_main, |
| 517 | void *private_ctx, |
| 518 | memif_control_fd_update_t * on_control_fd_update, |
| 519 | char *app_name, memif_alloc_t * memif_alloc, |
| 520 | memif_realloc_t * memif_realloc, |
| 521 | memif_free_t * memif_free); |
| 522 | |
Jakub Grajciar | 7c5c40d | 2017-08-30 10:13:25 +0200 | [diff] [blame] | 523 | /** \brief Memif cleanup |
| 524 | |
| 525 | Free libmemif internal allocations. |
| 526 | |
| 527 | \return 0 |
| 528 | */ |
| 529 | int memif_cleanup (); |
| 530 | |
Jakub Grajciar | 17f2a7b | 2019-07-31 14:40:52 +0200 | [diff] [blame] | 531 | /** \brief Memif per thread cleanup |
| 532 | @param pt_main - per thread main handle |
| 533 | |
| 534 | Free libmemif internal allocations and sets the handle to NULL. |
| 535 | |
| 536 | \return memif_err_t |
| 537 | */ |
| 538 | int memif_per_thread_cleanup (memif_per_thread_main_handle_t * pt_main); |
| 539 | |
Jakub Grajciar | 7c5c40d | 2017-08-30 10:13:25 +0200 | [diff] [blame] | 540 | /** \brief Memory interface create function |
Jakub Grajciar | 12df497 | 2019-07-01 14:24:48 +0200 | [diff] [blame] | 541 | @param conn - connection handle for client app |
Jakub Grajciar | 7c5c40d | 2017-08-30 10:13:25 +0200 | [diff] [blame] | 542 | @param args - memory interface connection arguments |
| 543 | @param on_connect - inform user about connected status |
| 544 | @param on_disconnect - inform user about disconnected status |
| 545 | @param on_interrupt - informs user about interrupt, if set to null user will not be notified about interrupt, user can use memif_get_queue_efd call to get interrupt fd to poll for events |
Paul Vinciguerra | f4fbfd6 | 2020-05-15 23:13:36 -0400 | [diff] [blame] | 546 | @param private_ctx - private context passed back to user with callback |
Jakub Grajciar | 7c5c40d | 2017-08-30 10:13:25 +0200 | [diff] [blame] | 547 | |
| 548 | Creates memory interface. |
Jakub Grajciar | 84b8377 | 2019-03-04 12:42:19 +0100 | [diff] [blame] | 549 | |
| 550 | SLAVE-MODE - |
Jakub Grajciar | 7c5c40d | 2017-08-30 10:13:25 +0200 | [diff] [blame] | 551 | Start timer that will send events to timerfd. If this fd is passed to memif_control_fd_handler |
| 552 | every disconnected memif in slave mode will send connection request. |
| 553 | On success new fd is passed to user with memif_control_fd_update_t. |
| 554 | |
Jakub Grajciar | 84b8377 | 2019-03-04 12:42:19 +0100 | [diff] [blame] | 555 | MASTER-MODE - |
Paul Vinciguerra | f4fbfd6 | 2020-05-15 23:13:36 -0400 | [diff] [blame] | 556 | Create listener socket and pass fd to user with memif_control_fd_update_t. |
Jakub Grajciar | 7c5c40d | 2017-08-30 10:13:25 +0200 | [diff] [blame] | 557 | If this fd is passed to memif_control_fd_handler accept will be called and |
| 558 | new fd will be passed to user with memif_control_fd_update_t. |
| 559 | |
| 560 | |
| 561 | \return memif_err_t |
| 562 | */ |
| 563 | int memif_create (memif_conn_handle_t * conn, memif_conn_args_t * args, |
| 564 | memif_connection_update_t * on_connect, |
| 565 | memif_connection_update_t * on_disconnect, |
| 566 | memif_interrupt_t * on_interrupt, void *private_ctx); |
| 567 | |
| 568 | /** \brief Memif control file descriptor handler |
Paul Vinciguerra | f4fbfd6 | 2020-05-15 23:13:36 -0400 | [diff] [blame] | 569 | @param fd - file descriptor on which the event occurred |
| 570 | @param events - event type(s) that occurred |
Jakub Grajciar | 7c5c40d | 2017-08-30 10:13:25 +0200 | [diff] [blame] | 571 | |
Paul Vinciguerra | f4fbfd6 | 2020-05-15 23:13:36 -0400 | [diff] [blame] | 572 | If event occurs on any control fd, call memif_control_fd_handler. |
| 573 | Internal - lib will "identify" fd (timerfd, listener, control) and handle event accordingly. |
Jakub Grajciar | 84b8377 | 2019-03-04 12:42:19 +0100 | [diff] [blame] | 574 | |
| 575 | FD-TYPE - |
| 576 | TIMERFD - |
Jakub Grajciar | 7c5c40d | 2017-08-30 10:13:25 +0200 | [diff] [blame] | 577 | Every disconnected memif in slave mode will request connection. |
Jakub Grajciar | 84b8377 | 2019-03-04 12:42:19 +0100 | [diff] [blame] | 578 | LISTENER or CONTROL - |
Jakub Grajciar | 7c5c40d | 2017-08-30 10:13:25 +0200 | [diff] [blame] | 579 | Handle socket messaging (internal connection establishment). |
Jakub Grajciar | 84b8377 | 2019-03-04 12:42:19 +0100 | [diff] [blame] | 580 | INTERRUPT - |
Jakub Grajciar | 7c5c40d | 2017-08-30 10:13:25 +0200 | [diff] [blame] | 581 | Call on_interrupt callback (if set). |
Jakub Grajciar | 84b8377 | 2019-03-04 12:42:19 +0100 | [diff] [blame] | 582 | |
Jakub Grajciar | 7c5c40d | 2017-08-30 10:13:25 +0200 | [diff] [blame] | 583 | \return memif_err_t |
| 584 | |
| 585 | */ |
| 586 | int memif_control_fd_handler (int fd, uint8_t events); |
| 587 | |
Jakub Grajciar | 17f2a7b | 2019-07-31 14:40:52 +0200 | [diff] [blame] | 588 | /** \brief Memif per thread control file descriptor handler |
| 589 | @param pt_main - per thread main handle |
Paul Vinciguerra | f4fbfd6 | 2020-05-15 23:13:36 -0400 | [diff] [blame] | 590 | @param fd - file descriptor on which the event occurred |
| 591 | @param events - event type(s) that occurred |
Jakub Grajciar | 17f2a7b | 2019-07-31 14:40:52 +0200 | [diff] [blame] | 592 | |
| 593 | Per thread version of memif_control_fd_handler. |
| 594 | |
| 595 | \return memif_err_t |
| 596 | |
| 597 | */ |
| 598 | int memif_per_thread_control_fd_handler (memif_per_thread_main_handle_t |
| 599 | pt_main, int fd, uint8_t events); |
| 600 | |
Jakub Grajciar | 7c5c40d | 2017-08-30 10:13:25 +0200 | [diff] [blame] | 601 | /** \brief Memif delete |
| 602 | @param conn - pointer to memif connection handle |
| 603 | |
| 604 | |
| 605 | disconnect session (free queues and regions, close file descriptors, unmap shared memory) |
| 606 | set connection handle to NULL, to avoid possible double free |
| 607 | |
| 608 | \return memif_err_t |
| 609 | */ |
| 610 | int memif_delete (memif_conn_handle_t * conn); |
| 611 | |
Jakub Grajciar | 3744fc7 | 2018-03-29 13:15:10 +0200 | [diff] [blame] | 612 | /** \brief Memif buffer enq tx |
Paul Vinciguerra | f4fbfd6 | 2020-05-15 23:13:36 -0400 | [diff] [blame] | 613 | @param conn - memif connection handle |
| 614 | @param qid - number identifying queue |
Jakub Grajciar | 3744fc7 | 2018-03-29 13:15:10 +0200 | [diff] [blame] | 615 | @param bufs - memif buffers |
Paul Vinciguerra | f4fbfd6 | 2020-05-15 23:13:36 -0400 | [diff] [blame] | 616 | @param count - number of memif buffers to enqueue |
Jakub Grajciar | 3744fc7 | 2018-03-29 13:15:10 +0200 | [diff] [blame] | 617 | @param count_out - returns number of allocated buffers |
| 618 | |
| 619 | Slave is producer of buffers. |
| 620 | If connection handle points to master returns MEMIF_ERR_INVAL_ARG. |
| 621 | |
| 622 | \return memif_err_t |
| 623 | */ |
| 624 | int memif_buffer_enq_tx (memif_conn_handle_t conn, uint16_t qid, |
| 625 | memif_buffer_t * bufs, uint16_t count, |
| 626 | uint16_t * count_out); |
| 627 | |
Jakub Grajciar | 7c5c40d | 2017-08-30 10:13:25 +0200 | [diff] [blame] | 628 | /** \brief Memif buffer alloc |
Paul Vinciguerra | f4fbfd6 | 2020-05-15 23:13:36 -0400 | [diff] [blame] | 629 | @param conn - memif connection handle |
| 630 | @param qid - number identifying queue |
Jakub Grajciar | 7c5c40d | 2017-08-30 10:13:25 +0200 | [diff] [blame] | 631 | @param bufs - memif buffers |
| 632 | @param count - number of memif buffers to allocate |
| 633 | @param count_out - returns number of allocated buffers |
Jakub Grajciar | ecfa2aa | 2018-03-26 11:26:34 +0200 | [diff] [blame] | 634 | @param size - buffer size, may return chained buffers if size > buffer_size |
Jakub Grajciar | 7c5c40d | 2017-08-30 10:13:25 +0200 | [diff] [blame] | 635 | |
| 636 | \return memif_err_t |
| 637 | */ |
| 638 | int memif_buffer_alloc (memif_conn_handle_t conn, uint16_t qid, |
| 639 | memif_buffer_t * bufs, uint16_t count, |
Jakub Grajciar | b467b2a | 2017-09-14 14:12:10 +0200 | [diff] [blame] | 640 | uint16_t * count_out, uint16_t size); |
Jakub Grajciar | 7c5c40d | 2017-08-30 10:13:25 +0200 | [diff] [blame] | 641 | |
Jakub Grajciar | ecfa2aa | 2018-03-26 11:26:34 +0200 | [diff] [blame] | 642 | /** \brief Memif refill ring |
Paul Vinciguerra | f4fbfd6 | 2020-05-15 23:13:36 -0400 | [diff] [blame] | 643 | @param conn - memif connection handle |
| 644 | @param qid - number identifying queue |
Jakub Grajciar | ecfa2aa | 2018-03-26 11:26:34 +0200 | [diff] [blame] | 645 | @param count - number of buffers to be placed on ring |
Jakub Grajciar | 3744fc7 | 2018-03-29 13:15:10 +0200 | [diff] [blame] | 646 | @param headroom - offset the buffer by headroom |
Jakub Grajciar | 7c5c40d | 2017-08-30 10:13:25 +0200 | [diff] [blame] | 647 | |
| 648 | \return memif_err_t |
| 649 | */ |
Jakub Grajciar | ecfa2aa | 2018-03-26 11:26:34 +0200 | [diff] [blame] | 650 | int memif_refill_queue (memif_conn_handle_t conn, uint16_t qid, |
Jakub Grajciar | 3744fc7 | 2018-03-29 13:15:10 +0200 | [diff] [blame] | 651 | uint16_t count, uint16_t headroom); |
Jakub Grajciar | 7c5c40d | 2017-08-30 10:13:25 +0200 | [diff] [blame] | 652 | |
| 653 | /** \brief Memif transmit buffer burst |
Paul Vinciguerra | f4fbfd6 | 2020-05-15 23:13:36 -0400 | [diff] [blame] | 654 | @param conn - memif connection handle |
| 655 | @param qid - number identifying queue |
Jakub Grajciar | 7c5c40d | 2017-08-30 10:13:25 +0200 | [diff] [blame] | 656 | @param bufs - memif buffers |
| 657 | @param count - number of memif buffers to transmit |
| 658 | @param tx - returns number of transmitted buffers |
| 659 | |
| 660 | \return memif_err_t |
| 661 | */ |
| 662 | int memif_tx_burst (memif_conn_handle_t conn, uint16_t qid, |
| 663 | memif_buffer_t * bufs, uint16_t count, uint16_t * tx); |
| 664 | |
| 665 | /** \brief Memif receive buffer burst |
Paul Vinciguerra | f4fbfd6 | 2020-05-15 23:13:36 -0400 | [diff] [blame] | 666 | @param conn - memif connection handle |
| 667 | @param qid - number identifying queue |
Jakub Grajciar | 7c5c40d | 2017-08-30 10:13:25 +0200 | [diff] [blame] | 668 | @param bufs - memif buffers |
| 669 | @param count - number of memif buffers to receive |
| 670 | @param rx - returns number of received buffers |
| 671 | |
Jan Cavojsky | 77a95cd | 2020-03-03 16:25:58 +0100 | [diff] [blame] | 672 | Consume interrupt event for receive queue. |
| 673 | The event is not consumed, if memif_rx_burst fails. |
| 674 | |
Jakub Grajciar | 7c5c40d | 2017-08-30 10:13:25 +0200 | [diff] [blame] | 675 | \return memif_err_t |
| 676 | */ |
| 677 | int memif_rx_burst (memif_conn_handle_t conn, uint16_t qid, |
| 678 | memif_buffer_t * bufs, uint16_t count, uint16_t * rx); |
| 679 | |
| 680 | /** \brief Memif poll event |
| 681 | @param timeout - timeout in seconds |
| 682 | |
Jakub Grajciar | 84b8377 | 2019-03-04 12:42:19 +0100 | [diff] [blame] | 683 | Passive event polling - |
Jakub Grajciar | 7c5c40d | 2017-08-30 10:13:25 +0200 | [diff] [blame] | 684 | timeout = 0 - dont wait for event, check event queue if there is an event and return. |
| 685 | timeout = -1 - wait until event |
| 686 | |
| 687 | \return memif_err_t |
| 688 | */ |
| 689 | int memif_poll_event (int timeout); |
Milan Lenco | 0a47c99 | 2017-10-12 14:19:31 +0200 | [diff] [blame] | 690 | |
Jakub Grajciar | 17f2a7b | 2019-07-31 14:40:52 +0200 | [diff] [blame] | 691 | /** \brief Memif poll event |
| 692 | @param pt_main - per thread main handle |
| 693 | @param timeout - timeout in seconds |
| 694 | |
| 695 | Per thread version of memif_poll_event. |
| 696 | |
| 697 | \return memif_err_t |
| 698 | */ |
| 699 | int memif_per_thread_poll_event (memif_per_thread_main_handle_t pt_main, |
| 700 | int timeout); |
| 701 | |
Milan Lenco | 0a47c99 | 2017-10-12 14:19:31 +0200 | [diff] [blame] | 702 | /** \brief Send signal to stop concurrently running memif_poll_event(). |
| 703 | |
| 704 | The function, however, does not wait for memif_poll_event() to stop. |
Paul Vinciguerra | f4fbfd6 | 2020-05-15 23:13:36 -0400 | [diff] [blame] | 705 | memif_poll_event() may still return simply because an event has occurred |
Milan Lenco | 0a47c99 | 2017-10-12 14:19:31 +0200 | [diff] [blame] | 706 | or the timeout has elapsed, but if called repeatedly in an infinite loop, |
Paul Vinciguerra | f4fbfd6 | 2020-05-15 23:13:36 -0400 | [diff] [blame] | 707 | a canceled memif_poll_event() is guaranteed to return MEMIF_ERR_POLL_CANCEL |
Milan Lenco | 0a47c99 | 2017-10-12 14:19:31 +0200 | [diff] [blame] | 708 | in the shortest possible time. |
| 709 | This feature was not available in the first release. |
| 710 | Use macro MEMIF_HAVE_CANCEL_POLL_EVENT to check if the feature is present. |
| 711 | |
| 712 | \return memif_err_t |
| 713 | */ |
| 714 | #define MEMIF_HAVE_CANCEL_POLL_EVENT 1 |
| 715 | int memif_cancel_poll_event (); |
Jakub Grajciar | 17f2a7b | 2019-07-31 14:40:52 +0200 | [diff] [blame] | 716 | /** \brief Send signal to stop concurrently running memif_poll_event(). |
| 717 | @param pt_main - per thread main handle |
| 718 | |
| 719 | Per thread version of memif_cancel_poll_event. |
| 720 | |
| 721 | \return memif_err_t |
| 722 | */ |
| 723 | int memif_per_thread_cancel_poll_event (memif_per_thread_main_handle_t |
| 724 | pt_main); |
Jakub Grajciar | 84b8377 | 2019-03-04 12:42:19 +0100 | [diff] [blame] | 725 | |
| 726 | /** \brief Set connection request timer value |
| 727 | @param timer - new timer value |
| 728 | |
| 729 | Timer on which all disconnected slaves request connection. |
| 730 | See system call 'timer_settime' man-page. |
| 731 | |
| 732 | \return memif_err_t |
| 733 | */ |
Jakub Grajciar | 12df497 | 2019-07-01 14:24:48 +0200 | [diff] [blame] | 734 | int memif_set_connection_request_timer (struct itimerspec timer); |
Jakub Grajciar | 84b8377 | 2019-03-04 12:42:19 +0100 | [diff] [blame] | 735 | |
Jakub Grajciar | 17f2a7b | 2019-07-31 14:40:52 +0200 | [diff] [blame] | 736 | /** \brief Set connection request timer value |
| 737 | @param pt_main - per thread main handle |
| 738 | @param timer - new timer value |
| 739 | |
| 740 | Per thread version of memif_set_connection_request_timer |
| 741 | |
| 742 | \return memif_err_t |
| 743 | */ |
| 744 | int |
| 745 | memif_per_thread_set_connection_request_timer (memif_per_thread_main_handle_t |
| 746 | pt_main, |
| 747 | struct itimerspec timer); |
| 748 | |
Jakub Grajciar | 84b8377 | 2019-03-04 12:42:19 +0100 | [diff] [blame] | 749 | /** \brief Send connection request |
| 750 | @param conn - memif connection handle |
| 751 | |
| 752 | Only slave interface can request connection. |
| 753 | |
| 754 | \return memif_err_t |
| 755 | */ |
Jakub Grajciar | 12df497 | 2019-07-01 14:24:48 +0200 | [diff] [blame] | 756 | int memif_request_connection (memif_conn_handle_t conn); |
| 757 | |
| 758 | /** \brief Create memif socket |
| 759 | @param sock - socket handle for client app |
| 760 | @param filename - path to socket file |
| 761 | @param private_ctx - private context |
| 762 | |
| 763 | The first time an interface is assigned a socket, its type is determined. |
| 764 | For master role it's 'listener', for slave role it's 'client'. Each interface |
Paul Vinciguerra | f4fbfd6 | 2020-05-15 23:13:36 -0400 | [diff] [blame] | 765 | requires socket of its respective type. Default socket is created if no |
Jakub Grajciar | 12df497 | 2019-07-01 14:24:48 +0200 | [diff] [blame] | 766 | socket handle is passed to memif_create(). It's private context is NULL. |
| 767 | If all interfaces using this socket are deleted, the socket returns |
| 768 | to its default state. |
| 769 | |
| 770 | \return memif_err_t |
| 771 | */ |
Jakub Grajciar | 17f2a7b | 2019-07-31 14:40:52 +0200 | [diff] [blame] | 772 | int memif_create_socket (memif_socket_handle_t * sock, const char *filename, |
| 773 | void *private_ctx); |
| 774 | |
| 775 | /** \brief Create memif socket |
| 776 | @param pt_main - per thread main handle |
| 777 | @param sock - socket handle for client app |
| 778 | @param filename - path to socket file |
| 779 | @param private_ctx - private context |
| 780 | |
Paul Vinciguerra | f4fbfd6 | 2020-05-15 23:13:36 -0400 | [diff] [blame] | 781 | Per thread version of memif_create_socket. |
Jakub Grajciar | 17f2a7b | 2019-07-31 14:40:52 +0200 | [diff] [blame] | 782 | |
| 783 | \return memif_err_t |
| 784 | */ |
| 785 | int memif_per_thread_create_socket (memif_per_thread_main_handle_t pt_main, |
| 786 | memif_socket_handle_t * sock, |
| 787 | const char *filename, void *private_ctx); |
Jakub Grajciar | 12df497 | 2019-07-01 14:24:48 +0200 | [diff] [blame] | 788 | |
| 789 | /** \brief Delete memif socket |
| 790 | @param sock - socket handle for client app |
| 791 | |
| 792 | When trying to free socket in use, socket will not be freed and |
| 793 | MEMIF_ERR_INVAL_ARG is returned. |
| 794 | |
| 795 | \return memif_err_t |
| 796 | */ |
| 797 | int memif_delete_socket (memif_socket_handle_t * sock); |
| 798 | |
Jakub Grajciar | 17f2a7b | 2019-07-31 14:40:52 +0200 | [diff] [blame] | 799 | /** \brief Get socket filename |
| 800 | @param sock - socket handle for client app |
| 801 | |
| 802 | Return constant pointer to socket filename. |
| 803 | |
Paul Vinciguerra | f4fbfd6 | 2020-05-15 23:13:36 -0400 | [diff] [blame] | 804 | \return const char * |
Jakub Grajciar | 17f2a7b | 2019-07-31 14:40:52 +0200 | [diff] [blame] | 805 | */ |
| 806 | const char *memif_get_socket_filename (memif_socket_handle_t sock); |
| 807 | |
Jakub Grajciar | 7c5c40d | 2017-08-30 10:13:25 +0200 | [diff] [blame] | 808 | /** @} */ |
| 809 | |
| 810 | #endif /* _LIBMEMIF_H_ */ |