/* fs/direct-io.c */
static inline int dio_bio_reap(struct dio *dio, struct dio_submit *sdio)
{
    int ret = 0;

    if (sdio->reap_counter++ >= 64) {
        while (dio->bio_list) {
            unsigned long flags;
            struct bio *bio;
            int ret2;

            spin_lock_irqsave(&dio->bio_lock, flags);
            bio = dio->bio_list;
            dio->bio_list = bio->bi_private;
            spin_unlock_irqrestore(&dio->bio_lock, flags);
            ret2 = blkdev_issue_flush(bio->bi_bdev);
            if (ret == 0)
                ret = ret2;
            bio_put(bio);
        }
        sdio->reap_counter = 0;
    }
    return ret;
}

/* fs/direct-io.c */
struct dio {
    int             flags;          /* flags from file open */
    blk_opf_t       opf;            /* request operation type and flags */
    struct gendisk  *bio_disk;
    struct inode    *inode;
    loff_t          i_size;         /* i_size when submitted */
    dio_iodone_t    *end_io;        /* IO completion function */

    void            *private;       /* copy from map_bh.b_private */

    /* BIO completion state */
    spinlock_t      bio_lock;       /* protects BIO fields below */
    int             page_errors;    /* errno from get_user_pages() */
    int             is_async;       /* non-zero if this is async DIO */
    bool            defer_completion; /* defer AIO completion to workqueue? */
    bool            should_dirty;   /* if pages should be dirtied */
    int             io_error;       /* IO error in completion path */
    unsigned long   refcount;       /* direct_io_worker() and bios */
    struct bio      *bio_list;      /* singly linked via bi_private */
    struct task_struct *waiter;     /* waiting task (NULL if none) */

    /* AIO related stuff */
    struct kiocb    *iocb;          /* kiocb */
    ssize_t         result;         /* IO result */

    /*
     * pages[] (and any fields after it) are not zeroed out at
     * allocation time. Don't add new fields after pages[] unless
     * you handle that.
     */
    union {
        struct page *pages[DIO_PAGES]; /* page buffer */
        struct work_struct complete_work; /* deferred AIO completion */
    };
} ____cacheline_aligned_in_smp;

ssize_t __blockdev_direct_IO(struct kiocb *iocb, struct inode *inode,
                              struct block_device *bdev,
                              struct iov_iter *iter,
                              get_block_t get_block,
                              dio_iodone_t end_io,
                              int flags)
{
    unsigned i_blkbits = READ_ONCE(inode->i_blkbits);
    unsigned blkbits = i_blkbits;
    unsigned blocksize_mask = (1 << blkbits) - 1;
    ssize_t retval = -EINVAL;
    const size_t count = iov_iter_count(iter);
    loff_t offset = iocb->ki_pos;
    const loff_t end = offset + count;
    struct dio *dio;
    struct dio_submit sdio = { 0, };
    struct buffer_head map_bh = { 0, };

    /* ... 对齐检查 ... */
    if ((offset & blocksize_mask) || (count & blocksize_mask)) {
        if (bdev) {
            blkbits = blksize_bits(bdev_logical_block_size(bdev));
            blocksize_mask = (1 << blkbits) - 1;
            if ((offset & blocksize_mask) || (count & blocksize_mask))
                goto out;
        } else {
            goto out;
        }
    }

    dio = kmem_cache_alloc(dio_cache, GFP_KERNEL);
    /* ... 初始化 dio，提交 bio，等待完成 ... */
}

static void dio_bio_submit(struct dio *dio, struct dio_submit *sdio)
{
    struct bio *bio = sdio->bio;
    unsigned long flags;

    bio->bi_private = dio;

    spin_lock_irqsave(&dio->bio_lock, flags);
    dio->refcount++;
    spin_unlock_irqrestore(&dio->bio_lock, flags);

    if (dio->is_async && dio->opf == REQ_OP_READ && dio->should_dirty)
        bio_set_pages_dirty(bio);

    dio->bio_disk = bio->bi_bdev->bd_disk;

    if (sdio->submit_io) {
        sdio->submit_io(bio, dio->inode, sdio->logical_offset_in_bio);
        sdio->bio = NULL;
        sdio->boundary = 0;
        sdio->logical_offset_in_bio = 0;
    } else {
        submit_bio(bio);
    }

    sdio->bio = NULL;
    sdio->boundary = 0;
    sdio->logical_offset_in_bio = 0;
}

