fix locking of USB_MTX
[gnuk/neug.git] / README
diff --git a/README b/README
index e1295f2..6ae5449 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.00
-                                                            2011-07-14
+                                                          Version 0.10
+                                                            2013-06-XX
                                                           Niibe Yutaka
                                      Free Software Initiative of Japan
 
@@ -21,38 +21,59 @@ My primary intention was to incorporate NeuG routines into Gnuk for
 random number generation, but the stand alone version could be useful
 too.
 
+Gnuk was named after my son who loved the pacifier when he was baby.
+NeuG was named after my daughter, but I don't say she is noisy.
+
 
 Release notes
 =============
 
-This is the first release of NeuG, which is experimental enough.  You
-can enjoy NeuG device, but I don't know how it is good yet.  Note that
-you need the snapshot of ChibiOS/RT (from trunk).  This means that it
-is covered by GNU GPL.  No "linking exception" option is available for
-the snapshot.
+This is the seventh 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 Chopstx as external source code.
 
 
 FAQ
 ===
 
 Q0: How NeuG device is good?
-A0: I don't know yet.  It is under evaluation now.
-A0-dash: For better entropy device, you can get EntropyKey.
-         See http://www.entropykey.co.uk/
-A0-double-dash: STM32F2xx has built-in TRNG, it would be better for you.
+A0: I believe it's good enough if we compare to other hardware RNGs.
+    I evaluated it with rngtest of RNG-tools, NIST STS test suite and
+    Dieharder.  See the directory neug/test-results/.
+A0-dash: For better entropy device with embedded test, you could get
+         EntropyKey.  See http://www.entropykey.co.uk/
+A0-double-dash: STM32F2xx and STM32F4xx have built-in TRNG, it would
+                be better for you (although the quality of randomness
+                looks not that good).
 
 Q1: How fast is NeuG device?
-A1: It's something around 24 Ki-byte/second.
+A1: It's more than 50 Ki-byte/sec for conditioned output (by SHA-256),
+    and more than 140 Ki-byte/sec for CRC-32 filtered output.
 
 Q2: Should we check condition of noise sources?
-A2: Yes, we should.  It's not implemented yet, and I don't have an
-    good idea how to implement.  Please let me know your idea.
+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
+    is really rare, but it could occur even for normal condition), the
+    generation of random bits restart again.
+
+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.  With
+    high speed hub, you'll get more than 240 Ki-byte/second .
 
 
 Targets
 =======
 
-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.  CQ-STARM, STBee Mini, and STBee will be supported.
 
 
 Souce code
@@ -71,12 +92,54 @@ 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.
+
+* chopstx/ -- Chopstx, the RT Thread Library
+
+It is available at:
+
+  http://gitorious.org/chopstx/chopstx
+
+
+USB vendor ID and product ID (USB device ID)
+============================================
+
+When you have a vender ID and assign a product ID for NeuG, edit the
+file NEUG_USB_DEVICE_ID and add an entry for yours.  In this case,
+please contact Niibe, so that it is listed to the file in the official
+release of the source code.
+
+When you are modifing NeuG and installing the binary to device, you
+should replace the vendor string to yours, so that users can see it's
+not by original vendor, and it is modified version.
+
+FSIJ allows you to use USB device ID of FSIJ (234b:0001) for devices
+with standalone NeuG under one of following conditions:
+
+  * For everyone for experimental purpose:
+
+    - You must not distribute a binary with FSIJ's USB device ID, but
+      must use the binary by yourself only for your experiment.  Note
+      that "Distributing binary" includes distributing a device which
+      holds the binary.
 
-* chibios/  -- ChibiOS/RT 2.3.x snapshot
+  * For general individuals:
 
-  Please get it from http://chibios.sourceforge.net/
-  We use ChibiOS/RT as the kernel for NeuG device.
+    - No additional conditions.
+
+  * For individuals with explicit permission from FSIJ.
+
+    - No additional conditions.
+
+FSIJ could give companies or business entities "second source
+manufacturer" license to use USB device ID of FSIJ for devices with
+unmodified version of NeuG, provided they support Free Software and
+respect users' freedom for computing.  Please ask FSIJ for the
+license.
+
+Otherwise, companies which want to distribute NeuG devices, please use
+your own USB vendor ID and product ID.  Please replace vendor string
+and possibly product string to yours, when you modify NeuG.
 
 
 How to compile
