869 lines
34 KiB
C
869 lines
34 KiB
C
/***************************************************************************
|
|
* Copyright 2007 - 2014 VMware, Inc. All rights reserved.
|
|
***************************************************************************/
|
|
|
|
/*
|
|
* @VMKAPIMOD_LICENSE@
|
|
*/
|
|
|
|
/*
|
|
***********************************************************************
|
|
* Sockets */ /**
|
|
* \defgroup Socket Network Socket Interfaces
|
|
* @{
|
|
*
|
|
***********************************************************************
|
|
*/
|
|
|
|
#ifndef _VMKAPI_SOCKET_H_
|
|
#define _VMKAPI_SOCKET_H_
|
|
|
|
/** \cond never */
|
|
#ifndef VMK_HEADER_INCLUDED_FROM_VMKAPI_H
|
|
#error This vmkapi file should never be included directly but only via vmkapi.h
|
|
#endif
|
|
/** \endcond never */
|
|
|
|
#include "sockets/vmkapi_socket_util.h"
|
|
|
|
/**
|
|
* \brief Opaque socket handle.
|
|
*/
|
|
typedef struct vmk_SocketInt *vmk_Socket;
|
|
|
|
/**
|
|
* \brief Definition for an invalid vmk_Socket.
|
|
*/
|
|
#define VMK_SOCKET_INVALID ((vmk_Socket)NULL)
|
|
|
|
/*
|
|
* Address families
|
|
*/
|
|
/** \brief IPv4 */
|
|
#define VMK_SOCKET_AF_INET 2
|
|
|
|
/** \brief IPv6 */
|
|
#define VMK_SOCKET_AF_INET6 28
|
|
|
|
/*
|
|
* Socket types
|
|
*/
|
|
/** \brief Streaming */
|
|
#define VMK_SOCKET_SOCK_STREAM 1
|
|
|
|
/** \brief Datagrams */
|
|
#define VMK_SOCKET_SOCK_DGRAM 2
|
|
|
|
/** \brief Raw datagrams */
|
|
#define VMK_SOCKET_SOCK_RAW 3
|
|
|
|
/*
|
|
* Flags for vmk_SocketSendTo() and vmk_SocketRecvFrom()
|
|
*/
|
|
/** \brief Send/receive of this message should not block */
|
|
#define VMK_SOCKET_MSG_DONTWAIT 0x80
|
|
/** \brief Receive from socket inside socket callback function */
|
|
#define VMK_SOCKET_MSG_SOCALLBCK 0x10000
|
|
|
|
/*
|
|
* Socket option levels
|
|
*/
|
|
/** \brief Operate on the socket itself */
|
|
#define VMK_SOCKET_SOL_SOCKET 0xffff
|
|
|
|
/*
|
|
* Socket-level socket options
|
|
*/
|
|
/** \brief Allow local address reuse */
|
|
#define VMK_SOCKET_SO_REUSEADDR 0x0004
|
|
/** \brief Keep connections alive */
|
|
#define VMK_SOCKET_SO_KEEPALIVE 0x0008
|
|
/** \brief Just use interface addresses */
|
|
#define VMK_SOCKET_SO_DONTROUTE 0x0010
|
|
/** \brief Linger on close if data present */
|
|
#define VMK_SOCKET_SO_LINGER 0x0080
|
|
/** \brief Allow local address and port reuse */
|
|
#define VMK_SOCKET_SO_REUSEPORT 0x0200
|
|
/** \brief Timestamp received dgram traffic */
|
|
#define VMK_SOCKET_SO_TIMESTAMP 0x0400
|
|
/** \brief Use non-blocking socket semantics */
|
|
#define VMK_SOCKET_SO_NONBLOCKING 0x1015
|
|
|
|
/** \brief Bind socket to a vmknic
|
|
* \note Note that the TCP/IP stack will only transmit the packet if the routing
|
|
* decision indicates that it can be sent out of the specified vmknic.
|
|
*/
|
|
#define VMK_SOCKET_SO_BINDTOVMK 0x1016
|
|
|
|
/*
|
|
* Values for the vmk_SocketShutdown()'s "how" parameter
|
|
*/
|
|
/** \brief Further receives will be disallowed */
|
|
#define VMK_SOCKET_SHUT_RD 0
|
|
/** \brief Further sends will be disallowed. */
|
|
#define VMK_SOCKET_SHUT_WR 1
|
|
/** \brief Further sends and receives will be disallowed. */
|
|
#define VMK_SOCKET_SHUT_RDWR 2
|
|
|
|
/**
|
|
* \brief
|
|
* Data structure for setting the VMK_SOCKET_SO_LINGER option
|
|
*/
|
|
typedef struct vmk_SocketLingerData {
|
|
/** \brief Whether linger is enabled or not */
|
|
vmk_uint32 enabled;
|
|
/** \brief Linger duration (in seconds) */
|
|
vmk_uint32 duration;
|
|
} VMK_ATTRIBUTE_PACKED vmk_SocketLingerData;
|
|
|
|
/*
|
|
***********************************************************************
|
|
* vmk_SocketCallbackFn -- */ /**
|
|
*
|
|
* \ingroup Socket
|
|
* \brief Called when data is available or when data is sent out.
|
|
*
|
|
* \softwaredriversonly
|
|
*
|
|
* This callback is registered by vmk_SocketRegisterRecvBufferCallback
|
|
* or vmk_SocketRegisterSendBufferCallback.
|
|
*
|
|
* \param[in] socket Socket the data is available on or sent out
|
|
* from.
|
|
* \param[in] arg Argument given when registering the callback.
|
|
*
|
|
***********************************************************************
|
|
*/
|
|
typedef void (*vmk_SocketCallbackFn)(vmk_Socket socket, void *arg);
|
|
|
|
/*
|
|
***********************************************************************
|
|
* vmk_SocketCreate -- */ /**
|
|
*
|
|
* \ingroup Socket
|
|
* \brief Create a new unbound socket.
|
|
*
|
|
* \softwaredriversonly
|
|
*
|
|
* \note This function will not block.
|
|
* \note The default behavior is to create a blocking socket. If
|
|
* nonblocking behavior is required then the
|
|
* VMK_SOCKET_SO_NONBLOCKING socket option must be set.
|
|
*
|
|
* \param[in] domain Protocol family for this socket.
|
|
* \param[in] type Type of communication on this socket
|
|
* \param[in] protocol Specific protocol to use from address family
|
|
* \param[out] socket Newly created socket
|
|
*
|
|
* \retval VMK_OK Success.
|
|
* \retval VMK_BAD_PARAM Bad input parameter.
|
|
* \retval VMK_NO_MODULE_HEAP The module's heap is not set.
|
|
* \retval VMK_NO_MEMORY Unable to allocate memory for socket.
|
|
* \retval VMK_EPROTONOSUPPORT Maps to BSD error code EPROTONOSUPPORT.
|
|
* \retval VMK_BAD_PARAM_TYPE Maps to BSD error code EPROTOTYPE.
|
|
* \retval VMK_NO_BUFFERSPACE Maps to BSD error code ENOBUFS.
|
|
* \retval VMK_EOPNOTSUPP Maps to BSD error code EOPNOTSUPP.
|
|
* \retval VMK_NO_ACCESS Maps to BSD error code EACCESS.
|
|
*
|
|
* \note For BSD error code definitions see the FreeBSD 7 man page
|
|
* socket(2).
|
|
*
|
|
* \note Specific domain (VMK_SOCKET_AF_*), type (VMK_SOCKET_SOCK_*),
|
|
* and protocol (VMK_SOCKET_*PROTO*) values are implementation
|
|
* dependent, an application can determine if a specific domain
|
|
* and type is supported by trying to create a socket with zero
|
|
* protocol value.
|
|
*
|
|
***********************************************************************
|
|
*/
|
|
VMK_ReturnStatus vmk_SocketCreate(int domain,
|
|
int type,
|
|
int protocol,
|
|
vmk_Socket *socket);
|
|
|
|
/*
|
|
***********************************************************************
|
|
* vmk_SocketBind -- */ /**
|
|
*
|
|
* \ingroup Socket
|
|
* \brief Bind a socket to a network address endpoint.
|
|
*
|
|
* \nativedriversdisallowed
|
|
*
|
|
* \note This function will not block.
|
|
*
|
|
* \param[in] socket Socket to bind to the network address
|
|
* \param[in] address Information describing the network address
|
|
* that the socket will be bound to.
|
|
* \param[in] addressLength Length in bytes of the network address
|
|
* information.
|
|
*
|
|
* \retval VMK_BAD_PARAM Socket was already bound
|
|
* \retval VMK_NOT_SUPPORTED Unknown socket type.
|
|
* \retval VMK_NO_MODULE_HEAP This module's heap is not set.
|
|
* \retval VMK_EOPNOTSUPP Maps to BSD error code EOPNOTSUPP.
|
|
* \retval VMK_BAD_PARAM Maps to BSD error code EINVAL.
|
|
* \retval VMK_EADDRNOTAVAIL Maps to BSD error code EADDRNOTAVAIL.
|
|
* \retval VMK_ADDRFAM_UNSUPP Maps to BSD error code EAFNOSUPPORT.
|
|
* \retval VMK_EADDRINUSE Maps to BSD error code EADDRINUSE.
|
|
* \retval VMK_NO_ACCESS Maps to BSD error code EACCESS.
|
|
*
|
|
* \note For BSD error code definitions see the FreeBSD 7 man page
|
|
* bind(2).
|
|
*
|
|
***********************************************************************
|
|
*/
|
|
VMK_ReturnStatus vmk_SocketBind(vmk_Socket socket,
|
|
vmk_SocketAddress *address,
|
|
int addressLength);
|
|
|
|
/*
|
|
***********************************************************************
|
|
* vmk_SocketConnect -- */ /**
|
|
*
|
|
* \ingroup Socket
|
|
* \brief Connect to a network address
|
|
*
|
|
* \softwaredriversonly
|
|
*
|
|
* \note This function may block if the socket is blocking socket
|
|
* (this is the default behavior). If nonblocking behavior is required
|
|
* then the VMK_SOCKET_SO_NONBLOCKING socket option must be set.
|
|
* \note On non-blocking sockets, the connection may not be established
|
|
* by the time the function returns. In such a case, VMK_EINPROGRESS
|
|
* will be returned. A subsequent invocation of the send socket callback
|
|
* will indicate updates to the connection status. The send socket
|
|
* callback can use \ref vmk_SocketIsConnected() to check the connection
|
|
* status.
|
|
*
|
|
* \param[in] socket Socket to connect through.
|
|
* \param[in] address The network address info for the address
|
|
* to connect to.
|
|
* \param[in] addressLength The length of the address info.
|
|
*
|
|
* \retval VMK_NOT_SUPPORTED Unknown socket type.
|
|
* \retval VMK_EALREADY Socket already connected.
|
|
* \retval VMK_EINPROGRESS Socket is nonblocking and connection
|
|
* is still in progress.
|
|
* \retval VMK_EOPNOTSUPP Maps to BSD error code EOPNOTSUPP.
|
|
* \retval VMK_ALREADY_CONNECTED Maps to BSD error code EISCONN.
|
|
* \retval VMK_BAD_PARAM Maps to BSD error code EINVAL.
|
|
* \retval VMK_EADDRNOTAVAIL Maps to BSD error code EADDRNOTAVAIL.
|
|
* \retval VMK_ADDRFAM_UNSUPP Maps to BSD error code EAFNOSUPPORT.
|
|
* \retval VMK_EADDRINUSE Maps to BSD error code EADDRINUSE.
|
|
* \retval VMK_NO_ACCESS Maps to BSD error code EACCESS.
|
|
*
|
|
* \note For BSD error code definitions see the FreeBSD 7 man page
|
|
* connect(2).
|
|
*
|
|
***********************************************************************
|
|
*/
|
|
VMK_ReturnStatus vmk_SocketConnect(vmk_Socket socket,
|
|
vmk_SocketAddress *address,
|
|
int addressLength);
|
|
|
|
/*
|
|
***********************************************************************
|
|
* vmk_SocketShutdown -- */ /**
|
|
*
|
|
* \ingroup Socket
|
|
* \brief Shutdown part or all of a connection on a socket
|
|
*
|
|
* \softwaredriversonly
|
|
*
|
|
* \note This function may block if VMK_SOCKET_SO_LINGER has been set
|
|
* otherwise it will not block.
|
|
*
|
|
* \param[in] socket Socket to query.
|
|
* \param[in] how Data direction(s) to shutdown on the socket.
|
|
*
|
|
* \retval VMK_NOT_SUPPORTED Unknown socket type.
|
|
* \retval VMK_EOPNOTSUPP Maps to BSD error code EOPNOTSUPP.
|
|
* \retval VMK_ECONNRESET Maps to BSD error code ECONNRESET.
|
|
* \retval VMK_ENOTCONN Maps to BSD error code ENOTCONN.
|
|
*
|
|
* \note For BSD error code definitions see the FreeBSD 7 man page
|
|
* shutdown(2).
|
|
*
|
|
***********************************************************************
|
|
*/
|
|
VMK_ReturnStatus vmk_SocketShutdown(vmk_Socket socket,
|
|
int how);
|
|
|
|
/*
|
|
***********************************************************************
|
|
* vmk_SocketClose -- */ /**
|
|
*
|
|
* \ingroup Socket
|
|
* \brief Destroy an existing socket.
|
|
*
|
|
* \softwaredriversonly
|
|
*
|
|
* \note This function may block if VMK_SOCKET_SO_LINGER has been set
|
|
* otherwise will not block.
|
|
*
|
|
* \param[in] socket Socket to close
|
|
*
|
|
* \retval VMK_OK Success.
|
|
* \retval VMK_BAD_PARAM Input socket is invalid.
|
|
* \retval VMK_NO_MODULE_HEAP The module's heap is not set.
|
|
* \retval VMK_BUSY Socket is already closing.
|
|
* \retval VMK_NOT_SUPPORTED Unknown socket type.
|
|
*
|
|
***********************************************************************
|
|
*/
|
|
VMK_ReturnStatus vmk_SocketClose(vmk_Socket socket);
|
|
|
|
/*
|
|
***********************************************************************
|
|
* vmk_SocketGetSockOpt -- */ /**
|
|
*
|
|
* \ingroup Socket
|
|
* \brief Get the option information from a socket
|
|
*
|
|
* \softwaredriversonly
|
|
*
|
|
* \note This function will not block.
|
|
*
|
|
* \param[in] socket Socket to get the option info from.
|
|
* \param[in] level Level of communication infrastructure from which
|
|
* to get the socket option.
|
|
* \param[in] option The option to get the information about.
|
|
* \param[out] optval Data that is currently set on the option.
|
|
* \param[out] optlen The length of option data.
|
|
*
|
|
* \retval VMK_OK Success.
|
|
* \retval VMK_BAD_PARAM Input socket is invalid.
|
|
* \retval VMK_NOT_SUPPORTED Unknown socket type.
|
|
* \retval VMK_NOT_SUPPORTED Maps to BSD error code ENOPROTOOPT.
|
|
* \retval VMK_EOPNOTSUPP Maps to BSD error code EOPNOTSUPP.
|
|
* \retval VMK_BAD_PARAM Maps to BSD error code EINVAL.
|
|
*
|
|
* \note For BSD error code definitions see the FreeBSD 7 man page
|
|
* getsockopt(2).
|
|
*
|
|
***********************************************************************
|
|
*/
|
|
VMK_ReturnStatus vmk_SocketGetSockOpt(vmk_Socket socket,
|
|
int level,
|
|
int option,
|
|
void *optval,
|
|
int *optlen);
|
|
|
|
/*
|
|
***********************************************************************
|
|
* vmk_SocketSetSockOpt -- */ /**
|
|
*
|
|
* \ingroup Socket
|
|
* \brief Set the option information on a socket
|
|
*
|
|
* \softwaredriversonly
|
|
*
|
|
* \note This function will not block.
|
|
*
|
|
* \param[in] socket Socket to set the option info on.
|
|
* \param[in] level Level of communication infrastructure from which
|
|
* to set the socket option.
|
|
* \param[in] option The option to set the information about.
|
|
* \param[in] optval Data to set on the option.
|
|
* \param[in] optlen The length of the option data.
|
|
*
|
|
* \retval VMK_OK Success.
|
|
* \retval VMK_BAD_PARAM Input socket is invalid.
|
|
* \retval VMK_NOT_SUPPORTED Unknown socket type.
|
|
* \retval VMK_NOT_SUPPORTED Maps to BSD error code ENOPROTOOPT.
|
|
* \retval VMK_EOPNOTSUPP Maps to BSD error code EOPNOTSUPP.
|
|
* \retval VMK_BAD_PARAM Maps to BSD error code EINVAL.
|
|
*
|
|
* \note For BSD error code definitions see the FreeBSD 7 man page
|
|
* setsockopt(2).
|
|
*
|
|
***********************************************************************
|
|
*/
|
|
VMK_ReturnStatus vmk_SocketSetSockOpt(vmk_Socket socket,
|
|
int level,
|
|
int option,
|
|
const void *optval,
|
|
int optlen);
|
|
|
|
/*
|
|
***********************************************************************
|
|
* vmk_SocketSendTo -- */ /**
|
|
*
|
|
* \ingroup Socket
|
|
* \brief Send data to a network address.
|
|
*
|
|
* \softwaredriversonly
|
|
*
|
|
* \note This function may block if the VMK_SOCKET_MSG_DONTWAIT flag is
|
|
* not set or the socket is a blocking socket.
|
|
*
|
|
* \param[in] socket Socket to send the data through.
|
|
* \param[in] flags Settings for this send transaction.
|
|
* \param[in] address Address information describing the
|
|
* data's destination.
|
|
* \param[in] data Pointer to data buffer to send.
|
|
* \param[in] len Length in bytes of the data buffer to send.
|
|
* \param[out] bytesSent Number of bytes actually sent.
|
|
*
|
|
* \retval VMK_OK Success.
|
|
* \retval VMK_NOT_SUPPORTED Unknown socket type.
|
|
* \retval VMK_BAD_PARAM Unsupported flags setting.
|
|
* \retval VMK_EOPNOTSUPP Maps to BSD error code EOPNOTSUPP.
|
|
* \retval VMK_ENOTCONN Maps to BSD error code ENOTCONN.
|
|
* \retval VMK_EDESTADDRREQ Maps to BSD error code EDESTADDRREQ.
|
|
* \retval VMK_MESSAGE_TOO_LONG Maps to BSD error code EMSGSIZE.
|
|
* \retval VMK_WOULD_BLOCK Maps to BSD error code EAGAIN.
|
|
* \retval VMK_NO_BUFFERSPACE Maps to BSD error code ENOBUFS.
|
|
* \retval VMK_EHOSTUNREACH Maps to BSD error code EHOSTUNREACH.
|
|
* \retval VMK_ALREADY_CONNECTED Maps to BSD error code EISCONN.
|
|
* \retval VMK_ECONNREFUSED Maps to BSD error code ECONNREFUSED.
|
|
* \retval VMK_EHOSTDOWN Maps to BSD error code EHOSTDOWN.
|
|
* \retval VMK_ENETDOWN Maps to BSD error code ENETDOWN.
|
|
* \retval VMK_EADDRNOTAVAIL Maps to BSD error code EADDRNOTAVAIL.
|
|
* \retval VMK_BROKEN_PIPE Maps to BSD error code EPIPE.
|
|
*
|
|
* \note For BSD error code definitions see the FreeBSD 7 man page
|
|
* sendto(2).
|
|
*
|
|
***********************************************************************
|
|
*/
|
|
VMK_ReturnStatus vmk_SocketSendTo(vmk_Socket socket,
|
|
int flags,
|
|
vmk_SocketAddress *address,
|
|
void *data,
|
|
int len,
|
|
int *bytesSent);
|
|
|
|
/*
|
|
***********************************************************************
|
|
* vmk_SocketRecvFrom -- */ /**
|
|
*
|
|
* \ingroup Socket
|
|
* \brief Receive data from a network address.
|
|
*
|
|
* \softwaredriversonly
|
|
*
|
|
* \note This function may block if the VMK_SOCKET_MSG_DONTWAIT flag is
|
|
* not set or the socket is a blocking socket.
|
|
*
|
|
* \param[in] socket Socket to receive the data through.
|
|
* \param[in] flags Settings for this receive transaction.
|
|
* \param[in] address The source address information the
|
|
* messages should be received from,
|
|
* or NULL if this is not necessary for
|
|
* the socket's protocol or settings.
|
|
* \param[in,out] addressLength Length in bytes of the address
|
|
* information.
|
|
* \param[in] data Pointer to data buffer to receive to.
|
|
* \param[in] len Length in bytes of the data buffer.
|
|
* \param[out] bytesReceived Number of bytes actually received.
|
|
*
|
|
* \retval VMK_NOT_SUPPORTED Receive on unbound VMKLINK socket is
|
|
* not supported.
|
|
* \retval VMK_EOPNOTSUPP Maps to BSD error code EOPNOTSUPP.
|
|
* \retval VMK_ENOTCONN Maps to BSD error code ENOTCONN.
|
|
* \retval VMK_MESSAGE_TOO_LONG Maps to BSD error code EMSGSIZE.
|
|
* \retval VMK_WOULD_BLOCK Maps to BSD error code EAGAIN.
|
|
* \retval VMK_ECONNRESET Maps to BSD error code ECONNRESET.
|
|
* \retval VMK_INVALID_ADDRESS Maps to BSD error code EFAULT.
|
|
*
|
|
* \note For BSD error code definitions see the FreeBSD 7 man page
|
|
* recvfrom(2).
|
|
*
|
|
***********************************************************************
|
|
*/
|
|
VMK_ReturnStatus vmk_SocketRecvFrom(vmk_Socket socket,
|
|
int flags,
|
|
vmk_SocketAddress *address,
|
|
int *addressLength,
|
|
void *data,
|
|
int len,
|
|
int *bytesReceived);
|
|
|
|
/*
|
|
***********************************************************************
|
|
* vmk_SocketGetSockName -- */ /**
|
|
*
|
|
* \ingroup Socket
|
|
* \brief Get the socket's local endpoint network address information.
|
|
*
|
|
* \softwaredriversonly
|
|
*
|
|
* \note This function will not block.
|
|
*
|
|
* \param[in] socket Socket to query.
|
|
* \param[out] address The network address info for the socket
|
|
* local endpoint.
|
|
* \param[in,out] addressLength The length of the address info.
|
|
*
|
|
* \retval VMK_OK Success.
|
|
* \retval VMK_BAD_PARAM Bad input socket or address.
|
|
* \retval VMK_NOT_SUPPORTED Unknown socket family.
|
|
* \retval VMK_EOPNOTSUPP Maps to BSD error code EOPNOTSUPP.
|
|
* \retval VMK_BAD_PARAM Maps to BSD error code EINVAL.
|
|
* \retval VMK_NO_MEMORY Maps to BSD error code ENOMEM.
|
|
*
|
|
* \note For BSD error code definitions see the FreeBSD 7 man page
|
|
* getsockname(2).
|
|
*
|
|
***********************************************************************
|
|
*/
|
|
VMK_ReturnStatus vmk_SocketGetSockName(vmk_Socket socket,
|
|
vmk_SocketAddress *address,
|
|
int *addressLength);
|
|
|
|
/*
|
|
***********************************************************************
|
|
* vmk_SocketGetPeerName -- */ /**
|
|
*
|
|
* \ingroup Socket
|
|
* \brief Get the socket's far endpoint network address information.
|
|
*
|
|
* \softwaredriversonly
|
|
*
|
|
* \note This function will not block.
|
|
*
|
|
* \param[in] socket Socket to query.
|
|
* \param[out] address The network address info for the
|
|
* socket remote endpoint.
|
|
* \param[in,out] addressLength The length of the address info.
|
|
*
|
|
* \retval VMK_OK Success.
|
|
* \retval VMK_BAD_PARAM Bad input socket or address.
|
|
* \retval VMK_NOT_SUPPORTED Unknown socket family.
|
|
* \retval VMK_EOPNOTSUPP Maps to BSD error code EOPNOTSUPP.
|
|
* \retval VMK_NO_MEMORY Maps to BSD error code ENOMEM.
|
|
* \retval VMK_ENOTCONN Maps to BSD error code ENOTCONN.
|
|
*
|
|
* \note For BSD error code definitions see the FreeBSD 7 man page
|
|
* getpeername(2).
|
|
*
|
|
***********************************************************************
|
|
*/
|
|
VMK_ReturnStatus vmk_SocketGetPeerName(vmk_Socket socket,
|
|
vmk_SocketAddress *address,
|
|
int *addressLength);
|
|
|
|
/*
|
|
***********************************************************************
|
|
* vmk_SocketRecvSgVirtArrayZeroCopy -- */ /**
|
|
*
|
|
* \ingroup Socket
|
|
* \brief Receive a scatter-gather VA array using zero copy.
|
|
*
|
|
* \softwaredriversonly
|
|
*
|
|
* Zero copy implies that the sgVirtArray returned as out argument by
|
|
* the function (and the corresponding data buffers) are owned by the
|
|
* underlying layers, and the ownership is being passed to the caller,
|
|
* without making a copy of the buffers. The caller must treat the
|
|
* data as read-only, and after consumption, the caller must transfer
|
|
* the ownership back by calling vmk_SgVirtArrayFree.
|
|
*
|
|
* Example:
|
|
*
|
|
* 1. vmk_SocketRecvSgVirtArrayZeroCopy(): returns recvdSgVirtArray
|
|
*
|
|
* 2. Consume the data
|
|
* a. vmk_SgVirtArrayGetUsedElems: returns usedElems.
|
|
* b. For i from 0 to usedElems:
|
|
* i. vmk_SgVirtArrayGetElem().
|
|
* ii. vmk_SgVirtElemGetInfo().
|
|
* iii. Consume the data.
|
|
*
|
|
* 3. vmk_SgVirtArrayFree(): releases the ownership back to underlying
|
|
* layer.
|
|
*
|
|
* \note The data buffers returned are read-only.
|
|
* \note Will block for blocking socket, will return immediately for
|
|
* non-blocking sockets.
|
|
* \note For blocking socket, if the peer socket closes connection, this
|
|
* call will return immediately. In such a case, VMK_OK will be
|
|
* returned and *recvdSgVirtArray will be set to NULL.
|
|
* \note Only TCP sockets (VMK_SOCKET_IPPROTO_TCP) are currently
|
|
* supported.
|
|
*
|
|
* \param[in] socket Socket to receive from.
|
|
* \param[in] flags Settings for this receive
|
|
* transaction.
|
|
* \param[in,out] address The source address information the
|
|
* messages should be received from,
|
|
* or NULL if this is not necessary for
|
|
* the socket's protocol or settings.
|
|
* \param[in,out] addressLength Length in bytes of the address
|
|
* information.
|
|
* \param[in] len Length in bytes of the data buffer.
|
|
* \param[out] recvdSgVirtArray SG VA array for the buffer received.
|
|
*
|
|
* \retval VMK_OK Success.
|
|
* \retval VMK_WOULD_BLOCK No more bytes to read from receive
|
|
* socket buffer.
|
|
* \retval VMK_BAD_PARAM Bad input socket or address.
|
|
* \retval VMK_NOT_SUPPORTED Unknown socket family or not a TCP socket.
|
|
* \retval VMK_NO_BUFFERSPACE Unable to allocate memory for the
|
|
* SG VA array.
|
|
*
|
|
* \sideeffect Upon any memory allocation failure (VMK_NO_BUFFERSPACE),
|
|
* the socket will be shutdown for read operations. No more
|
|
* data can be read from the socket after such an error.
|
|
*
|
|
***********************************************************************
|
|
*/
|
|
VMK_ReturnStatus
|
|
vmk_SocketRecvSgVirtArrayZeroCopy(vmk_Socket socket,
|
|
int flags,
|
|
vmk_SocketAddress *address,
|
|
int *addressLength,
|
|
int len,
|
|
vmk_SgVirtArray *recvdSgVirtArray);
|
|
|
|
/*
|
|
***********************************************************************
|
|
* vmk_SocketRegisterRecvBufferCallback -- */ /**
|
|
*
|
|
* \ingroup Socket
|
|
* \brief Registers a callback notifying of receive buffer changes.
|
|
*
|
|
* \softwaredriversonly
|
|
*
|
|
* The callback will be invoked when data is available to be read,
|
|
* or on events like connection being closed.
|
|
*
|
|
* \note Previously registered callback, if any, is replaced.
|
|
* \note Callbacks can be unregistered by passing NULL as the fn.
|
|
* \note vmk_SocketSetRecvBufferLoWat() can be used to throttle the
|
|
* rate at which the callback is called.
|
|
* \note The callback may issue reads (e.g. vmk_SocketRecvFrom()), or
|
|
* may choose to defer such action, e.g. to a system world. If
|
|
* reads are done from the callback, then they must specify
|
|
* VMK_SOCKET_MSG_SOCALLBCK in the flag argument.
|
|
* \note The callback needs to handle spurious upcalls of any sort.
|
|
* \note Registering this callback is optional.
|
|
*
|
|
* \param[in] socket Socket whose receive buffer changed.
|
|
* \param[in] fn The callback.
|
|
* \param[in] arg An argument passed back to the callback.
|
|
*
|
|
* \retval VMK_OK Receive callback registered successfully.
|
|
* \retval VMK_BAD_PARAM Bad input socket or address.
|
|
* \retval VMK_NOT_SUPPORTED Registering callbacks not supported for
|
|
* this stack instance.
|
|
*
|
|
***********************************************************************
|
|
*/
|
|
VMK_ReturnStatus
|
|
vmk_SocketRegisterRecvBufferCallback(vmk_Socket socket,
|
|
vmk_SocketCallbackFn fn,
|
|
void *arg);
|
|
|
|
/*
|
|
***********************************************************************
|
|
* vmk_SocketSetRecvBufferLoWat
|
|
*
|
|
* \ingroup Socket
|
|
* \brief Set the receive socket buffer low watermark.
|
|
*
|
|
* \softwaredriversonly
|
|
*
|
|
* If a receive socket buffer callback has been registered
|
|
* (vmk_SocketRegisterRecvBufferCallback(), then the low watermark
|
|
* is a hint to the TCP stack to not invoke the callback unless the
|
|
* socket buffer is filled to at least the low watermark.
|
|
*
|
|
* \note The low watermark is a hint, not a binding guarantee of no
|
|
* callback invocations if there are less bytes than the
|
|
* watermark available.
|
|
* \note May be called from within the receive callback.
|
|
*
|
|
* \param[in] socket Socket to set receive low watermark on.
|
|
* \param[in] bytes Low watermark measured in bytes.
|
|
*
|
|
* \retval VMK_OK Receive low watermark set successfully.
|
|
* \retval VMK_BAD_PARAM Bad input socket or address.
|
|
* \retval VMK_NOT_SUPPORTED Setting low watermark not supported for
|
|
* this stack instance.
|
|
*
|
|
***********************************************************************
|
|
*/
|
|
VMK_ReturnStatus
|
|
vmk_SocketSetRecvBufferLoWat(vmk_Socket socket, vmk_ByteCountSmall bytes);
|
|
|
|
/*
|
|
***********************************************************************
|
|
* vmk_SocketSendSgVirtArrayZeroCopy -- */ /**
|
|
*
|
|
* \ingroup Socket
|
|
* \brief Send a scatter-gather VA array using zero copy.
|
|
*
|
|
* \softwaredriversonly
|
|
*
|
|
* This function is asynchronous in nature, and the underlying layers
|
|
* utilize the same data buffers described by the sgVirtArray parameter.
|
|
* The following behavior is implied by this function:
|
|
*
|
|
* 1. With a call to this function, the ownership of sgVirtArray as
|
|
* well as the data buffers it describes, is passed to the
|
|
* underlying layer. Once the data buffers are successfully
|
|
* transmitted, the caller receives a call to vmk_SgVirtArrayOpsFree.
|
|
* This signals that the ownership of SgVirtArray and the data
|
|
* buffers it describes is passed back to the caller.
|
|
*
|
|
* 2. The caller should not be modifying sgVirtArray and the data
|
|
* buffers it describes, while sgVirtArray is owned by the
|
|
* underlying layer.
|
|
*
|
|
* Example:
|
|
*
|
|
* 1. vmk_SgVirtOpsHandleCreate: creates SG VA ops handle. Must
|
|
* register ops.alloc and ops.free. Usually performed once for
|
|
* a lifetime of a socket.
|
|
*
|
|
* 2. For every call to this function
|
|
* a. txBufList: list of buffers to send (list of VAs).
|
|
* txBufNumElems: number of buffers in the list.
|
|
* b. vmk_SgVirtArrayAllocWithInit(..., txBufNumElems, ...);
|
|
* invokes ops.alloc and later initializes the array.
|
|
* c. For every txBuf in the txBufList
|
|
* vmk_SgVirtElemInit().
|
|
*
|
|
* 3. vmk_SocketSendSgVirtArrayZeroCopy().
|
|
*
|
|
* 4. On successful transmission, ops.free will be invoked to signal
|
|
* that the ownership is passed back to the caller. ops.free
|
|
* must free the memory allocated for sgVirtArray.
|
|
*
|
|
* 5. vmk_SgVirtOpsHandleDestroy: Destroys SG VA ops handle.
|
|
* Must be called only after all the SG VA arrays for this handle
|
|
* are freed i.e. there are no outstanding zero copy transmits.
|
|
*
|
|
* \note For blocking socket, if the peer socket closes connection,
|
|
* this call will return immediately.
|
|
* \note If memory allocation fails midway, VMK_NO_BUFFERSPACE is
|
|
* returned to the caller, but the ownership cannot be returned
|
|
* immediately. Instead, the allocated memory is freed, and
|
|
* then the ownership is returned to the caller using
|
|
* vmk_SgVirtArrayOpFree callback.
|
|
* \note vmk_SgVirtArrayOpFree callback can occur before
|
|
* vmk_SocketSendSgVirtArrayZeroCopy returns.
|
|
* \note Only TCP sockets (VMK_SOCKET_IPPROTO_TCP) are currently
|
|
* supported.
|
|
*
|
|
* \param[in] socket Socket to send on.
|
|
* \param[in] address Destination to send the sgVirtArray to.
|
|
* \param[in] addressLength The length of the address info.
|
|
* \param[in] sgVirtArray SG VA array for the buffer to send.
|
|
*
|
|
* \retval VMK_OK Success.
|
|
* \retval VMK_BAD_PARAM Bad input socket or address.
|
|
* \retval VMK_NOT_SUPPORTED Unknown socket family.
|
|
* \retval VMK_NO_MODULE_HEAP The module's heap is not set.
|
|
* \retval VMK_NO_BUFFERSPACE Unable to allocate memory to send
|
|
* the data.
|
|
*
|
|
***********************************************************************
|
|
*/
|
|
VMK_ReturnStatus
|
|
vmk_SocketSendSgVirtArrayZeroCopy(vmk_Socket socket,
|
|
const vmk_SocketAddress *address,
|
|
int addressLength,
|
|
vmk_SgVirtArray sgVirtArray);
|
|
|
|
/*
|
|
***********************************************************************
|
|
* vmk_SocketRegisterSendBufferCallback */ /**
|
|
*
|
|
* \ingroup Socket
|
|
* \brief Registers a callback notifying of send buffer changes.
|
|
*
|
|
* \softwaredriversonly
|
|
*
|
|
* This callback will be invoked when data is sent, and the send buffer
|
|
* space is available for enqueuing more data to send.
|
|
*
|
|
* \note Callbacks can be unregistered by passing NULL as the fn
|
|
* \note vmk_SocketSetSendBufferLoWat() can be used to throttle the
|
|
* rate at which the callback is called.
|
|
* \note The callback is currently not expected to do sends in the
|
|
* same context.
|
|
* \note The callback needs to handle spurious upcalls of any sort.
|
|
* \note Registering this callback is optional.
|
|
*
|
|
* \param[in] socket Socket whose send buffer changed.
|
|
* \param[in] fn The callback.
|
|
* \param[in] arg An argument passed back to the callback.
|
|
*
|
|
* \retval VMK_OK Send callback registered successfully.
|
|
* \retval VMK_BAD_PARAM Bad input socket or address.
|
|
* \retval VMK_NOT_SUPPORTED Registering callbacks not supported for
|
|
* this stack instance.
|
|
*
|
|
***********************************************************************
|
|
*/
|
|
VMK_ReturnStatus
|
|
vmk_SocketRegisterSendBufferCallback(vmk_Socket socket,
|
|
vmk_SocketCallbackFn fn,
|
|
void *arg);
|
|
|
|
/*
|
|
***********************************************************************
|
|
* vmk_SocketSetSendBufferLoWat */ /**
|
|
*
|
|
* \ingroup Socket
|
|
* \brief Set the send socket buffer low watermark.
|
|
*
|
|
* \softwaredriversonly
|
|
*
|
|
* If a send socket buffer callback has been registered
|
|
* (vmk_SocketRegisterSendBufferCallback()), then the low watermark
|
|
* is a hint to the TCP stack to not invoke the callback unless the
|
|
* send socket buffer has at least the watermark worth of bytes
|
|
* available.
|
|
*
|
|
* \note The low watermark is a hint, not a binding guarantee of no
|
|
* callback invocations if there are less bytes than the
|
|
* watermark available.
|
|
* \note May be called from within the send callback.
|
|
*
|
|
* \param[in] socket Socket to set send low watermark on.
|
|
* \param[in] bytes Low watermark measured in bytes.
|
|
*
|
|
* \retval VMK_OK Send low watermark set successfully.
|
|
* \retval VMK_BAD_PARAM Bad input socket or address.
|
|
* \retval VMK_NOT_SUPPORTED Setting low watermark not supported for
|
|
* this stack instance.
|
|
*
|
|
***********************************************************************
|
|
*/
|
|
VMK_ReturnStatus
|
|
vmk_SocketSetSendBufferLoWat(vmk_Socket socket, vmk_ByteCountSmall bytes);
|
|
|
|
/*
|
|
***********************************************************************
|
|
* vmk_SocketIsConnected */ /**
|
|
*
|
|
* \brief Check if the socket is connected.
|
|
*
|
|
* \softwaredriversonly
|
|
*
|
|
* \note This function will not block.
|
|
*
|
|
* \param[in] socket Socket to check the connection status of.
|
|
* \param[out] isConnected VMK_TRUE if the socket is connected,
|
|
* VMK_FALSE otherwise. Set to a valid value
|
|
* only when the return status is VMK_OK.
|
|
*
|
|
* \retval VMK_OK Successful, socket is connected or
|
|
* disconnected as indicated by
|
|
* the out argument isConnected.
|
|
* \retval VMK_BUSY Socket is in the process of connecting.
|
|
* \retval VMK_BAD_PARAM Input socket is invalid.
|
|
* \retval VMK_NOT_SUPPORTED Not supported by this stack.
|
|
*
|
|
***********************************************************************
|
|
*/
|
|
VMK_ReturnStatus
|
|
vmk_SocketIsConnected(vmk_Socket socket, vmk_Bool *isConnected);
|
|
|
|
#endif /* _VMKAPI_SOCKET_H_ */
|
|
/** @} */
|