OpenOnload

https://github.com/xilinx-cns/onload
Admin
OpenOnload is a high-performance user-level network stack that accelerates TCP and UDP network I/O...
Tokens:33,732
Snippets:215
Trust Score:7.5
Update:9 months ago
Show doc for...
Tokens:
Raw
### Build Example Applications with make

Source: https://github.com/xilinx-cns/onload/blob/master/src/include/etherfabric/doxygen/030_apps.dox

Demonstrates the process of cleaning and rebuilding example applications for Onload using the 'make' utility. This involves setting the PATH environment variable to include the scripts directory and navigating to the build directory.

```sh
[root@server01 Onload-<version>]# cd scripts/
[root@server01 scripts]# export PATH="$PWD:$PATH"
[root@server01 scripts]# cd ../build/gnu_x86_64/tests/ef_vi/
[root@server01 ef_vi]# make clean
[root@server01 ef_vi]# make
```

--------------------------------

### Onload %ef_vi application framework example (C)

Source: https://github.com/xilinx-cns/onload/blob/master/src/include/etherfabric/doxygen/040_using.dox

A basic C framework for an %ef_vi application demonstrating event polling, packet reception handling, transmission completion, and buffer management. This example requires additional initialization and implementation details for a complete program. It includes functions for handling polls, refilling the receive ring, and a main loop for continuous operation.

```c
static void handle_poll(ef_vi *vi)
{
  ef_event events[POLL_BATCH_SIZE];
  int n_ev = ef_eventq_poll(&vi, events, POLL_BATCH_SIZE);
  for( i = O; i < n_ev; ++i ) {
    switch( EF_EVENT_TYPE(events[i]) ) {
    case EF_EVENT_TYPE_RX:
      // Accumulate used buffer
      break;
    case EF_EVENT_TYPE_TX:
      /* Each EF_EVENT_TYPE_TX can signal multiple completed sends */
      int num_completed = ef_vi_transmit_unbundle(vi, events[i], &dma_id);
      break;
    case EF_EVENT_TYPE_RX_DISCARD:
    case EF_EVENT_TYPE_RX_NO_DESC_TRUNC:
      /* Discard events also use up buffers */
      // Accumulate buffer in user space
      break;
    default:
      /* Other error types */
    }
  }
}

static void refill_rx_ring(ef_vi *vi)
{
  if( ef_vi_receive_space(&vi) < REFILL_BATCH_SIZE )
    return;
  int refill_count = REFILL_BATCH_SIZE;
  /* Falling too low? */
  if( ef_vi_receive_space(&vi) > ef_vi_receive_capacity(&vi) / 2 )
    refill_count = ef_vi_receive_space(&vi);
  /* Enough free buffers? */
  if( refill_count > free_bufs_in_sw )
    refill_count = free_bufs_in_sw;
  /* Round down to batch size */
  refill_count &= ~(REFILL_BATCH_SIZE - 1);
  if( refill_count ) {
    while( refill_count ) {
      ef_vi_receive_init(...);
      --refill_count;
	}
    ef_vi_receive_push(&vi);
  }
}

int main(int argc, char argv[]) (
  while( 1 ) {
    poll_events(&vi);
    refill_rx_ring(&vi);
  }
}
```

--------------------------------

### Initialize ef_vi Driver and Resources

Source: https://github.com/xilinx-cns/onload/blob/master/src/include/etherfabric/doxygen/050_examples.dox

Initializes the ef_vi driver, allocates a protection domain, and then allocates a virtual interface from that protection domain. This is a foundational step for network interface configuration.

```c
ef_driver_handle  driver_handle;
	ef_vi             vi;
	ef_pd             pd;
	static void do_init(int ifindex){
  ef_driver_open(&driver_handle);
  ef_pd_alloc(&pd, driver_handle, ifindex, EF_PD_DEFAULT );
  ef_vi_alloc_from_pd(&vi, driver_handle, &pd, driver_handle,
                      -1, -1, -1, NULL, -1, 0);
```

--------------------------------

### Run Trader Application with Normal and Delegated Sends

Source: https://github.com/xilinx-cns/onload/blob/master/src/include/etherfabric/doxygen/030_apps.dox

