Rework README.md

README.md

-NOTE
+----------------------------------------------------
+====================================================
+    __ __          __            __
+   / //_/__  _____/ /_________  / /
+  / ,< / _ \/ ___/ __/ ___/ _ \/ /
+ / /| /  __(__  ) /_/ /  /  __/ /
+/_/_|_\___/____/\__/_/ __\___/_/ _________
+  / ___/____  / __/ /_/ __ )/  |/  / ____/
+  \__ \/ __ \/ /_/ __/ __  / /|_/ / /
+ ___/ / /_/ / __/ /_/ /_/ / /  / / /___
+/____/\____/_/  \__/_____/_/  /_/\____/
+
+====================================================
+----------------------------------------------------
+
+# Kestrel SoftBMC Project
+## Zephyr firmware files
+Copyright (c) 2020 - 2021 Raptor Engineering, LLC
+
+====================================================
+
+**NOTE**
+
 This application is developed on OpenPOWER (Raptor Computing Systems POWER9) host systems.  Other development systems may or may not work without significant effort.
 
 With that disclaimer out of the way...
 
-How to build:
-0.) Create directory to hold development sources and builds
-	mkdir kestrel-zephyr
-	cd kestrel-zephyr
-1.) Clone all repositories
-	git clone https://gitlab.raptorengineering.com/kestrel-collaboration/kestrel-firmware/zephyr-rtos
-	git clone https://gitlab.raptorengineering.com/kestrel-collaboration/kestrel-firmware/zephyr-firmware
-	git clone https://gitlab.raptorengineering.com/kestrel-collaboration/kestrel-firmware/mbedtls
-	git clone https://gitlab.raptorengineering.com/kestrel-collaboration/kestrel-firmware/civetweb
-	git clone https://gitlab.raptorengineering.com/kestrel-collaboration/kestrel-tooling/gcc
-2.) Build soft floating point library from GCC toolchain sources
-	NOTE:
-	This is a bit of a hack.  Unfortunately, our target platform is soft float, while most (all?) "real" OpenPOWER distros are hard float.
-	As a result, we need to compile a copy of the soft float static library for our target.
-
-	cd gcc/libgcc/soft-fp/
-	gcc -c -O2 -msoft-float -mno-string -mno-multiple -mno-vsx -mno-altivec -mlittle-endian -mstrict-align -fno-stack-protector -m64 -mabi=elfv2 -mcmodel=small -I../config/rs6000/ -I../../include -I.. *.c
-	<ignore expected errors>
-	ar -crv libsoft-fp.a *.o
-	cp -Rp libsoft-fp.a ../../../
-	cd ../../../
-3.) Build Zephyr application
-	export SOURCE_ROOT_DIR=$(pwd)
-	cd zephyr
-	mkdir build
-	ZEPHYR_BASE=${SOURCE_ROOT_DIR}/zephyr ZEPHYR_TOOLCHAIN_VARIANT=host cmake -DZEPHYR_MODULES="${SOURCE_ROOT_DIR}/littlefs;${SOURCE_ROOT_DIR}/mbedtls;${SOURCE_ROOT_DIR}/civetweb" -DBOARD=litex_kestrel ${SOURCE_ROOT_DIR}/zephyr-firmware
-	cp -Rp ../libsoft-fp.a zephyr/
-	make -j144
+# How to build
+
+1. Create directory to hold development sources and builds
+
+
+    mkdir kestrel-zephyr
+    cd kestrel-zephyr
+
+2. Clone all repositories
+
+
+    git clone https://gitlab.raptorengineering.com/kestrel-collaboration/kestrel-firmware/zephyr-rtos
+    git clone https://gitlab.raptorengineering.com/kestrel-collaboration/kestrel-firmware/zephyr-firmware
+    git clone https://gitlab.raptorengineering.com/kestrel-collaboration/kestrel-firmware/mbedtls
+    git clone https://gitlab.raptorengineering.com/kestrel-collaboration/kestrel-firmware/civetweb
+    git clone https://gitlab.raptorengineering.com/kestrel-collaboration/kestrel-tooling/gcc
+
+3. Build soft floating point library from GCC toolchain sources
+
+**NOTE**
+
+This is a bit of a hack.  Unfortunately, our target platform is soft float, while most (all?) "real" OpenPOWER distros are hard float.
+As a result, we need to compile a copy of the soft float static library for our target.
+
+    cd gcc/libgcc/soft-fp/
+    gcc -c -O2 -msoft-float -mno-string -mno-multiple -mno-vsx -mno-altivec -mlittle-endian -mstrict-align -fno-stack-protector -m64 -mabi=elfv2 -mcmodel=small -I../config/rs6000/ -I../../include -I.. *.c
+    <ignore expected errors>
+    ar -crv libsoft-fp.a *.o
+    cp -Rp libsoft-fp.a ../../../
+    cd ../../../
+
+4. Build Zephyr application
+
+
+    export SOURCE_ROOT_DIR=$(pwd)
+    cd zephyr
+    mkdir build
+    ZEPHYR_BASE=${SOURCE_ROOT_DIR}/zephyr ZEPHYR_TOOLCHAIN_VARIANT=host cmake -DZEPHYR_MODULES="${SOURCE_ROOT_DIR}/littlefs;${SOURCE_ROOT_DIR}/mbedtls;${SOURCE_ROOT_DIR}/civetweb" -DBOARD=litex_kestrel ${SOURCE_ROOT_DIR}/zephyr-firmware
+    cp -Rp ../libsoft-fp.a zephyr/
+    make -j144
 
 Output is in zephyr/zephyr.bin
