Isolate eBPF store APIs into atomic km & um libraries. (microsoft#2690)

* draft * wip * wip * wip * wip * wip - km & um compile * fix * fix include order * wip * wip * wip * wip - api_common * wip - updated projects * wip * wip * fix merge issues * wip * fix C28196/C6387 * wip * wip * fix SAL * cleanup * fix SAL bugs * wip - cmake * add cmake files * wip * wip * update msi artifacts * wip * cleanup * collapse null-checks * clean-up headers * refactor return types to ebpf_result_t * replace ebpf_registry_result_t with ebpf_result_t * update header * remove cpp wrapper, misc cleanup. * rename um/km registry helpers * cleanup * cleanup * update * nit * fix * Added KERNEL_MODE var, so to default to USER_MODE. * fix cmake * align result var names with ebpf_result_t * pr feedback * add project refs * Add NativeOnly* cfgs to ebpf_store_helper_km * Update docs, API reordering in source. * pr feedback * Rename types to abstract use of registry * Normalize all registry API names. * rename * merge sln * fix var typo * refactor store root keys * feedback * doc/comments * remove KERNEL_MODE * Force ignore format on all preprocessor code paths.
WilliamTaack · Aug 7, 2023 · 4cb79e5 · 4cb79e5
1 parent ced7990
commit 4cb79e5
Show file tree

Hide file tree

Showing 52 changed files with 1,642 additions and 893 deletions.
diff --git a/docs/eBpfExtensions.md b/docs/eBpfExtensions.md
@@ -296,14 +296,48 @@ The helper function ID for a general helper function must be in the range 0 - 65
 The parameter and return types for these helper functions must adhere to the `ebpf_argument_type_t` and
 `ebpf_return_type_t` enums.
 
-### 2.7 Registering Program Types and Attach Types
+### 2.7 Registering Program Types and Attach Types - eBPF Store
 The eBPF Execution Context loads an eBPF program from an ELF file that has program section(s) with section names. The
 prefix to these names determines the program type. For example, the section name `"xdp"` implies that the corresponding
-program type is `EBPF_PROGRAM_TYPE_XDP`. The Execution Context discovers the program type associated with a section
-prefix by reading the data from Windows registry. When an eBPF extension is installed, it must update the registry with
-the program types it implements along with the associated section prefixes.
+program type is `EBPF_PROGRAM_TYPE_XDP`.
 
-_Note: The registry location and data format are TBD. This is currently tracked by issue #223._
+The *Execution Context* discovers the program type associated with a section prefix by reading the data from the ***"eBPF store"***, which is currently kept in the Windows registry.
+When an eBPF extension is installed, it must update the eBPF store with the program types it implements along with the associated section prefixes.
+
+To operate on the eBPF store, the extension must link the `\lib\ebpf_store_helper_km.lib` kernel-mode library and include the related `\include\ebpf_store_helper.h` header file, both distributed within the [eBPF for Windows NuGet package](https://www.nuget.org/packages/eBPF-for-Windows/). With these, the extension can use the following APIs to register program types, attach types and helper functions:
+
+- `ebpf_store_update_helper_prototype`: updates the program type specific helper information in the eBPF store, given a pointer to the store key to be initialized and a pointer to the helper function prototype (i.e., `_ebpf_helper_function_prototype`):
+
+    ```c
+    ebpf_result_t
+    ebpf_store_update_helper_prototype(
+        ebpf_store_key_t helper_info_key, _In_ const ebpf_helper_function_prototype_t* helper_info);
+    ```c
+    ```
+
+- `ebpf_store_update_global_helper_information`: updates the global helper information in the eBPF store, given a pointer to an array of helper function prototypes:
+
+    ```c
+    ebpf_result_t
+    ebpf_store_update_global_helper_information(
+        _In_reads_(helper_info_count) ebpf_helper_function_prototype_t* helper_info, uint32_t helper_info_count);
+    ```
+
+- `ebpf_store_update_section_information`: updates the section information in the eBPF store, given a pointer to an array of section information (i.e., `_ebpf_program_section_info`):
+
+    ```c
+    ebpf_result_t
+    ebpf_store_update_section_information(
+        _In_reads_(section_info_count) const ebpf_program_section_info_t* section_info, uint32_t section_info_count);
+    ```
+
+- `ebpf_store_update_program_information`: updates program information in the eBPF store, given a pointer to an array of program information (i.e., `_ebpf_program_info`):
+
+    ```c
+    ebpf_result_t
+    ebpf_store_update_program_information(
+        _In_reads_(program_info_count) const ebpf_program_info_t* program_info, uint32_t program_info_count);
+    ```
 
 ### 2.8 eBPF Sample Driver
 The eBPF for Windows project provides a

diff --git a/ebpf-for-windows.sln b/ebpf-for-windows.sln
diff --git a/ebpfapi/ebpfapi.vcxproj b/ebpfapi/ebpfapi.vcxproj
@@ -239,12 +239,12 @@
     <ProjectReference Include="..\external\ebpf-verifier\build\ebpfverifier.vcxproj">
       <Project>{7d5b4e68-c0fa-3f86-9405-f6400219b440}</Project>
     </ProjectReference>
+    <ProjectReference Include="..\external\ebpf-verifier\build\external\libbtf\libbtf\libbtf.vcxproj">
+      <Project>{bc45d39c-f956-3951-bd46-44eae20ec7c9}</Project>
+    </ProjectReference>
     <ProjectReference Include="..\external\usersim\src\usersim.vcxproj">
       <Project>{030a7ac6-14dc-45cf-af34-891057ab1402}</Project>
     </ProjectReference>
-    <ProjectReference Include="..\external\ebpf-verifier\external\libbtf\build\libbtf\libbtf.vcxproj">
-      <Project>{c034859f-e0d6-3ae6-b4fe-71b012fdc618}</Project>
-    </ProjectReference>
     <ProjectReference Include="..\libs\api\api.vcxproj">
       <Project>{c8bf60c3-40a9-43ad-891a-8aa34f1c3a68}</Project>
     </ProjectReference>
@@ -276,4 +276,4 @@
   <Import Project="$(VCTargetsPath)\Microsoft.Cpp.targets" />
   <ImportGroup Label="ExtensionTargets">
   </ImportGroup>
-</Project>
+</Project>
diff --git a/ebpfcore/CMakeLists.txt b/ebpfcore/CMakeLists.txt
@@ -15,9 +15,10 @@ wdk_add_driver("EbpfCore" WINVER "${EBPFFORWINDOWS_WDK_WINVER}" KMDF "${EBPFFORW
 
 target_include_directories("EbpfCore" PRIVATE
   "${CMAKE_SOURCE_DIR}/include"
+  "${CMAKE_SOURCE_DIR}/libs/execution_context"
   "${CMAKE_SOURCE_DIR}/libs/platform"
   "${CMAKE_SOURCE_DIR}/libs/platform/kernel"
-  "${CMAKE_SOURCE_DIR}/libs/execution_context"
+  "${CMAKE_SOURCE_DIR}/libs/store_helper/kernel"
   "${CMAKE_SOURCE_DIR}/resource"
   "${CMAKE_CURRENT_SOURCE_DIR}"
 )
@@ -28,6 +29,7 @@ target_link_directories("EbpfCore" PRIVATE
 
 target_link_libraries("EbpfCore"
   "ebpf_for_windows_common_settings"
+  "ebpf_store_helper_km"
   "execution_context_kernel"
   "platform_kernel"
   "external::ebpfverifier_headers"