microsoft / microsoft/ebpf-for-windows

Getting Started and Debugging guides don't mention native mode

Open
#4,146 0 comments 1 reaction 2 assignees Assigned to @Alan-Jowett View on GitHub
documentation P3 triaged
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.