TCP socket abstraction layer. More...
Data Structures | |
| struct | spdk_sock_request |
| Anywhere this struct is used, an iovec array is assumed to immediately follow the last member in memory, without any padding. More... | |
| struct | spdk_sock_request::__sock_request_internal |
| struct | spdk_sock_request_opts |
| struct | spdk_sock_impl_opts |
| SPDK socket implementation options. More... | |
| struct | spdk_sock_opts |
| Spdk socket initialization options. More... | |
| struct | spdk_sock_initialize_opts |
| Options for the socket library. More... | |
| struct | spdk_sock_group_opts |
Macros | |
| #define | SPDK_SOCK_REQUEST_IOV(req, i) ((struct iovec *)(((uint8_t *)req + sizeof(struct spdk_sock_request)) + (sizeof(struct iovec) * i))) |
| #define | SPDK_TLS_VERSION_1_1 11 |
| #define | SPDK_TLS_VERSION_1_2 12 |
| #define | SPDK_TLS_VERSION_1_3 13 |
Typedefs | |
| typedef void(* | spdk_sock_connect_cb_fn) (void *cb_arg, int status) |
| Signature for callback function invoked when a connection is completed. | |
| typedef void(* | spdk_sock_cb) (void *arg, struct spdk_sock_group *group, struct spdk_sock *sock) |
| Callback function for spdk_sock_group_opts. | |
Enumerations | |
| enum | spdk_placement_mode { PLACEMENT_NONE , PLACEMENT_NAPI , PLACEMENT_CPU , PLACEMENT_MARK } |
Functions | |
| SPDK_STATIC_ASSERT (sizeof(struct spdk_sock_request)==64, "Incorrect size.") | |
| SPDK_STATIC_ASSERT (sizeof(struct spdk_sock_request_opts)==24, "Incorrect size.") | |
| SPDK_STATIC_ASSERT (sizeof(struct spdk_sock_opts)==80, "Incorrect size") | |
| void | spdk_sock_get_default_initialize_opts (struct spdk_sock_initialize_opts *opts, size_t opts_size) |
| Initialize the default value of socket initialization opts. | |
| int | spdk_sock_initialize (struct spdk_sock_initialize_opts *opts) |
| Initialize the socket module. | |
| void | spdk_sock_get_default_opts (struct spdk_sock_opts *opts) |
| Initialize the default value of opts. | |
| int | spdk_sock_getaddr (struct spdk_sock *sock, char *saddr, int slen, uint16_t *sport, char *caddr, int clen, uint16_t *cport) |
| Get client and server addresses of the given socket. | |
| const char * | spdk_sock_get_impl_name (struct spdk_sock *sock) |
| Get socket implementation name. | |
| struct spdk_sock * | spdk_sock_connect (const char *ip, int port, struct spdk_sock_opts *opts, spdk_sock_connect_cb_fn cb_fn, void *cb_arg) |
| Create a socket using the specific sock implementation, initiate the socket connection to the specified address and port (of the server), and then return the socket. | |
| struct spdk_sock * | spdk_sock_listen (const char *ip, int port, struct spdk_sock_opts *opts) |
| Create a socket using the specific sock implementation, bind the socket to the specified address and port and listen on the socket, and then return the socket. | |
| struct spdk_sock * | spdk_sock_accept (struct spdk_sock *sock) |
| Accept a new connection from a client on the specified socket and return a socket structure which holds the connection. | |
| void | spdk_sock_set_user_ctx (struct spdk_sock *sock, void *user_ctx) |
| Change the user context callback argument passed to spdk_sock_cb for this socket. | |
| const char * | spdk_sock_get_interface_name (struct spdk_sock *sock) |
| Gets the name of the network interface of the local port for the socket. | |
| int32_t | spdk_sock_get_numa_id (struct spdk_sock *sock) |
| Gets the NUMA node ID for the network interface of the local port for the TCP socket. | |
| int | spdk_sock_close (struct spdk_sock **sock) |
| Close a socket. | |
| int | spdk_sock_flush (struct spdk_sock *sock) |
| Flush a socket from data gathered in previous writev_async calls. | |
| ssize_t | spdk_sock_recv (struct spdk_sock *sock, void *buf, size_t len) |
| Receive a message from the given socket. | |
| ssize_t | spdk_sock_writev (struct spdk_sock *sock, struct iovec *iov, int iovcnt) |
| Write message to the given socket from the I/O vector array. | |
| void | spdk_sock_writev_async (struct spdk_sock *sock, struct spdk_sock_request *req) |
| Write data to the given socket asynchronously, calling the provided callback when the data has been written. | |
| void | spdk_sock_writev_async_ext (struct spdk_sock *sock, struct spdk_sock_request *req, const struct spdk_sock_request_opts *opts) |
| Write data to the given socket asynchronously with optional request metadata. | |
| ssize_t | spdk_sock_readv (struct spdk_sock *sock, struct iovec *iov, int iovcnt) |
| Read message from the given socket to the I/O vector array. | |
| int | spdk_sock_recv_next (struct spdk_sock *sock, void **buf, struct spdk_sock_buf_token **token) |
| Receive the next portion of the stream from the socket. | |
| bool | spdk_sock_impl_supports_recv_next (const char *impl_name) |
| Check whether a socket implementation supports spdk_sock_recv_next(). | |
| int | spdk_sock_group_release_buf (struct spdk_sock_group *group, void *buf, struct spdk_sock_buf_token *token) |
| Release a buffer obtained via spdk_sock_recv_next() back to the receive pool of the group that owns it, identified by the group rather than the socket it was received on. | |
| int | spdk_sock_set_recvlowat (struct spdk_sock *sock, int nbytes) |
| Set the value used to specify the low water mark (in bytes) for this socket. | |
| int | spdk_sock_set_recvbuf (struct spdk_sock *sock, int sz) |
| Set receive buffer size for the given socket. | |
| int | spdk_sock_set_sendbuf (struct spdk_sock *sock, int sz) |
| Set send buffer size for the given socket. | |
| bool | spdk_sock_is_ipv6 (struct spdk_sock *sock) |
| Check whether the address of socket is ipv6. | |
| bool | spdk_sock_is_ipv4 (struct spdk_sock *sock) |
| Check whether the address of socket is ipv4. | |
| bool | spdk_sock_is_connected (struct spdk_sock *sock) |
| Check whether the socket is currently connected. | |
| struct spdk_sock_group * | spdk_sock_group_create (const struct spdk_sock_group_opts *opts) |
| Create a new socket group. | |
| void * | spdk_sock_group_get_ctx (struct spdk_sock_group *sock_group) |
| Get the ctx of the sock group. | |
| int | spdk_sock_group_add_sock (struct spdk_sock_group *group, struct spdk_sock *sock) |
| Add a socket to the group. | |
| int | spdk_sock_group_remove_sock (struct spdk_sock_group *group, struct spdk_sock *sock) |
| Remove a socket from the group. | |
| int | spdk_sock_group_poll (struct spdk_sock_group *group) |
| Poll incoming events for each registered socket. | |
| int | spdk_sock_group_close (struct spdk_sock_group **group) |
| Close all registered sockets of the group and then remove the group. | |
| int | spdk_sock_get_optimal_sock_group (struct spdk_sock *sock, struct spdk_sock_group **group, struct spdk_sock_group *hint) |
| Get the optimal sock group for this sock. | |
| int | spdk_sock_impl_get_opts (const char *impl_name, struct spdk_sock_impl_opts *opts, size_t *len) |
| Get current socket implementation options. | |
| int | spdk_sock_impl_set_opts (const char *impl_name, const struct spdk_sock_impl_opts *opts, size_t len) |
| Set socket implementation options. | |
| int | spdk_sock_set_default_impl (const char *impl_name) |
| Set the given sock implementation to be used as the default one. | |
| const char * | spdk_sock_get_default_impl (void) |
| Get the name of the current default implementation. | |
| void | spdk_sock_write_config_json (struct spdk_json_write_ctx *w) |
| Write socket subsystem configuration into provided JSON context. | |
| int | spdk_sock_group_get_interruptfd (struct spdk_sock_group *group) |
| Obtain an fd that becomes ready when one of the sockets in this group is ready. | |
| struct spdk_memory_domain * | spdk_sock_get_memory_domain (struct spdk_sock *sock) |
| Get memory domain associated with the socket, or NULL if the socket module doesn't support memory domains. | |
TCP socket abstraction layer.
| typedef void(* spdk_sock_cb) (void *arg, struct spdk_sock_group *group, struct spdk_sock *sock) |
Callback function for spdk_sock_group_opts.
| arg | Socket argument for the callback function. |
| group | Socket group. |
| sock | Socket. |
| typedef void(* spdk_sock_connect_cb_fn) (void *cb_arg, int status) |
Signature for callback function invoked when a connection is completed.
| cb_arg | Context specified by spdk_sock_connect. |
| status | 0 on success, negative errno value on failure. |
| struct spdk_sock * spdk_sock_accept | ( | struct spdk_sock * | sock | ) |
Accept a new connection from a client on the specified socket and return a socket structure which holds the connection.
The new socket will belong to the same spdk_sock_group that the listen socket belongs to. The group can be changed using spdk_sock_group_remove_sock and spdk_sock_group_add_sock.
| sock | Listening socket. |
| int spdk_sock_close | ( | struct spdk_sock ** | sock | ) |
Close a socket.
This will automatically remove the socket from its group.
| sock | Socket to close. |
| struct spdk_sock * spdk_sock_connect | ( | const char * | ip, |
| int | port, | ||
| struct spdk_sock_opts * | opts, | ||
| spdk_sock_connect_cb_fn | cb_fn, | ||
| void * | cb_arg ) |
Create a socket using the specific sock implementation, initiate the socket connection to the specified address and port (of the server), and then return the socket.
This function is used by client.
The connection is always established asynchronously. The socket is returned before the connection completes, and cb_fn reports the outcome. Not every function taking a sock object is allowed before the connection is established; such functions may return EAGAIN to indicate the connection is still in progress, or another errno value if it failed.
Callback function cb_fn is invoked only if this function returns a non-NULL value, and never before this function has returned.
| ip | IP address of the server. |
| port | Port number of the server. |
| opts | The sock option pointer provided by the user which should not be NULL pointer. |
| cb_fn | Callback function invoked when the connection attempt is completed. (optional) |
| cb_arg | Argument passed to callback function. (optional) |
| int spdk_sock_flush | ( | struct spdk_sock * | sock | ) |
Flush a socket from data gathered in previous writev_async calls.
On failure check rc matching -EAGAIN to determine failure is retryable.
| sock | Socket to flush. |
| const char * spdk_sock_get_default_impl | ( | void | ) |
Get the name of the current default implementation.
| void spdk_sock_get_default_initialize_opts | ( | struct spdk_sock_initialize_opts * | opts, |
| size_t | opts_size ) |
Initialize the default value of socket initialization opts.
| opts | Data structure where SPDK will initialize the default socket initialization options. |
| opts_size | Size of the opts structure being passed. |
| void spdk_sock_get_default_opts | ( | struct spdk_sock_opts * | opts | ) |
Initialize the default value of opts.
| opts | Data structure where SPDK will initialize the default sock options. Users must set opts_size to sizeof(struct spdk_sock_opts). This will ensure that the libraryonly tries to fill as many fields as allocated by the caller. This allows ABI compatibility with future versions of this library that may extend the spdk_sock_opts structure. |
| const char * spdk_sock_get_impl_name | ( | struct spdk_sock * | sock | ) |
Get socket implementation name.
| sock | Pointer to SPDK socket. |
| const char * spdk_sock_get_interface_name | ( | struct spdk_sock * | sock | ) |
Gets the name of the network interface of the local port for the socket.
| sock | socket to find the interface name for |
| struct spdk_memory_domain * spdk_sock_get_memory_domain | ( | struct spdk_sock * | sock | ) |
Get memory domain associated with the socket, or NULL if the socket module doesn't support memory domains.
A socket exposes at most one memory domain because the domain is tied to the socket implementation and connection. Callers that need to choose among multiple device domain types should perform that selection at the higher layer that owns those devices.
| sock | Socket. |
| int32_t spdk_sock_get_numa_id | ( | struct spdk_sock * | sock | ) |
Gets the NUMA node ID for the network interface of the local port for the TCP socket.
| sock | TCP socket to find the NUMA socket ID for |
| int spdk_sock_get_optimal_sock_group | ( | struct spdk_sock * | sock, |
| struct spdk_sock_group ** | group, | ||
| struct spdk_sock_group * | hint ) |
Get the optimal sock group for this sock.
This function is allowed only when connection is established.
| sock | The socket |
| group | Returns the optimal sock group. If there is no optimal sock group, returns NULL. |
| hint | When return is 0 and group is set to NULL, hint is used to set optimal sock group for the socket. |
| int spdk_sock_getaddr | ( | struct spdk_sock * | sock, |
| char * | saddr, | ||
| int | slen, | ||
| uint16_t * | sport, | ||
| char * | caddr, | ||
| int | clen, | ||
| uint16_t * | cport ) |
Get client and server addresses of the given socket.
This function is allowed only when connection is established.
| sock | Socket to get address. |
| saddr | A pointer to the buffer to hold the address of server. |
| slen | Length of the buffer 'saddr'. |
| sport | A pointer(May be NULL) to the buffer to hold the port info of server. |
| caddr | A pointer to the buffer to hold the address of client. |
| clen | Length of the buffer 'caddr'. |
| cport | A pointer(May be NULL) to the buffer to hold the port info of server. |
| int spdk_sock_group_add_sock | ( | struct spdk_sock_group * | group, |
| struct spdk_sock * | sock ) |
Add a socket to the group.
| group | Socket group. |
| sock | Socket to add. |
If this socket was previously removed from another group, see spdk_sock_group_remove_sock() for module-specific behavior while the socket is not in any group.
| int spdk_sock_group_close | ( | struct spdk_sock_group ** | group | ) |
Close all registered sockets of the group and then remove the group.
If any sockets were added to the group by spdk_sock_group_add_sock these must be removed first by using spdk_sock_group_remove_sock.
| group | Group to close. |
| struct spdk_sock_group * spdk_sock_group_create | ( | const struct spdk_sock_group_opts * | opts | ) |
Create a new socket group.
| opts | Socket group options. This is required and may not be NULL. |
| void * spdk_sock_group_get_ctx | ( | struct spdk_sock_group * | sock_group | ) |
Get the ctx of the sock group.
| sock_group | Socket group. |
| int spdk_sock_group_get_interruptfd | ( | struct spdk_sock_group * | group | ) |
Obtain an fd that becomes ready when one of the sockets in this group is ready.
This fd is suitable for use in APIs such as spdk_interrupt_register_for_events().
| group | Socket group. |
| int spdk_sock_group_poll | ( | struct spdk_sock_group * | group | ) |
Poll incoming events for each registered socket.
| group | Group to poll. |
| int spdk_sock_group_release_buf | ( | struct spdk_sock_group * | group, |
| void * | buf, | ||
| struct spdk_sock_buf_token * | token ) |
Release a buffer obtained via spdk_sock_recv_next() back to the receive pool of the group that owns it, identified by the group rather than the socket it was received on.
The buffer pool is owned by the group, not the socket, so buffers can be released after their socket has been closed (e.g. during qpair teardown). The group must remain open until all of its buffers have been released.
| group | Socket group that owns the buffer pool. |
| buf | Pointer to the buffer. |
| token | Token for the buffer. |
| int spdk_sock_group_remove_sock | ( | struct spdk_sock_group * | group, |
| struct spdk_sock * | sock ) |
Remove a socket from the group.
While a socket is not in a group, no rx_cb will fire for that socket. For kernel-based modules, incoming data remains buffered by the kernel and becomes visible when the socket is re-added. For user-space modules, incoming data for that socket may be dropped.
| group | Socket group. |
| sock | Socket to remove. |
| int spdk_sock_impl_get_opts | ( | const char * | impl_name, |
| struct spdk_sock_impl_opts * | opts, | ||
| size_t * | len ) |
Get current socket implementation options.
| impl_name | The socket implementation to use, such as "posix". |
| opts | Pointer to allocated spdk_sock_impl_opts structure that will be filled with actual values. |
| len | On input specifies size of passed opts structure. On return it is set to actual size that was filled with values. |
| int spdk_sock_impl_set_opts | ( | const char * | impl_name, |
| const struct spdk_sock_impl_opts * | opts, | ||
| size_t | len ) |
Set socket implementation options.
| impl_name | The socket implementation to use, such as "posix". |
| opts | Pointer to allocated spdk_sock_impl_opts structure with new options values. |
| len | Size of passed opts structure. |
| bool spdk_sock_impl_supports_recv_next | ( | const char * | impl_name | ) |
Check whether a socket implementation supports spdk_sock_recv_next().
| impl_name | The socket implementation to check, or NULL for the current default. |
| int spdk_sock_initialize | ( | struct spdk_sock_initialize_opts * | opts | ) |
Initialize the socket module.
This is an optional call that may be called before any use of the socket library.
This function is not thread safe and should be called only once. Subsequent calls will succeed if the options passed in are the same as the first invocation, otherwise it will return -EALREADY.
| opts | Options for the socket library. |
| bool spdk_sock_is_connected | ( | struct spdk_sock * | sock | ) |
Check whether the socket is currently connected.
| sock | Socket to check |
| bool spdk_sock_is_ipv4 | ( | struct spdk_sock * | sock | ) |
Check whether the address of socket is ipv4.
This function is allowed only when connection is established.
| sock | Socket to check. |
| bool spdk_sock_is_ipv6 | ( | struct spdk_sock * | sock | ) |
Check whether the address of socket is ipv6.
This function is allowed only when connection is established.
| sock | Socket to check. |
| struct spdk_sock * spdk_sock_listen | ( | const char * | ip, |
| int | port, | ||
| struct spdk_sock_opts * | opts ) |
Create a socket using the specific sock implementation, bind the socket to the specified address and port and listen on the socket, and then return the socket.
This function is used by server.
| ip | IP address to listen on. |
| port | Port number. |
| opts | The sock option pointer provided by the user, which should not be NULL pointer. |
| ssize_t spdk_sock_readv | ( | struct spdk_sock * | sock, |
| struct iovec * | iov, | ||
| int | iovcnt ) |
Read message from the given socket to the I/O vector array.
On failure check errno matching EAGAIN to determine failure is retryable.
| sock | Socket to receive message. |
| iov | I/O vector. |
| iovcnt | Number of I/O vectors in the array. |
| ssize_t spdk_sock_recv | ( | struct spdk_sock * | sock, |
| void * | buf, | ||
| size_t | len ) |
Receive a message from the given socket.
On failure check rc matching -EAGAIN to determine failure is retryable.
| sock | Socket to receive message. |
| buf | Pointer to a buffer to hold the data. |
| len | Length of the buffer. |
| int spdk_sock_recv_next | ( | struct spdk_sock * | sock, |
| void ** | buf, | ||
| struct spdk_sock_buf_token ** | token ) |
Receive the next portion of the stream from the socket.
Callers must first check support using spdk_sock_impl_supports_recv_next(), or select a socket implementation known to support this operation.
The buffer pointed to by buf must later be returned by calling spdk_sock_group_release_buf().
Note that the amount of data in buf is determined entirely by the sock layer. You cannot request to receive only a limited amount here. You simply get whatever the next portion of the stream is, as determined by the sock module.
| sock | Socket to receive from. |
| buf | Populated with the next portion of the stream |
| token | Populated with the token for the buffer |
| int spdk_sock_set_default_impl | ( | const char * | impl_name | ) |
Set the given sock implementation to be used as the default one.
Note: passing a specific sock implementation name in some sock API functions (such as spdk_sock_connect, spdk_sock_listen and etc) ignores the default value set by this function.
| impl_name | The socket implementation to use, such as "posix". |
| int spdk_sock_set_recvbuf | ( | struct spdk_sock * | sock, |
| int | sz ) |
Set receive buffer size for the given socket.
| sock | Socket to set buffer size for. |
| sz | Buffer size in bytes. |
| int spdk_sock_set_recvlowat | ( | struct spdk_sock * | sock, |
| int | nbytes ) |
Set the value used to specify the low water mark (in bytes) for this socket.
| sock | Socket to set for. |
| nbytes | Value for recvlowat. |
| int spdk_sock_set_sendbuf | ( | struct spdk_sock * | sock, |
| int | sz ) |
Set send buffer size for the given socket.
| sock | Socket to set buffer size for. |
| sz | Buffer size in bytes. |
| void spdk_sock_set_user_ctx | ( | struct spdk_sock * | sock, |
| void * | user_ctx ) |
Change the user context callback argument passed to spdk_sock_cb for this socket.
This is intended for attaching per-connection state to a newly accepted socket. It can also update the context after the socket has been added to a group.
| sock | The socket to change the callback argument for. |
| user_ctx | The new callback argument to set. |
| void spdk_sock_write_config_json | ( | struct spdk_json_write_ctx * | w | ) |
Write socket subsystem configuration into provided JSON context.
| w | JSON write context |
| ssize_t spdk_sock_writev | ( | struct spdk_sock * | sock, |
| struct iovec * | iov, | ||
| int | iovcnt ) |
Write message to the given socket from the I/O vector array.
On failure check rc matching -EAGAIN to determine failure is retryable.
| sock | Socket to write to. |
| iov | I/O vector. |
| iovcnt | Number of I/O vectors in the array. |
| void spdk_sock_writev_async | ( | struct spdk_sock * | sock, |
| struct spdk_sock_request * | req ) |
Write data to the given socket asynchronously, calling the provided callback when the data has been written.
| sock | Socket to write to. |
| req | The write request to submit. |
| void spdk_sock_writev_async_ext | ( | struct spdk_sock * | sock, |
| struct spdk_sock_request * | req, | ||
| const struct spdk_sock_request_opts * | opts ) |
Write data to the given socket asynchronously with optional request metadata.
| sock | Socket to write to. |
| req | The write request to submit. |
| opts | Optional request metadata. The socket layer consumes this structure before returning and does not retain the pointer. opts->memory_domain may be set only if spdk_sock_get_memory_domain() returns a memory domain for this socket, and that domain must be able to translate the payload. Otherwise the payload must be in host memory. |