Re: [PATCH 19/20] doc: Add UDP provider documentation

On 26/09/2025 20:05, [email protected] wrote:
> From: Eugene Loh <[email protected]>
> 
> Signed-off-by: Eugene Loh <[email protected]>
> ---
>  doc/userguide/index.md                        |  6 ++
>  doc/userguide/reference/dtrace_providers.md   |  2 +
>  .../reference/dtrace_providers_udp.md         | 77 +++++++++++++++++++
>  3 files changed, 85 insertions(+)
>  create mode 100644 doc/userguide/reference/dtrace_providers_udp.md
>

as per IP provider I'd rework the table to have a line per probe and
column per parameter.

with that,

Reviewed-by: Alan Maguire <[email protected]>

> diff --git a/doc/userguide/index.md b/doc/userguide/index.md
> index d47df094b..4eb682a8a 100644
> --- a/doc/userguide/index.md
> +++ b/doc/userguide/index.md
> @@ -266,6 +266,12 @@
>              -   [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)
> +    -   [UDP Provider](reference/dtrace_providers_udp.md)
> +        -   [udp Probes](reference/dtrace_providers_udp.md#udp-probes)
> +        -   [udp Probe Arguments](reference/dtrace_providers_udp.md#udp-probe-arguments)
> +            -   [udpsinfo\_t](reference/dtrace_providers_udp.md#udpsinfo_t)
> +            -   [udpinfo\_t](reference/dtrace_providers_udp.md#udpinfo_t)
> +        -   [udp Stability](reference/dtrace_providers_udp.md#udp-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 029f62c54..450adf9bb 100644
> --- a/doc/userguide/reference/dtrace_providers.md
> +++ b/doc/userguide/reference/dtrace_providers.md
> @@ -31,5 +31,7 @@ The Statically Defined Tracing \(SDT\) provider \(`sdt`\) creates probes at site
>  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.
> +-   **[UDP Provider](../reference/dtrace_providers_udp.md)**  
> +The `udp` provider makes available a probe at UDP send and receive operations in the system.
>  -   **[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_udp.md b/doc/userguide/reference/dtrace_providers_udp.md
> new file mode 100644
> index 000000000..b3e0c3d2a
> --- /dev/null
> +++ b/doc/userguide/reference/dtrace_providers_udp.md
> @@ -0,0 +1,77 @@
> +
> +# UDP Provider
> +
> +The `udp` provider makes available a probe at UDP send operations in the system and a probe at receive.
> +
> +**Parent topic:**[DTrace Provider Reference](../reference/dtrace_providers.md)
> +
> +## udp Probes
> +
> +`udp` provides a probe for UDP sends and one for UDP receives.
> +The module name is always `vmlinux` and the function name is empty.
> +
> +## udp 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]` | `udpsinfo_t *` |
> +| `args[4]` | `udpinfo_t *`  |
> +
> +The `pktinfo_t`, `csinfo_t`, and `ipinfo_t` structures are described in [IP Provider](dtrace_providers_ip.md).
> +
> +### udpsinfo\_t
> +
> +The `udpsinfo_t` structure contains stable UDP details from `udp_t`.
> +Detailed information about this data structure can be found in `/usr/lib64/dtrace/*version*/udp.d`.
> +The definition of `udpsinfo_t` is as follows:
> +
> +```nocopybutton
> +typedef struct udpsinfo {
> +        uintptr_t udps_addr;
> +        uint16_t udps_lport;   /* local port */
> +        uint16_t udps_rport;   /* remote port */
> +        string udps_laddr;     /* local address, as a string */
> +        string udps_raddr;     /* remote address, as a string */
> +} udpsinfo_t;
> +```
> +
> +**Note:**
> +
> +DTrace translates the members of `udpsinfo_t` from a `struct udp_sock *`.
> +
> +### udpinfo\_t
> +
> +The `udpinfo_t` structure contains the UDP header fields.
> +Detailed information about this data structure can be found in `/usr/lib64/dtrace/*version*/udp.d`.
> +The definition of `udpinfo_t` is as follows:
> +
> +```nocopybutton
> +typedef struct udpinfo {
> +        uint16_t udp_sport;     /* source port */
> +        uint16_t udp_dport;     /* destination port */
> +        uint16_t udp_length;    /* total length */
> +        uint16_t udp_checksum;  /* headers + data checksum */
> +        struct udphdr *udp_hdr; /* raw UDP header */
> +} udpinfo_t;
> +```
> +
> +**Note:**
> +
> +DTrace translates the members of `udpinfo_t` from a `struct udphdr *`.
> +
> +## udp Stability
> +
> +The `udp` 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              |