// 系统调用入口：epoll_create1（Linux 5.4，有删节）
SYSCALL_DEFINE1(epoll_create1, int, flags)
{
    struct eventpoll *ep;
    int error, fd;

    // 1. 分配并初始化内核 eventpoll 对象。
    //    注意：真正的初始化在 ep_alloc 内完成（rbr = RB_ROOT_CACHED、
    //    INIT_LIST_HEAD(rdllist)、init_waitqueue_head(wq/poll_wait)、
    //    spin_lock_init(lock)、mutex_init(mtx) 等），并不存在
    //    "init_rb_root" 这类函数；本函数只是调用 ep_alloc 而已。
    error = ep_alloc(&ep);
    if (error < 0)
        return error;

    // 2. 分配用户态 fd 并与内核对象绑定（epoll 使用匿名 inode）
    fd = anon_inode_getfd("[eventpoll]", &eventpoll_fops, ep,
                          O_RDWR | (flags & O_CLOEXEC));
    if (fd < 0)
        ep_free(ep);

    return fd;
}

// epoll_ctl ADD 核心执行逻辑（Linux 5.4，有删节）
static int ep_insert(struct eventpoll *ep, struct epoll_event *event,
                     struct file *tfile, int fd, int full_check)
{
    struct epitem *epi;
    struct ep_pqueue epq;
    __poll_t revents;
    int error;

    // 1. 分配epitem节点（单个fd的托管对象）
    epi = kmem_cache_alloc(epi_cache, GFP_KERNEL);
    if (unlikely(!epi))
        return -ENOMEM;

    // 2. 绑定fd、监听事件、内核文件结构体
    //    注意：epitem 没有 epi->fd / epi->file 这两个裸字段，文件与 fd 封装在
    //    epi->ffd（struct epoll_filefd）中，由 ep_set_ffd 统一设置。
    INIT_LIST_HEAD(&epi->rdllink);
    INIT_LIST_HEAD(&epi->fllink);
    INIT_LIST_HEAD(&epi->pwqlist);
    epi->ep = ep;
    ep_set_ffd(&epi->ffd, tfile, fd);
    epi->event = *event;
    epi->nwait = 0;
    epi->next = EP_UNACTIVE_PTR;

    // 3. 插入红黑树（O(logN)），fd 已存在则返回 -EEXIST
    error = ep_rbtree_insert(ep, epi);
    if (error < 0)
        goto error_cleanup;

    // 4. 核心：通过 poll 机制把 ep_poll_callback 挂到 socket 的等待队列上。
    //    init_poll_funcptr(&epq.pt, ep_ptable_queue_proc) 后调用
    //    ep_item_poll(epi, &epq.pt, 1) → vfs_poll → socket 的 poll 函数，
    //    该函数内部会调用 ep_ptable_queue_proc 注册等待项（回调 = ep_poll_callback）。
    //    注意：这不是"替换 f_op->poll"，socket 自身的 poll 逻辑保持不变。
    epq.epi = epi;
    init_poll_funcptr(&epq.pt, ep_ptable_queue_proc);
    revents = ep_item_poll(epi, &epq.pt, 1);
    ...

    return 0;

error_cleanup:
    kmem_cache_free(epi_cache, epi);
    return error;
}

// epoll_wait 核心阻塞逻辑（Linux 5.4，结构示意）
static int ep_poll(struct eventpoll *ep, struct epoll_event __user *events,
                   int maxevents, long timeout)
{
    ...
    // 关键点：判断"是否有事件可投递"用的是 ep_events_available(ep)
    // （就绪链表非空 或 溢出链表 ovflist 有项），而非只查 rdllist。
    if (!ep_events_available(ep)) {
        // 无就绪事件：把当前进程注册到 ep->wq 后休眠。
        // 注意：epoll_wait 的等待项【不会】设置 WQ_FLAG_EXCLUSIVE
        // （那是 EPOLLEXCLUSIVE 语义，属于另一套机制）。
        init_waitqueue_entry(&wait, current);
        __add_wait_queue(&ep->wq, &wait);
        ...
        // 休眠通过 schedule_hrtimeout_range 实现高精度超时等待
        //（并非 jiffies 粒度的 schedule_timeout），被事件唤醒或超时后
        // 回到"检查事件"处；超时且无事件则返回 0。
        if (!schedule_hrtimeout_range(to, slack, HRTIMER_MODE_ABS))
            return 0;
        ...
        remove_wait_queue(&ep->wq, &wait);
    }
    ...
    return ep_send_events(ep, events, maxevents);
}

