io_uring (Async I/O)

Linux io_uring 비동기 I/O 인터페이스를 커널-사용자 공간 공유 링 모델 관점에서 심층 분석합니다. SQE/CQE 기반 제출·완료 경로, SQPOLL/IOPOLL/고정 버퍼/고정 파일 등 지연시간 최적화 모드, io-wq와 worker 오프로딩 동작, timeout·cancel·multishot·링크드 연산 같은 고급 제어 패턴, zero-copy 전송과 io_uring_cmd passthrough 활용, liburing 실전 코드 구조, epoll/스레드풀/AIO 대비 선택 기준, 보안 제약과 취약점 대응 전략, 운영 환경에서의 계측·튜닝·장애 분석 절차까지 고성능 서비스 개발에 필요한 핵심 내용을 종합적으로 다룹니다.

개요

io_uring은 Linux 5.1(2019)에서 도입된 비동기 I/O 인터페이스입니다. 기존 AIO(io_submit/io_getevents)의 한계(버퍼드 I/O 미지원, 시스템 콜 오버헤드)를 해결하며, 사용자-커널 간 공유 링 버퍼를 통해 시스템 콜 없이 I/O를 제출하고 완료를 수확합니다.

io_uring 발전 역사

io_uring은 Jens Axboe가 설계하여 Linux 5.1에서 처음 도입되었으며, 이후 매 커널 릴리스마다 새로운 opcode와 기능이 추가되어 범용 비동기 인터페이스로 발전하고 있습니다.

시스템 콜 인터페이스

io_uring은 3개의 시스템 콜로 동작합니다. 초기 설정 이후에는 io_uring_enter()조차 호출하지 않는 완전한 커널 폴링 모드도 가능합니다.

/* 1. io_uring 인스턴스 생성 */
int io_uring_setup(u32 entries, struct io_uring_params *params);
/* entries: SQ 크기 (2의 거듭제곱으로 올림)
 * params: 설정 플래그 + 커널이 채워주는 SQ/CQ 오프셋 정보
 * 반환: io_uring fd → mmap()으로 SQ/CQ 매핑 */

/* 2. I/O 제출 및 완료 대기 */
int io_uring_enter(int fd, u32 to_submit, u32 min_complete,
                    u32 flags, sigset_t *sig);
/* to_submit: 제출할 SQE 수
 * min_complete: 최소 완료 대기 수 (0이면 논블로킹)
 * flags: IORING_ENTER_GETEVENTS, IORING_ENTER_SQ_WAKEUP 등 */

/* 3. 리소스 사전 등록 (선택) */
int io_uring_register(int fd, u32 opcode, void *arg, u32 nr_args);
/* fd/버퍼를 커널에 사전 등록 → 매 I/O마다 fget/fput, 페이지 핀 비용 제거
 * IORING_REGISTER_BUFFERS: 고정 버퍼 등록
 * IORING_REGISTER_FILES: 고정 파일 디스크립터 등록 */

SQE / CQE 자료구조

SQE(Submission Queue Entry)는 I/O 요청을, CQE(Completion Queue Entry)는 완료 결과를 나타냅니다. 두 구조체 모두 고정 크기로 캐시 친화적입니다.

/* include/uapi/linux/io_uring.h */
struct io_uring_sqe {
    __u8    opcode;     /* IORING_OP_READ, IORING_OP_WRITE, ... */
    __u8    flags;      /* IOSQE_FIXED_FILE, IOSQE_IO_LINK, ... */
    __u16   ioprio;     /* I/O 우선순위 */
    __s32   fd;         /* 대상 파일 디스크립터 */
    union {
        __u64 off;      /* 파일 오프셋 */
        __u64 addr2;    /* 두 번째 주소 (opcode에 따라) */
    };
    union {
        __u64 addr;     /* 버퍼 주소 또는 iovec 포인터 */
        __u64 splice_off_in;
    };
    __u32   len;        /* 버퍼 크기 또는 iovec 수 */
    union {
        __kernel_rwf_t rw_flags;
        __u32          fsync_flags;
        __u32          poll_events;
        __u32          msg_flags;
        __u32          accept_flags;
    };
    __u64   user_data;  /* CQE에 그대로 복사 → 요청 식별자 */
    union {
        __u16 buf_index; /* 고정 버퍼 인덱스 */
        __u16 buf_group; /* 버퍼 그룹 ID (provided buffers) */
    };
    __u16   personality;
    union {
        __s32 splice_fd_in;
        __u32 file_index;
    };
    __u64   __pad2[2];
};  /* sizeof = 64 bytes (1 캐시라인) */

struct io_uring_cqe {
    __u64   user_data;  /* SQE에서 복사된 사용자 데이터 */
    __s32   res;        /* 결과값 (바이트 수 또는 -errno) */
    __u32   flags;      /* IORING_CQE_F_BUFFER, IORING_CQE_F_MORE */
};  /* sizeof = 16 bytes */

링 버퍼 동작 원리

SQ/CQ 링은 mmap()으로 사용자 공간에 매핑된 lock-free SPSC(Single-Producer Single-Consumer) 링 버퍼입니다. 메모리 배리어만으로 동기화합니다.

/* SQE 제출 과정 (사용자 공간) */
unsigned idx = sq->tail & sq->ring_mask;
struct io_uring_sqe *sqe = &sq->sqes[idx];

sqe->opcode  = IORING_OP_READ;
sqe->fd      = file_fd;
sqe->addr    = (unsigned long)buf;
sqe->len     = buf_size;
sqe->off     = offset;
sqe->user_data = my_request_id;

/* SQ tail 포인터 갱신 (write barrier 필수) */
io_uring_smp_store_release(&sq->tail, sq->tail + 1);
io_uring_enter(ring_fd, 1, 0, 0, NULL);

/* CQE 수확 과정 (사용자 공간) */
unsigned head = io_uring_smp_load_acquire(&cq->head);
while (head != cq->tail) {
    struct io_uring_cqe *cqe = &cq->cqes[head & cq->ring_mask];
    handle_completion(cqe->user_data, cqe->res);
    head++;
}
io_uring_smp_store_release(&cq->head, head);

mmap 메모리 레이아웃

io_uring의 SQ/CQ 링과 SQE 배열은 mmap()을 통해 사용자 공간에 매핑됩니다. 커널 5.4+ 이후 SQ와 CQ 링은 하나의 mmap 영역을 공유하여 메모리를 절약합니다.

/* mmap 설정 코드 (liburing 내부 동작) */
struct io_uring_params p;
int fd = io_uring_setup(256, &p);

/* 1. SQ Ring 매핑 (CQ Ring도 같은 영역에 포함) */
size_t sq_ring_sz = p.sq_off.array + p.sq_entries * sizeof(u32);
size_t cq_ring_sz = p.cq_off.cqes + p.cq_entries * sizeof(struct io_uring_cqe);
size_t ring_sz = sq_ring_sz > cq_ring_sz ? sq_ring_sz : cq_ring_sz;

void *sq_ptr = mmap(NULL, ring_sz, PROT_READ | PROT_WRITE,
                    MAP_SHARED | MAP_POPULATE, fd, IORING_OFF_SQ_RING);

/* SQ 필드 오프셋 (params.sq_off에서 제공) */
u32 *sq_head     = sq_ptr + p.sq_off.head;
u32 *sq_tail     = sq_ptr + p.sq_off.tail;
u32 *sq_mask     = sq_ptr + p.sq_off.ring_mask;
u32 *sq_entries  = sq_ptr + p.sq_off.ring_entries;
u32 *sq_flags    = sq_ptr + p.sq_off.flags;
u32 *sq_array    = sq_ptr + p.sq_off.array;

/* CQ 필드 오프셋 (같은 mmap 영역, params.cq_off에서 제공) */
u32 *cq_head     = sq_ptr + p.cq_off.head;    /* 5.4+: 같은 mmap */
u32 *cq_tail     = sq_ptr + p.cq_off.tail;
struct io_uring_cqe *cqes = sq_ptr + p.cq_off.cqes;

/* 2. SQE 배열 매핑 (별도 mmap 영역) */
struct io_uring_sqe *sqes = mmap(NULL,
    p.sq_entries * sizeof(struct io_uring_sqe),
    PROT_READ | PROT_WRITE, MAP_SHARED | MAP_POPULATE,
    fd, IORING_OFF_SQES);

SQE 간접 인덱싱 상세

SQ Ring에는 SQE를 직접 저장하지 않고, sq.array[]라는 간접 인덱스 배열이 있습니다. 이 배열의 각 항목은 별도 mmap된 sqes[] 배열의 인덱스를 가리킵니다.

/* 간접 인덱싱 (기본): sq.array[idx]가 sqes[] 인덱스를 가리킴 */
unsigned idx = sq_tail & sq_mask;
sq_array[idx] = idx;           /* 간접 인덱스 설정 (보통 idx == idx) */
struct io_uring_sqe *sqe = &sqes[idx];
sqe->opcode = IORING_OP_READ;
/* ... SQE 필드 설정 ... */

/* 간접 인덱싱의 장점: 순서 변경 가능 */
sq_array[0] = 2;  /* 첫 번째 제출할 SQE: sqes[2] */
sq_array[1] = 0;  /* 두 번째 제출할 SQE: sqes[0] */

/* 직접 인덱싱 (6.7+): sq.array 불필요 */
struct io_uring_params params = {
    .flags = IORING_SETUP_NO_SQARRAY,
};
/* sqes[sq_tail & mask]가 곧 SQE → 간접 참조 1단계 제거 */

주요 연산 (opcodes)

io_uring_params 플래그 상세

io_uring_setup() 호출 시 io_uring_params.flags에 설정하는 플래그들은 링의 동작 방식을 결정합니다.

동작 모드

기본 모드 (Interrupt Driven)

struct io_uring_params params = {};
int ring_fd = io_uring_setup(256, &params);
io_uring_enter(ring_fd, 1, 1, IORING_ENTER_GETEVENTS, NULL);

SQPOLL 모드 (커널 폴링)

커널 스레드(io_uring-sq)가 SQ를 지속적으로 폴링합니다. 시스템 콜 없이 SQ tail만 갱신하면 커널이 자동으로 처리합니다.

struct io_uring_params params = {
    .flags = IORING_SETUP_SQPOLL,
    .sq_thread_idle = 2000,  /* 2초 유휴 시 스레드 슬립 */
};
int ring_fd = io_uring_setup(256, &params);

/* 커널 스레드가 슬립했다면 깨워야 함 */
if (*sq->flags & IORING_SQ_NEED_WAKEUP)
    io_uring_enter(ring_fd, 0, 0, IORING_ENTER_SQ_WAKEUP, NULL);

IOPOLL 모드 (하드웨어 폴링)

커널이 블록 디바이스 완료를 인터럽트 대신 폴링으로 확인합니다. NVMe 등 고성능 스토리지에서 인터럽트 지연을 제거합니다. O_DIRECT 전용입니다.

struct io_uring_params params = {
    .flags = IORING_SETUP_IOPOLL,
};
/* SQPOLL + IOPOLL = 완전한 폴링 기반 I/O (시스템 콜 0, 인터럽트 0) */

