Docs: Note the packet-pointer-field gotcha, with the planned mechanism

xdp_md.data/data_end/data_meta and __sk_buff.data/data_end are u32 in
C and packet pointers to the verifier, so arithmetic on them directly
is rejected as 32-bit pointer arithmetic, for C and for us alike. A
TODO at the point where a field's rank is decided describes the planned
fix (64-bit pointer rank for those fields, no cast needed), and the
user guide documents the workaround until then: copy to a local or cast
through c_void_p.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

Author: r41k0u

docs/user-guide/integers.md

@@ -109,6 +109,34 @@ compares in the resulting type. `c_uint64(10) > c_int64(-1)` is therefore an uns
 comparison in which `-1` is the largest possible value, and the result is false. The
 result of a comparison is `1` or `0`, as in C.
 
+## A verifier gotcha: packet pointer fields
+
+A few context fields are declared as 32-bit integers but are pointers as far as the
+kernel verifier is concerned: `data`, `data_end` and `data_meta` on `xdp_md`, and `data`
+and `data_end` on `__sk_buff`. Because they are `c_uint32`, arithmetic on them directly
+is a 32-bit operation, exactly as in C, and the verifier rejects 32-bit arithmetic on a
+pointer:
+
+```
+R0 32-bit pointer arithmetic prohibited
+```
+
+C programs cast these fields through `(void *)(long)` before using them for the same
+reason. Until PythonBPF does this for you, copy the field into a local first, which is a
+64-bit slot, or cast it with `c_void_p`:
+
+```python
+data = ctx.data            # 64-bit local
+end = ctx.data_end
+if data + 34 < end:        # 64-bit pointer arithmetic, accepted
+    ...
+```
+
+```{note}
+This is a known gap. The plan is to give these fields pointer rank automatically so that
+no cast or copy is needed; this section will go away when that lands.
+```
+
 ## Divergences from Python
 
 Because the semantics are C's, some Python behaviour does not carry over:

pythonbpf/expr/expr_pass.py

@@ -205,6 +205,17 @@ def _descriptor(val, ty):
     if field is not None:
         # A vmlinux field: load_ctx_field already widened the value, but C
         # ranks it by its declared width (a c_uint32 field is unsigned int).
+        #
+        # TODO(gotcha): some u32 context fields are packet pointers to the
+        # verifier, not numbers: xdp_md.data / data_end / data_meta and
+        # __sk_buff.data / data_end. Ranking them as u32 is what C does, and
+        # the verifier then rejects any arithmetic on them ("32-bit pointer
+        # arithmetic prohibited"), so C code casts them through
+        # (void *)(long) first. The plan is to spare users that: give these
+        # fields 64-bit pointer rank here, so `ctx.data + 34 < ctx.data_end`
+        # lowers to 64-bit pointer arithmetic without a cast. Until then,
+        # copy the field into a local (a 64-bit slot) or cast it via
+        # c_void_p before using it.
         return field
     if val is not None and isinstance(val.type, ir.IntType):
         return IntTy(val.type.width, signedness(ty))