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

[Alan Maguire <alan.maguire@oracle.com>]

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              |