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

[Kris Van Hees <kris.van.hees@oracle.com>]

On Thu, Oct 09, 2025 at 05:00:06PM -0400, Eugene Loh wrote:
> 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?

Ah yes, I didn't realize it was part of the 20-patch series.  I think it was
an independent patch in its v1 form?  If so, I prpbably was thinking about
that.

OK - let's keep it as part of the series and it will go in with it.

> 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, eugene.loh@oracle.com wrote:
> > > From: Eugene Loh <eugene.loh@oracle.com>
> > > 
> > > Signed-off-by: Eugene Loh <eugene.loh@oracle.com>
> > > Reviewed-by: Alan Maguire <alan.maguire@oracle.com>
> > > ---
> > >   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
> > >