Linux Kernel 4.x

https://www.kernel.org/doc/html/v4.19/
Admin
This documentation provides release notes, installation instructions, and various guides for the...
Tokens:3,849,002
Snippets:42,421
Trust Score:10
Update:3 months ago
Show doc for...
Tokens:
Raw
### IIO HW Consumer Setup Example

Source: https://www.kernel.org/doc/html/v4.19/driver-api/iio/hw-consumer.html

Demonstrates a typical setup for an IIO HW consumer, including device probing and enabling/disabling the consumer. This setup is based on the standard IIO provider/consumer model.

```c
static struct iio_hw_consumer *hwc;

static const struct iio_info adc_info = {
        .read_raw = adc_read_raw,
};

static int adc_read_raw(struct iio_dev *indio_dev,
                        struct iio_chan_spec const *chan, int *val,
                        int *val2, long mask)
{
        ret = iio_hw_consumer_enable(hwc);

        /* Acquire data */

        ret = iio_hw_consumer_disable(hwc);
}

static int adc_probe(struct platform_device *pdev)
{
        hwc = devm_iio_hw_consumer_alloc(&iio->dev);
}
```

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

### IIO HW Consumer Setup Example

Source: https://www.kernel.org/doc/html/v4.19/_sources/driver-api/iio/hw-consumer.rst.txt

Demonstrates the typical setup for an IIO Hardware Consumer, including allocation and usage within a device probe and read function.

```c
static struct iio_hw_consumer *hwc;

static const struct iio_info adc_info = {
	.read_raw = adc_read_raw,
};

static int adc_read_raw(struct iio_dev *indio_dev,
				struct iio_chan_spec const *chan, int *val,
				int *val2, long mask)
{
	ret = iio_hw_consumer_enable(hwc);

	/* Acquire data */

	ret = iio_hw_consumer_disable(hwc);
}

static int adc_probe(struct platform_device *pdev)
{
	hwc = devm_iio_hw_consumer_alloc(&iio->dev);
}
```

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

### IIO Triggered Buffer Setup Example

Source: https://www.kernel.org/doc/html/v4.19/_sources/driver-api/iio/triggered-buffers.rst.txt

Demonstrates the setup of a triggered buffer, including defining buffer setup operations, poll functions, and trigger handlers. This is typically done in a probe function.

```c
const struct iio_buffer_setup_ops sensor_buffer_setup_ops = {
  .preenable    = sensor_buffer_preenable,
  .postenable   = sensor_buffer_postenable,
  .postdisable  = sensor_buffer_postdisable,
  .predisable   = sensor_buffer_predisable,
};

irqreturn_t sensor_iio_pollfunc(int irq, void *p)
{
    pf->timestamp = iio_get_time_ns((struct indio_dev *)p);
    return IRQ_WAKE_THREAD;
}

irqreturn_t sensor_trigger_handler(int irq, void *p)
{
    u16 buf[8];
    int i = 0;

    /* read data for each active channel */
    for_each_set_bit(bit, active_scan_mask, masklength)
        buf[i++] = sensor_get_data(bit)

    iio_push_to_buffers_with_timestamp(indio_dev, buf, timestamp);

    iio_trigger_notify_done(trigger);
    return IRQ_HANDLED;
}

/* setup triggered buffer, usually in probe function */
iio_triggered_buffer_setup(indio_dev, sensor_iio_polfunc,
                           sensor_trigger_handler,
                           sensor_buffer_setup_ops);
```

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

### IIO Trigger Setup Example

Source: https://www.kernel.org/doc/html/v4.19/_sources/driver-api/iio/triggers.rst.txt

A C code example demonstrating how to allocate, configure, and register an IIO trigger with the IIO core.

```APIDOC
## IIO Trigger Setup Example

This example shows how to set up a trigger to be used by a driver:

```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);
```
```

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

### IIO Triggered Buffer Setup Example

Source: https://www.kernel.org/doc/html/v4.19/driver-api/iio/triggered-buffers.html

Demonstrates a typical setup for a triggered buffer in an IIO driver. This includes defining buffer setup operations, a poll function top-half, a trigger handler bottom-half, and calling `iio_triggered_buffer_setup`.

```c
const struct iio_buffer_setup_ops sensor_buffer_setup_ops = {
  .preenable    = sensor_buffer_preenable,
  .postenable   = sensor_buffer_postenable,
  .postdisable  = sensor_buffer_postdisable,
  .predisable   = sensor_buffer_predisable,
};

irqreturn_t sensor_iio_pollfunc(int irq, void *p)
{
    pf->timestamp = iio_get_time_ns((struct indio_dev *)p);
    return IRQ_WAKE_THREAD;
}

irqreturn_t sensor_trigger_handler(int irq, void *p)
{
    u16 buf[8];
    int i = 0;

    /* read data for each active channel */
    for_each_set_bit(bit, active_scan_mask, masklength)
        buf[i++] = sensor_get_data(bit)

    iio_push_to_buffers_with_timestamp(indio_dev, buf, timestamp);

    iio_trigger_notify_done(trigger);
    return IRQ_HANDLED;
}

/* setup triggered buffer, usually in probe function */
iio_triggered_buffer_setup(indio_dev, sensor_iio_polfunc,
                           sensor_trigger_handler,
                           sensor_buffer_setup_ops);

```

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

### Example Directory Setup for Gcov

Source: https://www.kernel.org/doc/html/v4.19/_sources/dev-tools/gcov.rst.txt

Demonstrates the directory structure and the command to run gcov on the build machine after copying coverage files.

```bash
[user@build] cd /tmp/out
[user@build] gcov -o /tmp/coverage/tmp/out/init main.c
```

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

### Example Git Bisect Workflow

Source: https://www.kernel.org/doc/html/v4.19/_sources/admin-guide/bug-bisect.rst.txt

