Receive Filtering API - UG1586

The Onload Extensions Receive Filtering API provides the following components:

• #include <onload/extensions_zc.h>

  In addition to the common components, an application should include this header file which contains all function prototypes and constant values required when using the API.

  This file includes comprehensive documentation, required data structures and function definitions.

The Receive Filtering API is a variation on the zero-copy receive whereby the normal socket methods are used for accessing the data, but the application can specify a callback to inspect each datagram before it is received.

typedef enum onload_zc_callback_rc
(*onload_zc_recv_filter_callback)(struct onload_zc_msg *msg,
                                  void* arg,
                                  int flags);
int onload_set_recv_filter(int fd,
                           onload_zc_recv_filter_callback filter,
                           void* cb_arg,
                           int flags);

The onload_set_recv_filter() function returns immediately.

The callback is invoked once per message in the context of subsequent calls to recv(), recvmsg() etc. The cb_arg value is passed to the callback along with the message. The flags argument of the callback is set to ONLOAD_ZC_MSG_SHARED if the message is shared with other sockets, and the caller should take care not to modify the contents of the iovec.

The message can be found in msg->iov[], and the iovec is of length msg->msghdr.msg_iovlen.

The callback must return ONLOAD_ZC_CONTINUE to allow the message to be delivered to the application. Other return codes such as ONLOAD_ZC_TERMINATE and ONLOAD_ZC_MODIFIED are deprecated and no longer supported.

This function can only be used with accelerated sockets (those being handled by Onload). If a socket has been handed over to the kernel stack (for example because it has been bound to an address that is not routed over a SFC interface), it will return -ESOCKTNOSUPPORT.