isovalent · dylandreimerink · Dec 7, 2024 · Dec 7, 2024 · Dec 7, 2024 · Dec 7, 2024
diff --git a/.github/workflows/generate-docs.yaml b/.github/workflows/generate-docs.yaml
@@ -0,0 +1,22 @@
+name: Generate docs
+
+on:
+  pull_request: {}
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+env:
+  USER: root
+
+jobs:
+  generate-docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - name: Run generate-docs
+        run: |
+          make generate-docs
+      - name: Assert no changes
+        run: |
+          git diff --quiet || (echo "Please run 'make generate-docs' and commit the changes" && exit 1)
+
diff --git a/Makefile b/Makefile
@@ -66,17 +66,27 @@ build-gen-tools:
 	CGO_ENABLED=0 go build -buildvcs=false -o /docs/tools/bin/mtu-calc /docs/tools/mtu-calc/. && \
 	CGO_ENABLED=0 go build -buildvcs=false -o /docs/tools/bin/helper-def-scraper /docs/tools/helper-def-scraper/."
 
+LIBBPF_REF := $(shell cat ${REPODIR}/tools/libbpf-ref)
+
 .PHONY: generate-docs
 generate-docs: build-gen-tools
 	${CONTAINER_ENGINE} run --rm -v "${REPODIR}:/docs" \
 		-w /docs -e "AS_USER=$$(id -u $${USER})" -e "AS_GROUP=$$(id -g $${USER})" "${IMAGE}:${VERSION}" \
 		"/docs/tools/bin/helper-ref-gen --project-root /docs && \
-		/docs/tools/bin/libbpf-tag-gen --project-root /docs && \
+		/docs/tools/bin/libbpf-tag-gen --project-root /docs --libbpf-ref '${LIBBPF_REF}' && \
 		/docs/tools/bin/feature-gen --project-root /docs --tags && \
 		/docs/tools/bin/feature-gen --project-root /docs --timeline && \
 		/docs/tools/bin/kfunc-gen --project-root /docs && \
 		/docs/tools/bin/mtu-calc --project-root /docs && \
-		/docs/tools/bin/helper-def-scraper --helper-path /docs/docs/linux/helper-function"
+		/docs/tools/bin/helper-def-scraper --helper-path /docs/docs/linux/helper-function --libbpf-ref '${LIBBPF_REF}'"
+
+.PHONY: update-libbpf-ref
+update-libbpf-ref:
+	curl -L \
+		-H "Accept: application/vnd.github+json" \
+		-H "X-GitHub-Api-Version: 2022-11-28" \
+		https://api.github.com/repos/libbpf/libbpf/commits | \
+	jq -r '.[0].sha' > ${REPODIR}/tools/libbpf-ref
 
 .PHONY: spellcheck
 spellcheck: build-spellcheck html

diff --git a/data/kfuncs.yaml b/data/kfuncs.yaml
@@ -358,32 +358,30 @@ sets:
     program_types:
       - BPF_PROG_TYPE_XDP
 
-  hid_bpf_kfunc_ids:
+  # Excluding `hid_bpf_kfunc_ids` and `hid_bpf_syscall_kfunc_ids`, these have overlapping
+  # kfuncs, which makes it difficult to automatically generate correct pages.
+  # Pages for these kfuncs are manually managed.
+  #
+  # These pseudo sets is here so generation can still be used for the program type pages
+  hid_bpf_pseudo_kfunc_ids:
     funcs:
       - name: hid_bpf_get_data
-        flags: [KF_RET_NULL]
       - name: hid_bpf_allocate_context
-        flags: [KF_ACQUIRE, KF_RET_NULL, KF_SLEEPABLE]
       - name: hid_bpf_release_context
-        flags: [KF_RELEASE, KF_SLEEPABLE]
       - name: hid_bpf_hw_request
-        flags: [KF_SLEEPABLE]
       - name: hid_bpf_hw_output_report
-        flags: [KF_SLEEPABLE]
       - name: hid_bpf_input_report
-        flags: [KF_SLEEPABLE]
       - name: hid_bpf_try_input_report
     program_types:
-      - BPF_PROG_TYPE_TRACING
-      - BPF_PROG_TYPE_LSM
+      - BPF_PROG_TYPE_TRACING    # until v6.11 ebc0d8093e8c97de459615438edefad1a4ac352c
+      - BPF_PROG_TYPE_LSM        # until v6.11 ebc0d8093e8c97de459615438edefad1a4ac352c
+      - BPF_PROG_TYPE_STRUCT_OPS # since v6.11 ebc0d8093e8c97de459615438edefad1a4ac352c
 
-  hid_bpf_syscall_kfunc_ids:
+  hid_bpf_pseudo_syscall_kfunc_ids:
     funcs:
       - name: hid_bpf_attach_prog
       - name: hid_bpf_allocate_context
-        flags: [KF_ACQUIRE, KF_RET_NULL]
       - name: hid_bpf_release_context
-        flags: [KF_RELEASE]
       - name: hid_bpf_hw_request
       - name: hid_bpf_hw_output_report
       - name: hid_bpf_input_report

diff --git a/docs/linux/kfuncs/hid_bpf_allocate_context.md b/docs/linux/kfuncs/hid_bpf_allocate_context.md
@@ -20,7 +20,6 @@ Allocate a context to the given HID device
 
 A pointer to &struct hid_bpf_ctx on success, `NULL` on error.
 
-<!-- [KFUNC_DEF] -->
 `#!c struct hid_bpf_ctx *hid_bpf_allocate_context(unsigned int hid_id)`
 
 !!! note