struct kiocb {
    struct file         *ki_filp;       /* 目标文件 */
    loff_t              ki_pos;         /* 当前 IO 偏移量 */
    void (*ki_complete)(struct kiocb *iocb, long ret); /* 完成回调 */
    void                *private;
    int                 ki_flags;       /* IOCB_* 标志位 */
    u16                 ki_ioprio;      /* 请求优先级 (IOPRIO_PRIO_VALUE) */
    union {
        /* AIO 完成事件关联 */
        struct wait_page_queue  *ki_waitq;
        /* 用于 poll 路径 */
        __poll_t (*ki_poll)(struct file *, struct poll_table_struct *);
    };
};

/* fs/aio.c */
static int __io_submit_one(struct kioctx *ctx, const struct iocb *iocb,
                           struct iocb __user *user_iocb, struct aio_kiocb *req,
                           bool compat)
{
    req->ki_filp = fget(iocb->aio_fildes);
    if (unlikely(!req->ki_filp))
        return -EBADF;

    if (iocb->aio_flags & IOCB_FLAG_RESFD) {
        /*
         * eventfd 通知模式：完成时写入 eventfd
         */
        req->ki_eventfd = eventfd_ctx_fdget(iocb->aio_resfd);
        if (IS_ERR(req->ki_eventfd)) {
            int ret = PTR_ERR(req->ki_eventfd);
            req->ki_eventfd = NULL;
            return ret;
        }
    }

    ret = put_user(KIOCB_KEY, &user_iocb->aio_key);
    if (unlikely(ret))
        return ret;

    req->ki_res.obj = (u64)(unsigned long)user_iocb;
    req->ki_res.data = iocb->aio_data;
    req->ki_res.res = 0;
    req->ki_res.res2 = 0;

    switch (iocb->aio_lio_opcode) {
    case IOCB_CMD_PREAD:
        return aio_read(&req->rw, iocb, false, compat);
    case IOCB_CMD_PWRITE:
        return aio_write(&req->rw, iocb, false, compat);
    case IOCB_CMD_PREADV:
        return aio_read(&req->rw, iocb, true, compat);
    case IOCB_CMD_PWRITEV:
        return aio_write(&req->rw, iocb, true, compat);
    case IOCB_CMD_FSYNC:
        return aio_fsync(&req->fsync, iocb, false);
    case IOCB_CMD_FDSYNC:
        return aio_fsync(&req->fsync, iocb, true);
    case IOCB_CMD_POLL:
        return aio_poll(req, iocb);
    default:
        pr_debug("EINVAL: no operation provided\n");
        return -EINVAL;
    }
}

/* fs/aio.c */
static long read_events(struct kioctx *ctx, long min_nr, long nr,
                        struct io_event __user *event,
                        ktime_t until)
{
    long ret = 0;

    /*
     * Note that aio_read_events() is being called as the conditional
     * in a wait_event() loop. When the conditional is satisfied,
     * the loop exits; otherwise we wait until an event is reaped.
     */
    if (!wait_event_interruptible_hrtimeout(ctx->wait,
            aio_read_events(ctx, min_nr, nr, event, &ret), until))
        return ret;

    if (!ret && !time_after(jiffies, ctx->mmap_base))
        ret = -EINTR;
    return ret;
}

struct io_event {
    __u64   data;    /* 用户设置的 aio_data，用于关联请求 */
    __u64   obj;     /* 指向原始 iocb 的指针 */
    __s64   res;     /* 操作结果（>=0 成功，<0 errno）*/
    __s64   res2;    /* 二级结果（如 preadv2 flags） */
};

/* io_uring/io_uring.c（简化） */
struct io_ring_ctx {
    /* 不可变字段（初始化后不再修改） */
    struct {
        unsigned int            flags;
        unsigned int            compat   : 1;
        unsigned int            drain_next : 1;
        unsigned int            restricted : 1;
        unsigned int            off_timeout_used : 1;
        unsigned int            drain_active : 1;
    } ____cacheline_aligned_in_smp;

    /* 提交队列（SQ）相关 */
    struct {
        struct mutex            uring_lock;
        u32                     *sq_array;      /* SQ 索引数组（共享内存） */
        struct io_uring_sqe     *sq_sqes;       /* SQE 环（共享内存） */
        unsigned                cached_sq_head;
        unsigned                sq_entries;
        struct io_wq_work_list  defer_list;
    } ____cacheline_aligned_in_smp;

    /* 完成队列（CQ）相关 */
    struct {
        unsigned                cached_cq_tail;
        unsigned                cq_entries;
        struct io_ev_fd __rcu   *io_ev_fd;      /* eventfd 通知 */
        struct wait_queue_head  cq_wait;
        unsigned                cq_extra;
    } ____cacheline_aligned_in_smp;

