Linux Kernel

https://www.kernel.org/doc/html/latest/
Admin
The Linux Kernel is the core component of the Linux operating system that manages hardware resources...
Tokens:17,834,896
Snippets:121,435
Trust Score:10
Update:1 week ago
Show doc for...
Tokens:
Raw
### modprobe command example

Source: https://www.kernel.org/doc/html/latest/_sources/scsi/sym53c8xx_2.rst.txt

Installs the sym53c8xx driver module with the same options as the boot setup command: cmd_per_lun=4, sync=10, and debug=0x200.

```bash
modprobe sym53c8xx cmd_per_lun=4 sync=10 debug=0x200
```

--------------------------------

### Example 3: Simplified eprobe setup

Source: https://www.kernel.org/doc/html/latest/_sources/trace/eprobetrace.rst.txt

Commands to achieve the same result as Example 2 when syscall trace events are available, without the first eprobe.

```bash
# echo 's:filename u64 file' >> dynamic_events
# echo 'hist:keys=common_pid:f=filename' > events/syscalls/sys_enter_openat/trigger
# echo 'hist:keys=common_pid:file=$f:onmatch(syscalls.sys_enter_openat).trace(filename,$file)' > events/syscalls/sys_exit_openat/trigger
# echo 'e:openat synthetic.filename filename=+0($file):ustring' >> dynamic_events
# echo 1 > events/eprobes/openat/enable
```

--------------------------------

### Boot setup command example

Source: https://www.kernel.org/doc/html/latest/_sources/scsi/sym53c8xx_2.rst.txt

Example of passing driver options at boot time via the lilo prompt. Enables tagged commands (up to 4), sets synchronous negotiation speed to 10 Mega-transfers/second, and sets the DEBUG_NEGO flag.

```bash
lilo: linux root=/dev/sda2 sym53c8xx.cmd_per_lun=4 sym53c8xx.sync=10 sym53c8xx.debug=0x200
```

--------------------------------

### Start diod 9pfs server

Source: https://www.kernel.org/doc/html/latest/filesystems/9p.html

Starts the diod 9pfs server on the development host, listening on all interfaces at port 9999 and exporting the current directory. This is part of the USB gadget example setup.

```shell
$ diod -f -n -d 0 -S -l 0.0.0.0:9999 -e $PWD

```

--------------------------------

### Complete example: setup_socket, display, walk_block, flush_block, teardown_socket, main

Source: https://www.kernel.org/doc/html/latest/_sources/networking/packet_mmap.rst.txt

This is the full example program from the documentation, showing how to set up a packet socket with a ring buffer, process packets, and handle statistics. It includes functions for socket setup, packet display, block walking, flushing, and teardown.

```c
    err = bind(fd, (struct sockaddr *) &ll, sizeof(ll));
    if (err < 0) {
	    perror("bind");
	    exit(1);
    }

    return fd;
}

static void display(struct tpacket3_hdr *ppd)
{
	struct ethhdr *eth = (struct ethhdr *) ((uint8_t *) ppd + ppd->tp_mac);
	struct iphdr *ip = (struct iphdr *) ((uint8_t *) eth + ETH_HLEN);

	if (eth->h_proto == htons(ETH_P_IP)) {
		struct sockaddr_in ss, sd;
		char sbuff[NI_MAXHOST], dbuff[NI_MAXHOST];

		memset(&ss, 0, sizeof(ss));
		ss.sin_family = PF_INET;
		ss.sin_addr.s_addr = ip->saddr;
		getnameinfo((struct sockaddr *) &ss, sizeof(ss),
			    sbuff, sizeof(sbuff), NULL, 0, NI_NUMERICHOST);

		memset(&sd, 0, sizeof(sd));
		sd.sin_family = PF_INET;
		sd.sin_addr.s_addr = ip->daddr;
		getnameinfo((struct sockaddr *) &sd, sizeof(sd),
			    dbuff, sizeof(dbuff), NULL, 0, NI_NUMERICHOST);

		printf("%s -> %s, ", sbuff, dbuff);
	}

	printf("rxhash: 0x%x\n", ppd->hv1.tp_rxhash);
}

static void walk_block(struct block_desc *pbd, const int block_num)
{
	int num_pkts = pbd->h1.num_pkts, i;
	unsigned long bytes = 0;
	struct tpacket3_hdr *ppd;

	ppd = (struct tpacket3_hdr *) ((uint8_t *) pbd +
					pbd->h1.offset_to_first_pkt);
	for (i = 0; i < num_pkts; ++i) {
		bytes += ppd->tp_snaplen;
		display(ppd);

		ppd = (struct tpacket3_hdr *) ((uint8_t *) ppd +
						ppd->tp_next_offset);
	}

	packets_total += num_pkts;
	bytes_total += bytes;
}

static void flush_block(struct block_desc *pbd)
{
	pbd->h1.block_status = TP_STATUS_KERNEL;
}

static void teardown_socket(struct ring *ring, int fd)
{
	munmap(ring->map, ring->req.tp_block_size * ring->req.tp_block_nr);
	free(ring->rd);
	close(fd);
}

int main(int argc, char **argp)
{
	int fd, err;
	socklen_t len;
	struct ring ring;
	struct pollfd pfd;
	unsigned int block_num = 0, blocks = 64;
	struct block_desc *pbd;
	struct tpacket_stats_v3 stats;

	if (argc != 2) {
		fprintf(stderr, "Usage: %s INTERFACE\n", argp[0]);
		return EXIT_FAILURE;
	}

	signal(SIGINT, sighandler);

	memset(&ring, 0, sizeof(ring));
	fd = setup_socket(&ring, argp[argc - 1]);
	assert(fd > 0);

	memset(&pfd, 0, sizeof(pfd));
	pfd.fd = fd;
	pfd.events = POLLIN | POLLERR;
	pfd.revents = 0;

	while (likely(!sigint)) {
		pbd = (struct block_desc *) ring.rd[block_num].iov_base;

		if ((pbd->h1.block_status & TP_STATUS_USER) == 0) {
			poll(&pfd, 1, -1);
			continue;
		}

		walk_block(pbd, block_num);
		flush_block(pbd);
		block_num = (block_num + 1) % blocks;
	}

	len = sizeof(stats);
	err = getsockopt(fd, SOL_PACKET, PACKET_STATISTICS, &stats, &len);
	if (err < 0) {
		perror("getsockopt");
		exit(1);
	}

	fflush(stdout);
	printf("\nReceived %u packets, %lu bytes, %u dropped, freeze_q_cnt: %u\n",
	    stats.tp_packets, bytes_total, stats.tp_drops,
	    stats.tp_freeze_q_cnt);

	teardown_socket(&ring, fd);
	return 0;
}
```