Provides command-line examples for running the trader_onload_ds_efvi application. It shows how to execute both normal socket-based sends and 'delegated' sends, specifying multicast interfaces and server IP addresses.

```sh
__Server:__ <code>onload -p latency-best ./exchange _mcast-intf_</code>

__Client:__ <code>onload -p latency-best ./trader_onload_ds_efvi _mcast-intf_ _server_</code>

__Server:__ <code>onload -p latency-best ./exchange _mcast-intf_</code>

__Client:__ <code>onload -p latency-best ./trader_onload_ds_efvi -d _mcast-intf_ _server_</code>
```

--------------------------------

### Enable Verbose Mode and Check Version

Source: https://context7.com/xilinx-cns/onload/llms.txt

Run applications with Onload in verbose mode for detailed debugging information. Also, check the installed Onload version.

```bash
onload -v ./my_app
onload --version
```

--------------------------------

### Post RX Packet Buffers for Reception

Source: https://github.com/xilinx-cns/onload/blob/master/src/include/etherfabric/doxygen/050_examples.dox

This function posts packet buffers to the RX descriptor ring for receiving incoming packets. It efficiently posts buffers in batches. It requires pre-allocated packet buffers and uses `ef_vi_receive_init` and `ef_vi_receive_push` from the Onload library. The function takes an integer `n` representing the number of buffers to post.

```c
unsigned rx_posted = 0;  /* We need to keep track of which buffers are
                          * already on the ring */
void rx_post( int n ) {
  for( int i = 0; i < n; ++i ) {
    struct pkt_buf* pb = pkt_bufs[rx_posted % N_RX_BUFS];
    ef_vi_receive_init(&vi, pb->dma_buf_addr, pb->id);
    ++rx_posted;
  }
  ef_vi_receive_push(&vi);

}
```

--------------------------------

### Setting up Userland Helper for Generic XDP Mode (Shell)

Source: https://github.com/xilinx-cns/onload/blob/master/README.md

This sequence of commands builds the bpf_link_helper tool and then configures the system to use it as the userland helper for generic XDP mode when AF_XDP is not natively supported by the network driver.

```shell
$ make -C ./src/tools/bpf_link_helper/
$ echo $(realpath ./src/tools/bpf_link_helper/bpf-link-helper) | sudo tee /sys/module/sfc_resource/parameters/bpf_link_helper
```

--------------------------------

### Launching Applications with OpenOnload (Shell)

Source: https://github.com/xilinx-cns/onload/blob/master/README.md

This demonstrates how to launch an application with OpenOnload acceleration. By prefixing the command with `onload`, the application's network I/O will be processed by the OpenOnload stack.

```shell
onload <your_application_command>
```

--------------------------------

### Structure for Packet Buffer Meta-data

Source: https://github.com/xilinx-cns/onload/blob/master/src/include/etherfabric/doxygen/050_examples.dox

Defines a structure to cache packet meta-data, such as DMA addresses and packet IDs, within each buffer. This structure is designed for cache alignment to improve performance.

```c
#define MEMBER_OFFSET(c_type, mbr_name) \
                     ((uint32_t) (uintptr_t)(&((c_type*)0)->mbr_name))
#define CACHE_ALIGN  __attribute__((aligned(EF_VI_DMA_ALIGN)))
struct pkt_buf {
  struct pkt_buf* next;
  /* We're not actually going to use this;
   * but chaining multiple buffers together is a common and useful trick. */
  ef_addr         dma_buf_addr;
  int             id;
  uint8_t         dma_buf[1] CACHE_ALIGN;
  /* Not strictly required, but cache aligning the payload is a speed
   * boost, so do it. */
};
/* We're also going to want to keep track of all our buffers, so have an
 * array of them.  Not strictly needed, but convenient.  */
    struct pkt_buf* pkt_bufs [N_BUFS];
    for( i = 0; i < N_BUFS; ++i ) {
      struct pkt_buf* pb = (struct pkt_buf*) ((char*) p + i * 2048);
      pb->id = i;
      pb->dma_buf_addr = ef_memreg_dma_addr(&memreg, i * 2048);
      pb->dma_buf_addr += MEMBER_OFFSET(struct pkt_buf, dma_buf);
      pkt_bufs[i] = pb;
    }
```

--------------------------------

### Stack Option Configuration API