고급 기능

SQE 링크 (Chaining)

/* write → fsync 순차 실행 보장 */
sqe1->opcode = IORING_OP_WRITE;
sqe1->flags  = IOSQE_IO_LINK;
sqe2->opcode = IORING_OP_FSYNC;
sqe2->flags  = 0;
/* IOSQE_IO_HARDLINK: 앞 SQE 실패해도 계속 실행 */

고정 파일/버퍼 (Registered Resources)

매 I/O마다 발생하는 fget()/fput()와 페이지 핀(GUP) 비용을 제거합니다.

int fds[] = {fd1, fd2, fd3};
io_uring_register(ring_fd, IORING_REGISTER_FILES, fds, 3);
sqe->flags |= IOSQE_FIXED_FILE;
sqe->fd = 0;  /* fds[0] = fd1 사용 */

struct iovec iovs[] = { { buf1, 4096 }, { buf2, 4096 } };
io_uring_register(ring_fd, IORING_REGISTER_BUFFERS, iovs, 2);
sqe->opcode = IORING_OP_READ_FIXED;
sqe->buf_index = 0;

Provided Buffers (커널 버퍼 선택)

버퍼 풀을 커널에 제공하고, 커널이 완료 시 적절한 버퍼를 자동 선택합니다.

struct io_uring_buf_ring *br;
br = mmap(..., ring_fd, IORING_OFF_PBUF_RING);
for (int i = 0; i < nr_bufs; i++)
    io_uring_buf_ring_add(br, bufs[i], buf_size, i, mask, i);
io_uring_buf_ring_advance(br, nr_bufs);

sqe->opcode = IORING_OP_RECV;
sqe->flags  = IOSQE_BUFFER_SELECT;
sqe->buf_group = group_id;

Multishot 연산

하나의 SQE로 여러 번의 CQE를 생성합니다. accept, recv, poll 등에서 반복적인 SQE 재제출 오버헤드를 제거합니다.

/* Multishot accept */
sqe->opcode = IORING_OP_ACCEPT;
sqe->fd     = listen_fd;
sqe->ioprio = IORING_ACCEPT_MULTISHOT;
/* 새 연결마다 CQE 생성, CQE.flags에 IORING_CQE_F_MORE 설정 */

/* Multishot recv */
sqe->opcode    = IORING_OP_RECV;
sqe->ioprio    = IORING_RECV_MULTISHOT;
sqe->flags     = IOSQE_BUFFER_SELECT;
sqe->buf_group = group_id;

Cancel / Timeout 연산 심화

IORING_OP_ASYNC_CANCEL

sqe->opcode = IORING_OP_ASYNC_CANCEL;
sqe->addr   = target_user_data;
/* 결과: 0=취소됨, -ENOENT=없음, -EALREADY=이미 완료 중 */

/* fd 기반 취소 (6.0+) */
sqe->fd    = target_fd;
sqe->flags = IORING_ASYNC_CANCEL_FD;

/* 모든 요청 취소 (6.1+) */
sqe->cancel_flags = IORING_ASYNC_CANCEL_ANY;

IORING_OP_TIMEOUT

struct __kernel_timespec ts = { .tv_sec = 2 };
sqe->opcode = IORING_OP_TIMEOUT;
sqe->addr   = (unsigned long)&ts;
sqe->len    = 1;
sqe->off    = 5;  /* 5개 CQE 완료되면 조기 해제 */
/* -ETIME=만료, 0=조기 해제, -ECANCELED=취소됨 */

IORING_OP_LINK_TIMEOUT

/* read가 3초 내 완료되지 않으면 취소 */
sqe1->opcode = IORING_OP_READ;
sqe1->flags  = IOSQE_IO_LINK;

struct __kernel_timespec ts = { .tv_sec = 3 };
sqe2->opcode = IORING_OP_LINK_TIMEOUT;
sqe2->addr   = (unsigned long)&ts;
sqe2->len    = 1;

Zero-copy 네트워킹

IORING_OP_SEND_ZC는 사용자 공간 버퍼를 복사 없이 커널 네트워크 스택에 직접 전달합니다.

sqe->opcode = IORING_OP_SEND_ZC;
sqe->fd     = sock_fd;
sqe->addr   = (unsigned long)send_buf;
sqe->len    = send_len;

/* 주의: 2개의 CQE가 생성됨
 * 1) 전송 완료 (IORING_CQE_F_MORE)
 * 2) notification: 버퍼 해제 가능 (IORING_CQE_F_NOTIF) */
if (cqe->flags & IORING_CQE_F_NOTIF)
    recycle_buffer(cqe->user_data);

MSG_RING — 링 간 메시징

IORING_OP_MSG_RING(커널 5.18+)은 한 io_uring 인스턴스에서 다른 인스턴스로 CQE를 직접 전송하는 연산입니다. 멀티스레드 환경에서 별도 동기화 없이 스레드 간 통신이 가능합니다.

/* MSG_RING: Ring A에서 Ring B로 데이터 전달 */
struct io_uring_sqe *sqe = io_uring_get_sqe(&ring_a);

io_uring_prep_msg_ring(sqe,
    ring_b.ring_fd,   /* 대상 ring fd */
    42,               /* CQE.res에 들어갈 값 */
    0xDEAD,           /* CQE.user_data에 들어갈 값 */
    0                 /* 플래그 */
);
io_uring_submit(&ring_a);

/* Ring B 쪽에서 CQE 수신 */
struct io_uring_cqe *cqe;
io_uring_wait_cqe(&ring_b, &cqe);
/* cqe->res = 42, cqe->user_data = 0xDEAD */

/* MSG_RING_FD: fd를 대상 ring에 전달 (6.3+) */
sqe = io_uring_get_sqe(&ring_a);
sqe->opcode   = IORING_OP_MSG_RING;
sqe->fd       = ring_b.ring_fd;
sqe->len      = IORING_MSG_SEND_FD;
sqe->addr     = 0;                /* CQE.user_data */
sqe->addr3    = client_fd;         /* 전달할 fd */
sqe->file_index = dest_slot;       /* 대상 ring의 fixed file 슬롯 */

FUSE io_uring 지원 (v6.14+)

커널 6.14에서 FUSE(Filesystem in Userspace)에 io_uring 지원이 추가되었습니다. 기존 FUSE는 /dev/fuse를 통한 read/write 시스템 콜로 커널↔유저스페이스 간 요청을 교환했으나, io_uring을 사용하면 시스템 콜 오버헤드와 컨텍스트 스위칭을 크게 줄일 수 있습니다.

io_uring_cmd (Passthrough)

IORING_OP_URING_CMD는 디바이스 드라이버에 io_uring을 통해 직접 커스텀 명령을 전달합니다. NVMe passthrough가 대표적입니다.

/* NVMe passthrough (IORING_SETUP_SQE128 필요) */
sqe->opcode = IORING_OP_URING_CMD;
sqe->fd     = nvme_ns_fd;       /* /dev/ng0n1 */
sqe->cmd_op = NVME_URING_CMD_IO;

struct nvme_uring_cmd *cmd = (struct nvme_uring_cmd *)sqe->cmd;
cmd->opcode  = nvme_cmd_read;
cmd->addr    = (__u64)buffer;
cmd->data_len = 4096;

/* 커널 드라이버 측 */
static const struct file_operations my_fops = {
    .uring_cmd = my_uring_cmd_handler,
};

CQE Overflow 처리

CQ 링이 가득 찬 상태에서 새 CQE가 생성되면 오버플로가 발생합니다. 커널은 내부 오버플로 리스트에 CQE를 보관하고, 사용자가 CQ에서 CQE를 소비하면 자동으로 옮겨줍니다.

/* 오버플로 감지 */
if (*sq->flags & IORING_SQ_CQ_OVERFLOW)
    io_uring_enter(ring_fd, 0, 0, IORING_ENTER_GETEVENTS, NULL);

/* 오버플로 방지: CQ 크기를 충분히 크게 */
params.flags |= IORING_SETUP_CQSIZE;
params.cq_entries = 4096;  /* SQ의 4배 이상 권장 */

CQ 링 원형 버퍼 내부 구조

CQ(Completion Queue) 링은 커널이 완료된 I/O 결과를 기록하고 사용자 공간이 이를 수확하는 lock-free SPSC 원형 버퍼입니다. SQ와 달리 간접 인덱싱 배열 없이 직접 인덱싱을 사용하여 구조가 더 단순합니다.

/* CQ 링 인덱싱 메커니즘 */
/* 커널: CQE 기록 후 tail 전진 */
unsigned tail = ctx->rings->cq.tail;
unsigned idx = tail & ctx->cq_mask;  /* cq_mask = cq_entries - 1 */
struct io_uring_cqe *cqe = &ctx->rings->cqes[idx];
cqe->user_data = req->cqe.user_data;
cqe->res       = req->cqe.res;
cqe->flags     = req->cqe.flags;
smp_store_release(&ctx->rings->cq.tail, tail + 1);

/* 유저: head ~ tail 범위에서 CQE 소비 */
unsigned head = io_uring_smp_load_acquire(cq->khead);
while (head != *cq->ktail) {
    struct io_uring_cqe *cqe = &cq->cqes[head & cq->ring_mask];
    process_cqe(cqe);
    head++;
}
io_uring_smp_store_release(cq->khead, head);

/* struct io_rings — CQ 관련 필드 (include/uapi/linux/io_uring.h) */
struct io_rings {
    struct io_uring sq, cq;       /* 각각 head/tail/flags/entries 포함 */
    u32 sq_ring_mask;              /* sq_entries - 1 */
    u32 cq_ring_mask;              /* cq_entries - 1 */
    u32 sq_ring_entries;           /* SQ 엔트리 수 */
    u32 cq_ring_entries;           /* CQ 엔트리 수 */
    u32 sq_dropped;                /* 드롭된 SQE 카운터 */
    u32 sq_flags;                  /* IORING_SQ_* 플래그 */
    u32 cq_flags;                  /* IORING_CQ_* 플래그 */
    u32 cq_overflow;               /* 오버플로 카운터 */
    struct io_uring_cqe cqes[];   /* CQE 배열 (가변 길이) */
};

CQE 필드 상세 분석

각 CQE는 16바이트(CQE32 확장 시 32바이트)로 3개의 필드로 구성됩니다: user_data(8B), res(4B), flags(4B). 이 필드들의 의미와 활용 패턴을 상세히 분석합니다.

user_data 필드와 요청 식별 패턴

user_data는 SQE 제출 시 설정한 8바이트 값이 CQE에 그대로 복사되는 식별자입니다. 커널은 이 값을 해석하지 않으며, 애플리케이션이 어떤 요청의 완료인지 식별하는 유일한 수단입니다.

/* 패턴 1: 포인터 캐스트 — 가장 직관적 */
struct my_request *req = malloc(sizeof(*req));
req->op = OP_READ;
req->buf = buffer;
sqe->user_data = (__u64)(uintptr_t)req;
/* CQE 수확 시 */
struct my_request *req = (void *)(uintptr_t)cqe->user_data;

