Documentation/networking/iou-zcrx.rst

Source file repositories/reference/linux-study-clean/Documentation/networking/iou-zcrx.rst

File Facts

System
Linux kernel
Corpus path
Documentation/networking/iou-zcrx.rst
Extension
.rst
Size
6501 bytes
Lines
223
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: documentation
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

io_uring_for_each_cqe(ring, head, cqe) {
    struct io_uring_zcrx_cqe *rcqe = (struct io_uring_zcrx_cqe *)(cqe + 1);

    unsigned long mask = (1ULL << IORING_ZCRX_AREA_SHIFT) - 1;
    unsigned char *data = area_ptr + (rcqe->off & mask);
    /* do something with the data */

    count++;
  }
  io_uring_cq_advance(ring, count);

Recycling buffers
-----------------

Return buffers back to the kernel to be used again::

  struct io_uring_zcrx_rqe *rqe;
  unsigned mask = refill_ring.ring_entries - 1;
  rqe = &refill_ring.rqes[refill_ring.rq_tail & mask];

  unsigned long area_offset = rcqe->off & ~IORING_ZCRX_AREA_MASK;
  rqe->off = area_offset | area_reg.rq_area_token;
  rqe->len = cqe->res;
  IO_URING_WRITE_ONCE(*refill_ring.ktail, ++refill_ring.rq_tail);

Area chunking
-------------

zcrx splits the memory area into fixed-length physically contiguous chunks.
This limits the maximum buffer size returned in a single io_uring CQE. Users
can provide a hint to the kernel to use larger chunks by setting the
``rx_buf_len`` field of ``struct io_uring_zcrx_ifq_reg`` to the desired length
during registration. If this field is set to zero, the kernel defaults to
the system page size.

To use larger sizes, the memory area must be backed by physically contiguous
ranges whose sizes are multiples of ``rx_buf_len``. It also requires kernel
and hardware support. If registration fails, users are generally expected to
fall back to defaults by setting ``rx_buf_len`` to zero.

Larger chunks don't give any additional guarantees about buffer sizes returned
in CQEs, and they can vary depending on many factors like traffic pattern,
hardware offload, etc. It doesn't require any application changes beyond zcrx
registration.

Testing
=======

See ``tools/testing/selftests/drivers/net/hw/iou-zcrx.c``

Annotation

Implementation Notes