Add support for extensible maps. by saxena-anurag · Pull Request #4869 · microsoft/ebpf-for-windows

saxena-anurag · 2025-12-03T00:07:17Z

Description

This pull request introduces support for extensible eBPF map types in the Windows eBPF extension framework. The changes add a new NPI provider for map information, define new structures and APIs for extensible map management, and update documentation to guide extension authors on implementing custom map types. These updates enable extensions to register and manage their own map types beyond those provided by the core eBPF runtime.

Extensible Map Support

Added a new NPI provider type, Map Information NPI, allowing extensions to register and implement custom map types via the EBPF_MAP_INFO_EXTENSION_IID GUID. [1] [2]
Defined new structures (ebpf_map_provider_data_t, ebpf_map_client_data_t, and dispatch tables) and APIs for creating, deleting, and operating on extensible maps, including memory management via epoch-based APIs.
Updated the map type enum (ebpf_map_type_t) to reserve IDs 1–4095 for global map types and allow extensions to use IDs above BPF_MAP_TYPE_MAX for their own map types. [1] [2]

Documentation Updates

Revised docs/eBpfExtensions.md to describe the new extensible map support, including how to implement and register map types, the new NPI provider, and sample usage. [1] [2] [3] [4] [5]
Added details and examples for the new structures and APIs, and clarified the process for avoiding map type collisions by updating the core enum via pull request.

Miscellaneous

Added new flag definitions for map operations (EBPF_MAP_FLAG_HELPER, EBPF_MAP_FIND_FLAG_DELETE).
Minor formatting and macro updates for consistency.

These changes collectively enable extension developers to create, register, and manage custom eBPF map types in Windows, expanding the flexibility and power of the eBPF extension ecosystem.

Testing

This PR adds new tests.

Documentation

Updated documentation.

Installation

No.

mtfriesen · 2025-12-05T19:40:20Z

+    uint8_t* key_value_data; // Key followed by value in contiguous memory
+} sample_hash_bucket_entry_t;
+
+typedef struct _sample_hash_bucket


I'm not sure we should delegate implementation of a map to each extension; it is known to be quite tricky to implement a reliable and high performance RCU hash table.

Hi, we had discussed this earlier, and the proposal was to let extensions implement the map, as these would typically be program type specific.

eBPF runtime will expose epoch based APIs for extension to utilize the RCU implementation in eBPFCore.

dthaler · 2025-12-09T16:21:24Z

 ## 1 Overview
-An "eBPF extension" is a Windows kernel driver or component that implements eBPF hooks or helper functions. The design
-of eBPF for Windows is such that an extension providing an implementation for hooks and helper functions can be
+An "eBPF extension" is a Windows kernel driver or component that implements eBPF hooks, helper functions and extensible maps. The design


To verify: So an extension can implement an extensible map but it cannot implement a non-extensible map? I'll observe that this document never defines the term "extensible map", so either define it or remove that term entirely. Line 30 says "program type specific map", should this line use that language?

dthaler · 2025-12-09T16:21:52Z

-providers.
+eBPF Extensions need to implement *provider modules* for three types of NPIs. They are the **Program Information NPI**
+provider, **Hook NPI** provider and **Map Information NPI**.
+**Map Information NPI** is optional and only needs to be implemented if an extension want to add support for a


Suggested change

**Map Information NPI** is optional and only needs to be implemented if an extension want to add support for a

**Map Information NPI** is optional and only needs to be implemented if an extension wants to add support for a

grammar

dthaler · 2025-12-09T16:23:09Z

+3. Author any extensible maps.
 3. Invoke eBPF programs from hook(s).
 4. Register program and attach types.
+5. Register extensible map types, if any.


As before, should this say "program type specific map types" rather than "extensible map types"?

dthaler · 2025-12-09T16:24:35Z

+The `dispatch_table` is a pointer to the provider dispatch table that the extension provides for operations on the supported maps.
+
+#### Map ID
+eBPF-for-Windows runtime supports some global map types. eBPF-for-Windows has reserved the map IDs 1 to 4095 (BPF_MAP_TYPE_MAX) for the global map types implemented in eBPF Core. Extensions need to use a map ID > BPF_MAP_TYPE_MAX for any extensible map they implement.