    struct io_rings             *rings;         /* 指向共享内存中的环头 */

    /* 注册资源 */
    struct io_rsrc_data         *file_data;     /* 注册文件表 */
    struct io_rsrc_data         *buf_data;      /* 注册缓冲区表 */

    /* SQPOLL 内核线程 */
    struct io_sq_data           *sq_data;

    /* 工作队列 */
    struct io_wq                *io_wq;

    /* 其他字段... */
};

struct io_uring_sqe {
    __u8    opcode;         /* IORING_OP_READ/WRITE/... */
    __u8    flags;          /* IOSQE_* 标志 */
    __u16   ioprio;
    __s32   fd;             /* 目标文件描述符（或注册文件索引） */
    union {
        __u64   off;        /* 偏移量（pread/pwrite 用） */
        __u64   addr2;
    };
    union {
        __u64   addr;       /* 缓冲区地址（或注册缓冲区索引） */
        __u64   splice_off_in;
    };
    __u32   len;            /* 缓冲区长度 */
    union {
        __kernel_rwf_t  rw_flags;
        __u32           fsync_flags;
        __u16           poll_events;
        __u32           poll32_events;
        __u32           sync_range_flags;
        __u32           msg_flags;
        __u32           timeout_flags;
        __u32           accept_flags;
        __u32           cancel_flags;
        __u32           open_flags;
        __u32           statx_flags;
        __u32           fadvise_advice;
        __u32           splice_flags;
        __u32           rename_flags;
        __u32           unlink_flags;
        __u32           hardlink_flags;
        __u32           xattr_flags;
        __u32           msg_ring_flags;
        __u32           uring_cmd_flags;
    };
    __u64   user_data;      /* 用户自定义标识，原样返回 CQE */
    union {
        __u16   buf_index;  /* 注册缓冲区索引 */
        __u16   buf_group;
    } __attribute__((packed));
    __u16   personality;
    union {
        __s32   splice_fd_in;
        __u32   file_index;
        __u32   optlen;
        struct {
            __u16 addr_len;
            __u16 __pad3[1];
        };
    };
    /* ... */
};

struct io_uring_cqe {
    __u64   user_data;  /* 对应 SQE 的 user_data */
    __s32   res;        /* 操作结果 */
    __u32   flags;      /* IORING_CQE_F_* */
};

/* io_uring/io_uring.c */
static struct io_ring_ctx *io_ring_ctx_alloc(struct io_uring_params *p)
{
    struct io_ring_ctx *ctx;
    int hash_bits;

    ctx = kzalloc(sizeof(*ctx), GFP_KERNEL);
    if (!ctx)
        return NULL;

    xa_init(&ctx->io_bl_xa);

    hash_bits = ilog2(p->cq_entries);
    hash_bits = clamp(hash_bits, 1, 8);
    ctx->cancel_table.hbs = hash_bits;
    ctx->cancel_table.hash = kcalloc(1U << hash_bits,
                    sizeof(struct hlist_head), GFP_KERNEL);
    if (!ctx->cancel_table.hash)
        goto err;

    ctx->cancel_table_locked.hbs = hash_bits;
    ctx->cancel_table_locked.hash = kcalloc(1U << hash_bits,
                    sizeof(struct hlist_head), GFP_KERNEL);
    if (!ctx->cancel_table_locked.hash)
        goto err;

    if (percpu_ref_init(&ctx->refs, io_ring_ctx_ref_free,
                        0, GFP_KERNEL))
        goto err;

    ctx->flags = p->flags;
    init_waitqueue_head(&ctx->sqo_sq_wait);
    INIT_LIST_HEAD(&ctx->sqd_list);
    init_waitqueue_head(&ctx->poll_wait);
    INIT_LIST_HEAD(&ctx->cq_overflow_list);
    /* ... 更多初始化 ... */
    return ctx;
err:
    io_ring_ctx_free(ctx);
    return NULL;
}

/* io_uring/sqpoll.c（简化） */
static int io_sq_thread(void *data)
{
    struct io_sq_data *sqd = data;
    struct io_ring_ctx *ctx;
    unsigned long timeout = 0;
    char buf[TASK_COMM_LEN];
    DEFINE_WAIT(wait);

    snprintf(buf, sizeof(buf), "iou-sqp-%d", sqd->task_pid);
    set_task_comm(current, buf);

    while (!test_bit(IO_SQ_THREAD_SHOULD_STOP, &sqd->state)) {
        int ret;
        bool cap_entries, sqt_spin = false;

        /* 轮询所有关联的 ring ctx */
        list_for_each_entry(ctx, &sqd->ctx_list, sqd_list) {
            if (io_sq_have_work(ctx))
                sqt_spin |= io_sq_thread_handle_c(ctx, &cap_entries);
        }

        if (sqt_spin || !time_after(jiffies, timeout)) {
            io_run_task_work();
            cond_resched();
            if (sqt_spin)
                timeout = jiffies + sqd->sq_thread_idle;
            continue;
        }

        /* 超过 idle 时间，进入睡眠等待新任务 */
        prepare_to_wait(&sqd->wait, &wait, TASK_INTERRUPTIBLE);
        /* ... */
    }
    return 0;
}

