Linux 内核之旅（二十四）：内核视角下的IO读写（四）

static const struct address_space_operations ext4_aops = {
	.readpage		= ext4_readpage,
	.readpages		= ext4_readpages,
	.writepage		= ext4_writepage,
	.writepages		= ext4_writepages,
	.write_begin		= ext4_write_begin,
	.write_end		= ext4_write_end,
  ......
};

static const struct address_space_operations ext4_journalled_aops = {
	.readpage		= ext4_readpage,
	.readpages		= ext4_readpages,
	.writepage		= ext4_writepage,
	.writepages		= ext4_writepages,
	.write_begin		= ext4_write_begin,
	.write_end		= ext4_journalled_write_end,
  ......
};

// https://elixir.bootlin.com/linux/v4.11.6/source/fs/ext4/inode.c#L3779
static const struct address_space_operations ext4_da_aops = {
	.readpage		= ext4_readpage,
	.readpages		= ext4_readpages,
	.writepage		= ext4_writepage,
	.writepages		= ext4_writepages,
	.write_begin		= ext4_da_write_begin,
	.write_end		= ext4_da_write_end,
  ......
};

// https://elixir.bootlin.com/linux/v4.11.6/source/include/linux/fs.h#L310
struct kiocb {
    struct file     *ki_filp;       // 关联的 file 结构
    loff_t          ki_pos;         // 当前读写位置
    void (*ki_complete)(struct kiocb *iocb, long ret, long ret2);
    void            *private;
    int             ki_flags;       // IOCB_DIRECT / IOCB_DSYNC / IOCB_SYNC 等标志
};

// https://elixir.bootlin.com/linux/v4.11.6/source/include/linux/uio.h#L36
struct iov_iter {
    int type;               // 迭代器类型（READ/WRITE）和缓冲区类型（ITER_IOVEC/ITER_KVEC/ITER_BVEC）
    size_t iov_offset;      // 当前 iovec 段内的偏移
    size_t count;           // 剩余待处理的总字节数
    union {
        const struct iovec *iov;    // 用户态缓冲区数组
        const struct kvec *kvec;    // 内核态缓冲区数组
        const struct bio_vec *bvec; // 块设备 I/O 向量
    };
    unsigned long nr_segs;  // 缓冲区段数
};

// https://elixir.bootlin.com/linux/v4.11.6/source/include/linux/fs.h#L433
struct address_space {
    struct inode        *host;          // 所属的 inode
    struct radix_tree_root page_tree;   // 基数树，索引所有缓存页
    spinlock_t          tree_lock;      // 保护 page_tree
    atomic_t            i_mmap_writable;// 可写 mmap 的计数
    struct rb_root      i_mmap;         // 映射该 address_space 的 VMA 红黑树
    unsigned long       nrpages;        // 总页数
    const struct address_space_operations *a_ops;  // 操作方法表
    // ...
};

// https://elixir.bootlin.com/linux/v4.11.6/source/fs/read_write.c#L564
SYSCALL_DEFINE3(write, unsigned int, fd, const char __user *, buf,
        size_t, count)
{
    struct fd f = fdget_pos(fd);    // 通过 fd 查找 struct file，同时获取文件位置锁
    ssize_t ret = -EBADF;

    if (f.file) {
        loff_t pos = file_pos_read(f.file);     // 读取当前文件偏移 f_pos
        ret = vfs_write(f.file, buf, count, &pos);
        if (ret >= 0)
            file_pos_write(f.file, pos);         // 写入成功，更新 f_pos
        fdput_pos(f);                            // 释放引用
    }

    return ret;
}

static inline void file_pos_write(struct file *file, loff_t pos)
{
	file->f_pos = pos;
}

// https://elixir.bootlin.com/linux/v4.11.6/source/fs/read_write.c#L520
ssize_t vfs_write(struct file *file, const char __user *buf, size_t count, loff_t *pos)
{
    ssize_t ret;

    if (!(file->f_mode & FMODE_WRITE))      // 检查文件是否以写模式打开
        return -EBADF;
    if (!(file->f_mode & FMODE_CAN_WRITE))   // 检查文件是否支持写操作
        return -EINVAL;
    if (unlikely(!access_ok(VERIFY_READ, buf, count)))  // 校验用户空间缓冲区地址合法性
        return -EFAULT;

    ret = rw_verify_area(WRITE, file, pos, count);  // LSM 安全检查 + 强制锁检查
    if (!ret) {
        if (count > MAX_RW_COUNT)
            count = MAX_RW_COUNT;            // 单次写入上限 MAX_RW_COUNT（2G - 1 页）
        file_start_write(file);              // 获取 sb_writers 信号量，防止文件系统 freeze 期间写入
        ret = __vfs_write(file, buf, count, pos);
        if (ret > 0) {
            fsnotify_modify(file);           // 通知 inotify/fanotify 监控
            add_wchar(current, ret);         // 更新进程的写入字节统计
        }
        inc_syscw(current);                  // 更新进程的系统调用写计数
        file_end_write(file);                // 释放 sb_writers 信号量
    }

    return ret;
}

