Merge pull request #2608 from ArmDeveloperEcosystem/main

prod update

Author: pareenaverma

content/learning-paths/embedded-and-microcontrollers/streamline-kernel-module/1_overview.md

@@ -1,19 +1,24 @@
 ---
-title: Overview
+title: Profile Linux kernel modules with Arm Streamline
 weight: 2
 
 ### FIXED, DO NOT MODIFY
 layout: learningpathall
 ---
 
-## Linux kernel profiling with Arm Streamline
+## Overview
+Performance tuning is just as important for kernel modules as it is for user-space applications. Arm Streamline is a powerful profiling tool that helps you find performance bottlenecks, hotspots, and memory issues - even inside the Linux kernel. In this Learning Path, you'll learn how to use Arm Streamline to profile a simple kernel module on Arm-based systems. You'll see how profiling can reveal optimization opportunities and help you improve your module's efficiency.
+## Benefits of profiling Linux kernel modules with Arm Streamline
 
-Performance tuning is not limited to user-space applications—kernel modules can also benefit from careful analysis. [Arm Streamline](https://developer.arm.com/Tools%20and%20Software/Streamline%20Performance%20Analyzer) is a powerful software profiling tool that helps developers understand performance bottlenecks, hotspots, and memory usage, even inside the Linux kernel. This learning path explains how to use Arm Streamline to profile a simple kernel module.
+Kernel modules often operate in performance-critical paths, such as device drivers or networking subsystems. Even a small inefficiency in a module can affect the overall system performance.
 
-### Why profile a kernel module?
+Profiling enables you to do the following:
 
-Kernel modules often operate in performance-critical paths, such as device drivers or networking subsystems. Even a small inefficiency in a module can affect the overall system performance. Profiling enables you to:
+- Identify hotspots (functions consuming most CPU cycles)
+- Measure cache and memory behavior
+- Understand call stacks for debugging performance issues
+- Detect synchronization bottlenecks and race conditions
+- Quantify the impact of code changes on system latency and throughput
+- Validate that optimizations improve performance on Arm-based systems
 
-- Identify hotspots (functions consuming most CPU cycles)  
-- Measure cache and memory behavior  
-- Understand call stacks for debugging performance issues  
+By using Arm Streamline, you gain visibility into how your kernel module interacts with the rest of the system. This insight helps you make data-driven decisions to optimize code paths, reduce resource contention, and ensure your module performs efficiently on Arm platforms. Profiling is especially valuable when porting modules from x86 to Arm, as architectural differences can reveal new optimization opportunities or highlight previously hidden issues.

content/learning-paths/embedded-and-microcontrollers/streamline-kernel-module/2_build_kernel_image.md

@@ -1,45 +1,49 @@
 ---
-title: Build Linux image
+title: Set up your environment 
 weight: 3
 
 ### FIXED, DO NOT MODIFY
 layout: learningpathall
 ---
 
-## Install packages
+## Prepare to build a Linux image with Buildroot
 
-```
+Before you build a Linux image with [Buildroot](https://github.com/buildroot/buildroot), make sure your development environment includes all the required packages. These tools and libraries are essential for compiling, configuring, and assembling embedded Linux images on Arm platforms. Installing them now helps you avoid build errors and ensures a smooth workflow.
+
+## Install the required packages for Buildroot
+
+Run the following commands on your AArch64-based Linux system to update your package list and install the necessary dependencies:
+
+```bash
 sudo apt update
-sudo apt install -y which sed make binutils build-essential diffutils gcc g++ bash patch gzip \ 
+sudo apt install -y which sed make binutils build-essential diffutils gcc g++ bash patch gzip \
 bzip2 perl tar cpio unzip rsync file bc findutils gawk libncurses-dev python-is-python3 \
 gcc-arm-none-eabi
 ```
 
+These packages ensure that Buildroot can configure, compile, and assemble all the components needed for your custom Linux image. If you encounter missing package errors during the build process, check your distribution's documentation for any additional dependencies specific to your environment.
+
+
 ## Build a debuggable kernel image
 
-For this learning path you will be using [Buildroot](https://github.com/buildroot/buildroot) to build a Linux image for Raspberry Pi 3B+ with a debuggable Linux kernel. You will profile Linux kernel modules built out-of-tree and Linux device drivers built in the Linux source code tree.  
+For this Learning Path you'll build a Linux image for Raspberry Pi 3B+ with a debuggable Linux kernel. You'll profile Linux kernel modules built out-of-tree and Linux device drivers built in the Linux source code tree. 
+
+{{% notice Note on using a different board%}}
+If you're not using a Raspberry Pi 3B+ for this Learning Path, select the default configuration that matches your hardware. Replace `raspberrypi3_64_defconfig` with the appropriate file from the `$(BUILDROOT_HOME)/configs` directory. This ensures Buildroot generates an image compatible with your target board.{{% /notice %}}
 
-1. Clone the Buildroot Repository and initialize the build system with the default configurations.
+Start by cloning the Buildroot repository and initialize the build system with the default configurations:
 
 ```bash
 git clone https://github.com/buildroot/buildroot.git
 cd buildroot
 export BUILDROOT_HOME=$(pwd)
 make raspberrypi3_64_defconfig
-```
-{{% notice Using a different board %}}
-If you're not using a Raspberry Pi 3 for this Learning Path, change the `raspberrypi3_64_defconfig` to the option that matches your hardware in `$(BUILDROOT_HOME)/configs`
-{{% /notice %}}
-
-2.  You will use `menuconfig` to configure the setup. Invoke it with the following command:
-
-```
 make menuconfig
 ```
 
-![Menuconfig UI for Buildroot configuration](./images/menuconfig.png)
+![Buildroot menuconfig interface showing configuration options. The screen displays a blue dialog box with white text and a highlighted menu. The main menu lists Build options, System configuration, Kernel, and Target packages. The Build options section is selected, and sub-options include build packages with debugging symbols, gcc debug level set to debug level 3, and build packages with runtime debugging info. The environment is a text-based terminal interface, typical for embedded Linux development. The tone is technical and instructional, guiding users through enabling debugging features in Buildroot. alt-text#center](./images/menuconfig.png "Buildroot menuconfig interface showing configuration options")
 
-Change Buildroot configurations to enable debugging symbols and SSH access. 
+Now change the Buildroot configuration to enable debugging symbols and SSH access:
 
 ```plaintext
 Build options  --->
@@ -61,38 +65,51 @@ Target packages  --->
         [*] openssh
             [*]   server
             [*]   key utilities
-```
-
-You might also need to change your default `sshd_config` file according to your network settings. To do that, you need to modify System configuration→ Root filesystem overlay directories to add a directory that contains your modified `sshd_config` file.
+You might need to update your default `sshd_config` file to match your network requirements. To do this, set the **Root filesystem overlay directories** option in the **System configuration** menu. Add a directory containing your customized `sshd_config` file. This ensures your SSH server uses the correct settings when the image boots.
 
-3. By default the Linux kernel images are stripped. You will need to make the image debuggable as you'll be using it later.
+By default, Linux kernel images are stripped of debugging information. To make the image debuggable for profiling, you need to adjust the kernel build settings.
 
-Invoke `linux-menuconfig` and uncheck the option as shown.
+Open the kernel configuration menu using the following:
 
 ```bash
 make linux-menuconfig
 ```
 
+In the menu, navigate to **Kernel hacking** and ensure that debugging options are enabled. Uncheck any option that reduces debugging information. This step preserves the symbols needed for effective kernel debugging and profiling:
+
 ```plaintext
 Kernel hacking  --->
     -*- Kernel debugging
     Compile-time checks and compiler options  --->
         Debug information (Rely on the toolchain's implicit default DWARF version)
     [ ] Reduce debugging information # un-check
 ```
+Now you're ready to build the Linux image and flash it to your SD card for use with the Raspberry Pi.
 
-4. Now you can build the Linux image and flash it to the the SD card to run it on the Raspberry Pi.
+Run the following command to start the build process:
 
 ```bash
 make -j$(nproc)
 ```
 
-It will take some time to build the Linux image. When it completes, the output will be in `$BUILDROOT_HOME/output/images/sdcard.img`:
+This step can take a while, depending on your system's performance. When the build finishes, you'll find the generated image at `$BUILDROOT_HOME/output/images/sdcard.img`.
+
+To confirm that Buildroot created the SD card image, list the contents of the output directory:
 
 ```bash
 ls $BUILDROOT_HOME/output/images/ | grep sdcard.img
 ```
 
-For details on flashing the SD card image, see [this helpful article](https://www.ev3dev.org/docs/tutorials/writing-sd-card-image-ubuntu-disk-image-writer/).
+The expected output is:
+
+```output
+sdcard.img
+```
+
+If you see `sdcard.img` listed, your image is ready to be flashed to your SD card. You can now flash this image to your SD card and boot your Raspberry Pi with a debuggable Linux kernel.
+
+For details on flashing the SD card image, see the article [Writing an SD Card Image Using Ubuntu Disk Image Writer](https://www.ev3dev.org/docs/tutorials/writing-sd-card-image-ubuntu-disk-image-writer/).
+
+## What you've accomplished and what's next
 
-Now that you have a target running Linux with a debuggable kernel image, you can start writing your kernel module that you want to profile.
+You've now successfully built a custom Linux image with debugging features enabled and flashed it to your Raspberry Pi. This milestone means your development board is now running a kernel that's ready for profiling and advanced debugging. Great job! Setting up a debuggable environment is a significant step in embedded Linux development. Next, you'll write and profile your own kernel module, building on the solid foundation you've established.

content/learning-paths/embedded-and-microcontrollers/streamline-kernel-module/3_oot_module.md

@@ -1,18 +1,20 @@
 ---
-title: Build out-of-tree kernel module
+title: Build the out-of-tree kernel module
 weight: 4
 
 ### FIXED, DO NOT MODIFY
 layout: learningpathall
 ---
 
-## Creating the Linux Kernel Module
+## Develop a cache-unfriendly Linux kernel module to analyze with Arm Streamline
 
-You will now create an example Linux kernel module (Character device) that demonstrates a cache miss issue caused by traversing a 2D array in column-major order. This access pattern is not cache-friendly, as it skips over most of the neighboring elements in memory during each iteration.
+You'll create a simple Linux kernel module that acts as a character device and intentionally causes cache misses. It does this by traversing a two-dimensional array in column-major order, which is inefficient for the CPU cache because it jumps between non-adjacent memory locations. This pattern helps you see how cache-unfriendly code can slow down performance, making it easier to analyze with Arm Streamline.
 
-To build the Linux kernel module, start by creating a new directory, for example `example_module`. Inside this directory, add two files: `mychardrv.c` and `Makefile`. 
+To build the Linux kernel module, start by creating a new directory, for example `example_module`. Inside this directory, add two files: `Makefile` and `mychardrv.c`. 
 
-**Makefile**  
+## Makefile  
+
+To build your Linux kernel module for Arm, you need a Makefile that instructs the build system how to compile and link your code against the kernel source. The Makefile below is designed for use with Buildroot and cross-compiles your module for the aarch64 architecture. Update the `BUILDROOT_OUT` variable to match your Buildroot output directory before running the build:
 
 ```makefile
 obj-m += mychardrv.o
@@ -28,11 +30,10 @@ clean:
     $(MAKE) -C $(KDIR) M=$(PWD) clean
 ```
 
-{{% notice Note %}}
-Change **BUILDROOT_OUT** to the correct buildroot output directory on your host machine.
-{{% /notice %}}
 
-**mychardrv.c**  
+## mychardrv.c  
+
+The `mychardrv.c` file contains the source code for your custom Linux kernel module. This module implements a simple character device that demonstrates cache-unfriendly behavior by traversing a two-dimensional array in column-major order. The code below allocates and initializes the array, performs the cache-unfriendly traversal, and exposes a write interface for user input. You’ll use this module to generate measurable performance bottlenecks for analysis with Arm Streamline.
 
 ```c
 // SPDX-License-Identifier: GPL-2.0
@@ -203,55 +204,54 @@ MODULE_DESCRIPTION("A simple char driver with cache misses issue");
 
 The module above receives the size of a 2D array as a string through the `char_dev_write()` function, converts it to an integer, and passes it to the `char_dev_cache_traverse()` function. This function then creates the 2D array, initializes it with simple data, traverses it in a column-major (cache-unfriendly) order, computes the sum of its elements, and prints the result to the kernel log. The cache-unfriendly aspects allows you to inspect a bottleneck using Streamline in the next section.
 
-## Building and Running the Kernel Module
+## Build and run the kernel module
 
-1. To compile the kernel module, run make inside the example_module directory. This will generate the output file `mychardrv.ko`.
+To compile the kernel module, run `make` inside the `example_module` directory. This generates the output file `mychardrv.ko`.
 
-2. Transfer the .ko file to the target using scp command and then insert it using insmod command. After inserting the module, you create a character device node using mknod command. Finally, you can test the module by writing a size value (e.g., 10000) to the device file and measuring the time taken for the operation using the `time` command.
+Transfer the kernel module (`mychardrv.ko`) to your target device using the `scp` command. Then, insert the module with `insmod` and create the character device node with `mknod`. To test the module, write a size value (such as 10000) to the device file and use the `time` command to measure how long the operation takes. This lets you see the performance impact of the cache-unfriendly access pattern in a clear, hands-on way:
 
-    ```bash
+```bash
     scp mychardrv.ko root@<target-ip>:/root/
-    ```
+```
 
-    {{% notice Note %}}
-    Replace \<target-ip> with your target's IP address
-    {{% /notice %}}
+{{% notice Note %}} Replace `<target-ip>` with your target's IP address
+{{% /notice %}}
 
-3. SSH onto your target device:
+SSH onto your target device:
 
-    ```bash
+```bash
     ssh root@<your-target-ip>
-    ```    
+```    
 
-4. Execute the following commands on the target to run the module:
-    ```bash
+Execute the following commads on the target to run the module:
+```bash
     insmod /root/mychardrv.ko
     mknod /dev/mychardrv c 42 0
-    ```
+```
+
+{{% notice Note %}}
+    42 and 0 are the major and minor number specified in the module code above.
+  {{% /notice %}}
 
-    {{% notice Note %}}
-    42 and 0 are the major and minor number specified in the module code above
-    {{% /notice %}}
+To confirm that your kernel module is loaded and running, use the `dmesg` command. You should see a message like this in the output:
 
-4. To verify that the module is active, run `dmesg` and the output should match the below:
 
-    ```bash
+ ```bash
     dmesg
-    ```
+ ```
 
-    ```output
+  ```output
       [12381.654983] mychardrv is open - Major(42) Minor(0)
-    ```
+  ```
 
-5. To make sure it's working as expected you can use the following command:
+To make sure it's working as expected you can use the following command:
 
-    ```bash { output_lines = "2-4" }
+```bash { output_lines = "2-4" }
     time echo '10000' > /dev/mychardrv
     #   real    0m 38.04s
     #   user    0m 0.00s
     #   sys     0m 38.03s
-    ```
-
-    The command above passes 10000 to the module, which specifies the size of the 2D array to be created and traversed. The **echo** command takes a long time to complete (around 38 seconds) due to the cache-unfriendly traversal implemented in the `char_dev_cache_traverse()` function.
+```
+The command above sends the value 10000 to your kernel module, which sets the size of the 2D array it creates and traverses. Because the module accesses the array in a cache-unfriendly way, the `echo` command takes a noticeable amount of time to finish - it's about 38 seconds in this example. This delay is expected and highlights the performance impact of inefficient memory access patterns, making it easy to analyze with Arm Streamline.
 
-With the kernel module built, the next step is to profile it using Arm Streamline. You will use it to capture runtime behavior, highlight performance bottlenecks, and help identifying issues such as the cache-unfriendly traversal in your module.
+You have successfully built and run your kernel module. In the next section, you'll profile it using Arm Streamline to capture runtime behavior, identify performance bottlenecks, and observe the effects of cache-unfriendly access patterns. This analysis will help you understand and optimize your code.