/* 注册固定缓冲区 */
struct iovec iov[2];
iov[0].iov_base = buf0;
iov[0].iov_len  = BUF_SIZE;
iov[1].iov_base = buf1;
iov[1].iov_len  = BUF_SIZE;
io_uring_register(ring_fd, IORING_REGISTER_BUFFERS, iov, 2);

/* 使用固定缓冲区时，SQE 中用 buf_index 代替地址 */
sqe->opcode    = IORING_OP_READ_FIXED;
sqe->buf_index = 0;  /* 使用第 0 个注册缓冲区 */

/* 读取文件 → 处理 → 写入另一个文件，串行执行 */
sqe = io_uring_get_sqe(&ring);
io_uring_prep_read(sqe, src_fd, buf, len, 0);
sqe->flags |= IOSQE_IO_LINK;   /* 链接到下一个 SQE */
sqe->user_data = 1;

sqe = io_uring_get_sqe(&ring);
io_uring_prep_write(sqe, dst_fd, buf, len, 0);
sqe->user_data = 2;             /* 最后一个不设 IOSQE_IO_LINK */

io_uring_submit(&ring);
/* 内核保证先执行 read，read 完成后才执行 write */

#include <liburing.h>
#include <fcntl.h>
#include <string.h>

#define QUEUE_DEPTH 64
#define BLOCK_SZ    4096

int main(void)
{
    struct io_uring ring;
    struct io_uring_sqe *sqe;
    struct io_uring_cqe *cqe;
    char buf[BLOCK_SZ];
    int fd, ret;

    /* 初始化 io_uring，深度为 64 */
    io_uring_queue_init(QUEUE_DEPTH, &ring, 0);

    fd = open("/tmp/testfile", O_RDONLY | O_DIRECT);

    /* 获取 SQE 并填写读请求 */
    sqe = io_uring_get_sqe(&ring);
    io_uring_prep_read(sqe, fd, buf, BLOCK_SZ, 0);
    sqe->user_data = 42;  /* 自定义标识 */

    /* 提交（写 SQ tail，触发内核处理） */
    io_uring_submit(&ring);

    /* 等待完成事件 */
    ret = io_uring_wait_cqe(&ring, &cqe);
    if (ret == 0 && cqe->res > 0) {
        printf("读取 %d 字节，user_data=%llu\n",
               cqe->res, (unsigned long long)cqe->user_data);
    }

    /* 标记 CQE 已消费（推进 CQ head） */
    io_uring_cqe_seen(&ring, cqe);

    io_uring_queue_exit(&ring);
    close(fd);
    return 0;
}

// include/uapi/linux/btrfs_tree.h

/*
 * btrfs_disk_key is in disk byte order.  struct btrfs_key is always
 * in cpu native order.  Otherwise they are identical and their sizes
 * should be the same (ie both packed)
 */
struct btrfs_disk_key {
    __le64 objectid;
    __u8 type;
    __le64 offset;
} __attribute__ ((__packed__));

struct btrfs_key {
    __u64 objectid;
    __u8 type;
    __u64 offset;
} __attribute__ ((__packed__));

// fs/btrfs/ctree.c

#ifdef __LITTLE_ENDIAN
/*
 * Compare two keys, on little-endian the disk order is same as CPU order and
 * we can avoid the conversion.
 */
static int comp_keys(const struct btrfs_disk_key *disk_key,
                     const struct btrfs_key *k2)
{
    const struct btrfs_key *k1 = (const struct btrfs_key *)disk_key;
    return btrfs_comp_cpu_keys(k1, k2);
}
#endif

int __pure btrfs_comp_cpu_keys(const struct btrfs_key *k1, const struct btrfs_key *k2)
{
    if (k1->objectid > k2->objectid)
        return 1;
    if (k1->objectid < k2->objectid)
        return -1;
    if (k1->type > k2->type)
        return 1;
    if (k1->type < k2->type)
        return -1;
    if (k1->offset > k2->offset)
        return 1;
    if (k1->offset < k2->offset)
        return -1;
    return 0;
}

