update kfunc example

Author: yunwei37

src/43-kfuncs/README.md

@@ -2,7 +2,7 @@
 
 Have you ever felt constrained by eBPF's capabilities? Maybe you've run into situations where the existing eBPF features just aren't enough to accomplish your goals. Perhaps you need deeper interactions with the kernel, or you're facing performance issues that the standard eBPF runtime can't solve. If you've ever wished for more flexibility and power in your eBPF programs, this tutorial is for you.
 
-## Introduction: Breaking Free from eBPF Runtime Limitations with kfuncs
+## Introduction: Adding a `strstr` kfunc to Break Free from eBPF Runtime Limitations
 
 **eBPF (extended Berkeley Packet Filter)** has revolutionized Linux system programming by allowing developers to run sandboxed programs inside the kernel. It's a game-changer for networking, security, and observability, enabling powerful functionalities without the need to modify kernel source code or load traditional kernel modules.
 
@@ -20,11 +20,13 @@ Enter **kfuncs (BPF Kernel Functions)**. By defining your own kfuncs within kern
 - **Customize Behavior:** Tailor kernel interactions to fit your specific needs.
 - **Boost Performance:** Optimize critical paths by executing custom code directly in the kernel context.
 
+**In this tutorial, we'll specifically add a `strstr` kfunc.** While implementing a string search directly in eBPF is challenging due to verifier restrictions, defining it as a kfunc allows us to bypass these limitations and perform more complex operations safely and efficiently.
+
 Best of all, you achieve this without modifying the core kernel, keeping your system stable and your code safe.
 
 In this tutorial, we'll show you how to define custom kfuncs to fill any gaps in eBPF's capabilities. We'll walk through creating a kernel module that introduces new kfuncs and demonstrate how to use them in your eBPF programs. Whether you're looking to overcome performance bottlenecks or need features the eBPF runtime doesn't offer, custom kfuncs can unlock new possibilities for your projects.
 
-## Understanding kfuncs: Extending eBPF Beyond Helpers
+## Understanding kfunc: Extending eBPF Beyond Helpers
 
 ### What Are kfuncs?
 
@@ -40,7 +42,7 @@ In this tutorial, we'll show you how to define custom kfuncs to fill any gaps in
 
 kfuncs serve as bridges between eBPF programs and deeper kernel functionalities. They allow eBPF programs to perform more intricate operations by either exposing existing kernel functions or introducing new wrappers specifically designed for eBPF interactions. This integration facilitates deeper kernel interactions while ensuring that eBPF programs remain safe and maintainable.
 
-It's important to note that the Linux kernel already includes a plethora of kfuncs. These built-in kfuncs cover a wide range of functionalities, allowing most developers to accomplish their tasks without the need to define new ones. However, in cases where the existing kfuncs do not meet specific requirements, defining custom kfuncs becomes necessary. This tutorial demonstrates how to define new kfuncs to fill any gaps, ensuring that your eBPF programs can leverage the exact functionality you need. eBPF can also be extended to userspace. In the userspace eBPF runtime [bpftime](https://github.com/eunomia-bpf/bpftime), we are also implementing ufuncs, which are similar to kfuncs but extending userspace applications.
+It's important to note that the Linux kernel already includes a plethora of kfuncs. These built-in kfuncs cover a wide range of functionalities, allowing most developers to accomplish their tasks without the need to define new ones. However, in cases where the existing kfuncs do not meet specific requirements, defining custom kfuncs becomes necessary. This tutorial demonstrates how to define new kfuncs to fill any gaps, ensuring that your eBPF programs can leverage the exact functionality you need. eBPF can also be extended to userspace. In the userspace eBPF runtime [bpftime](https://github.com/eunomia-bpf/bpftime), we are also implementing ufuncs, which are similar to kfuncs but extend userspace applications.
 
 ## Overview of kfuncs and Their Evolution
 
@@ -62,83 +64,112 @@ To harness the power of kfuncs, you'll need to define them within a kernel modul
 
 ### Writing the Kernel Module
 
