[DTrace-devel] [PATCH 20/20] doc: Add rawfbt 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                        |  4 ++
 doc/userguide/reference/dtrace_providers.md   |  2 +
 .../reference/dtrace_providers_rawfbt.md      | 51 +++++++++++++++++++
 3 files changed, 57 insertions(+)
 create mode 100644 doc/userguide/reference/dtrace_providers_rawfbt.md

diff --git a/doc/userguide/index.md b/doc/userguide/index.md
index 4eb682a8a..d76c4bed4 100644
--- a/doc/userguide/index.md
+++ b/doc/userguide/index.md
@@ -241,6 +241,10 @@
         -   [profile Probe Arguments](reference/dtrace_providers_profile.md#profile-probe-arguments)
         -   [profile Probe Creation](reference/dtrace_providers_profile.md#profile-probe-creation)
         -   [profile Stability](reference/dtrace_providers_profile.md#prof-stability)
+    -   [Raw FBT Provider](reference/dtrace_providers_rawfbt.md)
+        -   [rawfbt Probes](reference/dtrace_providers_rawfbt.md#rawfbt-probes)
+        -   [rawfbt Probe Arguments](reference/dtrace_providers_rawfbt.md#rawfbt-probe-arguments)
+        -   [rawfbt Stability](reference/dtrace_providers_rawfbt.md#rawfbt-stability)
     -   [Rawtp Provider](reference/dtrace_providers_rawtp.md)
         -   [rawtp Stability](reference/dtrace_providers_rawtp.md#rawtp-stability)
     -   [Sched Provider](reference/dtrace_providers_sched.md)
diff --git a/doc/userguide/reference/dtrace_providers.md b/doc/userguide/reference/dtrace_providers.md
index 450adf9bb..6d9d29131 100644
--- a/doc/userguide/reference/dtrace_providers.md
+++ b/doc/userguide/reference/dtrace_providers.md
@@ -21,6 +21,8 @@ The `pid` provider traces a user process, both function `entry` and `return`, an
 The `proc` provider makes available the probes that pertain to the following activities: process creation and termination, LWP creation and termination, execution of new program images, and signal sending and handling.
 -   **[Profile Provider](../reference/dtrace_providers_profile.md)**
 The `profile` provider includes probes that are associated with an interrupt that fires at some regular, specified time interval.
+-   **[Raw FBT Provider](../reference/dtrace_providers_rawfbt.md)**  
+The `rawfbt` provider is a version of the `fbt` provider based on kprobes and allowing probing of synthetic function variants generated by the compiler.
 -   **[Rawtp Provider](../reference/dtrace_providers_rawtp.md)**  
 The `rawtp` provider gives DTrace users access to the raw tracepoints exposed by the kernel tracing system, including access to the untranslated arguments of the associated tracepoint events.
 -   **[Sched Provider](../reference/dtrace_providers_sched.md)**
diff --git a/doc/userguide/reference/dtrace_providers_rawfbt.md b/doc/userguide/reference/dtrace_providers_rawfbt.md
new file mode 100644
index 000000000..9e4d5bf3c
--- /dev/null
+++ b/doc/userguide/reference/dtrace_providers_rawfbt.md
@@ -0,0 +1,51 @@
+
+# Raw FBT Provider
+
+The [fbt provider](../reference/dtrace_providers_fbt.md) consists of
+probes that are associated with the entry to and return from most functions
+in the Linux kernel.  It does not support tracing synthetic functions,
+that is, compiler-generated functions with a . in their name.
+
+In contrast, the `rawfbt` provider implements a variant of the FBT provider
+and always uses kprobes.  It does allow tracing of synthetic functions, such
+as compiler-generated optimized variants of functions with . suffixes.
+
+You can see the raw FBT probes on your system with:
+
+```
+sudo dtrace -lP rawfbt
+```
+
+As with the `fbt` provider, there could be tens of thousands of probes,
+and effective use requires knowledge of the kernel implementation.
+
+**Parent topic:**[DTrace Provider Reference](../reference/dtrace_providers.md)
+
+## rawfbt Probes
+
+The module name of a `rawfbt` probe is `vmlinux` for built-in modules.
+The function name is the probed function.
+The probe name is either `entry` or `return`.
+
+## rawfbt Probe Arguments
+
+The arguments to `entry` probes are the same as the arguments to the corresponding operating system kernel function.
+These arguments can be accessed as `int64_t` values by using the `arg0`, `arg1`, `arg2`, ... variables.
+
+If the function has a return value, the return value is stored in `arg1` of the `return` probe.
+If a function doesn't have a return value, `arg1` isn't defined.
+
+There are no typed `args[]` arguments for any `rawfbt` probes.
+
+## rawfbt Stability
+
+The `rawfbt` 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       | Common           |
+| Module    | Private        | Private        | Unknown          |
+| Function  | Private        | Private        | ISA              |
+| Name      | Evolving       | Evolving       | Common           |
+| Arguments | Private        | Private        | ISA              |
-- 
2.47.3