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

Alan Maguire
2025-10-24T08:18:43Z

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>
> ---
> 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 <alan.maguire@oracle.com>

> 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 |