--------------------------------

### Setup and teardown a statically allocated state in the STARTING section

Source: https://www.kernel.org/doc/html/latest/_sources/core-api/cpu_hotplug.rst.txt

Example of setting up and tearing down a statically allocated CPU hotplug state in the STARTING section for notifications on online and offline operations. Uses cpuhp_setup_state() and cpuhp_remove_state().

```c
   ret = cpuhp_setup_state(CPUHP_SUBSYS_STARTING, "subsys:starting", subsys_cpu_starting, subsys_cpu_dying);
   if (ret < 0)
        return ret;
   ....
   cpuhp_remove_state(CPUHP_SUBSYS_STARTING);
```

--------------------------------

### Create example configuration c.1

Source: https://www.kernel.org/doc/html/latest/usb/gadget_configfs.html

Creates a configuration named c.1.

```bash
$ mkdir configs/c.1

...
...
...
```

--------------------------------

### Boot config example: foo.bar.baz = value1 and foo.bar.qux.quux = value2

Source: https://www.kernel.org/doc/html/latest/_sources/admin-guide/bootconfig.rst.txt

Example of two key-value pairs with shared prefix 'foo.bar'.

```text
foo.bar.baz = value1
foo.bar.qux.quux = value2
```

--------------------------------

### VFIO_EEH_PE_OP example: EEH setup, error detection and recovery

Source: https://www.kernel.org/doc/html/latest/driver-api/vfio.html

This example shows the required sequence of ioctl calls for EEH on PPC64 sPAPR. It starts with container setup and IOMMU configuration, then enables EEH, injects an error, checks PE state, and performs recovery steps. The code includes comments explaining each step and notes about saving/restoring device state.

