update fraucheky
[gnuk/neug.git] / README
diff --git a/README b/README
index 597f4c2..470ba9b 100644 (file)
--- a/README
+++ b/README
@@ -1,7 +1,7 @@
-NeuG - a random number generator implementation (for STM32F103)
+NeuG - a true random number generator implementation (for STM32F103)
 
-                                                          Version 0.04
-                                                            2012-10-2X
+                                                         Version 1.0.1
+                                                            2015-02-??
                                                           Niibe Yutaka
                                      Free Software Initiative of Japan
 
@@ -28,10 +28,18 @@ NeuG was named after my daughter, but I don't say she is noisy.
 Release notes
 =============
 
-This is the fifth release of NeuG, which is still experimental.  Basic
-features (generating random numbers) are stable, but newly added
-things like reGNUal support should be considered unstable.  Note that
-you need ChibiOS/RT 2.4.x as external source code.
+This is the first minor release of NeuG, after 1.0.
+
+Basic features (generating random numbers) are stable, but newly added
+things like fraucheky (USB Mass Storage Class) support and reGNUal
+(firmware upgrad) support should be considered experimental.
+
+Note that you need Chopstx (the thread library) as external source
+code (instead of ChibiOS/RT).
+
+The "boards" directory is now obsolete, it's for old versions of NeuG
+with ChibiOS/RT.  When you find a board under this directory, it means
+it doesn't work.  We leave them to port new NeuG.
 
 
 FAQ
@@ -49,19 +57,13 @@ A0-double-dash: STM32F2xx and STM32F4xx have built-in TRNG, it would
 
 Q1: How fast is NeuG device?
 A1: It's more than 50 Ki-byte/sec for conditioned output (by SHA-256),
-    and more than 200 Ki-byte/sec for CRC-32 filtered output.  Please
-    note that the NeuG device is USB "full-speed" device.  If you
-    connect it to full-speed hub or root hub which runs at full-speed,
-    you get lower speed than the real capability of the device.
-    That's because host submits a frame to device once per 1ms frame
-    with full-speed hub.  When you connect it to high-speed hub, you
-    get higher performance for CRC-32 filtered output.
+    and more than 140 Ki-byte/sec for CRC-32 filtered output.
 
 Q2: Should we check condition of noise sources?
 A2: Yes, we should.  Three continuous tests are implemented, following
     (Draft of) NIST SP 800-90B.  Those are Repetition Count Test,
     Adaptive Proportion Test (for 64 samples), and another Adaptive
