diff options
Diffstat (limited to 'extras/libmemif/src/libmemif.h')
| -rw-r--r-- | extras/libmemif/src/libmemif.h | 420 |
1 files changed, 181 insertions, 239 deletions
diff --git a/extras/libmemif/src/libmemif.h b/extras/libmemif/src/libmemif.h index 12d2f1e3af4..e604c40b20e 100644 --- a/extras/libmemif/src/libmemif.h +++ b/extras/libmemif/src/libmemif.h @@ -23,7 +23,7 @@ #define _LIBMEMIF_H_ /** Libmemif version. */ -#define LIBMEMIF_VERSION "3.1" +#define LIBMEMIF_VERSION "4.0" /** Default name of application using libmemif. */ #define MEMIF_DEFAULT_APP_NAME "libmemif-app" @@ -35,50 +35,51 @@ /*! Error codes */ typedef enum { - MEMIF_ERR_SUCCESS = 0, /*!< success */ -/* SYSCALL ERRORS */ - MEMIF_ERR_SYSCALL, /*!< other syscall error */ - MEMIF_ERR_CONNREFUSED, /*!< connection refused */ - MEMIF_ERR_ACCES, /*!< permission denied */ - MEMIF_ERR_NO_FILE, /*!< file does not exist */ - MEMIF_ERR_FILE_LIMIT, /*!< system open file limit */ - MEMIF_ERR_PROC_FILE_LIMIT, /*!< process open file limit */ - MEMIF_ERR_ALREADY, /*!< connection already requested */ - MEMIF_ERR_AGAIN, /*!< fd is not socket, or operation would block */ - MEMIF_ERR_BAD_FD, /*!< invalid fd */ - MEMIF_ERR_NOMEM, /*!< out of memory */ -/* LIBMEMIF ERRORS */ - MEMIF_ERR_INVAL_ARG, /*!< invalid argument */ - MEMIF_ERR_NOCONN, /*!< handle points to no connection */ - MEMIF_ERR_CONN, /*!< handle points to existing connection */ - MEMIF_ERR_CB_FDUPDATE, /*!< user defined callback memif_control_fd_update_t error */ - MEMIF_ERR_FILE_NOT_SOCK, /*!< file specified by socket filename - exists, but it's not socket */ - MEMIF_ERR_NO_SHMFD, /*!< missing shm fd */ - MEMIF_ERR_COOKIE, /*!< wrong cookie on ring */ - MEMIF_ERR_NOBUF_RING, /*!< ring buffer full */ - MEMIF_ERR_NOBUF, /*!< not enough memif buffers */ - MEMIF_ERR_NOBUF_DET, /*!< memif details needs larger buffer */ - MEMIF_ERR_INT_WRITE, /*!< send interrupt error */ - MEMIF_ERR_MFMSG, /*!< malformed msg received */ - MEMIF_ERR_QID, /*!< invalid queue id */ -/* MEMIF PROTO ERRORS */ - MEMIF_ERR_PROTO, /*!< incompatible protocol version */ - MEMIF_ERR_ID, /*!< unmatched interface id */ - MEMIF_ERR_ACCSLAVE, /*!< slave cannot accept connection requests */ - MEMIF_ERR_ALRCONN, /*!< memif is already connected */ - MEMIF_ERR_MODE, /*!< mode mismatch */ - MEMIF_ERR_SECRET, /*!< secret mismatch */ - MEMIF_ERR_NOSECRET, /*!< secret required */ - MEMIF_ERR_MAXREG, /*!< max region limit reached */ - MEMIF_ERR_MAXRING, /*!< max ring limit reached */ - MEMIF_ERR_NO_INTFD, /*!< missing interrupt fd */ - MEMIF_ERR_DISCONNECT, /*!< disconnect received */ - MEMIF_ERR_DISCONNECTED, /*!< peer interface disconnected */ - MEMIF_ERR_UNKNOWN_MSG, /*!< unknown message type */ - MEMIF_ERR_POLL_CANCEL, /*!< memif_poll_event() was cancelled */ - MEMIF_ERR_MAX_RING, /*!< too large ring size */ - MEMIF_ERR_PRIVHDR, /*!< private hdrs not supported */ + MEMIF_ERR_SUCCESS = 0, /*!< success */ + /* SYSCALL ERRORS */ + MEMIF_ERR_SYSCALL, /*!< other syscall error */ + MEMIF_ERR_CONNREFUSED, /*!< connection refused */ + MEMIF_ERR_ACCES, /*!< permission denied */ + MEMIF_ERR_NO_FILE, /*!< file does not exist */ + MEMIF_ERR_FILE_LIMIT, /*!< system open file limit */ + MEMIF_ERR_PROC_FILE_LIMIT, /*!< process open file limit */ + MEMIF_ERR_ALREADY, /*!< connection already requested */ + MEMIF_ERR_AGAIN, /*!< fd is not socket, or operation would block */ + MEMIF_ERR_BAD_FD, /*!< invalid fd */ + MEMIF_ERR_NOMEM, /*!< out of memory */ + /* LIBMEMIF ERRORS */ + MEMIF_ERR_INVAL_ARG, /*!< invalid argument */ + MEMIF_ERR_NOCONN, /*!< handle points to no connection */ + MEMIF_ERR_CONN, /*!< handle points to existing connection */ + MEMIF_ERR_CB_FDUPDATE, /*!< user defined callback memif_control_fd_update_t + error */ + MEMIF_ERR_FILE_NOT_SOCK, /*!< file specified by socket path + exists, but it's not socket */ + MEMIF_ERR_NO_SHMFD, /*!< missing shm fd */ + MEMIF_ERR_COOKIE, /*!< wrong cookie on ring */ + MEMIF_ERR_NOBUF_RING, /*!< ring buffer full */ + MEMIF_ERR_NOBUF, /*!< not enough memif buffers */ + MEMIF_ERR_NOBUF_DET, /*!< memif details needs larger buffer */ + MEMIF_ERR_INT_WRITE, /*!< send interrupt error */ + MEMIF_ERR_MFMSG, /*!< malformed msg received */ + MEMIF_ERR_QID, /*!< invalid queue id */ + /* MEMIF PROTO ERRORS */ + MEMIF_ERR_PROTO, /*!< incompatible protocol version */ + MEMIF_ERR_ID, /*!< unmatched interface id */ + MEMIF_ERR_ACCSLAVE, /*!< slave cannot accept connection requests */ + MEMIF_ERR_ALRCONN, /*!< memif is already connected */ + MEMIF_ERR_MODE, /*!< mode mismatch */ + MEMIF_ERR_SECRET, /*!< secret mismatch */ + MEMIF_ERR_NOSECRET, /*!< secret required */ + MEMIF_ERR_MAXREG, /*!< max region limit reached */ + MEMIF_ERR_MAXRING, /*!< max ring limit reached */ + MEMIF_ERR_NO_INTFD, /*!< missing interrupt fd */ + MEMIF_ERR_DISCONNECT, /*!< disconnect received */ + MEMIF_ERR_DISCONNECTED, /*!< peer interface disconnected */ + MEMIF_ERR_UNKNOWN_MSG, /*!< unknown message type */ + MEMIF_ERR_POLL_CANCEL, /*!< memif_poll_event() was cancelled */ + MEMIF_ERR_MAX_RING, /*!< too large ring size */ + MEMIF_ERR_PRIVHDR, /*!< private hdrs not supported */ } memif_err_t; /** @@ -87,23 +88,24 @@ typedef enum * @{ */ -/** user needs to set events that occurred on fd and pass them to memif_control_fd_handler */ -#define MEMIF_FD_EVENT_READ (1 << 0) -#define MEMIF_FD_EVENT_WRITE (1 << 1) -/** inform libmemif that error occurred on fd */ -#define MEMIF_FD_EVENT_ERROR (1 << 2) -/** if set, informs that fd is going to be closed (user may want to stop watching for events on this fd) */ -#define MEMIF_FD_EVENT_DEL (1 << 3) -/** update events */ -#define MEMIF_FD_EVENT_MOD (1 << 4) +/** \brief Memif fd events + * User needs to set events that occurred on fd and pass them to + * memif_control_fd_handler + */ +typedef enum memif_fd_event_type +{ + MEMIF_FD_EVENT_READ = 1, /* 00001 */ + MEMIF_FD_EVENT_WRITE = 2, /* 00010 */ + /** inform libmemif that error occurred on fd */ + MEMIF_FD_EVENT_ERROR = 4, /* 00100 */ + /** if set, informs that fd is going to be closed (user may want to stop + watching for events on this fd) */ + MEMIF_FD_EVENT_DEL = 8, /* 01000 */ + /** update events */ + MEMIF_FD_EVENT_MOD = 16 /* 10000 */ +} memif_fd_event_type_t; /** @} */ -/** \brief Memif per thread main handle - Pointer of type void, pointing to internal structure. - Used to identify internal per thread database. -*/ -typedef void *memif_per_thread_main_handle_t; - /** \brief Memif connection handle pointer of type void, pointing to internal structure */ @@ -144,19 +146,29 @@ typedef void (memif_free_t) (void *ptr); * @{ */ +/** \brief Memif fd event + @param fd - interrupt file descriptor + @param type - memif fd event type + @param private_ctx - private event data +*/ +typedef struct memif_fd_event +{ + int fd; + memif_fd_event_type_t type; + void *private_ctx; +} memif_fd_event_t; + /** \brief Memif control file descriptor update (callback function) - @param fd - new file descriptor to watch - @param events - event type(s) to watch for - @param private_ctx - libmemif main private context. Is NULL for - libmemif main created by memif_init() + @param fde - memif fd event + @param private_ctx - private context of socket this fd belongs to This callback is called when there is new fd to watch for events on - or if fd is about to be closed (user mey want to stop watching for events on this fd). - Private context is taken from libmemif_main, 'private_ctx' passed to memif_per_thread_init() - or NULL in case of memif_init() + or if fd is about to be closed (user mey want to stop watching for events + on this fd). Private context is taken from libmemif_main, 'private_ctx' + passed to memif_per_thread_init() or NULL in case of memif_init() */ -typedef int (memif_control_fd_update_t) (int fd, uint8_t events, +typedef int (memif_control_fd_update_t) (memif_fd_event_t fde, void *private_ctx); /** \brief Memif connection status update (callback function) @@ -176,8 +188,8 @@ typedef int (memif_connection_update_t) (memif_conn_handle_t conn, Called when event is received on interrupt fd. */ -typedef int (memif_interrupt_t) (memif_conn_handle_t conn, void *private_ctx, - uint16_t qid); +typedef int (memif_on_interrupt_t) (memif_conn_handle_t conn, + void *private_ctx, uint16_t qid); /** @} */ @@ -235,10 +247,11 @@ typedef int (memif_del_external_region_t) (void *addr, uint32_t size, int fd, @param dr - delete external region callback @param go - get external buffer offset callback (optional) */ -void memif_register_external_region (memif_add_external_region_t * ar, - memif_get_external_region_addr_t * gr, - memif_del_external_region_t * dr, - memif_get_external_buffer_offset_t * go); +void memif_register_external_region (memif_socket_handle_t sock, + memif_add_external_region_t *ar, + memif_get_external_region_addr_t *gr, + memif_del_external_region_t *dr, + memif_get_external_buffer_offset_t *go); /** \brief Register external region @param pt_main - per thread main handle @@ -276,6 +289,37 @@ typedef enum } memif_interface_mode_t; #endif /* _MEMIF_H_ */ +/** \brief Memif socket arguments + @param path - UNIX socket path, supports abstract socket (have '\0' or '@' + as the first char of the path) + @param app_name - application name + @param connection_request_timer - automaticaly request connection each time + this timer expires, must be non-zero to enable this feature + @param on_control_fd_update - if control fd updates inform user to watch + new fd + @param alloc - custom memory allocator, NULL = default + @param realloc - custom memory reallocation, NULL = default + @param free - custom memory free, NULL = default + + If param on_control_fd_update is set to NULL, + libmemif will handle file descriptor event polling + if a valid callback is set, file descriptor event polling needs to be done + by user application, all file descriptors and event types will be passed in + this callback to user application +*/ +typedef struct memif_socket_args +{ + char path[108]; + char app_name[32]; + + struct itimerspec connection_request_timer; + + memif_control_fd_update_t *on_control_fd_update; + memif_alloc_t *alloc; + memif_realloc_t *realloc; + memif_free_t *free; +} memif_socket_args_t; + /** \brief Memif connection arguments @param socket - Memif socket handle, if NULL default socket will be used. Default socket is only supported in global database (see memif_init). @@ -353,7 +397,7 @@ typedef struct typedef struct { uint8_t region; - uint8_t qid; + uint16_t qid; uint32_t ring_size; /** if set queue is in polling mode, else in interrupt mode */ #define MEMIF_QUEUE_FLAG_POLLING 1 @@ -388,7 +432,7 @@ typedef struct @param secret - secret @param role - 0 = master, 1 = slave @param mode - 0 = ethernet, 1 = ip , 2 = punt/inject - @param socket_filename - socket filename + @param socket_path - socket path @param regions_num - number of regions @param regions - struct containing region details @param rx_queues_num - number of receive queues @@ -409,7 +453,7 @@ typedef struct uint8_t *secret; /* optional */ uint8_t role; /* 0 = master, 1 = slave */ uint8_t mode; /* 0 = ethernet, 1 = ip, 2 = punt/inject */ - uint8_t *socket_filename; + uint8_t *socket_path; uint8_t regions_num; memif_region_details_t *regions; uint8_t rx_queues_num; @@ -433,7 +477,12 @@ typedef struct \return ((MEMIF_VERSION_MAJOR << 8) | MEMIF_VERSION_MINOR) */ -uint16_t memif_get_version (); +uint16_t memif_get_version (void); + +/** \brief Get memif version as string + \return major.minor +*/ +const char *memif_get_version_str (void); /** \brief Memif get queue event file descriptor @param conn - memif connection handle @@ -475,68 +524,6 @@ char *memif_strerror (int err_code); int memif_get_details (memif_conn_handle_t conn, memif_details_t * md, char *buf, ssize_t buflen); -/** \brief Memif initialization - @param on_control_fd_update - if control fd updates inform user to watch new fd - @param app_name - application name (will be truncated to 32 chars) - @param memif_alloc - custom memory allocator, NULL = default - @param memif_realloc - custom memory reallocation, NULL = default - @param memif_free - custom memory free, NULL = default - - if param on_control_fd_update is set to NULL, - libmemif will handle file descriptor event polling - if a valid callback is set, file descriptor event polling needs to be done by - user application, all file descriptors and event types will be passed in - this callback to user application - - Initialize internal libmemif structures. Create timerfd (used to periodically request connection by - disconnected memifs in slave mode, with no additional API call). This fd is passed to user with memif_control_fd_update_t - timer is inactive at this state. It activates with if there is at least one memif in slave mode. - - \return memif_err_t -*/ -int memif_init (memif_control_fd_update_t * on_control_fd_update, - char *app_name, memif_alloc_t * memif_alloc, - memif_realloc_t * memif_realloc, memif_free_t * memif_free); - -/** \brief Memif per thread initialization - @param pt_main - per thread main handle - @param private_ctx - private context - @param on_control_fd_update - if control fd updates inform user to watch new fd - @param app_name - application name (will be truncated to 32 chars) - @param memif_alloc - custom memory allocator, NULL = default - @param memif_realloc - custom memory reallocation, NULL = default - @param memif_free - custom memory free, NULL = default - - Per thread version of memif_init (). - Instead of using global database, creates and initializes unique database, - identified by 'memif_per_thread_main_handle_t'. - - \return memif_err_t -*/ -int memif_per_thread_init (memif_per_thread_main_handle_t * pt_main, - void *private_ctx, - memif_control_fd_update_t * on_control_fd_update, - char *app_name, memif_alloc_t * memif_alloc, - memif_realloc_t * memif_realloc, - memif_free_t * memif_free); - -/** \brief Memif cleanup - - Free libmemif internal allocations. - - \return 0 -*/ -int memif_cleanup (); - -/** \brief Memif per thread cleanup - @param pt_main - per thread main handle - - Free libmemif internal allocations and sets the handle to NULL. - - \return memif_err_t -*/ -int memif_per_thread_cleanup (memif_per_thread_main_handle_t * pt_main); - /** \brief Memory interface create function @param conn - connection handle for client app @param args - memory interface connection arguments @@ -560,43 +547,19 @@ int memif_per_thread_cleanup (memif_per_thread_main_handle_t * pt_main); \return memif_err_t */ -int memif_create (memif_conn_handle_t * conn, memif_conn_args_t * args, - memif_connection_update_t * on_connect, - memif_connection_update_t * on_disconnect, - memif_interrupt_t * on_interrupt, void *private_ctx); +int memif_create (memif_conn_handle_t *conn, memif_conn_args_t *args, + memif_connection_update_t *on_connect, + memif_connection_update_t *on_disconnect, + memif_on_interrupt_t *on_interrupt, void *private_ctx); /** \brief Memif control file descriptor handler - @param fd - file descriptor on which the event occurred + @param ptr - pointer to event data @param events - event type(s) that occurred - If event occurs on any control fd, call memif_control_fd_handler. - Internal - lib will "identify" fd (timerfd, listener, control) and handle event accordingly. - - FD-TYPE - - TIMERFD - - Every disconnected memif in slave mode will request connection. - LISTENER or CONTROL - - Handle socket messaging (internal connection establishment). - INTERRUPT - - Call on_interrupt callback (if set). - - \return memif_err_t - -*/ -int memif_control_fd_handler (int fd, uint8_t events); - -/** \brief Memif per thread control file descriptor handler - @param pt_main - per thread main handle - @param fd - file descriptor on which the event occurred - @param events - event type(s) that occurred - - Per thread version of memif_control_fd_handler. - \return memif_err_t */ -int memif_per_thread_control_fd_handler (memif_per_thread_main_handle_t - pt_main, int fd, uint8_t events); +int memif_control_fd_handler (void *ptr, memif_fd_event_type_t events); /** \brief Memif delete @param conn - pointer to memif connection handle @@ -700,28 +663,19 @@ int memif_rx_burst (memif_conn_handle_t conn, uint16_t qid, memif_buffer_t * bufs, uint16_t count, uint16_t * rx); /** \brief Memif poll event + @param sock - socket to poll events on @param timeout - timeout in seconds Passive event polling - - timeout = 0 - dont wait for event, check event queue if there is an event and return. - timeout = -1 - wait until event + timeout = 0 - dont wait for event, check event queue if there is an event + and return. timeout = -1 - wait until event \return memif_err_t */ -int memif_poll_event (int timeout); - -/** \brief Memif per thread poll event - @param pt_main - per thread main handle - @param timeout - timeout in seconds - - Per thread version of memif_poll_event. - - \return memif_err_t -*/ -int memif_per_thread_poll_event (memif_per_thread_main_handle_t pt_main, - int timeout); +int memif_poll_event (memif_socket_handle_t sock, int timeout); /** \brief Send signal to stop concurrently running memif_poll_event(). + @param sock - stop polling on this socket The function, however, does not wait for memif_poll_event() to stop. memif_poll_event() may still return simply because an event has occurred @@ -734,39 +688,7 @@ int memif_per_thread_poll_event (memif_per_thread_main_handle_t pt_main, \return memif_err_t */ #define MEMIF_HAVE_CANCEL_POLL_EVENT 1 -int memif_cancel_poll_event (); -/** \brief Send signal to stop concurrently running memif_poll_event(). - @param pt_main - per thread main handle - - Per thread version of memif_cancel_poll_event. - - \return memif_err_t -*/ -int memif_per_thread_cancel_poll_event (memif_per_thread_main_handle_t - pt_main); - -/** \brief Set connection request timer value - @param timer - new timer value - - Timer on which all disconnected slaves request connection. - See system call 'timer_settime' man-page. - - \return memif_err_t -*/ -int memif_set_connection_request_timer (struct itimerspec timer); - -/** \brief Set connection request timer value - @param pt_main - per thread main handle - @param timer - new timer value - - Per thread version of memif_set_connection_request_timer - - \return memif_err_t -*/ -int -memif_per_thread_set_connection_request_timer (memif_per_thread_main_handle_t - pt_main, - struct itimerspec timer); +int memif_cancel_poll_event (memif_socket_handle_t sock); /** \brief Send connection request @param conn - memif connection handle @@ -779,34 +701,27 @@ int memif_request_connection (memif_conn_handle_t conn); /** \brief Create memif socket @param sock - socket handle for client app - @param filename - path to socket file + @param args - memif socket arguments @param private_ctx - private context The first time an interface is assigned a socket, its type is determined. - For master role it's 'listener', for slave role it's 'client'. Each interface - requires socket of its respective type. Default socket is created if no - socket handle is passed to memif_create(). It's private context is NULL. - If all interfaces using this socket are deleted, the socket returns - to its default state. + For master role it's 'listener', for slave role it's 'client'. Each + interface requires socket of its respective type. Default socket is created + if no socket handle is passed to memif_create(). It's private context is + NULL. If all interfaces using this socket are deleted, the socket returns to + its default state. \return memif_err_t */ -int memif_create_socket (memif_socket_handle_t * sock, const char *filename, - void *private_ctx); +int memif_create_socket (memif_socket_handle_t *sock, + memif_socket_args_t *args, void *private_ctx); -/** \brief Create memif socket - @param pt_main - per thread main handle - @param sock - socket handle for client app - @param filename - path to socket file - @param private_ctx - private context - - Per thread version of memif_create_socket. +/** \brief Get memif socket handle from connection + @param conn - memif connection handle - \return memif_err_t + \return memif_socket_handle_t */ -int memif_per_thread_create_socket (memif_per_thread_main_handle_t pt_main, - memif_socket_handle_t * sock, - const char *filename, void *private_ctx); +memif_socket_handle_t memif_get_socket_handle (memif_conn_handle_t conn); /** \brief Delete memif socket @param sock - socket handle for client app @@ -818,14 +733,41 @@ int memif_per_thread_create_socket (memif_per_thread_main_handle_t pt_main, */ int memif_delete_socket (memif_socket_handle_t * sock); -/** \brief Get socket filename +/** \brief Get socket path @param sock - socket handle for client app - Return constant pointer to socket filename. + Return constant pointer to socket path. \return const char * */ -const char *memif_get_socket_filename (memif_socket_handle_t sock); +const char *memif_get_socket_path (memif_socket_handle_t sock); + +/** \brief Get listener file descriptor + @param sock - memif socket handle + + \return listener fd +*/ +int memif_get_listener_fd (memif_socket_handle_t sock); + +/** \brief Set listener file descriptor + @param sock - memif socket handle + @param if - file descriptor + + \return memif_err_t +*/ +int memif_set_listener_fd (memif_socket_handle_t sock, int fd); + +/** \brief Set connection request timer value + @param sock - memif socket handle + @param timer - new timer value + + Timer on which all disconnected slaves request connection. + If the timer doesn't exist (timerspec is 0) create new timer. + See system call 'timer_settime' man-page. + \return memif_err_t +*/ +int memif_set_connection_request_timer (memif_socket_handle_t sock, + struct itimerspec timer); /** @} */ |