```c
struct vfio_eeh_pe_op pe_op = { .argsz = sizeof(pe_op), .flags = 0 };

.....
/* Add the group to the container */
ioctl(group, VFIO_GROUP_SET_CONTAINER, &container);

/* Enable the IOMMU model we want */
ioctl(container, VFIO_SET_IOMMU, VFIO_SPAPR_TCE_IOMMU)

/* Get addition sPAPR IOMMU info */
vfio_iommu_spapr_tce_info spapr_iommu_info;
ioctl(container, VFIO_IOMMU_SPAPR_TCE_GET_INFO, &spapr_iommu_info);

if (ioctl(container, VFIO_IOMMU_ENABLE))
        /* Cannot enable container, may be low rlimit */

/* Allocate some space and setup a DMA mapping */
dma_map.vaddr = mmap(0, 1024 * 1024, PROT_READ | PROT_WRITE,
                     MAP_PRIVATE | MAP_ANONYMOUS, 0, 0);

dma_map.size = 1024 * 1024;
dma_map.iova = 0; /* 1MB starting at 0x0 from device view */
dma_map.flags = VFIO_DMA_MAP_FLAG_READ | VFIO_DMA_MAP_FLAG_WRITE;

/* Check here is .iova/.size are within DMA window from spapr_iommu_info */
ioctl(container, VFIO_IOMMU_MAP_DMA, &dma_map);

/* Get a file descriptor for the device */
device = ioctl(group, VFIO_GROUP_GET_DEVICE_FD, "0000:06:0d.0");

....

/* Gratuitous device reset and go... */
ioctl(device, VFIO_DEVICE_RESET);

/* Make sure EEH is supported */
ioctl(container, VFIO_CHECK_EXTENSION, VFIO_EEH);

/* Enable the EEH functionality on the device */
pe_op.op = VFIO_EEH_PE_ENABLE;
ioctl(container, VFIO_EEH_PE_OP, &pe_op);

/* You're suggested to create additional data struct to represent
 * PE, and put child devices belonging to same IOMMU group to the
 * PE instance for later reference.
 */

/* Check the PE's state and make sure it's in functional state */
pe_op.op = VFIO_EEH_PE_GET_STATE;
ioctl(container, VFIO_EEH_PE_OP, &pe_op);

/* Save device state using pci_save_state().
 * EEH should be enabled on the specified device.
 */

....

/* Inject EEH error, which is expected to be caused by 32-bits
 * config load.
 */
pe_op.op = VFIO_EEH_PE_INJECT_ERR;
pe_op.err.type = EEH_ERR_TYPE_32;
pe_op.err.func = EEH_ERR_FUNC_LD_CFG_ADDR;
pe_op.err.addr = 0ul;
pe_op.err.mask = 0ul;
ioctl(container, VFIO_EEH_PE_OP, &pe_op);

....

/* When 0xFF's returned from reading PCI config space or IO BARs
 * of the PCI device. Check the PE's state to see if that has been
 * frozen.
 */
ioctl(container, VFIO_EEH_PE_OP, &pe_op);

/* Waiting for pending PCI transactions to be completed and don't
 * produce any more PCI traffic from/to the affected PE until
 * recovery is finished.
 */

/* Enable IO for the affected PE and collect logs. Usually, the
 * standard part of PCI config space, AER registers are dumped
 * as logs for further analysis.
 */
pe_op.op = VFIO_EEH_PE_UNFREEZE_IO;
ioctl(container, VFIO_EEH_PE_OP, &pe_op);

/*
 * Issue PE reset: hot or fundamental reset. Usually, hot reset
 * is enough. However, the firmware of some PCI adapters would
 * require fundamental reset.
 */
pe_op.op = VFIO_EEH_PE_RESET_HOT;
ioctl(container, VFIO_EEH_PE_OP, &pe_op);
pe_op.op = VFIO_EEH_PE_RESET_DEACTIVATE;
ioctl(container, VFIO_EEH_PE_OP, &pe_op);

/* Configure the PCI bridges for the affected PE */
pe_op.op = VFIO_EEH_PE_CONFIGURE;
ioctl(container, VFIO_EEH_PE_OP, &pe_op);

/* Restored state we saved at initialization time. pci_restore_state()
 * is good enough as an example.
 */

/* Hopefully, error is recovered successfully. Now, you can resume to
 * start PCI traffic to/from the affected PE.
 */

....

```

--------------------------------

### Example .config file with media support options

Source: https://www.kernel.org/doc/html/latest/_sources/admin-guide/media/building.rst.txt

Example of the .config file after configuring media support. Shows the relevant configuration options and their values.

```text
    ...
    # CONFIG_RC_CORE is not set
    # CONFIG_CEC_CORE is not set
    CONFIG_MEDIA_SUPPORT=m
    CONFIG_MEDIA_SUPPORT_FILTER=y
    ...
```

--------------------------------

### HDIO_GETGEO usage example

Source: https://www.kernel.org/doc/html/latest/userspace-api/ioctl/hdio.html

Calls HDIO_GETGEO to get device geometry. Returns a hd_geometry structure with heads, sectors, cylinders, and start. Returns EINVAL if the device is not a disk or floppy drive or if a null pointer is passed.

```c
struct hd_geometry geom;

ioctl(fd, HDIO_GETGEO, &geom);

```

--------------------------------

### IIO Trigger Setup Example

Source: https://www.kernel.org/doc/html/latest/driver-api/iio/triggers.html

Example of allocating, configuring, and registering an IIO trigger.

```APIDOC
## IIO Trigger Setup

### Description
Example of how to allocate, configure, and register an IIO trigger.

### Code
```c
struct iio_trigger_ops trigger_ops = {
    .set_trigger_state = sample_trigger_state,
    .validate_device = sample_validate_device,
}

struct iio_trigger *trig;

/* first, allocate memory for our trigger */
trig = iio_trigger_alloc(dev, "trig-%s-%d", name, idx);

