microsoft / microsoft/ebpf-for-windows
Getting Started and Debugging guides don't mention native mode
- Dominant language
- C
- Stars
- 3.6k
- Forks
- 311
- Avg merge
- 6d 10h
- Merged PRs (30d)
- 21
Description
## Summary
Native mode is the preferred deployment option for eBPF for Windows, but the entry-point docs currently lead with (or heavily use) the JIT + netsh flow. This issue tracks updating the documentation so the **native code flow is shown first**, while keeping the JIT flow as an explicitly labeled alternative for rapid iteration.
A concrete proposal/design doc exists in-repo:
- https://github.com/microsoft/ebpf-for-windows/blob/main/docs/NativeModeDocsUpdateProposal.md
(There was also a historical attempt to address this in PR #4595, which was closed unmerged; it can be used for wording/structure inspiration.)
## Goals
- Make the “happy path” in docs **native-first**.
- Keep JIT instructions as a supported, clearly labeled alternative (“dev convenience”).
- Ensure commands and filenames match existing repo tooling (no hypothetical steps).
## Scope (files to change)
- `docs/GettingStarted.md`
- `docs/debugging.md`
Related reference doc (already exists):
- `docs/NativeCodeGeneration.md`
## Required doc updates (implementation-ready)
### 1) `docs/GettingStarted.md`: introduce execution modes and make native the default path
Add a short section near the top of the “Using eBPF for Windows” content:
**Title:** “Execution modes: native (preferred) and JIT (alternative)”
Include:
- One-paragraph explanation of native vs JIT.
- Clear statement that native is preferred (especially for production/security-sensitive environments).
- Link to `docs/NativeCodeGeneration.md`.
### 2) `docs/GettingStarted.md`: add a copy/pasteable native workflow
Document the native workflow using existing tooling:
1. Compile eBPF C to ELF:
```cmd
clang -target bpf -O2 -g -Werror -c program.c -o program.o
```
2. Convert ELF to a native `.sys` using the repo script:
```powershell
powershell scripts\Convert-BpfToNative.ps1 -FileName program
```
3. Load/unload as a driver service:
```cmd
sc create program_service type= kernel binPath= C:\path\to\program.sys
sc start program_service
sc stop program_service
sc delete program_service
```
Notes to include:
- Where the `.sys` output lands (per `docs/NativeCodeGeneration.md`).
- Driver loading prerequisites (test signing / KD / production signing), leveraging existing “Installing eBPF for Windows” text.
### 3) `docs/GettingStarted.md`: update demos to show native-first where feasible
For the walkthrough demos (e.g., DNS flood):
- Show the native compile/convert/load path first.
- Keep the current netsh/JIT commands as an “Alternative: JIT mode” subsection.
If a demo remains JIT-oriented for practical reasons, explicitly call that out and link back to the native workflow section.
### 4) `docs/debugging.md`: add a native-mode debugging section at the top
Add a new section near the beginning:
**Title:** “Debugging native mode (preferred)”
Cover:
- How to take the sample program used in this tutorial, generate the `.sys` from its `.o`.
- High-level kernel debugging checklist (KD/test-signing prerequisites, verifying module load, symbols).
### 5) `docs/debugging.md`: keep existing verifier/JIT walkthrough as an alternative
Retain the current content, but add an upfront note:
- This walkthrough demonstrates verifier-centric debugging using ELF + netsh (JIT flow).
- Link to the new native section for users following the preferred deployment model.
## Acceptance criteria
- `docs/GettingStarted.md` explicitly states native mode is preferred and includes a native-first workflow.
- `docs/debugging.md` contains a native-mode debugging section before the JIT/netsh walkthrough.
- JIT instructions remain present but are clearly labeled as alternative/dev convenience.
- All referenced commands/files exist and match repo tooling.
## References
- Proposal doc: `docs/NativeModeDocsUpdateProposal.md`
- Native pipeline background: `docs/NativeCodeGeneration.md`
- Historical PR attempt: #4595
Contributor guide
Assessment
This issue has not been assessed yet.