// https://elixir.bootlin.com/linux/v4.11.6/source/fs/read_write.c#L504
ssize_t __vfs_write(struct file *file, const char __user *p, size_t count,
            loff_t *pos)
{
    if (file->f_op->write)
        return file->f_op->write(file, p, count, pos);  // 旧式接口（已不推荐）
    else if (file->f_op->write_iter)
        return new_sync_write(file, p, count, pos);      // 新式迭代器接口（ext4_file_write_iter）
    else
        return -EINVAL;
}

//ext4 文件系统的定义
const struct file_operations ext4_file_operations = {
  ......
	.write_iter	= ext4_file_write_iter, //只实现了write_iter方法
	.mmap		= ext4_file_mmap,
	.open		= ext4_file_open,
	.fsync		= ext4_sync_file,
	.get_unmapped_area = thp_get_unmapped_area,
	.splice_read	= generic_file_splice_read,
	.splice_write	= iter_file_splice_write,
  ......
};

// https://elixir.bootlin.com/linux/v4.11.6/source/fs/read_write.c#L474
static ssize_t new_sync_write(struct file *filp, const char __user *buf,
                              size_t len, loff_t *ppos)
{
    // 将用户空间缓冲区地址和长度封装为 iovec

    // 注意：用户空间的缓冲区地址buf是保存在iov中的
    // 该结构体对象记录了用户空间缓冲区地址buf和所要写的字节数len
    struct iovec iov = { .iov_base = (void __user *)buf, .iov_len = len };
    struct kiocb kiocb;
    struct iov_iter iter;
    ssize_t ret;

    init_sync_kiocb(&kiocb, filp);      // 初始化同步 IO 控制块，关联 file
    kiocb.ki_pos = *ppos;               // 设置写入起始位置

    // 将 iovec 封装为迭代器，type = WRITE | ITER_IOVEC
    iov_iter_init(&iter, WRITE, &iov, 1, len);

    // 调用文件系统的 write_iter 方法，对 ext4 即 ext4_file_write_iter
    ret = call_write_iter(filp, &kiocb, &iter);
    BUG_ON(ret == -EIOCBQUEUED);         // 同步 IO 不应返回排队状态
    if (ret > 0)
        *ppos = kiocb.ki_pos;            // 更新文件偏移
    return ret;
}

// https://elixir.bootlin.com/linux/v4.11.6/source/fs/ext4/file.c#L691
const struct file_operations ext4_file_operations = {
    .llseek     = ext4_llseek,
    .read_iter  = generic_file_read_iter,       // 读：使用通用实现
    .write_iter = ext4_file_write_iter,         // 写：ext4 自定义实现
    .unlocked_ioctl = ext4_ioctl,
    .mmap       = ext4_file_mmap,
    .open       = ext4_file_open,
    .release    = ext4_release_file,
    .fsync      = ext4_sync_file,
    .get_unmapped_area = thp_get_unmapped_area,
    .splice_read    = generic_file_splice_read,
    .splice_write   = iter_file_splice_write,
    .fallocate  = ext4_fallocate,
};

