[DTrace-devel] [PATCH v2 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         | 76 +++++++++++++++++++
 3 files changed, 84 insertions(+)
 create mode 100644 doc/userguide/reference/dtrace_providers_udp.md

diff --git a/doc/userguide/index.md b/doc/userguide/index.md
index fa9d9d021..f86c8b9e5 100644
--- a/doc/userguide/index.md
+++ b/doc/userguide/index.md
@@ -266,6 +266,12 @@
             -   [tcpsinfo\_t](reference/dtrace_providers_tcp.md#dt_ref_tcptcps_prov)
             -   [tcplsinfo\_t](reference/dtrace_providers_tcp.md#dt_ref_tcptcpls_prov)
         -   [tcp Stability](reference/dtrace_providers_tcp.md#dt_ref_tcpstab_prov)
+    -   [UDP Provider](reference/dtrace_providers_udp.md)
+        -   [udp Probes](reference/dtrace_providers_udp.md#dt_ref_udpprobes_prov)
+        -   [udp Probe Arguments](reference/dtrace_providers_udp.md#dt_ref_udpargs_prov)
+            -   [udpsinfo\_t](reference/dtrace_providers_udp.md#dt_ref_udpudps_prov)
+            -   [udpinfo\_t](reference/dtrace_providers_udp.md#dt_ref_udpudp_prov)
+        -   [udp Stability](reference/dtrace_providers_udp.md#dt_ref_udpstab_prov)
     -   [USDT Provider](reference/dtrace-ref-StaticallyDefinedTracingofUserApplications.md#dt_ref_usdt_prov)
         -   [Defining USDT Providers and Probes](reference/dtrace-ref-StaticallyDefinedTracingofUserApplications.md#dt_ref_usdtprobes_prov)
         -   [Adding USDT Probes to Application Code](reference/dtrace-ref-StaticallyDefinedTracingofUserApplications.md#dt_ref_usdt_probe_add_prov)
diff --git a/doc/userguide/reference/dtrace_providers.md b/doc/userguide/reference/dtrace_providers.md
index 7da634d2a..f11bacb2f 100644
--- a/doc/userguide/reference/dtrace_providers.md
+++ b/doc/userguide/reference/dtrace_providers.md
@@ -31,6 +31,8 @@ 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..455f91e4d
--- /dev/null
+++ b/doc/userguide/reference/dtrace_providers_udp.md
@@ -0,0 +1,76 @@
+# 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 <a id="dt_ref_udpprobes_prov">
+
+`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 <a id="dt_ref_udpargs_prov">
+
+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 <a id="dt_ref_udpudps_prov">
+
+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 <a id="dt_ref_udpudp_prov">
+
+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 <a id="dt_ref_udpstab_prov">
+
+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