kfuncs: Removed kfunc ref generation from BPF-HID kfuncs

The BPF-HID kfuncs are present in two sets, with different flags in each set, and different allowed program types. Our current tooling is not smart enough to merge these when generating a single kfunc page. In addition, the set of allowed program types has changed over time for some of these, something our tool also currently cannot handle. So for now, switch these to manual management, so that doc generation produces stable results. Perhaps we can later improve the tooling to handle these cases. Signed-off-by: Dylan Reimerink <dylan.reimerink@isovalent.com>
isovalent · Dec 7, 2024 · 376fab8 · 376fab8
1 parent 783151e
commit 376fab8
Show file tree

Hide file tree

Showing 10 changed files with 74 additions and 70 deletions.
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/kfunc-gen/main.go b/tools/kfunc-gen/main.go
@@ -39,8 +39,10 @@ const (
 	progKfuncRefEnd   = `<!-- [/PROG_KFUNC_REF] -->`
 )
 
-// List of kfuncs which only exists for the selftests, and are not actually supposed to be used
-var testKfuncs = []string{
+// List of kfuncs which we purposefully ignore in the data file
+var ignoreKfuncs = []string{
+	// These are technically usable kfuncs, but they do not do anything useful.
+	// They are just here for testing purposes. So we will not document them.
 	"bpf_fentry_test1",
 	"bpf_modify_return_test",
 	"bpf_modify_return_test2",
@@ -87,8 +89,7 @@ func main() {
 		switch t := (iter.Type).(type) {
 		case *btf.Func:
 			if slices.Contains(t.Tags, "bpf_kfunc") {
-				// Ignore test functions
-				if slices.Contains(testKfuncs, t.Name) {
+				if slices.Contains(ignoreKfuncs, t.Name) {
 					continue
 				}
 
@@ -148,6 +149,10 @@ func main() {
 			startIdx := strings.Index(fileStr, kfuncDefStart)
 			endIdx := strings.Index(fileStr, kfuncDefEnd)
 
+			if startIdx == -1 || endIdx == -1 {
+				continue
+			}
+
 			var newFile strings.Builder
 			// Write everything before the marker
 			newFile.WriteString(fileStr[:startIdx])
@@ -212,17 +217,6 @@ func main() {
 				panic(err)
 			}
 
-			fileStr := string(fileContents)
-
-			startIdx := strings.Index(fileStr, kfuncProgRefStart)
-			endIdx := strings.Index(fileStr, kfuncProgRefEnd)
-
-			var newFile strings.Builder
-			// Write everything before the marker
-			newFile.WriteString(fileStr[:startIdx])
-			newFile.WriteString(kfuncProgRefStart)
-
-			newFile.WriteString("\n")
 			var progTypes []string
 			for _, progType := range set.ProgramTypes {
 				if progType == "BPF_PROG_TYPE_UNSPEC" {
@@ -239,6 +233,22 @@ func main() {
 				progToKfunc[progType] = append(progToKfunc[progType], kfunc.Name)
 			}
 
+			fileStr := string(fileContents)
+
+			startIdx := strings.Index(fileStr, kfuncProgRefStart)
+			endIdx := strings.Index(fileStr, kfuncProgRefEnd)
+
+			if startIdx == -1 || endIdx == -1 {
+				continue
+			}
+
+			var newFile strings.Builder
+			// Write everything before the marker
+			newFile.WriteString(fileStr[:startIdx])
+			newFile.WriteString(kfuncProgRefStart)
+
+			newFile.WriteString("\n")
+
 			for _, progType := range progTypes {
 				newFile.WriteString(fmt.Sprintf("- [`%s`](../program-type/%s.md)\n", progType, progType))
 			}