@@ -84,7 +147,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':
@@ -124,7 +187,7 @@ If you are using Olimex JTAG-Tiny, type following to invoke OpenOCD:
 
   $ openocd -f interface/olimex-jtag-tiny.cfg -f board/olimex_stm32_h103.cfg
 
-Then, with another terminal, type following to write "gnuk.elf" to Flash ROM:
+Then, with another terminal, type following to write "neug.elf" to Flash ROM:
 
   $ telnet localhost 4444
   > reset halt
@@ -145,81 +208,129 @@ Before using /dev/ttyACM0, you need to configure its TTY discipline.
 
 Then, you can use output of /dev/ttyACM0.
 
-
-
-Structure of the NeuG
-=====================
-
-NeuG consists of two RNG, one is the RNG based on physical noise, and
-another is Pseudo RNG.  Outputs of RNGs are exclusive or-ed
-to generate final output.  Here is a figure of the circuit.
-
-
-                        Entropy Pool (16-byte)
-                       +----------------+
-                       |                |
-                       | 8 parallel     |   8  ||<-- [ Vref ]
-                 +---- |  CRC-16        |<--/--||
-                 |     | shift registers|      ||<-- [ Temperature Sensor ]
-                 |     |                |
-                 |     |                |<----/------ SysTick
-                 |     +----------------+     1
-                 |     Physical-based RNG
-                 / 8
-                 |
-                 v
-               ===== Output function
-                 |
-                 / 32
-                 |
-                 +-------------+
-                 |             |
-                 / 32          / 32  Seed
-                 |             |
-                 |             v
-  Random     32  v      32 +--------+
-  Number  <--/--[XOR]<--/--| TinyMT |
-  Output                   +--------+
-                           Pseudo RNG
-
-
-STM32F103 has built-in Vref (voltage reference) and Temperature Sensor
-which are connected to A/D converter of 12-bit resolution.  NeuG uses
-LSBs of A/D converter's outputs and A/D converter's interrupt timings
-as entropy sources.
-
-By four samplings of two channels, we can get 8-bit, as we can get two
-bits (LSB of Vref and LSB of Temperature Sensor) from one sampling.
-We put this 8-bit noise to entropy pool.  Entropy pool consist of
-16-byte buffer, which is 8 parallel CRC-16 shift registers.  The noise
-source is not "white", but it can be used as RNG with this CRC-16
-filter.  An experiment shows that raw noise source of LSBs has more
-than 6 bit/byte entropy.  So, we put 7-byte to get 4-byte (32-bit)
-output.
-
-I don't know how stable the noise source is.
-
-So, NeuG comes with second RNG.  It is pseudo RNG timings.  We use
-TinyMT for pseudo RNG.  Please see following page for TinyMT:
-
-   "Tiny Mersenne Twister (TinyMT): A small-sized variant of Mersenne Twister"
-   by Mutsuo Saito and Makoto Matsumoto
-     http://www.math.sci.hiroshima-u.ac.jp/~m-mat/MT/TINYMT/
+When you want to get raw output (not conditioned), you can configure:
+
+  $ stty -F /dev/ttyACM0 parenb parodd
+
+for raw data after filter.  For direct raw data of ADC samples,
+configure:
+
+  $ stty -F /dev/ttyACM0 parenb -parodd
+
+And you can get conditioned output by configuring:
+
+  $ stty -F /dev/ttyACM0 -parenb
+
+
+Structure of NeuG
+=================
+
+Here is a figure of the circuit.
+
+                                         Noise sources
+
+                              /|<---+--- [ Analog input Vref ]
+                16           | |<-+-|--- [ Analog input Temperature Sensor ]
+             +---/-[ADC1] <==| |  | |
+             |               | |<-+ |
+      +-+    |                \|<---+
+      | |<---+                |
+ +----| |          MUX CTL >--+
+ |    | |<---+
+ |    +-+    |                /|
+ |           |  16           | |<------- [ Analog input 0 ] (pull up to Vdd)
+ |           +---/-[ADC2] <==| |
+ |                           | |<------- [ Analog input 1 ] (pull up to Vdd)
+ |                            \|
+ |                            |
+ |                 MUX CTL >--+
+ |
+ +------------------+         <============ (*1)
+                    |
+                    / 32
+                    |
+                    | Put 4 times to output 32-bit
+                    V
+            [ CRC-32 filter ]
+                    |
+                    |           Put 35 times to output 1120-bit
+                    +---------------------------------+         <====== (*2)
+                                                      |
+                                                      / 32
+                                                      |
+                                                      V
+                                              [ Entropy Buffer ]
+                                                      |          
+            +--------------+                          |
+            |              |                          |
+            | Conditioning |            1120          |
+            | Component    |<------------/------------+
+            |              |
+      +-----|  Hash_df     |
+      |     |    by        |
+      |     |  SHA-256     |
+      |     |              |  128
+      |     |              |<--/--+
+      |     +--------------+      |
+      |                           |
+      +---------------------------+
+      |
+      / 256
+      |
+      v
+ Random Number Output <========== (*3)
+
+
+
+Specifying by "stty", you can get (*3) with -parenb, (*2) with parenb
+parodd, and (*1) with parenb -parodd.
+
+STM32F103 has two built-in A/D converters.  NeuG uses A/D converters'
+outputs as entropy sources.  It is considered noise of quantization
+error, plus noise from power supply, etc.
+
+We chose four analog input sources of: built-in voltage reference,
+temperature sensor and two analog inputs which are pull-up to Vdd.
+
+By a single sampling of two channels, we get 32-bit (not all 32-bit is
+valid, as a A/D converter resolution is 12-bit only).  We take four
+sampling of combinations: (Vref, IN0), (Temp, IN1), (Vref, IN1), and
+(Temp, IN0).  Those 32-bit * 4 is fed into CRC32 filter.
+
+We use STM32F103's CRC32 calculation unit as a kind of filter.  We put
+output of A/D converters into CRC32 calculation unit, four times, to
+get 4-byte output.
+
+Output of CRC32 filter is collected 35 times, and it becomes 1120-bit
+(32 * 35).  This is the noise source bits.
+
+We put this 1120-bit and half of previous output (128-bit) to
+conditioning component.
+
+Conditioning Component is implemented by Hash_df function which is
+composed by SHA-256.  Since the noise source is not "white", signal is
+whiten by this Conditioning Component.
+
+My experience with STM32F103 and NeuG shows that noise source is
+stable at least for a year.
 
 
 Test results
 ============
 
 See files under the directory test-results, for test result of
-"rngtest" in rng-tools, and NIST STS 2.1.1.  Currently, I am testing
-NeuG device by dieharder, but it seems that it takes a month or so (8
-days passed, it's running RGB Bit distribution test ntup=9).
+"rngtest" in rng-tools, NIST STS 2.1.1, and 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
+You can browse at http://www.gniibe.org/gitweb?p=neug.git
 
 You can get it by:
 
@@ -230,7 +341,7 @@ or
   $ git clone http://www.gniibe.org/git/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
@@ -240,15 +351,8 @@ I put ChibiOS/RT as a submodule of Git.  Please do this:
 Information on the Web
 ======================
 
-Not yet.
-
-
-Known Problem(s)
-================
+Please use FST-01 Q&A Forum at: http://no-passwd.net/askbot/questions/
 
-On STBee (high-density device of STM32), I observed stall of
-generation of random number, after two hours, two hours and half, etc.
-Not yet identified the bug.
 
 
 Your Contributions
@@ -256,4 +360,4 @@ Your Contributions
 
 FSIJ welcomes your contributions.  Please assign your copyright
 to FSIJ (if possible).
--- 
+--