Custom maps implementation

[saxena-anurag]

Fixes #4375

This pull request introduces support for custom map types in eBPF extensions for Windows. It updates both the documentation and the extension API to describe and enable how extensions can implement and register new map types, alongside hooks and helper functions. The changes define new NPI contracts, data structures, and dispatch tables for map providers, and clarify how helper functions interact with custom maps.

Key changes:

Documentation updates for custom maps

• Expanded the definition of an "eBPF extension" to include the ability to implement custom maps, not just hooks and helper functions. The documentation now details the requirements and process for registering new map types, including the new "Map Information NPI" contract and the steps for authoring and registering custom maps. It also explains the required data structures and the importance of using reserved map IDs. [1] [2] [3] [4] [5] [6]

New API and data structures for custom map providers

• Added new constants, function pointer typedefs, and data structures in ebpf_extension.h to support custom map operations (create, delete, find, add, associate with program types, etc.) and epoch-based memory management. This includes the ebpf_map_provider_data_t, ebpf_base_map_provider_dispatch_table_t, and related client-side structures and macros. [1] [2]

NPI contract and GUID for map extensions

• Introduced a new GUID (EBPF_MAP_INFO_EXTENSION_IID) in ebpf_extension_uuids.h to uniquely identify the NPI contract for map information providers.

---

These changes collectively enable eBPF extensions to define and register new map types, provide the necessary interfaces for the eBPF core to interact with custom maps, and document the requirements and procedures for extension authors.##

Testing

This PR adds tests.

Documentation

PR updates documentation.

Installation

NA.

[Alan-Jowett]

Code Review - Custom Maps Implementation

I've reviewed the changes for PR #4895. Overall the implementation is solid with good separation of concerns and proper use of NMR for provider registration. Here are my findings:

Issues Found

1. Missing NULL check for provider_dispatch in cleanup functions (Low severity)

In _clean_up_custom_hash_map\ (line 4282), \map->provider_dispatch->process_map_delete_element\ is called without a NULL check. While I verified that the current code flow ensures \provider_dispatch\ is set before this function is reachable (via \�bpf_custom_map_delete\ which is only called after successful map creation), this creates a maintenance hazard.

If future code changes introduce paths where the hash table cleanup is called before provider attachment completes, this will crash. Consider adding a defensive check:

\\c
if (map->provider_dispatch != NULL) {
map->provider_dispatch->process_map_delete_element(...);
}
\\

2. Potential partial initialization from undersized provider dispatch table (Medium severity)

In _ebpf_custom_map_client_attach_provider\ (lines 4683-4686):

\\c
memcpy(
provider_dispatch_table,
provider_data->base_provider_table,
min(sizeof(ebpf_base_map_provider_dispatch_table_t), provider_data->base_provider_table->header.size));
\\

While _ebpf_validate_map_provider_dispatch_table\ checks that \header.size == EBPF_BASE_MAP_PROVIDER_DISPATCH_TABLE_CURRENT_VERSION_SIZE, if a future version allows different sizes for backwards compatibility, the \min()\ could copy less than expected, leaving function pointers uninitialized (they'd be zeroed from \�bpf_allocate_cache_aligned_with_tag, but not validated as non-NULL for optional functions like \process_map_find_element).

Currently safe due to strict validation, but worth noting for future versioning support.

Questions/Suggestions

1. Documentation: The documentation mentions \BPF_MAP_TYPE_XSKMAP\ as an example custom map type, but I don't see it added to \�bpf_map_type_t\ in this PR. Is that intentional (just an example) or should it be added?

2. Test coverage: The sample extension tests look comprehensive. Are there any fault injection tests for the custom map path to verify error handling?

Overall the implementation looks good to ship. The validation is thorough and the NMR integration follows established patterns in the codebase.

[matthewige]

nit: should this be hooks, helpers, OR custom maps?

[matthewige]

nit: This "is" the dispatch table

[mtfriesen]

Let's document the caller context is the same as the original user mode process if EBPF_MAP_OPERATION_HELPER is not set. This allows providers to implicitly use the handle table of the current process when resolving parameters like file descriptors.