Source: https://context7.com/xilinx-cns/onload/llms.txt

Programmatically configure Onload stack options at runtime. This API allows setting and getting integer and string options, and resetting all options to their default values.

```APIDOC
## Stack Option Configuration

### Description
Programmatically configure Onload stack options at runtime. This API allows setting and getting integer and string options, and resetting all options to their default values.

### Functions
- `onload_stack_opt_set_int(const char *name, int64_t value)`: Sets an integer stack option.
- `onload_stack_opt_set_str(const char *name, const char *value)`: Sets a string stack option.
- `onload_stack_opt_get_int(const char *name, int64_t *value)`: Gets an integer stack option.
- `onload_stack_opt_get_str(const char *name, char *buffer, size_t *len)`: Gets a string stack option.
- `onload_stack_opt_reset()`: Resets all stack options to their default values.

### Example Usage
```c
#include <onload/extensions.h>
#include <stdio.h>

int main() {
    // Set integer option: Enable TCP timestamps
    if (onload_stack_opt_set_int("EF_TCP_TIMESTAMPS", 1) != 0) {
        perror("Failed to set EF_TCP_TIMESTAMPS");
    }

    // Set string option: Configure interface
    if (onload_stack_opt_set_str("EF_INTERFACE", "eth0") != 0) {
        perror("Failed to set EF_INTERFACE");
    }

    // Get integer option
    int64_t tcp_sndbuf_val;
    if (onload_stack_opt_get_int("EF_TCP_SNDBUF", &tcp_sndbuf_val) == 0) {
        printf("EF_TCP_SNDBUF: %ld\n", tcp_sndbuf_val);
    }

    // Get string option
    char buffer[256];
    size_t len = sizeof(buffer);
    if (onload_stack_opt_get_str("EF_INTERFACE", buffer, &len) == 0) {
        printf("EF_INTERFACE: %s\n", buffer);
    }

    // Reset all options to defaults
    onload_stack_opt_reset();

    return 0;
}
```
```

--------------------------------

### Build Onload Driver and User Code Trees

Source: https://github.com/xilinx-cns/onload/blob/master/DEVELOPING.md

Commands to set up and build both the driver and user code components of Onload from the repository. This involves exporting the scripts directory to the PATH, constructing the build trees, and then compiling each component separately.

```bash
export PATH="$PWD/scripts:$PATH"

mmakebuildtree --driver
mmakebuildtree --user

make -C "$(mmaketool --toppath)/build/$(mmaketool --driverbuild)"
make -C "$(mmaketool --toppath)/build/$(mmaketool --userbuild)"
```

--------------------------------

### Transmit Packets (C)

Source: https://github.com/xilinx-cns/onload/blob/master/src/include/etherfabric/doxygen/040_using.dox

Demonstrates the process of transmitting packets using Onload. It involves constructing the packet with headers, posting it to the transmit ring using ef_vi_transmit_init, and then ringing the doorbell with ef_vi_transmit_push. The code also shows how to reclaim packet buffers after transmission.

```c
// construct packet with proper headers

// Post on the transmit ring
ef_vi_transmit_init(&vi, addr, len, id);
// Ring doorbell
ef_vi_transmit_push(&vi);

```

--------------------------------

### Allocate and Register Packet Buffers

Source: https://github.com/xilinx-cns/onload/blob/master/src/include/etherfabric/doxygen/050_examples.dox

Allocates a contiguous memory region and registers it for use as packet buffers with the ef_vi. It ensures proper alignment and size for hardware requirements, typically 2KB buffers.

```c
    const int BUF_SIZE = 2048;  /* Hardware always wants 2k buffers */
    int bytes = N_BUFS * BUF_SIZE;
    void* p;
    posix_memalign(&p, 4096, bytes)  /* allocate aligned memory */
    ef_memreg_alloc(&memreg, driver_handle, &pd, driver_handle,
	                p, bytes); /* Make it available to ef_vi */
```

--------------------------------

### Initialize and Set IP4 Local Filter Specification

Source: https://github.com/xilinx-cns/onload/blob/master/src/include/etherfabric/doxygen/050_examples.dox

Initializes an ef_filter_spec structure and sets it to capture IP4 UDP traffic destined for a specific local address. This is used to direct incoming traffic to the virtual interface.