// https://elixir.bootlin.com/linux/v4.11.6/source/fs/ext4/file.c#L203
static ssize_t
ext4_file_write_iter(struct kiocb *iocb, struct iov_iter *from)
{
    struct inode *inode = file_inode(iocb->ki_filp);
    int o_direct = iocb->ki_flags & IOCB_DIRECT;
    int unaligned_aio = 0;
    int overwrite = 0;
    ssize_t ret;

    // 检查文件系统是否被强制关闭（如磁盘故障触发的 shutdown）
    if (unlikely(ext4_forced_shutdown(EXT4_SB(inode->i_sb))))
        return -EIO;

    /*
     * 获取 inode 的 i_rwsem 写锁，保护并发写操作。
     * 在 4.11.6 中 inode_lock 就是 mutex_lock(&inode->i_mutex)
     * (此版本 i_rwsem 已替代旧的 i_mutex，但语义相同：写独占)
     */
    inode_lock(inode);
    ret = generic_write_checks(iocb, from);  // 通用写入检查：文件大小限制、append 模式处理等
    if (ret <= 0)
        goto out;

    /*
     * 如果 inode 设置了 EXTENTS 标志但文件系统不支持 extent，
     * 或者遇到 inline data 的情况，需要特殊处理
     */
    if (o_direct) {
        /* Direct I/O 路径的特殊处理 */

        // 检测非对齐的异步 DIO：如果写入的偏移或长度不是块大小对齐的，
        // 且是异步 IO，则降级为同步处理（避免部分块写的复杂性）
        if (ext4_test_inode_flag(inode, EXT4_INODE_EXTENTS) &&
            !is_sync_kiocb(iocb) &&
            (iocb->ki_pos & (inode->i_sb->s_blocksize - 1) ||
             iov_iter_count(from) & (inode->i_sb->s_blocksize - 1))) {
            unaligned_aio = 1;
            inode_dio_wait(inode);  // 等待所有正在进行的 DIO 完成
        }

        /*
         * overwrite 检测：如果写入范围完全在已分配块内（不需要新分配块），
         * 则标记为 overwrite。overwrite 模式下可以降低锁粒度提升并发性能
         */
        // 通过 ext4_map_blocks 检查写入范围是否已分配 ...
    }

    ret = __generic_file_write_iter(iocb, from);

    inode_unlock(inode);

    if (ret > 0)
        ret = generic_write_sync(iocb, ret);    // 仅在 O_SYNC/O_DSYNC 模式下触发同步刷盘（详见 0x09 节）

    return ret;

out:
    inode_unlock(inode);
    return ret;
}

// https://elixir.bootlin.com/linux/v4.11.6/source/mm/filemap.c#L2874
ssize_t __generic_file_write_iter(struct kiocb *iocb, struct iov_iter *from)
{
    struct file *file = iocb->ki_filp;
    struct address_space *mapping = file->f_mapping;
    struct inode *inode = mapping->host;
    ssize_t written = 0;
    ssize_t err;
    ssize_t status;

    /* 关联当前进程的 backing_dev_info，用于 writeback 的脏页限流 */
    current->backing_dev_info = inode_to_bdi(inode);

    err = file_remove_privs(file);      // 写入时清除 setuid/setgid 位（安全考量）
    if (err)
        goto out;

    err = file_update_time(file);       // 更新 mtime（修改时间）和 ctime（变更时间）
    if (err)
        goto out;

    if (iocb->ki_flags & IOCB_DIRECT) {
        /* Direct I/O 路径 */
        loff_t pos, endbyte;

        written = generic_file_direct_write(iocb, from);
        /*
         * DIO 可能回退到 buffered write（当写入范围包含空洞时）
         * 如果 DIO 写了部分数据，继续用 buffered 写剩余部分
         */
        if (written < 0 || !iov_iter_count(from) ||
            IS_DAX(inode))
            goto out;

        // 内联赋值 pos = iocb->ki_pos：DIO 已推进 ki_pos，从当前偏移开始 buffered 补写
        // 同时把该起点记入 pos，供下方计算 endbyte 及失效 page cache 范围使用
        status = generic_perform_write(file, from, pos = iocb->ki_pos);
        if (unlikely(status < 0)) {
            err = status;
            goto out;
        }
        iocb->ki_pos += status;
        written += status;

        /*
         * DIO 回退到 buffered 后需要使 page cache 中相关页面失效，
         * 确保后续 DIO 读不会读到过期的缓存数据
         */
        endbyte = pos + status - 1;
        err = filemap_write_and_wait_range(mapping, pos, endbyte);
        if (err == 0) {
            invalidate_mapping_pages(mapping,
                         pos >> PAGE_SHIFT,
                         endbyte >> PAGE_SHIFT);
        }
    } else {
        /* Buffered I/O 路径（默认） */
        written = generic_perform_write(file, from, iocb->ki_pos);
        if (likely(written > 0))
            iocb->ki_pos += written;     // 更新 kiocb 中的文件偏移
    }

out:
    current->backing_dev_info = NULL;
    return written ? written : err;
}
EXPORT_SYMBOL(__generic_file_write_iter);