// include/uapi/linux/btrfs_tree.h

/*
 * Every tree block (leaf or node) starts with this header.
 */
struct btrfs_header {
    /* These first four must match the super block */
    __u8 csum[BTRFS_CSUM_SIZE];
    /* FS specific uuid */
    __u8 fsid[BTRFS_FSID_SIZE];
    /* Which block this node is supposed to live in */
    __le64 bytenr;
    __le64 flags;

    /* Allowed to be different from the super from here on down */
    __u8 chunk_tree_uuid[BTRFS_UUID_SIZE];
    __le64 generation;
    __le64 owner;
    __le32 nritems;
    __u8 level;
} __attribute__ ((__packed__));

// include/uapi/linux/btrfs_tree.h

/*
 * A leaf is full of items. offset and size tell us where to find the item in
 * the leaf (relative to the start of the data area)
 */
struct btrfs_item {
    struct btrfs_disk_key key;
    __le32 offset;
    __le32 size;
} __attribute__ ((__packed__));

/*
 * Leaves have an item area and a data area:
 * [item0, item1....itemN] [free space] [dataN...data1, data0]
 *
 * The data is separate from the items to get the keys closer together during
 * searches.
 */
struct btrfs_leaf {
    struct btrfs_header header;
    struct btrfs_item items[];
} __attribute__ ((__packed__));

// include/uapi/linux/btrfs_tree.h

/*
 * All non-leaf blocks are nodes, they hold only keys and pointers to other
 * blocks.
 */
struct btrfs_key_ptr {
    struct btrfs_disk_key key;
    __le64 blockptr;
    __le64 generation;
} __attribute__ ((__packed__));

struct btrfs_node {
    struct btrfs_header header;
    struct btrfs_key_ptr ptrs[];
} __attribute__ ((__packed__));

// fs/btrfs/ctree.h

/*
 * in ram representation of the tree. extent_root is used for all allocations
 * and for the extent tree extent_root root.
 */
struct btrfs_root {
    struct rb_node rb_node;

    struct extent_buffer *node;       /* 当前根节点（写操作用） */
    struct extent_buffer *commit_root; /* 已提交的根节点（读操作用） */
    struct btrfs_root *log_root;
    struct btrfs_root *reloc_root;

    unsigned long state;
    struct btrfs_root_item root_item;
    struct btrfs_key root_key;
    struct btrfs_fs_info *fs_info;

    spinlock_t inode_lock;
    struct rb_root inode_tree;        /* 内存中 inode 的红黑树 */

    /* red-black tree that keeps track of in-memory inodes */
    struct radix_tree_root delayed_nodes_tree;

    refcount_t refs;
    /* ... 以及大量的锁、列表、计数器 ... */
};

// fs/btrfs/fs.h

struct btrfs_fs_info {
    u8 chunk_tree_uuid[BTRFS_UUID_SIZE];
    unsigned long flags;
    struct btrfs_root *tree_root;       /* 存放其他树根的"根之树" */
    struct btrfs_root *chunk_root;      /* 物理块组管理树 */
    struct btrfs_root *dev_root;        /* 设备信息树 */
    struct btrfs_root *fs_root;         /* 默认子卷树 */
    struct btrfs_root *quota_root;
    struct btrfs_root *uuid_root;
    struct btrfs_root *data_reloc_root;
    struct btrfs_root *block_group_root;

    /* The log root tree is a directory of all the other log roots */
    struct btrfs_root *log_root_tree;

    /* The tree that holds the global roots (csum, extent, etc) */
    rwlock_t global_root_lock;
    struct rb_root global_root_tree;

    spinlock_t trans_lock;
    struct list_head trans_list;
    struct btrfs_transaction *running_transaction;

    u64 generation;
    u64 last_trans_committed;

    unsigned long compress_type:4;
    unsigned int compress_level;
    u32 commit_interval;
    /* ... */
};

// fs/btrfs/ctree.h

/*
 * btrfs_paths remember the path taken from the root down to the leaf.
 * level 0 is always the leaf, and nodes[1...BTRFS_MAX_LEVEL] will point
 * to any other levels that are present.
 *
 * The slots array records the index of the item or block pointer
 * used while walking the tree.
 */
struct btrfs_path {
    struct extent_buffer *nodes[BTRFS_MAX_LEVEL];
    int slots[BTRFS_MAX_LEVEL];
    u8 locks[BTRFS_MAX_LEVEL];
    u8 reada;
    u8 lowest_level;