/* 패턴 2: 태그드 유니온 — 상위 비트 = 타입, 하위 = 인덱스 */
enum { TAG_ACCEPT = 0, TAG_READ = 1, TAG_WRITE = 2 };
#define MAKE_UD(tag, idx) (((__u64)(tag) << 56) | (__u64)(idx))
#define UD_TAG(ud)       ((unsigned)((ud) >> 56))
#define UD_IDX(ud)       ((unsigned)((ud) & 0x00FFFFFFFFFFFFFF))
sqe->user_data = MAKE_UD(TAG_READ, conn_id);
/* CQE 수확 시 */
switch (UD_TAG(cqe->user_data)) {
    case TAG_READ:  handle_read(UD_IDX(cqe->user_data), cqe->res); break;
    case TAG_WRITE: handle_write(UD_IDX(cqe->user_data), cqe->res); break;
}

/* 패턴 3: 순차 ID + 해시맵 — 대규모 요청 추적 */
static __u64 next_id = 1;
__u64 id = next_id++;
hashmap_insert(pending, id, request_ctx);
sqe->user_data = id;
/* CQE 수확 시 */
struct request_ctx *ctx = hashmap_remove(pending, cqe->user_data);

res 필드: opcode별 결과 의미

res 필드는 요청의 결과를 나타내며, 양수는 성공(바이트 수, fd 번호 등), 0은 EOF 또는 성공, 음수는 -errno 에러 코드입니다. Short read/write는 res > 0이지만 요청한 크기보다 작은 경우로, 에러가 아닌 정상 동작입니다.

flags 필드: CQE 플래그 전체 참조

CQE의 flags 필드는 완료 결과에 대한 추가 메타데이터를 전달합니다. 하위 비트는 플래그, 상위 16비트는 버퍼 선택(provided buffers) 시 버퍼 ID를 인코딩합니다.

/* CQE 플래그 해석 패턴 */
#define IORING_CQE_BUFFER_SHIFT  16

if (cqe->flags & IORING_CQE_F_BUFFER) {
    unsigned buf_id = cqe->flags >> IORING_CQE_BUFFER_SHIFT;
    void *buf = bufs[buf_id];
    /* buf_id로 실제 버퍼 접근 */
}

if (cqe->flags & IORING_CQE_F_MORE) {
    /* multishot: 아직 더 올 CQE가 있음, SQE 재제출 불필요 */
} else {
    /* 마지막 CQE: multishot 종료, 필요 시 SQE 재제출 */
}

if (cqe->flags & IORING_CQE_F_NOTIF) {
    /* 제로카피 send: 커널이 버퍼를 해제함, 실제 전송 결과 아님 */
    return;  /* 알림만 — res 무시 */
}

커널 CQE 게시 내부 경로

커널이 I/O 완료 후 CQE를 사용자에게 전달하는 내부 경로를 추적합니다. 핵심 함수 체인은 io_req_complete_post() → io_fill_cqe_req() → io_commit_cqring() → io_cqring_ev_posted()입니다.

/* io_fill_cqe_req() — 간소화된 커널 코드 */
static bool io_fill_cqe_req(struct io_ring_ctx *ctx,
                             struct io_kiocb *req)
{
    struct io_uring_cqe *cqe;
    u32 tail = ctx->rings->cq.tail;

    /* CQ 가득 찼는지 확인 */
    if (tail - READ_ONCE(ctx->rings->cq.head) >= ctx->cq_entries) {
        /* 오버플로 리스트에 추가 */
        return io_cqring_event_overflow(ctx, req->cqe.user_data,
                                        req->cqe.res, req->cqe.flags);
    }

    cqe = &ctx->rings->cqes[tail & ctx->cq_mask];
    cqe->user_data = req->cqe.user_data;
    cqe->res       = req->cqe.res;
    cqe->flags     = req->cqe.flags;

    return true;
}

/* io_commit_cqring() — tail을 store_release로 갱신 */
static void io_commit_cqring(struct io_ring_ctx *ctx)
{
    smp_store_release(&ctx->rings->cq.tail,
                      ctx->cached_cq_tail);
}

/* io_cqring_ev_posted() — 대기자 깨우기 */
static void io_cqring_ev_posted(struct io_ring_ctx *ctx)
{
    if (wq_has_sleeper(&ctx->cq_wait))
        wake_up_all(&ctx->cq_wait);
    if (ctx->cq_ev_fd)
        eventfd_signal(ctx->cq_ev_fd, 1);
}

CQE 소비 패턴과 liburing API

liburing은 CQE 수확을 위한 다양한 API를 제공합니다. 상황에 맞는 소비 패턴 선택이 지연시간과 처리량에 직접 영향을 줍니다.

peek vs wait vs batch

/* 배치 소비 패턴 — 최적 성능 */
struct io_uring_cqe *cqes[256];
unsigned count, i;

/* 최소 1개 대기 후 가용한 만큼 배치 수확 */
io_uring_wait_cqe(&ring, &cqes[0]);
count = io_uring_peek_batch_cqe(&ring, cqes, 256);

for (i = 0; i < count; i++) {
    process_completion(cqes[i]->user_data,
                       cqes[i]->res,
                       cqes[i]->flags);
}
/* 한 번의 store_release로 모든 CQE 소비 완료 */
io_uring_cq_advance(&ring, count);

CQ 크기 선택 전략

CQ 크기는 성능과 메모리 사이의 트레이드오프입니다. 너무 작으면 오버플로가 발생하고, 너무 크면 메모리를 낭비합니다. Multishot 연산은 단일 SQE에서 무한 CQE를 생성할 수 있어 특별한 고려가 필요합니다.

/* IORING_SETUP_CQSIZE로 CQ 크기 커스텀 설정 */
struct io_uring_params params = {};
params.flags = IORING_SETUP_CQSIZE;
params.cq_entries = 4096;  /* 반드시 power-of-2 */

int ring_fd = io_uring_setup(512, &params);
/* 커널이 params.cq_entries를 실제 할당된 값으로 갱신 */

/* liburing 래퍼 */
struct io_uring ring;
struct io_uring_params p = { .flags = IORING_SETUP_CQSIZE, .cq_entries = 4096 };
io_uring_queue_init_params(512, &ring, &p);

/* 동적 크기 산정: multishot 연결 수 기반 */
unsigned sq_size = 256;
unsigned max_multishot_conns = 1000;
unsigned cq_size = next_power_of_2(sq_size * 2 + max_multishot_conns * 4);
/* 최소 SQ×2, multishot당 여유 4 CQE 확보 */

CQE 대기 메커니즘 심화

CQE를 대기하는 방법은 여러 가지이며, 각각 지연시간/CPU 사용량 특성이 다릅니다. 워크로드에 맞는 대기 전략 선택이 중요합니다.

/* EXT_ARG: 나노초 타임아웃 + 시그널 마스크 */
struct __kernel_timespec ts = { .tv_sec = 0, .tv_nsec = 500000000 }; /* 500ms */
struct io_uring_getevents_arg arg = {
    .sigmask    = (__u64)(uintptr_t)&sigmask,
    .sigmask_sz = sizeof(sigmask),
    .ts         = (__u64)(uintptr_t)&ts,
};
io_uring_enter(ring_fd, 0, 1,
               IORING_ENTER_GETEVENTS | IORING_ENTER_EXT_ARG,
               &arg);
/* 반환: 타임아웃 시 -ETIME, CQE 도착 시 0 */

/* eventfd + ASYNC: 비동기 완료만 시그널 */
int efd = eventfd(0, EFD_NONBLOCK);
io_uring_register_eventfd_async(&ring, efd);
/* epoll에 eventfd 등록 */
struct epoll_event ev = { .events = EPOLLIN, .data.fd = efd };
epoll_ctl(epfd, EPOLL_CTL_ADD, efd, &ev);

CQ 오버플로 내부 메커니즘

CQ 링이 가득 찬 상태에서 새 CQE가 발생하면 커널은 오버플로 리스트(struct io_overflow_cqe)에 보관합니다. 이 리스트의 생명주기와 플러시/드롭 메커니즘을 상세히 분석합니다.

/* struct io_overflow_cqe — 오버플로 CQE 보관 구조 */
struct io_overflow_cqe {
    struct list_head list;      /* ctx->cq_overflow_list에 연결 */
    struct io_uring_cqe cqe;    /* CQE 데이터 직접 내장 */
};

/* 오버플로 모니터링 패턴 */
static void check_overflow(struct io_uring *ring) {
    unsigned flags = IO_URING_READ_ONCE(*ring->sq.kflags);

    if (flags & IORING_SQ_CQ_OVERFLOW) {
        /* 오버플로 발생: CQ에서 CQE를 빨리 소비하여 플러시 유도 */
        fprintf(stderr, "CQ overflow detected!\n");

        /* GETEVENTS로 플러시 트리거 */
        io_uring_enter(ring->ring_fd, 0, 0,
                       IORING_ENTER_GETEVENTS, NULL);

        /* 드롭된 CQE 확인 */
        unsigned overflow = *ring->cq.koverflow;
        if (overflow)
            fprintf(stderr, "Dropped %u CQEs!\n", overflow);
    }
}

CQE 순서 보장과 완료 의미론

io_uring은 기본적으로 CQE 순서를 보장하지 않습니다. I/O가 완료되는 순서대로 CQE가 게시되므로, 빠른 연산이 느린 연산보다 먼저 완료될 수 있습니다. 링크와 드레인 플래그로 순서를 강제할 수 있습니다.

Multishot CQE 동작 상세

Multishot 연산은 하나의 SQE 제출로 다수의 CQE를 스트림으로 수신합니다. IORING_CQE_F_MORE 플래그가 설정된 CQE는 "아직 더 올 CQE가 있다"는 의미이며, 이 플래그 없이 도착한 CQE가 스트림의 종료를 나타냅니다.

/* Multishot recv CQE 처리 루프 */
void handle_multishot_recv(struct io_uring *ring,
                           struct io_uring_cqe *cqe,
                           int sock_fd)
{
    if (cqe->res < 0) {
        /* 에러: -ECONNRESET, -ECANCELED 등 */
        fprintf(stderr, "multishot recv error: %d\n", cqe->res);
        if (!(cqe->flags & IORING_CQE_F_MORE))
            resubmit_multishot_recv(ring, sock_fd);
        return;
    }

    if (cqe->res == 0) {
        /* 연결 종료 (EOF) */
        close_connection(sock_fd);
        return;
    }

    /* 성공: 버퍼 ID 추출 */
    if (cqe->flags & IORING_CQE_F_BUFFER) {
        unsigned buf_id = cqe->flags >> IORING_CQE_BUFFER_SHIFT;
        void *buf = provided_bufs[buf_id];
        process_data(buf, cqe->res);
        replenish_buffer(ring, buf_id);  /* 버퍼 재공급 */
    }

    /* F_MORE 없으면 multishot 종료 → 재제출 */
    if (!(cqe->flags & IORING_CQE_F_MORE)) {
        resubmit_multishot_recv(ring, sock_fd);
    }
}

