Expand the explanation of how METADATA_SIZE should be chosen to accommodate
both device-reserved and custom metadata. Additionally, add a diagram to
illustrate the calculation of the delta parameter for bpf_xdp_adjust_meta,
including alignment and size constraints.
These changes help users correctly allocate and access metadata in AF_XDP
use cases.
Signed-off-by: Song Yoong Siang <yoong.siang.s...@intel.com>
---
Documentation/networking/xdp-rx-metadata.rst | 38 ++++++++++++++++++++
1 file changed, 38 insertions(+)
diff --git a/Documentation/networking/xdp-rx-metadata.rst
b/Documentation/networking/xdp-rx-metadata.rst
index a6e0ece18be5..61418f533e0e 100644
--- a/Documentation/networking/xdp-rx-metadata.rst
+++ b/Documentation/networking/xdp-rx-metadata.rst
@@ -54,6 +54,19 @@ area in whichever format it chooses. Later consumers of the
metadata
will have to agree on the format by some out of band contract (like for
the AF_XDP use case, see below).
+It is important to note that some devices may utilize the ``data_meta`` area
for
+their own purposes. For example, the IGC device utilizes ``IGC_TS_HDR_LEN``
+bytes of the ``data_meta`` area for receiving hardware timestamps. Therefore,
+the XDP program should ensure that it does not overwrite any existing metadata.
+The metadata layout of such device is depicted below::
+
+ +----------+-----------------+--------------------------+------+
+ | headroom | custom metadata | device-reserved metadata | data |
+ +----------+-----------------+--------------------------+------+
+ ^ ^
+ | |
+ xdp_buff->data_meta xdp_buff->data
+
AF_XDP
======
@@ -76,6 +89,31 @@ Here is the ``AF_XDP`` consumer layout (note missing
``data_meta`` pointer)::
|
rx_desc->address
+It is crucial that the agreed ``METADATA_SIZE`` between the BPF program and the
+final consumer is sufficient to accommodate both device-reserved metadata and
+the data the BPF program needs to populate. When calling
+``bpf_xdp_adjust_meta``, the input parameter ``delta`` should be calculated as
+``METADATA_SIZE - (xdp_buff->data - xdp_buff->data_meta)``.
+
+The diagram below provides a visual representation of the calculation of
+``delta`` and the overall metadata layout::
+
+ |<-------------------METADATA_SIZE------------------->|
+ +----------+--------------------------+--------------------------+------+
+ | headroom | custom metadata | device-reserved metadata | data |
+ +----------+--------------------------+--------------------------+------+
+ ^ ^ ^
+ | | |
+ new xdp_buff->data_meta old xdp_buff->data_meta xdp_buff->data
+ | |
+ |<----------delta--------->|
+
+``bpf_xdp_adjust_meta`` ensures that ``METADATA_SIZE`` is aligned to 4 bytes,
+does not exceed 252 bytes, and leaves sufficient space for building the
+xdp_frame. If these conditions are not met, it returns a negative error. In
this
+case, the BPF program should not proceed to populate data into the
``data_meta``
+area.
+
XDP_PASS
========
--
2.34.1