```c
  struct sockaddr_in sa_local;  /* TODO: Fill this out somehow */
  ef_filter_spec filter_spec;
  ef_filter_spec_init(&filter_spec, EF_FILTER_FLAG_NONE);
  TRY(ef_filter_spec_set_ip4_local(&filter_spec, IPPROTO_UDP,

```

--------------------------------

### Configure Onload Logging via Environment Variables

Source: https://github.com/xilinx-cns/onload/blob/master/DEVELOPING.md

Configuration of Onload's logging levels using environment variables. EF_UNIX_LOG controls user-level logging for non-stack related events, and TP_LOG controls user-level logging for stack-related events. Default values are provided.

```bash
# User-level logging (non-stack)
export EF_UNIX_LOG=0x3

# User-level logging (stack related)
export TP_LOG=0xb
```

--------------------------------

### Transmit Packet

Source: https://github.com/xilinx-cns/onload/blob/master/src/include/etherfabric/doxygen/050_examples.dox

This snippet shows the basic function call to transmit a packet using the Onload library. It requires a pre-initialized packet buffer (`pb`) and its corresponding DMA address, along with the total frame length. The `ef_vi_transmit` function is used for this purpose. It's important to manage buffer usage after transmission.

```c
ef_vi_transmit(&vi, pb->dma_buf_addr, frame_length, 0);
```

--------------------------------

### Configure Onload Stack Options at Runtime (C)

Source: https://context7.com/xilinx-cns/onload/llms.txt

This C code snippet demonstrates how to programmatically set and retrieve Onload stack options at runtime using the `onload_stack_opt_set_int`, `onload_stack_opt_set_str`, `onload_stack_opt_get_int`, and `onload_stack_opt_get_str` functions. It also shows how to reset all options to their default values. Proper error handling using `perror` is included. Dependencies include the `<onload/extensions.h>` and `<stdio.h>` headers.

```c
#include <onload/extensions.h>
#include <stdio.h>

int main() {
    // Set integer option: Enable TCP timestamps
    if (onload_stack_opt_set_int("EF_TCP_TIMESTAMPS", 1) != 0) {
        perror("Failed to set EF_TCP_TIMESTAMPS");
    }

    // Set string option: Configure interface
    if (onload_stack_opt_set_str("EF_INTERFACE", "eth0") != 0) {
        perror("Failed to set EF_INTERFACE");
    }

    // Get integer option
    int64_t tcp_sndbuf_val;
    if (onload_stack_opt_get_int("EF_TCP_SNDBUF", &tcp_sndbuf_val) == 0) {
        printf("EF_TCP_SNDBUF: %ld\n", tcp_sndbuf_val);
    }

    // Get string option
    char buffer[256];
    size_t len = sizeof(buffer);
    if (onload_stack_opt_get_str("EF_INTERFACE", buffer, &len) == 0) {
        printf("EF_INTERFACE: %s\n", buffer);
    }

    // Reset all options to defaults
    onload_stack_opt_reset();

    return 0;
}

```

--------------------------------

### Run Application with Onload via LD_PRELOAD

Source: https://github.com/xilinx-cns/onload/blob/master/DEVELOPING.md

Method to run an application with Onload by preloading the Onload user-level library. This approach uses the LD_PRELOAD environment variable to specify the library path.

```bash
LD_PRELOAD="$(mmaketool --toppath)/build/$(mmaketool --userbuild)/lib/transport/unix/libcitransport0.so" <app>
```

--------------------------------

### Wait for and Handle Incoming Events

Source: https://github.com/xilinx-cns/onload/blob/master/src/include/etherfabric/doxygen/050_examples.dox

This function polls the event queue for incoming packets and transmission completion events. It handles RX events, RX discard events, and TX events. For efficiency, it polls multiple events at once. It requires an event queue and defines constants for event polling. The `handle_rx_packet` function is called for received packets.