// https://elixir.bootlin.com/linux/v4.11.6/source/mm/filemap.c#L2784
ssize_t generic_perform_write(struct file *file,
                struct iov_iter *i, loff_t pos)
{
    struct address_space *mapping = file->f_mapping;
    const struct address_space_operations *a_ops = mapping->a_ops;
    long status = 0;
    ssize_t written = 0;
    unsigned int flags = 0;

    if (!iter_is_iovec(i))
        flags |= AOP_FLAG_UNINTERRUPTIBLE;  // 内核空间拷贝不可中断（NFSD 是主要用户）

    //由于可能要写多页，所以需要一个大的循环进行处理
    do {
        struct page *page;
        unsigned long offset;   // 页内偏移
        unsigned long bytes;    // 本次写入字节数（不超过页内剩余空间）
        size_t copied;          // 实际拷贝的字节数
        void *fsdata;

        /* 计算页内偏移和本次写入字节数 */
        offset = (pos & (PAGE_SIZE - 1));   // pos 对 PAGE_SIZE 取模
        bytes = min_t(unsigned long, PAGE_SIZE - offset,
                        iov_iter_count(i));

again:
        /*
         * 预先触发用户页面的缺页异常。如果不这样做，后续在持有页锁的情况下
         * 执行 copy_from_user 可能触发缺页，而缺页处理可能需要获取同一个页锁
         * （当用户缓冲区恰好 mmap 到同一文件时），导致 ABBA 死锁
         */
        if (unlikely(iov_iter_fault_in_readable(i, bytes))) {
            status = -EFAULT;
            break;
        }

        if (fatal_signal_pending(current)) {
            status = -EINTR;
            break;
        }

        /* step1： write_begin：准备页面（分配/查找缓存页，准备 buffer_head） */
        status = a_ops->write_begin(file, mapping, pos, bytes, flags,
                        &page, &fsdata);
        if (unlikely(status < 0))
            break;

        /* 如果该页面被用户空间 mmap 了，刷新 dcache 保证一致性 */
        if (mapping_writably_mapped(mapping))
            flush_dcache_page(page);

        /* step2：数据拷贝：将用户数据原子地拷贝到内核页 */
        copied = iov_iter_copy_from_user_atomic(page, i, offset, bytes);
        flush_dcache_page(page);

        /* step3：write_end：完成写入（更新元数据、标记脏页） */
        status = a_ops->write_end(file, mapping, pos, bytes, copied,
                        page, fsdata);
        if (unlikely(status < 0))
            break;
        copied = status;

        cond_resched();     // 主动让出 CPU，避免长时间占用（大文件写入时）

        iov_iter_advance(i, copied);    // 推进迭代器
        if (unlikely(copied == 0)) {
            /*
             * 如果一个字节都没拷贝成功，说明用户页面可能跨段边界。
             * 缩小为单段长度重试，避免活锁
             */
            bytes = min_t(unsigned long, PAGE_SIZE - offset,
                        iov_iter_single_seg_count(i));
            goto again;
        }
        pos += copied;
        written += copied;

        /*
         * 脏页限流：如果系统中脏页比例超过阈值（dirty_ratio），
         * 当前进程会被阻塞在此处，直到 writeback 线程回写了足够的脏页。
         * 这是内核防止 OOM 的重要背压机制
         */
        balance_dirty_pages_ratelimited(mapping);
    } while (iov_iter_count(i));

    return written ? written : status;
}

// https://elixir.bootlin.com/linux/v4.11.6/source/fs/ext4/inode.c#L3093
static int ext4_da_write_begin(struct file *file, struct address_space *mapping,
                loff_t pos, unsigned len, unsigned flags,
                struct page **pagep, void **fsdata)
{
    int ret, retries = 0;
    struct page *page;
    pgoff_t index;
    struct inode *inode = mapping->host;
    handle_t *handle;

    index = pos >> PAGE_SHIFT;  // 将文件偏移转换为页号

    // ...trim len to not cross page boundary...

retry_grab:
    /* 在 Page Cache 中查找或分配页面 */
    page = grab_cache_page_write_begin(mapping, index, flags);
    if (!page)
        return -ENOMEM;
    unlock_page(page);

    /*
     * 开启 JBD2 事务 handle。延迟分配模式下，write_begin 阶段主要操作的
     * 是元数据（extent status tree 的更新），所以需要日志保护
     */
retry_journal:
    handle = ext4_journal_start(inode, EXT4_HT_WRITE_PAGE,
                ext4_da_write_credits(inode, pos, len));
    if (IS_ERR(handle)) {
        put_page(page);
        return PTR_ERR(handle);
    }

