diff --git a/docs/DevelopmentGuide.md b/docs/DevelopmentGuide.md index 403aadfdfe..98d2eb4be8 100644 --- a/docs/DevelopmentGuide.md +++ b/docs/DevelopmentGuide.md @@ -91,7 +91,7 @@ If you see unexpected formatting changes in the code, verify that you are runnin The following license header **must** be included at the top of every code file: -``` +```c // Copyright (c) Microsoft Corporation // SPDX-License-Identifier: MIT ``` diff --git a/docs/InstallEbpf.md b/docs/InstallEbpf.md index 48c53dc770..56b3e78add 100644 --- a/docs/InstallEbpf.md +++ b/docs/InstallEbpf.md @@ -176,7 +176,7 @@ Start an admin Powershell on the Windows Host and run the following command and ```ps .\images\build-images.ps1 - ```` + ``` * To **build the image on a Linux machine** (e.g. Ubuntu), make sure docker is installed (see [install docker on Ubuntu](https://docs.docker.com/engine/install/ubuntu/)), and do the following: @@ -184,7 +184,7 @@ Start an admin Powershell on the Windows Host and run the following command and ```bash $HOME/ebpf-for-windows-image/build-images.sh - ```` + ``` 3. Push the `ebpf-for-windows` image to your repository. diff --git a/docs/NativeCodeGeneration.md b/docs/NativeCodeGeneration.md index 2d5945547c..4abd391073 100644 --- a/docs/NativeCodeGeneration.md +++ b/docs/NativeCodeGeneration.md @@ -94,7 +94,7 @@ required, and to import the helper functions. Every generated C file contains a single global entry point of type metadata_table_t: -``` +```c typedef struct _metadata_table { void (*programs)(program_entry_t** programs, size_t* count); @@ -111,7 +111,7 @@ is not valid in a C variable name. This variable is the only globally visible va ## Exported programs Each program in the generated C file is exported via a program_entry_t: -``` +```c typedef struct _program_entry { uint64_t (*function)(void*); @@ -138,7 +138,7 @@ The skeleton framework then uses NMR to publish this information to the eBPF exe The generated C code exposes a table containing the address of each helper function, name, ID, and additional meta-data of the helper function. The C code generator emits a table for the helper functions referenced by the program: -``` +```c typedef struct _helper_function_entry { uint64_t (*address)(uint64_t, uint64_t, uint64_t, uint64_t, uint64_t); @@ -161,7 +161,7 @@ in the generated code are called indirectly via the address field. Each map referenced by any of the eBPF programs is added as a map_entry_t: -``` +```c typedef struct _map_entry { void* address; diff --git a/docs/TroubleshootingGuide.md b/docs/TroubleshootingGuide.md index aaad56f740..ca12fd829a 100644 --- a/docs/TroubleshootingGuide.md +++ b/docs/TroubleshootingGuide.md @@ -95,7 +95,7 @@ invoked, see [troubleshooting eBPF program issues](#Troubleshooting-general-eBPF ### Expected WFP objects for the program type BPF_PROG_TYPE_CGROUP_SOCK_ADDR The following are the expected `sublayer` objects for this program type: -``` +```xml {7c7b3fb9-3331-436a-98e1-b901df457fff} @@ -141,7 +141,7 @@ In this scenario, the `FWPM_LAYER_ALE_CONNECT_REDIRECT_V6` layer objects are nec handles dual-stack sockets. This is the expected `callout` and `filter` at the `FWPM_LAYER_ALE_CONNECT_REDIRECT_V4` layer: -``` +```xml {98849e0f-b07d-11ec-9a30-18602489beee} @@ -186,7 +186,7 @@ This is the expected `callout` and `filter` at the `FWPM_LAYER_ALE_CONNECT_REDIR ``` This is the expected `callout` and `filter` at the `FWPM_LAYER_ALE_CONNECT_REDIRECT_V6` layer: -``` +```xml {98849e10-b07d-11ec-9a30-18602489beee} @@ -232,7 +232,7 @@ This is the expected `callout` and `filter` at the `FWPM_LAYER_ALE_CONNECT_REDIR ``` This is the expected `callout` and `filter` at the `FWPM_LAYER_ALE_AUTH_CONNECT_V4` layer: -``` +```xml {98849e0b-b07d-11ec-9a30-18602489beee} @@ -298,7 +298,7 @@ In this output, check that you see the expected eBPF program, looking at the `na and `map_ids` for the next set of checks. Example Output: -``` +```json [{ "id": 196867, "type": "sock_addr", @@ -319,8 +319,7 @@ In this output, check for an entry with the `prog_id` which matches the `id` fro the `attach_type` is as expected. Example output: -``` -bpftool.exe -p link +```json [{ "id": 262403, "type": 2, @@ -341,7 +340,7 @@ bpftool.exe -p map show id In this output, use the `map_ids` from the above output. Map usage is up to the eBPF program developer, so you should confirm that the `type` and `name` is as expected for the scenario. This example output is from invoking the bpftool for each map: -``` +```json { "id": 66054, "type": "hash", @@ -519,7 +518,7 @@ callout here. If you see more than 1, then another WFP callout driver may be att that your eBPF program is, which may affect the final connection. Sample output: -``` +```xml {98849e0f-b07d-11ec-9a30-18602489beee} @@ -557,4 +556,4 @@ Sample output: uninstall or disable the other WFP callouts. Note that the `name` field in the `wfpstate` output may differ from the actual driver or product name. --------------------- \ No newline at end of file +-------------------- diff --git a/docs/debugging.md b/docs/debugging.md index 6ab7377bf7..3557d7afd7 100644 --- a/docs/debugging.md +++ b/docs/debugging.md @@ -262,7 +262,7 @@ Disassembly of section .text: We see that the code the ntohs() function in [tests\sample\ebpf.h](../tests/sample/ebpf.h): -``` +```c uint16_t ntohs(uint16_t us) { diff --git a/docs/eBpfExtensions.md b/docs/eBpfExtensions.md index 567232c239..54d1b7d9bd 100644 --- a/docs/eBpfExtensions.md +++ b/docs/eBpfExtensions.md @@ -100,7 +100,7 @@ invoking an eBPF program. The various fields of this struct are as follows. * `meta`: Offset (in bytes) to the field in the context structure that is pointing to the beginning of context metadata. For example, for the XDP_TEST program types, the context data structure is as follows: -``` +```c // XDP_TEST hook. We use "struct xdp_md" for cross-platform compatibility. typedef struct xdp_md { @@ -113,7 +113,7 @@ typedef struct xdp_md } xdp_md_t; ``` The corresponding context descriptor looks like: -``` +```c const ebpf_context_descriptor_t g_xdp_context_descriptor = {sizeof(xdp_md_t), EBPF_OFFSET_OF(xdp_md_t, data), EBPF_OFFSET_OF(xdp_md_t, data_end), @@ -134,7 +134,7 @@ helper function. #### `ebpf_argument_type_t` Enum This enum describes the various argument types that can be passed to an eBPF helper function. This is defined in the [PREVAIL Verifier](https://github.com/vbpf/ebpf-verifier) project. -``` +```c typedef enum _ebpf_argument_type { EBPF_ARGUMENT_TYPE_DONTCARE = 0, EBPF_ARGUMENT_TYPE_ANYTHING, @@ -154,7 +154,7 @@ typedef enum _ebpf_argument_type { #### `ebpf_return_type` Enum This enum describes the various return types from an eBPF helper function. This is defined in the [PREVAIL Verifier](https://github.com/vbpf/ebpf-verifier) project. -``` +```c typedef enum _ebpf_return_type { EBPF_RETURN_TYPE_INTEGER = 0, EBPF_RETURN_TYPE_PTR_TO_MAP_VALUE_OR_NULL, @@ -235,7 +235,7 @@ specific data that may be used by an extension for attaching an eBPF program. Fo being attached to an XDP_TEST hook, the network interface index can be passed via this parameter. This tells the extension to invoke the eBPF program whenever there are any inbound packets on that network interface. The attach parameter can be obtained as follows: -``` +```c ebpf_extension_data_t* extension_data = (ebpf_extension_data_t*)ClientRegistrationInstance->NpiSpecificCharacteristics; attach_parameter = extension_data->data; ``` @@ -250,7 +250,7 @@ the provider must free the per-client context passed in via `ProviderBindingCont To invoke an eBPF program, the extension uses the dispatch table supplied by the Hook NPI client during attaching. The client dispatch table contains the functions, with the following type prototypes: -``` +```c /** * @brief Invoke the eBPF program. * @@ -309,7 +309,7 @@ typedef ebpf_result_t (*ebpf_program_batch_end_invoke_function_t)( ``` The function pointer can be obtained from the client dispatch table as follows: -``` +```c invoke_program = (ebpf_program_invoke_function_t)client_dispatch_table->function[0]; ``` When an extension invokes this function pointer, then the call flows through the eBPF Execution Context and eventually @@ -344,7 +344,7 @@ itself. However, if a program type so chooses, it may provide implementations fo the extension would have to provide another Program Information NPI provider, which *does not* provide any program context descriptor. Instead, it only supplies the prototypes and addresses of the general helper functions. The NPI ID of this module defined as: -``` +```c GUID ebpf_general_helper_function_module_id = {/* 8d2a1d3f-9ce6-473d-b48e-17aa5c5581fe */ 0x8d2a1d3f, 0x9ce6, diff --git a/docs/tutorial.md b/docs/tutorial.md index f228194436..ca6be90115 100644 --- a/docs/tutorial.md +++ b/docs/tutorial.md @@ -25,7 +25,7 @@ However, we'll do this walkthrough assuming one is only using Windows. **Step 1)** Author a new file by putting some content into a file, say `bpf.c`: -``` +```c int func() { return 0; @@ -166,7 +166,7 @@ reached. In this way, there can even be multiple sections per source file. Author a new file, say in `bpf2.c` this time, with another function and a pragma above each one: -``` +```c #pragma clang section text="myprog" int func() @@ -493,7 +493,7 @@ hook-specific context structure passed as one argument.) The "xdp_test" hook point has the following prototype in `ebpf_nethooks.h`: -``` +```c typedef struct xdp_md { void* data; // Pointer to start of packet data. @@ -514,7 +514,7 @@ typedef xdp_action_t xdp_hook_t(xdp_md_t* context); A sample eBPF program might look like this: -``` +```c #include "bpf_helpers.h" #include "ebpf_nethooks.h" @@ -596,7 +596,7 @@ What would have happened had the prototype not matched? Let's say the verifier is the same as above but XDP_TEST instead had a different struct definition: -``` +```c typedef struct _xdp_md_t { uint64_t more; @@ -641,7 +641,7 @@ can vary by platform. For comparison, helpers for Linux are documented in the Let's say the following helper function prototype is exposed by Windows: -``` +```c #define EBPF_HELPER(return_type, name, args) typedef return_type(*name##_t) args EBPF_HELPER(int64_t, bpf_map_update_elem, (struct bpf_map * map, void* key, void* value, uint64_t flags)); ``` @@ -649,7 +649,7 @@ EBPF_HELPER(int64_t, bpf_map_update_elem, (struct bpf_map * map, void* key, void We'll cover in section 6.3 what this function does, but for now we only care about the prototype. We can create a sample (but, as we will see, invalid) program like so: -``` +```c #include "bpf_helpers.h" int func() @@ -758,7 +758,7 @@ of eBPF programs, or to expose information (e.g., statistics) to applications. To see how maps are exposed to eBPF programs, let's first start from a plain eBPF program: -``` +```c SEC("myprog") int func() { @@ -773,7 +773,7 @@ if multiple instances of our program are simultaneously running on different CPUs. -``` +```c #include "bpf_helpers.h" struct { @@ -810,7 +810,7 @@ Contents of section maps: ``` Now to make use of the map, we have to use helper functions to access it: -``` +```c void *bpf_map_lookup_elem(struct bpf_map* map, const void* key); int bpf_map_update_elem(struct bpf_map* map, const void* key, const void* value, uint64_t flags); int bpf_map_delete_elem(struct bpf_map* map, const void* key); @@ -818,7 +818,7 @@ int bpf_map_delete_elem(struct bpf_map* map, const void* key); Let's update the program to write the value "42" to the map section for the current CPU, by changing the "myprog" section to the following: -``` +```c SEC("myprog") int func1() { @@ -882,7 +882,7 @@ Above shows "call 2", but `netsh` shows more details ; C:\your\path\here/map.c:13 ; return result; 12: exit -```` +``` Notice from instruction 11 that `netsh` understands that `bpf_map_update_elem()` expects a map file descriptor (FD) in R1, a map key in R2, and a map value in R3.