-Let's start by creating a simple kernel module that defines a kfunc. This kfunc will perform a basic arithmetic operation, serving as a foundation for understanding the mechanics.
+Let's start by creating a simple kernel module that defines a `strstr` kfunc. This kfunc will perform a substring search operation, serving as a foundation for understanding the mechanics.
 
 #### **File: `hello.c`**
 
 ```c
-#include <linux/init.h>    // Macros for module initialization
-#include <linux/module.h>  // Core header for loading modules
-#include <linux/kernel.h>  // Kernel logging macros
+#include <linux/init.h>       // Macros for module initialization
+#include <linux/module.h>     // Core header for loading modules
+#include <linux/kernel.h>     // Kernel logging macros
 #include <linux/bpf.h>
 #include <linux/btf.h>
 #include <linux/btf_ids.h>
 
-// Declare the kfunc
-__bpf_kfunc u64 bpf_kfunc_call_test(u32 a, u64 b, u32 c, u64 d);
+/* Declare the kfunc prototype */
+__bpf_kfunc int bpf_strstr(const char *str, u32 str__sz, const char *substr, u32 substr__sz);
 
-/* Define the kfunc functions */
+/* Begin kfunc definitions */
 __bpf_kfunc_start_defs();
 
-__bpf_kfunc u64 bpf_kfunc_call_test(u32 a, u64 b, u32 c, u64 d)
+/* Define the bpf_strstr kfunc */
+__bpf_kfunc int bpf_strstr(const char *str, u32 str__sz, const char *substr, u32 substr__sz)
 {
-    return a + b + c + d;
+    // Edge case: if substr is empty, return 0 (assuming empty string is found at the start)
+    if (substr__sz == 0)
+    {
+        return 0;
+    }
+    // Edge case: if the substring is longer than the main string, it's impossible to find
+    if (substr__sz > str__sz)
+    {
+        return -1; // Return -1 to indicate not found
+    }
+    // Iterate through the main string, considering the size limit
+    for (size_t i = 0; i <= str__sz - substr__sz; i++)
+    {
+        size_t j = 0;
+        // Compare the substring with the current position in the string
+        while (j < substr__sz && str[i + j] == substr[j])
+        {
+            j++;
+        }
+        // If the entire substring was found
+        if (j == substr__sz)
+        {
+            return i; // Return the index of the first match
+        }
+    }
+    // Return -1 if the substring is not found
+    return -1;
 }
 
+/* End kfunc definitions */
 __bpf_kfunc_end_defs();
 
-// Define the BTF kfunc ID set
+/* Define the BTF kfuncs ID set */
 BTF_KFUNCS_START(bpf_kfunc_example_ids_set)
-BTF_ID_FLAGS(func, bpf_kfunc_call_test)
+BTF_ID_FLAGS(func, bpf_strstr)
 BTF_KFUNCS_END(bpf_kfunc_example_ids_set)
 
-// Register the kfunc ID set
+/* Register the kfunc ID set */
 static const struct btf_kfunc_id_set bpf_kfunc_example_set = {
     .owner = THIS_MODULE,
     .set = &bpf_kfunc_example_ids_set,
 };
 
-// Module initialization
+/* Function executed when the module is loaded */
 static int __init hello_init(void)
 {
     int ret;
 
     printk(KERN_INFO "Hello, world!\n");
-    // Register the BTF kfunc ID set
+    /* Register the BTF kfunc ID set for BPF_PROG_TYPE_KPROBE */
     ret = register_btf_kfunc_id_set(BPF_PROG_TYPE_KPROBE, &bpf_kfunc_example_set);
-    if (ret) {
+    if (ret)
+    {
         pr_err("bpf_kfunc_example: Failed to register BTF kfunc ID set\n");
         return ret;
     }
     printk(KERN_INFO "bpf_kfunc_example: Module loaded successfully\n");
-    return 0;  // Success
+    return 0; // Return 0 if successful
 }
 
-// Module cleanup
+/* Function executed when the module is removed */
 static void __exit hello_exit(void)
 {
-    // Unregister the BTF kfunc ID set (optional based on kernel version)
-    // unregister_btf_kfunc_id_set(BPF_PROG_TYPE_KPROBE, &bpf_kfunc_example_set);
+    /* Unregister the BTF kfunc ID set */
+    unregister_btf_kfunc_id_set(BPF_PROG_TYPE_KPROBE, &bpf_kfunc_example_set);
     printk(KERN_INFO "Goodbye, world!\n");
 }
 
-// Define module entry and exit points
+/* Macros to define the module’s init and exit points */
 module_init(hello_init);
 module_exit(hello_exit);
 
-MODULE_LICENSE("GPL");                 // License type
+MODULE_LICENSE("GPL");                 // License type (GPL)
 MODULE_AUTHOR("Your Name");            // Module author
 MODULE_DESCRIPTION("A simple module"); // Module description
 MODULE_VERSION("1.0");                 // Module version
 ```
 
 **Explanation of the Code:**
 
