extension_header (#3326) (#3414)

* extension_header

* fix logic error.

* Re-purposing the size field to act as the "minor version". Additional validation checks are added.

* PR Feedback.

* fix break due to bad merge with PR #3372

docs/eBpfExtensions.md

@@ -62,8 +62,23 @@ initialized as follows:
 * `NpiSpecificCharacteristics`: Pointer to structure of type `ebpf_extension_data_t`.
   * The `data` field of this structure should point to a structure of type `ebpf_program_data_t`.
 
+#### `ebpf_extension_header_t` Struct
+This is a mandatory header that is common to all data structures needed by eBPF extensions to register with the eBPF framework.
+* `version`: Version of the extension data structure.
+* `size`: Size of the extension data structure.
+ When populating these data structures, the correct `version` and `size` fields must be set. The set of current version numbers and the
+ size for the various extension structures are listed in `ebpf_windows.h`. For example:
+```c
+ #define EBPF_PROGRAM_TYPE_DESCRIPTOR_CURRENT_VERSION 1
+ #define EBPF_PROGRAM_TYPE_DESCRIPTOR_CURRENT_VERSION_SIZE \
+    (EBPF_OFFSET_OF(ebpf_program_type_descriptor_t, is_privileged) + sizeof(char))
+```
+> NOTE: Extension developers **must not** set the `size` field of these structures to `sizeof()` of the corresponding type. Instead,
+> the `CURRENT_VERSION_SIZE` macros defined in `ebpf_windows.h` should be used.
+
 #### `ebpf_program_data_t` Struct
 The various fields of this structure should be set as follows:
+* `header`: Version and size.
 * `program_info`: Pointer to `ebpf_program_info_t`.
 * `program_type_specific_helper_function_addresses`: Pointer to `ebpf_helper_function_addresses_t`. This structure
 provides the helper functions that are exclusive to this program type.
@@ -77,12 +92,14 @@ context structure and populates the returned data and context buffers.
 
 #### `ebpf_program_info_t` Struct
 The various fields of this structure should be set as follows:
-* `program_type_descriptor`: Field of type `ebpf_program_type_descriptor_t`.
+* `header`: Version and size.
+* `program_type_descriptor`: Pointer to `ebpf_program_type_descriptor_t`.
 * `count_of_helpers`: The number of helper functions that are implemented by this extension for the given program type.
 * `helper_prototype`: Pointer to array of `ebpf_helper_function_prototype_t`.
 
 #### `ebpf_program_type_descriptor_t` Struct
 The various fields of this structure should be set as follows:
+* `header`: Version and size.
 * `name`: Friendly name of the program type.
 * `context_descriptor`: Pointer of type `ebpf_context_descriptor_t`.
 * `program_type`: GUID for the program type. This should be the same as the `NpiId` in `NPI_REGISTRATION_INSTANCE` as
@@ -94,6 +111,7 @@ field should be set to `0 (BPF_PROG_TYPE_UNSPEC)`.
 #### `ebpf_context_descriptor_t` Struct
 This structure (as the name signifies) provides a description of the context parameter that a hook passes when
 invoking an eBPF program. The various fields of this struct are as follows.
+* `header`: Version and size.
 * `size`: Size of the context structure.
 * `data`: Offset (in bytes) to the field in the context structure that is pointing to the beginning of context data.
 * `end`: Offset (in bytes) to the field in the context structure that is pointing to the end of context data.
@@ -124,6 +142,7 @@ in the context descriptor.
 
 #### `ebpf_helper_function_prototype_t` Struct
 This structure is used to describe the prototypes of the various helper functions implemented by the extension.
+* `header`: Version and size.
 * `helper_id`: Integer signifying the helper function ID. (See section 2.6).
 Helper function IDs for different program types need not be unique.
 * `name`: Helper function name.
@@ -189,7 +208,17 @@ This optional function is used to populate the flat buffers representing the dat
 returned to the application when the `bpf_prog_test_run_opts` call completes. In addition, the function frees any
 resources allocated in the `ebpf_program_context_create_t` call.
 
-### 2.2 Program Information NPI Client Attach and Detach Callbacks
+### 2.2 Backward compatibility of the Extension data structures
+All the extension data structures are versioned. To maintain backward compatibility with the existing extensions, new fields **MUST** be added
+to the end of a data structure. The constant defining the current size of the modified struct will be updated in `ebpf_windows.h`. Existing
+eBPF extensions will continue to work without requiring recompilation. If an extension is modified to use a newly added field, the length
+field must be updated accordingly.
+
+If the change in data structure is such that it is no longer backward compatible (such as changing field type or position),
+then the version number will be updated. In this case, the product version of eBPF for Windows must be updated to indicate a breaking change
+as well. Existing eBPF extensions would need to be re-compiled to work with the latest version of eBPF.
+
+### 2.3 Program Information NPI Client Attach and Detach Callbacks
 The eBPF Execution Context registers a Program Information NPI client module with the NMR for every eBPF program that
 gets loaded. The Execution Context will use the program type GUID of the program as the NPI ID of the client module.
 And as a result, upon eBPF program load, the associated Program Information NPI client module will attach with the
@@ -198,7 +227,7 @@ client or provider dispatch tables. Neither does the client's `NpiSpecificCharac
 special processing is required in the client attach and detach callback handler on the provider module. An extension
 must not unload until there are no more attached Program Information NPI clients.
 
-### 2.3 Hook NPI Provider Registration
+### 2.4 Hook NPI Provider Registration
 When registering itself to the NMR, the Hook NPI provider should have the
 [`NPI_REGISTRATION_INSTANCE`](https://docs.microsoft.com/en-us/windows-hardware/drivers/ddi/netioddk/ns-netioddk-_npi_registration_instance)
 initialized as follows:
@@ -220,7 +249,7 @@ requested attach type is supported by the Hook NPI provider. If not, the eBPF pr
 The `bpf_attach_type` field should contain the equivalent bpf attach type integer. If there is no equivalent bpf
 attach type, this field should be set to `0 (BPF_ATTACH_TYPE_UNSPEC)`.
 
-### 2.4 Hook NPI Client Attach and Detach Callbacks
+### 2.5 Hook NPI Client Attach and Detach Callbacks
 The eBPF Execution Context registers a Hook NPI client module with the NMR for each program that is attached to a hook.
 The attach type GUID is used as the NPI of the client module. And as a result, when an eBPF program gets attached to
 a hook, the associated Hook NPI client module will attach to the corresponding Hook NPI provider module in the
@@ -246,7 +275,7 @@ Upon
 [client detach callback](https://docs.microsoft.com/en-us/windows-hardware/drivers/ddi/netioddk/nc-netioddk-npi_provider_detach_client_fn)
 the provider must free the per-client context passed in via `ProviderBindingContext` parameter.
 
-### 2.5 Invoking an eBPF program from Hook NPI Provider
+### 2.6 Invoking an eBPF program from Hook NPI Provider
 To invoke an eBPF program, the extension uses the dispatch table supplied by the Hook NPI client during attaching.
 The client dispatch table contains the functions, with the following type prototypes:
 
@@ -330,7 +359,7 @@ of time a batch is open and must not change IRQL between calling batch begin and
 the number of times the program has been invoked, so callers should limit the number of calls within a batch to
 prevent long delays in batch end.
 
-### 2.6 Authoring Helper Functions
+### 2.7 Authoring Helper Functions
 An extension can provide an implementation of helper functions that can be invoked by the eBPF programs. The helper
 functions can be of two types:
 1. Program-Type specific: These helper functions can only be invoked by eBPF programs of a given program type. Usually,
@@ -356,7 +385,7 @@ The helper function ID for a general helper function must be in the range 0 - 65
 The parameter and return types for these helper functions must adhere to the `ebpf_argument_type_t` and
 `ebpf_return_type_t` enums.
 
-### 2.7 Registering Program Types and Attach Types - eBPF Store
+### 2.8 Registering Program Types and Attach Types - eBPF Store
 The eBPF Execution Context loads an eBPF program from an ELF file that has program section(s) with section names. The
 prefix to these names determines the program type. For example, the section name `"xdp_test"` implies that the corresponding
 program type is `EBPF_PROGRAM_TYPE_XDP_TEST`.
@@ -373,15 +402,15 @@ To operate on the eBPF store, the user mode application needs to link with eBPFA
         _In_reads_(section_info_count) const ebpf_program_section_info_t* section_info, uint32_t section_info_count);
     ```
 
-- `ebpf_store_update_program_information`: updates program information in the eBPF store, given a pointer to an array of program information (i.e., `_ebpf_program_info`):
+- `ebpf_store_update_program_information_array`: updates program information in the eBPF store, given a pointer to an array of program information (i.e., `_ebpf_program_info`):
 
     ```c
     ebpf_result_t
-    ebpf_store_update_program_information(
+    ebpf_store_update_program_information_array(
         _In_reads_(program_info_count) const ebpf_program_info_t* program_info, uint32_t program_info_count);
     ```
 
-### 2.8 eBPF Sample Driver
+### 2.9 eBPF Sample Driver
 The eBPF for Windows project provides a
 [sample extension driver](https://github.com/microsoft/ebpf-for-windows/tree/8f46b4020f79c32f994d3a59671ce8782e4b4cf0/tests/sample/ext)
 as an example for how to implement an extension. This simple extension exposes a new program type, and implements a

ebpfapi/Source.def

@@ -119,7 +119,7 @@ EXPORTS
     ebpf_program_query_info
     ebpf_store_delete_program_information
     ebpf_store_delete_section_information
-    ebpf_store_update_program_information
+    ebpf_store_update_program_information_array
     ebpf_store_update_section_information
     libbpf_attach_type_by_name
     libbpf_bpf_attach_type_str

include/ebpf_extension.h

@@ -87,13 +87,13 @@ typedef struct _ebpf_extension_program_dispatch_table
 
 typedef struct _ebpf_extension_data
 {
-    uint16_t version;
-    size_t size;
+    ebpf_extension_header_t header;
     const void* data;
 } ebpf_extension_data_t;
 
 typedef struct _ebpf_attach_provider_data
 {
+    ebpf_extension_header_t header;
     ebpf_program_type_t supported_program_type;
     bpf_attach_type_t bpf_attach_type;
     enum bpf_link_type link_type;
@@ -118,9 +118,4 @@ typedef struct _ebpf_execution_context_state
         const void* next_program;
         uint32_t count;
     } tail_call_state;
-} ebpf_execution_context_state_t;
-
-#define EBPF_ATTACH_CLIENT_DATA_VERSION 0
-#define EBPF_ATTACH_PROVIDER_DATA_VERSION 1
-#define EBPF_PROGRAM_INFORMATION_PROVIDER_DATA_VERSION 0
-#define EBPF_MAX_GENERAL_HELPER_FUNCTION 0xFFFF
+} ebpf_execution_context_state_t;

include/ebpf_program_attach_type_guids.h

@@ -21,69 +21,98 @@ extern "C"
     __declspec(selectany) ebpf_attach_type_t EBPF_ATTACH_TYPE_XDP = {
         0x85e0d8ef, 0x579e, 0x4931, {0xb0, 0x72, 0x8e, 0xe2, 0x26, 0xbb, 0x2e, 0x9d}};
 
+#define EBPF_ATTACH_TYPE_BIND_GUID                                                     \
+    {                                                                                  \
+        0xb9707e04, 0x8127, 0x4c72, { 0x83, 0x3e, 0x05, 0xb1, 0xfb, 0x43, 0x94, 0x96 } \
+    }
     /** @brief Attach type for handling socket bind() requests.
      *
      * Program type: \ref EBPF_PROGRAM_TYPE_BIND
      */
-    __declspec(selectany) ebpf_attach_type_t EBPF_ATTACH_TYPE_BIND = {
-        0xb9707e04, 0x8127, 0x4c72, {0x83, 0x3e, 0x05, 0xb1, 0xfb, 0x43, 0x94, 0x96}};
+    __declspec(selectany) ebpf_attach_type_t EBPF_ATTACH_TYPE_BIND = EBPF_ATTACH_TYPE_BIND_GUID;
 
+#define EBPF_ATTACH_TYPE_CGROUP_INET4_CONNECT_GUID                                     \
+    {                                                                                  \
+        0xa82e37b1, 0xaee7, 0x11ec, { 0x9a, 0x30, 0x18, 0x60, 0x24, 0x89, 0xbe, 0xee } \
+    }
     /** @brief The programs attached to the INET4_CONNECT hook will be invoked for
      * connect() calls on TCP or UDP sockets or when a UDP socket sends a packet to
      * a unique remote address/port tuple.
      *
      * Program type: \ref EBPF_PROGRAM_TYPE_CGROUP_SOCK_ADDR
      */
-    __declspec(selectany) ebpf_attach_type_t EBPF_ATTACH_TYPE_CGROUP_INET4_CONNECT = {
-        0xa82e37b1, 0xaee7, 0x11ec, {0x9a, 0x30, 0x18, 0x60, 0x24, 0x89, 0xbe, 0xee}};
+    __declspec(selectany)
+        ebpf_attach_type_t EBPF_ATTACH_TYPE_CGROUP_INET4_CONNECT = EBPF_ATTACH_TYPE_CGROUP_INET4_CONNECT_GUID;
 
+#define EBPF_ATTACH_TYPE_CGROUP_INET6_CONNECT_GUID                                     \
+    {                                                                                  \
+        0xa82e37b2, 0xaee7, 0x11ec, { 0x9a, 0x30, 0x18, 0x60, 0x24, 0x89, 0xbe, 0xee } \
+    }
     /** @brief The programs attached to the INET6_CONNECT hook will be invoked for
      * connect() calls on TCP or UDP sockets or when a UDP socket sends a packet to
      * a unique remote address/port tuple.
      *
      * Program type: \ref EBPF_PROGRAM_TYPE_CGROUP_SOCK_ADDR
      */
-    __declspec(selectany) ebpf_attach_type_t EBPF_ATTACH_TYPE_CGROUP_INET6_CONNECT = {
-        0xa82e37b2, 0xaee7, 0x11ec, {0x9a, 0x30, 0x18, 0x60, 0x24, 0x89, 0xbe, 0xee}};
+    __declspec(selectany)
+        ebpf_attach_type_t EBPF_ATTACH_TYPE_CGROUP_INET6_CONNECT = EBPF_ATTACH_TYPE_CGROUP_INET6_CONNECT_GUID;
 
+#define EBPF_ATTACH_TYPE_CGROUP_INET4_RECV_ACCEPT_GUID                                 \
+    {                                                                                  \
+        0xa82e37b3, 0xaee7, 0x11ec, { 0x9a, 0x30, 0x18, 0x60, 0x24, 0x89, 0xbe, 0xee } \
+    }
     /** @brief The programs attached to the INET4_RECV_ACCEPT hook will get invoked for
      *  TCP accept() calls or for the first unicast UDP packet from a unique remote
      *  address/port tuple.
      *
      * Program type: \ref EBPF_PROGRAM_TYPE_CGROUP_SOCK_ADDR
      */
-    __declspec(selectany) ebpf_attach_type_t EBPF_ATTACH_TYPE_CGROUP_INET4_RECV_ACCEPT = {
-        0xa82e37b3, 0xaee7, 0x11ec, {0x9a, 0x30, 0x18, 0x60, 0x24, 0x89, 0xbe, 0xee}};
+    __declspec(selectany)
+        ebpf_attach_type_t EBPF_ATTACH_TYPE_CGROUP_INET4_RECV_ACCEPT = EBPF_ATTACH_TYPE_CGROUP_INET4_RECV_ACCEPT_GUID;
 
+#define EBPF_ATTACH_TYPE_CGROUP_INET6_RECV_ACCEPT_GUID                                 \
+    {                                                                                  \
+        0xa82e37b4, 0xaee7, 0x11ec, { 0x9a, 0x30, 0x18, 0x60, 0x24, 0x89, 0xbe, 0xee } \
+    }
     /** @brief The programs attached to the INET6_RECV_ACCEPT hook will get invoked for
      *  TCP accept() calls or for the first unicast UDP packet from a unique remote
      *  address/port tuple.
      *
      * Program type: \ref EBPF_PROGRAM_TYPE_CGROUP_SOCK_ADDR
      */
-    __declspec(selectany) ebpf_attach_type_t EBPF_ATTACH_TYPE_CGROUP_INET6_RECV_ACCEPT = {
-        0xa82e37b4, 0xaee7, 0x11ec, {0x9a, 0x30, 0x18, 0x60, 0x24, 0x89, 0xbe, 0xee}};
+    __declspec(selectany)
+        ebpf_attach_type_t EBPF_ATTACH_TYPE_CGROUP_INET6_RECV_ACCEPT = EBPF_ATTACH_TYPE_CGROUP_INET6_RECV_ACCEPT_GUID;
 
+#define EBPF_ATTACH_TYPE_CGROUP_SOCK_OPS_GUID                                          \
+    {                                                                                  \
+        0x837d02cd, 0x3251, 0x4632, { 0x8d, 0x94, 0x60, 0xd3, 0xb4, 0x57, 0x69, 0xf2 } \
+    }
     /** @brief Attach type for handling socket event notifications.
      *
      * Program type: \ref EBPF_PROGRAM_TYPE_SOCK_OPS
      */
-    __declspec(selectany) ebpf_attach_type_t EBPF_ATTACH_TYPE_CGROUP_SOCK_OPS = {
-        0x837d02cd, 0x3251, 0x4632, {0x8d, 0x94, 0x60, 0xd3, 0xb4, 0x57, 0x69, 0xf2}};
+    __declspec(selectany) ebpf_attach_type_t EBPF_ATTACH_TYPE_CGROUP_SOCK_OPS = EBPF_ATTACH_TYPE_CGROUP_SOCK_OPS_GUID;
+
+#define EBPF_ATTACH_TYPE_SAMPLE_GUID                                                   \
+    {                                                                                  \
+        0xf788ef4b, 0x207d, 0x4dc3, { 0x85, 0xcf, 0x0f, 0x2e, 0xa1, 0x07, 0x21, 0x3c } \
+    }
 
     /** @brief Attach type implemented by eBPF Sample Extension driver, used for testing.
      *
-     * Program type: \ref EBPF_PROGRAM_TYPE_SAMPLE
+     * Program type: \ref EBPF_ATTACH_TYPE_SAMPLE
      */
-    __declspec(selectany) ebpf_attach_type_t EBPF_ATTACH_TYPE_SAMPLE = {
-        0xf788ef4b, 0x207d, 0x4dc3, {0x85, 0xcf, 0x0f, 0x2e, 0xa1, 0x07, 0x21, 0x3c}};
+    __declspec(selectany) ebpf_attach_type_t EBPF_ATTACH_TYPE_SAMPLE = EBPF_ATTACH_TYPE_SAMPLE_GUID;
 
+#define EBPF_ATTACH_TYPE_XDP_TEST_GUID                                                 \
+    {                                                                                  \
+        0x0dccc15d, 0xa5f9, 0x4dc1, { 0xac, 0x79, 0xfa, 0x25, 0xee, 0xf2, 0x15, 0xc3 } \
+    }
     /** @brief Attach type for handling incoming packets as early as possible.
      *
      * Program type: \ref EBPF_PROGRAM_TYPE_XDP_TEST
      */
-    __declspec(selectany) ebpf_attach_type_t EBPF_ATTACH_TYPE_XDP_TEST = {
-        0x0dccc15d, 0xa5f9, 0x4dc1, {0xac, 0x79, 0xfa, 0x25, 0xee, 0xf2, 0x15, 0xc3}};
+    __declspec(selectany) ebpf_attach_type_t EBPF_ATTACH_TYPE_XDP_TEST = EBPF_ATTACH_TYPE_XDP_TEST_GUID;
 
     //
     // Program Types.