CQ 성능 최적화

배치 소비와 tail advance 최적화

CQE를 하나씩 io_uring_cqe_seen()으로 소비하면 매번 smp_store_release가 발생합니다. 배치로 처리 후 한 번의 io_uring_cq_advance()를 호출하면 메모리 배리어 비용을 최소화할 수 있습니다.

DEFER_TASKRUN과 CQ 성능

IORING_SETUP_DEFER_TASKRUN | IORING_SETUP_SINGLE_ISSUER 조합은 CQE 게시를 io_uring_enter() 호출 시점으로 지연시킵니다. 이를 통해 task_work 인터럽트 없이 예측 가능한 지연시간을 제공합니다.

/* DEFER_TASKRUN 최적 폴링 루프 */
struct io_uring ring;
struct io_uring_params p = {
    .flags = IORING_SETUP_DEFER_TASKRUN
           | IORING_SETUP_SINGLE_ISSUER
           | IORING_SETUP_CQSIZE,
    .cq_entries = 4096,
};
io_uring_queue_init_params(512, &ring, &p);

while (running) {
    /* 제출할 SQE 준비 */
    prepare_submissions(&ring);
    io_uring_submit(&ring);

    /* CQE 대기 — DEFER_TASKRUN이므로 이 시점에 CQE 게시 */
    struct io_uring_cqe *cqe;
    io_uring_wait_cqe(&ring, &cqe);

    /* 배치 수확 */
    struct io_uring_cqe *cqes[256];
    unsigned n = io_uring_peek_batch_cqe(&ring, cqes, 256);

    for (unsigned i = 0; i < n; i++)
        dispatch_cqe(cqes[i]);

    io_uring_cq_advance(&ring, n);
}

CQE 에러 처리 패턴

견고한 io_uring 애플리케이션은 CQE의 res 값을 체계적으로 분류하고 적절히 처리해야 합니다. 양수(성공), 0(EOF/성공), 음수(에러)의 세 가지 범주와 각 에러 코드별 복구 전략을 정리합니다.

/* 견고한 CQE 에러 처리 함수 */
static void handle_cqe_result(struct io_uring *ring,
                               struct io_uring_cqe *cqe,
                               struct request *req)
{
    if (cqe->res < 0) {
        switch (-cqe->res) {
        case EAGAIN:
            /* 자원 부족: IOSQE_ASYNC로 재제출 */
            req->flags |= IOSQE_ASYNC;
            resubmit_request(ring, req);
            return;
        case ECANCELED:
            /* 취소됨: 자원 정리 */
            cleanup_request(req);
            return;
        case ECONNRESET:
        case EPIPE:
            /* 연결 끊김: 소켓 정리 */
            close_connection(req->fd);
            free_request(req);
            return;
        default:
            fprintf(stderr, "I/O error: %s (fd=%d)\n",
                    strerror(-cqe->res), req->fd);
            free_request(req);
            return;
        }
    }

    if (cqe->res == 0 && req->op == OP_READ) {
        /* EOF */
        handle_eof(req);
        return;
    }

    /* Short read/write 처리 */
    if (cqe->res > 0 && (unsigned)cqe->res < req->len) {
        /* 부분 완료: offset 조정 후 나머지 재제출 */
        req->buf  += cqe->res;
        req->len  -= cqe->res;
        req->off  += cqe->res;
        resubmit_request(ring, req);
        return;
    }

    /* 완전 완료 */
    complete_request(req, cqe->res);
}

eventfd 기반 CQ 알림 상세

eventfd를 io_uring에 등록하면 CQE 게시 시 자동으로 시그널이 발생합니다. 이를 통해 기존 epoll 기반 이벤트 루프에 io_uring을 통합할 수 있습니다. 일반 모드와 ASYNC 모드의 차이를 이해하는 것이 중요합니다.

/* eventfd 등록 + epoll 통합 */
struct io_uring ring;
io_uring_queue_init(256, &ring, 0);

/* 일반 eventfd: 모든 CQE에 시그널 */
int efd = eventfd(0, EFD_NONBLOCK);
io_uring_register_eventfd(&ring, efd);

/* 또는 ASYNC 변형: 비동기 완료만 시그널 */
/* io_uring_register_eventfd_async(&ring, efd); */

/* epoll에 eventfd 추가 */
int epfd = epoll_create1(0);
struct epoll_event ev = {
    .events = EPOLLIN,
    .data.fd = efd,
};
epoll_ctl(epfd, EPOLL_CTL_ADD, efd, &ev);

/* 이벤트 루프: io_uring + 다른 fd 통합 */
while (running) {
    struct epoll_event events[64];
    int n = epoll_wait(epfd, events, 64, -1);

    for (int i = 0; i < n; i++) {
        if (events[i].data.fd == efd) {
            /* eventfd 시그널: io_uring CQE 도착 */
            uint64_t val;
            read(efd, &val, sizeof(val));  /* eventfd 소비 */

            struct io_uring_cqe *cqe;
            while (io_uring_peek_cqe(&ring, &cqe) == 0) {
                process_cqe(cqe);
                io_uring_cqe_seen(&ring, cqe);
            }
        } else {
            /* 다른 fd 이벤트 처리 */
            handle_other_fd(events[i].data.fd);
        }
    }
}

/* eventfd 해제 */
io_uring_unregister_eventfd(&ring);
close(efd);

커널 내부 구현

/* io_uring/io_uring.c - 핵심 커널 자료구조 */
struct io_ring_ctx {
    struct {
        unsigned int        flags;
        unsigned int        sq_entries;
        unsigned int        cq_entries;
        struct io_rings     *rings;
        struct io_uring_sqe *sq_sqes;
    } ____cacheline_aligned_in_smp;

    struct io_sq_data    *sq_data;   /* SQPOLL 스레드 */
    struct io_wq        *io_wq;     /* 비동기 워커 풀 */
    struct io_rsrc_data *file_data;  /* 고정 파일 */
    struct io_rsrc_data *buf_data;   /* 고정 버퍼 */
};

/* SQE 처리 흐름 */
io_uring_enter()
  → io_submit_sqes()
      → io_get_sqe()         /* SQ에서 SQE 가져오기 */
      → io_init_req()        /* SQE → io_kiocb 변환 */
      → io_issue_sqe()       /* opcode별 핸들러 디스패치 */
          → io_read() → vfs_read()
          → io_req_complete()  /* 즉시 완료: CQE 게시 */
          → io_queue_async()   /* 블로킹: io-wq에 위임 */

io_kiocb 생명주기

io_kiocb는 io_uring 내부에서 각 I/O 요청을 추적하는 핵심 구조체입니다.

struct io_kiocb {
    struct file        *file;
    u8                  opcode;
    u64                 user_data;
    s32                 result;
    struct io_ring_ctx  *ctx;
    struct task_struct  *task;
    struct io_kiocb     *link;
    struct io_wq_work   work;
};

io-wq 워커 스레드 풀

즉시 완료되지 않는 (블로킹) 요청은 io-wq 커널 워커 스레드 풀로 넘겨집니다.

# 실행 중인 io-wq 워커 확인
ps -eo pid,comm | grep io_uring
ls /proc/<pid>/task/ | wc -l

task_work 완료 전달 메커니즘

io_uring은 I/O 완료를 제출자 태스크의 컨텍스트에서 처리하기 위해 커널의 task_work 메커니즘을 사용합니다. 완료가 어떤 컨텍스트(IRQ, softirq, 워커 스레드)에서 발생하든, 최종 CQE 게시와 사용자 알림은 제출자 태스크에서 실행됩니다.

/* DEFER_TASKRUN 최적 설정 */
struct io_uring_params params = {
    .flags = IORING_SETUP_SINGLE_ISSUER
           | IORING_SETUP_DEFER_TASKRUN
           | IORING_SETUP_COOP_TASKRUN,  /* DEFER에 포함되지만 명시적 설정 */
};
io_uring_queue_init_params(256, &ring, &params);

/* 이벤트 루프: GETEVENTS 시 적립된 task_work 일괄 실행 */
while (1) {
    io_uring_submit_and_wait(&ring, 1);
    /* ↑ 여기서 적립된 모든 task_work가 한번에 실행됨
     *   → CQE가 배치로 게시 → 한 번의 CQ 순회로 모두 처리 */

    struct io_uring_cqe *cqe;
    unsigned head, count = 0;
    io_uring_for_each_cqe(&ring, head, cqe) {
        process(cqe);
        count++;
    }
    io_uring_cq_advance(&ring, count);
}

io_uring 커널 소스 구조

io_uring 코드는 Linux 5.20(6.0) 이후 fs/io_uring.c 단일 파일(~27,000줄)에서 io_uring/ 디렉토리로 분리되어 약 30개 파일로 모듈화되었습니다.

liburing 사용 예제

liburing은 io_uring 시스템 콜의 저수준 복잡성을 추상화하는 헬퍼 라이브러리입니다.

#include <liburing.h>

int main(void) {
    struct io_uring ring;
    struct io_uring_sqe *sqe;
    struct io_uring_cqe *cqe;
    char buf[4096];

    io_uring_queue_init(256, &ring, 0);

    sqe = io_uring_get_sqe(&ring);
    io_uring_prep_read(sqe, fd, buf, sizeof(buf), 0);
    io_uring_sqe_set_data(sqe, my_context);

    io_uring_submit(&ring);

    io_uring_wait_cqe(&ring, &cqe);
    if (cqe->res < 0)
        fprintf(stderr, "I/O error: %s\\n", strerror(-cqe->res));
    else
        printf("Read %d bytes\\n", cqe->res);

    io_uring_cqe_seen(&ring, cqe);
    io_uring_queue_exit(&ring);
    return 0;
}

SQPOLL 모드 설정 예제

SQPOLL 모드를 사용하면 커널 스레드가 SQ를 폴링하여 시스템 콜 없이 I/O를 처리합니다.

#include <liburing.h>

int setup_sqpoll_ring(struct io_uring *ring) {
    struct io_uring_params params;
    memset(&params, 0, sizeof(params));

    params.flags = IORING_SETUP_SQPOLL;
    params.sq_thread_idle = 2000;  /* 2초 유휴 시 슬립 */
    params.sq_thread_cpu = 2;       /* CPU 2번에 고정 (선택) */

    return io_uring_queue_init_params(256, ring, &params);
}

void submit_sqpoll(struct io_uring *ring, int fd) {
    struct io_uring_sqe *sqe;
    char buf[4096];

    sqe = io_uring_get_sqe(ring);
    io_uring_prep_read(sqe, fd, buf, sizeof(buf), 0);

    /* SQPOLL 모드에서는 submit()만으로 충분 (syscall 없음) */
    io_uring_submit(ring);  /* 커널 스레드가 자동 처리 */

    /* 만약 커널 스레드가 슬립했다면 깨워야 함 */
    if (io_uring_sq_ring_needs_wakeup(ring)) {
        io_uring_enter(ring->ring_fd, 0, 0,
                        IORING_ENTER_SQ_WAKEUP, NULL);
    }
}

Multishot Accept 예제