```c
void rx_wait(void) {
  /* Again, for efficiency, poll multiple events at once.  */
  ef_event      evs[NUM_POLL_EVENTS];
  int           n_ev, i;

  while( 1 ) {
    n_ev = ef_eventq_poll(&vi, evs, NUM_POLL_EVENTS);
    if( n_ev > 0 )
      for( i = 0; i < n_ev; ++i )
        switch( EF_EVENT_TYPE(evs[i]) ) {
        case EF_EVENT_TYPE_RX:
          handle_rx_packet(EF_EVENT_RX_RQ_ID(evs[i]),
                           EF_EVENT_RX_BYTES(evs[i]) );
          break;
        case EF_EVENT_TYPE_RX_DISCARD:
          /* Interesting to print out the cause of the discard */
          fprintf(stderr, "ERROR: RX_DISCARD type=%d",
                  EF_EVENT_RX_DISCARD_TYPE(evs[i]));
          /* but let's handle it like a normal packet anyway */
          handle_rx_packet(EF_EVENT_RX_RQ_ID(evs[i]),
                           EF_EVENT_RX_BYTES(evs[i]) );
          break;
        case EF_EVENT_TYPE_TX:
          ef_vi_transmit_unbundle(&vi, &evs[i], ids);
          break;
}
}
}
```

--------------------------------

### Run Application with Onload via onload Script

Source: https://github.com/xilinx-cns/onload/blob/master/DEVELOPING.md

Alternative method to run an application with Onload using the provided 'onload' script. This script likely handles the necessary environment variable configurations automatically.

```bash
scripts/onload <app>
```

--------------------------------

### Get TCP Connection Information using Onload C Extension

Source: https://context7.com/xilinx-cns/onload/llms.txt

Retrieves detailed internal TCP connection state information beyond standard TCP_INFO using the onload_get_tcp_info function. This C code requires the onload/extensions.h header and is intended for use with Onload-accelerated TCP sockets. It outputs buffer sizes, window information, and calculated send capacity.

```c
#include <onload/extensions.h>
#include <sys/socket.h>
#include <stdio.h>

int main() {
    int sock = socket(AF_INET, SOCK_STREAM, 0);

    // Connect to server (connection setup omitted)
    // connect(sock, ...);

    struct onload_tcp_info info;
    int len = sizeof(info);

    if (onload_get_tcp_info(sock, &info, &len) == 0) {
        printf("=== Onload TCP Info ===\n");
        printf("Receive buffer:\n");
        printf("  SO_RCVBUF: %d bytes\n", info.so_recvbuf);
        printf("  Buffer used: %d bytes\n", info.rcvbuf_used);
        printf("  Receive window: %d bytes\n", info.rcv_window);

        printf("\nSend buffer:\n");
        printf("  SO_SNDBUF: %d bytes\n", info.so_sndbuf);
        printf("  SO_SNDBUF packets: %d\n", info.so_sndbuf_pkts);
        printf("  Packets available: %d\n", info.sndbuf_pkts_avail);
        printf("  MSS: %d bytes\n", info.snd_mss);

        printf("\nWindows:\n");
        printf("  Send window: %d bytes\n", info.snd_window);
        printf("  Congestion window: %d bytes\n", info.cong_window);

        // Calculate how much we can send right now
        int can_send = info.snd_window < info.cong_window ?
                       info.snd_window : info.cong_window;
        printf("\nCan send immediately: %d bytes\n", can_send);
    } else {
        printf("Socket is not an Onload-accelerated TCP socket\n");
    }

    close(sock);
    return 0;
}

```

--------------------------------

### Launch Applications with Onload Acceleration using Wrapper Script

Source: https://context7.com/xilinx-cns/onload/llms.txt

Launches applications with Onload acceleration using the 'onload' wrapper script. This is a command-line utility for enabling Onload's performance benefits without modifying application code. It supports basic execution and the use of specific configuration profiles.

```bash
# Basic usage - run application with Onload
onload ./my_server

# Use specific configuration profile
onload --profile=latency ./trading_app

```

--------------------------------

### Building OpenOnload without SFC Driver (onload_build)

Source: https://github.com/xilinx-cns/onload/blob/master/README.md

When using the `onload_build` script, the `--no-sfc` parameter instructs the build process to exclude AMD Solarflare NIC support, focusing solely on AF_XDP acceleration.

```shell
onload_build --no-sfc
```

--------------------------------

### Registering Interfaces for AF_XDP Acceleration (Shell)

Source: https://github.com/xilinx-cns/onload/blob/master/README.md

