# The Linux Kernel/Human interfaces

* human interfaces
* text interfaces
* security
* debugging
* multimedia subsystems
* human interface devices, input devices
* HI drivers
Welcome to the first article of the book. The article is named after USB class and Linux facility Human Interface Devices (HID). HID facility in Linux supports keyboard, mouse and other input devices. Console, multimedia (or just media), sound (audio), video, graphics also are in the focus of this article. Additionally, this chapter covers security and debugging topics as they are closely linked to user and human interactions.

## Text interfaces

In the world of Linux, a text terminal emulators and consoles are essential components of the operating system that allow users to interact with applications trough kernel. A text terminal is a device that provides a text-based interface for communicating with the kernel, while the console is the physical device that houses the terminal and displays the output of the kernel.
The Linux kernel includes a built-in console driver that provides a basic interface for communicating with the console and controlling the terminal. The console driver also supports various input and output devices, such as keyboards and displays, to enable users to interact with the system through a terminal.
The use of text terminals and system consoles in Linux can be traced back to the early days of computing, when graphical user interfaces were not yet widely available. Despite the widespread adoption of graphical user interfaces, text-based interfaces and consoles remain popular among Linux users and developers for their simplicity, efficiency, and flexibility. Overall, the text terminal and console play a crucial role in the Linux kernel, providing users with a powerful interface for managing and interacting with the operating system.

### Char devices

cdev$_{id}$ – "character device" is a type of device driver that provides an implementation for character device file in the /dev directory. The word "device" here means abstract interface, proxy to a usually peripheral physical device. A character device is a type of device that can be accessed as a stream of bytes, rather than as a block of data like a block device. Cdev drivers are commonly used for devices that provide a stream of data, such as keyboards, mouses, terminals, serial ports, and printers. They are also used for devices that provide access to memory-mapped I/O regions, such as frame buffers and network devices. A cdev driver typically consists of a set of functions that implement the low-level I/O operations for the device, such as open, read and write. These functions are called by the kernel when a user space program accesses the character device file. To create a cdev driver, a kernel developer must first initialize a cdev structure using cdev_init$_{id}$ or cdev_alloc$_{id}$. The cdev structure contains information about the device, such as its major and minor numbers and the set of I/O functions that the driver implements. Once the cdev structure has been initialized, it can be registered with the kernel using the cdev_add$_{id}$ function. This function creates the character device file in the /dev directory and associates it with the cdev driver.
You can find a list of registered char devices on the beginning the listing of /proc/devices. Input devices keyboard and mouse are examples of char devices.
Tip: Browse the cross-referencing site to explore nearby API and use cases
💾 Historical: It is one of the most simple, fundamental and oldest concepts derived from UNIX.
⚲ API
    linux/cdev.h$_{inc}$
       dev_t$_{id}$ - device id consists of MAJOR$_{id}$ and MINOR$_{id}$ numbers
       cdev$_{id}$ - core char device struct
       cdev_init$_{id}$ or cdev_alloc$_{id}$
       cdev_device_add$_{id}$ - helper function, uses
          cdev_add$_{id}$ - common key function to add a char device to the system.
    register_chrdev$_{id}$ - obviously registers char device by major number, name and file operations
    unregister_chrdev$_{id}$
    alloc_chrdev_region$_{id}$ / register_chrdev_region$_{id}$,
    unregister_chrdev_region$_{id}$
    uapi/linux/major.h$_{inc}$ - static definitions of many major numbers, including obsolete.
⚙️ Internals
    fs/char_dev.c$_{src}$
    chrdevs$_{id}$
📖 References
    Char devices$_{doc}$
    Character device drivers, linux-kernel-labs
    Character device files, on opensourceforu
💾 Historical
    LDD3:Char Drivers
    LDD3:Advanced Char Driver Operations
    LDD1:#3
    LDD1:#5

### Text terminals and console

🗝️ Acronyms
    tty - 💾 historically TeleTYpewriter, means just terminal
    pty - pseudoterminal
    pts - pseudoterminal slave
    ptmx - pseudoterminal master
