### Platform Setup Callback Example (C) Source: https://github.com/wireguard/wireguard-linux/blob/stable/Documentation/fb/ep93xx-fb.rst An example of a platform setup function for the EP93xx framebuffer driver. This function is called during driver initialization and receives the `platform_device` structure, from which the `ep93xxfb_mach_info` and `fb_info` structures can be accessed. ```c static int some_board_fb_setup(struct platform_device *pdev) { struct ep93xxfb_mach_info *mach_info = pdev->dev.platform_data; struct fb_info *fb_info = platform_get_drvdata(pdev); /* Board specific framebuffer setup */ } ``` -------------------------------- ### Example: Multi-Instance State Setup and Teardown (C) Source: https://github.com/wireguard/wireguard-linux/blob/stable/Documentation/core-api/cpu_hotplug.rst Demonstrates the setup, instance addition, instance removal, and teardown of a dynamically allocated multi-instance state for notifications on online and offline operations. ```c int state = cpuhp_setup_state_multi(CPUHP_AP_ONLINE_DYN, "subsys:online", subsys_cpu_online, subsys_cpu_offline); if (state < 0) return state; .... ret = cpuhp_state_add_instance(state, &inst1->node); if (ret) return ret; .... ret = cpuhp_state_add_instance(state, &inst2->node); if (ret) return ret; .... cpuhp_remove_instance(state, &inst1->node); .... cpuhp_remove_instance(state, &inst2->node); .... cpuhp_remove_multi_state(state); ``` -------------------------------- ### ifconfig Output Example for Bonding (Text) Source: https://github.com/wireguard/wireguard-linux/blob/stable/Documentation/networking/bonding.rst This text snippet is an example output of the `ifconfig` command, illustrating a bonding setup. It shows the `bond0` interface as the MASTER and `eth0` and `eth1` as SLAVE interfaces, all sharing the same MAC address in this particular configuration. ```text bond0 Link encap:Ethernet HWaddr 00:C0:F0:1F:37:B4 inet addr:XXX.XXX.XXX.YYY Bcast:XXX.XXX.XXX.255 Mask:255.255.252.0 UP BROADCAST RUNNING MASTER MULTICAST MTU:1500 Metric:1 RX packets:7224794 errors:0 dropped:0 overruns:0 frame:0 TX packets:3286647 errors:1 dropped:0 overruns:1 carrier:0 collisions:0 txqueuelen:0 eth0 Link encap:Ethernet HWaddr 00:C0:F0:1F:37:B4 UP BROADCAST RUNNING SLAVE MULTICAST MTU:1500 Metric:1 RX packets:3573025 errors:0 dropped:0 overruns:0 frame:0 TX packets:1643167 errors:1 dropped:0 overruns:1 carrier:0 collisions:0 txqueuelen:100 Interrupt:10 Base address:0x1080 eth1 Link encap:Ethernet HWaddr 00:C0:F0:1F:37:B4 UP BROADCAST RUNNING SLAVE MULTICAST MTU:1500 Metric:1 RX packets:3651769 errors:0 dropped:0 overruns:0 frame:0 TX packets:1643480 errors:0 dropped:0 overruns:0 carrier:0 collisions:0 txqueuelen:100 Interrupt:9 Base address:0x1400 ``` -------------------------------- ### DMA Mapping and Preparation Example - C Source: https://github.com/wireguard/wireguard-linux/blob/stable/Documentation/driver-api/dmaengine/client.rst Demonstrates the typical setup for preparing a slave SG DMA transfer. It involves getting the DMA device, mapping the scatterlist, and then preparing the DMA descriptor. Error handling for mapping is included. ```c struct device *dma_dev = dmaengine_get_dma_device(chan); nr_sg = dma_map_sg(dma_dev, sgl, sg_len); if (nr_sg == 0) /* error */ desc = dmaengine_prep_slave_sg(chan, sgl, nr_sg, direction, flags); ``` -------------------------------- ### Start IEEE 802.15.4 Hardware Device (C) Source: https://github.com/wireguard/wireguard-linux/blob/stable/Documentation/networking/ieee802154.rst Handler called by the 802.15.4 module to initialize the hardware device. This function should perform any necessary setup for the radio transceiver and return 0 on success or a negative error code on failure. ```c int start(struct ieee802154_hw *hw) ``` -------------------------------- ### Create and Test a Simple Initramfs with 'hello world' Source: https://github.com/wireguard/wireguard-linux/blob/stable/Documentation/filesystems/ramfs-rootfs-initramfs.rst This snippet demonstrates how to create a basic initramfs containing a 'hello world' program. It involves writing C code, compiling it statically, creating a cpio archive, compressing it with gzip, and then testing it using QEMU with the kernel's initrd loading mechanism. This is useful for verifying initramfs functionality and debugging. ```c #include #include int main(int argc, char *argv[]) { printf("Hello world!\n"); sleep(999999999); } ``` ```bash gcc -static hello.c -o init echo init | cpio -o -H newc | gzip > test.cpio.gz # Testing external initramfs using the initrd loading mechanism. qemu -kernel /boot/vmlinuz -initrd test.cpio.gz /dev/zero ``` -------------------------------- ### Example: Pointing to SETUP_E820_EXT Data using setup_indirect in C Source: https://github.com/wireguard/wireguard-linux/blob/stable/Documentation/arch/x86/boot.rst Illustrates how to use the setup_indirect structure to point to SETUP_E820_EXT data. This example shows the layout of both setup_data and setup_indirect when used together to pass extended memory map information. ```c struct setup_data { .next = 0, .type = SETUP_INDIRECT, .len = sizeof(setup_indirect), .data[sizeof(setup_indirect)] = (struct setup_indirect) { .type = SETUP_INDIRECT | SETUP_E820_EXT, .reserved = 0, .len = , .addr = , }, } ``` -------------------------------- ### Default Response Example with STOP/START Source: https://github.com/wireguard/wireguard-linux/blob/stable/Documentation/i2c/slave-testunit-backend.rst This example demonstrates that using STOP/START combinations between i2c messages does not work like a REPEATED START. It shows the default response when the controller does not handle repeated starts correctly. ```bash # i2cset -y 0 0x30 4 0 0 i; i2cget -y 0 0x30 0x00 ``` -------------------------------- ### Sample Boot Loader Configuration (C) Source: https://github.com/wireguard/wireguard-linux/blob/stable/Documentation/arch/x86/boot.rst Provides a C code example for a sample boot loader configuration, demonstrating how to set up kernel header fields, including heap end, command line pointer, and copying the command line string for different protocol versions. ```c unsigned long base_ptr; if (setup_sects == 0) setup_sects = 4; if (protocol >= 0x0200) { type_of_loader = ; if (loading_initrd) { ramdisk_image = ; ramdisk_size = ; } if (protocol >= 0x0202 && loadflags & 0x01) heap_end = 0xe000; else heap_end = 0x9800; if (protocol >= 0x0201) { heap_end_ptr = heap_end - 0x200; loadflags |= 0x80; /* CAN_USE_HEAP */ } if (protocol >= 0x0202) { cmd_line_ptr = base_ptr + heap_end; strcpy(cmd_line_ptr, cmdline); } else { cmd_line_magic = 0xA33F; cmd_line_offset = heap_end; setup_move_size = heap_end + strlen(cmdline) + 1; strcpy(base_ptr + cmd_line_offset, cmdline); } } else { /* Very old kernel */ } ``` -------------------------------- ### Referencing a Specific Commit in Git Source: https://github.com/wireguard/wireguard-linux/blob/stable/Documentation/process/submitting-patches.rst This example shows the recommended way to reference a specific commit in a patch description. It includes both the commit's SHA-1 ID and its one-line summary for clarity, making it easier for reviewers to understand the context. ```git commit message Commit e21d2170f36602ae2708 ("video: remove unnecessary ``` -------------------------------- ### OverlayFS Basic Mount Example Source: https://github.com/wireguard/wireguard-linux/blob/stable/Documentation/filesystems/overlayfs.rst A basic example demonstrating the equivalence between copying files upfront and using OverlayFS with an upper and lower directory. This shows the on-demand copying nature of OverlayFS. ```bash mount -t overlay overlay -olowerdir=/lower,upperdir=/upper /merged ``` -------------------------------- ### Clone Linux Kernel Mainline Repository using Git Source: https://github.com/wireguard/wireguard-linux/blob/stable/Documentation/process/submitting-patches.rst This command demonstrates how to obtain the current Linux kernel source tree using 'git clone'. It fetches the mainline repository from the official kernel Git server. Ensure you have 'git' installed and configured. ```bash git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git ``` -------------------------------- ### Prepare cgroups and mount memory controller Source: https://github.com/wireguard/wireguard-linux/blob/stable/Documentation/admin-guide/cgroup-v1/memory.rst This snippet demonstrates the initial steps to set up cgroups and mount the memory controller. It involves creating a temporary filesystem for cgroups, creating a memory cgroup directory, and mounting the memory controller with specific options. This is a prerequisite for managing memory per cgroup. ```bash # mount -t tmpfs none /sys/fs/cgroup # mkdir /sys/fs/cgroup/memory # mount -t cgroup none /sys/fs/cgroup/memory -o memory ``` -------------------------------- ### Creating Sync Files Source: https://github.com/wireguard/wireguard-linux/blob/stable/Documentation/driver-api/sync_file.rst When a driver needs to send an out-fence to userspace, it creates a sync_file. The caller passes the out-fence and gets back the sync_file. An fd is then installed on sync_file->file and can be sent to userspace. If the creation process fails or the sync_file needs to be released, fput(sync_file->file) should be used. ```APIDOC ## Creating Sync Files ### Description Creates a sync_file to send out-fences to userspace. ### Method N/A (Kernel function) ### Endpoint N/A (Kernel function) ### Parameters #### Path Parameters None #### Query Parameters None #### Request Body None ### Request Example ```c struct sync_file *sync_file_create(struct dma_fence *fence); // ... later ... int fd = get_unused_fd_flags(O_CLOEXEC); fd_install(fd, sync_file->file); ``` ### Response #### Success Response (200) N/A (Kernel function returns a pointer to struct sync_file) #### Response Example N/A ``` -------------------------------- ### Testing MIDI Input from Gadget to Host Source: https://github.com/wireguard/wireguard-linux/blob/stable/Documentation/usb/gadget-testing.rst This example demonstrates how to test MIDI input from a gadget to the host, emulating a MIDI keyboard. It involves using 'aconnect' to list ports and 'aplaymidi' on the gadget to send a MIDI stream, which can then be recorded on the host using 'arecordmidi'. ```bash # On the gadget: $ aconnect -o .... client 20: 'MIDI 2.0 Gadget' [type=kernel,card=1] 0 'MIDI 2.0 ' 1 'Group 1 (MIDI 2.0 Gadget I/O)' $ aplaymidi -p 20:1 to_host.mid # On the host: $ aconnect -i .... client 24: 'MIDI 2.0 Gadget' [type=kernel,card=2] 0 'MIDI 2.0 ' 1 'Group 1 (MIDI 2.0 Gadget I/O)' $ arecordmidi -p 24:1 from_gadget.mid ``` -------------------------------- ### Start CAN Network Device Source: https://github.com/wireguard/wireguard-linux/blob/stable/Documentation/networking/can.rst Starts a CAN network device, typically named 'canX'. It's essential to define proper bit-timing parameters before starting the device to avoid error-prone default settings. This example sets the bitrate to 125000. ```bash ip link set canX up type can bitrate 125000 ``` -------------------------------- ### Real-Mode Kernel Setup and Relocation (C) Source: https://github.com/wireguard/wireguard-linux/blob/stable/Documentation/arch/x86/boot.rst This C code snippet demonstrates the setup of the real-mode kernel, including defining memory locations like heap_end and cmd_line_offset. It handles copying the real-mode kernel to a specific address (0x90000) if it's not already there and then copies the command line to its designated location. It also includes clearing a portion of memory. ```c heap_end = 0x9800; cmd_line_magic = 0xA33F; cmd_line_offset = heap_end; /* A very old kernel MUST have its real-mode code loaded at 0x90000 */ if (base_ptr != 0x90000) { /* Copy the real-mode kernel */ memcpy(0x90000, base_ptr, (setup_sects + 1) * 512); base_ptr = 0x90000; /* Relocated */ } strcpy(0x90000 + cmd_line_offset, cmdline); /* It is recommended to clear memory up to the 32K mark */ memset(0x90000 + (setup_sects + 1) * 512, 0, (64 - (setup_sects + 1)) * 512); ``` -------------------------------- ### Verifying kselftest Setup Source: https://github.com/wireguard/wireguard-linux/blob/stable/Documentation/dev-tools/kselftest.rst This sequence of commands verifies the kselftest setup by building the kernel, modules, installing them, and then running the kselftest suite, specifically targeting the 'lib' module. ```sh # Assumes you have booted a fresh build of this kernel tree cd /path/to/linux/tree make kselftest-merge make modules sudo make modules_install make TARGETS=lib kselftest ``` -------------------------------- ### Manually Configure Bonding Interface with iproute2 Source: https://github.com/wireguard/wireguard-linux/blob/stable/Documentation/networking/bonding.rst This example demonstrates the manual setup of a bonding interface using `modprobe` and `ip link` commands. It's intended for systems where network initialization scripts lack specific bonding support. The commands load the bonding module with specified options, load a network card driver, configure the bond interface's IP address, and assign physical interfaces to the bond. ```shell modprobe bonding mode=balance-alb miimon=100 modprobe e100 ifconfig bond0 192.168.1.1 netmask 255.255.255.0 up ip link set eth0 master bond0 ip link set eth1 master bond0 ``` -------------------------------- ### seq_file Iterator Start Function Example (C) Source: https://github.com/wireguard/wireguard-linux/blob/stable/Documentation/filesystems/seq_file.rst An example of the `start` function required for a seq_file iterator. This function initializes the iterator, taking a position argument and returning an iterator structure that begins reading from that position. It demonstrates memory allocation for the position using `kmalloc`. ```c static void *ct_seq_start(struct seq_file *s, loff_t *pos) { loff_t *spos = kmalloc(sizeof(loff_t), GFP_KERNEL); if (! spos) ``` -------------------------------- ### dmsetup Command to Create a Cache Device (Writeback with Tuning) Source: https://github.com/wireguard/wireguard-linux/blob/stable/Documentation/admin-guide/device-mapper/cache.rst Another example of creating a cache device with `dmsetup`, this time including specific tuning parameters for the 'writeback' policy, such as `sequential_threshold` and `random_threshold`. This allows for more fine-grained control over cache behavior. ```bash dmsetup create my_cache --table '0 41943040 cache /dev/mapper/metadata \ /dev/mapper/ssd /dev/mapper/origin 1024 1 writeback \ mq 4 sequential_threshold 1024 random_threshold 8' ``` -------------------------------- ### Start OrangeFS Server and Client Services Source: https://github.com/wireguard/wireguard-linux/blob/stable/Documentation/filesystems/orangefs.rst Starts the OrangeFS server and client services using systemctl. Assumes the services have been installed via package manager. ```bash systemctl start orangefs-server systemctl start orangefs-client ``` -------------------------------- ### Configure Multiple Bonding Instances with Different Options Source: https://github.com/wireguard/wireguard-linux/blob/stable/Documentation/networking/bonding.rst This configuration example shows how to load multiple instances of the bonding module with distinct options, allowing for multiple bonding devices with different settings. Each instance is given a unique alias and options, enabling flexibility for complex network setups on systems lacking advanced initscript support. ```shell alias bond0 bonding options bond0 -o bond0 mode=balance-rr miimon=100 alias bond1 bonding options bond1 -o bond1 mode=balance-alb miimon=50 ``` -------------------------------- ### Linux Server TCP 3-Way Handshake Setup Source: https://github.com/wireguard/wireguard-linux/blob/stable/Documentation/networking/snmp_counter.rst Shows the command to start a netcat listener on a Linux server for TCP connections. This is the server-side setup for initiating a TCP 3-way handshake. ```bash nstatuser@nstat-b:~$ nc -lknv 0.0.0.0 9000 Listening on [0.0.0.0] (family 0, port 9000) ``` -------------------------------- ### Example Bond Configuration (sysfs, init.d) Source: https://github.com/wireguard/wireguard-linux/blob/stable/Documentation/networking/bonding.rst This example shows how to configure a bond interface (bond0) with two e100 devices (eth0, eth1) in balance-alb mode, along with MII monitoring, to persist across reboots. It involves loading kernel modules and setting sysfs parameters. ```bash modprobe bonding modprobe e100 echo balance-alb > /sys/class/net/bond0/bonding/mode ifconfig bond0 192.168.1.1 netmask 255.255.255.0 up echo 100 > /sys/class/net/bond0/bonding/miimon echo +eth0 > /sys/class/net/bond0/bonding/slaves echo +eth1 > /sys/class/net/bond0/bonding/slaves ``` -------------------------------- ### Install OrangeFS on Fedora Source: https://github.com/wireguard/wireguard-linux/blob/stable/Documentation/filesystems/orangefs.rst Installs the OrangeFS userspace components and server package on Fedora systems using dnf. This is the recommended method for quick setup on supported distributions. ```bash dnf -y install orangefs orangefs-server ``` -------------------------------- ### Configure and Request Bandwidth via Test Client Source: https://github.com/wireguard/wireguard-linux/blob/stable/Documentation/driver-api/interconnect.rst This example demonstrates how to use the `test-client` interface to configure source and destination nodes, retrieve path information, set desired average and peak bandwidth, and commit the bandwidth request. This feature is disabled by default and requires enabling `INTERCONNECT_ALLOW_WRITE_DEBUGFS`. ```bash cd /sys/kernel/debug/interconnect/test-client/ # Configure node endpoints for the path from CPU to DDR on # qcom/sm8550. echo chm_apps > src_node echo ebi > dst_node # Get path between src_node and dst_node. This is only # necessary after updating the node endpoints. echo 1 > get # Set desired BW to 1GBps avg and 2GBps peak. echo 1000000 > avg_bw echo 2000000 > peak_bw # Vote for avg_bw and peak_bw on the latest path from "get". # Voting for multiple paths is possible by repeating this # process for different nodes endpoints. echo 1 > commit ``` -------------------------------- ### Example: Using vidctrl and dd for device I/O Source: https://github.com/wireguard/wireguard-linux/blob/stable/Documentation/userspace-api/media/v4l/rw.rst This example demonstrates a command-line usage scenario for interacting with a video device using fictitious tools 'vidctrl' and the standard 'dd' command. It shows how to set input, format, and size, and then capture image data to a file. This illustrates a simple I/O method for capturing still images. ```none $ vidctrl /dev/video --input=0 --format=YUYV --size=352x288 $ dd if=/dev/video of=myimage.422 bs=202752 count=1 ``` -------------------------------- ### Customizing Module Installation Path with INSTALL_MOD_PATH Source: https://github.com/wireguard/wireguard-linux/blob/stable/Documentation/kbuild/modules.rst This example shows how to specify a custom installation prefix for kernel modules using the INSTALL_MOD_PATH variable. This variable can be set as a shell variable or directly on the 'make' command line, affecting both in-tree and out-of-tree module installations. ```bash $ make INSTALL_MOD_PATH=/frodo modules_install => Install dir: /frodo/lib/modules/$(KERNELRELEASE)/kernel/ ``` -------------------------------- ### Show Icon Example (Shell) Source: https://github.com/wireguard/wireguard-linux/blob/stable/Documentation/input/devices/yealink.rst This example shows how to activate the 'STORE' icon on the LCD. It writes the icon name to the 'show_icon' sysfs interface, which also updates the corresponding character on the LCD if it's part of a line. ```shell echo -n "STORE" > ./show_icon ``` -------------------------------- ### GPIO IRQCHIP Setup Helper Example (C) Source: https://github.com/wireguard/wireguard-linux/blob/stable/Documentation/driver-api/gpio/driver.rst Illustrates how to use infrastructure helpers for GPIO IRQCHIPs by filling in the struct gpio_irq_chip within struct gpio_chip. This example shows a typical setup for a chained cascaded interrupt handler, where mask/unmask functions call into the core gpiolib code. ```c /* Typical state container */ struct my_gpio { struct gpio_chip gc; }; /* ... initialization code ... */ /* The additional irq_chip will be set up by gpiolib */ /* ... */ /* Note how the mask/unmask (or disable/enable) functions call into the core gpiolib code */ ```