An example demonstrating how to start a bisect when the current version is known to be bad and a specific older version (v4.8) is known to be good.

```bash
$ git bisect start
$ git bisect bad                 # Current version is bad
$ git bisect good v4.8
```

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

### IIO Trigger Setup Example

Source: https://www.kernel.org/doc/html/v4.19/_sources/driver-api/iio/triggers.rst.txt

This snippet demonstrates the basic steps to allocate, configure, and register an IIO trigger with the IIO core. It requires defining trigger operations and associating them with the trigger.

```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);
```

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

### Example Usage of kselftest Harness

Source: https://www.kernel.org/doc/html/v4.19/_sources/dev-tools/kselftest.rst.txt

Demonstrates an example of how to use the kselftest harness. This snippet is generated from the kernel-doc directive for the 'example' documentation section.

```c
/*
 * Example test using the kselftest harness.
 */
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <errno.h>
#include <sys/types.h>
#include <sys/stat.h>
#include <fcntl.h>
#include <unistd.h>

#include "kselftest_harness.h"

/*
 * A simple test case.
 */
TEST(basic, simple)
{
	ASSERT_TRUE(1 == 1);
}

/*
 * Another test case.
 */
TEST(basic, another)
{
	ASSERT_EQ(1, 1);
}

/*
 * A test case that uses fixture data.
 */
FIXTURE_DATA(my_fixture, int, 42);

FIXTURE_SETUP(my_fixture)
{
	return 0;
}

FIXTURE_TEARDOWN(my_fixture)
{
	// Cleanup resources if any.
}

TEST_F(my_fixture, uses_fixture)
{
	ASSERT_EQ(*my_fixture, 42);
}

/*
 * A test case that expects a signal.
 */
TEST_SIGNAL(basic, signal_test, SIGSEGV)
{
	volatile int *ptr = NULL;
	*ptr = 1;
}

/*
 * Main function to run the tests.
 */
TEST_HARNESS_MAIN()

```

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

### ALSA Get Callback Example

Source: https://www.kernel.org/doc/html/v4.19/_sources/sound/kernel-api/writing-an-alsa-driver.rst.txt

Example of a get callback function to read the current value of a control and return it to user-space.

```c
static int snd_myctl_get(struct snd_kcontrol *kcontrol,
                               struct snd_ctl_elem_value *ucontrol)
{
              struct mychip *chip = snd_kcontrol_chip(kcontrol);
              ucontrol->value.integer.value[0] = get_some_value(chip);
              return 0;
}
```

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

### Example output with annotate option

Source: https://www.kernel.org/doc/html/v4.19/_sources/trace/ftrace.rst.txt

The 'annotate' option helps distinguish between CPU buffers by indicating when a new buffer starts. This example shows '##### CPU 2 buffer started ####' and subsequent events on different CPUs.

```text
##### CPU 2 buffer started ####
			  <idle>-0     [002] .N.1 21169.031484: rcu_idle_exit <-cpu_idle
			  <idle>-0     [001] .Ns3 21169.031484: _raw_spin_unlock <-clocksource_watchdog
			  <idle>-0     [001] .Ns3 21169.031485: sub_preempt_count <-_raw_spin_unlock
```

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

### Boot Parameter Example

Source: https://www.kernel.org/doc/html/v4.19/_sources/admin-guide/dynamic-debug-howto.rst.txt

Shows how to use the 'dyndbg' boot parameter to enable debug messages for specific files during the kernel boot process.

```text
dyndbg="file ec.c +p"
```

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

### Loadlin Boot Command Example

Source: https://www.kernel.org/doc/html/v4.19/_sources/admin-guide/initrd.rst.txt

Example of booting with Loadlin, specifying the kernel and initrd image.

```bash
LOADLIN C:\LINUX\BZIMAGE initrd=C:\LINUX\INITRD.GZ root=/dev/ram0 rw
```

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

### Main Program Entry Point

Source: https://www.kernel.org/doc/html/v4.19/media/uapi/v4l/capture.c.html

Parses command-line arguments, initializes the device, starts capturing, runs the main loop, and cleans up resources.

```c
int main(int argc, char **argv)
{
        dev_name = "/dev/video0";

        for (;; ) {
                int idx;
                int c;

                c = getopt_long(argc, argv,
                                short_options, long_options, &idx);

                if (-1 == c)
                        break;

                switch (c) {
                case 0: /* getopt_long() flag */
                        break;

                case 'd':
                        dev_name = optarg;
                        break;

                case 'h':
                        usage(stdout, argc, argv);
                        exit(EXIT_SUCCESS);

                case 'm':
                        io = IO_METHOD_MMAP;
                        break;

                case 'r':
                        io = IO_METHOD_READ;
                        break;

                case 'u':
                        io = IO_METHOD_USERPTR;
                        break;

                case 'o':
                        out_buf++;
                        break;

                case 'f':
                        force_format++;
                        break;

                case 'c':
                        errno = 0;
                        frame_count = strtol(optarg, NULL, 0);
                        if (errno)
                                errno_exit(optarg);
                        break;

                default:
                        usage(stderr, argc, argv);
                        exit(EXIT_FAILURE);
                }
        }

        open_device();
        init_device();
        start_capturing();
        mainloop();
        stop_capturing();
        uninit_device();
        close_device();
        fprintf(stderr, "\n");
        return 0;
}

```

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

### Using the snapshot feature

Source: https://www.kernel.org/doc/html/v4.19/_sources/trace/ftrace.rst.txt

This example demonstrates how to enable a specific event, take a snapshot, and then read the captured trace data using the 'snapshot' file.

