Fix for GNU/Linux
[gnuk/neug.git] / README
diff --git a/README b/README
index ecc0919..d67065f 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.03
-                                                            2012-09-27
+                                                         Version 1.0.5
+                                                            2015-10-17
                                                           Niibe Yutaka
                                      Free Software Initiative of Japan
 
@@ -28,12 +28,15 @@ NeuG was named after my daughter, but I don't say she is noisy.
 Release notes
 =============
 
-This is the fourth release of NeuG, which is still experimental.
+This is the fifth minor release of NeuG, after 1.0.
+
 Basic features (generating random numbers) are stable, but newly added
-things like reGNUal support should be considered unstable.  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.
+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).  If you get the source code by Git,
+Chopstx is submodule of NeuG.
 
 
 FAQ
@@ -41,10 +44,8 @@ FAQ
 
 Q0: How NeuG device is good?
 A0: I believe it's good enough if we compare to other hardware RNGs.
-    If its usage is as an entropy source for RNG-tools, or use for
-    computer simulations, I think that it's good enough.  I evaluated
-    it with rngtest of RNG-tools, NIST STS test suite and Dieharder.
-    See the directory neug/test-results/.
+    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
@@ -52,22 +53,52 @@ A0-double-dash: STM32F2xx and STM32F4xx have built-in TRNG, it would
                 looks not that good).
 
 Q1: How fast is NeuG device?
-A1: It's something around 30 Ki-byte/second.
+A1: It's about 80 kB/sec for conditioned output (by SHA-256), and 
+    about 270 kB/sec for CRC-32 filtered output (kB = 1000 byte).
 
 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.
 
+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 CRC-32 filtered output would be good
+    enough.
+
+Q4: Configuring by 'stty' doesn't work, what's up?
+A4: Common problem on GNU/Linux is the "modemmanager" try to control
+    /dev/ttyACM0, which interferes.  Please consider removing
+    modemmanager from your system or configure it to ignore NeuG
+    device.  For detail, please see the FST-01 support pages on the
+    web.
+
 
 Targets
 =======
 
-FST-01, STBee Mini, Olimex STM32-H103, CQ-STARM, and STBee are
-supported.
+FST-01, Nitrokey-Start, Olimex STM32-H103, STM32 part of STM8S
+Discovery Kit, STBee Mini, STBee, STM32 Primer 2, CQ STARM, ST Dongle
+and STM32 Nucleo F103 are supported.
+
+
+Build system and Host system
+============================
+
+Makefile is written for GNU make.  You need Bash 4.x for configure.
+
+If your bash is not installed as /bin/bash, you need to run configure
+script prepending 'bash' before './configure'.
+
+Some tools are written in Python.  If your Python is not installed as
+/usr/bin/python, please prepend 'python' for your command invocation.
+Python 2.7 and PyUSB 0.4.3 is assumed.  I also use Python 3.5 and
+PyUSB 1.0.0.
 
 
 Souce code
@@ -75,6 +106,11 @@ Souce code
 
 NeuG source code is under src/ directory.
 
+Note that SHA-256 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
 =======
@@ -86,12 +122,52 @@ It is distributed under GNU General Public Licence version 3 or later
 External source code
 ====================
 
-To build NeuG device, we need external source code.
+NeuG is distributed with external source code.
+
+* chopstx/ -- Chopstx, the RT Thread Library
+
+* [optional] fraucheky/ -- Fraucheky, the GPL container
+
+Those are available at:
+
+  https://anonscm.debian.org/cgit/gnuk/chopstx/
+
 
-* chibios/  -- ChibiOS/RT 2.3.x snapshot
+USB vendor ID and product ID (USB device ID)
+============================================
 
-  Please get it from http://chibios.sourceforge.net/
-  We use ChibiOS/RT as the kernel for NeuG device.
+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.
+
+  * For individuals:
+
+    - 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
@@ -99,8 +175,16 @@ How to compile
 
 You need GNU toolchain and newlib for 'arm-none-eabi' target.
 
