[DTrace-devel] [PATCH v2 17/20] doc: Add IP provider documentation
Eugene Loh
eugene.loh at oracle.com
Thu Oct 9 21:00:06 UTC 2025
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, eugene.loh at oracle.com wrote:
>> From: Eugene Loh <eugene.loh at oracle.com>
>>
>> Signed-off-by: Eugene Loh <eugene.loh at oracle.com>
>> Reviewed-by: Alan Maguire <alan.maguire at 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
>>
More information about the DTrace-devel
mailing list