```bash
# echo 1 > events/sched/enable
# echo 1 > snapshot
# cat snapshot
# tracer: nop
#
# entries-in-buffer/entries-written: 71/71   #P:8
#
#                              _-----=> irqs-off
#                             / _----=> need-resched
#                            | / _---=> hardirq/softirq
#                            || / _--=> preempt-depth
#                            ||| /     delay
#           TASK-PID   CPU#  ||||    TIMESTAMP  FUNCTION
#              | |       |   ||||       |         |
            <idle>-0     [005] d...  2440.603828: sched_switch: prev_comm=swapper/5 prev_pid=0 prev_prio=120   prev_state=R ==> next_comm=snapshot-test-2 next_pid=2242 next_prio=120
             sleep-2242  [005] d...  2440.603846: sched_switch: prev_comm=snapshot-test-2 prev_pid=2242 prev_prio=120   prev_state=R ==> next_comm=kworker/5:1 next_pid=60 next_prio=120
  [...]
          <idle>-0     [002] d...  2440.707230: sched_switch: prev_comm=swapper/2 prev_pid=0 prev_prio=120 prev_state=R ==> next_comm=snapshot-test-2 next_pid=2229 next_prio=120  

# cat trace  
# tracer: nop
#
# entries-in-buffer/entries-written: 77/77   #P:8
#
#                              _-----=> irqs-off
#                             / _----=> need-resched
#                            | / _---=> hardirq/softirq
#                            || / _--=> preempt-depth
#                            ||| /     delay
#           TASK-PID   CPU#  ||||    TIMESTAMP  FUNCTION
#              | |       |   ||||       |         |
            <idle>-0     [007] d...  2440.707395: sched_switch: prev_comm=swapper/7 prev_pid=0 prev_prio=120 prev_state=R ==> next_comm=snapshot-test-2 next_pid=2243 next_prio=120
   snapshot-test-2-2229  [002] d...  2440.707438: sched_switch: prev_comm=snapshot-test-2 prev_pid=2229 prev_prio=120 prev_state=S ==> next_comm=swapper/2 next_pid=0 next_prio=120
  [...]
```

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

### Manually Probe Device Setup

Source: https://www.kernel.org/doc/html/v4.19/sound/cards/audiophile-usb.html

Example command to manually probe the Audiophile USB device setup as root, allowing for dynamic configuration.

```bash
echo "0x01" > /sys/module/snd_usb_audio/parameters/device_setup
```

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

### Swap Device Binding Example (4-Node System)

Source: https://www.kernel.org/doc/html/v4.19/_sources/vm/swap_numa.rst.txt

Illustrates a more complex scenario with multiple swap devices attached to different NUMA nodes. The example shows the command to activate these devices and the resulting usage order for each node.

```bash
# swapon /dev/swapA
# swapon /dev/swapB
# swapon /dev/swapC
# swapon /dev/swapD
# swapon /dev/swapE
# swapon /dev/swapF
```

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

### One-line patch description example

Source: https://www.kernel.org/doc/html/v4.19/process/5.Posting.html

This is an example of a concise one-line description for a patch, often used in short-form changelogs. It typically starts with the relevant subsystem name.

```text
gpio: fix build on CONFIG_GPIO_SYSFS=n

```

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

### sparse_keymap_setup

Source: https://www.kernel.org/doc/html/v4.19/driver-api/input.html

Sets up a sparse keymap for an input device. It takes the input device, the keymap array, and an optional setup function as parameters.

```APIDOC
## sparse_keymap_setup

### Description
Sets up sparse keymap for an input device.

### Method
Not applicable (function call)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **dev** (struct input_dev *) - Input device
- **keymap** (const struct key_entry *) - Keymap in form of array of `key_entry` structures ending with `KE_END` type entry
- **setup** (int (*)(struct input_dev *, struct key_entry *)) - Function that can be used to adjust keymap entries depending on device’s needs, may be `NULL`

### Description
The function calculates size and allocates copy of the original keymap after which sets up input device event bits appropriately. The allocated copy of the keymap is automatically freed when it is no longer needed.
```

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

### C Code for Tracing Setup

Source: https://www.kernel.org/doc/html/v4.19/_sources/trace/ftrace.rst.txt

This C code demonstrates how to open tracing files, write to them to set up tracing, and execute a command.

```c
int main (int argc, char **argv)
{
	if (argc < 1)
		exit(-1);

	if (fork() > 0) {
		int fd, ffd;
		char line[64];
		int s;

		ffd = open(tracing_file("current_tracer"), O_WRONLY);
		if (ffd < 0)
			exit(-1);
		write(ffd, "nop", 3);

		fd = open(tracing_file("set_ftrace_pid"), O_WRONLY);
		s = sprintf(line, "%d\n", getpid());
		write(fd, line, s);

		write(ffd, "function", 8);

		close(fd);
		close(ffd);

		execvp(argv[1], argv+1);
	}

	return 0;
}
```

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

### Setup V4L2 Controls

Source: https://www.kernel.org/doc/html/v4.19/_sources/media/kapi/v4l2-controls.rst.txt

Optionally forces initial control setup by calling s_ctrl for all controls, synchronizing hardware with default values.

```c
v4l2_ctrl_handler_setup(&foo->ctrl_handler);
```

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

### Example Loadlin Command for RAID Array

Source: https://www.kernel.org/doc/html/v4.19/_sources/admin-guide/md.rst.txt

An example of a loadlin command line that includes RAID array configuration. This specifies the root device as md0 and details the RAID setup.

```bash
e:\loadlin\loadlin e:\zimage root=/dev/md0 md=0,0,4,0,/dev/hdb2,/dev/hdc3 ro
```

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

### Create and Save a Trusted Key (Example)

Source: https://www.kernel.org/doc/html/v4.19/security/keys/trusted-encrypted.html

This example demonstrates creating a 32-byte trusted key named 'kmk' and saving its blob to a file.

