doc

.gitignore

@@ -14,3 +14,4 @@ src/*.inc
 regnual/regnual.bin
 regnual/regnual.hex
 regnual/regnual.elf
+doc/_build

ChangeLog

@@ -1,3 +1,9 @@
+2012-07-21  Niibe Yutaka  <gniibe@fsij.org>
+
+	Documentation by Sphinx.
+	* doc/Makefile: New.
+	* doc/note: Old notes are moved here.
+
 2012-07-20  Niibe Yutaka  <gniibe@fsij.org>
 
 	* test/features/002_get_data_static.feature: Support CERTDO enabled

doc/Makefile

@@ -4,7 +4,7 @@
 # You can set these variables from the command line.
 SPHINXOPTS    =
 SPHINXBUILD   = sphinx-build
-PAPER         =
+PAPER         = a4
 BUILDDIR      = _build
 
 # Internal variables.

doc/development.rst

@@ -0,0 +1,60 @@
+Development Environment
+=======================
+
+
+Hardware
+--------
+
+JTAG debugger or SWD debugger is required.
+
+
+GNU Toolchain
+-------------
+
+You need GNU toolchain and newlib for 'arm-none-eabi' target.
+
+See http://github.com/esden/summon-arm-toolchain/ (which includes fix
+of binutils-2.21.1) for preparation of GNU Toolchain for
+'arm-none-eabi' target.  This is for GCC 4.5.
+
+Note that we need to link correct C library (for string functions).
+For this purpose, our src/Makefile.in contains following line:
+
+	MCFLAGS= -mcpu=$(MCU) -mfix-cortex-m3-ldrd
+
+This should not be needed (as -mcpu=cortex-m3 means
+-mfix-cortex-m3-ldrd), but it is needed for the configuration of
+patch-gcc-config-arm-t-arm-elf.diff in summon-arm-toolchain in practice.
+
+In ChibiOS_2.0.8/os/ports/GCC/ARM/rules.mk, it specifies
+-mno-thumb-interwork option.  This means that you should not link C
+library which contains ARM (not Thumb) code.
+
+Recently, there is "gcc-arm-embedded" project.  See:
+https://launchpad.net/gcc-arm-embedded/
+
+It is based on GCC 4.6.   For version 4.6-2012-q2-update, you'd
+need "-O3 -s" instead of "-O2" and it will be slightly better.
+
+
+
+Building Gnuk
+-------------
+
+Change directory to ``src``:
+
+  $ cd gnuk-VERSION/src
+
+Then, run ``configure``:
+
+  $ ./configure --vidpid=<VID:PID>
+
+Here, you need to specify USB vendor ID and product ID.  For FSIJ's,
+it's: --vidpid=234b:0000 .  Please read section 'USB vendor ID and
+product ID' above.
+
+Type:
+
+  $ make
+
+Then, we will have "gnuk.elf".

doc/intro.rst

@@ -0,0 +1,45 @@
+Introduction
+============
+
+
+What's Gnuk?
+------------
+
+Gnuk is an implementation of USB cryptographic token for GNU Privacy
+Guard.  Gnuk supports OpenPGP card protocol version 2, and it runs on
+STM32F103 processor.
+
+
+Cryptographic token and feature of Gnuk
+---------------------------------------
+
+Cryptographic token is a store of private keys and it computes cryptographic functions on the device.
+
+
+Development Environment
+-----------------------
+
+See :doc:`development` for development environment for Gnuk.  It builds on Free Software.
+
+
+Prerequisites
+-------------
+
+* GNU Privacy Guard (GnuPG)
+
+* libusb
+
+* [Optional] PC/SC lite (pcscd, libccid)
+
+* SSH: openssh
+
+* Web: scute, firefox
+
+
+Usage
+-----
+
+* Sign with GnuPG
+* Decrypt with GnuPG
+* Use with OpenSSH
+* Use with Firefox for X.509 client certificate authentication