-    Proportion Test (for 4096 samples).  When it detect an error (it
+    Proportion Test (for 4096 samples).  When it detects an error (it
     is really rare, but it could occur even for normal condition), the
     generation of random bits restart again.
 
@@ -69,17 +71,19 @@ Q3: Conditioning with SHA-256 sounds over-kill.  Why not simpler?
 A3: It is because NIST SP 800-90B mandates something like that for
     "full entropy source".  If your usage is as an entropy source for
     RNG-tools to feed entropy to your kernel, or use for computer
-    simulations, I think that CRC32 filter would be good enough.  You
-    can configure NeuG device by "stty -F /dev/ttyACM0 parenb parodd"
-    to get raw data before SHA-256 conditioning component.  Then,
-    you'll get more than 350 Ki-byte/second (with high speed hub).
+    simulations, I think that CRC32 filtered output would be good
+    enough.  You can configure NeuG device by "stty -F /dev/ttyACM0
+    parenb parodd" to get raw data before SHA-256 conditioning
+    component.  With high speed hub, you'll get more than 240
+    Ki-byte/second .
 
 
 Targets
 =======
 
-FST-01, STBee Mini, Olimex STM32-H103, CQ-STARM, and STBee are
-supported.
+FST-01, Olimex STM32-H103, and STM32 part of STM8S Discovery Kit are
+supported.  Porting to CQ-STARM, STBee Mini, and STBee is not that
+hard.
 
 
 Souce code
@@ -87,6 +91,11 @@ Souce code
 
 NeuG source code is under src/ directory.
 
+Note that SHA-2 hash function implementation, src/sha256.c, is based
+on the original implementation by Dr. Brian Gladman.  See:
+
+  http://gladman.plushost.co.uk/oldsite/cryptography_technology/sha/index.php
+
 
 License
 =======
@@ -98,12 +107,15 @@ It is distributed under GNU General Public Licence version 3 or later
 External source code
 ====================
 
-To build NeuG device, we need external source code.
+To build NeuG device, you need external source code.
 
-* chibios/  -- ChibiOS/RT 2.4.x
+* chopstx/ -- Chopstx, the RT Thread Library
 
-  Please get it from http://chibios.sourceforge.net/
-  We use ChibiOS/RT as the kernel for NeuG device.
+* [optional] fraucheky/ -- Fraucheky, the GPL container
+
+It is available at:
+
+  http://gitorious.org/chopstx/chopstx
 
 
 USB vendor ID and product ID (USB device ID)
@@ -128,11 +140,7 @@ with standalone NeuG under one of following conditions:
       that "Distributing binary" includes distributing a device which
       holds the binary.
 
-  * For general individuals:
-
-    - No additional conditions.
-
-  * For individuals with explicit permission from FSIJ.
+  * For individuals:
 
     - No additional conditions.
 
@@ -152,7 +160,7 @@ How to compile
 
 You need GNU toolchain and newlib for 'arm-none-eabi' target.
 
-See http://github.com/uwehermann/summon-arm-toolchain/ for preparation
+See https://launchpad.net/gcc-arm-embedded for preparation
 of GNU Toolchain for 'arm-none-eabi' target.
 
 Change directory to `src':
@@ -161,36 +169,48 @@ Change directory to `src':
 
 Then, run `configure':
 
-  $ ./configure
+  $ ./configure --vidpid=<VID:PID>
+
+Here, you need to specify USB vendor ID and product ID.  For FSIJ's,
+it's: --vidpid=234b:0001 .  Please read section 'USB vendor ID and
+product ID' above.
+
 
 Type:
 
   $ make
 
-Then, we will have "neug.elf".
+Then, we will have "neug.elf" under the "build" directory.
 
 
 How to install
 ==============
 
-STBee Mini and STBee
---------------------
+Olimex STM32-H103 board
+-----------------------
 
-Reset the board with "USER" switch pushed.  Type following to write
-to flash:
+If you are using Olimex JTAG-Tiny, type following to invoke OpenOCD:
 
-  # cd ../tool
-  # ./dfuse.py ../src/neug.hex
+  $ openocd -f interface/olimex-jtag-tiny.cfg -f board/olimex_stm32_h103.cfg
 
-Then, reset the board.
+Then, with another terminal, type following to write "neug.elf" to Flash ROM:
 
+  $ telnet localhost 4444
+  > reset halt
+  > flash write_image erase neug.elf
+  > reset
+  > exit
+  $ 
 
-Olimex STM32-H103 board
------------------------
 
-If you are using Olimex JTAG-Tiny, type following to invoke OpenOCD:
+Flying Stone Tiny 01 and STM8S Discovery Kit
+--------------------------------------------
 
-  $ openocd -f interface/olimex-jtag-tiny.cfg -f board/olimex_stm32_h103.cfg
+If you are using Flying Stone Tiny 01, you need a SWD writer.
+
+OpenOCD 0.6.1 or newer supports ST-Link/V2.  With that we can do:
+
+  $ openocd -f interface/stlink-v2.cfg -f target/stm32f1x_stlink.cfg
 
 Then, with another terminal, type following to write "neug.elf" to Flash ROM:
 
@@ -201,6 +221,9 @@ Then, with another terminal, type following to write "neug.elf" to Flash ROM:
   > exit
   $ 
 
+Note that OpenOCD (as of 0.7.0) doesn't support option bytes handling yet.
+
+You can also use tool/stlinkv2.py in Gnuk.
 
 
 Use of NeuG device
@@ -326,25 +349,25 @@ Test results
 See files under the directory test-results, for test result of
 "rngtest" in rng-tools, NIST STS 2.1.1, and Dieharder.
 
-For Dieharder, I correct 1500MB (it took four days or so), and use
-scripts to invoke dieharder.
+I collect 110 files of 125MB (= 13750MB), and use scripts to invoke
+dieharder and rngtest.  Collecting 110 files, it took three days.
 
+For NIST STS 2.1.1, I used only 10 files of size 125MB.
 
-Read-only Git Repository
-========================
 
-You can browse at http://www.gniibe.org/gitweb?p=neug.git;a=summary
+Git Repository
+==============
 
-You can get it by:
+NeuG is available in the Gnuk repository at Gitorious.org:
 
-  $ git clone git://www.gniibe.org/neug.git/
+    http://gitorious.org/gnuk/neug
 
-or
+You can get it by:
 
-  $ git clone http://www.gniibe.org/git/neug.git/
+    $ git clone git://gitorious.org/gnuk/neug.git
 
 
-I put ChibiOS/RT as a submodule of Git.  Please do this:
+I put Chopstx as a submodule of Git.  Please do this:
 
   $ git submodule init
   $ git submodule update
@@ -354,7 +377,7 @@ I put ChibiOS/RT as a submodule of Git.  Please do this:
 Information on the Web
 ======================
 
-Not yet.
+Please use FST-01 Q&A Forum at: http://no-passwd.net/askbot/questions/