Re: [PATCH 18/20] doc: Add TCP provider documentation

Alan Maguire
2025-10-24T08:25:02Z

On 26/09/2025 20:05, 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>

Future work we should think about; add a few examples to each provider
doc. But getting the core documentation is a massive step!

> ---
> doc/userguide/index.md | 7 +
> doc/userguide/reference/dtrace_providers.md | 2 +
> .../reference/dtrace_providers_tcp.md | 128 ++++++++++++++++++
> 3 files changed, 137 insertions(+)
> create mode 100644 doc/userguide/reference/dtrace_providers_tcp.md
>
> diff --git a/doc/userguide/index.md b/doc/userguide/index.md
> index 18b9bcd68..d47df094b 100644
> --- a/doc/userguide/index.md
> +++ b/doc/userguide/index.md
> @@ -259,6 +259,13 @@
> - [syscall Probes](reference/dtrace_providers_syscall.md#syscall-probes)
> - [syscall Probe Arguments](reference/dtrace_providers_syscall.md#syscall-probe-arguments)
> - [syscall Stability](reference/dtrace_providers_syscall.md#syscall-stability)
> + - [TCP Provider](reference/dtrace_providers_tcp.md)
> + - [tcp Probes](reference/dtrace_providers_tcp.md#tcp-probes)
> + - [tcp Probe Arguments](reference/dtrace_providers_tcp.md#tcp-probe-arguments)
> + - [tcpinfo\_t](reference/dtrace_providers_tcp.md#tcpinfo_t)
> + - [tcpsinfo\_t](reference/dtrace_providers_tcp.md#tcpsinfo_t)
> + - [tcplsinfo\_t](reference/dtrace_providers_tcp.md#tcplsinfo_t)
> + - [tcp Stability](reference/dtrace_providers_tcp.md#tcp-stability)
> - [USDT Provider](reference/dtrace-ref-StaticallyDefinedTracingofUserApplications.md)
> - [Defining USDT Providers and Probes](reference/dtrace-ref-StaticallyDefinedTracingofUserApplications.md#defining-usdt-providers-and-probes)
> - [Adding USDT Probes to Application Code](reference/dtrace-ref-StaticallyDefinedTracingofUserApplications.md#adding-usdt-probes-to-application-code)
> diff --git a/doc/userguide/reference/dtrace_providers.md b/doc/userguide/reference/dtrace_providers.md
> index 54a018d5c..029f62c54 100644
> --- a/doc/userguide/reference/dtrace_providers.md
> +++ b/doc/userguide/reference/dtrace_providers.md
> @@ -29,5 +29,7 @@ The `sched` provider makes available probes related to CPU scheduling.
> The Statically Defined Tracing \(SDT\) provider \(`sdt`\) creates probes at sites that a software programmer has formally designated. Thus, the SDT provider is chiefly of interest only to developers of new providers. Most users access SDT only indirectly by using other providers.
> - **[Syscall Provider](../reference/dtrace_providers_syscall.md)**
> The `syscall` provider makes available a probe at the entry to and return from every system call in the system.
> +- **[TCP Provider](../reference/dtrace_providers_tcp.md)**
> +The `tcp` provider makes available probe at different phases of TCP processing.
> - **[USDT Provider](../reference/dtrace-ref-StaticallyDefinedTracingofUserApplications.md)**
> Use the USDT provider, for user space statically defined tracing, to instrument user space code with probes that are meaningful for an application.
> diff --git a/doc/userguide/reference/dtrace_providers_tcp.md b/doc/userguide/reference/dtrace_providers_tcp.md
> new file mode 100644
> index 000000000..9f6e4928c
> --- /dev/null
> +++ b/doc/userguide/reference/dtrace_providers_tcp.md
> @@ -0,0 +1,128 @@
> +
> +# TCP Provider
> +
> +The `tcp` provider makes available probes that mark different
> +phases of tcp processing.
> +
> +**Parent topic:**[DTrace Provider Reference](../reference/dtrace_providers.md)
> +
> +## tcp Probes
> +
> +`tcp` provides a probe for each of TCP accept (established or refused), connect
> +(request, established, refused), send, receive, and state-change:
> +
> +- `accept-established`
> +- `accept-refused`
> +- `connect-request`
> +- `connect-established`
> +- `connect-refused`
> +- `send`
> +- `receive`
> +- `state-change`
> +
> +The module name is always `vmlinux` and the function name is empty.
> +
> +## tcp Probe Arguments
> +
> +The following table lists the argument types for `tcp` probes.
> +
> +| probe | `args[0]` | `args[1]` | `args[2]` | `args[3]` | `args[4]` | `args[5]` |
> +| :--- | :--- | :--- | :--- | :--- | :--- | :--- |
> +| `accept-established` | `pktinfo_t *` | `csinfo_t *` | `ipinfo_t *` | `tcpsinfo_t *` | `tcpinfo_t *` | `void` |
> +| `accept-refused` | `pktinfo_t *` | `csinfo_t *` | `ipinfo_t *` | `tcpsinfo_t *` | `tcpinfo_t *` | `void` |
> +| `connect-request` | `pktinfo_t *` | `csinfo_t *` | `ipinfo_t *` | `tcpsinfo_t *` | `tcpinfo_t *` | `void` |
> +| `connect-established` | `pktinfo_t *` | `csinfo_t *` | `ipinfo_t *` | `tcpsinfo_t *` | `tcpinfo_t *` | `void` |
> +| `connect-refused` | `pktinfo_t *` | `csinfo_t *` | `ipinfo_t *` | `tcpsinfo_t *` | `tcpinfo_t *` | `void` |
> +| `send` | `pktinfo_t *` | `csinfo_t *` | `ipinfo_t *` | `tcpsinfo_t *` | `tcpinfo_t *` | `void` |
> +| `receive` | `pktinfo_t *` | `csinfo_t *` | `ipinfo_t *` | `tcpsinfo_t *` | `tcpinfo_t *` | `void` |
> +| `state-change` | `void` | `csinfo_t *` | `void` | `tcpsinfo_t *` | `void` | `tcplsinfo_t *` |
> +
> +The `pktinfo_t`, `csinfo_t`, and `ipinfo_t` structures are described in [IP Provider](dtrace_providers_ip.md).
> +

this is the table format we should standardize across provider docs IMO;
having a standard format will help the LLMs likely.

> +### tcpinfo\_t
> +
> +The `tcpinfo_t` structure contains TCP header fields.
> +Detailed information about this data structure can be found in `/usr/lib64/dtrace/*version*/tcp.d`.
> +The definition of `tcpinfo_t` is as follows:
> +
> +```nocopybutton
> +typedef struct tcpinfo {
> + uint16_t tcp_sport; /* source port */
> + uint16_t tcp_dport; /* destination port */
> + uint32_t tcp_seq; /* sequence number */
> + uint32_t tcp_ack; /* acknowledgment number */
> + uint8_t tcp_offset; /* data offset, in bytes */
> + uint8_t tcp_flags; /* flags */
> + uint16_t tcp_window; /* window size */
> + uint16_t tcp_checksum; /* checksum */
> + uint16_t tcp_urgent; /* urgent data pointer */
> + uintptr_t tcp_hdr; /* raw TCP header */
> +} tcpinfo_t;
> +```
> +
> +**Note:**
> +
> +DTrace translates the members of `tcpinfo_t` from a `struct tcphdr *`.
> +
> +### tcpsinfo\_t
> +
> +The `tcpsinfo_t` structure contains stable TCP details from tcp_t.
> +Detailed information about this data structure can be found in `/usr/lib64/dtrace/*version*/tcp.d`.
> +The definition of `tcpsinfo_t` is as follows:
> +
> +```nocopybutton
> +typedef struct tcpsinfo {
> + uintptr_t tcps_addr;
> + int tcps_local; /* is delivered locally, boolean */
> + uint16_t tcps_lport; /* local port */
> + uint16_t tcps_rport; /* remote port */
> + string tcps_laddr; /* local address, as a string */
> + string tcps_raddr; /* remote address, as a string */
> + int tcps_state; /* TCP state */
> + uint32_t tcps_iss; /* Initial sequence # sent */
> + uint32_t tcps_suna; /* sequence # sent but unacked */
> + uint32_t tcps_snxt; /* next sequence # to send */
> + uint32_t tcps_rnxt; /* next sequence # expected */
> + uint32_t tcps_swnd; /* send window size */
> + int32_t tcps_snd_ws; /* send window scaling */
> + uint32_t tcps_rwnd; /* receive window size */
> + int32_t tcps_rcv_ws; /* receive window scaling */
> + uint32_t tcps_cwnd; /* congestion window */
> + uint32_t tcps_cwnd_ssthresh; /* threshold for congestion avoidance */
> + uint32_t tcps_sack_snxt; /* next SACK seq # for retransmission */
> + uint32_t tcps_rto; /* round-trip timeout, msec */
> + uint32_t tcps_mss; /* max segment size */
> + int tcps_retransmit; /* retransmit send event, boolean */
> + uint32_t tcps_rtt; /* smoothed avg round-trip time, msec */
> + uint32_t tcps_rtt_sd; /* standard deviation of RTT */
> + uint32_t tcps_irs; /* Initial recv sequence # */
> +} tcpsinfo_t;
> +```
> +
> +**Note:**
> +
> +DTrace translates the members of `tcpsinfo_t` from a `struct tcp_sock *`.
> +
> +### tcplsinfo\_t> +
> +The `tcplsinfo_t` structure has the old tcp state for state changes.
> +Detailed information about this data structure can be found in `/usr/lib64/dtrace/*version*/tcp.d`.
> +The definition of `tcplsinfo_t` is as follows:
> +
> +```nocopybutton
> +typedef struct tcplsinfo {
> + int tcps_state; /* previous TCP state */
> +} tcplsinfo_t;
> +```
> +
> +## tcp Stability
> +
> +The `tcp` 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 |