```bash
$ keyctl add trusted kmk "new 32" @u
440502848
```

```bash
$ keyctl show
Session Keyring
       -3 --alswrv    500   500  keyring: _ses
 97833714 --alswrv    500    -1   \_ keyring: _uid.500
440502848 --alswrv    500   500       \_ trusted: kmk
```

```bash
$ keyctl print 440502848
0101000000000000000001005d01b7e3f4a6be5709930f3b70a743cbb42e0cc95e18e915
3f60da455bbf1144ad12e4f92b452f966929f6105fd29ca28e4d4d5a031d068478bacb0b
27351119f822911b0a11ba3d3498ba6a32e50dac7f32894dd890eb9ad578e4e292c83722
a52e56a097e6a68b3f56f7a52ece0cdccba1eb62cad7d817f6dc58898b3ac15f36026fec
d568bd4a706cb60bb37be6d8f1240661199d640b66fb0fe3b079f97f450b9ef9c22c6d5d
dd379f0facd1cd020281dfa3c70ba21a3fa6fc2471dc6d13ecf8298b946f65345faa5ef0
f1f8fff03ad0acb083725535636addb08d73dedb9832da198081e5deae84bfaf0409c22b
e4a8aea2b607ec96931e6f4d4fe563ba
```

```bash
$ keyctl pipe 440502848 > kmk.blob
```

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

### preemptoff Latency Trace Example

Source: https://www.kernel.org/doc/html/v4.19/_sources/trace/ftrace.rst.txt

This is an example of the output from the preemptoff tracer, showing a latency of 46 microseconds. It details the task, start and end times, and a call trace of functions executed during the preemption-disabled period.

```text
# tracer: preemptoff
#
# preemptoff latency trace v1.1.5 on 3.8.0-test+
# --------------------------------------------------------------------
# latency: 46 us, #4/4, CPU#1 | (M:preempt VP:0, KP:0, SP:0 HP:0 #P:4)
#    -----------------
#    | task: sshd-1991 (uid:0 nice:0 policy:0 rt_prio:0)
#    -----------------
#  => started at: do_IRQ
#  => ended at:   do_IRQ
#
#
#                  _------=> CPU#            
#                 / _-----=> irqs-off        
#                | / _----=> need-resched    
#                || / _---=> hardirq/softirq 
#                ||| / _--=> preempt-depth   
#                |||| /     delay             
#  cmd     pid   ||||| time  |   caller      
#     \   /      |||||  \    |   /
       sshd-1991    1d.h.    0us+: irq_enter <-do_IRQ
       sshd-1991    1d..1   46us : irq_exit <-do_IRQ
       sshd-1991    1d..1   47us+: trace_preempt_on <-do_IRQ
       sshd-1991    1d..1   52us : <stack trace>
   => sub_preempt_count
   => irq_exit
   => do_IRQ
   => ret_from_intr
```

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

### irqsoff Latency Trace Example

Source: https://www.kernel.org/doc/html/v4.19/_sources/trace/ftrace.rst.txt

This is an example of the output from the irqsoff tracer, showing a latency of 71 microseconds. It details the task, start and end times, and a call trace of functions executed during the latency period.

```text
# tracer: irqsoff
#
# irqsoff latency trace v1.1.5 on 3.8.0-test+
# --------------------------------------------------------------------
# latency: 71 us, #168/168, CPU#3 | (M:preempt VP:0, KP:0, SP:0 HP:0 #P:4)
#    -----------------
#    | task: bash-2042 (uid:0 nice:0 policy:0 rt_prio:0)
#    -----------------
#  => started at: ata_scsi_queuecmd
#  => ended at:   ata_scsi_queuecmd
#
#
#                  _------=> CPU#            
#                 / _-----=> irqs-off        
#                | / _----=> need-resched    
#                || / _---=> hardirq/softirq 
#                ||| / _--=> preempt-depth   
#                |||| /     delay             
#  cmd     pid   ||||| time  |   caller      
#     \   /      |||||  \    |   /
       bash-2042    3d...    0us : _raw_spin_lock_irqsave <-ata_scsi_queuecmd
       bash-2042    3d...    0us : add_preempt_count <-_raw_spin_lock_irqsave
       bash-2042    3d..1    1us : ata_scsi_find_dev <-ata_scsi_queuecmd
       bash-2042    3d..1    1us : __ata_scsi_find_dev <-ata_scsi_find_dev
       bash-2042    3d..1    2us : ata_find_dev.part.14 <-__ata_scsi_find_dev
       bash-2042    3d..1    2us : ata_qc_new_init <-__ata_scsi_queuecmd
       bash-2042    3d..1    3us : ata_sg_init <-__ata_scsi_queuecmd
       bash-2042    3d..1    4us : ata_scsi_rw_xlat <-__ata_scsi_queuecmd
       bash-2042    3d..1    4us : ata_build_rw_tf <-ata_scsi_rw_xlat
   [...]
       bash-2042    3d..1   67us : delay_tsc <-__delay
       bash-2042    3d..1   67us : add_preempt_count <-delay_tsc
       bash-2042    3d..2   67us : sub_preempt_count <-delay_tsc
       bash-2042    3d..1   67us : add_preempt_count <-delay_tsc
       bash-2042    3d..2   68us : sub_preempt_count <-delay_tsc
       bash-2042    3d..1   68us+: ata_bmdma_start <-ata_bmdma_qc_issue
       bash-2042    3d..1   71us : _raw_spin_unlock_irqrestore <-ata_scsi_queuecmd
       bash-2042    3d..1   71us : _raw_spin_unlock_irqrestore <-ata_scsi_queuecmd
       bash-2042    3d..1   72us+: trace_hardirqs_on <-ata_scsi_queuecmd
       bash-2042    3d..1  120us : <stack trace>
   => _raw_spin_unlock_irqrestore
   => ata_scsi_queuecmd
   => scsi_dispatch_cmd
   => scsi_request_fn
   => __blk_run_queue_uncond
   => __blk_run_queue
   => blk_queue_bio
   => generic_make_request
   => submit_bio
   => submit_bh
   => __ext3_get_inode_loc
   => ext3_iget
   => ext3_lookup
   => lookup_real
   => __lookup_hash
   => walk_component
   => lookup_last
   => path_lookupat
   => filename_lookup
   => user_path_at_empty
   => user_path_at
   => vfs_fstatat
   => vfs_stat
   => sys_newstat
   => system_call_fastpath
```

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