Multishot accept는 하나의 SQE로 여러 연결을 처리합니다 (커널 5.19+).

#include <liburing.h>

int start_multishot_accept(struct io_uring *ring, int listen_fd) {
    struct io_uring_sqe *sqe;

    sqe = io_uring_get_sqe(ring);
    io_uring_prep_multishot_accept(sqe, listen_fd, NULL, NULL, 0);
    io_uring_sqe_set_data(sqe, (void*)(uintptr_t)listen_fd);

    io_uring_submit(ring);

    /* 이벤트 루프 */
    while (1) {
        struct io_uring_cqe *cqe;
        int ret = io_uring_wait_cqe(ring, &cqe);

        if (ret < 0) break;

        if (cqe->res < 0) {
            fprintf(stderr, "Accept error: %s\n", strerror(-cqe->res));
        } else {
            int client_fd = cqe->res;
            printf("Accepted connection: fd=%d\n", client_fd);

            /* 클라이언트 처리... */
            handle_client(ring, client_fd);
        }

        /* Multishot: CQE에 IORING_CQE_F_MORE 플래그가 있으면 계속 accept */
        if (!(cqe->flags & IORING_CQE_F_MORE)) {
            printf("Multishot accept ended, resubmitting...\n");
            start_multishot_accept(ring, listen_fd);
        }

        io_uring_cqe_seen(ring, cqe);
    }
}

Fixed Files 사용 예제

파일 디스크립터를 사전 등록하여 매 I/O마다 fd 조회 오버헤드를 제거합니다.

int use_fixed_files(struct io_uring *ring, int *fds, int nr_files) {
    /* 파일 디스크립터 배열 등록 */
    int ret = io_uring_register_files(ring, fds, nr_files);
    if (ret < 0) return ret;

    /* I/O 수행 시 fixed file index 사용 */
    struct io_uring_sqe *sqe = io_uring_get_sqe(ring);
    char buf[4096];

    io_uring_prep_read(sqe, 0, buf, sizeof(buf), 0);  /* index 0 사용 */
    sqe->flags |= IOSQE_FIXED_FILE;  /* Fixed file 플래그 */

    io_uring_submit(ring);

    /* 정리 */
    io_uring_unregister_files(ring);
    return 0;
}

Multi-ring 패턴

하나의 프로세스에서 여러 io_uring 인스턴스를 사용하면 잠금 경합 회피, I/O 유형별 격리, NUMA 최적화 등의 이점을 얻을 수 있습니다.

/* Per-thread ring 설정 + ATTACH_WQ로 워커 풀 공유 */
struct io_uring primary_ring, secondary_ring;

/* 1. 메인 ring 생성 (워커 풀 소유) */
struct io_uring_params p1 = {
    .flags = IORING_SETUP_SINGLE_ISSUER
           | IORING_SETUP_DEFER_TASKRUN,
};
io_uring_queue_init_params(256, &primary_ring, &p1);

/* 워커 수 제한: [bounded=8, unbounded=4] */
unsigned int workers[2] = { 8, 4 };
io_uring_register_iowq_max_workers(&primary_ring, workers);

/* 2. 보조 ring 생성 (메인 ring의 워커 풀 공유) */
struct io_uring_params p2 = {
    .flags = IORING_SETUP_SINGLE_ISSUER
           | IORING_SETUP_ATTACH_WQ,
    .wq_fd = primary_ring.ring_fd,  /* 메인 ring의 fd */
};
io_uring_queue_init_params(128, &secondary_ring, &p2);

이벤트 루프 설계 패턴

io_uring은 Proactor 패턴(비동기 I/O 완료 통지)을 따르며, epoll의 Reactor 패턴(준비 상태 통지)과 근본적으로 다릅니다.

io_uring 이벤트 루프 스켈레톤

#include <liburing.h>

/* 4단계 이벤트 루프: 준비 → 제출+대기 → 수확 → 디스패치 */
void event_loop(struct io_uring *ring) {
    while (!shutdown_requested) {
        /* 1단계: 새 SQE 준비 (타이머, accept 재등록 등) */
        prepare_pending_ops(ring);

        /* 2단계: 배치 제출 + 최소 1개 완료 대기 */
        io_uring_submit_and_wait(ring, 1);

        /* 3단계: CQE 수확 (배치 처리) */
        struct io_uring_cqe *cqe;
        unsigned head;
        unsigned count = 0;

        io_uring_for_each_cqe(ring, head, cqe) {
            /* 4단계: user_data 기반 디스패치 */
            struct request *req = (struct request *)cqe->user_data;
            switch (req->type) {
            case REQ_ACCEPT:
                handle_accept(ring, cqe); break;
            case REQ_READ:
                handle_read(ring, cqe);   break;
            case REQ_WRITE:
                handle_write(ring, cqe);  break;
            case REQ_TIMEOUT:
                handle_timeout(ring, cqe); break;
            }
            count++;
        }
        io_uring_cq_advance(ring, count);
    }
}

/* user_data 인코딩 전략:
 * - 구조체 포인터: (struct request *)sqe->user_data
 * - 인덱스 + 타입: upper 8bit = type, lower 56bit = index
 * - 태그: 고유 ID로 해시맵에서 컨텍스트 조회
 */

eventfd 통합: 기존 이벤트 루프와 연동

기존 epoll/select 기반 이벤트 루프에 io_uring을 통합하려면, eventfd를 등록하여 CQE 완료 시 epoll에 통지할 수 있습니다.

int efd = eventfd(0, EFD_NONBLOCK);

/* io_uring에 eventfd 등록: CQE 완료 시 efd에 시그널 */
io_uring_register_eventfd(&ring, efd);

/* epoll에 eventfd 추가 */
struct epoll_event ev = { .events = EPOLLIN, .data.fd = efd };
epoll_ctl(epoll_fd, EPOLL_CTL_ADD, efd, &ev);

/* 이벤트 루프에서 io_uring 완료를 epoll로 감지 */
while (1) {
    struct epoll_event events[64];
    int n = epoll_wait(epoll_fd, events, 64, -1);

    for (int i = 0; i < n; i++) {
        if (events[i].data.fd == efd) {
            uint64_t val;
            read(efd, &val, sizeof(val));
            /* io_uring CQE 처리 */
            drain_cqes(&ring);
        } else {
            /* 기존 소켓 이벤트 처리 */
        }
    }
}

성능 비교

벤치마크 데이터: libaio vs io_uring

4KB 랜덤 읽기, NVMe SSD (Samsung 980 PRO), QD=128 환경에서 측정한 실제 성능 비교:

순차 읽기 성능 (128KB, QD=32, buffered I/O):

io_uring vs epoll 상세 비교

실전 패턴: 고성능 Echo 서버

liburing 기반 multishot accept + provided buffers를 활용한 이벤트 루프 구현입니다.

#include <liburing.h>
#include <netinet/in.h>

#define ENTRIES   256
#define BUF_COUNT 64
#define BUF_SIZE  4096
#define BUF_BGID  0

enum { EV_ACCEPT, EV_RECV, EV_SEND };
struct conn_info { int fd; int type; };

static char bufs[BUF_COUNT][BUF_SIZE];
static struct io_uring_buf_ring *buf_ring;

static void setup_buf_ring(struct io_uring *ring) {
    struct io_uring_buf_reg reg = {
        .ring_entries = BUF_COUNT, .bgid = BUF_BGID,
    };
    buf_ring = io_uring_setup_buf_ring(ring, &reg, 0);
    for (int i = 0; i < BUF_COUNT; i++)
        io_uring_buf_ring_add(buf_ring, bufs[i], BUF_SIZE,
                              i, BUF_COUNT - 1, i);
    io_uring_buf_ring_advance(buf_ring, BUF_COUNT);
}

int main(void) {
    struct io_uring ring;
    io_uring_queue_init(ENTRIES, &ring, 0);
    setup_buf_ring(&ring);

    int listen_fd = /* socket + bind + listen */;

    /* Multishot accept 등록 */
    struct io_uring_sqe *sqe = io_uring_get_sqe(&ring);
    io_uring_prep_multishot_accept(sqe, listen_fd, NULL, NULL, 0);
    struct conn_info ci = { listen_fd, EV_ACCEPT };
    memcpy(&sqe->user_data, &ci, sizeof(ci));

    while (1) {
        io_uring_submit_and_wait(&ring, 1);

        struct io_uring_cqe *cqe;
        unsigned head, count = 0;
        io_uring_for_each_cqe(&ring, head, cqe) {
            struct conn_info ci;
            memcpy(&ci, &cqe->user_data, sizeof(ci));

            if (ci.type == EV_ACCEPT && cqe->res >= 0) {
                /* 새 연결: multishot recv 등록 */
                struct io_uring_sqe *s = io_uring_get_sqe(&ring);
                io_uring_prep_recv_multishot(s, cqe->res, NULL, 0, 0);
                s->flags |= IOSQE_BUFFER_SELECT;
                s->buf_group = BUF_BGID;
                struct conn_info ri = { cqe->res, EV_RECV };
                memcpy(&s->user_data, &ri, sizeof(ri));
            } else if (ci.type == EV_RECV && cqe->res > 0) {
                int bid = cqe->flags >> IORING_CQE_BUFFER_SHIFT;
                /* echo: 받은 데이터 그대로 전송 */
                struct io_uring_sqe *s = io_uring_get_sqe(&ring);
                io_uring_prep_send(s, ci.fd, bufs[bid], cqe->res, 0);
                struct conn_info si = { ci.fd, EV_SEND };
                memcpy(&s->user_data, &si, sizeof(si));
                /* 버퍼 반환 */
                io_uring_buf_ring_add(buf_ring, bufs[bid], BUF_SIZE,
                                      bid, BUF_COUNT - 1, 0);
                io_uring_buf_ring_advance(buf_ring, 1);
            } else if (ci.type == EV_RECV && cqe->res <= 0) {
                close(ci.fd);
            }
            count++;
        }
        io_uring_cq_advance(&ring, count);
    }
}

실전 패턴: 비동기 파일 복사

io_uring의 SQE 링크를 활용하여 read→write 체인으로 비동기 파일 복사를 구현합니다.

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

#define BLOCK_SIZE  (128 * 1024)
#define QUEUE_DEPTH 32

