[doc] Proposal doc for extensible maps by saxena-anurag · Pull Request #4566 · microsoft/ebpf-for-windows

saxena-anurag · 2025-08-12T18:34:49Z

Description

This PR adds proposal for implementing extensible maps (#4375), and what areas will need to be touched to add this support.

Testing

NA

Documentation

This is doc only PR

Installation

No

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

dthaler · 2025-08-18T15:36:36Z

@@ -0,0 +1,79 @@
+# Introduction
+
+Extensible maps are program type specific maps that will be implemented by the extension that is implementing the program type (program info provider). This document contains the proposal for implementing support for extensible / program type specific maps in eBPF-for-Windows. The below sections describe all the scenarios / areas that will need to be updated or tested for this new map type.


Recommend splitting into shorter source lines.

dthaler · 2025-08-18T15:38:26Z

+Global maps get an ID for their map types from a global namespace. There are two possible options for how we can allocate IDs for map types for extensible maps.
+
+**Option 1: Global Map IDs**
+- The map type IDs are allocated from a global namespace. This will be disjoint from the namespace for global maps. Global maps will use IDs from 1 to 4095. Extensible maps will use IDs 4096 onwards.


Elaborate... I don't follow why you need a separate ID range instead of just using normal IDs.

Answer: this is about map type IDs (which makes sense) not map IDs per se. Please update all uses of the term :)

dthaler · 2025-08-18T15:39:43Z

+## Map lifecycle
+Even though the extensible map will be created by and reside in the extension, ebpfcore will also create a corresponding map entry, as it does for the global maps. The difference being, in case of extensible maps, the map CRUD APIs will be supplied by the extension, and map entry in ebpfcore will contain these function pointers provided by the extension.
+
+Map lifetime will also be maintained by eBPFcore, and it will invoke extension's map delete API when the map needs to be finally deleted.


Suggested change

Map lifetime will also be maintained by eBPFcore, and it will invoke extension's map delete API when the map needs to be finally deleted.

Map lifetime will also be maintained by eBPFcore, and it will invoke the extension's map delete API when the map needs to be finally deleted.

dthaler · 2025-08-18T15:40:44Z

+- Once it finds the program info provider, it makes a (new) ioctl call to create the extensible map, and also pass the program type.
+- eBPFcore will first attach (NMR) to this provider, and check if the actual provider supports this map type. If yes, proceed to create map in the extension.
+
+Implicit map creation flow will also be similar. ebpf runtime will have similar flow for map creation, automatic map pinning, and map reuse.


Suggested change

Implicit map creation flow will also be similar. ebpf runtime will have similar flow for map creation, automatic map pinning, and map reuse.

Implicit map creation flow will also be similar. The ebpf runtime will have a similar flow for map creation, automatic map pinning, and map reuse.

Also by "ebpf runtime" do you mean ebpfcore?

saxena-anurag · 2025-08-18T16:04:57Z

+
+Extensible maps are program type specific maps that will be implemented by the extension that is implementing the program type (program info provider). This document contains the proposal for implementing support for extensible / program type specific maps in eBPF-for-Windows. The below sections describe all the scenarios / areas that will need to be updated or tested for this new map type.
+
+## Map Id partitioning


Update text and replace "Map ID" by "map type enum"

saxena-anurag · 2025-08-18T16:13:59Z

+Map lifetime will also be maintained by eBPFcore, and it will invoke extension's map delete API when the map needs to be finally deleted.
+Similarly, map pinning will also be handled by eBPFcore as that impacts map lifetime.
+
+Another thing to note is that once an extensible map is created, the corresponding extension **cannot be allowed to unload / restart**, as that will delete the map and its entries. This will be a limitation / restriction for the extension that is implementing extensible maps, and may impact their servicing flow.


Explore if the map memory can come from ebpfcore so that it survives extension restart.

Setting aside the extension behavior, what happens on Linux if an XSK map contains an entry for an XSK and:

The XSK file handle is closed?

The process that created the XSK terminates? [Can an XSK map be pinned such that it persists across process lifetime?]

I vaguely recall reading somewhere that the XSK map may have entries automatically removed - let me try to find that old context.

I see this blurb on the man page, but it refers to user mode automatically cleaning up the XSK entry, and not a kernel implementation:

When libxdp deletes an XSK it also removes the associated socket entry from the XSKMAP.

As long as our observable behavior matches Linux (e.g., if adding an XSK to a map keeps the entry around indefinitely) then I agree the simplest extension model is best. If the Linux kernel does support implicit XSK entry deletion, then I'd lean towards having the map itself also be implicitly deleted by the extension if it initiates NMR teardown.

Copilot

Pull Request Overview

This PR introduces a proposal document for implementing extensible maps in eBPF-for-Windows, which would allow program type specific maps to be implemented by extensions rather than being limited to global maps. The proposal outlines the technical design considerations and implementation areas that need to be addressed.

