[DTrace-devel] [PATCH] WIP doc: Add IP provider documentation
Alan Maguire
alan.maguire at oracle.com
Mon Sep 22 13:48:44 UTC 2025
On 18/09/2025 20:59, eugene.loh at oracle.com wrote:
> From: Eugene Loh <eugene.loh at oracle.com>
>
> I'm starting to add some provider documentation to the MD user guide:
> ip, tcp, udp, and rawfbt. This is my first cut at editing the MD UG
> and I'm pretty unfamiliar with the ip provider (and tcp and udp).
> So if you want to offer preliminary feedback, feel free. Otherwise,
> I'll do those providers and then go back and look the whole thing over
> more carefully before posting for review.
>
> Signed-off-by: Eugene Loh <eugene.loh at oracle.com>
looks great! (one comment below about csinfo_t)
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 | 177 ++++++++++++++++++
> 3 files changed, 189 insertions(+)
> create mode 100644 doc/userguide/reference/dtrace_providers_ip.md
>
> diff --git a/doc/userguide/index.md b/doc/userguide/index.md
> index abd1096db..760867eee 100644
> --- a/doc/userguide/index.md
> +++ b/doc/userguide/index.md
> @@ -208,6 +208,16 @@
> - [fileinfo\_t](reference/dtrace_providers_io.md#dt_ref_iofile_prov)
> - [io Examples](reference/dtrace_providers_io.md#dt_ref_ioexamples_prov)
> - [io Stability](reference/dtrace_providers_io.md#dt_ref_iostab_prov)
> + - [IP Provider](reference/dtrace_providers_ip.md#dt_ref_ip_prov)
> + - [ip Probes](reference/dtrace_providers_ip.md#dt_ref_ipprobes_prov)
> + - [ip Probe Arguments](reference/dtrace_providers_ip.md#dt_ref_ipargs_prov)
> + - [pktinfo\_t](reference/dtrace_providers_ip.md#dt_ref_ippkt_prov)
> + - [csinfo\_t](reference/dtrace_providers_ip.md#dt_ref_ipcs_prov)
> + - [ipinfo\_t](reference/dtrace_providers_ip.md#dt_ref_ipip_prov)
> + - [ifinfo\_t](reference/dtrace_providers_ip.md#dt_ref_ipif_prov)
> + - [ipv4info\_t](reference/dtrace_providers_ip.md#dt_ref_ipipv4_prov)
> + - [ipv6info\_t](reference/dtrace_providers_ip.md#dt_ref_ipipv6_prov)
> + - [ip Stability](reference/dtrace_providers_ip.md#dt_ref_ipstab_prov)
> - [Lockstat Provider](reference/dtrace_providers_lockstat.md#dt_ref_lockstat_prov)
> - [lockstat Probes](reference/dtrace_providers_lockstat.md#dt_ref_lockstatprobes_prov)
> - [lockstat Probe Arguments](reference/dtrace_providers_lockstat.md#dt_ref_lockstatargs_prov)
> diff --git a/doc/userguide/reference/dtrace_providers.md b/doc/userguide/reference/dtrace_providers.md
> index 6fd0fec6e..f8e8026db 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..67acd52cd
> --- /dev/null
> +++ b/doc/userguide/reference/dtrace_providers_ip.md
> @@ -0,0 +1,177 @@
> +
> +# IP Provider {#dt_ref_ip_prov}
> +
> +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 {#dt_ref_ipprobes_prov}
> +
> +`ip` provides a probe for IP sends and one for IP receives.
> +The module name is always `vmlinux` and the function name is empty.
> +
> +## ip Probe Arguments {#dt_ref_ipargs_prov}
> +
> +The following table lists the argument types for both the `send` and `receive` probes.
> +
> +|`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 {#dt_ref_ippkt_prov}
> +
> +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 {#dt_ref_ipcs_prov}
> +
> +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; IS THIS SET?
IIRC on Solaris it was basically just the pointer to the socket, which
isn't really a great idea as a unique identifier as the socket pointers
get recycled via slab allocation. We don't seem to have the field in the
Linux csinfo judging by the content of ip.d.
> +} csinfo_t;
> +```
> +
> +**Note:**
> +
> +DTrace translates the members of `csinfo_t` from the `struct sock *`.
> +
> +### ipinfo\_t {#dt_ref_ipip_prov}
> +
> +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 {#dt_ref_ipif_prov}
> +
> +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 {#dt_ref_ipipv4_prov}
> +
> +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 {#dt_ref_ipipv6_prov}
> +
> +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 {#dt_ref_ipstab_prov}
> +
> +The `ip` provider uses DTrace's stability mechanism to describe its stabilities. These stability values are listed in the following table.
> +
> +<table>
> + <thead>
> + <tr><th>Element </th><th>Name Stability</th><th>Data Stability</th><th>Dependency Class</th></tr>
> + </thead>
> + <tbody>
> + <tr><td>Provider </td><td>Evolving </td><td>Evolving </td><td>ISA </td></tr>
> + <tr><td>Module </td><td>Private </td><td>Private </td><td>Unknown </td></tr>
> + <tr><td>Function </td><td>Private </td><td>Private </td><td>Unknown </td></tr>
> + <tr><td>Name </td><td>Evolving </td><td>Evolving </td><td>ISA </td></tr>
> + <tr><td>Arguments</td><td>Evolving </td><td>Evolving </td><td>ISA </td></tr>
> + <tbody>
> +</table>
More information about the DTrace-devel
mailing list