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.song@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