From 81ed5bce3391528ae08c6725712de3139dca13a3 Mon Sep 17 00:00:00 2001
From: Holger Hans Peter Freyther <zecke@selfish.org>
Date: Sat, 8 Oct 2011 15:25:53 +0200
Subject: [PATCH] doc: Introduce a chapter on the firmware

Begin to document how to get the firmware, how to build it, how to
flash it, how to hack on it. Some parts are not there yet.
---
 docs/chapters/firmware.xml | 44 ++++++++++++++++++++++++++++++++++++++
 docs/usermanual.xml        |  8 +++++++
 2 files changed, 52 insertions(+)
 create mode 100644 docs/chapters/firmware.xml

diff --git a/docs/chapters/firmware.xml b/docs/chapters/firmware.xml
new file mode 100644
index 0000000..a753b62
--- /dev/null
+++ b/docs/chapters/firmware.xml
@@ -0,0 +1,44 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="chapter_firmware">
+    <title>Getting and Building the Firmware</title>
+    <section id="building_fw_intro">
+        <title>Introduction</title>
+        <para>The Firmware is the Software that is running on the
+        Microcontroller of the SIMtrace hardware. The Firmware itself
+        consists out of a couple of components for different parts of
+        the system. Besides the source code for the firmware you will
+        also need to have an ARM Cross-Compile Toolchain, a copy of the
+        SAM7 utilities to initially program the device or recover from
+        a fatal error and dfu-util to update the main part of the firmware
+        using the Device Firmware Update (DFU) mode.</para>
+    </section>
+
+    <section id="getting_the_firmware">
+        <title>Getting and Building the Firmware</title>
+
+        <subsection>
+            <para>The SIMtrace firmware is based on the OpenPCD RFID Reader Firmware and the
+            SIMtrace firmware code is located in the OpenPCD repository. You can use the
+            <command>git</command> to clone the repository.
+            <screen>
+$ git clone git://git.gnumonks.org/openpcd.git
+            </screen>
+            </para>
+        </subsection>
+    
+        <subsection>
+            <para>The firmware consists out of two separate binaries that will be concatted
+            and flashed into the NOR flash of the microcontroller. The main part is the dfu
+            program that will handle basic USB functionality and respond to Device Firmware
+            Update (DFU) requests to allow to update the firmware in the NOR or execute
+            software in RAM.
+            <screen>
+$ cd openpcd/firmware
+$ make -f Makefile.dfu BOARD=SIMTRACE
+$ make BOARD=SIMTRACE DEBUG=1 TARGET=main_simtrace
+$ cat dfu.bin main_simtrace.bin > main_simtrace.samba
+$ cd ../..
+            </screen></para>
+        </subsection>
+    </section>
+</chapter>
diff --git a/docs/usermanual.xml b/docs/usermanual.xml
index 626b1dd..3c85255 100644
--- a/docs/usermanual.xml
+++ b/docs/usermanual.xml
@@ -10,6 +10,7 @@
 <!ENTITY chapter-hw-details SYSTEM "chapters/hardware_details.xml">
 <!ENTITY chapter-using-sniff SYSTEM "chapters/using_sniff.xml">
 <!ENTITY chapter-building SYSTEM "chapters/building.xml">
+<!ENTITY chapter-firmware SYSTEM "chapters/firmware.xml">
 <!ENTITY chapter-appendix SYSTEM "chapters/appendix.xml">
 ]>
 
@@ -34,6 +35,12 @@
             <authorinitials>z</authorinitials>
             <revremark>Document building wireshark</revremark>
         </revision>
+        <revision>
+            <revnumber>0.0.4</revnumber>
+            <date>8 October 2011</date>
+            <authorinitials>z</authorinitials>
+            <revremark>Document Firmware</revremark>
+        </revision>
     </revhistory>
 
     <title>SIMtrace Usermanual</title>
@@ -57,6 +64,7 @@
   &chapter-hw-details;
   &chapter-using-sniff;
   &chapter-building;
+  &chapter-firmware;
 
   &chapter-appendix;
 </book>