### Create and Format Initrd Filesystem

Source: https://www.kernel.org/doc/html/v4.19/_sources/admin-guide/initrd.rst.txt

Create an empty filesystem for initrd using dd and mke2fs. Use Minix FS if space is critical.

```bash
# dd if=/dev/zero of=initrd bs=300k count=1
# mke2fs -F -m0 initrd
```

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

### Create and Compile a Simple Java Program

Source: https://www.kernel.org/doc/html/v4.19/admin-guide/java.html

Demonstrates how to create a 'HelloWorld.java' file, compile it using javac, and set executable permissions for the resulting .class file.

```java
class HelloWorld {
        public static void main(String args[]) {
                System.out.println("Hello World!");
        }
}

```

```bash
javac HelloWorld.java

```

```bash
chmod 755 HelloWorld.class

```

```bash
./HelloWorld.class

```

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

### Get NAND Sub-operation Address Start Offset

Source: https://www.kernel.org/doc/html/v4.19/driver-api/mtdnand.html

Retrieves the start offset in an address array for a given instruction within a sub-operation. Avoid direct access to 'addr.addrs' as address instructions might be split.

```c
unsigned int nand_subop_get_addr_start_off(const struct nand_subop *_subop_, unsigned int _instr_idx_);
```

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

### Example Usage of vidctrl and dd for V4L2 Read/Write

Source: https://www.kernel.org/doc/html/v4.19/_sources/media/uapi/v4l/rw.rst.txt

This example demonstrates how to use command-line tools to set up a video device and capture an image using the Read/Write I/O method. It requires the vidctrl tool (fictitious) and the dd command.

```bash
$ vidctrl /dev/video --input=0 --format=YUYV --size=352x288
$ dd if=/dev/video of=myimage.422 bs=202752 count=1
```

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

### Get NAND Sub-operation Data Start Offset

Source: https://www.kernel.org/doc/html/v4.19/driver-api/mtdnand.html

Retrieves the start offset in a data array for a given data instruction within a sub-operation. Avoid direct access to 'data->buf.{in,out}' as data instructions might be split.

```c
unsigned int nand_subop_get_data_start_off(const struct nand_subop *_subop_, unsigned int _instr_idx_);
```

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

### User-space trace_marker usage

Source: https://www.kernel.org/doc/html/v4.19/trace/histogram.html

Example of how to use the traceputs function in user-space code to mark the start and end of a sleep period.

```c
traceputs("start");
clock_nanosleep(...);
traceputs("end");
```

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

### Bind Socket to CAN Interface

Source: https://www.kernel.org/doc/html/v4.19/networking/can.html

Example of binding a raw CAN socket to the 'can0' interface using ioctl to get the interface index.

```c
int s;
struct sockaddr_can addr;
struct ifreq ifr;

s = socket(PF_CAN, SOCK_RAW, CAN_RAW);

strcpy(ifr.ifr_name, "can0" );
ioctl(s, SIOCGIFINDEX, &ifr);

addr.can_family = AF_CAN;
addr.can_ifindex = ifr.ifr_ifindex;

bind(s, (struct sockaddr *)&addr, sizeof(addr));

(..)

```

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

### Get VMA Node Start Address (Page-Based)

Source: https://www.kernel.org/doc/html/v4.19/gpu/drm-mm.html

Returns the start address of a VMA node for page-based addressing. This can be used as an offset into the linear VM space provided by the VMA offset manager. Returns 0 if the node does not have an offset allocated.

```c
unsigned long drm_vma_node_start(const struct drm_vma_offset_node *_node_)
```

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

### Create and Format Initrd Image

Source: https://www.kernel.org/doc/html/v4.19/admin-guide/initrd.html

Creates a raw file for the initrd and formats it with the ext2 filesystem. Use Minix FS if space is critical.

```bash
dd if=/dev/zero of=initrd bs=300k count=1
mke2fs -F -m0 initrd
```

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

### Get Monotonic Time (ktime_t)

Source: https://www.kernel.org/doc/html/v4.19/_sources/core-api/timekeeping.rst.txt

Use ktime_get() for reliable timestamps and measuring short intervals. This clock starts at system boot but stops during suspend.

```c
ktime_t ktime_get( void )
```

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

### Example io.weight Read Output

Source: https://www.kernel.org/doc/html/v4.19/admin-guide/cgroup-v2.html

Shows the default weight and device-specific overrides for IO weighting.

```text
default 100
8:16 200
8:0 50

```

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

### Setup Maple Get Condition Callback

Source: https://www.kernel.org/doc/html/v4.19/sh/index.html

Sets up a callback handler for MAPLE_COMMAND_GETCOND. This function specifies the device, the callback function, the interval between callbacks, and the function code.

```c
void maple_getcond_callback(struct maple_device *_dev_, void (*callback) (struct mapleq _*mq_, unsigned long _interval_, unsigned long _function_))
```

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

### v4l2_ctrl_handler_setup

Source: https://www.kernel.org/doc/html/v4.19/media/kapi/v4l2-controls.html

Calls the s_ctrl op for all controls belonging to the handler to initialize hardware.

