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

Word "device" usually means abstract interface, proxy to a peripheral or internal physical device. A character device file is a file-like sequential access interface. This kind of devices is used in many facilities from keyboard input to default interface for a sophisticated new 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.

Common key function cdev_add _id adds a char device to the system.

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

• include/linux/console.h _src
• 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
• man 7 pty
• 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

---

Appendix for Security:

🔧 TODO:

• man 2 fcntl ↪ do_fcntl _id
• man 2 seccomp ↪ do_seccomp _id
• man 2 bpf ↪ kernel/bpf/syscall.c _src
• 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 1 strace traces system calls and signals
• man 2 ptrace process trace
• man 2 syslog
• man 3 klogctl
• man 5 core
• /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
• Kprobe-based Event Tracing _doc
• Dynamic debug _doc
• Linux Magic System Request Key Hacks _doc
• Magic SysRq key

Printing to log

Most common functions

• 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_crit _id, pr_alert _id, pr_emerg _id

🔧 TODO. 🚀 advanced features

• pr_cont _id- continues a previous log message in the same line
• print_hex_dump_bytes _id
• print_hex_dump_debug _id
• linux/printk.h _inc
• dump_stack _id

📚 References:

• Message logging with printk _doc
• Debugging by printing

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

Tracing and logging

📚 References:

• 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
• logging _ltp, tracing _ltp
• samples/ftrace _src
• samples/trace_events _src
• samples/trace_printk _src

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/
• drm _inc
• uapi/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_dev _id
• input_report_key _id input_sync _id

👁 Examples:

• drivers/input/mousedev.c _src
• drivers/input/keyboard/atkbd.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
• 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

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