    lock_page(page);
    if (page->mapping != mapping) {
        /* 页面在重新获取锁之前被截断了，重试 */
        unlock_page(page);
        put_page(page);
        ext4_journal_stop(handle);
        goto retry_grab;
    }

    /* 准备 buffer_head 并预留延迟分配空间 */
    ret = __block_write_begin(page, pos, len, ext4_da_get_block_prep);
    if (ret < 0) {
        unlock_page(page);
        ext4_journal_stop(handle);
        if (ret == -ENOSPC &&
            ext4_should_retry_alloc(inode->i_sb, &retries))
            goto retry_journal;
        put_page(page);
        return ret;
    }

    *pagep = page;
    return ret;
}

// https://elixir.bootlin.com/linux/v4.11.6/source/lib/iov_iter.c#L763
size_t iov_iter_copy_from_user_atomic(struct page *page,
        struct iov_iter *i, unsigned long offset, size_t bytes)
{
    char *kaddr = kmap_atomic(page), *p = kaddr + offset;
    iterate_all_kinds(i, bytes, v,
        copyin((p += v.iov_len) - v.iov_len, v.iov_base, v.iov_len),
        memcpy_from_page((p += v.bv_len) - v.bv_len, v.bv_page,
                 v.bv_offset, v.bv_len),
        memcpy((p += v.iov_len) - v.iov_len, v.iov_base, v.iov_len)
    )
    kunmap_atomic(kaddr);
    return bytes;
}

// https://elixir.bootlin.com/linux/v4.11.6/source/fs/ext4/inode.c#L3164
static int ext4_da_write_end(struct file *file,
                struct address_space *mapping,
                loff_t pos, unsigned len, unsigned copied,
                struct page *page, void *fsdata)
{
    struct inode *inode = mapping->host;
    int ret = 0, ret2;
    handle_t *handle = ext4_journal_current_handle();
    loff_t new_i_size;
    unsigned long start, end;
    int write_mode = (int)(unsigned long)fsdata;

    // ...inline data handling...

    start = pos & (PAGE_SIZE - 1);
    end = start + copied - 1;

    /*
     * generic_write_end 是通用的 write_end 实现，它会：
     * 1. 调用 block_write_end 更新 buffer_head 状态（标记 BH_Uptodate / BH_Dirty）
     * 2. 如果写入扩展了文件，更新 i_size
     * 3. 解锁页面并释放引用
     * 4. 标记页面为 dirty（通过 __set_page_dirty_buffers）
     */
    ret = generic_write_end(file, mapping, pos, len, copied, page, fsdata);

    /*
     * 如果写入位置超出了当前文件大小，需要更新 inode 的 i_disksize。
     * i_disksize 是已知的磁盘上的文件大小（可能小于 i_size），
     * 在延迟分配模式下，i_size 可能超前于 i_disksize
     */
    new_i_size = pos + copied;
    if (new_i_size > EXT4_I(inode)->i_disksize) {
        ext4_update_i_disksize(inode, new_i_size);
    }

    /* 停止 JBD2 事务 handle */
    ret2 = ext4_journal_stop(handle);
    if (!ret)
        ret = ret2;

    return ret ? ret : copied;
}

// https://elixir.bootlin.com/linux/v4.11.6/source/fs/ext4/inode.c#L1563
static int ext4_da_reserve_space(struct inode *inode)
{
    struct ext4_sb_info *sbi = EXT4_SB(inode->i_sb);
    struct ext4_inode_info *ei = EXT4_I(inode);
    int ret;

    /*
     * 使用 dquot 系统预留一个数据块 + 可能需要的元数据块。
     * 虽然还没有分配物理块，但需要确保后续 writeback 时有足够的空间
     */
    ret = dquot_reserve_block(inode, EXT4_C2B(sbi, 1));
    if (ret)
        return ret;

    spin_lock(&ei->i_block_reservation_lock);
    ei->i_reserved_data_blocks++;        // 预留的数据块计数 +1
    spin_unlock(&ei->i_block_reservation_lock);

    return 0;
}

// https://elixir.bootlin.com/linux/v4.11.6/source/fs/ext4/ext4_extents.h#L88
struct ext4_extent {
    __le32  ee_block;       // 起始逻辑块号
    __le16  ee_len;         // 覆盖的块数（高位用于标记 unwritten）
    __le16  ee_start_hi;    // 起始物理块号的高 16 位
    __le32  ee_start_lo;    // 起始物理块号的低 32 位
};