This command registers a network interface (e.g., ens2f0) to be accelerated using AF_XDP. This is typically done when using non-AMD Solarflare interfaces with OpenOnload.

```shell
echo ens2f0 > /sys/module/sfc_resource/afxdp/register
```

--------------------------------

### Run All Onload Unit Tests

Source: https://github.com/xilinx-cns/onload/blob/master/DEVELOPING.md

Command to execute a script that builds and runs all the unit tests for Onload. These tests are located within the user build tree.

```bash
scripts/run_unit_tests.sh
```

--------------------------------

### Building OpenOnload without SFC Driver (Make)

Source: https://github.com/xilinx-cns/onload/blob/master/README.md

This make command variable `HAVE_SFC=0` is used to build OpenOnload specifically for AF_XDP acceleration, excluding support for AMD Solarflare NICs and their native ef_vi interface.

```make
make HAVE_SFC=0
```

--------------------------------

### Packet Receiving Initialization

Source: https://github.com/xilinx-cns/onload/blob/master/src/include/etherfabric/doxygen/040_using.dox

Functionality for preparing and posting descriptors for receiving packets.

```APIDOC
## Packet Receiving Initialization

### Description
This section outlines the basic process for receiving packets, focusing on the initialization and posting of descriptors to the receive descriptor ring using specific `ef_vi` functions.

### Process
1.  **Post Descriptors**: Initiate empty packet buffers onto the RX descriptor ring using `ef_vi_receive_init()`, `ef_vi_receive_push()`, or `ef_vi_receive_post()`.

### Important Considerations
-   **Descriptor Posting Multiples**: Receive descriptors should be posted in multiples of 8. If fewer than 8 descriptors are pushed when the ring is empty before blocking on the event queue, the application may remain blocked as no descriptors will be available for packet reception.
-   **Ignoring Small Batches**: The `ef_vi` layer ignores descriptor batch sizes less than 8.
```

--------------------------------

### Configure Onload Behavior with Environment Variables

Source: https://context7.com/xilinx-cns/onload/llms.txt

Set environment variables to customize Onload's behavior, such as network interface selection, TCP timestamping, buffer sizes, stack naming, CPU usage (spinning), hardware timestamping, and logging. Applications can then be run with these configurations.

```bash
export EF_INTERFACE=eth0
export EF_TCP_TIMESTAMPS=1
export EF_TCP_SNDBUF=524288
export EF_TCP_RCVBUF=524288
export EF_NAME=my_application_stack
export EF_POLL_USEC=0
export EF_TX_TIMESTAMPING=1
export EF_RX_TIMESTAMPING=1
export EF_UNIX_LOG=0x3
export TP_LOG=0xb

# Run application with configuration
onload ./my_app

# Or use LD_PRELOAD directly
LD_PRELOAD=libonload.so ./my_app
```

--------------------------------

### Run Applications with Onload Profiles

Source: https://context7.com/xilinx-cns/onload/llms.txt

Execute applications with specified Onload profiles for latency optimization. Profiles can be comma-separated, and settings can be forced to override environment variables. Application-specific handlers can also be disabled.

```bash
onload --profile=latency,low-latency ./hft_app
onload --force-profiles --profile=latency ./app
onload --no-app-handler ./generic_app
```

--------------------------------

### Buffering and Overhead Query Functions

Source: https://github.com/xilinx-cns/onload/blob/master/src/include/etherfabric/doxygen/040_using.dox

Utilities for querying transmit buffering capabilities and packet overheads.

```APIDOC
## Buffering and Overhead Query Functions

### Description
These C functions provide mechanisms to query the buffering characteristics and per-packet overheads related to transmit operations, as well as calculate the buffer usage for a given packet length.

### Functions

- **ef_vi_transmit_alt_query_buffering**
  - **Description**: Queries the amount of user-visible buffering available for transmit alternatives.
  - **Parameters**:
    - `vi` (*struct ef_vi*): Pointer to the virtual interface structure.
    - `ifindex` (*int*): The interface index.
    - `vi_dh` (*ef_driver_handle*): The driver handle for the virtual interface.
    - `n_alts` (*int*): The number of transmit alternatives.
  - **Return**: The amount of available buffering on success, a negative error code on failure.

- **ef_vi_transmit_alt_query_overhead**
  - **Description**: Queries the per-packet overheads for transmit operations.
  - **Parameters**:
    - `vi` (*ef_vi*): Pointer to the virtual interface structure.
    - `params` (*struct ef_vi_transmit_alt_overhead*): Pointer to a structure to store the overhead parameters.
  - **Return**: 0 on success, a negative error code on failure.

- **ef_vi_transmit_alt_usage**
  - **Description**: Calculates the buffer usage for a packet based on provided overheads and packet length.
  - **Parameters**:
    - `params` (*const struct ef_vi_transmit_alt_overhead*): Pointer to the structure containing per-packet overheads.
    - `pkt_len` (*uint32_t*): The length of the packet.
  - **Return**: The calculated buffer usage in bytes.
```