⚲ API
    To find out current terminal:
       readlink /proc/self/fd/0
       man 1 tty
       man 1 who -m
    linux/tty.h$_{inc}$
    register_console$_{id}$ obviously registers console$_{id}$
       👁 example virtio_console$_{id}$
    linux/console.h$_{inc}$
    man 2 ioctl_console
⚙️ Internals
    drivers/tty$_{src}$
    fs/devpts$_{src}$
    fs/proc/proc_tty.c$_{src}$
    drivers/tty/vt/vt.c$_{src}$
📖 References
    man 4 tty – controlling terminal
    man 4 ptmx and pts – pseudoterminal master and slave
    man 7 pty – pseudoterminal interfaces
    console$_{doc}$
💾 Historical
    LDD3:TTY Drivers

## Security

The goal of security is to restrict access through interfaces. From access control and authentication mechanisms to secure boot and memory protection, the Linux kernel employs a variety of techniques to safeguard the system and its users. Basic Linux security is quite simple. It consists of tree ownership classes and tree access modes. One of the most frequently executed functions is may_open$_{id}$. It rejects access of unauthorized users to open a file.
See article Security for new features.

### Authorization

Authorization is the function of specifying access rights/privileges to system resources. The main goal of authorization is prevention of privilege escalation under any circumstances.
🔧 TODO. Keywords: permission, capabilities, ownership, mitigation.
⚲ API
    linux/stat.h$_{inc}$
    uapi/linux/stat.h$_{inc}$
Basic classic UNIX authorization is based on ownership and tree access modes: reading, writing and execution.
Ownership is encoded by owning user id uid_t$_{id}$ and owning group id gid_t$_{id}$.
umode_t$_{id}$ - just typedef used for encoding access mode. S_IRUSR$_{id}$ - minimal "read only by user/owner" access mode. S_IALLUGO$_{id}$ - full access mode. Please read the source for details for other modes.
Binary Access Control Matrix of access modes:
| modes | bits | Read | Write | Execute |
| bit offset | | 2 | 1 | 0 |
| Others | 0-2 | or | ow | ox |
| Group | 3-5 | gr | gw | gx |
| User | 6-8 | ur | uw | ux |
    man 2 chown ↪ do_fchownat$_{id}$ changes ownership for file or directory
    man 2 chmod ↪ do_fchmodat$_{id}$ changes access mode for file or directory
    man 2 access, man 2 faccessat ↪ do_faccessat$_{id}$ checks access rights
Common authorization errors
    EPERM$_{id}$ – "Operation not permitted"
    EACCES$_{id}$ – "Permission denied"
🚀 Advanced features
    man 5 acl posix_acl$_{id}$
    uapi/linux/capability.h$_{inc}$
       man 2 capset and capget – set/get capabilities of thread(s)
       man 3 libcap
    man 1 setpriv – run a program with different privilege settings
⚙️ Internals
    may_open$_{id}$ rejects unauthorized file opening
       inode_permission$_{id}$ checks for access rights to a given inode
    kernel/capability.c$_{src}$
📖 References
    File-system permissions
    man 7 capabilities

### Credentials

🔧 TODO. Keywords: authentication, user IDs, group IDs, Process group ID, session ID.
⚲ API
    uapi/asm-generic/stat.h$_{inc}$
    arch/x86/include/uapi/asm/stat.h$_{src}$
    linux/cred.h$_{inc}$
       struct cred$_{id}$ - the security context of a task
    man 1 id, man 1 test - shell utilities
    man 2 getuid ↪ current_uid$_{id}$
    man 2 getgid
    man 2 geteuid is used by utility man 1 whoami
    Real, effective, and saved user/group IDs:
       man 2 getresuid, getresgid
       man 2 setreuid, setregid
    man 2 setfsuid - set user identity used for filesystem checks
    man 2 umask - sets file mode creation mask
    man 1 stat, man 2 stat ↪ vfs_fstat$_{id}$, vfs_fstatat$_{id}$
    man 2 statx ↪ do_statx$_{id}$
⚙️ Internals
    kstat$_{id}$
    make_kuid$_{id}$ etc
    from_kuid_munged$_{id}$ etc