-- **Declaring the kfunc:** The `__bpf_kfunc` macro declares a function that eBPF programs can invoke. Here, `bpf_kfunc_call_test` takes four parameters (`a`, `b`, `c`, `d`) and returns their sum.
+- **Declaring the kfunc:** The `__bpf_kfunc` macro declares a function that eBPF programs can invoke. Here, `bpf_strstr` performs a substring search within a given string.
   
 - **BTF Definitions:** The `__bpf_kfunc_start_defs` and `__bpf_kfunc_end_defs` macros demarcate the beginning and end of kfunc definitions. The `BTF_KFUNCS_START` and related macros assist in registering the kfuncs with the BPF Type Format (BTF).
   
-- **Module Initialization:** The `hello_init` function registers the kfunc ID set, making `bpf_kfunc_call_test` available to eBPF programs of type `BPF_PROG_TYPE_KPROBE`.
+- **Module Initialization:** The `hello_init` function registers the kfunc ID set, making `bpf_strstr` available to eBPF programs of type `BPF_PROG_TYPE_KPROBE`.
   
 - **Module Cleanup:** The `hello_exit` function ensures that the kfunc ID set is unregistered upon module removal, maintaining system cleanliness.
 
@@ -258,15 +289,15 @@ Skipping BTF generation for /root/bpf-developer-tutorial/src/43-kfuncs/module/he
 
    This command copies the `vmlinux` file to the appropriate build directory, enabling successful BTF generation.
 
