user-doc: add instructions to build, flash and configure the TBM firmware.

user-doc/user-doc.tex

@@ -386,4 +386,157 @@ At some point the kernel will run the init script in the initramfs.
 When this happens the ROTS will start communicating with the TBM to fetch the time as well as the certificates.
 Once these have been retrieved from the TBM, the ROTS will mount the external media such as hard disks and enumerate and verify possible boot images on those media.
 
+\section{Trusted Boot Module}
+
+In this section the process of building, flashing and configuring the firmware for the TBM is described.
+
+\subsection{Building}
+
+A cross-compiler targetting ARMv6 or ARMv7-M such as the GNU ARM Embedded Toolchain is required to build the source code for the Trusted Boot Module.
+Either install it using your package manager or download the toolchain from https://developer.arm.com/open-source/gnu-toolchain/gnu-rm.
+For Gentoo users, an ebuild is available in the tbm-overlay repository.
+Building your own cross-compiler using a tool like crossdev can be quite tricky, and is therefore discouraged.
+
+To build the source code in this repository, you will also need libopencm3.
+Download the source code for libopencm3 and build it as follows:
+
+\begin{minted}[breaklines]{text}
+git submodule init
+git submodule update
+make -C libopencm3
+\end{minted}
+
+To build the code for the Trusted Boot Module, run:
+
+\begin{minted}[breaklines]{text}
+TARGET=stm32f1 make
+\end{minted}
+
+\subsection{Flashing}
+
+Connect your computer with a JTAG device and connect the I/O, CLK, GND and VDD wires with the SWD pin-out of the TBM.
+Run the following as root:
+
+\begin{minted}[breaklines]{text}
+TARGET=stm32f1 make openocd
+\end{minted}
+
+If OpenOCD, the JTAG device and the TBM are functioning correctly, OpenOCD should report the available breakpoint registers.
+To flash the firmware onto the device, run the following command:
+
+\begin{minted}[breaklines]{text}
+TARGET=stm32f1 make run
+\end{minted}
+
+Close OpenOCD and disconnect the power from the TBM, then detach the I/O and CLK wires.
+
+\subsection{Configuration}
+
+Download the source code for gorots and build the admin utility as follows:
+
+\begin{minted}[breaklines]{text}
+go build
+\end{minted}
+
+Attach a serial cable to the debugging serial interface of the TBM.
+Power on the TBM using an external power source such as a JTAG adapter.
+Run the {\tt prepare.sh} script to perform an initial configuration of the TBM.
+This script will also perform tests to ensure the hardware is functioning as expected.
+
+\section{Using gorots}
+
+The gorots package consists of two tools: {\tt admin} and {\tt protocol}.
+The {\tt protocol} utility is used by the ROTS to communicate with the user serial interface.
+The {\tt admin} utility is used with the admin serial interface of the TBM to configure it.
+
+The following commands are available for the {\tt admin} utility:
+
+\begin{itemize}
+\item {\tt ./admin echo <string>}
+
+Returns the string passed as an argument to echo.
+\item {\tt ./admin flash\_probe}
+
+Mounts the SPI NOR flash device as a raw device.
+\item {\tt ./admin flash\_erase <offset> <length>}
+
+Erases the region provided by the offset and the length in blocks.
+
+\item {\tt ./admin ftl\_probe}
+
+Mounts the SPI NOR flash device and initialises the Flash Translation Layer.
+
+\item {\tt ./admin date}
+
+Returns the current time formatted as a human-readable date.
+
+\item {\tt ./admin time}
+
+Returns the current time in seconds since the UNIX epoch.
+
+\item {\tt ./admin set-time <seconds>}
+
+Sets the current time to the given time in seconds since the UNIX epoch.
+
+\item {\tt ./admin sync-time }
+
+Synchronizes the current time of the TBM with the current time of the host device
+		
+		\item {\tt ./admin set-time <seconds>}
+			
+		Sets the current time to the given time in seconds since the UNIX epoch.
+		
+\item {\tt ./admin sync-time }
+
+Synchronizes the current time of the TBM with the current time of the host device.
+
+\item {\tt ./admin mount }
+
+Mounts the filesystem on the flash device.
+
+\item {\tt ./admin umount}
+
+Unmounts the currently mounted filesystem.
+
+\item {\tt ./admin format}
+
+Formats the filesystem of the flash device.
+
+\item {\tt ./admin mkdir <path>}
+
+Creates a directory at the given path, if the path does not yet exist and if the parent is a directory.
+
+\item {\tt ./admin rmdir <path>}
+
+Removes the directory at the given path, if the path exists and points to a directory.
+
+\item {\tt ./admin ls <path>}
+
+Lists the files in the given path, if the path exists and points to a directory.
+
+\item {\tt ./admin cat <path>}
+
+Concatenates the file with the standard output.
+
+\item {\tt ./admin write <path> <file>}
+
+Writes the contents of the file to the file at the given path. Creates a new file if the path does not point to an existing file. Otherwise the file will be truncated first.
+
+\item {\tt ./admin append <path> <file>}
+
+Appends the contents of the file to the file at the given path. Creates a new file if the path does not point to an existing file.
+
+\item {\tt ./admin mv <old> <new>}
+
+Moves the file or directory from the old path to the new path.
+
+\item {\tt ./admin cp <old> <new>}
+
+Copies the contents of the file from the old path to the file pointed to by the new path. Creates a file at the new path if it does not exist yet. Otherwise the file is truncated before copying the contents.
+
+\item {\tt ./admin rm <path>}
+
+Removes the file at the given path, if the path exists and points to a file.
+\end{itemize}
+
 \end{document}