-Pass to litex_term using the --kernel parameter
+
+# How to use
+
+1. Soft-load application onto FPGA
+
+
+    python3 litex/tools/litex_term.py --speed 115200 /dev/ttyUSB1 --kernel zephyr/build/zephyr/zephyr.bin
+    <using a second terminal, program the FPGA with openocd>
+    openocd --log_output openocd.log 3 -f "/usr/share/trellis/misc/openocd/ecp5-versa.cfg" -c "transport select jtag; init; svf build/versa_ecp5/gateware/versa_ecp5.svf; exit"
+
+2. Flash Kestrel onto the FPGA board (optional)
+
+Programming Kestrel onto the FPGA will provide a very rapid (under 10 seconds) startup from cold / no power applied to online and ready to IPL the host.  It requires three separate programming files, and Kestrel to be connected to the network and online via the openocd soft load process.  The files required are:
+
+
+    versa_ecp5.bit
+    zephyr.bin
+    pnor.img
+
+First, determine the IP address of the Kestrel system.  You can use the Zephyr shell (`exit` from the Kestrel shell, then `net iface`) to determine the IP address granted to the Kestrel system by the DHCP server.
+
+Once the IP address is known, use a Web browser to naviate to http://<BMC IP>:8080  Click the Firmware link, then select the `versa_ecp5.bit` file and upload.  After the upload has finished, run `kestrel reflash fpga` on the terminal.
+
+Next, navigate to the Firmware link again, and upload the `zephyr.bin` file.  After the upload has finished, run `kestrel reflash bmc` on the terminal.
+
+At this point, Kestrel itself is now installed and will survive a power cycle of the FPGA board.  In and of itself it is not very useful until the host firmware is uploaded, however.
+
+Uploading the host firmware will take a long time, as the PNOR is 64MB for Raptor Computing Systems devices.  After starting the upload grab a cup of coffee, then once the upload is finished run `kestrel reflash pnor`
+
+3. Control the host
+
+Most commands to interact with the host are contained within the `kestrel` subcommand.  Important commands include:
+
+
+    obmcutil poweron
+    obmcutil chassisoff
+    obmc-console-client
\ No newline at end of file