user-doc: document Google flashrom

user-doc/user-doc.tex

@@ -118,7 +118,7 @@ Figure~\ref{fig:bp36-connect} shows how to connect the BusPirate v3.6a with the
 Connect the \emph{Chip Select} (CS) pins using the white cable, the \emph{Master In Slave Out} (MISO) pin with the \emph{Data Out} (DO) pin using the black cable, the \emph{Master Out Slave In} (MOSI) pin with the \emph{Data In} (DI) pin using the grey cable and the \emph{Clock} (CLK) pins using the purple cable.
 Further, the \emph{Ground} (GND) pins should be connected using the brown cable and the 5V and the VCC pins should be connected with the orange cable.
 In order for the SPI NOR flash chip to function, the H/R pin of the SPI NOR flash chip should be pulled high, this can be done by connecting the 5V pin with the H/R pin.
-Finally, to be able to program the chip in case write-protection has been configured before, we have to make sure that the \emph{Write-Protect} (WP) is pulled low to disable write-protection.
+Finally, to be able to program the chip in case write-protection has been configured before, we have to make sure that the \emph{Write-Protect} (WP) is pulled high to disable write-protection.
 
 \begin{figure}[H]
 \centering
@@ -151,6 +151,77 @@ Finally, to be able to program the chip in case write-protection has been config
 \label{fig:bp36-connect}
 \end{figure}
 
+Because the configuration of write-protection is vendor-specific, the mainline version of \emph{flashrom} does not support configuring write-protection.
+Therefore, to be able to configure the write-protection of the SPI NOR flash chip, we have to use Google's fork of \emph{flashrom}.
 
+Unlike the mainline version of flashrom, Google's fork has two flags to get the name and the
+size of the Flash chip:
+
+\begin{minted}{text}
+./flashrom --programmer=buspirate_spi:dev=/dev/buspirate --flash-name
+flashrom v0.9.4  : bc6cab1 : Oct 30 2014 07:32:01 UTC on Linux 4.9.4-gentoo (x86_64), built with libpci 3.1.10, GCC 4.8.x-google 20140307 (prerelease), little endian
+vendor="Macronix" name="MX25L6406E"
+./flashrom --programmer=buspirate_spi:dev=/dev/buspirate --get-size
+flashrom v0.9.4  : bc6cab1 : Oct 30 2014 07:32:01 UTC on Linux 4.9.4-gentoo (x86_64), built with libpci 3.1.10, GCC 4.8.x-google 20140307 (prerelease), little endian
+8388608
+\end{minted}
+
+Further, Google's fork of flashrom allows us to tag regions on the SPI NOR flash chip with a custom name.
+Assuming that the SPI NOR flash chip is 8 MiB, that the u-boot image is 512 kiB and that the Linux image is 3.5 MiB, we will be using the following \path{layout.txt} file for the ROTS:
+
+\begin{minted}{text}
+000000:07ffff uboot
+080000:3fffff linux
+400000:7fffff initramfs
+\end{minted}
+
+We can then write \path{u-boot.bin}, \path{bzImage} and \path{initramfs.cpio.gz} to the SPI NOR flash chip by using the respective names of the regions.
+To speed up the process of writing these images, we have to disable parsing the fmap and the verification of unmodified regions.
+Furthermore, to maintain an optimal stability, an SPI speed of no more than 2 MHz is recommended when using the BusPirate v3.6a:
+
+\begin{minted}{text}
+./flashrom --programmer=buspirate_spi:dev=/dev/buspirate -l layout.txt -i uboot:u-boot.bin linux:bzImage initramfs:initramfs.cpio.gz -w --ignore-fmap --fast-verify
+\end{minted}
+
+Now that the images have been written to their respective regions, we can look at the write-protect ranges supported by the chip:
+
+\begin{minted}{text}
+./flashrom --programmer=buspirate_spi:dev=/dev/buspirate --wp-list
+flashrom v0.9.4  : bc6cab1 : Oct 30 2014 07:32:01 UTC on Linux 4.9.4-gentoo (x86_64), built with libpci 3.1.10, GCC 4.8.x-google 20140307 (prerelease), little endian
+Valid write protection ranges:
+start: 0x000000, length: 0x000000
+start: 0x7e0000, length: 0x020000
+start: 0x7c0000, length: 0x040000
+start: 0x7a0000, length: 0x080000
+start: 0x700000, length: 0x100000
+start: 0x600000, length: 0x200000
+start: 0x400000, length: 0x400000
+start: 0x000000, length: 0x800000
+start: 0x000000, length: 0x800000
+start: 0x000000, length: 0x400000
+start: 0x000000, length: 0x600000
+start: 0x000000, length: 0x700000
+start: 0x000000, length: 0x780000
+start: 0x000000, length: 0x7c0000
+start: 0x000000, length: 0x7e0000
+start: 0x000000, length: 0x800000
+\end{minted}
+
+Since we don't want our images to be tampered with, we want to enable write-protection for the full range.
+We can configure the write-protected range as follows:
+
+\begin{minted}{text}
+./flashrom --programmer=buspirate_spi:dev=/dev/buspirate --wp-range 0x000000 0x800000
+\end{minted}
+
+After setting the range, we are still able to modify the contents of the entire SPI NOR flash chip.
+To protect the range, we have to enable write protection as follows:
+
+\begin{minted}{text}
+./flashrom --programmer=buspirate_spi:dev=/dev/buspirate --wp-enable
+\end{minted}
+
+Upon enabling write-protection, the \emph{Write-Protect} (WP) pin has to be pulled low for the write-protection to be effective.
+This prevents the user from disabling the write-protection feature, changing the write-protect range and from writing to the write-protected region.
 
 \end{document}