static int copy_file(const char *src, const char *dst) {
    struct io_uring ring;
    io_uring_queue_init(QUEUE_DEPTH, &ring, 0);

    int in_fd  = open(src, O_RDONLY);
    int out_fd = open(dst, O_WRONLY | O_CREAT | O_TRUNC, 0644);

    off_t offset = 0;
    int inflight = 0, done = 0;
    char *bufs[QUEUE_DEPTH];
    for (int i = 0; i < QUEUE_DEPTH; i++)
        bufs[i] = malloc(BLOCK_SIZE);

    while (!done || inflight) {
        while (!done && inflight < QUEUE_DEPTH) {
            /* read → write 링크 */
            struct io_uring_sqe *sqe_r = io_uring_get_sqe(&ring);
            io_uring_prep_read(sqe_r, in_fd, bufs[inflight],
                               BLOCK_SIZE, offset);
            sqe_r->flags |= IOSQE_IO_LINK;
            sqe_r->user_data = offset;

            struct io_uring_sqe *sqe_w = io_uring_get_sqe(&ring);
            io_uring_prep_write(sqe_w, out_fd, bufs[inflight],
                                BLOCK_SIZE, offset);
            sqe_w->user_data = offset | (1ULL << 63);

            offset += BLOCK_SIZE;
            inflight++;
        }
        io_uring_submit(&ring);

        struct io_uring_cqe *cqe;
        io_uring_wait_cqe(&ring, &cqe);
        if (cqe->res == 0 && !(cqe->user_data & (1ULL << 63)))
            done = 1;
        if (cqe->user_data & (1ULL << 63))
            inflight--;
        io_uring_cqe_seen(&ring, cqe);
    }

    for (int i = 0; i < QUEUE_DEPTH; i++) free(bufs[i]);
    close(in_fd); close(out_fd);
    io_uring_queue_exit(&ring);
    return 0;
}

실전 패턴: 데이터베이스 WAL 쓰기

데이터베이스의 WAL(Write-Ahead Log)은 내구성(durability)을 보장하면서도 높은 쓰기 처리량을 달성해야 합니다. io_uring의 SQE 링크(write → fdatasync)를 활용하면 배치 WAL 쓰기를 원자적으로 수행할 수 있습니다.

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

#define WAL_BATCH_MAX 32

struct wal_writer {
    struct io_uring ring;
    int             wal_fd;
    off_t           write_pos;
    int             pending;
};

int wal_init(struct wal_writer *w, const char *path) {
    io_uring_queue_init(256, &w->ring, 0);
    w->wal_fd = open(path, O_WRONLY | O_CREAT | O_APPEND, 0644);
    w->write_pos = 0;
    w->pending = 0;

    /* WAL fd를 고정 등록 → fget/fput 비용 제거 */
    io_uring_register_files(&w->ring, &w->wal_fd, 1);
    return 0;
}

/* WAL 배치 쓰기: write → fdatasync 링크 체인 */
int wal_write_batch(struct wal_writer *w,
                    struct iovec *entries, int nr_entries) {
    /* 1. 배치의 모든 엔트리를 하나의 writev로 작성 */
    struct io_uring_sqe *sqe = io_uring_get_sqe(&w->ring);
    io_uring_prep_writev(sqe, 0, entries, nr_entries, w->write_pos);
    sqe->flags |= IOSQE_FIXED_FILE | IOSQE_IO_LINK;
    sqe->user_data = 1;  /* write 식별 */

    /* 2. fdatasync로 디스크 플러시 보장 (링크: write 완료 후 실행) */
    sqe = io_uring_get_sqe(&w->ring);
    io_uring_prep_fsync(sqe, 0, IORING_FSYNC_DATASYNC);
    sqe->flags |= IOSQE_FIXED_FILE;
    sqe->user_data = 2;  /* fsync 식별 */

    /* 3. 제출 및 fsync 완료 대기 */
    io_uring_submit(&w->ring);

    struct io_uring_cqe *cqe;
    int remaining = 2;
    while (remaining > 0) {
        io_uring_wait_cqe(&w->ring, &cqe);
        if (cqe->res < 0) {
            fprintf(stderr, "WAL %s error: %s\n",
                    cqe->user_data == 1 ? "write" : "fsync",
                    strerror(-cqe->res));
            return -1;
        }
        if (cqe->user_data == 1)
            w->write_pos += cqe->res;
        io_uring_cqe_seen(&w->ring, cqe);
        remaining--;
    }
    return 0;  /* fsync 완료 = 내구성 보장 */
}

실전 패턴: 프록시 서버 (splice)

io_uring의 IORING_OP_SPLICE를 활용하면 사용자 공간 버퍼를 거치지 않고 커널 내에서 직접 데이터를 전달하는 제로카피 프록시를 구현할 수 있습니다.

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

/* splice 기반 프록시: client_fd → pipe → server_fd */
void proxy_splice(struct io_uring *ring,
                  int client_fd, int server_fd,
                  int pipe_rd, int pipe_wr) {
    struct io_uring_sqe *sqe;

    /* 1단계: client → pipe (SPLICE_F_MOVE로 페이지 이동) */
    sqe = io_uring_get_sqe(ring);
    io_uring_prep_splice(sqe, client_fd, -1,
                         pipe_wr, -1, 65536,
                         SPLICE_F_MOVE | SPLICE_F_NONBLOCK);
    sqe->flags |= IOSQE_IO_LINK;
    sqe->user_data = 1;  /* client→pipe */

    /* 2단계: pipe → server (링크: 1단계 완료 후 실행) */
    sqe = io_uring_get_sqe(ring);
    io_uring_prep_splice(sqe, pipe_rd, -1,
                         server_fd, -1, 65536,
                         SPLICE_F_MOVE | SPLICE_F_NONBLOCK);
    sqe->user_data = 2;  /* pipe→server */

    io_uring_submit(ring);
}

io_uring Restrictions (샌드박싱)

IORING_REGISTER_RESTRICTIONS를 사용하면 허용되는 opcode, 플래그, 등록 연산을 제한할 수 있습니다.

struct io_uring_params params = {
    .flags = IORING_SETUP_R_DISABLED,
};
int ring_fd = io_uring_setup(256, &params);

struct io_uring_restriction res[] = {
    { .opcode = IORING_RESTRICTION_SQE_OP,
      .sqe_op = IORING_OP_READ },
    { .opcode = IORING_RESTRICTION_SQE_OP,
      .sqe_op = IORING_OP_WRITE },
    { .opcode = IORING_RESTRICTION_SQE_FLAGS_ALLOWED,
      .sqe_flags = IOSQE_FIXED_FILE },
    { .opcode = IORING_RESTRICTION_REGISTER_OP,
      .register_op = IORING_REGISTER_FILES },
};
io_uring_register(ring_fd, IORING_REGISTER_RESTRICTIONS,
                  res, sizeof(res) / sizeof(res[0]));

/* ring 활성화 (이후 restriction 변경 불가) */
io_uring_register(ring_fd, IORING_REGISTER_ENABLE_RINGS,
                  NULL, 0);

io_uring 디버깅

/proc/PID/fdinfo

# io_uring fd의 상세 정보 확인
cat /proc/<pid>/fdinfo/<uring_fd>
# SqSize, CqSize, SqThreadCpu, UserFiles, UserBufs 등 출력

io_uring tracepoints

# 사용 가능한 io_uring tracepoint 목록
ls /sys/kernel/tracing/events/io_uring/
# io_uring_create, io_uring_submit_sqe, io_uring_complete,
# io_uring_queue_async_work, io_uring_poll_arm, io_uring_task_add

# ftrace로 io_uring 이벤트 추적
echo 1 > /sys/kernel/tracing/events/io_uring/enable
cat /sys/kernel/tracing/trace_pipe

bpftrace 원라이너

# io_uring SQE 제출 추적 (opcode별 카운트)
bpftrace -e 'tracepoint:io_uring:io_uring_submit_sqe {
    @ops[args->opcode] = count();
}'

# io_uring 완료 지연 시간 히스토그램
bpftrace -e '
tracepoint:io_uring:io_uring_submit_sqe {
    @start[args->req] = nsecs;
}
tracepoint:io_uring:io_uring_complete /@start[args->req]/ {
    @latency_us = hist((nsecs - @start[args->req]) / 1000);
    delete(@start[args->req]);
}'

# CQE 오버플로 감지
bpftrace -e 'kprobe:io_cqring_overflow_flush {
    @overflow = count();
}'

문제 해결 가이드

일반적인 오류와 해결

성능 저하 진단

1. 시스템 콜 오버헤드 확인

# io_uring_enter() 호출 빈도 측정
perf stat -e 'syscalls:sys_enter_io_uring_enter' ./my_app

# SQPOLL 모드가 제대로 동작하는지 확인 (0회여야 함)

2. I/O 지연 프로파일링

# SQE 제출부터 CQE 완료까지 지연 시간 분포
bpftrace -e '
tracepoint:io_uring:io_uring_submit_sqe {
    @start[args->req] = nsecs;
}
tracepoint:io_uring:io_uring_complete /@start[args->req]/ {
    @latency_us = hist((nsecs - @start[args->req]) / 1000);
    delete(@start[args->req]);
}
interval:s:10 {
    print(@latency_us);
    clear(@latency_us);
}'

3. CQ 처리 병목 확인

/* CQ 처리 루프에서 한 번에 처리하는 CQE 수 측정 */
unsigned int count = 0, head;
struct io_uring_cqe *cqe;

io_uring_for_each_cqe(ring, head, cqe) {
    count++;
    /* 처리 */
}
printf("Batch size: %u\n", count);  /* 1에 가까우면 배치 효과 없음 */

4. 워커 스레드 포화 확인

# io-wq 워커 스레드 생성 추적
bpftrace -e 'kprobe:io_wq_create { @wq_creates = count(); }'

# 대기 중인 작업 수 (높으면 워커 부족)
cat /proc/<pid>/fdinfo/<uring_fd> | grep SqThreadIdle

성능 최적화 체크리스트

피해야 할 안티 패턴

NUMA 최적화

다중 소켓 서버에서 io_uring 성능을 극대화하려면 NUMA(Non-Uniform Memory Access) 토폴로지를 고려한 설정이 필수입니다. 메모리 접근 지연이 로컬 노드 대비 원격 노드에서 2~3배 차이 나므로, 링 버퍼·워커·버퍼 모두 동일 NUMA 노드에 배치해야 합니다.

#define _GNU_SOURCE
#include <liburing.h>
#include <numa.h>
#include <sched.h>

int setup_numa_ring(struct io_uring *ring, int numa_node, int sqpoll_cpu) {
    /* 1. 현재 스레드를 NUMA 노드에 바인딩 */
    struct bitmask *mask = numa_allocate_nodemask();
    numa_bitmask_setbit(mask, numa_node);
    numa_bind(mask);
    numa_bitmask_free(mask);

    /* 2. SQPOLL 스레드를 로컬 CPU에 고정 */
    struct io_uring_params params = {
        .flags = IORING_SETUP_SQPOLL | IORING_SETUP_SQ_AFF
               | IORING_SETUP_SINGLE_ISSUER,
        .sq_thread_cpu  = sqpoll_cpu,
        .sq_thread_idle = 2000,
    };
    int ret = io_uring_queue_init_params(256, ring, &params);
    if (ret < 0) return ret;

    /* 3. io-wq 워커도 같은 NUMA 노드 CPU에 제한 */
    cpu_set_t cpuset;
    CPU_ZERO(&cpuset);
    for (int c = numa_node * 8; c < (numa_node + 1) * 8; c++)
        CPU_SET(c, &cpuset);
    io_uring_register_iowq_aff(ring, sizeof(cpuset), &cpuset);

    /* 4. 고정 버퍼를 로컬 NUMA 노드에 할당 */
    void *buf = numa_alloc_onnode(4096 * 64, numa_node);
    struct iovec iov = { .iov_base = buf, .iov_len = 4096 * 64 };
    io_uring_register_buffers(ring, &iov, 1);

    return 0;
}