@@ -35,7 +34,7 @@ A pointer to &struct hid_bpf_ctx on success, `NULL` on error.
 
 !!! note
     This function may sleep, and therefore can only be used from [sleepable programs](../syscall/BPF_PROG_LOAD.md/#bpf_f_sleepable).
-<!-- [/KFUNC_DEF] -->
+	This is only true when not used from [`BPF_PROG_SYSCALL`](../program-type/BPF_PROG_SYSCALL.md) programs.
 
 ## Usage
 
@@ -46,10 +45,10 @@ A pointer to &struct hid_bpf_ctx on success, `NULL` on error.
 
 The following program types can make use of this kfunc:
 
-<!-- [KFUNC_PROG_REF] -->
-- [`BPF_PROG_TYPE_LSM`](../program-type/BPF_PROG_TYPE_LSM.md)
-- [`BPF_PROG_TYPE_TRACING`](../program-type/BPF_PROG_TYPE_TRACING.md)
-<!-- [/KFUNC_PROG_REF] -->
+- [`BPF_PROG_TYPE_LSM`](../program-type/BPF_PROG_TYPE_LSM.md) Until [:octicons-tag-24: v6.11](https://github.com/torvalds/linux/commit/ebc0d8093e8c97de459615438edefad1a4ac352c)
+- [`BPF_PROG_TYPE_TRACING`](../program-type/BPF_PROG_TYPE_TRACING.md) Until [:octicons-tag-24: v6.11](https://github.com/torvalds/linux/commit/ebc0d8093e8c97de459615438edefad1a4ac352c)
+- [`BPF_PROG_TYPE_STRUCT_OPS`](../program-type/BPF_PROG_TYPE_STRUCT_OPS.md) Since [:octicons-tag-24: v6.11](https://github.com/torvalds/linux/commit/ebc0d8093e8c97de459615438edefad1a4ac352c)
+- [`BPF_PROG_TYPE_SYSCALL`](../program-type/BPF_PROG_TYPE_SYSCALL.md)
 
 ### Example
 

diff --git a/docs/linux/kfuncs/hid_bpf_get_data.md b/docs/linux/kfuncs/hid_bpf_get_data.md
@@ -24,13 +24,11 @@ Get the kernel memory pointer associated with the context @ctx
 
 `NULL` on error, an `__u8` memory pointer on success
 
-<!-- [KFUNC_DEF] -->
 `#!c __u8 *hid_bpf_get_data(struct hid_bpf_ctx *ctx, unsigned int offset, const size_t rdwr_buf_size)`
 
 !!! note
 	The pointer returned by the kfunc may be NULL. Hence, it forces the user to do a NULL check on the pointer returned 
 	from the kfunc before making use of it (dereferencing or passing to another helper).
-<!-- [/KFUNC_DEF] -->
 
 ## Usage
 
@@ -40,10 +38,9 @@ The goal of HID-BPF is to partially replace drivers, so this situation can be pr
 
 The following program types can make use of this kfunc:
 
-<!-- [KFUNC_PROG_REF] -->
-- [`BPF_PROG_TYPE_LSM`](../program-type/BPF_PROG_TYPE_LSM.md)
-- [`BPF_PROG_TYPE_TRACING`](../program-type/BPF_PROG_TYPE_TRACING.md)
-<!-- [/KFUNC_PROG_REF] -->
+- [`BPF_PROG_TYPE_LSM`](../program-type/BPF_PROG_TYPE_LSM.md) Until [:octicons-tag-24: v6.11](https://github.com/torvalds/linux/commit/ebc0d8093e8c97de459615438edefad1a4ac352c)
+- [`BPF_PROG_TYPE_TRACING`](../program-type/BPF_PROG_TYPE_TRACING.md) Until [:octicons-tag-24: v6.11](https://github.com/torvalds/linux/commit/ebc0d8093e8c97de459615438edefad1a4ac352c)
+- [`BPF_PROG_TYPE_STRUCT_OPS`](../program-type/BPF_PROG_TYPE_STRUCT_OPS.md) Since [:octicons-tag-24: v6.11](https://github.com/torvalds/linux/commit/ebc0d8093e8c97de459615438edefad1a4ac352c)
 
 ### Example
 

diff --git a/docs/linux/kfuncs/hid_bpf_hw_output_report.md b/docs/linux/kfuncs/hid_bpf_hw_output_report.md
@@ -24,12 +24,11 @@ Send an output report to a HID device
 
 Returns the number of bytes transferred on success, a negative error code otherwise.
 
-<!-- [KFUNC_DEF] -->
 `#!c int hid_bpf_hw_output_report(struct hid_bpf_ctx *ctx, __u8 *buf, size_t buf__sz)`
 
 !!! note
     This function may sleep, and therefore can only be used from [sleepable programs](../syscall/BPF_PROG_LOAD.md/#bpf_f_sleepable).
-<!-- [/KFUNC_DEF] -->
+    This is only true when not used from [`BPF_PROG_SYSCALL`](../program-type/BPF_PROG_SYSCALL.md) programs.
 
 ## Usage
 
@@ -40,10 +39,10 @@ Returns the number of bytes transferred on success, a negative error code otherw
 
 The following program types can make use of this kfunc:
 
-<!-- [KFUNC_PROG_REF] -->
-- [`BPF_PROG_TYPE_LSM`](../program-type/BPF_PROG_TYPE_LSM.md)
-- [`BPF_PROG_TYPE_TRACING`](../program-type/BPF_PROG_TYPE_TRACING.md)
-<!-- [/KFUNC_PROG_REF] -->
+- [`BPF_PROG_TYPE_LSM`](../program-type/BPF_PROG_TYPE_LSM.md) Until [:octicons-tag-24: v6.11](https://github.com/torvalds/linux/commit/ebc0d8093e8c97de459615438edefad1a4ac352c)
+- [`BPF_PROG_TYPE_TRACING`](../program-type/BPF_PROG_TYPE_TRACING.md) Until [:octicons-tag-24: v6.11](https://github.com/torvalds/linux/commit/ebc0d8093e8c97de459615438edefad1a4ac352c)
+- [`BPF_PROG_TYPE_STRUCT_OPS`](../program-type/BPF_PROG_TYPE_STRUCT_OPS.md) Since [:octicons-tag-24: v6.11](https://github.com/torvalds/linux/commit/ebc0d8093e8c97de459615438edefad1a4ac352c)
+- [`BPF_PROG_TYPE_SYSCALL`](../program-type/BPF_PROG_TYPE_SYSCALL.md)
 
 ### Example
 

diff --git a/docs/linux/kfuncs/hid_bpf_hw_request.md b/docs/linux/kfuncs/hid_bpf_hw_request.md
@@ -28,12 +28,11 @@ Communicate with a HID device
 
 `0` on success, a negative error code otherwise.
 
-<!-- [KFUNC_DEF] -->
 `#!c int hid_bpf_hw_request(struct hid_bpf_ctx *ctx, __u8 *buf, size_t buf__sz, hid_report_type rtype, hid_class_request reqtype)`
 
 !!! note
     This function may sleep, and therefore can only be used from [sleepable programs](../syscall/BPF_PROG_LOAD.md/#bpf_f_sleepable).
-<!-- [/KFUNC_DEF] -->
+    This is only true when not used from [`BPF_PROG_SYSCALL`](../program-type/BPF_PROG_SYSCALL.md) programs.
 
 ## Usage
 
@@ -44,10 +43,10 @@ Communicate with a HID device
 
 The following program types can make use of this kfunc:
 
-<!-- [KFUNC_PROG_REF] -->
-- [`BPF_PROG_TYPE_LSM`](../program-type/BPF_PROG_TYPE_LSM.md)
-- [`BPF_PROG_TYPE_TRACING`](../program-type/BPF_PROG_TYPE_TRACING.md)
-<!-- [/KFUNC_PROG_REF] -->
+- [`BPF_PROG_TYPE_LSM`](../program-type/BPF_PROG_TYPE_LSM.md) Until [:octicons-tag-24: v6.11](https://github.com/torvalds/linux/commit/ebc0d8093e8c97de459615438edefad1a4ac352c)
+- [`BPF_PROG_TYPE_TRACING`](../program-type/BPF_PROG_TYPE_TRACING.md) Until [:octicons-tag-24: v6.11](https://github.com/torvalds/linux/commit/ebc0d8093e8c97de459615438edefad1a4ac352c)
+- [`BPF_PROG_TYPE_STRUCT_OPS`](../program-type/BPF_PROG_TYPE_STRUCT_OPS.md) Since [:octicons-tag-24: v6.11](https://github.com/torvalds/linux/commit/ebc0d8093e8c97de459615438edefad1a4ac352c)
+- [`BPF_PROG_TYPE_SYSCALL`](../program-type/BPF_PROG_TYPE_SYSCALL.md)
 
 ### Example
 

diff --git a/docs/linux/kfuncs/hid_bpf_input_report.md b/docs/linux/kfuncs/hid_bpf_input_report.md
@@ -27,12 +27,11 @@ Inject a HID report in the kernel from a HID device
 
 Returns `0` on success, a negative error code otherwise. This function will wait for the device to be available before injecting the event, thus needs to be called in sleepable context.
 
-<!-- [KFUNC_DEF] -->
 `#!c int hid_bpf_input_report(struct hid_bpf_ctx *ctx, hid_report_type type, u8 *buf, const size_t buf__sz)`
 
 !!! note
     This function may sleep, and therefore can only be used from [sleepable programs](../syscall/BPF_PROG_LOAD.md/#bpf_f_sleepable).
-<!-- [/KFUNC_DEF] -->
+    This is only true when not used from [`BPF_PROG_SYSCALL`](../program-type/BPF_PROG_SYSCALL.md) programs.
 
 ## Usage
 
@@ -43,10 +42,10 @@ Returns `0` on success, a negative error code otherwise. This function will wait
 
 The following program types can make use of this kfunc:
 
-<!-- [KFUNC_PROG_REF] -->
-- [`BPF_PROG_TYPE_LSM`](../program-type/BPF_PROG_TYPE_LSM.md)
-- [`BPF_PROG_TYPE_TRACING`](../program-type/BPF_PROG_TYPE_TRACING.md)
-<!-- [/KFUNC_PROG_REF] -->
+- [`BPF_PROG_TYPE_LSM`](../program-type/BPF_PROG_TYPE_LSM.md) Until [:octicons-tag-24: v6.11](https://github.com/torvalds/linux/commit/ebc0d8093e8c97de459615438edefad1a4ac352c)
+- [`BPF_PROG_TYPE_TRACING`](../program-type/BPF_PROG_TYPE_TRACING.md) Until [:octicons-tag-24: v6.11](https://github.com/torvalds/linux/commit/ebc0d8093e8c97de459615438edefad1a4ac352c)
+- [`BPF_PROG_TYPE_STRUCT_OPS`](../program-type/BPF_PROG_TYPE_STRUCT_OPS.md) Since [:octicons-tag-24: v6.11](https://github.com/torvalds/linux/commit/ebc0d8093e8c97de459615438edefad1a4ac352c)
+- [`BPF_PROG_TYPE_SYSCALL`](../program-type/BPF_PROG_TYPE_SYSCALL.md)
 
 ### Example
 

diff --git a/docs/linux/kfuncs/hid_bpf_release_context.md b/docs/linux/kfuncs/hid_bpf_release_context.md
@@ -14,16 +14,15 @@ Release the previously allocated context @ctx
 
 `ctx`: the HID-BPF context to release
 
-<!-- [KFUNC_DEF] -->
 `#!c void hid_bpf_release_context(struct hid_bpf_ctx *ctx)`
 
 !!! note
 	This kfunc releases the pointer passed in to it. There can be only one referenced pointer that can be passed in. 
 	All copies of the pointer being released are invalidated as a result of invoking this kfunc.
 
 !!! note
-    This function may sleep, and therefore can only be used from [sleepable programs](../syscall/BPF_PROG_LOAD.md/#bpf_f_sleepable).
-<!-- [/KFUNC_DEF] -->
+	This function may sleep, and therefore can only be used from [sleepable programs](../syscall/BPF_PROG_LOAD.md/#bpf_f_sleepable).
+	This is only true when not used from [`BPF_PROG_SYSCALL`](../program-type/BPF_PROG_SYSCALL.md) programs.
 
 ## Usage
 
@@ -34,10 +33,10 @@ Release the previously allocated context @ctx
 
 The following program types can make use of this kfunc:
 
-<!-- [KFUNC_PROG_REF] -->
-- [`BPF_PROG_TYPE_LSM`](../program-type/BPF_PROG_TYPE_LSM.md)
-- [`BPF_PROG_TYPE_TRACING`](../program-type/BPF_PROG_TYPE_TRACING.md)
-<!-- [/KFUNC_PROG_REF] -->
+- [`BPF_PROG_TYPE_LSM`](../program-type/BPF_PROG_TYPE_LSM.md) Until [:octicons-tag-24: v6.11](https://github.com/torvalds/linux/commit/ebc0d8093e8c97de459615438edefad1a4ac352c)
+- [`BPF_PROG_TYPE_TRACING`](../program-type/BPF_PROG_TYPE_TRACING.md) Until [:octicons-tag-24: v6.11](https://github.com/torvalds/linux/commit/ebc0d8093e8c97de459615438edefad1a4ac352c)
+- [`BPF_PROG_TYPE_STRUCT_OPS`](../program-type/BPF_PROG_TYPE_STRUCT_OPS.md) Since [:octicons-tag-24: v6.11](https://github.com/torvalds/linux/commit/ebc0d8093e8c97de459615438edefad1a4ac352c)
+- [`BPF_PROG_TYPE_SYSCALL`](../program-type/BPF_PROG_TYPE_SYSCALL.md)
 
 ### Example
 

diff --git a/docs/linux/kfuncs/hid_bpf_try_input_report.md b/docs/linux/kfuncs/hid_bpf_try_input_report.md
@@ -26,9 +26,7 @@ Inject a HID report in the kernel from a HID device
 
 Returns `0` on success, a negative error code otherwise. This function will immediately fail if the device is not available, thus can be safely used in IRQ context.
 
-<!-- [KFUNC_DEF] -->
 `#!c int hid_bpf_try_input_report(struct hid_bpf_ctx *ctx, hid_report_type type, u8 *buf, const size_t buf__sz)`
-<!-- [/KFUNC_DEF] -->
 
 ## Usage
 
@@ -39,10 +37,9 @@ Returns `0` on success, a negative error code otherwise. This function will imme
 
 The following program types can make use of this kfunc:
 
-<!-- [KFUNC_PROG_REF] -->
-- [`BPF_PROG_TYPE_LSM`](../program-type/BPF_PROG_TYPE_LSM.md)
-- [`BPF_PROG_TYPE_TRACING`](../program-type/BPF_PROG_TYPE_TRACING.md)
-<!-- [/KFUNC_PROG_REF] -->
+- [`BPF_PROG_TYPE_LSM`](../program-type/BPF_PROG_TYPE_LSM.md) Until [:octicons-tag-24: v6.11](https://github.com/torvalds/linux/commit/ebc0d8093e8c97de459615438edefad1a4ac352c)
+- [`BPF_PROG_TYPE_TRACING`](../program-type/BPF_PROG_TYPE_TRACING.md) Until [:octicons-tag-24: v6.11](https://github.com/torvalds/linux/commit/ebc0d8093e8c97de459615438edefad1a4ac352c)
+- [`BPF_PROG_TYPE_STRUCT_OPS`](../program-type/BPF_PROG_TYPE_STRUCT_OPS.md) Since [:octicons-tag-24: v6.11](https://github.com/torvalds/linux/commit/ebc0d8093e8c97de459615438edefad1a4ac352c)
 
 ### Example
 

diff --git a/docs/linux/program-type/BPF_PROG_TYPE_STRUCT_OPS.md b/docs/linux/program-type/BPF_PROG_TYPE_STRUCT_OPS.md
@@ -454,6 +454,13 @@ Not all helper functions are available in all program types. These are the helpe
     - [`dctcp_ssthresh`](../kfuncs/dctcp_ssthresh.md)
     - [`dctcp_state`](../kfuncs/dctcp_state.md)
     - [`dctcp_update_alpha`](../kfuncs/dctcp_update_alpha.md)
+    - [`hid_bpf_allocate_context`](../kfuncs/hid_bpf_allocate_context.md)
+    - [`hid_bpf_get_data`](../kfuncs/hid_bpf_get_data.md)
+    - [`hid_bpf_hw_output_report`](../kfuncs/hid_bpf_hw_output_report.md)
+    - [`hid_bpf_hw_request`](../kfuncs/hid_bpf_hw_request.md)
+    - [`hid_bpf_input_report`](../kfuncs/hid_bpf_input_report.md)
+    - [`hid_bpf_release_context`](../kfuncs/hid_bpf_release_context.md)
+    - [`hid_bpf_try_input_report`](../kfuncs/hid_bpf_try_input_report.md)
     - [`tcp_cong_avoid_ai`](../kfuncs/tcp_cong_avoid_ai.md)
     - [`tcp_reno_cong_avoid`](../kfuncs/tcp_reno_cong_avoid.md)
     - [`tcp_reno_ssthresh`](../kfuncs/tcp_reno_ssthresh.md)

diff --git a/tools/helper-def-scraper/main.go b/tools/helper-def-scraper/main.go
@@ -14,9 +14,10 @@ import (
 	"strings"
 )
 
-const libBpfGhHelperDefsURL = "https://raw.githubusercontent.com/libbpf/libbpf/master/src/bpf_helper_defs.h"
+const libBpfGhHelperDefsURL = "https://raw.githubusercontent.com/libbpf/libbpf/{ref}/src/bpf_helper_defs.h"
 
 var (
+	libbpfRef      = flag.String("libbpf-ref", "master", "libbpf ref")
 	filePath       = flag.String("file-path", "", "If set, use a file path instead of fetching from the interwebs")
 	helperFuncPath = flag.String("helper-path", "", "The path the helper function pages")
 
@@ -47,7 +48,8 @@ func main() {
 
 		headerFileReader = file
 	} else {
-		resp, err := http.Get(libBpfGhHelperDefsURL)
+		url := strings.Replace(libBpfGhHelperDefsURL, "{ref}", *libbpfRef, 1)
+		resp, err := http.Get(url)
 		if err != nil {
 			fmt.Fprintln(os.Stderr, "Error: %w", err)
 			return