From 61ec9b7ed71e9516f579c90e588403d3cc0a1d22 Mon Sep 17 00:00:00 2001
From: NIIBE Yutaka <gniibe@fsij.org>
Date: Thu, 2 Aug 2012 17:11:42 +0900
Subject: [PATCH] add doc

---
 doc/development.rst | 24 +++++++++++++++++++++++-
 doc/intro.rst       | 36 ++++++++++++++++++++++++++++++------
 2 files changed, 53 insertions(+), 7 deletions(-)

diff --git a/doc/development.rst b/doc/development.rst
index df3d30f..cb0c259 100644
--- a/doc/development.rst
+++ b/doc/development.rst
@@ -5,7 +5,29 @@ Development Environment
 Hardware
 --------
 
-JTAG debugger or SWD debugger is required.
+For development, it is highly recommended to have JTAG debugger or SWD
+debugger.
+
+For boards with DFU (Device Firmware Upgrade) feature, such as DfuSe,
+it is possible to develop with that.  But it should be considered
+*experimental* environment, and it should not be used for usual
+purpose.  That's because it is basically impossible for DfuSe
+implementations to disable reading-out from flash ROM.  It means
+that your secret will be readily extracted by DfuSe.
+
+For JTAG debugger, Olimex JTAG-Tiny is good and supported well.  For
+SWD debugger, ST-Link/V2 would be good, and it is supported by
+the tool of tool/stlinkv2.py.
+
+
+OpenOCD
+-------
+
+For JTAG debugger or SWD debugger, we can use OpenOCD.
+
+Note that ST-Link/V2 is *not* supported by OpenOCD 0.5.0.  It will be
+supported by version 0.6 or later, as current development version
+supports it.
 
 
 GNU Toolchain
diff --git a/doc/intro.rst b/doc/intro.rst
index 63933b4..792018b 100644
--- a/doc/intro.rst
+++ b/doc/intro.rst
@@ -13,17 +13,41 @@ STM32F103 processor.
 Cryptographic token and feature of Gnuk
 ---------------------------------------
 
-Cryptographic token is a store of private keys and it computes cryptographic functions on the device.
+Cryptographic token is a store of private keys and it computes cryptographic
+functions on the device.
+
+The idea is to separate important secrets to independent device, 
+from where nobody can extract them.
 
 
 Development Environment
 -----------------------
 
-See :doc:`development` for development environment for Gnuk.  It builds on Free Software.
+See :doc:`development` for development environment for Gnuk.
+Gnuk is developed on the environment where there are only Free Software.
 
 
-Prerequisites
--------------
+Target boards for running Gnuk
+------------------------------
+
+Hardware requirement for Gnuk is the micro controller STM32F103.
+In version 1.0, Gnuk supports following boards.
+
+* FST-01 (Flying Stone Tiny ZERO-ONE)
+
+* Olimex STM32-H103
+
+* CQ STARM
+
+* STBee
+
+* STBee Mini
+
+* STM32 part of STM8S Discovery Kit
+
+
+Host prerequisites for using Gnuk Token
+---------------------------------------
 
 * GNU Privacy Guard (GnuPG)
 
@@ -36,8 +60,8 @@ Prerequisites
 * Web: scute, firefox
 
 
-Usage
------
+Usages
+------
 
 * Sign with GnuPG
 * Decrypt with GnuPG