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[edit | edit source]
Char devices[edit | edit source]
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:
π References:
- Char devices doc
- Character device drivers, linux-kernel-labs
- Character device files, on opensourceforu
πΎ Historical
Text terminals and console[edit | edit source]
ποΈ Acronyms:
- tty - πΎ historically TeleTYpewriter, means just terminal
- pty - pseudoterminal
- pts - pseudoterminal slave
- ptmx - pseudoterminal master
β² API:
- To find out current terminal:
- 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:
π References:
πΎ Historical:
Security[edit | edit source]
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[edit | edit source]
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:
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:
π 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:
Credentials[edit | edit source]
π§ 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[edit | edit source]
π§ TODO
ποΈ Acronyms:
β² 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:
Namespaces[edit | edit source]
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
βοΈ 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:
Control Groups[edit | edit source]
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:
βοΈ Internals:
π References:
- Control Group v2 doc
- Control Groups v1 doc
- man 1 systemd-cgtop
- man 7 cgroups
- man 7 cgroup_namespaces
Audit[edit | edit source]
- 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
π References:
- Security 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[edit | edit source]
User space debug interfaces[edit | edit source]
β² 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
π 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[edit | edit source]
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:
π§ 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:
βοΈ 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[edit | edit source]
π 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[edit | edit source]
β² Interfaces
βοΈ Internals
π References
π 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[edit | edit source]
Graphics[edit | edit source]
Old graphics (not to be confused with v4l):
β² API:
βοΈ Internals:
Direct Rendering Manager (DRM)[edit | edit source]
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)[edit | edit source]
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:
π References:
Video4Linux (V4L2)[edit | edit source]
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
HID[edit | edit source]
Generic human interface devices. Don't confuse with hiddev.
Input devices[edit | edit source]
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:
β¨ Hands on:
sudo hexdump /dev/input/mice # dump your mouse movements events from your kernel
βοΈ Internals:
π References
HID devices[edit | edit source]
π§ 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[edit | edit source]
π§ TODO
β² API:
π References
HI device drivers[edit | edit source]
This section is about low level drivers to human interface peripheral devices.
β² HID API:
βοΈ 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:
βοΈ Internals:
π References
Graphics[edit | edit source]
π§ 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
π Examples:
π References:
Sound SoC - ASoC[edit | edit source]
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
- snd_soc_card id
- sound/soc-component.h inc
- sound/soc-dpcm.h inc - DPCM - Dynamic PCM doc
- sound/soc-dapm.h inc - DAPM - Dynamic Audio Power Management doc
π Examples:
- sound/soc/generic/simple-card.c src
- sound/soc/generic/audio-graph-card.c src uses sound/graph_card.h inc
βοΈ Internals:
π References:
ποΈ 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: