From b6dcb86fce2e29754fde295b18aa50341c374720 Mon Sep 17 00:00:00 2001 From: Dylan Reimerink Date: Sat, 7 Dec 2024 17:57:29 +0100 Subject: [PATCH 1/3] tools: Make libbpf based tools use a stable reference We would like to be able to run assert in CI that running `make generate-docs` will not change the output of the documentation. This avoids issues where someone manually modifies bits of the docs that are supposed to be generated. However, we have a few tools that use files from libbpf as input, which so far we have been pulling from the `master` branch which is always in flux. This means that the output of the tools can change between runs. So, lets use a pinned commit hash for the libbpf reference. We will manually have to update it periodically to pull in changes from libbpf. Signed-off-by: Dylan Reimerink --- Makefile | 14 ++++++++++++-- tools/helper-def-scraper/main.go | 6 ++++-- tools/libbpf-ref | 1 + tools/libbpf-tag-gen/main.go | 10 +++++++--- 4 files changed, 24 insertions(+), 7 deletions(-) create mode 100644 tools/libbpf-ref diff --git a/Makefile b/Makefile index c9c63c03..315ef5ba 100644 --- 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/tools/helper-def-scraper/main.go b/tools/helper-def-scraper/main.go index 405287ed..e7bca33a 100644 --- 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 diff --git a/tools/libbpf-ref b/tools/libbpf-ref new file mode 100644 index 00000000..a497d5d5 --- /dev/null +++ b/tools/libbpf-ref @@ -0,0 +1 @@ +c5f22aca0f3aa855daa159b2777472b35e721804 diff --git a/tools/libbpf-tag-gen/main.go b/tools/libbpf-tag-gen/main.go index 7eb16837..e538efdf 100644 --- a/tools/libbpf-tag-gen/main.go +++ b/tools/libbpf-tag-gen/main.go @@ -11,9 +11,12 @@ import ( "strings" ) -var projectroot = flag.String("project-root", "", "Root of the project") +var ( + projectroot = flag.String("project-root", "", "Root of the project") + libbpfRef = flag.String("libbpf-ref", "master", "libbpf ref") +) -const libbpfMapURL = "https://raw.githubusercontent.com/libbpf/libbpf/refs/heads/master/src/libbpf.map" +const libbpfMapURL = "https://raw.githubusercontent.com/libbpf/libbpf/{ref}/src/libbpf.map" const ( LIBBPF_TAG_START = "" @@ -26,7 +29,8 @@ func main() { panic("project-root is required") } - resp, err := http.Get(libbpfMapURL) + url := strings.Replace(libbpfMapURL, "{ref}", *libbpfRef, 1) + resp, err := http.Get(url) if err != nil { fmt.Fprintf(os.Stderr, "Failed to download libbpf.map: %v\n", err) os.Exit(1) From d4d441d68040742c9e2d4f609d3dcb6a8fafcab7 Mon Sep 17 00:00:00 2001 From: Dylan Reimerink Date: Sat, 7 Dec 2024 18:24:15 +0100 Subject: [PATCH 2/3] 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 --- data/kfuncs.yaml | 22 +++++----- docs/linux/kfuncs/hid_bpf_allocate_context.md | 11 +++-- docs/linux/kfuncs/hid_bpf_get_data.md | 9 ++--- docs/linux/kfuncs/hid_bpf_hw_output_report.md | 11 +++-- docs/linux/kfuncs/hid_bpf_hw_request.md | 11 +++-- docs/linux/kfuncs/hid_bpf_input_report.md | 11 +++-- docs/linux/kfuncs/hid_bpf_release_context.md | 13 +++--- docs/linux/kfuncs/hid_bpf_try_input_report.md | 9 ++--- .../program-type/BPF_PROG_TYPE_STRUCT_OPS.md | 7 ++++ tools/kfunc-gen/main.go | 40 ++++++++++++------- 10 files changed, 74 insertions(+), 70 deletions(-) diff --git a/data/kfuncs.yaml b/data/kfuncs.yaml index 9bbf9eee..288add9b 100644 --- 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 index 8afba35b..c948e518 100644 --- 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. - `#!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). - + 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: - -- [`BPF_PROG_TYPE_LSM`](../program-type/BPF_PROG_TYPE_LSM.md) -- [`BPF_PROG_TYPE_TRACING`](../program-type/BPF_PROG_TYPE_TRACING.md) - +- [`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 index 786d6628..077cc0e1 100644 --- 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 - `#!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). - ## 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: - -- [`BPF_PROG_TYPE_LSM`](../program-type/BPF_PROG_TYPE_LSM.md) -- [`BPF_PROG_TYPE_TRACING`](../program-type/BPF_PROG_TYPE_TRACING.md) - +- [`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 index 4345dc89..7610375e 100644 --- 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. - `#!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). - + 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: - -- [`BPF_PROG_TYPE_LSM`](../program-type/BPF_PROG_TYPE_LSM.md) -- [`BPF_PROG_TYPE_TRACING`](../program-type/BPF_PROG_TYPE_TRACING.md) - +- [`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 index 0f8222c4..388881d0 100644 --- 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. - `#!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). - + 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: - -- [`BPF_PROG_TYPE_LSM`](../program-type/BPF_PROG_TYPE_LSM.md) -- [`BPF_PROG_TYPE_TRACING`](../program-type/BPF_PROG_TYPE_TRACING.md) - +- [`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 index c18f3449..e6df48ed 100644 --- 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. - `#!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). - + 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: - -- [`BPF_PROG_TYPE_LSM`](../program-type/BPF_PROG_TYPE_LSM.md) -- [`BPF_PROG_TYPE_TRACING`](../program-type/BPF_PROG_TYPE_TRACING.md) - +- [`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 index e10bba50..de1fe867 100644 --- a/docs/linux/kfuncs/hid_bpf_release_context.md +++ b/docs/linux/kfuncs/hid_bpf_release_context.md @@ -14,7 +14,6 @@ Release the previously allocated context @ctx `ctx`: the HID-BPF context to release - `#!c void hid_bpf_release_context(struct hid_bpf_ctx *ctx)` !!! note @@ -22,8 +21,8 @@ Release the previously allocated context @ctx 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). - + 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: - -- [`BPF_PROG_TYPE_LSM`](../program-type/BPF_PROG_TYPE_LSM.md) -- [`BPF_PROG_TYPE_TRACING`](../program-type/BPF_PROG_TYPE_TRACING.md) - +- [`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 index 78bd1828..a4841270 100644 --- 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. - `#!c int hid_bpf_try_input_report(struct hid_bpf_ctx *ctx, hid_report_type type, u8 *buf, const size_t buf__sz)` - ## 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: - -- [`BPF_PROG_TYPE_LSM`](../program-type/BPF_PROG_TYPE_LSM.md) -- [`BPF_PROG_TYPE_TRACING`](../program-type/BPF_PROG_TYPE_TRACING.md) - +- [`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 index 7696e55e..48ff8b62 100644 --- 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 index 48eba271..a84a9b5c 100644 --- a/tools/kfunc-gen/main.go +++ b/tools/kfunc-gen/main.go @@ -39,8 +39,10 @@ const ( progKfuncRefEnd = `` ) -// 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)) } From 814887ea1281979775eaeef6cc88606fdbad838a Mon Sep 17 00:00:00 2001 From: Dylan Reimerink Date: Sat, 7 Dec 2024 18:52:41 +0100 Subject: [PATCH 3/3] .github/workflows: Add generate-docs CI workflow This workflow will call the `make generate-docs` command and error if the command fails or if it causes any changes to the repository. Signed-off-by: Dylan Reimerink --- .github/workflows/generate-docs.yaml | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) create mode 100644 .github/workflows/generate-docs.yaml diff --git a/.github/workflows/generate-docs.yaml b/.github/workflows/generate-docs.yaml new file mode 100644 index 00000000..7a33f522 --- /dev/null +++ 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) +