Designing backward compatible eBPF extension API

[shankarseal]

The 0.14 release of eBPF introduced a regression, which broke existing extensions (such as XDP for Windows. This is tracked by #3277 and fixed in 0.14.1 via #3263. The crux of the problem was that some of the APIs used for eBPF extensions are not backward compatible because they lack the version information.

In Windows, there are two well-known pattern for authoring versioned APIs.

1. The WFP API way – where every struct and function has a version suffix. There are version independent APIs that resolve to the latest API defined in the Windows SDK.

2. The NDIS way – where every struct has a header with version information. Different versions of the struct have different fields but the type name does not change. Here is an example.

The proposal is to use the NDIS pattern for the eBPF extension APIs. This is somewhat already followed in the ebpf_extension_data_t type.

typedef struct _ebpf_extension_data
{
    uint16_t version;
    size_t size;
    const void* data;
} ebpf_extension_data_t;

This is used in the various NMR provider (program info, hook) and client (link) characteristics.

The proposed changes are as follows:

1. define a new extension data header type:

typedef struct _ebpf_extension_data_header
{
    uint16_t version;
    size_t size;
} ebpf_extension_data_header_t;

2. Re-define ebpf_program_data_t and ebpf_program_section_info_t to use the above header struct.

3. Re-define the NMR contracts (data types) and store API parameters to use the new data types.

4. Modify eBPF core logic to look at the version information, before reading the rest of the program / section information structures. The eBPF core will always allocate the object for the latest data types it supports and copy the data supplied by older extensions. It will then fill the newer fields with safe defaults.

For example, version 1 of ebpf_helper_function_prototype_t will have the new reallocate_packet bitfield. When initializing older extensions (version 0), eBPF core will initialize this bitfield with FALSE.

Note: This will be a breaking change and will require all eBPF extensions have to be updated.