Flesh out documentation even more

.github/workflows/deploy.yml

@@ -1,7 +1,7 @@
 name: Deploy
 on:
   push:
-    branches: [ "master", "task/docs" ] # TODO -- remove task/docs from this list after finished debugging
+    branches: [ "master" ]
 
 jobs:
   deploy:

docs/src/SUMMARY.md

@@ -3,8 +3,8 @@
 - [Introduction](intro.md)
 
 - [Getting Started](intro/getting_started.md)
-  - [WIP - Grammar](intro/grammar.md)
-  - [WIP - Events](intro/events.md)
+  - [Language](intro/language.md)
+  - [Events](intro/events.md)
   - [WIP - Libraries](intro/libraries.md)
   - [WIP - Testing](intro/testing.md)
   - [WIP - Injection Strategies](intro/injection_strategies.md)

docs/src/intro.md

@@ -11,7 +11,7 @@ This book will help you [get on the right track](intro/getting_started.md) when
 Here are some of the goals of `whamm!`:
 1. is **high-level** and **intuitive**
 2. instrumentation is **easy-to-build**, [**testable**](intro/testing.md), and **debuggable**
-3. express instrumentation in terms of [**predicated probes**](intro/grammar.md)
+3. express instrumentation in terms of [**predicated probes**](intro/language.md)
 4. can instrument **[events](intro/events.md) of different granularity**
 5. provide **[behavior](intro/libraries.md) as Wasm functions**, say where to call them in `whamm!`
 6. **write instrumentation once**, `whamm!` takes care of the [injection strategy](intro/injection_strategies.md).

docs/src/intro/events.md

@@ -1,2 +1,15 @@
 # Instrumentable Events #
-TODO
+
+Currently available `packages`:
+- `wasm:bytecode`, e.g. `wasm:bytecode:call:alt`
+
+`Packages` to be added:
+- `thread` operation events
+- `gc` operation events
+- `function` enter/exit/unwind events, e.g. `wasm:fn:enter:before`
+- `memory` access (read/write) events
+- `table` access (read/write) events
+- WASI `component` operation events, e.g. `wasi:http:send_req:alt`
+- `BEGIN`/`END` events
+- `traps`
+- `exception` throw/rethrow/catch events

docs/src/intro/getting_started.md

@@ -28,6 +28,9 @@ This is an example of manipulating an application's dynamic behavior through cha
 
 Continue reading through this book's "getting started" content for how to write such _monitors_ and _manipulators_.
 
+# Architecture #
+TODO
+
 # Helpful Tools #
 
 Here are some tools that may help when working with Wasm:

docs/src/intro/language.md

@@ -1,20 +1,69 @@
-# Grammar
+# The Language #
 
-
-This DSL enables tool implementers to express their instrumentation in terms of program events and corresponding predicated actions; "When _this event_ occurs during program execution, do _these actions_ if _this predicate_ (or conditional) evaluates to true."
+`whamm!` enables tool implementers to express their instrumentation in terms of program _events_ and corresponding _predicated actions_;
+"When _this event_ occurs during program execution, do _these actions_ if _this predicate_ (or conditional) evaluates to `true`."
 This abstraction provides a high-level and intuitive syntax that can target events at various granularities in the instrumented program.
 
-We use the term `probe` to refer to this triple of `event`, `predicate` and `actions`.
+Here is a high-level abstraction of the grammar:
+```
+// Statements to initialize the global state of the instrumentation
+global_statements;
+...
+
+// An example of what a `probe` would look.
+// There can be many of these in a monitor.
+provider:package:event:mode / predicate / {
+  probe_statements;
+  ...
+}
+```
+
+## Helpful `info` in CLI ##
+`whamm info --help`
+
+The `info` command provided by the CLI is a great resource to view what can be used as the probe specification.
+This command provides documentation describing the specification parts as well as the globals and functions in scope, which can help users learn about how to build their instrumentation.
+
+## Probes ##
+`<probe_specification> / <predicate> / { <actions> }`
+
+We use the term `probe` to refer to this triple of `probe_specification`, `predicate` and `actions`.
+
+When performing bytecode rewriting, `whamm!`:
+1. traverses the application's Wasm module to find the locations-of-interest as specified by each probe's `probe_specification`.
+2. checks if the `predicate` evaluates to `false` statically
+   - if it does evaluate to `false` it continues on, not injecting the probe's actions
+   - if it does not evaluate to `false`, it injects the probe's actions at that location along with the folded `predicate`.
+     - if the `predicate` evaluates to `true` statically, it will simply inject the actions into the program un-predicated.
+     - if the `predicate` does not fold to a simple `boolean` value, it will inject predicated actions into this location.
+       The predicate will then be evaluated dynamically when the application runs to conditionally execute the probe actions.
+
+### The Probe Specification ###
+`provider:package:event:mode`
+
+The `probe_specification` is a way to express some "location" you want to instrument for your program.
+
+| _part_       | _description_                                                                                                                               |
+|--------------|---------------------------------------------------------------------------------------------------------------------------------------------|
+| **provider** | The name of the `provider` that supports this instrumentation capability used in this probe.                                                |
+| **package**  | The name of the `package` within the specified provider that supports the instrumentation capability used in this probe.                    |
+| **event**    | The name of the `event` that would correlate with the location to insert this probe in the instrumented program.                            |
+| **mode**     | The name of the `mode` that should be used when emitting the probe actions at the `event`'s location, such as `before`, `after`, and `alt`. |
+
+Each part of the `probe_specification` gradually increases in specificity until reaching the `mode` of your probe.
+Consider the following example specification: `wasm:bytecode:br_if:before`.
+This spec can be read as "Insert this probe _before_ each of the _br_if_ _Wasm_ _bytecode_ instructions in my program."
 
-The overarching goal of this DSL is to enable tool implementers to write instrumentation in an intuitive way, by express
-At a high level, we wish to insert probes into a WebAssembly application, to gain some insights into its execution.
-A probe is a location or activity to which Whamm can bind a request to perform a set of actions, like recording a stack trace, a timestamp, or the argument to a function.
-Probes are like programmable sensors scattered all over your wasm application in interesting places.
+Read through our [instrumentable events](events.md) documentation for what we currently support and our future goals.
 
-For a comprehensive guide on using DTrace and the D language, see [the Dynamic Tracing Guide](https://illumos.org/books/dtrace/bookinfo.html).
+### The Predicate ###
+`/ <predicate> /`
 
-![one liner](../images/oneliner.png)
+The `predicate` is a way to express some "conditional" you want to evaluate to `true` for the probe's actions to be executed.
+This aspect of a probe is optional to use.
+If there is no `predicate` for some probe, the `actions` will always execute when the probe's location is reached during program execution.
 
+### The Actions ###
+`{ <actions> }`
 
-Every whamm clause begins with a list of one or more probe descriptions (red), each taking the usual form: 
-*<p style="text-align: center;">*provider:module:function:name*</p>*
+The `actions` are statements that are executed at the `probe_specification`'s location if the `predicate` evaluates to `true`.

docs/src/intro/libraries.md

@@ -0,0 +1,10 @@
+# Libraries #
+
+## How does `whamm!` use libraries? ##
+TODO
+
+## Provided libraries ##
+TODO
+
+## Building and using custom libraries ##
+TODO