[lldb/Docs] Document active and passive replay.

[labath]

This is really great, and a lot more than I hoped for (I was expecting a couple of doxygen comments). I have just two remarks:

• the "Inline Replay" section is written in past tense, while the rest of the document uses present statement-of-fact tense. It would be good to rephrase that to keep the style consistent.
• there's some confusion about the terminology, this patch uses the term "inline" replay, whereas the SB function name is "APIReplay". Part of reason for my confusion was that we also have "inline" tests, and so I thought the other patch refers to some special logic needed to replay inline tests (I guess that would have been obvious if I actually opened the patch, but I was busy so I figured I'd just start with the first patch in the series so we make some progress). "API" replay also doesn't really make it clear who is it that is replaying the API calls. I actually very much liked the terms "active" and "passive", which capture that disctinction very well and also don't conflict with anything else in lldb. Here they are mentioned as a sort of an after thought, but maybe we could make it so that these are the official names for the two modes ?

[JDevlieghere]

Thanks for the feedback!

[labath]

cool

lldb/docs/resources/reproducers.rst

 A reproducer can significantly improve a bug report, but it in itself is not
 sufficient. Always describe the expected and unexpected behavior. Just like the
 debugger can have bugs, the reproducer can have bugs too.
 
 
 Design
 ------
 
-Coming soon.
+
+Replay
+``````
+
+Reproducers support two replay modes. The main and most common mode is active
+replay. It's called active, because it's LLDB that is driving replay by calling
+the captured SB API functions one after each other. The second mode is passive
+replay. In this mode, LLDB sits idle until an SB API function is called, for
+example from Python, and then replays just this individual call.
+
+Active Replay
+^^^^^^^^^^^^^
+
+No matter how a reproducer was captured, they can always be replayed with the
+command line driver. When a reproducer is passed with the `--replay` flag, the
+driver short-circuits and passes off control to the reproducer infrastructure,
+effectively bypassing its normal operation. This works because the driver is
+implemented using the SB API and is therefore nothing more than a sequence of
+SB API calls.
+
+Replay is driven by the ``Registry::Replay``. As long as there's data in the
+buffer holding the API data, the next SB API function call is deserialized.
+Once the function is known, the registry can retrieve its signature, and use
+that to deserialize its arguments. The function can then be invoked, most
+commonly through the synthesized default replayer, or potentially using a
+custom defined replay function. This process continues, until more data is
+available or a replay error is encountered.
+
+During replay only a function's side effects matter. The result returned by the
+replayed function is ignored because it cannot be observed beyond the driver.
+This is sound, because anything that is passed into a subsequent API call will
+have been serialized as an input argument. This also works for SB API objects
+because the reproducers know about every object that has crossed the API
+boundary, which is true by definition for object return values.
+
+
+Passive Replay
+^^^^^^^^^^^^^^
+
+Passive replay exists to support running the API test suite against a
+reproducer. The API test suite is written in Python and tests the debugger by
+calling into its API from Python. To make this work, the API must transparently
+replay itself when called. This is what makes passive replay different from
+driver replay, where it is lldb itself that's driving replay. For passive
+replay, the driving factor is external.
+
+In order to replay API calls, the reproducers need a way to intercept them.
+Every API call is already instrumented with an ``LLDB_RECORD_*`` macro that
+captures its input arguments. Furthermore, it also contains the necessary logic
+to detect which calls cross the API boundary and should be intercepted. We were
+able to reuse all of this to implement passive replay.
+
+During passive replay is enabled, nothing happens until an SB API is called.
+Inside that API function, the macro detects whether this call should be
+replayed (i.e. crossed the API boundary). If the answer is yes, the next
+function is deserialized from the SB API data and compared to the current
+function. If the signature matches, we deserialize its input arguments and
+reinvoke the current function with the deserialized arguments. We don't need to
+do anything special to prevent us from recursively calling the replayed version
+again, as the API boundary crossing logic knows that we're still behind the API
+boundary when we re-invoked the current function.
+
+Another big difference with driver replay is the return value. While this
+didn't matter for driver replay, it's key for passive replay, because that's
+what gets checked by the test suite. Luckily, the ``LLDB_RECORD_*`` macros
+contained sufficient type information to derive the result type.
 
 Testing
 -------
 
 Reproducers are tested in the following ways:
 
  - Unit tests to cover the reproducer infrastructure. There are tests for the
    provider, loader and for the reproducer instrumentation.