Re: [PATCH v2 17/20] doc: Add IP provider documentation

Hmm, just to clarify... you mean pull this patch out of the patch series 
so that it can be applied independently of the other fixes?

On 10/9/25 13:03, Kris Van Hees wrote:
> This patch does not apply cleanly to dev-queue.  Can you look into that and
> post a v3 (keeping the R-b)?
>
> On Fri, Sep 26, 2025 at 03:05:54PM -0400, [email protected] wrote:
>> From: Eugene Loh <[email protected]>
>>
>> Signed-off-by: Eugene Loh <[email protected]>
>> Reviewed-by: Alan Maguire <[email protected]>
>> ---
>>   doc/userguide/index.md                        |  10 +
>>   doc/userguide/reference/dtrace_providers.md   |   2 +
>>   .../reference/dtrace_providers_ip.md          | 174 ++++++++++++++++++
>>   3 files changed, 186 insertions(+)
>>   create mode 100644 doc/userguide/reference/dtrace_providers_ip.md
>>
>> diff --git a/doc/userguide/index.md b/doc/userguide/index.md
>> index f3d96a4d6..18b9bcd68 100644
>> --- a/doc/userguide/index.md
>> +++ b/doc/userguide/index.md
>> @@ -208,6 +208,16 @@
>>               -   [fileinfo\_t](reference/dtrace_providers_io.md#fileinfo_t)
>>           -   [io Examples](reference/dtrace_providers_io.md#io-examples)
>>           -   [io Stability](reference/dtrace_providers_io.md#io-stability)
>> +    -   [IP Provider](reference/dtrace_providers_ip.md)
>> +        -   [ip Probes](reference/dtrace_providers_ip.md#ip-probes)
>> +        -   [ip Probe Arguments](reference/dtrace_providers_ip.md#ip-probe-arguments)
>> +            -   [pktinfo\_t](reference/dtrace_providers_ip.md#pktinfo_t)
>> +            -   [csinfo\_t](reference/dtrace_providers_ip.md#csinfo_t)
>> +            -   [ipinfo\_t](reference/dtrace_providers_ip.md#ipinfo_t)
>> +            -   [ifinfo\_t](reference/dtrace_providers_ip.md#ifinfo_t)
>> +            -   [ipv4info\_t](reference/dtrace_providers_ip.md#ipv4info_t)
>> +            -   [ipv6info\_t](reference/dtrace_providers_ip.md#ipv6info_t)
>> +        -   [ip Stability](reference/dtrace_providers_ip.md#ip-stability)
>>       -   [Lockstat Provider](reference/dtrace_providers_lockstat.md)
>>           -   [lockstat Probes](reference/dtrace_providers_lockstat.md#lockstat-probes)
>>           -   [lockstat Probe Arguments](reference/dtrace_providers_lockstat.md#lockstat-probe-arguments)
>> diff --git a/doc/userguide/reference/dtrace_providers.md b/doc/userguide/reference/dtrace_providers.md
>> index 9f64935c6..54a018d5c 100644
>> --- a/doc/userguide/reference/dtrace_providers.md
>> +++ b/doc/userguide/reference/dtrace_providers.md
>> @@ -11,6 +11,8 @@ The `dtrace` provider includes several probes that are specific to DTrace itself
>>   The `fbt` \(Function Boundary Tracing\) provider includes probes that are associated with the entry to and return from most functions in the Linux kernel. Therefore, there could be tens of thousands of `fbt` probes.
>>   -   **[IO Provider](../reference/dtrace_providers_io.md)**
>>   The `io` provider makes available probes that relate to data input and output.
>> +-   **[IP Provider](../reference/dtrace_providers_ip.md)**
>> +The `ip` provider provides probes that can be used to study IP traffic.
>>   -   **[Lockstat Provider](../reference/dtrace_providers_lockstat.md)**
>>   The `lockstat` provider provides probes that can be used to study lock usage and contention.
>>   -   **[Pid Provider](../reference/dtrace_providers_pid.md)**
>> diff --git a/doc/userguide/reference/dtrace_providers_ip.md b/doc/userguide/reference/dtrace_providers_ip.md
>> new file mode 100644
>> index 000000000..4e6c47fb2
>> --- /dev/null
>> +++ b/doc/userguide/reference/dtrace_providers_ip.md
>> @@ -0,0 +1,174 @@
>> +
>> +# IP Provider
>> +
>> +The `ip` provider makes available a probe at IP send operations in the system and a probe at receive.
>> +
>> +**Parent topic:**[DTrace Provider Reference](../reference/dtrace_providers.md)
>> +
>> +## ip Probes
>> +
>> +The `ip` provider provides one probe for IP sends and another for IP receives.
>> +The module name is always `vmlinux` and the function name is empty.
>> +
>> +## ip Probe Arguments
>> +
>> +The following table lists the argument types for both the `send` and `receive` probes.
>> +
>> +| arg       | type            |
>> +| :---      | :---            |
>> +| `args[0]` | `pktinfo_t *`   |
>> +| `args[1]` | `csinfo_t *`    |
>> +| `args[2]` | `ipinfo_t *`    |
>> +| `args[3]` | `ifinfo_t *`    |
>> +| `args[4]` | `ipv4info_t *`  |
>> +| `args[5]` | `ipv6sinfo_t *` |
>> +
>> +### pktinfo\_t
>> +
>> +The `pktinfo_t` structure is an abstraction that describes a packet.
>> +Detailed information about this data structure can be found in
>> +`/usr/lib64/dtrace/*version*/ip.d` or
>> +`/usr/lib64/dtrace/*version*/net.d`, depending on `dtrace` version.
>> +The definition of `pktinfo_t` is as follows:
>> +
>> +```nocopybutton
>> +typedef struct pktinfo {
>> +        uintptr_t pkt_addr;
>> +} pktinfo_t;
>> +```
>> +
>> +**Note:**
>> +
>> +DTrace translates the members of `pktinfo_t` from the `struct sk_buff *`.
>> +
>> +### csinfo\_t
>> +
>> +The `csinfo_t` structure is an abstraction that describes connection state.
>> +Detailed information about this data structure can be found in
>> +`/usr/lib64/dtrace/*version*/ip.d` or
>> +`/usr/lib64/dtrace/*version*/net.d`, depending on `dtrace` version.
>> +The definition of `csinfo_t` is as follows:
>> +
>> +```nocopybutton
>> +typedef struct csinfo {
>> +	uintptr_t	cs_addr;
>> +	uint64_t	cs_cid;
>> +} csinfo_t;
>> +```
>> +
>> +**Note:**
>> +
>> +DTrace translates the members of `csinfo_t` from the `struct sock *`.
>> +
>> +### ipinfo\_t
>> +
>> +The `ipinfo_t` structure contains common IP info for both IPv4 and IPv6.
>> +Detailed information about this data structure can be found in `/usr/lib64/dtrace/*version*/ip.d`.
>> +The definition of `ipinfo_t` is as follows:
>> +
>> +```nocopybutton
>> +typedef struct ipinfo {
>> +        uint8_t ip_ver;         /* IP version (4, 6) */
>> +        uint32_t ip_plength;    /* payload length */
>> +        string ip_saddr;        /* source address */
>> +        string ip_daddr;        /* destination address */
>> +} ipinfo_t;
>> +```
>> +
>> +**Note:**
>> +
>> +DTrace translates the members of `ipinfo_t` from, variously,
>> +`struct iphdr *`, `struct ipv6hdr *`, or `void_ip_t *`.
>> +
>> +### ifinfo\_t
>> +
>> +The `ifinfo_t` structure contains network interface info.
>> +Detailed information about this data structure can be found in `/usr/lib64/dtrace/*version*/ip.d`.
>> +The definition of `ifinfo_t` is as follows:
>> +
>> +```nocopybutton
>> +typedef struct ifinfo {
>> +        string if_name;            /* interface name */
>> +        int8_t if_local;           /* is delivered locally */
>> +        netstackid_t if_ipstack;   /* netns pointer on Linux */
>> +        uintptr_t if_addr;         /* pointer to raw struct net_device */
>> +} ifinfo_t;
>> +```
>> +
>> +**Note:**
>> +
>> +DTrace translates the members of `ifinfo_t` from a `struct net_device *`.
>> +
>> +### ipv4info\_t
>> +
>> +The `ipv4info_t` structure is translated version of the IPv4 header
>> +(with raw pointer).
>> +These values are NULL if the packet is not IPv4.
>> +Detailed information about this data structure can be found in `/usr/lib64/dtrace/*version*/ip.d`.
>> +The definition of `ipv4info_t` is as follows:
>> +
>> +```nocopybutton
>> +typedef struct ipv4info {
>> +        uint8_t ipv4_ver;               /* IP version (4) */
>> +        uint8_t ipv4_ihl;               /* header length, bytes */
>> +        uint8_t ipv4_tos;               /* type of service field */
>> +        uint16_t ipv4_length;           /* length (header + payload) */
>> +        uint16_t ipv4_ident;            /* identification */
>> +        uint8_t ipv4_flags;             /* IP flags */
>> +        uint16_t ipv4_offset;           /* fragment offset */
>> +        uint8_t ipv4_ttl;               /* time to live */
>> +        uint8_t ipv4_protocol;          /* next level protocol */
>> +        string ipv4_protostr;           /* next level protocol, as string */
>> +        uint16_t ipv4_checksum;         /* header checksum */
>> +        ipaddr_t ipv4_src;              /* source address */
>> +        ipaddr_t ipv4_dst;              /* destination address */
>> +        string ipv4_saddr;              /* source address, string */
>> +        string ipv4_daddr;              /* destination address, string */
>> +        struct iphdr *ipv4_hdr;         /* pointer to raw header */
>> +} ipv4info_t;
>> +```
>> +
>> +**Note:**
>> +
>> +DTrace translates the members of `ipv4info_t` from a `struct iphdr *`.
>> +
>> +### ipv6info\_t
>> +
>> +The `ipv6info_t` structure is translated version of the IPv6 header
>> +(with raw pointer).
>> +These values are NULL if the packet is not IPv6.
>> +Detailed information about this data structure can be found in `/usr/lib64/dtrace/*version*/ip.d`.
>> +The definition of `ipv6info_t` is as follows:
>> +
>> +```nocopybutton
>> +typedef struct ipv6info {
>> +        uint8_t ipv6_ver;               /* IP version (6) */
>> +        uint8_t ipv6_tclass;            /* traffic class */
>> +        uint32_t ipv6_flow;             /* flow label */
>> +        uint16_t ipv6_plen;             /* payload length */
>> +        uint8_t ipv6_nexthdr;           /* next header protocol */
>> +        string ipv6_nextstr;            /* next header protocol, as string */
>> +        uint8_t ipv6_hlim;              /* hop limit */
>> +        in6_addr_t *ipv6_src;           /* source address */
>> +        in6_addr_t *ipv6_dst;           /* destination address */
>> +        string ipv6_saddr;              /* source address, string */
>> +        string ipv6_daddr;              /* destination address, string */
>> +        struct ipv6hdr *ipv6_hdr;       /* pointer to raw header */
>> +} ipv6info_t;
>> +```
>> +
>> +**Note:**
>> +
>> +DTrace translates the members of `ipv6info_t` from a `struct ipv6hdr *`.
>> +
>> +## ip Stability
>> +
>> +The `ip` provider uses DTrace's stability mechanism to describe its stabilities. These stability values are listed in the following table.
>> +
>> +| Element   | Name Stability | Data Stability | Dependency Class |
>> +| :---      | :---           | :---           | :---             |
>> +| Provider  | Evolving       | Evolving       | ISA              |
>> +| Module    | Private        | Private        | Unknown          |
>> +| Function  | Private        | Private        | Unknown          |
>> +| Name      | Evolving       | Evolving       | ISA              |
>> +| Arguments | Evolving       | Evolving       | ISA              |
>> -- 
>> 2.47.3
>>