// TCP报文接收就绪核心逻辑
static void tcp_data_ready(struct sock *sk)
{
    // 标记socket读就绪，唤醒所有监听该fd的多路复用机制
    if (sk->sk_state != TCP_CLOSE) {
        sk->sk_data_ready(sk);
    }
}

// socket就绪回调入口（最终调用epoll注册的ep_poll_callback）
void sock_def_readable(struct sock *sk)
{
    wake_up_interruptible_poll(&sk->sk_wq, EPOLLIN | EPOLLPRI);
}

// epoll 核心事件回调：ep_poll_callback（Linux 5.4，有删节）
static int ep_poll_callback(wait_queue_entry_t *wait, unsigned int mode,
                            int sync, void *key)
{
    struct epitem *epi = ep_item_from_wait(wait);  // 经 eppoll_entry 反查 epitem
    struct eventpoll *ep = epi->ep;
    int ewake = 0;
    unsigned long flags;

    spin_lock_irqsave(&ep->lock, flags);

    // 0. 溢出处理：若当前正在向用户态拷贝事件（ovflist 非空闲），
    //    把 epi 挂到溢出链表，避免在拷贝过程中改动就绪链表
    if (unlikely(ep->ovflist != EP_UNACTIVE_PTR)) {
        if (epi->next == EP_UNACTIVE_PTR) {
            epi->next = ep->ovflist;
            ep->ovflist = epi;
            ...
        }
    } else {
        // 1. 去重判断：不在就绪链表才入队（ep_is_linked 即检查 rdllink 是否为空）
        if (!ep_is_linked(epi)) {
            list_add_tail(&epi->rdllink, &ep->rdllist);
            ...
        }
    }

    // 2. 唤醒阻塞的 epoll_wait 进程（仅当确有事件可投递）
    if (!waitqueue_active(&ep->wq))
        goto out_unlock;
    if (ep_events_available(ep)) {
        ewake = 1;
        // 3. 持锁唤醒：默认唤醒全部等待者；EPOLLEXCLUSIVE 场景 nr_exclusive=1
        __wake_up_locked_key(&ep->wq, TASK_NORMAL, 0, (void *)key);
    }

out_unlock:
    spin_unlock_irqrestore(&ep->lock, flags);
    ...
    return 1;
}

// 阶段6 ep_send_events 中的核心分支（Linux 5.4，有删节）
revents = ep_item_poll(epi, &pt, 1);
if (!revents)
    continue;                                  // 当前已不就绪则跳过，不投递
...
if (epi->event.events & EPOLLONESHOT) {
    epi->event.events &= EP_PRIVATE_BITS;      // ONESHOT：投递后清事件位、禁用监听
} else if (!(epi->event.events & EPOLLET)) {
    list_add_tail(&epi->rdllink, &ep->rdllist);// LT：仍就绪则重新入队 → 下次继续触发
}
// ET：不重新入队。下次要再触发，必须等 fd 等待队列被再次唤醒
//（新数据到达等状态跃迁），这就是"单次触发"的源码本质

// 事件拷贝至用户态核心函数（Linux 5.4，有删节）
static int ep_send_events(struct eventpoll *ep,
                          struct epoll_event __user *events, int maxevents)
{
    struct epitem *epi, *tmp;
    LIST_HEAD(txlist);
    int eventcnt = 0;

    // 1. 持锁把就绪链表整体摘下（splice 到局部 txlist），避免在用户态
    //    拷贝期间阻塞回调入队（此时回调可先挂到 ovflist 溢出链表）
    spin_lock_irq(&ep->lock);
    if (!list_empty(&ep->rdllist))
        list_splice_tail_init(&ep->rdllist, &txlist);
    spin_unlock_irq(&ep->lock);

    // 2. 遍历 txlist：逐个重新 poll，取"当前真实就绪位"
    //    （防止投递已被消费的事件）
    list_for_each_entry_safe(epi, tmp, &txlist, rdllink) {
        __poll_t revents = ep_item_poll(epi, &pt, 1);
        if (!revents)
            continue;

        // 3. 内核态 -> 用户态拷贝（失败则把剩余事件放回就绪链表）
        if (!epoll_put_uevent(revents, epi->event.data, &esed)) {
            list_splice(txlist.prev, &ep->rdllist);
            ...
            return eventcnt;
        }
        eventcnt++;
        if (eventcnt >= maxevents)
            break;

        // 4. 核心分支：ONESHOT 清事件位 / LT 重新入队 / ET 不处理
        if (epi->event.events & EPOLLONESHOT)
            epi->event.events &= EP_PRIVATE_BITS;
        else if (!(epi->event.events & EPOLLET))
            list_add_tail(&epi->rdllink, &ep->rdllist);
    }
    ...
    return eventcnt;
}