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. Security and debugging topics are very related to user and human interactions so are described here too.

Text interfaces

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 peripheral or internal 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 purpose of security is to restrict access across interfaces. 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

⚙️ 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

Namespaces

Linux namespaces provide the way to make tasks work with different objects using the same id. For example same IPC id may refer to different objects or same pid may refer to different tasks when used in different namespaces.

🔧 TODO

⚲ API:

man 8 lsns

man 1 unshare, man 2 unshare

man 1 nsenter, man 2 setns

man 2 clone3, clone_args _id

linux/ns_common.h _inc

linux/proc_ns.h _inc

namespaces definition

uts_namespace _id

ipc_namespace _id

mnt_namespace _id

pid_namespace _id

net/net_namespace.h _inc - struct net

user_namespace _id

time_namespace _id

cgroup_namespace _id

⚙️ Internals:

init_nsproxy _src - struct of namespaces

kernel/nsproxy.c _src

fs/namespace.c _src

fs/proc/namespaces.c _src

net/core/net_namespace.c _src

kernel/time/namespace.c _src

kernel/user_namespace.c _src

kernel/pid_namespace.c _src

kernel/utsname.c _src

kernel/cgroup/namespace.c _src

ipc/namespace.c _src

📚 References:

man 7 namespaces

Control Groups

cgroups feature limits, accounts for, and isolates the resource usage (CPU, memory, disk I/O, network, etc.) of a collection of processes.

There are two versions of cgroups. Unlike v1, cgroup v2 has only a single process hierarchy and discriminates between processes, not threads.

🔧 TODO

⚲ API:

linux/cgroup.h _inc

linux/cgroup-defs.h _inc

linux/cgroup_subsys.h _inc

⚙️ Internals:

kernel/cgroup _src

cgroup_init _id

cgroup2_fs_type _id

📚 References:

Control Group v2 _doc

Control Groups v1 _doc

man 1 systemd-cgtop

man 7 cgroups

man 7 cgroup_namespaces

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

BPF

⚲ API:

man 2 bpf ↪ kernel/bpf/syscall.c _src

📚 References:

BPF _doc

---

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

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

User space debug interfaces

⚲ Interfaces

man 1 dmesg – prints or control the kernel ring buffer

man 2 syslog – system call, which is used to control the kernel printk() buffer

man 1 strace – system calls and signals tracing tool

man 2 ptrace – process trace system call

man 3 klogctl

man 5 core

man 1 perf – performance analysis tools

man 2 perf_event_open – sets up performance monitoring

/sys/kernel/debug/ – debugfs

dmesg --console-level <level>

gdb /usr/src/linux/vmlinux /proc/kcore

dynamic _doc debug

⌨ hands-on:

echo "module atkbd +pfl" | sudo tee /sys/kernel/debug/dynamic_debug/control

⚙️ Internals

handle_sysrq _id

📚 References

Development tools for the kernel _doc

DebugFS _doc, samples/qmi/qmi_sample_client.c _src

Kprobe-based Event Tracing _doc

Dynamic debug _doc

Linux Magic System Request Key Hacks _doc

Magic SysRq key

Tracing and logging

⚲ API:

User-space interface:

man 1 dmesg – prints or control the kernel ring buffer

man 2 syslog – system call, which is used to control the kernel printk() buffer

/proc/kmsg

Most common functions

linux/printk.h _inc

pr_devel _id- conditional debug-level message

pr_debug _id- conditional debug-level or dynamic _doc message

⌨ hands-on:

echo "module atkbd +pfl" | sudo tee /sys/kernel/debug/dynamic_debug/control

Log messages with other levels:

pr_info _id, pr_notice _id, pr_warn _id, pr_err _id, pr_crit _id, pr_alert _id, pr_emerg _id

asm-generic/bug.h _inc

WARN_ON _id

WARN _id

⚙️ Internals

printk _id

kernel/printk/printk.c _src

arch/x86/kernel/traps.c _src

lib/dump_stack.c _src

kernel/trace _src

scripts/tracing/draw_functrace.py _src

logging _ltp, tracing _ltp

samples/ftrace _src

samples/trace_events _src

samples/trace_printk _src

📚 References:

Message logging with printk _doc

Debugging by printing

Linux Tracing Technologies _doc

Function Tracer Design _doc

Tracepoint Analysis _doc

Function Tracer _doc

Using ftrace to hook to functions _doc

Kprobes _doc

Kprobe-based Event Tracing _doc

Uprobe-tracer: Uprobe-based Event Tracing _doc

Using the Linux Kernel Tracepoints _doc

Event Tracing _doc

Subsystem Trace Points: kmem _doc

Subsystem Trace Points: power _doc

NMI Trace Events _doc

In-kernel memory-mapped I/O tracing _doc

Event Histograms _doc

Histogram Design Notes _doc

Boot-time tracing _doc

Hardware Latency Detector _doc

Intel(R) Trace Hub (TH) _doc

Lockless Ring Buffer Design _doc

System Trace Module _doc

CoreSight - ARM Hardware Trace _doc

🔧 TODO. 🚀 advanced features

linux/kmemleak.h _inc – memory leak detector

pr_cont _id- continues a previous log message in the same line

print_hex_dump_bytes _id

print_hex_dump_debug _id

dump_stack _id

CONFIG_PRINTK_CALLER _id

CONFIG_DEBUG_KERNEL _id

CONFIG_DEBUG_INFO _id

kgdb and kdb

⚲ Interfaces

linux/kgdb.h _inc

linux/kdb.h _inc

⚙️ Internals

kernel/debug _src

📚 References

Using kgdb, kdb and the kernel debugger internals _doc

---

📚 References for debugging:

Ramoops oops/panic logger _doc

pstore block oops/panic logger _doc

Fault injection _doc

Bisecting a bug _doc

Development tools for the kernel _doc

linux/tracepoint.h _inc

https://wiki.ubuntu.com/Kernel/Debugging

Linux Applications Debugging Techniques

Multimedia subsystems

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_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 on:

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.

⚲ 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

---

⚙️ Internals:

drivers/media _src