--------------------------------

### Event Queue Handling

Source: https://github.com/xilinx-cns/onload/blob/master/src/include/etherfabric/doxygen/040_using.dox

Mechanisms for retrieving events from the adapter, including polling and blocking.

```APIDOC
## Event Queue Handling

### Description
This section describes how applications can retrieve events from the adapter's event queue, which notifies software about packet arrivals and transmit completions. It covers both busy-waiting and blocking methods, as well as considerations for timestamping and event queue overflow.

### Methods

- **ef_eventq_poll()**
  - **Description**: Retrieves events from the event queue via busy-waiting. Offers the lowest latency but consumes CPU cycles.
  - **Usage**: Call repeatedly in a loop. The batch size should be at least `EF_VI_EVENT_POLL_MIN_EVS`.

- **ef_eventq_wait()**
  - **Description**: Blocks the calling thread until events are available or a timeout occurs. Frees up CPU resources.

### Timestamping and Overflow
- When timestamping is enabled, timestamp events are added to the queue even without packet reception. Regular polling is essential to prevent event queue overflow (`EF_EVENT_TYPE_OFLOW`), which can lead to an undetermined state for the VI.

### File Descriptor Integration
- The `ef_vi` layer supports integration with `select()`, `poll()`, and `epoll()` using a file descriptor associated with the virtual interface.
- Before blocking on the file descriptor, call `ef_vi_prime()` to prime interrupts.

#### **ef_vi_prime()**
- **Description**: Primes interrupts on the virtual interface for file descriptor blocking.
- **Parameters**:
  - `vi` (*ef_vi*): Pointer to the virtual interface structure.
  - `dh` (*ef_driver_handle*): The driver handle used to allocate the virtual interface.
  - `current_ptr` (*unsigned*): The value obtained from `ef_eventq_current()`, indicating the number of events already read.
- **Usage**: Call this function before blocking on the file descriptor. After the file descriptor becomes readable and events are processed, `ef_vi_prime()` must be called again with the updated `ef_eventq_current()` value before blocking further.
```

--------------------------------

### Programmed I/O (PIO) with ef_pio_link_vi()

Source: https://github.com/xilinx-cns/onload/blob/master/src/include/etherfabric/doxygen/040_using.dox

Utilizes Programmed I/O on 7000-series cards for faster small packet transmission. Requires explicit PIO buffer allocation and association with a virtual interface using `ef_pio_link_vi()`. Data is copied using `ef_pio_memcpy()`. The buffer must be unlinked with `ef_pio_unlink_vi()` and freed with `ef_pio_free()` when no longer needed.

```c
int rc;
struct ef_pio_buffer* pio_buffer;

// Allocate and associate PIO buffer
rc = ef_pio_link_vi(vi, vi_dh, &pio_buffer, buffer_size);
if (rc < 0) {
    // Handle error
}

// Copy data to PIO buffer
memcpy(ef_pio_buffer_address(pio_buffer), data, data_len);
// Or using ef_pio_memcpy if available and preferred
// ef_pio_memcpy(pio_buffer, data, data_len);

// ... transmit data ...

// Unlink and free PIO buffer
rc = ef_pio_unlink_vi(vi, vi_dh, pio_buffer);
if (rc < 0) {
    // Handle error
}
rc = ef_pio_free(pio_buffer);
if (rc < 0) {
    // Handle error
}
```

--------------------------------

### Allocate a Virtual Interface (C)

Source: https://github.com/xilinx-cns/onload/blob/master/src/include/etherfabric/doxygen/040_using.dox