📖 References
    Credentials in Linux$_{doc}$
    man 7 credentials
    https://www.geeksforgeeks.org/real-effective-and-saved-userid-in-linux/

### Cryptography

🔧 TODO
🗝️ Acronyms
    AES - Advanced Encryption Standard
⚲ API
    AF_ALG$_{id}$ - User Space Interface$_{doc}$
    linux/crypto.h$_{inc}$ - Scatterlist Cryptographic API.
    crypto$_{inc}$
⚙️ Internals
    crypto$_{src}$
    drivers/crypto$_{src}$
    lib/crypto$_{src}$
    arch/x86/crypto$_{src}$
    fs/crypto$_{src}$ - per-file encryption
    fs/ecryptfs$_{src}$ eCrypt FS - Encrypted filesystem that operates on the VFS layer.
    dm-crypt, drivers/md/dm-crypt.c$_{src}$
📖 References
    Linux Kernel Crypto API$_{doc}$
    Crypto API (Linux)
    devicetree/bindings/crypto
    crypto$_{ltp}$

### Audit

    kernel/audit.h$_{src}$
    kernel/audit.c$_{src}$
    kernel/auditsc.c$_{src}$
    kernel/audit_tree.c$_{src}$
    kernel/audit_watch.c$_{src}$
    kernel/audit_fsnotify.c$_{src}$
    kernel/auditfilter.c$_{src}$
📖 References
    https://capsule8.com/blog/auditd-what-is-the-linux-auditing-system/
    https://wiki.archlinux.org/title/Audit_framework
    man 8 auditctl
See also eBPF and BPF
Appendix for Security:
🔧 TODO
    man 2 fcntl ↪ do_fcntl$_{id}$
    man 2 seccomp ↪ do_seccomp$_{id}$
    man 2 add_key ↪ security/keys/keyctl.c$_{src}$
    chroot, man 2 chroot
    Address space layout randomization
       man 8 setarch / man 2 personality
📖 References
    Security$_{doc}$
       LSM - Linux Security Modules$_{doc}$ Perf events and tool security
    Hardware vulnerabilities$_{doc}$
    Linux Security Modules
    linux/security.h$_{inc}$ ⇾ security$_{src}$
    keys$_{inc}$
    linux/verification.h$_{inc}$
    certs$_{src}$
    security$_{ltp}$
    cve$_{ltp}$
    http://kernsec.org/wiki/index.php/Main_Page
    SELinux http://selinuxproject.org/

## Debugging

See Debugging Linux kernel

## Multimedia subsystems

⚙️ Internals
    drivers/media$_{src}$

### Graphics

Old graphics (not to be confused with v4l):
⚲ API
    video$_{inc}$
⚙️ Internals
    drivers/video$_{src}$

#### Direct Rendering Manager (DRM)

DRM is responsible for interfacing with GPUs of modern video cards. DRM exposes an API that user-space programs can use to send commands and data to the GPU and perform operations such as configuring the mode setting of the display. User-space programs can use the DRM API to command the GPU to do hardware-accelerated 3D rendering and video decoding, as well as GPGPU computing.
⚲ API
    /sys/class/drm/
    uapi/drm$_{inc}$
       uapi/drm/drm.h$_{inc}$
          DRM_IOCTL_BASE$_{id}$
          drm_version$_{id}$
⚙️ Internals
    drm$_{inc}$
    drm_gem.h$_{inc}$ – Graphics Execution Manager Driver Interfaces
    drm_dev_register$_{id}$ registers drm_device$_{id}$

### Advanced Linux Sound Architecture (ALSA)

ALSA is a software framework and part of the Linux kernel that provides an API for sound card device drivers. Some of the goals of the ALSA project at its inception were automatic configuration of sound-card hardware and graceful handling of multiple sound devices in a system.
The sound servers PulseAudio, JACK (low-latency professional-grade audio editing and mixing) and PipeWire, the higher-level abstraction APIs OpenAL, SDL audio, etc. work on top of ALSA and implemented sound card device drivers. On Linux systems, ALSA succeeded the older Open Sound System (OSS).
⚲ API
    /proc/asound/cards, /sys/class/sound/
    snd_card$_{id}$ - central struct
    snd_card_new$_{id}$
    snd_card_register$_{id}$
    snd_device_ops$_{id}$
    snd_device_new$_{id}$ creates an ALSA device component
    uapi/sound/asound.h$_{inc}$
    sound/core.h$_{inc}$