Key changes:

Adds comprehensive proposal document covering map ID partitioning strategies
Defines NMR interface extensions and eBPF store modifications needed
Outlines map lifecycle management and API design considerations

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

Copilot · 2025-08-26T19:14:50Z

+
+**Option 1: Global Map IDs**
+- The map type IDs are allocated from a global namespace. This will be disjoint from the namespace for global maps. Global maps will use IDs from 1 to 4095. Extensible maps will use IDs 4096 onwards.
+- Each program info provider that implements a extensible map will need to register / reserve the MAP ID / enum in the eBPF repo by creating a PR.


There is a grammatical error: 'a extensible' should be 'an extensible'.

Suggested change

- Each program info provider that implements a extensible map will need to register / reserve the MAP ID / enum in the eBPF repo by creating a PR.

- Each program info provider that implements an extensible map will need to register / reserve the MAP ID / enum in the eBPF repo by creating a PR.

Copilot · 2025-08-26T19:14:51Z

+Use option 1 as it allows keeping the user mode API for map creation same as on Linux, only adding a one-time step for extension developers to reserve the map ID in the global namespace (by creating a PR in eBPF repo).
+
+## NMR interface for extensions
+The NMR interface for program info provider will extended (non-breaking) and extensions will provide below information:


There is a grammatical error: 'will extended' should be 'will be extended'.

Suggested change

The NMR interface for program info provider will extended (non-breaking) and extensions will provide below information:

The NMR interface for program info provider will be extended (non-breaking) and extensions will provide below information:

Copilot · 2025-08-26T19:14:51Z

+## Verfication
+- No impact on verfication (online or offline), as the verifier only cares about the actual map definitions.


There is a spelling error: 'Verfication' should be 'Verification'.

Suggested change

## Verfication

- No impact on verfication (online or offline), as the verifier only cares about the actual map definitions.

## Verification

- No impact on verification (online or offline), as the verifier only cares about the actual map definitions.

Copilot · 2025-08-26T19:14:51Z

+## Verfication
+- No impact on verfication (online or offline), as the verifier only cares about the actual map definitions.


There is a spelling error: 'verfication' should be 'verification'.

Suggested change

## Verfication

- No impact on verfication (online or offline), as the verifier only cares about the actual map definitions.

## Verification

- No impact on verification (online or offline), as the verifier only cares about the actual map definitions.

Copilot · 2025-08-26T19:14:52Z

+
+**Export RCU APIs via NMR interface**
+- Probably adds more complexity to ebpfcore.
+- Does not require new release from extensions wheenver there is a bugfix in RCU logic.


There is a spelling error: 'wheenver' should be 'whenever'.

Suggested change

- Does not require new release from extensions wheenver there is a bugfix in RCU logic.

- Does not require new release from extensions whenever there is a bugfix in RCU logic.

Copilot · 2025-08-26T19:14:52Z

+Proposal here is to export RCU as lib.
+
+## Perf Consideration
+Since map APIs for extensible maps will have logner path length, we should measure perf for extensible map operations.


There is a spelling error: 'logner' should be 'longer'.

Suggested change

Since map APIs for extensible maps will have logner path length, we should measure perf for extensible map operations.

Since map APIs for extensible maps will have longer path length, we should measure perf for extensible map operations.

dthaler · 2025-09-22T15:21:35Z

@@ -0,0 +1,79 @@
+# Introduction
+
+Extensible maps are program type specific maps that will be implemented by the extension that is implementing the program type (program info provider). This document contains the proposal for implementing support for extensible / program type specific maps in eBPF-for-Windows. The below sections describe all the scenarios / areas that will need to be updated or tested for this new map type.


Are all maps extensible maps? Or specific map types? If BPF_MAP_TYPE_XSKMAP is an example of one, say so and point to https://docs.kernel.org/bpf/map_xskmap.html

dthaler · 2025-12-10T15:41:31Z

@@ -0,0 +1,149 @@
+# Introduction
+
+Extensible maps are custom map types that can be implemented by eBPF extensions (e.g. BPF_MAP_TYPE_XSKMAP) through a new


Then the name is a misnomer. Something that is "extensible" is something that can itself be extended, not something that is an extension to something else. Either describe how an eBPF extension can extend a map type it didn't define, or else change the name. Examples: "extension-specific map type", "custom map type", "extension map type", "program type specific map type", etc. Or even "extension-implemented custom map types" as line 54 uses, but that's even longer. Any of those are more correct than "extensible map" if I understand this definition.

dthaler · 2025-12-10T15:43:16Z

+- **Global Maps (1-4095)**: Reserved for core eBPF runtime map types (hash, array, etc.)
+- **Extensible Maps (4096+)**: Available for extension-implemented custom map types
+
+Extensions *can* reserve unique map type IDs by submitting PRs to update the enum in the eBPF repository.