```APIDOC
## v4l2_ctrl_handler_setup

### Description
Call the s_ctrl op for all controls belonging to the handler to initialize the hardware to the current control values. Button controls will be skipped, as are read-only controls. If **hdl** == NULL, then this just returns 0.

### Parameters
* `struct v4l2_ctrl_handler * hdl` - The control handler.
```

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

### LILO Configuration Example

Source: https://www.kernel.org/doc/html/v4.19/_sources/admin-guide/initrd.rst.txt

Configure LILO to use an initrd image by specifying the initrd path and append parameters.

```bash
image = /bzImage
  initrd = /boot/initrd.gz
  append = "root=/dev/ram0 rw"
```

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

### Setup Asynchronous Atomic Commit

Source: https://www.kernel.org/doc/html/v4.19/gpu/drm-kms-helpers.html

Provides a starting point for implementing asynchronous atomic commits, utilizing split-out commit helpers for pre-plane, plane, and post-plane operations.

```c
drm_atomic_helper_setup_commit()
```

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

### Example: Adding Multiple V4L2 Controls

Source: https://www.kernel.org/doc/html/v4.19/media/kapi/v4l2-controls.html

Demonstrates initializing a control handler and adding various types of controls, including standard, menu, integer menu, and driver-specific menu controls. Includes error checking after control addition.

```c
static const s64 exp_bias_qmenu[] = {
       -2, -1, 0, 1, 2
};
static const char * const test_pattern[] = {
        "Disabled",
        "Vertical Bars",
        "Solid Black",
        "Solid White",
};

v4l2_ctrl_handler_init(&foo->ctrl_handler, nr_of_controls);
v4l2_ctrl_new_std(&foo->ctrl_handler, &foo_ctrl_ops,
                V4L2_CID_BRIGHTNESS, 0, 255, 1, 128);
v4l2_ctrl_new_std(&foo->ctrl_handler, &foo_ctrl_ops,
                V4L2_CID_CONTRAST, 0, 255, 1, 128);
v4l2_ctrl_new_std_menu(&foo->ctrl_handler, &foo_ctrl_ops,
                V4L2_CID_POWER_LINE_FREQUENCY,
                V4L2_CID_POWER_LINE_FREQUENCY_60HZ, 0,
                V4L2_CID_POWER_LINE_FREQUENCY_DISABLED);
v4l2_ctrl_new_int_menu(&foo->ctrl_handler, &foo_ctrl_ops,
                V4L2_CID_EXPOSURE_BIAS,
                ARRAY_SIZE(exp_bias_qmenu) - 1,
                ARRAY_SIZE(exp_bias_qmenu) / 2 - 1,
                exp_bias_qmenu);
v4l2_ctrl_new_std_menu_items(&foo->ctrl_handler, &foo_ctrl_ops,
                V4L2_CID_TEST_PATTERN, ARRAY_SIZE(test_pattern) - 1, 0,
                0, test_pattern);
...
if (foo->ctrl_handler.error) {
        int err = foo->ctrl_handler.error;

        v4l2_ctrl_handler_free(&foo->ctrl_handler);
        return err;
}

```

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

### Configure and Enable irqsoff Tracer

Source: https://www.kernel.org/doc/html/v4.19/_sources/trace/ftrace.rst.txt

Commands to disable function tracing, enable the irqsoff tracer, and start tracing latency. This setup is used to capture interrupt-related latencies.

```bash
# echo 0 > options/function-trace
# echo irqsoff > current_tracer
# echo 1 > tracing_on
# echo 0 > tracing_max_latency
```

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

### Example: Create and print an ecryptfs encrypted key

Source: https://www.kernel.org/doc/html/v4.19/security/keys/ecryptfs.html

Demonstrates creating a new 'ecryptfs' encrypted key with specific parameters and then printing its contents. The key is added to the user's keyring.

```bash
$ keyctl add encrypted 1000100010001000 "new ecryptfs user:test 64" @u
19184530
```

```bash
$ keyctl print 19184530
ecryptfs user:test 64 490045d4bfe48c99f0d465fbbbb79e7500da954178e2de0697
490045d4bfe48c99f0d465fbbbb79e7500da954178e2de0697
dd85091f5450a0511219e9f7cd70dcd498038181466f78ac8d4c19504fcc72402bfc41c2
f253a41b7507ccaa4b2b03fff19a69d1cc0b16e71746473f023a95488b6edfd86f7fdd40
9d292e4bacded1258880122dd553a661
```

```bash
$ keyctl pipe 19184530 > ecryptfs.blob
```

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

### Starting Video Capture Stream

Source: https://www.kernel.org/doc/html/v4.19/_sources/media/uapi/v4l/capture.c.rst.txt

Initiates the video capture stream using the `VIDIOC_STREAMON` ioctl. This function prepares the device for capturing frames and is called after buffer setup.

```c
static void start_capturing(void)
{
	unsigned int i;
	enum v4l2_buf_type type;

	sswitch (io) {
	case IO_METHOD_READ:
		/* Nothing to do. */
		break;


```

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

### ftrace Function Tail Display (Default)

Source: https://www.kernel.org/doc/html/v4.19/_sources/trace/ftrace.rst.txt

This example shows the default ftrace output where function names are not displayed after the closing bracket if the function's start is not in the trace buffer.

```text
0)               |      putname() {
0)               |        kmem_cache_free() {
0)   0.518 us    |          __phys_addr();
0)   1.757 us    |        }
0)   2.861 us    |      }
```

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

### __v4l2_ctrl_handler_setup

Source: https://www.kernel.org/doc/html/v4.19/media/kapi/v4l2-controls.html

Calls the s_ctrl op for all controls belonging to the handler to initialize hardware.