struct ext4_extent_idx {
    __le32  ei_block;       // 覆盖的起始逻辑块号
    __le32  ei_leaf_lo;     // 指向下一层节点的物理块号（低 32 位）
    __le16  ei_leaf_hi;     // 物理块号的高 16 位
    __u16   ei_unused;
};

struct ext4_extent_header {
    __le16  eh_magic;       // 魔数 0xF30A
    __le16  eh_entries;     // 有效 entry 数
    __le16  eh_max;         // 最大 entry 容量
    __le16  eh_depth;       // 树的深度（0 = 叶节点）
    __le32  eh_generation;  // 版本号
};

// https://elixir.bootlin.com/linux/v4.11.6/source/fs/ext4/mballoc.c#L4586
ext4_fsblk_t ext4_mb_new_blocks(handle_t *handle,
                struct ext4_allocation_request *ar, int *errp)
{
    struct ext4_allocation_context *ac = NULL;
    struct ext4_sb_info *sbi;
    // ...

    /* 归一化请求：将小的分配请求扩展为更大的对齐请求 */
    ext4_mb_normalize_request(ac, ar);

    /* 尝试使用 preallocation（预分配）满足请求 */
    ext4_mb_use_preallocation(ac);

    if (!ac->ac_found) {
        /* 预分配未满足，走正式的伙伴系统分配 */
        ext4_mb_regular_allocator(ac);
    }

    // ...
    *errp = ext4_mb_mark_diskspace_used(ac, handle, reserv_clstrs);
    // ...

    return block;
}

// ext4_da_write_begin 中
handle = ext4_journal_start(inode, EXT4_HT_WRITE_PAGE,
            ext4_da_write_credits(inode, pos, len));
// ... 修改元数据 ...

// ext4_da_write_end 中
ext4_journal_stop(handle);

// ext4_journal_start 最终调用：
// https://elixir.bootlin.com/linux/v4.11.6/source/fs/jbd2/transaction.c#L341
handle_t *jbd2__journal_start(journal_t *journal, int nblocks, int rsv_blocks,
                  gfp_t gfp_mask, unsigned int type,
                  unsigned int line_no)
{
    handle_t *handle = journal_current_handle();

    if (handle) {
        /* 嵌套 handle：递增引用计数即可 */
        handle->h_ref++;
        return handle;
    }

    handle = new_handle(nblocks);
    // ...

    /*
     * 将 handle 加入当前运行的 transaction。
     * 如果当前没有 running transaction，会创建一个新的。
     * 如果 running transaction 的剩余 credits 不足，
     * 会等待当前 transaction 提交后再开启新的
     */
    err = start_this_handle(journal, handle, gfp_mask);
    // ...

    return handle;
}

// https://elixir.bootlin.com/linux/v4.11.6/source/fs/jbd2/transaction.c#L1537
int jbd2_journal_stop(handle_t *handle)
{
    transaction_t *transaction = handle->h_transaction;
    journal_t *journal;

    // ...

    if (handle->h_ref > 1) {
        handle->h_ref--;    // 嵌套 handle，递减引用即可
        return 0;
    }

    journal = transaction->t_journal;

    /*
     * 如果当前 handle 是 transaction 中的最后一个活跃 handle，
     * 且 transaction 已经超时（达到 commit interval），
     * 则唤醒 kjournald2 线程提交 transaction
     */
    if (handle->h_sync ||
        transaction->t_outstanding_credits >
            journal->j_max_transaction_buffers ||
        time_after_eq(jiffies, transaction->t_expires)) {
        // ... 触发 transaction commit ...
    }

    // 释放 handle
    jbd2_free_handle(handle);
    return err;
}

// https://elixir.bootlin.com/linux/v4.11.6/source/fs/fs-writeback.c#L1861
void wb_workfn(struct work_struct *work)
{
    struct bdi_writeback *wb = container_of(to_delayed_work(work),
                        struct bdi_writeback, dwork);
    long pages_written;

    // ...
    if (likely(!current_is_workqueue_rescuer() ||
          !test_bit(WB_registered, &wb->state))) {
        do {
            pages_written = wb_do_writeback(wb);
        } while (!list_empty(&wb->work_list));
    }
    // ...
}

// https://elixir.bootlin.com/linux/v4.11.6/source/fs/ext4/inode.c#L2579
static int ext4_writepages(struct address_space *mapping,
               struct writeback_control *wbc)
{
    struct inode *inode = mapping->host;
    struct ext4_map_blocks map;
    struct mpage_da_data mpd;
    handle_t *handle = NULL;
    // ...

