gsc_without_servod: update based on user comments

A few good suggestions were made by people who read this doc, this
patch introduces the recommended changes.

BUG=none
TEST=none

Signed-off-by: Vadim Bendebury <vbendeb@chromium.org>
Change-Id: Id6d58d8db670e0ed616b79b7f430618ab5d1d1eb
Reviewed-on: https://chromium-review.googlesource.com/c/chromiumos/platform/ec/+/3385607
Reviewed-by: Mary Ruthven <mruthven@chromium.org>

1 files changed, 41 insertions, 21 deletions

diff --git a/docs/gsc_without_servod.md b/docs/gsc_without_servod.md
index b3ce71371e..27a8019a8e 100644
--- a/docs/gsc_without_servod.md
+++ b/docs/gsc_without_servod.md
@@ -3,6 +3,10 @@
 This write up describes an alternative method of controlling GSC and Chrome
 OS devices using Servo Micro or C2D2 called `adapters` below.
 
+The version you are looking at might be not the latest and greatest, [this
+link](https://chromium.googlesource.com/chromiumos/platform/ec/+/refs/heads/cr50_stab/docs/gsc_without_servod.md)
+points to the most updated copy.
+
 In a typical setup these `adapters` are controlled by the `servod` utility.
 This a very powerful tool, it allows to control the huge amount of various
 Chrome OS devices, accounting for numerous differences between devices and
@@ -28,28 +32,21 @@ to a USB port on the workstation), four `/dev/ttyUSBx` devices are created on
 the workstation, which allow access to all consoles of the `adapter` and of the
 DUT.
 
-### Building Your Own Rescue Utility Outside Chroot
+Two helpful scripts available in `../util` in the Chrome OS Cr50 tree are
+`maptty.sh` which shows how the TTY devices map to the `adapter(s)` and
+`brescue.sh` which takes care of invoking `rescue` with proper command line
+parameters (see below information about recovering from botched GSC updates).
 
-The only missing component is the `rescue` utility. If you are working inside
-Chrome OS chroot the utility can be generated by running `sudo emerge
-cr50-utils` and it becomes available as `/usr/bin/cr50-rescue`.
+If you don't have Chrome OS chroot, to access the scripts you can clone the EC
+tree as follows:
 
-If you are working outside chroot you can build your own `rescue` executable
-as follows (these instructions are for a recent Debian Mint environment,
-installing necessary packages could require different commands on different
-Linux distributions):
 ```
-$ git clone https://chrome-internal.googlesource.com/chromeos/platform/cr50-utils
-$ cd cr50-utils/software/tools/SPI
-$ sudo apt-get install libc6 libelf-dev libgcc-s1 libssl-dev libstdc++6 libudev1 libusb-1.0-0-dev zlib1g
-$ make rescue
+$ git clone https://chromium.googlesource.com/chromiumos/platform/ec
+$ cd ec
+$ git checkout -b cr50 origin/cr50_stab
+$ ls util/{maptty,brescue}.sh
+util/brescue.sh*  util/maptty.sh*
 ```
-This will create the `rescue` utility in the local directory, place it
-somewhere to make it available through `PATH`.
-
-Two helpful scripts available in `../util` are `maptty.sh` which shows how
-the TTY devices map to the `adapter(s)` and `brescue.sh` which takes care of
-invoking `rescue` with proper command line parameters.
 
 ## Controlling DUT With Servo Micro
 
@@ -128,13 +125,36 @@ dedicated console command for resetiing the GSC:
 ```
 And this is all there is to using C2D2.
 
-## Performing GSC Rescue Procedure
+## GSC Rescue
 
-This operation allows to recover from a corrupted GSC RW, when it is not
+GSC Rescue operation allows to recover from a corrupted GSC RW, when it is not
 possible to update it using `gsctool`. Very few people outside of GSC firmware
 team would need to use this regularly, but it might come handy in situations
 like updating early DT chips.
 
+Rescue procedure requires a utility, which can communicate with the GSC over
+UART, the utility is called `rescue`.
+
+If you have Chrome OS chroot the utility can be generated by running `sudo
+emerge cr50-utils` and it becomes available as `/usr/bin/cr50-rescue`.
+
+### Building Your Own Rescue Utility Outside Chroot
+
+If you are working outside chroot you can build your own `rescue` executable
+as follows (these instructions are for a recent Debian Mint environment,
+installing necessary packages could require different commands on different
+Linux distributions):
+```
+$ git clone https://chrome-internal.googlesource.com/chromeos/platform/cr50-utils
+$ cd cr50-utils/software/tools/SPI
+$ sudo apt-get install libc6 libelf-dev libgcc-s1 libssl-dev libstdc++6 libudev1 libusb-1.0-0-dev zlib1g
+$ make rescue
+```
+This will create the `rescue` utility in the local directory, place it
+somewhere to make it available through `PATH`.
+
+### Performing GSC Rescue Procedure
+
 To rescue H1 or DT chip which has a corrupted RW but is still 'alive', i.e.
 reacts with the RO boot console output to reset pulse generated by the
 `adapter`, first obtain a firmware image to rescue it to. If you have a chroot
@@ -149,7 +169,7 @@ colleagues where to get a GSC image to use.
 Then to rescue the GSC chip, do the following:
 
  - disconnect terminal from the GSC console TTY device
- - invoke `./brescue.sh <path to the firmware image> <GSC console TTY device>`
+ - invoke `brescue.sh <path to the firmware image> <GSC console TTY device>`
  - generate GSC reset pulse using instructions based on the adapter used to
  connect to the GSC ([Servo Micro](#reset-gsc-using-servo-micro) or [C2D2](#reset-gsc-using-c2d2))