    unsigned int search_for_split:1;
    unsigned int keep_locks:1;
    unsigned int skip_locking:1;
    unsigned int search_commit_root:1;
    unsigned int need_commit_sem:1;
    unsigned int skip_release_on_error:1;
    unsigned int search_for_extension:1;
    unsigned int nowait:1;
};

// fs/btrfs/ctree.c

/*
 * btrfs_search_slot - look for a key in a tree and perform necessary
 * modifications to preserve tree invariants.
 *
 * @trans:   Handle of transaction, used when modifying the tree
 * @p:       Holds all btree nodes along the search path
 * @root:    The root node of the tree
 * @key:     The key we are looking for
 * @ins_len: Indicates purpose of search:
 *           >0  for inserts it's size of item inserted
 *           <0  for deletions
 *            0  for plain searches, not modifying the tree
 * @cow:     boolean should CoW operations be performed.
 *
 * If @key is found, 0 is returned and you can find the item in the leaf level
 * of the path (level 0)
 *
 * If @key isn't found, 1 is returned and the leaf level of the path (level 0)
 * points to the slot where it should be inserted
 */
int btrfs_search_slot(struct btrfs_trans_handle *trans, struct btrfs_root *root,
                      const struct btrfs_key *key, struct btrfs_path *p,
                      int ins_len, int cow)

// fs/btrfs/ctree.c

int btrfs_bin_search(struct extent_buffer *eb, int first_slot,
                     const struct btrfs_key *key, int *slot)
{
    unsigned long p;
    int item_size;
    u32 low = first_slot;
    u32 high = btrfs_header_nritems(eb);
    int ret;
    const int key_size = sizeof(struct btrfs_disk_key);

    if (btrfs_header_level(eb) == 0) {
        p = offsetof(struct btrfs_leaf, items);
        item_size = sizeof(struct btrfs_item);
    } else {
        p = offsetof(struct btrfs_node, ptrs);
        item_size = sizeof(struct btrfs_key_ptr);
    }

    while (low < high) {
        unsigned long oip;
        unsigned long offset;
        struct btrfs_disk_key *tmp;
        struct btrfs_disk_key unaligned;
        int mid;

        mid = (low + high) / 2;
        offset = p + mid * item_size;
        oip = offset_in_page(offset);

        if (oip + key_size <= PAGE_SIZE) {
            const unsigned long idx = get_eb_page_index(offset);
            char *kaddr = page_address(eb->pages[idx]);
            oip = get_eb_offset_in_page(eb, offset);
            tmp = (struct btrfs_disk_key *)(kaddr + oip);
        } else {
            read_extent_buffer(eb, &unaligned, offset, key_size);
            tmp = &unaligned;
        }

        ret = comp_keys(tmp, key);
        if (ret < 0)
            low = mid + 1;
        else if (ret > 0)
            high = mid;
        else {
            *slot = mid;
            return 0;
        }
    }
    *slot = low;
    return 1;
}

// fs/btrfs/ctree.c (btrfs_search_slot 主循环简化版)

while (b) {
    level = btrfs_header_level(b);

    if (cow) {
        if (!should_cow_block(trans, root, b))
            goto cow_done;
        /* ... 确保持有足够级别的写锁 ... */
        err = btrfs_cow_block(trans, root, b,
                              p->nodes[level + 1],
                              p->slots[level + 1], &b,
                              BTRFS_NESTING_COW);
        if (err) {
            ret = err;
            goto done;
        }
    }
cow_done:
    p->nodes[level] = b;
    /* ... 向下一层走 ... */
}

// fs/btrfs/ctree.c

/*
 * node level balancing, used to make sure nodes are in proper order for
 * item deletion.  We balance from the top down, so we have to make sure
 * that a deletion won't leave a node completely empty later on.
 */
static noinline int balance_level(struct btrfs_trans_handle *trans,
                                  struct btrfs_root *root,
                                  struct btrfs_path *path, int level)
{
    /* ... 尝试从左/右兄弟节点移入 item，若节点为空则释放 ... */
    if (btrfs_header_nritems(mid) == 1) {
        /*
         * we're not allowed to leave a node with one item in the
         * tree during a delete.  A deletion from lower in the tree
         * could try to delete the only pointer in this node.
         * So, pull some keys from the left.
         */
        wret = balance_node_right(trans, mid, left);
    }
    if (btrfs_header_nritems(mid) == 0) {
        btrfs_clear_buffer_dirty(trans, mid);
        btrfs_tree_unlock(mid);
        del_ptr(root, path, level + 1, pslot);
        root_sub_used(root, mid->len);
        btrfs_free_tree_block(trans, btrfs_root_id(root), mid, 0, 1);
    }
    /* ... */
}