    mpd.inode = inode;
    mpd.first_page = 0;
    mpd.next_page = 0;
    mpd.io_submit.io_end = NULL;

    /* 遍历脏页区间 */
    while (!ret && mpd.first_page <= mpd.last_page) {
        /* 开启 JBD2 事务（此时需要真正修改磁盘元数据） */
        handle = ext4_journal_start(inode, EXT4_HT_WRITE_PAGE,
                    needed_blocks);

        /*
         * 扫描脏页，构建逻辑块范围 → 物理块的映射请求。
         * 将连续的脏页聚合为尽可能大的 extent
         */
        ret = mpage_prepare_extent_to_map(&mpd);

        if (mpd.map.m_len > 0) {
            /*
             * 核心操作：将延迟分配的逻辑块映射为物理块。
             * 这里真正调用 ext4_map_blocks → ext4_ext_map_blocks → ext4_mb_new_blocks
             * 完成物理块分配
             */
            ret = mpage_map_and_submit_extent(handle, &mpd, &give_up_on_write);
        }

        ext4_journal_stop(handle);
    }

    // ...
}

// mpage_map_and_submit_extent 中的核心调用
static int mpage_map_one_extent(handle_t *handle, struct mpage_da_data *mpd)
{
    struct inode *inode = mpd->inode;
    struct ext4_map_blocks *map = &mpd->map;
    int get_blocks_flags;

    /*
     * ext4_map_blocks 是 extent 操作的统一入口：
     * 对于延迟分配的块，它会调用 ext4_ext_map_blocks 真正分配物理块，
     * 并将 extent 插入到 inode 的 extent tree 中
     */
    return ext4_map_blocks(handle, inode, map, get_blocks_flags);
}

// https://elixir.bootlin.com/linux/v4.11.6/source/fs/ext4/page-io.c
void ext4_io_submit(struct ext4_io_submit *io)
{
    struct bio *bio = io->io_bio;

    if (bio) {
        int io_op_flags = io->io_wbc->sync_mode == WB_SYNC_ALL ?
                  WRITE_SYNC : 0;
        submit_bio(WRITE | io_op_flags, bio);   // 提交 BIO 到块设备层
    }
    io->io_bio = NULL;
}

// https://elixir.bootlin.com/linux/v4.11.6/source/include/linux/blk_types.h#L46
struct bio {
    struct bio          *bi_next;       // 链表，多个 bio 可以链在一起
    struct block_device *bi_bdev;       // 目标块设备
    unsigned int        bi_opf;         // 操作类型（READ/WRITE）和标志
    struct bvec_iter    bi_iter;        // 迭代器：起始扇区、剩余字节数
    unsigned short      bi_vcnt;        // bio_vec 段数
    struct bio_vec      *bi_io_vec;     // 指向页面数组（每个元素描述一个页面+偏移+长度）
    bio_end_io_t        *bi_end_io;     // I/O 完成回调
    // ...
};

// https://elixir.bootlin.com/linux/v4.11.6/source/mm/filemap.c#L2834
ssize_t generic_file_direct_write(struct kiocb *iocb, struct iov_iter *from)
{
    struct file *file = iocb->ki_filp;
    struct address_space *mapping = file->f_mapping;
    struct inode *inode = mapping->host;
    loff_t pos = iocb->ki_pos;
    ssize_t written;
    size_t write_len;
    pgoff_t end;

    write_len = iov_iter_count(from);
    end = (pos + write_len - 1) >> PAGE_SHIFT;

    /*
     * 如果 Page Cache 中有与写入范围重叠的脏页，必须先刷出到磁盘，
     * 否则 DIO 写入的新数据可能被后续 Page Cache 回写的旧数据覆盖
     */
    written = filemap_write_and_wait_range(mapping, pos, pos + write_len - 1);
    if (written)
        goto out;

    /*
     * 使 Page Cache 中重叠范围的页面失效。
     * 这保证后续读操作不会从 Page Cache 读到过期数据，而是从磁盘读取 DIO 写入的新数据
     */
    invalidate_inode_pages2_range(mapping, pos >> PAGE_SHIFT, end);

    /* 调用文件系统的 direct_IO 方法 */
    written = mapping->a_ops->direct_IO(iocb, from);

    if (written > 0) {
        pos += written;
        iocb->ki_pos = pos;
        /* 再次失效，防止并发 buffered read 在 DIO 期间填充了 Page Cache */
        invalidate_inode_pages2_range(mapping, pos >> PAGE_SHIFT, end);
    }

    // ...
    return written;
}

