Re: [PATCH v2 17/20] doc: Add IP provider documentation
Eugene Loh <[email protected]>
| Newsgroups | dev.linux.lists.dtrace |
|---|---|
| Message-ID | <[email protected]> |
On 10/9/25 17:45, Kris Van Hees wrote: > 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? Right. > 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. Sounds great. >> 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 >>>>