// fs/btrfs/ctree.c

static inline int should_cow_block(struct btrfs_trans_handle *trans,
                                   struct btrfs_root *root,
                                   struct extent_buffer *buf)
{
    if (btrfs_is_testing(root->fs_info))
        return 0;

    /* Ensure we can see the FORCE_COW bit */
    smp_mb__before_atomic();

    /*
     * We do not need to cow a block if
     * 1) this block is not created or changed in this transaction;
     * 2) this block does not belong to TREE_RELOC tree;
     * 3) the root is not forced COW.
     *
     * What is forced COW:
     *    when we create snapshot during committing the transaction,
     *    after we've finished copying src root, we must COW the shared
     *    block to ensure the metadata consistency.
     */
    if (btrfs_header_generation(buf) == trans->transid &&
        !btrfs_header_flag(buf, BTRFS_HEADER_FLAG_WRITTEN) &&
        !(root->root_key.objectid != BTRFS_TREE_RELOC_OBJECTID &&
          btrfs_header_flag(buf, BTRFS_HEADER_FLAG_RELOC)) &&
        !test_bit(BTRFS_ROOT_FORCE_COW, &root->state))
        return 0;
    return 1;
}

// fs/btrfs/ctree.c

/*
 * does the dirty work in cow of a single block.  The parent block (if
 * supplied) is updated to point to the new cow copy.  The new buffer is marked
 * dirty and returned locked.
 */
static noinline int __btrfs_cow_block(struct btrfs_trans_handle *trans,
                             struct btrfs_root *root,
                             struct extent_buffer *buf,
                             struct extent_buffer *parent, int parent_slot,
                             struct extent_buffer **cow_ret,
                             u64 search_start, u64 empty_size,
                             enum btrfs_lock_nesting nest)
{
    /* ... */
    level = btrfs_header_level(buf);

    /* 分配一个新树块 */
    cow = btrfs_alloc_tree_block(trans, root, parent_start,
                                 root->root_key.objectid, &disk_key, level,
                                 search_start, empty_size, nest);

    /* 将旧块内容完整复制到新块 */
    copy_extent_buffer_full(cow, buf);

    /* 更新新块的头部元数据 */
    btrfs_set_header_bytenr(cow, cow->start);
    btrfs_set_header_generation(cow, trans->transid);  /* 标记为当前事务 */
    btrfs_set_header_backref_rev(cow, BTRFS_MIXED_BACKREF_REV);
    btrfs_clear_header_flag(cow, BTRFS_HEADER_FLAG_WRITTEN |
                                  BTRFS_HEADER_FLAG_RELOC);
    btrfs_set_header_owner(cow, root->root_key.objectid);

    /* 更新反向引用，处理共享块的引用计数 */
    ret = update_ref_for_cow(trans, root, buf, cow, &last_ref);

    if (buf == root->node) {
        /* 如果 CoW 的是根节点，更新 root->node 指针 */
        rcu_assign_pointer(root->node, cow);
        btrfs_free_tree_block(trans, btrfs_root_id(root), buf,
                              parent_start, last_ref);
    } else {
        /* 否则更新父节点中的指针 */
        btrfs_set_node_blockptr(parent, parent_slot, cow->start);
        btrfs_set_node_ptr_generation(parent, parent_slot, trans->transid);
        btrfs_mark_buffer_dirty(parent);
        btrfs_free_tree_block(trans, btrfs_root_id(root), buf,
                              parent_start, last_ref);
    }

    btrfs_mark_buffer_dirty(cow);
    *cow_ret = cow;
    return 0;
}

// fs/btrfs/ctree.c

/*
 * check if the tree block can be shared by multiple trees
 */
int btrfs_block_can_be_shared(struct btrfs_root *root,
                              struct extent_buffer *buf)
{
    /*
     * Tree blocks not in shareable trees and tree roots are never shared.
     * If a block was allocated after the last snapshot and the block was
     * not allocated by tree relocation, we know the block is not shared.
     */
    if (test_bit(BTRFS_ROOT_SHAREABLE, &root->state) &&
        buf != root->node && buf != root->commit_root &&
        (btrfs_header_generation(buf) <=
         btrfs_root_last_snapshot(&root->root_item) ||
         btrfs_header_flag(buf, BTRFS_HEADER_FLAG_RELOC)))
        return 1;
    return 0;
}

// fs/btrfs/transaction.c

static noinline int create_pending_snapshot(struct btrfs_trans_handle *trans,
                                   struct btrfs_pending_snapshot *pending)
{
    /* ... */
    /* 为新快照分配一个新的 objectid */
    pending->error = btrfs_get_free_objectid(tree_root, &objectid);