Why is "can"highlighted? Just say "must". But I don't understand any benefit to partitioning the space. Please elaborate on what the benefit is. (I don't think allowing collisions is a benefit or a good thing, and requiring a PR is the only way you've defined in this document to avoid it.)

dthaler · 2025-12-10T15:45:35Z

+- `delete_batch()` - Batch delete operations
+- `lookup_and_delete_batch()` - Atomic lookup and delete operations
+
+## Memory Management and RCU Semantics


RCU is an undefined acronym. Please define / expand on first use. For example, if it's Read/Create/Update then why is Delete not supported? (and CRUD would be the usual acronym for that)

dthaler · 2026-03-23T19:48:03Z

@saxena-anurag is this PR obsoleted by PR #4882?

saxena-anurag added 3 commits August 12, 2025 11:29

add proposal doc

bd051c8

update doc

acdf04c

update doc

e38c4ee

saxena-anurag changed the title ~~add proposal doc~~ [doc] Proposal doc for extensible maps Aug 12, 2025

saxena-anurag marked this pull request as ready for review August 12, 2025 18:52

saxena-anurag requested review from Alan-Jowett, LakshK98, dthaler, matthewige, mikeagun, mtfriesen, poornagmsft and shankarseal as code owners August 12, 2025 18:52

Alan-Jowett reviewed Aug 12, 2025

View reviewed changes

Comment thread docs/ExtensibleMaps.md Outdated

Alan-Jowett reviewed Aug 12, 2025

View reviewed changes

Comment thread docs/ExtensibleMaps.md Outdated

saxena-anurag and others added 3 commits August 13, 2025 19:13

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

dthaler reviewed Aug 18, 2025

View reviewed changes

saxena-anurag commented Aug 18, 2025

View reviewed changes

Alan-Jowett requested a review from Copilot August 26, 2025 19:13

Copilot AI reviewed Aug 26, 2025

View reviewed changes

dthaler added the documentation Improvements or additions to documentation label Sep 22, 2025

dthaler reviewed Sep 22, 2025

View reviewed changes

saxena-anurag marked this pull request as draft September 24, 2025 21:30

saxena-anurag and others added 3 commits November 13, 2025 17:09

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

dthaler reviewed Dec 10, 2025

View reviewed changes

		@@ -0,0 +1,79 @@
		# Introduction

		Extensible maps are program type specific maps that will be implemented by the extension that is implementing the program type (program info provider). This document contains the proposal for implementing support for extensible / program type specific maps in eBPF-for-Windows. The below sections describe all the scenarios / areas that will need to be updated or tested for this new map type.

	Map lifetime will also be maintained by eBPFcore, and it will invoke extension's map delete API when the map needs to be finally deleted.
	Map lifetime will also be maintained by eBPFcore, and it will invoke the extension's map delete API when the map needs to be finally deleted.

	Implicit map creation flow will also be similar. ebpf runtime will have similar flow for map creation, automatic map pinning, and map reuse.
	Implicit map creation flow will also be similar. The ebpf runtime will have a similar flow for map creation, automatic map pinning, and map reuse.


		Extensible maps are program type specific maps that will be implemented by the extension that is implementing the program type (program info provider). This document contains the proposal for implementing support for extensible / program type specific maps in eBPF-for-Windows. The below sections describe all the scenarios / areas that will need to be updated or tested for this new map type.

		## Map Id partitioning

	- Each program info provider that implements a extensible map will need to register / reserve the MAP ID / enum in the eBPF repo by creating a PR.
	- Each program info provider that implements an extensible map will need to register / reserve the MAP ID / enum in the eBPF repo by creating a PR.

	The NMR interface for program info provider will extended (non-breaking) and extensions will provide below information:
	The NMR interface for program info provider will be extended (non-breaking) and extensions will provide below information:

		## Verfication
		- No impact on verfication (online or offline), as the verifier only cares about the actual map definitions.

	- Does not require new release from extensions wheenver there is a bugfix in RCU logic.
	- Does not require new release from extensions whenever there is a bugfix in RCU logic.

	Since map APIs for extensible maps will have logner path length, we should measure perf for extensible map operations.
	Since map APIs for extensible maps will have longer path length, we should measure perf for extensible map operations.

		@@ -0,0 +1,149 @@
		# Introduction

		Extensible maps are custom map types that can be implemented by eBPF extensions (e.g. BPF_MAP_TYPE_XSKMAP) through a new

Conversation

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

Uh oh!

Description

Testing

Documentation

Installation

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!

mtfriesen Aug 18, 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!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Uh oh!

Copilot AI Aug 26, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Aug 26, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Aug 26, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Aug 26, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Aug 26, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Aug 26, 2025

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!

dthaler Dec 10, 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!

dthaler commented Mar 23, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

saxena-anurag commented Aug 12, 2025 •

edited

Loading

mtfriesen Aug 18, 2025 •

edited

Loading

dthaler Dec 10, 2025 •

edited

Loading