```APIDOC
## __v4l2_ctrl_handler_setup

### Description
Call the s_ctrl op for all controls belonging to the handler to initialize the hardware to the current control values. The caller is responsible for acquiring the control handler mutex on behalf of `__v4l2_ctrl_handler_setup()`. Button controls will be skipped, as are read-only controls. If **hdl** == NULL, then this just returns 0.

### Parameters
* `struct v4l2_ctrl_handler * hdl` - The control handler.
```

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

### Get Interface for Asynchronous Power Management

Source: https://www.kernel.org/doc/html/v4.19/_sources/driver-api/usb/power-management.rst.txt

Call this function before starting asynchronous I/O operations. It helps synchronize with the PM core and prevents autosuspend if the device needs to be used.

```c
usb_autopm_get_interface_async(intf);
```

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

### Swap Device Binding Example (2-Node System)

Source: https://www.kernel.org/doc/html/v4.19/_sources/vm/swap_numa.rst.txt

Demonstrates how to enable automatic NUMA-aware swap device binding by simply activating swap devices. The system automatically assigns them to the appropriate NUMA nodes.

```bash
# swapon /dev/swapA
# swapon /dev/swapB
```

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

### ether_setup

Source: https://www.kernel.org/doc/html/v4.19/networking/kapi.html

Sets up an Ethernet network device with generic values.

```APIDOC
## ether_setup

### Description
Sets up the fields of the device structure with Ethernet-generic values.

### Parameters
* **_dev_** (struct net_device *) - Network device.
```

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

### Get and Select Default Pin Control State with GPIO Request

Source: https://www.kernel.org/doc/html/v4.19/_sources/driver-api/pinctl.rst.txt

This example shows how a driver can simultaneously acquire a pinctrl handle, select the default pin control state, and request a GPIO. It's crucial to get the pinctrl handle and select the state *before* requesting the GPIO to ensure proper pin muxing and biasing.

```c
#include <linux/pinctrl/consumer.h>
#include <linux/gpio.h>

struct pinctrl *pinctrl;
int gpio;

pinctrl = devm_pinctrl_get_select_default(&dev);
gpio = devm_gpio_request(&dev, 14, "foo");

Here we first request a certain pin state and then request GPIO 14 to be
used. If you're using the subsystems orthogonally like this, you should
nominally always get your pinctrl handle and select the desired pinctrl
state BEFORE requesting the GPIO. This is a semantic convention to avoid
situations that can be electrically unpleasant, you will certainly want to
mux in and bias pins in a certain way before the GPIO subsystems starts to
deal with them.
```

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

### Match Specification Examples

Source: https://www.kernel.org/doc/html/v4.19/_sources/admin-guide/dynamic-debug-howto.rst.txt

Illustrates various ways to use keywords like 'func', 'file', 'module', and 'format' to select specific debug call sites.

```text
func svc_tcp_accept
```

```text
file svcsock.c
```

```text
file kernel/freezer.c
```

```text
file /usr/src/packages/BUILD/sgi-enhancednfs-1.4/default/net/sunrpc/svcsock.c
```

```text
module sunrpc
```

```text
module nfsd
```

```text
format svcrdma:         // many of the NFS/RDMA server pr_debugs
```

```text
format readahead        // some pr_debugs in the readahead cache
```

```text
format nfsd:\040SETATTR // one way to match a format with whitespace
```

```text
format "nfsd: SETATTR"  // a neater way to match a format with whitespace
```

```text
format 'nfsd: SETATTR'  // yet another way to match a format with whitespace
```

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

### Annotate Option Example

Source: https://www.kernel.org/doc/html/v4.19/trace/ftrace.html

Demonstrates the output format when the 'annotate' option is enabled, indicating when a new CPU buffer starts to help interpret trace data across different CPUs.

```text
      <idle>-0     [001] dNs4 21169.031481: wake_up_idle_cpu <-add_timer_on
      <idle>-0     [001] dNs4 21169.031482: _raw_spin_unlock_irqrestore <-add_timer_on
      <idle>-0     [001] .Ns4 21169.031484: sub_preempt_count <-_raw_spin_unlock_irqrestore
```

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

### Example of cgroup-example-interface-file

Source: https://www.kernel.org/doc/html/v4.19/_sources/admin-guide/cgroup-v2.rst.txt

Demonstrates how to read, set default values, and set specific overrides for a keyed interface file in cgroups.

```bash
# cat cgroup-example-interface-file
default 150
8:0 300
```

```bash
# echo 125 > cgroup-example-interface-file
```

```bash
# echo "default 125" > cgroup-example-interface-file
```

```bash
# echo "8:16 170" > cgroup-example-interface-file
```

```bash
# echo "8:0 default" > cgroup-example-interface-file
# cat cgroup-example-interface-file
default 125
8:16 170
```

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

### Stream with Memory Mapping and Overlay

Source: https://www.kernel.org/doc/html/v4.19/media/v4l-drivers/vivid.html

Starts streaming data using memory mapping (mmap) and enables overlay on a vivid instance. This is part of the setup for testing the capture overlay API.

```bash
$ v4l2-ctl -d2 --stream-mmap --overlay=1
```

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

### Qt-Based Configuration

Source: https://www.kernel.org/doc/html/v4.19/_sources/admin-guide/README.rst.txt

Launch the 'make xconfig' command to use a graphical configuration tool based on the Qt framework.

```bash
make xconfig
```

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

### Initialize and Cluster Controls Using Anonymous Struct Pointers

Source: https://www.kernel.org/doc/html/v4.19/media/kapi/v4l2-controls.html

This example shows how to initialize controls for a cluster and then cluster them using pointers derived from an anonymous struct, simplifying the setup process.

