torvalds/linux

Block layer

Purpose

block/ is the layer between filesystems and storage drivers. It receives struct bio (block I/O) from filesystems, batches and reorders them in a multi-queue request scheduler, and submits them to driver queues. It also provides the cgroup blkio controller, the I/O priority subsystem, integrity (T10/PI) plumbing, and inline encryption.

Directory layout

block/
├── bio.c, bdev.c, fops.c, genhd.c, ioctl.c, ioprio.c, holder.c
├── blk-core.c, blk-mq.c, blk-mq-*.c, blk.h        # Multi-queue request layer
├── blk-flush.c, blk-merge.c, blk-map.c, blk-pm.c, blk-settings.c, blk-stat.c, blk-timeout.c, blk-zoned.c, blk-lib.c, blk-rq-qos.c
├── blk-cgroup*.c                                   # Block cgroup controller
├── blk-throttle.c, blk-iolatency.c, blk-ioprio.c, blk-iocost.c, blk-wbt.c
├── blk-crypto.c, blk-crypto-*.c                    # Inline encryption
├── blk-ia-ranges.c                                 # Independent access ranges
├── elevator.c, elevator.h                          # Elevator (I/O scheduler) framework
├── bfq-iosched.c, bfq-cgroup.c, bfq-wf2q.c         # BFQ scheduler
├── kyber-iosched.c                                 # Kyber scheduler
├── mq-deadline.c                                   # MQ-deadline scheduler
├── badblocks.c                                     # Bad-block tracking
├── bio-integrity.c, bio-integrity-fs.c, bio-integrity-auto.c, t10-pi.c   # Integrity (T10/PI)
├── disk-events.c, early-lookup.c, holder.c
├── partitions/                                      # Partition table parsers
├── bsg.c, bsg-lib.c                                # SCSI generic
└── opal_proto.h, sed-opal.c                        # OPAL self-encrypting drives

Key abstractions

Symbol	File	Purpose
`struct bio`	`include/linux/blk_types.h`, `block/bio.c`	Block I/O descriptor — scatter/gather list of pages plus metadata.
`struct request`	`include/linux/blkdev.h`, `block/blk-mq.c`	A request to the driver, possibly built from multiple bios.
`struct request_queue`	`include/linux/blkdev.h`	A device's queue.
`struct blk_mq_tag_set`, `struct blk_mq_hw_ctx`	`include/linux/blk-mq.h`	Per-device tag set and per-CPU hardware context.
`struct gendisk`	`include/linux/blkdev.h`, `block/genhd.c`	A disk device exposed to user space (`/dev/sda`, `/dev/nvme0n1`).
`struct block_device` (`bdev`)	`block/bdev.c`	A specific partition or whole-disk view used by the file layer.
`struct blkcg`, `blkcg_policy`	`block/blk-cgroup.c`	Block cgroup controller plumbing.
`struct elevator_type`	`block/elevator.c`	I/O scheduler vtable.

How it works

graph TD
    FS[Filesystem submits bio] --> SUBMIT[submit_bio in block/bio.c]
    SUBMIT --> MQ[blk-mq: build request]
    MQ -->|optionally| SCHED[Elevator: bfq / kyber / mq-deadline / none]
    SCHED --> HCTX[blk_mq_hw_ctx run_hw_queue]
    HCTX --> DRIVER[Driver queue_rq]
    DRIVER -->|hardware completion| COMPL[blk_mq_complete_request]
    COMPL -->|"end_io"| FS

blk-mq

The multi-queue block layer (blk-mq) replaced the single-queue legacy code (~3.13, 2014). Each device has a tag set, multiple software queues (per-CPU or per-NUMA), and one or more hardware queues backed by the driver. This scales linearly with cores on modern NVMe SSDs.

Per-device shape:

blk_mq_tag_set — pool of request tags shared by hctxs.
blk_mq_hw_ctx (hctx) — one per hardware queue. Drivers pull requests from here.
blk_mq_ctx — software queue per CPU, feeding requests into a hctx.

I/O schedulers

Pluggable via /sys/block/<dev>/queue/scheduler:

none — no scheduler; pass requests straight to the driver. Default for fast NVMe.
mq-deadline (block/mq-deadline.c) — deadline-style with reads prioritized.
kyber (block/kyber-iosched.c) — token-bucket latency-aware.
BFQ (block/bfq-iosched.c, bfq-wf2q.c, bfq-cgroup.c) — Budget Fair Queueing, fairness-oriented, good for desktop.

Block cgroup

block/blk-cgroup.c plus per-policy files:

blk-throttle.c — bandwidth/IOPS limits (io.max).
blk-iolatency.c — latency-driven throttling (io.latency).
blk-iocost.c — proportional weight via cost model (io.cost.qos, io.weight).
blk-ioprio.c — propagating ioprio to cgroups.

Writeback throttling

block/blk-wbt.c throttles background writeback to prevent it from harming latency of foreground reads.

Integrity and inline encryption

bio integrity (bio-integrity*.c, t10-pi.c) — protect data with T10 Protection Information checksums end-to-end.
inline encryption (blk-crypto*.c) — fscrypt-managed keys offloaded to hardware (UFS, eMMC) when available. Falls back to a software path.

fs/: every filesystem submits bios via submit_bio().
drivers/nvme/, drivers/scsi/, drivers/ata/, drivers/block/: the actual device drivers.
drivers/md/: device-mapper and MD RAID stack on top of and below block/.
kernel/cgroup/: block cgroup is a v2 controller registered here.
mm/: writeback (fs-writeback.c) issues bios.
crypto/: blk-crypto-fallback for inline encryption.

Key source files

File	Purpose
`block/blk-core.c`	`submit_bio`, lifecycle.
`block/blk-mq.c`	Multi-queue dispatch.
`block/bio.c`	bio allocator, mempool, splitter.
`block/genhd.c`	gendisk lifecycle, sysfs registration.
`block/bdev.c`	block_device cache, lookup, bd_holder.
`block/elevator.c`	Scheduler framework.
`block/blk-cgroup.c`	blkcg core.
`block/blk-mq-sched.c`	scheduler-mq glue.
`block/fops.c`	`file_operations` for raw block devices.
`block/blk-zoned.c`	Zoned-block support.
`block/blk-crypto.c`	Inline encryption.

Entry points for modification

Implementing a new block driver: register a blk_mq_ops and a blk_mq_tag_set. Examples: drivers/block/null_blk/, drivers/block/nbd.c, drivers/nvme/host/.
New I/O scheduler: implement struct elevator_type. There are very few, and the bar is high — read the BFQ paper and existing schedulers.
New cgroup policy: implement a blkcg_policy. See blk-iolatency.c as a small example.
New bio annotation flag: extend enum req_flag_bits.

Filesystems — where bios come from.
Drivers — drivers/nvme, drivers/scsi, drivers/ata, drivers/md.
Memory management — writeback path.

Built by Factory AutoWiki from public repository content. It is a generated preview for codebase exploration, not source-maintained documentation.