[doc] Custom maps proposal #4882

saxena-anurag · 2025-12-12T02:32:27Z

Description

This PR adds proposal for implementing custom maps (#4375).

Testing

NA

Documentation

This PR adds doc.

Installation

No

…saxena-anurag/ebpf-for-windows-1 into user/anusa/custom_maps_proposal

dthaler · 2025-12-12T02:57:01Z

docs/ExtensibleMaps.md

+This document contains proposal for adding support for extensible / custom maps. Custom maps are map types that are
+program type specific, and are implemented / coordinated by the extensions.
+
+Extensible / custom maps are program type specific map types that can be implemented / coordinated by eBPF extensions


Suggested change

Extensible / custom maps are program type specific map types that can be implemented / coordinated by eBPF extensions

Custom maps are program type specific map types that can be implemented / coordinated by eBPF extensions

Updated all instances to use "custom maps"

You missed one: the filename is still ExtensibleMaps.md. Please rename to CustomMaps.md for consistency.

docs/ExtensibleMaps.md

shankarseal · 2025-12-12T17:58:34Z

docs/ExtensibleMaps.md

+```c
+typedef struct _ebpf_map_provider_dispatch_table {
+    ebpf_extension_header_t header;
+    ebpf_map_create_notify_t create_map_notify;


Consider renaming to process_map_operation instead of operation_map_notify.

shankarseal · 2025-12-12T18:00:45Z

docs/ExtensibleMaps.md

+    ↓
+ebpfcore checks if map_type >= 4096
+    ↓
+ebpfcore creates extensible map with NMR client


editorial - rewrite to eBPF registers new map client for the map instance.

dthaler · 2025-12-23T16:59:52Z

docs/ExtensibleMaps.md

+This document contains proposal for adding support for extensible / custom maps. Custom maps are map types that are
+program type specific, and are implemented / coordinated by the extensions.
+
+Extensible / custom maps are program type specific map types that can be implemented / coordinated by eBPF extensions


You missed one: the filename is still ExtensibleMaps.md. Please rename to CustomMaps.md for consistency.

dthaler · 2025-12-23T17:02:21Z

docs/ExtensibleMaps.md

+Global maps will use IDs from 1 to 4095. Extensible maps will use IDs 4096 onwards.
+
+- **Global Maps (1-4095)**: Reserved for core eBPF runtime map types (hash, array, etc.)
+- **Extensible Maps (4096+)**: Available for extension-implemented custom map types


Once custom map types are registered, why have separate ranges in the first place?

dthaler · 2025-12-23T17:04:33Z

docs/ExtensibleMaps.md

+Note: Extensions **should** register the map types for the custom maps by creating a pull request to eBPF-for-Windows
+repository and updating `ebpf_map_type_t` enum in ebpf_structs.h. This helps in any map type collision with another
+extension.


Suggested change

Note: Extensions **should** register the map types for the custom maps by creating a pull request to eBPF-for-Windows

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

extension.

Note: Extensions **must** register the map types for the custom maps by creating a pull request to eBPF-for-Windows

repository and updating `ebpf_map_type_t` enum in ebpf_structs.h. This avoids any map type collision with another

extension or eBPF core.

(Requiring a PR also prevents extensions from colliding with core eBPF runtime map types.)

dthaler · 2025-12-23T17:05:01Z

docs/ExtensibleMaps.md

+
+**Dynamic Provider Discovery**: Uses NMR's built-in discovery mechanism
+- No central registry required - providers are discovered on-demand during map creation
+- When a map is created with a custom type (>= 4096), eBPF core:


Suggested change

- When a map is created with a custom type (>= 4096), eBPF core:

- When a custom map is created, eBPF core:

dthaler · 2025-12-23T17:05:50Z

docs/ExtensibleMaps.md

+    ↓
+ebpfapi validates parameters
+    ↓
+ebpfcore checks if map_type >= 4096


I think this line should be deleted since I'm not convinced it has any significant value.
I'm not opposed to it if you can articulate some value it provides though, but currently this document doesn't.

dthaler · 2025-12-23T17:06:23Z

docs/ExtensibleMaps.md

+
+### User-mode APIs
+All existing libbpf APIs work unchanged with custom maps
+- `bpf_create_map()` / `bpf_map_create()` - Creates custom maps when type >= 4096


Suggested change

- `bpf_create_map()` / `bpf_map_create()` - Creates custom maps when type >= 4096

- `bpf_create_map()` / `bpf_map_create()` - Creates custom maps when type is a custom map type

Copilot

Pull request overview

This PR proposes a design for implementing custom maps in eBPF-for-Windows, enabling extensions to register and manage their own map types (e.g., BPF_MAP_TYPE_XSKMAP) through a new NMR provider interface while leveraging the core runtime's existing map implementations.

Key changes:

Introduces a new NMR provider interface for custom maps with provider registration data and dispatch tables
Partitions the map type ID space: IDs 1-4095 for core maps, 4096+ for custom maps
Documents the map creation flow, lifecycle management, and how existing APIs remain unchanged

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-01-07T16:48:00Z

docs/ExtensibleMaps.md

+
+## Map Lifecycle
+**Provider Binding**: eBPF core maintains map lifecycle and coordinates with extensions for map creation, deletion,
+and othr map operations.


Corrected spelling of 'othr' to 'other'.

Copilot · 2026-01-07T16:48:00Z

docs/ExtensibleMaps.md

+### User-mode APIs
+All existing libbpf APIs work unchanged with custom maps
+- `bpf_create_map()` / `bpf_map_create()` - Creates custom maps when type >= 4096
+- Map operations - Operations are routed to custom maps, whicn in turn invokes provider callbacks.


Corrected spelling of 'whicn' to 'which'.

Suggested change

- Map operations - Operations are routed to custom maps, whicn in turn invokes provider callbacks.

- Map operations - Operations are routed to custom maps, which in turn invokes provider callbacks.

Copilot · 2026-01-07T16:48:01Z

docs/ExtensibleMaps.md

+## NMR Interface for Extensions
+To implement custom maps, a new NMR interface will be added and extensions will register as map info providers using
+NMR, similar to existing program and hook providers. An extension implementing more than one custom maps needs to
+register as a map provider once for each map type it supports.


The statement about registering 'once for each map type' conflicts with the structure definition at line 35 which shows 'uint32_t custom_map_type; // Single map type per provider.' Consider clarifying whether this means one registration per map type (requiring multiple registrations for extensions supporting multiple map types) or one registration total per extension.

Copilot · 2026-01-07T16:48:01Z

docs/ExtensibleMaps.md

+following scenarios:
+1. **Map Creation** -- eBPF runtime will invoke `process_map_create` to validate the key and value sizes, and optionally
+get actual value size.
+2. **Map Deletion** -- eBPF runtime will invoke process_map_delete to notify the extension that the map is being deleted.


Inconsistent naming: the dispatch table field is named 'process_map_delete' (line 46) but this sentence refers to it as 'process_map_delete'. However, reviewing the dispatch table structure shows the field is 'process_map_delete_t' as a type, not the function name. Consider using consistent terminology, such as 'the process_map_delete callback' to match the field name in the dispatch table.

Suggested change

2. **Map Deletion** -- eBPF runtime will invoke process_map_delete to notify the extension that the map is being deleted.

2. **Map Deletion** -- eBPF runtime will invoke the `process_map_delete` callback to notify the extension that the map is being deleted.

saxena-anurag and others added 10 commits August 12, 2025 11:29

add proposal doc

bd051c8

update doc

acdf04c

update doc

e38c4ee

Merge branch 'main' into user/anusa/custom_maps_proposal

79b91dd

cr comments

25e2774

Merge branch 'user/anusa/custom_maps_proposal' of https://github.com/…

e7680de

…saxena-anurag/ebpf-for-windows-1 into user/anusa/custom_maps_proposal

Merge branch 'microsoft:main' into user/anusa/custom_maps_proposal

936202e

Merge branch 'main' into user/anusa/custom_maps_proposal

4e677cf

update design doc

c953b19

proposal doc

8c4ab0a

dthaler reviewed Dec 12, 2025

View reviewed changes

shankarseal reviewed Dec 12, 2025

View reviewed changes

mtfriesen previously approved these changes Dec 12, 2025

View reviewed changes

CR comments

a0c7fd2

saxena-anurag dismissed mtfriesen’s stale review via a0c7fd2 December 12, 2025 20:46

saxena-anurag changed the title ~~custom maps proposal~~ [doc] Custom maps proposal Dec 12, 2025

CR comments

d5b4d20

saxena-anurag requested review from dthaler, mtfriesen and shankarseal December 12, 2025 20:50

saxena-anurag marked this pull request as ready for review December 12, 2025 20:50

saxena-anurag requested review from Alan-Jowett, LakshK98, matthewige, mikeagun and poornagmsft as code owners December 12, 2025 20:50

Merge branch 'main' into user/anusa/custom_maps_proposal_2

ce2ed60

saxena-anurag enabled auto-merge December 12, 2025 20:51

mtfriesen approved these changes Dec 12, 2025

View reviewed changes

dthaler reviewed Dec 23, 2025

View reviewed changes

dthaler mentioned this pull request Dec 24, 2025

Add support for extensible maps. #4869

Draft

Alan-Jowett requested a review from Copilot January 7, 2026 16:45

Copilot started reviewing on behalf of Alan-Jowett January 7, 2026 16:46 View session

Copilot AI reviewed Jan 7, 2026

View reviewed changes

	Extensible / custom maps are program type specific map types that can be implemented / coordinated by eBPF extensions
	Custom maps are program type specific map types that can be implemented / coordinated by eBPF extensions

	- When a map is created with a custom type (>= 4096), eBPF core:
	- When a custom map is created, eBPF core:

	- `bpf_create_map()` / `bpf_map_create()` - Creates custom maps when type >= 4096
	- `bpf_create_map()` / `bpf_map_create()` - Creates custom maps when type is a custom map type

	- Map operations - Operations are routed to custom maps, whicn in turn invokes provider callbacks.
	- Map operations - Operations are routed to custom maps, which in turn invokes provider callbacks.

	2. Map Deletion -- eBPF runtime will invoke process_map_delete to notify the extension that the map is being deleted.
	2. Map Deletion -- eBPF runtime will invoke the `process_map_delete` callback to notify the extension that the map is being deleted.

[doc] Custom maps proposal #4882

Are you sure you want to change the base?

[doc] Custom maps proposal #4882

Uh oh!

Conversation

saxena-anurag commented Dec 12, 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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

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!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Jan 7, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 7, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 7, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 7, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

saxena-anurag commented Dec 12, 2025 •

edited

Loading