// https://elixir.bootlin.com/linux/v4.11.6/source/fs/ext4/inode.c#L3454
static ssize_t ext4_direct_IO_write(struct kiocb *iocb, struct iov_iter *iter)
{
    struct file *file = iocb->ki_filp;
    struct inode *inode = file->f_mapping->host;
    ssize_t ret;
    // ...

    /*
     * 对于 overwrite（写入范围内所有块已分配），可以直接走 DIO。
     * 对于需要分配新块的情况，ext4 需要先分配块（不能延迟分配，
     * 因为 DIO 直接写磁盘，必须知道目标物理块号）
     */
    ret = __blockdev_direct_IO(iocb, inode, inode->i_sb->s_bdev,
                iter, ext4_dio_get_block, ext4_end_io_dio, NULL,
                get_block_flags);

    // ...
    return ret;
}

// https://elixir.bootlin.com/linux/v4.11.6/source/include/linux/fs.h#L2534
static inline ssize_t generic_write_sync(struct kiocb *iocb, ssize_t count)
{
    if (iocb->ki_flags & IOCB_DSYNC) {
        /*
         * IOCB_DSYNC: 需要同步数据（O_DSYNC 或 O_SYNC 都会设置此标志）
         * IOCB_SYNC:  额外需要同步元数据（仅 O_SYNC 设置）
         * datasync = 1 表示只同步数据（fdatasync 语义）
         * datasync = 0 表示同步数据 + 元数据（fsync 语义）
         */
        int ret = vfs_fsync_range(iocb->ki_filp,
                iocb->ki_pos - count, iocb->ki_pos - 1,
                (iocb->ki_flags & IOCB_SYNC) ? 0 : 1);
        if (ret)
            return ret;
    }

    return count;
}

// https://elixir.bootlin.com/linux/v4.11.6/source/fs/sync.c#L224
int vfs_fsync_range(struct file *file, loff_t start, loff_t end, int datasync)
{
    struct inode *inode = file->f_mapping->host;

    if (!file->f_op->fsync)
        return -EINVAL;
    if (!datasync && (inode->i_state & I_DIRTY_TIME)) {
        spin_lock(&inode->i_lock);
        inode->i_state &= ~I_DIRTY_TIME;
        spin_unlock(&inode->i_lock);
        mark_inode_dirty_sync(inode);
    }
    //ext4 对应的fsync实现为ext4_sync_file
    return file->f_op->fsync(file, start, end, datasync);
}

// https://elixir.bootlin.com/linux/v4.11.6/source/fs/ext4/fsync.c#L88
int ext4_sync_file(struct file *file, loff_t start, loff_t end, int datasync)
{
    struct inode *inode = file->f_mapping->host;
    struct ext4_inode_info *ei = EXT4_I(inode);
    journal_t *journal = EXT4_SB(inode->i_sb)->s_journal;
    int ret = 0, err;
    tid_t commit_tid;
    bool needs_barrier = false;

    // ...

    /* 将指定范围的脏页刷到磁盘（调用 ext4_writepages） */
    ret = filemap_write_and_wait_range(inode->i_mapping, start, end);
    if (ret)
        return ret;

    inode_lock(inode);

    if (!journal) {
        /* 无日志模式：直接同步 inode 元数据 */
        ret = __generic_file_fsync(file, start, end, datasync);
        goto out;
    }

    /*
     * data=journal 模式下，数据也在日志中，只需确保 transaction 提交即可。
     * data=ordered/writeback 模式下，数据已经通过 filemap_write_and_wait_range 刷出
     */
    if (ext4_should_journal_data(inode)) {
        ret = ext4_force_commit(inode->i_sb);
        goto out;
    }

    /*
     * 获取包含本次写入元数据修改的 transaction ID，
     * 然后强制提交该 transaction 并等待完成
     */
    commit_tid = datasync ? ei->i_datasync_tid : ei->i_sync_tid;
    if (journal->j_flags & JBD2_BARRIER &&
        !jbd2_trans_will_send_data_barrier(journal, commit_tid))
        needs_barrier = true;

    ret = jbd2_complete_transaction(journal, commit_tid);

    if (needs_barrier) {
        /* 发送 flush/FUA barrier 确保磁盘缓存刷出 */
        err = blkdev_issue_flush(inode->i_sb->s_bdev, GFP_KERNEL, NULL);
        if (!ret)
            ret = err;
    }

out:
    inode_unlock(inode);
    // ...
    return ret;
}