diff --git a/README.md b/README.md index 55e8253..7ea9629 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # eBPF Developer Tutorial: Learning eBPF Step by Step with Examples -[![Test run](https://github.com/eunomia-bpf/bpf-developer-tutorial/actions/workflows/main.yml/badge.svg)](https://github.com/eunomia-bpf/bpf-developer-tutorial/actions/workflows/test-libbpf.yml) +[![Test example CI](https://github.com/eunomia-bpf/bpf-developer-tutorial/actions/workflows/test-libbpf.yml/badge.svg)](https://github.com/eunomia-bpf/bpf-developer-tutorial/actions/workflows/test-libbpf.yml) [![Test and trigger downstream tutorial sync](https://github.com/eunomia-bpf/bpf-developer-tutorial/actions/workflows/trigger-sync.yml/badge.svg)](https://github.com/eunomia-bpf/bpf-developer-tutorial/actions/workflows/trigger-sync.yml) [GitHub](https://github.com/eunomia-bpf/bpf-developer-tutorial) diff --git a/README.zh.md b/README.zh.md index b9a634d..e0e8168 100644 --- a/README.zh.md +++ b/README.zh.md @@ -1,6 +1,6 @@ # eBPF 开发者教程与知识库:eBPF Tutorial by Example -[![Test run](https://github.com/eunomia-bpf/bpf-developer-tutorial/actions/workflows/main.yml/badge.svg)](https://github.com/eunomia-bpf/bpf-developer-tutorial/actions/workflows/test-libbpf.yml) +[![Test example CI](https://github.com/eunomia-bpf/bpf-developer-tutorial/actions/workflows/test-libbpf.yml/badge.svg)](https://github.com/eunomia-bpf/bpf-developer-tutorial/actions/workflows/test-libbpf.yml) [GitHub](https://github.com/eunomia-bpf/bpf-developer-tutorial) [Gitee 镜像](https://gitee.com/yunwei37/bpf-developer-tutorial) diff --git a/src/44-scx-simple/README.md b/src/44-scx-simple/README.md index 64624b3..2b6f2f0 100644 --- a/src/44-scx-simple/README.md +++ b/src/44-scx-simple/README.md @@ -1,6 +1,8 @@ # eBPF Tutorial: Introduction to the BPF Scheduler -Welcome to our deep dive into the world of eBPF with a focus on the BPF scheduler! If you're looking to extend your eBPF knowledge beyond the basics, you're in the right place. In this tutorial, we'll explore the **scx_simple scheduler**, a minimal example of the sched_ext scheduler class introduced in Linux kernel version `6.12`. We'll walk you through its architecture, how it leverages BPF programs to define scheduling behavior, and guide you through compiling and running the example. By the end, you'll have a solid understanding of how to create and manage advanced scheduling policies using eBPF. +Welcome to our deep dive into the world of eBPF with a focus on the BPF scheduler! If you're looking to extend your eBPF knowledge beyond the basics, you're in the right place. + +In this tutorial, we'll explore the **scx_simple scheduler**, a minimal example of the sched_ext scheduler class introduced in Linux kernel version `6.12`. We'll walk you through its architecture, how it leverages BPF programs to define scheduling behavior, and guide you through compiling and running the example. By the end, you'll have a solid understanding of how to create and manage advanced scheduling policies using eBPF. ## Understanding the Extensible BPF Scheduler @@ -8,20 +10,13 @@ At the heart of this tutorial is the **sched_ext** scheduler class. Unlike tradi ### Key Features of sched_ext -- **Flexible Scheduling Algorithms:** Implement any scheduling policy by writing BPF programs. -- **Dynamic CPU Grouping:** The BPF scheduler can group CPUs as needed, without tying tasks to specific CPUs upon wakeup. -- **Runtime Control:** Enable or disable the BPF scheduler on-the-fly without rebooting. -- **System Integrity:** Even if the BPF scheduler encounters errors, the system gracefully reverts to the default scheduling behavior. -- **Debugging Support:** Comprehensive debug information is available through the `sched_ext_dump` tracepoint and SysRq key sequences. +**sched_ext** offers flexible scheduling algorithms by allowing the implementation of any scheduling policy through BPF programs. It supports dynamic CPU grouping, enabling the BPF scheduler to group CPUs as needed without binding tasks to specific CPUs upon wakeup. The scheduler can be enabled or disabled at runtime without requiring a system reboot. In terms of system integrity, if the BPF scheduler encounters errors, the system gracefully reverts to the default scheduling behavior. Additionally, sched_ext provides comprehensive debugging support through the `sched_ext_dump` tracepoint and SysRq key sequences. With these features, sched_ext provides a robust foundation for experimenting with and deploying advanced scheduling strategies. ## Introducing scx_simple: A Minimal sched_ext Scheduler -The **scx_simple** scheduler is a straightforward example of a sched_ext scheduler in the linux tools. It's designed to be easy to understand and serves as a foundation for more complex scheduling policies. scx_simple can operate in two modes: - -1. **Global Weighted Virtual Time (vtime) Mode:** Prioritizes tasks based on their virtual time, allowing for fair scheduling across different workloads. -2. **FIFO (First-In-First-Out) Mode:** Simple queue-based scheduling where tasks are executed in the order they arrive. +The **scx_simple** scheduler is a straightforward example of a sched_ext scheduler in the Linux tools. It's designed to be easy to understand and serves as a foundation for more complex scheduling policies. scx_simple can operate in two modes: **Global Weighted Virtual Time (vtime) Mode**, which prioritizes tasks based on their virtual time, allowing for fair scheduling across different workloads, and **FIFO (First-In-First-Out) Mode**, a simple queue-based scheduling where tasks are executed in the order they arrive. scx_simple is particularly effective on single-socket CPUs with a uniform L3 cache topology. While the global FIFO mode can handle many workloads efficiently, it's essential to note that saturating threads might overshadow less active ones. Therefore, scx_simple is best suited for environments where a straightforward scheduling policy meets the performance and fairness requirements. @@ -174,30 +169,19 @@ SCX_OPS_DEFINE(simple_ops, The kernel-side implementation of scx_simple defines how tasks are selected, enqueued, dispatched, and managed. Here's a high-level overview: -1. **Initialization and Licensing:** - - The scheduler is licensed under GPL. - - A global variable `fifo_sched` determines the scheduling mode (FIFO or weighted vtime). +**Initialization and Licensing:** The scheduler is licensed under GPL. A global variable `fifo_sched` determines the scheduling mode (FIFO or weighted vtime). -2. **Dispatch Queue (DSQ) Management:** - - A shared DSQ (`SHARED_DSQ`) with ID 0 is created to handle task dispatching. - - A `stats` map tracks the number of tasks queued locally and globally. +**Dispatch Queue (DSQ) Management:** A shared DSQ (`SHARED_DSQ`) with ID 0 is created to handle task dispatching. A `stats` map tracks the number of tasks queued locally and globally. -3. **CPU Selection (`simple_select_cpu`):** - - Selects the CPU for a waking task. - - If the selected CPU is idle, the task is immediately dispatched to the local DSQ. +**CPU Selection (`simple_select_cpu`):** This function selects the CPU for a waking task. If the selected CPU is idle, the task is immediately dispatched to the local DSQ. -4. **Task Enqueueing (`simple_enqueue`):** - - Depending on the `fifo_sched` flag, tasks are either dispatched to the shared DSQ in FIFO mode or to a priority queue based on virtual time. - - Virtual time (`vtime`) ensures fair scheduling by accounting for task execution time and weight. +**Task Enqueueing (`simple_enqueue`):** Depending on the `fifo_sched` flag, tasks are either dispatched to the shared DSQ in FIFO mode or to a priority queue based on virtual time. Virtual time (`vtime`) ensures fair scheduling by accounting for task execution time and weight. -5. **Task Dispatching (`simple_dispatch`):** - - Consumes tasks from the shared DSQ and assigns them to CPUs. +**Task Dispatching (`simple_dispatch`):** This function consumes tasks from the shared DSQ and assigns them to CPUs. -6. **Running and Stopping Tasks (`simple_running` & `simple_stopping`):** - - Manages the progression of virtual time for tasks, ensuring that scheduling decisions remain fair and balanced. +**Running and Stopping Tasks (`simple_running` & `simple_stopping`):** These functions manage the progression of virtual time for tasks, ensuring that scheduling decisions remain fair and balanced. -7. **Enabling and Exiting:** - - Handles the enabling of the scheduler and records exit information for debugging. +**Enabling and Exiting:** Handles the enabling of the scheduler and records exit information for debugging. This modular structure allows scx_simple to be both simple and effective, providing a clear example of how to implement custom scheduling policies using eBPF. @@ -277,32 +261,23 @@ The complete code can be found in = 16.0.0** - - Required for compiling BPF programs. While GCC is working on BPF support, it lacks essential features like BTF type tags necessary for certain functionalities. - -2. **pahole >= 1.25** - - Used to generate BTF from DWARF, which is crucial for type information in BPF programs. - -3. **rust >= 1.70.0** - - If you're working with Rust-based schedulers, ensure you have the appropriate Rust toolchain version. - +- **clang >= 16.0.0:** Required for compiling BPF programs. GCC is working on BPF support but lacks essential features like BTF type tags necessary for certain functionalities. +- **pahole >= 1.25:** Used to generate BTF from DWARF, crucial for type information in BPF programs. +- **rust >= 1.70.0:** If you're working with Rust-based schedulers, ensure you have the appropriate Rust toolchain version. + Additionally, tools like `make` are required for building the examples. ### Kernel Configuration @@ -397,7 +341,7 @@ This command compiles the scx_simple scheduler along with its dependencies. ### Running scx_simple -Once compiled, you can execute the user-space program to load and monitor the scheduler: +Once compiled, execute the user-space program to load and monitor the scheduler: ```bash ./scx_simple -f @@ -415,12 +359,7 @@ local=124 global=457 ### Switching Between sched_ext and CFS -sched_ext operates alongside the default Completely Fair Scheduler (CFS). You can switch between sched_ext and CFS dynamically: - -- **Enable sched_ext:** Load the BPF scheduler using scx_simple. -- **Disable sched_ext:** Terminate the scx_simple program, reverting all tasks back to CFS. - -Additionally, using SysRq key sequences like `SysRq-S` can help manage the scheduler's state and trigger debug dumps with `SysRq-D`. +sched_ext operates alongside the default Completely Fair Scheduler (CFS). You can switch between sched_ext and CFS dynamically. To enable sched_ext, load the BPF scheduler using scx_simple. To disable sched_ext, terminate the scx_simple program, reverting all tasks back to CFS. Additionally, using SysRq key sequences like `SysRq-S` can help manage the scheduler's state and trigger debug dumps with `SysRq-D`. ## Summary and Next Steps @@ -428,7 +367,7 @@ In this tutorial, we've introduced the **sched_ext** scheduler class and walked By mastering scx_simple, you're well-equipped to design and implement more sophisticated scheduling policies tailored to your specific requirements. Whether you're optimizing for performance, fairness, or specific workload characteristics, sched_ext and eBPF offer the flexibility and power to achieve your goals. -> Ready to take your eBPF skills to the next level? Dive deeper into our tutorials and explore more examples by visiting our [tutorial repository https://github.com/eunomia-bpf/bpf-developer-tutorial](https://github.com/eunomia-bpf/bpf-developer-tutorial) or our [website https://eunomia.dev/tutorials/](https://eunomia.dev/tutorials/). +> Ready to take your eBPF skills to the next level? Dive deeper into our tutorials and explore more examples by visiting our [tutorial repository](https://github.com/eunomia-bpf/bpf-developer-tutorial) or our [website](https://eunomia.dev/tutorials/). ## References @@ -439,4 +378,3 @@ By mastering scx_simple, you're well-equipped to design and implement more sophi - **libbpf Documentation:** [https://github.com/libbpf/libbpf](https://github.com/libbpf/libbpf) Feel free to explore these resources to expand your understanding and continue your journey into advanced eBPF programming! -