Suggested change

eBPF-for-Windows runtime supports some global map types. eBPF-for-Windows has reserved the map IDs 1 to 4095 (BPF_MAP_TYPE_MAX) for the global map types implemented in eBPF Core. Extensions need to use a map ID > BPF_MAP_TYPE_MAX for any extensible map they implement.

The eBPF-for-Windows runtime supports some global map types. eBPF-for-Windows has reserved the map IDs 1 to 4095 (BPF_MAP_TYPE_MAX) for the global map types implemented in eBPF Core. Extensions need to use a map ID > BPF_MAP_TYPE_MAX for any extensible map they implement.

Also I think "Map ID" is the wrong term, since that's the ID for a specific map instance. I think you mean Map Type ID.

dthaler · 2025-12-09T16:24:53Z

+eBPF-for-Windows runtime supports some global map types. eBPF-for-Windows has reserved the map IDs 1 to 4095 (BPF_MAP_TYPE_MAX) for the global map types implemented in eBPF Core. Extensions need to use a map ID > BPF_MAP_TYPE_MAX for any extensible map they implement.
+
+Note: Though this is not required, extensions *can* register their map types by creating a pull request to eBPF-for-Windows
+repo and updating `ebpf_map_type_t` enum in ebpf_structs.h. This helps in any map type collision with another extension.


Suggested change

repo and updating `ebpf_map_type_t` enum in ebpf_structs.h. This helps in any map type collision with another extension.

repo and updating the `ebpf_map_type_t` enum in ebpf_structs.h. This helps avoid any map type collision with another extension.

dthaler · 2025-12-09T16:25:58Z

 `ebpf_return_type_t` enums.

-### 2.8 Registering Program Types and Attach Types - eBPF Store
+### 2.9 Helper functions that use extensible maps.


Suggested change

### 2.9 Helper functions that use extensible maps.

### 2.9 Helper functions that use extensible maps

dthaler · 2025-12-09T16:29:45Z