메모리 배리어와 순서 보장

io_uring의 SQ/CQ 링은 lock-free SPSC(Single-Producer Single-Consumer) 큐입니다. 뮤텍스 대신 메모리 배리어(memory barrier)만으로 생산자-소비자 간 데이터 가시성을 보장합니다. 배리어를 잘못 사용하면 데이터 손실이나 스톨이 발생할 수 있으므로 정확한 이해가 필요합니다.

아키텍처별 배리어 매핑

/* 올바른 원시(raw) SQ 제출 코드 (liburing 없이) */

/* 1. SQE 작성 — 데이터가 먼저 기록되어야 함 */
struct io_uring_sqe *sqe = &sq->sqes[sq->tail & sq->ring_mask];
sqe->opcode    = IORING_OP_READ;
sqe->fd        = fd;
sqe->addr      = (unsigned long)buf;
sqe->len       = len;
sqe->user_data = my_id;

/* 2. 간접 인덱스 배열 설정 (NO_SQARRAY 아닌 경우) */
sq->array[sq->tail & sq->ring_mask] = sq->tail & sq->ring_mask;

/* 3. store_release: SQE 내용이 반드시 tail 갱신 전에 가시적이어야 함
 *    이 배리어가 없으면 커널이 아직 기록되지 않은 SQE를 읽을 수 있음 */
io_uring_smp_store_release(sq->tail_ptr, sq->tail + 1);

/* 4. 커널 통지 (SQPOLL이 아닌 경우) */
io_uring_enter(ring_fd, 1, 0, 0, NULL);

/* === CQE 수확 === */

/* 5. load_acquire: tail 값을 읽은 후에야 CQE 데이터에 접근
 *    이 배리어가 없으면 커널이 아직 기록 중인 CQE를 읽을 수 있음 */
unsigned tail = io_uring_smp_load_acquire(cq->tail_ptr);
unsigned head = *cq->head_ptr;

while (head != tail) {
    struct io_uring_cqe *cqe = &cq->cqes[head & cq->ring_mask];
    process(cqe->user_data, cqe->res);
    head++;
}

/* 6. store_release: CQE 읽기 완료 후 head 갱신
 *    이 배리어가 없으면 커널이 아직 읽는 중인 슬롯을 재사용할 수 있음 */
io_uring_smp_store_release(cq->head_ptr, head);

보안 고려사항

io_uring의 강력한 기능은 보안 관점에서 주의가 필요합니다. 공유 메모리를 통한 시스템 콜 우회로 seccomp 필터링이 어렵고, 커널 공격 표면이 넓습니다.

# io_uring 사용 제한 (Linux 5.12.4+)
# 0: 모든 사용자 허용 (기본)
# 1: 권한 없는 사용자 비활성화
# 2: 모든 사용자 비활성화
sysctl -w kernel.io_uring_disabled=1

# Docker/Kubernetes: seccomp 프로파일에서 io_uring_* 차단

io_uring 주요 보안 취약점 사례

io_uring은 Linux 5.1에서 도입된 이후 빠른 기능 확장과 함께 다수의 심각한 보안 취약점이 발견되었습니다. 복잡한 비동기 상태 관리, 커널 스레드 기반의 SQPOLL, 다양한 opcode의 조합 등이 공격 면적을 크게 확장시킵니다. 2021~2023년에 CVE가 집중 발생하여, Google이 Android/ChromeOS에서 io_uring을 완전 비활성화하는 결정을 내리기도 했습니다.

/* io_uring 취약점 타임라인 (주요 항목) */

/*
 * 2021:
 * CVE-2021-20226  — io_uring close 연산에서 UAF
 * CVE-2021-41073  — 파일 등록 타입 혼동 → 권한 상승
 * CVE-2021-3491   — io_uring PROVIDE_BUFFERS OOB 쓰기
 *
 * 2022:
 * CVE-2022-29582  — LINK_TIMEOUT UAF (타이머 경쟁 조건)
 * CVE-2022-1043   — io_uring sendmsg/recvmsg UAF
 * CVE-2022-2602   — io_uring + Unix socket GC UAF
 *
 * 2023:
 * CVE-2023-2598   — 고정 버퍼 경계 초과
 * CVE-2023-2235   — io_uring timer의 이중 해제
 * CVE-2023-21400  — io_uring 파일 테이블 오프셋 UAF
 *
 * 근본 원인 분류:
 * - Use-After-Free: ~60% (비동기 생명주기 관리 실패)
 * - 경쟁 조건: ~20% (완료/취소/타임아웃 간 race)
 * - 범위 초과: ~15% (버퍼/인덱스 경계 검사 누락)
 * - 타입 혼동: ~5% (파일/소켓 타입 검증 누락)
 */

/* io_uring 비동기 생명주기 관리의 복잡성 */
struct io_kiocb {
    /* 하나의 요청(SQE)에 대한 커널 제어 블록
     * 생명주기:
     *   submit → queued → in_flight → completed → freed
     *
     * 위험 지점:
     * 1. cancel과 complete가 동시에 발생 (race)
     * 2. linked request 체인에서 중간 요청 실패 시 후속 정리
     * 3. SQPOLL 커널 스레드와 사용자 스레드의 동시 접근
     * 4. timeout과 target 요청의 상호 참조 해제
     */
    struct io_ring_ctx *ctx;     /* io_uring 인스턴스 */
    u8 opcode;                    /* 연산 종류 */
    struct io_kiocb *link;       /* 다음 연결된 요청 */
    struct io_tw_state tw;       /* task work 상태 */
    atomic_t refs;                /* 참조 카운트 */
};

/* io_uring 보안 설정 권장 */
# 시스템 전체에서 io_uring 비활성화 (보안 우선 환경)
sysctl -w kernel.io_uring_disabled=2  # 0=허용, 1=비특권 차단, 2=완전 차단

# 비특권 사용자만 차단 (일반 서버)
sysctl -w kernel.io_uring_disabled=1

레거시 Linux AIO

Linux AIO(Asynchronous I/O)는 Linux 2.5(2002)에 도입된 비동기 I/O 인터페이스로, io_uring(Linux 5.1, 2019)의 전신입니다. O_DIRECT 필수, 파일 I/O 전용, 복잡한 API 등의 한계로 현재는 유지보수 모드이며 새 프로젝트는 io_uring을 권장합니다.

동기 I/O vs 비동기 I/O

Linux AIO 시스템 콜

Linux AIO는 5개의 시스템 콜로 구성됩니다.

libaio 예제

#include <libaio.h>

io_context_t ctx = 0;
struct iocb *iocbs[DEPTH];
struct io_event events[DEPTH];

/* 1. AIO 컨텍스트 생성 */
io_setup(DEPTH, &ctx);

/* 2. O_DIRECT로 파일 열기 (필수!) */
int fd = open("datafile.bin", O_RDONLY | O_DIRECT);

/* 3. IOCB 초기화 및 제출 */
io_prep_pread(iocbs[0], fd, buffer, 4096, 0);
io_submit(ctx, 1, iocbs);

/* 4. 완료 대기 */
io_getevents(ctx, 1, DEPTH, events, NULL);
io_destroy(ctx);

O_DIRECT 요구사항

Linux AIO의 한계

• O_DIRECT 강제: Buffered I/O에서 비효율적
• 파일 I/O만 지원: 네트워크 소켓, 파이프 등 미지원
• 복잡한 API: 시스템 콜 직접 사용 어려움
• 메타데이터 연산 미지원: open(), stat(), mkdir() 등 블로킹

성능 벤치마크

Linux AIO 사용 시점

io_uring 채택 현황

io_uring은 도입 이후 빠르게 주요 인프라 프로젝트에 채택되고 있습니다. 다음은 io_uring을 적극적으로 활용하거나 실험하고 있는 대표적인 프로젝트입니다.

언어별 생태계

io_uring_register 전체 연산 참조

io_uring_register() 시스템 콜은 리소스 사전 등록, 기능 조회, 워커 제어 등 io_uring 인스턴스의 설정을 관리합니다. 다음은 전체 등록 연산 목록입니다.

기능 탐지: IORING_REGISTER_PROBE

런타임에 커널이 지원하는 opcode를 확인할 수 있습니다. 다양한 커널 버전에서 동작해야 하는 애플리케이션에 필수적입니다.

#include <liburing.h>
#include <stdio.h>

void probe_io_uring(struct io_uring *ring) {
    struct io_uring_probe *probe = io_uring_get_probe_ring(ring);
    if (!probe) {
        perror("probe not supported");
        return;
    }

    const char *op_names[] = {
        [IORING_OP_NOP]       = "NOP",
        [IORING_OP_READV]     = "READV",
        [IORING_OP_WRITEV]    = "WRITEV",
        [IORING_OP_READ]      = "READ",
        [IORING_OP_WRITE]     = "WRITE",
        [IORING_OP_SEND_ZC]  = "SEND_ZC",
        [IORING_OP_URING_CMD] = "URING_CMD",
    };

    for (int i = 0; i < probe->ops_len; i++) {
        if (probe->ops[i].flags & IO_URING_OP_SUPPORTED) {
            printf("  op %d (%s): supported\n",
                   i, i < sizeof(op_names)/sizeof(*op_names)
                      ? op_names[i] : "unknown");
        }
    }
    io_uring_free_probe(probe);
}

/* 특정 opcode 지원 여부 간편 확인 */
bool supports_op(struct io_uring *ring, int op) {
    struct io_uring_probe *p = io_uring_get_probe_ring(ring);
    bool ok = p && io_uring_opcode_supported(p, op);
    io_uring_free_probe(p);
    return ok;
}

NAPI Busy-Poll 통합

커널 6.9에서 도입된 IORING_REGISTER_NAPI는 io_uring과 네트워크 NAPI(New API) 폴링을 통합하여, 패킷 수신 시 인터럽트 대신 busy-poll을 사용해 네트워크 지연을 극적으로 줄입니다. 일반적인 인터럽트 경로에서 10~50μs 걸리는 패킷 수신이, busy-poll을 통해 2~5μs로 단축됩니다.

#include <liburing.h>

/* NAPI busy-poll 등록 (커널 6.9+) */
struct io_uring ring;
io_uring_queue_init(256, &ring, 0);

struct io_uring_napi napi = {
    .busy_poll_to = 100,    /* busy-poll 타임아웃: 100μs */
    .prefer_busy_poll = 1,  /* busy-poll 우선 */
};
io_uring_register_napi(&ring, &napi);

/* recv SQE 등록 */
struct io_uring_sqe *sqe = io_uring_get_sqe(&ring);
io_uring_prep_recv(sqe, sock_fd, buf, buf_len, 0);
io_uring_submit(&ring);

/* io_uring_enter(GETEVENTS) 시 내부적으로 napi_busy_loop() 호출
 * → NIC 드라이버의 poll 함수를 직접 호출하여 패킷 수확
 * → IRQ/softirq 경로를 완전히 우회 */
struct io_uring_cqe *cqe;
io_uring_wait_cqe(&ring, &cqe);  /* 여기서 busy-poll 발생 */

