onload_ordered_epoll_wait

Onload User Guide (UG1586)

Document ID
UG1586
Release Date
2023-07-31
Revision
1.2 English

For details of the Wire Order Delivery feature refer to Wire Order Delivery.

Description

If the epoll set contains accelerated sockets in only one stack this function can be used instead of epoll_wait() to return events in the order these were recovered from the wire. There is no explicit check on sockets, so applications must ensure that the rules are applied to avoid mis-ordering of packets.

Definition

int onload_ordered_epoll_wait (
  int epfd,
  struct epoll_event *events,
  struct onload_ordered_epoll_event *oo_events,
  int maxevents,
  int timeout);

Formal Parameters

See definition epoll_wait().

Return Value

  • A positive value identifies the number of epoll_evs / ordered_evs to process.
  • A zero value indicates there are no events which can be processed while maintaining ordering, that is there might be no data or only unordered data.
  • A negative return value identifies an error condition.

Notes

Any file descriptors returned as ready without a valid timestamp (tv_sec = 0), should be considered unordered with respect to the rest of the set. This can occur for data received via the kernel or data returned without a hardware timestamp, that is from an interface that does not support hardware timestamping.

The environment variable EF_UL_EPOLL=1 must be set if hardware timestamps are required. This feature is only available on the SFN8000 and X2 series adapters.

struct onload_ordered_epoll_event{
  /* The hardware timestamp of the first readable data */
  struct timespec ts;
  /* Number of bytes that may be read to maintain wire order */
  int bytes 
};

ONLOAD_MSG_ONEPKT and EF_TCP_RCVBUF_STRICT are incompatible with the wire order delivery feature. Refer to Wire Order Delivery for details.

Use the environment variable EF_RX_TIMESTAMPING_ORDERING to select either the (default) NIC hardware timestamps or external timestamps from cPacket trailers applied by upstream external equipment. When using external timestamps, packets might appear out of order due to external delays unknown to Onload.