    /* 记录源子卷的最后快照事务 ID */
    btrfs_set_root_last_snapshot(&root->root_item, trans->transid);
    memcpy(new_root_item, &root->root_item, sizeof(*new_root_item));

    /* 对源子卷的根节点做一次 CoW，确保后续修改都走 CoW 路径 */
    old = btrfs_lock_root_node(root);
    ret = btrfs_cow_block(trans, root, old, NULL, 0, &old,
                          BTRFS_NESTING_COW);

    /* 将 CoW 后的根节点复制一份，作为快照的根 */
    ret = btrfs_copy_root(trans, root, old, &tmp, objectid);

    /* 设置 FORCE_COW 标志，后续对源子卷的任何修改都必须 CoW */
    set_bit(BTRFS_ROOT_FORCE_COW, &root->state);
    smp_wmb();

    /* 将快照的根节点写入 tree_root */
    btrfs_set_root_node(new_root_item, tmp);
    key.offset = trans->transid;
    ret = btrfs_insert_root(trans, tree_root, &key, new_root_item);

    /* 添加目录项，使快照可以通过文件系统路径访问 */
    ret = btrfs_add_root_ref(trans, objectid,
                             parent_root->root_key.objectid,
                             btrfs_ino(BTRFS_I(parent_inode)), index,
                             &fname.disk_name);
    /* ... */
}

// fs/btrfs/transaction.h

struct btrfs_pending_snapshot {
    struct dentry *dentry;
    struct inode *dir;
    struct btrfs_root *root;
    struct btrfs_root_item *root_item;
    struct btrfs_root *snap;
    struct btrfs_qgroup_inherit *inherit;
    struct btrfs_path *path;
    struct btrfs_block_rsv block_rsv;
    int error;
    dev_t anon_dev;
    bool readonly;
    struct list_head list;
};

// fs/btrfs/ctree.c

static const struct btrfs_csums {
    u16       size;
    const char  name[10];
    const char  driver[12];
} btrfs_csums[] = {
    [BTRFS_CSUM_TYPE_CRC32]  = { .size = 4,  .name = "crc32c" },
    [BTRFS_CSUM_TYPE_XXHASH] = { .size = 8,  .name = "xxhash64" },
    [BTRFS_CSUM_TYPE_SHA256] = { .size = 32, .name = "sha256" },
    [BTRFS_CSUM_TYPE_BLAKE2] = { .size = 32, .name = "blake2b",
                                  .driver = "blake2b-256" },
};

// fs/btrfs/transaction.h

struct btrfs_transaction {
    u64 transid;
    atomic_t num_extwriters;  /* 外部写者数量（必须在 commit 前归零） */
    atomic_t num_writers;     /* 总写者数量（必须在 commit 前归零） */
    refcount_t use_count;

    unsigned long flags;
    enum btrfs_trans_state state;
    int aborted;

    struct list_head list;
    struct extent_io_tree dirty_pages;
    time64_t start_time;
    wait_queue_head_t writer_wait;
    wait_queue_head_t commit_wait;
    struct list_head pending_snapshots;  /* 待创建的快照 */
    struct list_head dirty_bgs;          /* 脏块组 */
    struct extent_io_tree pinned_extents;/* 被 pin 的 extent（不可释放） */

    struct btrfs_delayed_ref_root delayed_refs; /* 延迟引用更新 */
    struct btrfs_fs_info *fs_info;
};

// fs/btrfs/transaction.c

static noinline int join_transaction(struct btrfs_fs_info *fs_info,
                                     unsigned int type)
{
    struct btrfs_transaction *cur_trans;

    spin_lock(&fs_info->trans_lock);
loop:
    /* The file system has been taken offline. No new transactions. */
    if (BTRFS_FS_ERROR(fs_info)) {
        spin_unlock(&fs_info->trans_lock);
        return -EROFS;
    }

    cur_trans = fs_info->running_transaction;
    if (cur_trans) {
        if (TRANS_ABORTED(cur_trans)) {
            spin_unlock(&fs_info->trans_lock);
            return cur_trans->aborted;
        }
        if (btrfs_blocked_trans_types[cur_trans->state] & type) {
            spin_unlock(&fs_info->trans_lock);
            return -EBUSY;
        }
        refcount_inc(&cur_trans->use_count);
        atomic_inc(&cur_trans->num_writers);
        extwriter_counter_inc(cur_trans, type);
        spin_unlock(&fs_info->trans_lock);
        return 0;
    }
    /* ... 若无运行中事务，创建新事务 ... */
}