[doc] Custom maps design

[saxena-anurag]

Fixes #4375

Description

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

Testing

NA

Documentation

This PR adds doc.

Installation

No

[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.

[saxena-anurag]

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

@dthaler -- Even though it is recommended, extensions can choose to not register the new map type. Keeping a different range helps ebpfcore know if this is a native map type, or it needs to attach to an NMR provider for this map type.

[saxena-anurag]

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

@dthaler -- Even though it is recommended, extensions can choose to not register the new map type. Keeping a different range helps ebpfcore know if this is a native map type, or it needs to attach to an NMR provider for this map type.

How is that different from helper function IDs?

It is not. Helper function IDs are also partitioned today. Program type specific helper functions need to start from 0xFFFF

[saxena-anurag]

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

@dthaler -- Even though it is recommended, extensions can choose to not register the new map type. Keeping a different range helps ebpfcore know if this is a native map type, or it needs to attach to an NMR provider for this map type.

How is that different from helper function IDs?

It is not. Helper function IDs are also partitioned today. Program type specific helper functions need to start from 0xFFFF

Just to drill into the last part... two program type specific helper functions can have the same id because (I think) helper functions are always indexed by (program type, function id) not just by (function id), correct? Is the proposal that the separate range of map type ids must be specific to a single program type, and always indexed by (program type, map type), never just (map type)? Would such map types ever be accessible from user-mode? If so, using what API(s)?

No the map type ID would be globally unique across program types, hence the recommendation to register it in eBPF repo, to avoid a conflict.

[saxena-anurag]

Clarification needed on type ID collision behavior

The doc states that extensions "must" register map types via PR to avoid collisions, but doesn't explain what happens at runtime if:

 - A custom map type is used with no provider loaded
 - Two extensions register for the same type ID

Suggested clarification - Consider adding a note in the "Map Type Enum Partitioning" section (around line 135):

 **Runtime Behavior:**

 - If no provider is registered for a custom map type, NMR client registration will fail to find a
   provider and map creation will return an error.

 - If multiple extensions register as providers for the same custom map type ID, the behavior is
   undefined - NMR will offer all matching provider interfaces and eBPFCore will attach to the
   first one. This is why registering map types via PR is mandatory: it prevents collisions through
   code review rather than runtime enforcement.

This makes it clear that the PR-based registration process is the collision prevention mechanism, not runtime validation.

Updated text.

[github-actions]

This pull request isn't linked to any GitHub issue. Please reference an issue with a keyword such as Fixes #123, Closes #456, etc., so the work can be tracked.

[github-actions]

This pull request isn't linked to any GitHub issue. Please reference an issue with a keyword such as Fixes #123, Closes #456, etc., so the work can be tracked.

[github-actions]

This pull request isn't linked to any GitHub issue. Please reference an issue with a keyword such as Fixes #123, Closes #456, etc., so the work can be tracked.

[github-actions]

This pull request isn't linked to any GitHub issue. Please reference an issue with a keyword such as Fixes #123, Closes #456, etc., so the work can be tracked.

[saxena-anurag]

@dthaler I have updated this PR, and also created PR #5173 for the corresponding code changes.

[dthaler]

Looks ok modulo one wording nit.

[saxena-anurag]

@dthaler can you re-approve the PR. I had pushed another commit based on the review comments.