-The complete code for this tutorial can be found in the link <https://github.com/eunomia-bpf/bpf-developer-tutorial/tree/main/src/43-kfuncs> on GitHub. This is tested on Linux kernel version 6.11, and some modifications may be required for lower versions, referring to `compact.h`.
+The complete code for this tutorial can be found in the [bpf-developer-tutorial repository](https://github.com/eunomia-bpf/bpf-developer-tutorial/tree/main/src/43-kfuncs) on GitHub. This is tested on Linux kernel version 6.11, and some modifications may be required for lower versions, referring to `compact.h`.
 
 ## Utilizing Your Custom kfunc in an eBPF Program
 
-With the kernel module defining your custom kfunc in place, the next step is to create an eBPF program that leverages this function. This interaction showcases the enhanced capabilities introduced by kfuncs.
+With the kernel module defining your custom `strstr` kfunc in place, the next step is to create an eBPF program that leverages this function. This interaction showcases the enhanced capabilities introduced by kfuncs.
 
 ### Writing the eBPF Program
 
-Create an eBPF program that attaches to the `do_unlinkat` kernel function and uses the custom `bpf_kfunc_call_test` kfunc.
+Create an eBPF program that attaches to the `do_unlinkat` kernel function and uses the custom `bpf_strstr` kfunc.
 
 #### **File: `kfunc.c`**
 
@@ -278,33 +309,44 @@ Create an eBPF program that attaches to the `do_unlinkat` kernel function and us
 #include <bpf/bpf_tracing.h>
 
 typedef unsigned int u32;
-typedef unsigned long long u64;
-typedef int pid_t;
+typedef long long s64;
 
-// Declare the external kfunc
-extern u64 bpf_kfunc_call_test(u32 a, u64 b, u32 c, u64 d) __ksym;
+/* Declare the external kfunc */
+extern int bpf_strstr(const char *str, u32 str__sz, const char *substr, u32 substr__sz) __ksym;
 
-// License information
 char LICENSE[] SEC("license") = "Dual BSD/GPL";
 
-// Attach to the do_unlinkat kernel function
 SEC("kprobe/do_unlinkat")
-int handle_kprobe(void *ctx)
+int handle_kprobe(struct pt_regs *ctx)
 {
     pid_t pid = bpf_get_current_pid_tgid() >> 32;
-    u64 result = bpf_kfunc_call_test(1, 2, 3, 4);
-    bpf_printk("BPF triggered do_unlinkat from PID %d. Result: %lld\n", pid, result);
+    char str[] = "Hello, world!";
+    char substr[] = "wor";
+    int result = bpf_strstr(str, sizeof(str) - 1, substr, sizeof(substr) - 1);
+    if (result != -1)
+    {
+        bpf_printk("'%s' found in '%s' at index %d\n", substr, str, result);
+    }
+    bpf_printk("Hello, world! (pid: %d) bpf_strstr %d\n", pid, result);
     return 0;
 }
 ```
 
 **Explanation of the eBPF Code:**
 
-- **External kfunc Declaration:** The `extern` keyword declares the `bpf_kfunc_call_test` function, making it accessible within the eBPF program.
-  
+- **External kfunc Declaration:** The `extern` keyword declares the `bpf_strstr` function, making it accessible within the eBPF program.
+
 - **Kprobe Attachment:** The `SEC("kprobe/do_unlinkat")` macro attaches the eBPF program to the `do_unlinkat` kernel function. Every time `do_unlinkat` is invoked, the `handle_kprobe` function executes.
-  
-- **Using the kfunc:** Within `handle_kprobe`, the eBPF program calls `bpf_kfunc_call_test` with four arguments (`1, 2, 3, 4`). The result, which should be the sum of these numbers, is then printed using `bpf_printk`, displaying both the PID and the result.
+
+- **Using the kfunc:** Within `handle_kprobe`, the eBPF program calls `bpf_strstr` with four arguments:
+  - `str`: The main string to search within.
+  - `str__sz`: The size of the main string.
+  - `substr`: The substring to search for.
+  - `substr__sz`: The size of the substring.
+
+  The result, which is the index of the first occurrence of `substr` in `str` or `-1` if not found, is then printed using `bpf_printk`, displaying both the PID and the result.
+
+**Important Note:** Implementing a `strstr`-like function directly in eBPF is challenging due to verifier restrictions that limit loops and complex memory accesses. By implementing `strstr` as a kfunc, we bypass these limitations, allowing for more complex and efficient string operations within eBPF programs.
 
 ### Compiling the eBPF Program
 
@@ -316,39 +358,68 @@ To compile the eBPF program, ensure you have the necessary tools installed, such
    cd /path/to/bpf-developer-tutorial/src/43-kfuncs/
    ```
 
-2. **Compile the eBPF Program:**
+2. **Create a `Makefile` for the eBPF Program:**
+
+   ```makefile
+   # File: Makefile
+
+   CLANG ?= clang
+   LLVM_STRIP ?= llvm-strip
+   BPF_TARGET := bpf
+
+   CFLAGS := -O2 -g -target $(BPF_TARGET) -Wall -Werror -I/usr/include
+
+   all: kfunc.o
+
+   kfunc.o: kfunc.c
+       $(CLANG) $(CFLAGS) -c $< -o $@
+
+   clean:
+       rm -f kfunc.o
+   ```
+
+3. **Compile the eBPF Program:**
 
    ```bash
    make
    ```
 
+   This command will generate a file named `kfunc.o`, which is the compiled eBPF object file.
+
 ### Running the eBPF Program
 
 Assuming you have a user-space application or a tool to load and attach the eBPF program, you can execute it to observe the interaction between the eBPF program and the custom kfunc.
 
 **Sample Output:**
 
 ```bash
-$ sudo ./kfunc
+# sudo ./load_kfunc
 BPF program loaded and attached successfully. Press Ctrl-C to exit.
-            node-9523    [004] ...21  7520.587718: bpf_trace_printk: BPF triggered do_unlinkat from PID 9523. Result: 10
+```
 
-        cpptools-11242   [003] ...21  7859.613060: bpf_trace_printk: BPF triggered do_unlinkat from PID 11235. Result: 10
+Then, when the `do_unlinkat` function is invoked (e.g., when a file is unlinked), you can check the kernel logs:
 
-^C
-cpptools-11242   [002] ...21  7865.831074: bpf_trace_printk: BPF triggered do_unlinkat from PID 11235. Result: 10
+```bash
+dmesg | tail
+```
+
+**Expected Output:**
+
+```txt
+[ 1234.5678] 'wor' found in 'Hello, world!' at index 7
+[ 1234.5679] Hello, world! (pid: 2075) bpf_strstr 7
 ```
 
 **Explanation of the Output:**
 
-Each time the `do_unlinkat` function is invoked in the kernel, the eBPF program prints a message indicating the PID of the process and the result of the kfunc call. In this example, the sum `1 + 2 + 3 + 4` results in `10`, which is reflected in the output.
+Each time the `do_unlinkat` function is invoked in the kernel, the eBPF program prints a message indicating the PID of the process and the result of the kfunc call. In this example, the substring `"wor"` is found at index `7` in the string `"Hello, world!"`.
 
 ## Summary and Conclusion
 
 In this tutorial, we've delved deep into extending eBPF's capabilities by defining and utilizing custom kernel functions (kfuncs). Here's a recap of what we've covered:
 
 - **Understanding kfuncs:** Grasped the concept of kfuncs and their role in enhancing eBPF beyond standard helper functions.
-- **Defining kfuncs:** Created a kernel module that defines a custom kfunc, ensuring it can be safely exposed to eBPF programs without altering the core kernel.
+- **Defining kfuncs:** Created a kernel module that defines a custom `strstr` kfunc, ensuring it can be safely exposed to eBPF programs without altering the core kernel.
 - **Writing eBPF Programs with kfuncs:** Developed an eBPF program that leverages the custom kfunc to perform specific operations, demonstrating the enhanced functionality.
 - **Compilation and Execution:** Provided a step-by-step guide to compile, load, and run both the kernel module and the eBPF program, ensuring you can replicate the setup on your own system.
 - **Error Handling:** Addressed potential compilation issues and offered solutions to ensure a smooth development experience.
@@ -371,8 +442,4 @@ Happy eBPF-ing!
 
 ## Additional Resources
 
-If you'd like to learn more about eBPF knowledge and practices, you can visit our open source tutorial code repository at <https://github.com/eunomia-bpf/bpf-developer-tutorial> or website <https://eunomia.dev/tutorials/> for more examples and complete code.
-
-## Conclusion
-
-By following this detailed tutorial, you've equipped yourself with the knowledge to extend eBPF's capabilities using custom kfuncs. Whether you're aiming to perform advanced kernel interactions, overcome helper limitations, or enhance your observability tools, kfuncs provide the flexibility and power you need. Continue experimenting, stay curious, and contribute to the ever-evolving landscape of eBPF!
+If you'd like to learn more about eBPF knowledge and practices, you can visit our open-source tutorial code repository at [bpf-developer-tutorial](https://github.com/eunomia-bpf/bpf-developer-tutorial) or our website [eunomia.dev/tutorials](https://eunomia.dev/tutorials/) for more examples and complete code.

src/43-kfuncs/README_en.md

@@ -8,15 +8,21 @@ typedef unsigned int u32;
 typedef unsigned long long u64;
 typedef int pid_t;
 
-extern u64 bpf_kfunc_call_test(u32 a, u64 b, u32 c, u64 d) __ksym;
+extern int bpf_strstr(const char *str, u32 str__sz, const char *substr, u32 substr__sz) __ksym;
 
 char LICENSE[] SEC("license") = "Dual BSD/GPL";
 
 SEC("kprobe/do_unlinkat")
 int handle_kprobe(void *ctx)
 {
 	pid_t pid = bpf_get_current_pid_tgid() >> 32;
-	u64 result = bpf_kfunc_call_test(1, 2, 3, 4);
-	bpf_printk("BPF triggered do_unlinkat from PID %d. Result: %lld\n", pid, result);
+	char str[] = "Hello, world!";
+	char substr[] = "wor";
+	u32 result = bpf_strstr(str, sizeof(str) - 1, substr, sizeof(substr) - 1);
+	if (result != -1)
+	{
+		bpf_printk("'%s' found in '%s' at index %d\n", substr, str, result);
+	}
+	bpf_printk("Hello, world! (pid: %d) bpf_strstr %d\n", pid, result);
 	return 0;
 }

src/43-kfuncs/kfunc.bpf.c

@@ -1,24 +1,51 @@
-#include <linux/init.h>    // Macros for module initialization
-#include <linux/module.h>  // Core header for loading modules
-#include <linux/kernel.h>  // Kernel logging macros
+#include <linux/init.h>   // Macros for module initialization
+#include <linux/module.h> // Core header for loading modules
+#include <linux/kernel.h> // Kernel logging macros
 #include <linux/bpf.h>
 #include <linux/btf.h>
 #include <linux/btf_ids.h>
 
-__bpf_kfunc u64 bpf_kfunc_call_test(u32 a, u64 b, u32 c, u64 d);
+__bpf_kfunc int bpf_strstr(const char *str, u32 str__sz, const char *substr, u32 substr__sz);
 
 /* Define a kfunc function */
 __bpf_kfunc_start_defs();
 
-__bpf_kfunc u64 bpf_kfunc_call_test(u32 a, u64 b, u32 c, u64 d)
+__bpf_kfunc int bpf_strstr(const char *str, u32 str__sz, const char *substr, u32 substr__sz)
 {
-	return a + b + c + d;
+    // Edge case: if substr is empty, return 0 (assuming empty string is found at the start)
+    if (substr__sz == 0)
+    {
+        return 0;
+    }
+    // Edge case: if the substring is longer than the main string, it's impossible to find
+    if (substr__sz > str__sz)
+    {
+        return -1; // Return -1 to indicate not found
+    }
+
+    // Iterate through the main string, considering the size limit
+    for (size_t i = 0; i <= str__sz - substr__sz; i++)
+    {
+        size_t j = 0;
+        // Compare the substring with the current position in the string
+        while (j < substr__sz && str[i + j] == substr[j])
+        {
+            j++;
+        }
+        // If the entire substring was found
+        if (j == substr__sz)
+        {
+            return i; // Return the index of the first match
+        }
+    }
+    // Return -1 if the substring is not found
+    return -1;
 }
 
 __bpf_kfunc_end_defs();
 
 BTF_KFUNCS_START(bpf_kfunc_example_ids_set)
-BTF_ID_FLAGS(func, bpf_kfunc_call_test)
+BTF_ID_FLAGS(func, bpf_strstr)
 BTF_KFUNCS_END(bpf_kfunc_example_ids_set)
 
 // Register the kfunc ID set
@@ -35,12 +62,13 @@ static int __init hello_init(void)
     printk(KERN_INFO "Hello, world!\n");
     // Register the BTF kfunc ID set
     ret = register_btf_kfunc_id_set(BPF_PROG_TYPE_KPROBE, &bpf_kfunc_example_set);
-    if (ret) {
+    if (ret)
+    {
         pr_err("bpf_kfunc_example: Failed to register BTF kfunc ID set\n");
         return ret;
     }
     printk(KERN_INFO "bpf_kfunc_example: Module loaded successfully\n");
-    return 0;  // Return 0 if successful
+    return 0; // Return 0 if successful
 }
 
 // Function executed when the module is removed
@@ -55,7 +83,7 @@ static void __exit hello_exit(void)
 module_init(hello_init);
 module_exit(hello_exit);
 
-MODULE_LICENSE("GPL");               // License type (GPL)
-MODULE_AUTHOR("Your Name");          // Module author
+MODULE_LICENSE("GPL");                 // License type (GPL)
+MODULE_AUTHOR("Your Name");            // Module author
 MODULE_DESCRIPTION("A simple module"); // Module description
-MODULE_VERSION("1.0");               // Module version
+MODULE_VERSION("1.0");                 // Module version