-See http://github.com/uwehermann/summon-arm-toolchain/ for preparation
-of GNU Toolchain for 'arm-none-eabi' target.
+On Debian we can install the packages of gcc-arm-none-eabi,
+gdb-arm-none-eabi and its friends.  I'm using:
+
+       binutils-arm-none-eabi  2.26-4+8
+       gcc-arm-none-eabi       15:4.9.3+svn231177-1
+       gdb-arm-none-eabi       7.10-1+9
+       libnewlib-arm-none-eabi 2.2.0+git20150830.5a3d536-1
+
+Or else, see https://launchpad.net/gcc-arm-embedded for preparation of
+GNU Toolchain for 'arm-none-eabi' target.
 
 Change directory to `src':
 
@@ -108,38 +192,50 @@ 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/ftdi/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.
 
-Then, with another terminal, type following to write "gnuk.elf" to Flash ROM:
+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:
 
   $ telnet localhost 4444
   > reset halt
@@ -148,6 +244,9 @@ Then, with another terminal, type following to write "gnuk.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
@@ -160,75 +259,115 @@ Before using /dev/ttyACM0, you need to configure its TTY discipline.
 
 Then, you can use output of /dev/ttyACM0.
 
-When you want to get raw output (not conditioned), you can configure:
+When you want to get CRC-32 filtered output, you can configure:
 
   $ stty -F /dev/ttyACM0 parenb parodd
 
-for raw data of LSBs.  For raw data of samples, configure:
+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:
+And you can get SHA-256 conditioned output by configuring:
 
   $ stty -F /dev/ttyACM0 -parenb
 
 
-Structure of the NeuG
-=====================
+If your device is configured with Fraucheky, you can invoke Fraucheky
+from NeuG by setting the unusual sequence of configurations:
 
-Here is a figure of the circuit.
+  $ stty -F /dev/ttyACM0 ispeed 110 ospeed 110
+  $ stty -F /dev/ttyACM0 ispeed 115200 ospeed 115200
 
 
-           Physical-based RNG
-           
-            +--------------+              Noise sources 
+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    |<------------/------------+
             |              |
-            | Conditioning |   1112 ||<-- LSB of result of [ IN10 ]
-            | Component    |<---/---||
-            |              |        ||<-- LSB of result of [ IN11 ]
       +-----|  Hash_df     |
       |     |    by        |
       |     |  SHA-256     |
-      |     |              |
-      |     |              |   128
-      |     |              |<---/---+
-      |     +--------------+        |
-      |                             |
-      +-----------------------------+
+      |     |              |  128
+      |     |              |<--/--+
+      |     +--------------+      |
+      |                           |
+      +---------------------------+
       |
       / 256
       |
       v
- Random Number Output
+ Random Number Output <========== (*3)
+
 
 
-STM32F103 has two built-in A/D converters of 12-bit resolution.  NeuG
-uses LSBs of A/D converters' outputs as entropy sources.  It is
-considered noise of quantization error, plus noise from power supply,
-etc.
+Specifying by "stty", you can get (*3) with -parenb, (*2) with parenb
+parodd, and (*1) with parenb -parodd.
 
-We chose analog inputs of IN10 and IN11, which is not connected to
-external pin (for the version of 36-pin or 48-pin STM32F103).  The
-input is configured as digital output 50MHz to get maximum noise of
-environment.
+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.
 
-By 556 samplings of two channels, we can get 1112-bit, as we can get
-two bits (LSB of IN10 and LSB of IN11) from one sampling.  We put this
-1112-bit and half of previous output to conditioning component.
+We chose four analog input sources of: built-in voltage reference,
+temperature sensor and two analog inputs which are pull-up to Vdd.
 
-Conditioning component is implemented by Hash_df function by SHA-256.
-Since the noise source is not "white", signal is whiten by this
-Conditioning component.
+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.
 
-Experiments show that raw noise source of LSBs has more than 6.0
-bit/byte entropy when it is no computation but just to take samples.
-The entropy varies among different boards.  It seems that a board with
-good power supply and capacitor has smaller entropy (6.2 or so), and
-the one with poor power supply and capacitor has bigger entropy (7.3
-or so).  That is considered noise of quantization error.
+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.
 
-When there is some activities of MCU, it's more than 7.0 bit/byte
-entropy for a board even with good power supply and capacitor.
+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.
@@ -238,27 +377,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.
+PractRand 0.92.
 
-For Dieharder, I correct 13GiB (it took five days and six hours
-and more), and use scripts to invoke dieharder.
+I collect 140 files of 125MB (>= 16GiB), and run the test suite of
+PractRand 0.92.  Collecting 140 files, it took two days and a half.
 
 
-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:
 
-  $ git clone git://www.gniibe.org/neug.git/
+    https://anonscm.debian.org/cgit/gnuk/gnuk/
 
-or
+You can get it by:
 
-  $ git clone http://www.gniibe.org/git/neug.git/
+    $ git clone git://anonscm.debian.org/gnuk/gnuk/neug.git
 
 
-I put ChibiOS/RT as a submodule of Git.  Please do this:
+I put Chopstx and Fraucheky as a submodules of Git.  Please do this:
 
   $ git submodule init
   $ git submodule update
@@ -268,36 +405,14 @@ I put ChibiOS/RT as a submodule of Git.  Please do this:
 Information on the Web
 ======================
 
-Not yet.
-
-
-Known Problem(s)
-================
+Please see the FST-01 support pages:
 
-On STBee (high-density device of STM32), sometimes, I observed stall
-of generation of random number, after two hours, two hours and half,
-etc.
+    http://www.gniibe.org/category/fst-01.html
 
-Identified somehow.  When it stalls, status is like this (by OpenOCD, GDB):
+Please consider to join Gnuk-users mailing list:
 
-       adcp->state = ADC_ACTIVE
-       main thread: wait on condition variable at neug_get
-       rng thread: holding rb->m, event wait at rng_gen for ADC_DATA_AVAILABLE
-       idle thread: running
-       LED thread: event wait
+    https://lists.alioth.debian.org/mailman/listinfo/gnuk-users
 
-Kicking DMA controller again (note: ADC is continuous mode, no need to
-kick), by doing following:
-
-  (gdb) set ADCD1.dmastp->channel->CCR = 0
-  (gdb) set ADCD1.dmastp->channel->CNDTR = 8
-  (gdb) set ADCD1.dmastp->channel->CCR = 0x258f
-  (gdb) x/x 0x40020000         # DMA interrupt status register (DMA_ISR)
-  0x40020000:  0x00000007
-
-Then, it goes again.
-
-Lost DMA finish interrupt?
 
 
 Your Contributions
@@ -305,4 +420,10 @@ Your Contributions
 
 FSIJ welcomes your contributions.  Please assign your copyright
 to FSIJ (if possible).
+
+
+Foot note
+==========
+
+If NeuG had a family name, it must be Kunisada.
 --