```c
state->volume = v4l2_ctrl_new_std(&state->ctrl_handler, ...);
state->mute = v4l2_ctrl_new_std(&state->ctrl_handler, ...);
v4l2_ctrl_cluster(2, &state->volume);

```

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

### Configure and Enable preemptoff Tracer

Source: https://www.kernel.org/doc/html/v4.19/_sources/trace/ftrace.rst.txt

Commands to disable function tracing, enable the preemptoff tracer, and start tracing preemption-disabled periods. This setup is used to capture latencies where preemption is disabled.

```bash
# echo 0 > options/function-trace
# echo preemptoff > current_tracer
# echo 1 > tracing_on
# echo 0 > tracing_max_latency
```

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

### Example /proc/key-users Output

Source: https://www.kernel.org/doc/html/v4.19/_sources/security/keys/core.rst.txt

This example shows the output of the /proc/key-users file, which details tracking data for users with keys on the system, including quota information and statistics.

```text
[root@andromeda root]# cat /proc/key-users
0:     46 45/45 1/100 13/10000
29:     2 2/2 2/100 40/10000
32:     2 2/2 2/100 40/10000
38:     2 2/2 2/100 40/10000
```

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

### Initialization Commands

Source: https://www.kernel.org/doc/html/v4.19/input/devices/iforce-protocol.html

This section details commands used for initializing and configuring the iForce device, including setting control parameters and effect states.

```APIDOC
## Initialization Commands

### Description
Commands for initializing and configuring the device, including setting control parameters and effect states.

#### Set Control

##### Command Format
`OP= 40 <idx> <val> [<val>]`
`LEN= 2 or 3`

##### Parameters
- **idx**: Index of the control parameter.
  - `00`: Set dead zone (0..2048)
  - `01`: Ignore Deadman sensor (0..1)
  - `02`: Enable comm watchdog (0..1)
  - `03`: Set the strength of the spring (0..100)
  - `04`: Enable or disable the spring (0/1)
  - `05`: Set axis saturation threshold (0..2048)
- **val**: Value for the control parameter.

#### Set Effect State

##### Command Format
`OP= 42 <val>`
`LEN= 1`

##### Parameters
- **val**: State value.
  - Bit 3: Pause force feedback
  - Bit 2: Enable force feedback
  - Bit 0: Stop all effects

#### Set Overall Gain

##### Command Format
`OP= 43 <val>`
`LEN= 1`

##### Parameters
- **val**: Gain value.
  - `00`: 0%
  - `40`: 50%
  - `80`: 100%
```

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

### Evdev Device Nodes

Source: https://www.kernel.org/doc/html/v4.19/_sources/input/input.rst.txt

Example device nodes for the generic input event interface (evdev). The minors 64-95 are static legacy, while minors starting from 256 are for systems with more than 32 input devices.

```text
crw-r--r--   1 root     root      13,  64 Apr  1 10:49 event0
crw-r--r--   1 root     root      13,  65 Apr  1 10:50 event1
crw-r--r--   1 root     root      13,  66 Apr  1 10:50 event2
crw-r--r--   1 root     root      13,  67 Apr  1 10:50 event3
...
```

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

### Basic Histogram Trigger Setup

Source: https://www.kernel.org/doc/html/v4.19/_sources/trace/histogram.rst.txt

Sets up a histogram trigger to record 'hitcount' and 'len' based on 'skbaddr.hex' keys. The histogram is sorted by 'hitcount' and has a size of 2048. This is an example of a basic histogram configuration.

```bash
# echo 'hist:keys=skbaddr.hex:vals=hitcount,len:sort=hitcount:size=2048' > \
       /sys/kernel/debug/tracing/events/net/netif_receive_skb/trigger
```

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

### Cross-Compile Local Configuration Example

Source: https://www.kernel.org/doc/html/v4.19/_sources/admin-guide/README.rst.txt

Example demonstrating how to create a 'localmodconfig' for another machine when cross-compiling. It involves saving the target machine's lsmod output and passing it as a parameter.

```bash
target$ lsmod > /tmp/mylsmod
target$ scp /tmp/mylsmod host:/tmp

host$ make LSMOD=/tmp/mylsmod localmodconfig
```

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

### Runtime Pinmuxing Setup and Selection

Source: https://www.kernel.org/doc/html/v4.19/_sources/driver-api/pinctl.rst.txt

Demonstrates how to set up and select different pinmux states at runtime. This involves getting the pin control device, looking up states, and selecting them to change pin functions.

```c
#include <linux/pinctrl/consumer.h>

	struct pinctrl *p;
	struct pinctrl_state *s1, *s2;

	foo_probe()
	{
		/* Setup */
		p = devm_pinctrl_get(&device);
		if (IS_ERR(p))
			...

		s1 = pinctrl_lookup_state(foo->p, "pos-A");
		if (IS_ERR(s1))
			...

		s2 = pinctrl_lookup_state(foo->p, "pos-B");
		if (IS_ERR(s2))
			...
	}

	foo_switch()
	{
		/* Enable on position A */
		ret = pinctrl_select_state(s1);
		if (ret < 0)
		...

		...

		/* Enable on position B */
		ret = pinctrl_select_state(s2);
		if (ret < 0)
		...

		...
	}
```

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

### KDB Kernel Configuration Example

Source: https://www.kernel.org/doc/html/v4.19/dev-tools/kgdb.html

Example kernel configuration settings to enable KDB, including KGDB, serial console, and keyboard input. CONFIG_STRICT_KERNEL_RWX should be disabled for software breakpoints.

```bash
# CONFIG_STRICT_KERNEL_RWX is not set
CONFIG_FRAME_POINTER=y
CONFIG_KGDB=y
CONFIG_KGDB_SERIAL_CONSOLE=y
CONFIG_KGDB_KDB=y
CONFIG_KDB_KEYBOARD=y

```
Tokens:
Raw