[DTrace-devel] [PATCH 19/20] doc: Add UDP provider documentation

[eugene.loh at oracle.com]

From: Eugene Loh <eugene.loh at oracle.com>

Signed-off-by: Eugene Loh <eugene.loh at 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

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