+/**
+ * @brief eBPF map type.
+ * Global map types are defined in the range 1-4095.  The range 4096-65535 is reserved
+ * for extensible map types.


I don't understand how this prevents collisions, and don't understand what happens if a collision can happen. Can we require a mechanism that doesn't have collisions, either by requiring global registration or using BTF IDs or something?

dthaler · 2025-12-24T15:36:02Z

+typedef struct _ebpf_map_provider_data
+{
+    ebpf_extension_header_t header;
+    uint32_t map_type; // Extensible map type implemented by the provider.


Suggested change

uint32_t map_type; // Extensible map type implemented by the provider.

uint32_t map_type; // Custom map type implemented by the provider.

dthaler · 2025-12-24T15:36:27Z

+} ebpf_map_provider_data_t;
+
+/**
+ * @brief Extensible map client data.


Suggested change

* @brief Extensible map client data.

* @brief Custom map client data.

Update to match PR #4882

dthaler · 2025-12-24T15:37:09Z

@@ -0,0 +1,191 @@
+// Copyright (c) eBPF for Windows contributors


Rename filename to ebpf_custom_maps.h

saxena-anurag added 17 commits December 2, 2025 16:06

add proposal doc

3bfc155

update doc

912cc62

update doc

b26ae77

cr comments

9b408d1

implement extensible maps

a45ac14

patch

14bd9bb

changes

0cf4579

fix build breaks

8baea8c

add unit tests

3a76764

add program load tests

9211235

update tests, export epoch APIs

4a275a9

fix validation, add driver tests

9b92684

add epoch api usage in unit tests

91886cd

add array map

6924483

fix

3756d5b

add doc

5ac337a

update sample program, fix analysis failure

c0c7cf8

saxena-anurag self-assigned this Dec 3, 2025

saxena-anurag and others added 9 commits December 3, 2025 10:06

bugfix, add tests

ea1b288

add tests, fixes

8ac47a5

Merge branch 'main' into user/anusa/extensible_maps

ea3afd6

fix

248683e

fix build break

17fa874

fixes

98e8c73

Merge branch 'main' into user/anusa/extensible_maps

23786d2

cleanup

7a0caa1

cleanup

2b09b19

saxena-anurag changed the title ~~[DRAFT] DO NOT REVIEW~~ Add support for extensible maps. Dec 5, 2025

saxena-anurag marked this pull request as ready for review December 5, 2025 18:27

saxena-anurag requested a review from Alan-Jowett as a code owner December 5, 2025 18:27

saxena-anurag requested review from LakshK98, dthaler, matthewige, mikeagun, mtfriesen, poornagmsft and shankarseal as code owners December 5, 2025 18:27

mtfriesen reviewed Dec 5, 2025

View reviewed changes

saxena-anurag and others added 9 commits December 5, 2025 14:29

fix asan build

0c0273e

add hash map to unit tests

053dba6

add tests

5b97b69

fix tests

01b9fdc

test code refactor

2396181

add tests

5e26bdb

code cleanup

a66d544

cleanup

b5d316c

Merge branch 'main' into user/anusa/extensible_maps

834ab3d

dthaler reviewed Dec 9, 2025

View reviewed changes

saxena-anurag marked this pull request as draft December 12, 2025 20:53

dthaler reviewed Dec 24, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add support for extensible maps.#4869

Add support for extensible maps.#4869
saxena-anurag wants to merge 35 commits intomicrosoft:mainfrom
saxena-anurag:user/anusa/extensible_maps

saxena-anurag commented Dec 3, 2025 •

edited

Loading

Uh oh!

mtfriesen Dec 5, 2025

Uh oh!

saxena-anurag Dec 5, 2025 •

edited

Loading

Uh oh!

dthaler Dec 9, 2025

Uh oh!

dthaler Dec 9, 2025

Uh oh!

dthaler Dec 9, 2025

Uh oh!

dthaler Dec 9, 2025

Uh oh!

dthaler Dec 9, 2025

Uh oh!

dthaler Dec 9, 2025

Uh oh!

dthaler Dec 9, 2025

Uh oh!

dthaler Dec 24, 2025

Uh oh!

dthaler Dec 24, 2025

Uh oh!

dthaler Dec 24, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

	Map Information NPI is optional and only needs to be implemented if an extension want to add support for a
	Map Information NPI is optional and only needs to be implemented if an extension wants to add support for a

	eBPF-for-Windows runtime supports some global map types. eBPF-for-Windows has reserved the map IDs 1 to 4095 (BPF_MAP_TYPE_MAX) for the global map types implemented in eBPF Core. Extensions need to use a map ID > BPF_MAP_TYPE_MAX for any extensible map they implement.
	The eBPF-for-Windows runtime supports some global map types. eBPF-for-Windows has reserved the map IDs 1 to 4095 (BPF_MAP_TYPE_MAX) for the global map types implemented in eBPF Core. Extensions need to use a map ID > BPF_MAP_TYPE_MAX for any extensible map they implement.

	repo and updating `ebpf_map_type_t` enum in ebpf_structs.h. This helps in any map type collision with another extension.
	repo and updating the `ebpf_map_type_t` enum in ebpf_structs.h. This helps avoid any map type collision with another extension.

	### 2.9 Helper functions that use extensible maps.
	### 2.9 Helper functions that use extensible maps

	uint32_t map_type; // Extensible map type implemented by the provider.
	uint32_t map_type; // Custom map type implemented by the provider.

	* @brief Extensible map client data.
	* @brief Custom map client data.

		@@ -0,0 +1,191 @@
		// Copyright (c) eBPF for Windows contributors

Conversation

saxena-anurag commented Dec 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Testing

Documentation

Installation

Uh oh!

Choose a reason for hiding this comment

Uh oh!

saxena-anurag Dec 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

saxena-anurag commented Dec 3, 2025 •

edited

Loading

saxena-anurag Dec 5, 2025 •

edited

Loading