Function to allocate a virtual interface (VI) from a given protection domain (PD). This function requires the driver handles for the VI and PD, the PD object, and parameters specifying queue capacities and optional event queue details.

```c
/* Allocate a virtual interface */
int ef_vi_alloc_from_pd(ef_vi *vi, ef_driver_handle vi_dh,
                        ef_pd *pd, ef_driver_handle pd_dh,
                        int eventq_cap, int rxq_cap, int txq_cap,
                        ef_vi *opt_evq, ef_driver_handle opt_evq_dh,
                        enum ef_vi_flags flags));
```

--------------------------------

### Configure Onload Kernel Logging via Module Options

Source: https://github.com/xilinx-cns/onload/blob/master/DEVELOPING.md

Configuration of Onload's kernel-level logging using module options. oo_debug_bits controls kernel logging for non-stack events, and ci_tp_log controls kernel logging for stack-related events. Default values and a value for enabling all bits are shown.

```bash
# Kernel logging (non-stack)
# Example: oo_debug_bits=0x7fffffff (all bits)
# Default: oo_debug_bits=0x1

# Kernel logging (stack related)
# Default: ci_tp_log=0xf
```

--------------------------------

### Register Interfaces for AF_XDP Acceleration

Source: https://context7.com/xilinx-cns/onload/llms.txt

Register non-Solarflare network interfaces for acceleration using AF_XDP. This involves writing the interface name to a specific sysfs path. For generic XDP mode, a userland helper must first be built and configured.

```bash
# Register interface for AF_XDP acceleration
echo ens2f0 | sudo tee /sys/module/sfc_resource/afxdp/register

# For generic XDP mode (if native mode not supported)
# First build and configure userland helper
make -C ./src/tools/bpf_link_helper/
echo $(realpath ./src/tools/bpf_link_helper/bpf-link-helper) | \
    sudo tee /sys/module/sfc_resource/parameters/bpf_link_helper

# Then register interface
echo ens2f0 | sudo tee /sys/module/sfc_resource/afxdp/register
```

--------------------------------

### Allocate Zero-Copy Buffers using Onload C Extension

Source: https://context7.com/xilinx-cns/onload/llms.txt

Allocates and manages zero-copy buffers for high-performance network I/O using onload_zc_alloc_buffers. This C code requires onload/extensions_zc.h and demonstrates buffer allocation, filling, sending (commented out), awaiting stack synchronization, and releasing buffers. It's suitable for UDP and other protocols where zero-copy is beneficial.

```c
#include <onload/extensions_zc.h>
#include <sys/socket.h>
#include <stdio.h>
#include <string.h>

int main() {
    int sock = socket(AF_INET, SOCK_DGRAM, 0);
    if (sock < 0) {
        perror("socket");
        return 1;
    }

    // Allocate 4 zero-copy buffers for UDP
    struct onload_zc_iovec iovecs[4];
    int rc = onload_zc_alloc_buffers(sock, iovecs, 4,
                                     ONLOAD_ZC_BUFFER_HDR_UDP);
    if (rc < 0) {
        perror("onload_zc_alloc_buffers");
        return 1;
    }

    printf("Allocated %d zero-copy buffers:\n", 4);
    for (int i = 0; i < 4; i++) {
        printf("  Buffer %d: base=%p, len=%lu\n",
               i, iovecs[i].iov_base, (unsigned long)iovecs[i].iov_len);

        // Fill buffer with data
        memset(iovecs[i].iov_base, 'A' + i, iovecs[i].iov_len);
    }

    // Send data from first buffer (send implementation omitted)
    // onload_zc_send(...);

    // Wait for stack to finish using buffers
    rc = onload_zc_await_stack_sync(sock);
    if (rc < 0) {
        perror("onload_zc_await_stack_sync");
    }

    // Release all buffers
    onload_zc_handle handles[4];
    for (int i = 0; i < 4; i++) {
        handles[i] = iovecs[i].buf;
    }

    rc = onload_zc_release_buffers(sock, handles, 4);
    if (rc < 0) {
        perror("onload_zc_release_buffers");
        return 1;
    }

    printf("Released all zero-copy buffers\n");

    close(sock);
    return 0;
}

```
Tokens:
Raw