[DTrace-devel] [PATCH] WIP doc: Add IP provider documentation
eugene.loh at oracle.com
eugene.loh at oracle.com
Thu Sep 18 19:59:22 UTC 2025
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>
---
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?
+} 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>
--
2.47.3
More information about the DTrace-devel
mailing list