/* 해제 */
io_uring_unregister_napi(&ring, &napi);

Direct Descriptors (직접 파일 할당)

Direct Descriptors는 accept(), open() 등으로 생성되는 파일 디스크립터를 프로세스 fd 테이블에 설치하지 않고, io_uring의 fixed file 테이블에 직접 등록하는 기능입니다. 프로세스 fd 테이블의 잠금(fdget()/fdput())과 fd 번호 할당 오버헤드를 완전히 제거합니다.

#include <liburing.h>

/* 1. Fixed file 테이블 초기 할당 (빈 슬롯) */
int fds[1024];
memset(fds, -1, sizeof(fds));  /* -1 = 빈 슬롯 */
io_uring_register_files(&ring, fds, 1024);

/* 또는: 할당 범위 지정 (6.0+) */
struct io_uring_file_index_range range = {
    .off = 0, .len = 1024,
};
io_uring_register_file_alloc_range(&ring, range.off, range.len);

/* 2. Direct accept: 프로세스 fd 테이블을 거치지 않고 직접 fixed file에 설치 */
struct io_uring_sqe *sqe = io_uring_get_sqe(&ring);
io_uring_prep_multishot_accept_direct(sqe, listen_fd, NULL, NULL, 0);
/* IORING_FILE_INDEX_ALLOC → 커널이 빈 슬롯 자동 선택 */

/* 3. CQE에서 fixed file index 확인 */
struct io_uring_cqe *cqe;
io_uring_wait_cqe(&ring, &cqe);
int file_index = cqe->res;  /* fixed file 슬롯 인덱스 */

/* 4. Fixed file로 I/O 수행 */
sqe = io_uring_get_sqe(&ring);
io_uring_prep_recv(sqe, file_index, buf, len, 0);
sqe->flags |= IOSQE_FIXED_FILE;  /* 필수: fixed file 사용 표시 */

/* 5. 연결 종료 시: CLOSE_DIRECT로 슬롯만 해제 (process fd 테이블 미사용) */
sqe = io_uring_get_sqe(&ring);
io_uring_prep_close_direct(sqe, file_index);

/* 6. 필요 시 fixed file을 프로세스 fd로 변환 (6.12+) */
sqe = io_uring_get_sqe(&ring);
sqe->opcode = IORING_OP_FIXED_FD_INSTALL;
sqe->fd = file_index;
sqe->flags = IOSQE_FIXED_FILE;
/* CQE.res = 프로세스 fd 번호 (일반 fd처럼 사용 가능) */

CQE32 / SQE128 확장 포맷

기본 SQE는 64바이트, CQE는 16바이트입니다. IORING_SETUP_SQE128과 IORING_SETUP_CQE32 플래그를 사용하면 각각 128바이트, 32바이트로 확장하여 추가 데이터를 전달할 수 있습니다. NVMe passthrough(io_uring_cmd)에서 주로 사용됩니다.

/* SQE128 + CQE32 링 설정 (NVMe passthrough용) */
struct io_uring_params params = {
    .flags = IORING_SETUP_SQE128   /* SQE를 128바이트로 확장 */
           | IORING_SETUP_CQE32,   /* CQE를 32바이트로 확장 */
};
io_uring_queue_init_params(64, &ring, &params);

/* SQE128 mmap 크기: sq_entries × 128 (기본의 2배) */
/* CQE32 mmap 크기: cq_entries × 32 (기본의 2배) */

/* NVMe passthrough 예시 */
struct io_uring_sqe *sqe = io_uring_get_sqe(&ring);
sqe->opcode   = IORING_OP_URING_CMD;
sqe->fd       = nvme_ns_fd;
sqe->cmd_op   = NVME_URING_CMD_IO;

/* 확장 영역(offset 64~127)에 NVMe 커맨드 배치 */
struct nvme_uring_cmd *cmd = (struct nvme_uring_cmd *)sqe->cmd;
cmd->opcode   = nvme_cmd_read;
cmd->nsid     = 1;
cmd->addr     = (__u64)buffer;
cmd->data_len = 4096;
cmd->cdw10    = lba & 0xFFFFFFFF;
cmd->cdw11    = lba >> 32;
cmd->cdw12    = (4096 / 512) - 1;  /* 블록 수 */

io_uring_submit(&ring);

/* CQE32에서 확장 결과 읽기 */
struct io_uring_cqe *cqe;
io_uring_wait_cqe(&ring, &cqe);
__u64 extra1 = io_uring_cqe_get_extra1(cqe);  /* NVMe 결과 DW0 */
__u64 extra2 = io_uring_cqe_get_extra2(cqe);  /* NVMe 결과 DW1 */

Buffered I/O 내부 경로

io_uring이 기존 Linux AIO와 결정적으로 다른 점 중 하나는 Buffered I/O를 진정한 비동기로 처리할 수 있다는 것입니다. 페이지 캐시 히트 시 즉시 완료하고, 캐시 미스 시 자동으로 io-wq 워커에 위임하여 블로킹 없이 처리합니다.

Registered Ring FD 최적화

IORING_REGISTER_RING_FDS(5.18+)는 io_uring 링 자체의 fd를 커널 내부 테이블에 등록하여, io_uring_enter() 호출 시 fdget()/fdput() 오버헤드를 제거합니다. 고빈도로 io_uring_enter()를 호출하는 환경에서 유효합니다.

#include <liburing.h>

struct io_uring ring;
io_uring_queue_init(256, &ring, 0);

/* Ring fd를 커널에 등록 → enter_ring_fd 사용 가능 */
int ret = io_uring_register_ring_fd(&ring);
if (ret == 1) {
    /* 이후 io_uring_enter()는 등록된 인덱스를 사용
     * → fdget/fdput 스킵 → 시스템 콜당 ~200ns 절약
     * liburing이 자동으로 enter_ring_fd 사용 */
}

/* 일반 I/O 수행 — 내부적으로 최적화된 enter 경로 사용 */
io_uring_submit(&ring);

/* 해제 */
io_uring_unregister_ring_fd(&ring);

kTLS + io_uring 통합

커널 TLS(kTLS)는 TLS 암호화/복호화를 커널 공간에서 수행하여, 사용자 공간 TLS 라이브러리(OpenSSL 등)의 복사 오버헤드를 제거합니다. io_uring의 send/recv와 결합하면 TLS 전송도 비동기 + 제로카피로 처리할 수 있습니다.

#include <linux/tls.h>
#include <liburing.h>

/* 1. TCP 소켓에 kTLS 설정 (OpenSSL 핸드셰이크 후) */
struct tls12_crypto_info_aes_gcm_128 crypto_info;
crypto_info.info.version     = TLS_1_2_VERSION;
crypto_info.info.cipher_type = TLS_CIPHER_AES_GCM_128;
/* iv, key, salt, rec_seq 설정 (OpenSSL에서 추출) */

setsockopt(sock_fd, SOL_TCP, TCP_ULP, "tls", 3);
setsockopt(sock_fd, SOL_TLS, TLS_TX,
           &crypto_info, sizeof(crypto_info));

/* 2. io_uring으로 TLS 전송 (평문을 보내면 커널이 암호화) */
struct io_uring_sqe *sqe = io_uring_get_sqe(&ring);
io_uring_prep_send(sqe, sock_fd, plaintext, len, 0);
/* 커널 kTLS 레이어가 자동으로 AES-GCM 암호화 수행 */

/* 3. 제로카피 TLS 전송 (대용량 전송 시) */
sqe = io_uring_get_sqe(&ring);
io_uring_prep_send_zc(sqe, sock_fd, plaintext, len, 0, 0);
/* kTLS + SEND_ZC: 최소 복사로 최대 처리량 */

io_uring_submit(&ring);

io_uring 내부 잠금 전략

io_uring의 성능 핵심 중 하나는 잠금을 최소화하는 설계입니다. SQ/CQ 링 자체는 lock-free이지만, 내부 자원 관리(io_ring_ctx)에는 다양한 잠금이 사용되며, 커널 버전에 따라 세분화되어 왔습니다.

시스템 파라미터 튜닝 가이드

io_uring 성능과 안정성에 영향을 미치는 커널 파라미터, 리소스 제한, 시스템 설정을 종합적으로 정리합니다.

리소스 제한 (rlimits)

커널 sysctl 파라미터

io-wq 워커 제어

/* io-wq 워커 수 제한 */
unsigned int workers[2] = {
    16,   /* [0] bounded: buffered I/O 워커 (RLIMIT_NPROC 이하) */
    8,    /* [1] unbounded: 네트워크/폴 대기 워커 */
};
io_uring_register_iowq_max_workers(&ring, workers);
/* 반환: workers[]에 이전 값이 저장됨 */

/* io-wq 워커 CPU affinity 설정 */
cpu_set_t cpuset;
CPU_ZERO(&cpuset);
for (int i = 0; i < 8; i++)
    CPU_SET(i, &cpuset);
io_uring_register_iowq_aff(&ring, sizeof(cpuset), &cpuset);

프로덕션 배포 체크리스트

# 프로덕션 서버 io_uring 설정 스크립트

# 1. 리소스 제한 설정
cat <<EOF >> /etc/security/limits.conf
*    soft    memlock    unlimited
*    hard    memlock    unlimited
*    soft    nofile     65536
*    hard    nofile     65536
EOF

# 2. sysctl 설정
cat <<EOF >> /etc/sysctl.d/99-io-uring.conf
# io_uring 허용 (비특권 사용자 차단)
kernel.io_uring_disabled = 1

# 파일 시스템 제한
fs.file-max = 2097152
fs.nr_open = 1048576

# 네트워크 (io_uring NAPI 사용 시)
net.core.somaxconn = 65535
net.core.netdev_max_backlog = 50000
net.ipv4.tcp_max_syn_backlog = 30000
EOF

sysctl -p /etc/sysctl.d/99-io-uring.conf

# 3. 커널 버전 및 io_uring 기능 확인
uname -r
cat /proc/sys/kernel/io_uring_disabled

# 4. SQPOLL 권한 부여 (특정 바이너리에만)
setcap cap_sys_nice+ep /usr/local/bin/my_server

# 5. fio 기준선 측정
fio --ioengine=io_uring --direct=1 --bs=4k --iodepth=64 \
    --rw=randread --filename=/dev/nvme0n1 --name=baseline \
    --fixedbufs=1 --registerfiles=1 --sqthread_poll=1

커널 버전 호환성 매트릭스

io_uring 기능은 커널 버전에 따라 크게 달라집니다. 다음은 주요 기능별 최소 요구 커널 버전을 종합한 호환성 매트릭스입니다.

관련 문서

io_uring과 관련된 다른 주제를 더 깊이 이해하고 싶다면 다음 문서를 참고하세요.

• Block I/O — 블록 I/O 스택
• VFS — 파일 시스템 I/O
• 시스템 콜 — 전통적인 I/O 시스템 콜
• 네트워크 스택 — io_uring 네트워크 I/O
• 데이터베이스와 커널 — DB 비동기 I/O, fsync, 큐 깊이 정합 관점