/* setup trigger operations field */
trig->ops = &trigger_ops;

/* now register the trigger with the IIO core */
iio_trigger_register(trig);
```
```

--------------------------------

### Initrd /etc/fstab example

Source: https://www.kernel.org/doc/html/latest/_sources/power/swsusp-dmcrypt.rst.txt

Example fstab entries for the initrd, mounting the mini system and proc/sys.

```text
/dev/hda1   /mnt    ext3      ro                            0 0
none        /proc   proc      defaults,noatime,nodiratime   0 0
none        /sys    sysfs     defaults,noatime,nodiratime   0 0
```

--------------------------------

### Create gadget instance and configurations

Source: https://www.kernel.org/doc/html/latest/_sources/sound/designs/midi-2.0.rst.txt

Create a gadget instance and add configurations, including setting product/vendor IDs, strings, and MaxPower.

```shell
% cd /sys/kernel/config
% mkdir usb_gadget/g1

% cd usb_gadget/g1
% mkdir configs/c.1
% mkdir functions/midi2.usb0

% echo 0x0004 > idProduct
% echo 0x17b3 > idVendor
% mkdir strings/0x409
% echo "ACME Enterprises" > strings/0x409/manufacturer
% echo "ACMESynth" > strings/0x409/product
% echo "ABCD12345" > strings/0x409/serialnumber

% mkdir configs/c.1/strings/0x409
% echo "Monosynth" > configs/c.1/strings/0x409/configuration
% echo 120 > configs/c.1/MaxPower
```

--------------------------------

### menuconfig regex search example

Source: https://www.kernel.org/doc/html/latest/_sources/kbuild/kconfig.rst.txt

Example of using a regular expression in menuconfig search to match symbols starting with 'hotplug'.

```text
/^hotplug
```

--------------------------------

### Get current printer status

Source: https://www.kernel.org/doc/html/latest/_sources/usb/gadget_printer.rst.txt

Run the example program to get the current printer status. The output shows the status lines.

```bash
# prn_example -get_status
```

```bash
Printer status is:
     Printer is NOT Selected
     Paper is Out
     Printer OK
```

--------------------------------

### Get delays for a tgid

Source: https://www.kernel.org/doc/html/latest/_sources/accounting/delay-accounting.rst.txt

Example command to get sum and peak delays for all pids with tgid 242, showing sample output.

```bash
bash-4.4# ./getdelays -d -t 242
print delayacct stats ON
TGID    242
```

--------------------------------

### dmsetup create cache device examples

Source: https://www.kernel.org/doc/html/latest/_sources/admin-guide/device-mapper/cache.rst.txt

Example commands to create a cache device using the 'cache' target. The first uses writeback policy with default settings; the second uses the 'mq' policy with sequential_threshold and random_threshold arguments.

```text
dmsetup create my_cache --table '0 41943040 cache /dev/mapper/metadata \
	  /dev/mapper/ssd /dev/mapper/origin 512 1 writeback default 0'
  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'
```

--------------------------------

### Get delays for a specific pid

Source: https://www.kernel.org/doc/html/latest/_sources/accounting/delay-accounting.rst.txt

Example command to get delays since system boot for pid 10 using getdelays.

```bash
# ./getdelays -d -p 10
```

--------------------------------

### Create example.c implementation file

Source: https://www.kernel.org/doc/html/latest/_sources/dev-tools/kunit/start.rst.txt

Implementation of the function to be tested.

```c
#include <linux/errno.h>

#include "example.h"

int misc_example_add(int left, int right)
{
	return left + right;
}
```

--------------------------------

### Example command to run a .exe file directly

Source: https://www.kernel.org/doc/html/latest/_sources/admin-guide/mono.rst.txt

After setup, .exe binaries can be executed directly from the command prompt. If this fails with a permission denied error, ensure the .exe file has execute permissions.

```sh
/usr/bin/xsd.exe
```

--------------------------------

### Platform setup callback obtaining mach_info and fb_info

Source: https://www.kernel.org/doc/html/latest/_sources/fb/ep93xx-fb.rst.txt

Example of a setup callback that retrieves the ep93xxfb_mach_info and fb_info structures from the platform device.

```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 */
}
```

--------------------------------

### modprobe command to install sym53c8xx driver with same options

Source: https://www.kernel.org/doc/html/latest/scsi/sym53c8xx_2.html

Command to install the driver module with the same options as the lilo example: cmd_per_lun=4, sync=10, debug=0x200.

```bash
modprobe sym53c8xx cmd_per_lun=4 sync=10 debug=0x200

```

--------------------------------

### Create example.h header file

Source: https://www.kernel.org/doc/html/latest/_sources/dev-tools/kunit/start.rst.txt

Header file declaring the function to be tested.

```c
int misc_example_add(int left, int right);
```
Tokens:
Raw