⚙️ Internals
    sound$_{src}$
    sound/core/device.c$_{src}$
    See ASoC
📖 References
    ALSA (sound)$_{doc}$
    Writing an ALSA Driver$_{doc}$
    sound$_{ltp}$

### Video4Linux (V4L2)

V4L is a collection of device drivers and an API for supporting realtime video capture on Linux systems. It supports many USB webcams, TV tuners, and related devices, standardizing their output, so programmers can easily add video support to their applications. MythTV, tvtime and Tvheadend are typical applications that use the V4L framework.
⚲ API
    v4l2_device_register$_{id}$ registers v4l2_device$_{id}$
    video_register_device$_{id}$ registers video_device$_{id}$
    👁 examples drivers/media/test-drivers$_{src}$
📖 References
    Video4Linux
    media$_{doc}$
    V4L$_{doc}$
    Media subsystem kernel internal API

## HID

Generic human interface devices. Don't confuse with hiddev.

### Input devices

Input device files are kind of char devices with id INPUT_MAJOR$_{id}$. Classic input devices are keyboard and mouse.
⚲ API
    In shell: cat /proc/bus/input/devices
    linux/input.h$_{inc}$
    devm_input_allocate_device$_{id}$, input_register_device$_{id}$, input_register_handler$_{id}$, input_dev$_{id}$
    input_report_key$_{id}$ input_sync$_{id}$
👁 Examples
    drivers/input/mousedev.c$_{src}$
    drivers/input/keyboard/atkbd.c$_{src}$
    drivers/input/evbug.c$_{src}$
⌨️ Hands onInternals
sudo hexdump /dev/input/mice # dump your mouse movements events from your kernel
⚙️ Internals
    drivers/input/input.c$_{src}$
    input_event$_{id}$
📖 References
    Input$_{doc}$
    input$_{ltp}$

### HID devices

🔧 TODO
⚲ API
    hid_device$_{id}$ - device report descriptor. Operations: hid_allocate_device$_{id}$, hid_add_device$_{id}$ . 👁 Example usbhid_probe$_{id}$
    uapi/linux/hid.h$_{inc}$
    linux/hid.h$_{inc}$

### Camera

🔧 TODO
⚲ API
    uapi/linux/uvcvideo.h$_{inc}$
📖 References
    UVC$_{doc}$
    drivers/media/usb/uvc$_{src}$

## HI device drivers

This section is about low level drivers to human interface peripheral devices.
⚲ HID API
    linux/hidraw.h$_{inc}$
    module_hid_driver$_{id}$ registers hid_driver$_{id}$
    hid_hw_start$_{id}$
⚙️ Internals
    hid_bus_type$_{id}$
    drivers/hid$_{src}$
    drivers/hid/hid-core.c$_{src}$
    drivers/accessibility$_{src}$
    drivers/leds$_{src}$
    samples/uhid/uhid-example.c$_{src}$ - 👁 example of user mode HID driver
    drivers/input$_{src}$ : keyboard & mouse, misc, serio, tablet, touchscreen, gameport, joystick
       ⌨️ Hands on
       echo "module atkbd +pfl" | sudo tee /sys/kernel/debug/dynamic_debug/control
USB HID
⚲ HID API
    USB_INTERFACE_CLASS_HID$_{id}$ == USB_CLASS_HID$_{id}$
⚙️ Internals
    drivers/hid/usbhid$_{src}$
       drivers/hid/usbhid/usbkbd.c$_{src}$: usb_kbd_driver$_{id}$
       drivers/hid/usbhid/usbmouse.c$_{src}$: usb_mouse_driver$_{id}$
📖 References
    USB HID class$_{doc}$

### Graphics

