[18/18] htm: Documentation update

Signed-off-by: Michael Neuling <mikey@neuling.org>
---
 README.md | 32 +++++++++++++++-----------------
 1 file changed, 15 insertions(+), 17 deletions(-)

Thanks Mikey, I've merged this series although I've not tested it. I assume I
need some other firmware/override magic that is not documented below to make
this run? Is there any reason we couldn't include all the overrides or at least
some documentation on what override bits are required to actually make this
usable (eg. putspy/scom, etc.) in the documentation?

Otherwise I fear this information will get lost again and we won't be able to
reproduce the working environment you were testing with. Thanks.

- Alistair

On Tuesday, 19 June 2018 3:25:35 PM AEST Michael Neuling wrote:
> Signed-off-by: Michael Neuling <mikey@neuling.org>
> ---
>  README.md | 32 +++++++++++++++-----------------
>  1 file changed, 15 insertions(+), 17 deletions(-)
> 
> diff --git a/README.md b/README.md
> index f462df0240..a698703709 100644
> --- a/README.md
> +++ b/README.md
> @@ -330,27 +330,25 @@ $  sudo ./pdbg -p 0  getmem -ci 0x0003ffff40000000 4 |hexdump -C
>  ```
>  
>  ### Hardware Trace Macro
> -Expoitation of HTM is limited to POWER9 NestHTM from the powerpc host.
> -POWER8 (core and nest( is currently experimental. The dump files
> -should be correct but have not been confirmed to be.
> -
> -Using HTM requires a kernel built with both `CONFIG_PPC_MEMTRACE=y`
> -(v4.14) and `CONFIG_SCOM_DEBUGFS=y`. debugfs should be mounted at
> -`/sys/kernel/debug`.
>  
> -pdbg provides a `htm` command with a variety of subcommands:
> - - `trace` will configure the hardware and start tracing
> - - `analyse` which still stop the trace and dump the result to a file
> +Expoitation of HTM is limited to POWER9 NestHTM from the powerpc host.
> +POWER8 (core and nest).
>  
> +pdbg provides a `htm` command with a variety of subcommands the most
> +useful command is `record` which will start the trace, wait for buffer
> +to fill (~1 sec), stop and then dump (~5 sec). eg.
>  ```
> -./pdbg -b host -d p9 -a htm trace
> -[allow test to run]
> -./pdbg -b host -d p9 -a htm analyse
> +pdbg -p0 -c4 core htm record
>  ```
> -If you are running into a checkstop issue, `htm trace` will print the
> +There are also low level commands which can also be used:
> + - `start` will configure the hardware and start tracing in wrapping mode.
> + - `stop` will still stop the trace and deconfigure the hardware
> + - `dump` will dump the trace to a file
> +
> +If you are running into a checkstop issue, `htm status` will print the
>  physical address of the buffer it is tracing into and the BMC can be
>  used to recover this memory after checkstop see `getmem`.
>  
> -pdbg also provides some of the basic functionality to use HTM, such as
> -`htm reset`, `htm start` and `htm stop` to perform each step manually
> -if required.
> +Using HTM requires a kernel built with both `CONFIG_PPC_MEMTRACE=y`
> +(v4.14) and `CONFIG_SCOM_DEBUGFS=y`. debugfs should be mounted at
> +`/sys/kernel/debug`. Ubuntu 18.04 has this by default.
>

On Mon, 2018-06-25 at 15:25 +1000, Alistair Popple wrote:
> Thanks Mikey, I've merged this series although I've not tested it. I assume I
> need some other firmware/override magic that is not documented below to make
> this run? Is there any reason we couldn't include all the overrides or at
> least
> some documentation on what override bits are required to actually make this
> usable (eg. putspy/scom, etc.) in the documentation?

Good point, yes there is some special P8 firmware that you need unfortunately.
This is the weakest link in this process.

I have a list of inits (ie spys), but I'm not sure if I can make that public
though. Even if I did, there is no way with pdbg alone to check them and there
is no way with external firmware build tools to rebuild them.

> Otherwise I fear this information will get lost again and we won't be able to
> reproduce the working environment you were testing with. Thanks.

Yep

Mikey