🔧 TODO
🗝️ Acronyms
    FB - Framebuffer
    GPU - Graphics processing unit
    TFT (LCD) - Thin-film-transistor liquid-crystal display used for 🤖 embedded devices
    MIPI - 📱 Mobile Industry Processor Interface
       DBI - Display Bus Interface
       DSI - Display Serial Interface
       DCS - The Display Command Set
⚲ API
    cat /proc/fb
    ls -l /sys/class/graphics
    video/mipi_display.h$_{inc}$
    linux/fb.h$_{inc}$
    register_framebuffer$_{id}$
    FBTFT_REGISTER_DRIVER$_{id}$
    fbtft_display$_{id}$
⚙️ Internals
    drivers/video$_{src}$
    drivers/gpu$_{src}$
👁 Examples
    vivid_fb_init$_{id}$
    fbtft_register_framebuffer$_{id}$
📖 References
    GPU Driver Developer’s Guide$_{doc}$
    The Frame Buffer Device$_{doc}$
    Frame Buffer Library$_{doc}$
    LWN: Graphics

### Sound SoC - ASoC

ALSA System on Chip (ASoC) layer for or 🤖 embedded systems. ASoC is designed to handle complex audio processing and routing on low-power and resource-constrained systems, making it an ideal solution for embedded devices such as smartphones, tablets, and other IoT devices.
ASoC provides a comprehensive framework for audio drivers, enabling the creation of modular audio drivers that can be easily integrated with the rest of the kernel. It also supports a wide range of audio interfaces, including I2S, PCM, AC97, and SPDIF, making it highly versatile and capable of handling a variety of audio formats.
One of the key features of ASoC is its ability to handle audio routing and processing using Digital Signal Processing (DSP) techniques.
This enables ASoC to support advanced audio features such as noise reduction, echo cancellation, and dynamic range compression, among others.
Overall, ASoC is a powerful and flexible subsystem that enables Linux to support a wide range of audio hardware in embedded devices. It has become an essential component of many embedded Linux distributions and is widely used in the development of modern audio-enabled devices.
⚲ API
    sound/soc.h$_{inc}$
       snd_soc_card$_{id}$
          is registered by devm_snd_soc_register_card$_{id}$ ⇾ snd_soc_register_card$_{id}$
    sound/soc-component.h$_{inc}$
       snd_soc_component$_{id}$
          snd_soc_component_driver$_{id}$
          snd_soc_card$_{id}$
             snd_card$_{id}$
       snd_soc_register_component$_{id}$ snd_soc_component_get_drvdata$_{id}$ snd_soc_component_read$_{id}$ snd_soc_component_update_bits$_{id}$ snd_soc_component_write$_{id}$
    sound/soc-dai.h$_{inc}$ - DAI - Digital Audio Interface$_{doc}$: AC97, I2S, PCM
       snd_soc_dai$_{id}$ snd_soc_dai_driver$_{id}$ snd_soc_dai_get_drvdata$_{id}$
    sound/soc-dpcm.h$_{inc}$ - DPCM - Dynamic PCM$_{doc}$
    sound/soc-dapm.h$_{inc}$ - DAPM - Dynamic Audio Power Management$_{doc}$
       snd_soc_dapm_route$_{id}$, snd_soc_dapm_to_component$_{id}$, snd_soc_dapm_widget$_{id}$
👁 Examples
    sound/soc/generic/simple-card.c$_{src}$
    sound/soc/generic/audio-graph-card.c$_{src}$ uses sound/graph_card.h$_{inc}$
⚙️ Internals
    sound/soc$_{src}$
    snd_soc_card$_{id}$
       snd_soc_dai_link$_{id}$
📖 References
    ASoC - ALSA SoC Layer$_{doc}$
    ASoC Core API$_{doc}$
    https://www.alsa-project.org/wiki/ASoC
       https://www.alsa-project.org/wiki/DAPM
🗝️ Acronyms SAI could be
    STM Serial Audio Interface: sound/soc/stm/stm32_sai.h$_{src}$
    Freescale (FSL) Synchronous Audio Interface: sound/soc/fsl/fsl_sai.h$_{src}$