support non-default STBee Mini
[gnuk/neug.git] / README
1 NeuG - a random number generator implementation (for STM32F103)
2
3                                                            Version 0.03
4                                                              2012-09-27
5                                                            Niibe Yutaka
6                                       Free Software Initiative of Japan
7
8 What's NeuG?
9 ============
10
11 NeuG is a set of routines of random number generator (RNG) which is
12 based on physical noise.  It supports STM32F103.  It can be stand
13 alone USB RNG device (with main routine), too.
14
15 The name comes from Japanized English word "noidgy" (from English word
16 "noisy"), where many Japanese (including me) don't distinguish
17 pronunciations of "gee" and "zee".  NeuG includes my important letters
18 of "g", "n", and "u", and the word "neu" (German spelling of "new").
19
20 My primary intention was to incorporate NeuG routines into Gnuk for
21 random number generation, but the stand alone version could be useful
22 too.
23
24 Gnuk was named after my son who loved the pacifier when he was baby.
25 NeuG was named after my daughter, but I don't say she is noisy.
26
27
28 Release notes
29 =============
30
31 This is the fourth release of NeuG, which is still experimental.
32 Basic features (generating random numbers) are stable, but newly added
33 things like reGNUal support should be considered unstable.  Note that
34 you need the snapshot of ChibiOS/RT (from trunk).  This means that it
35 is covered by GNU GPL.  No "linking exception" option is available for
36 the snapshot.
37
38
39 FAQ
40 ===
41
42 Q0: How NeuG device is good?
43 A0: I believe it's good enough if we compare to other hardware RNGs.
44     If its usage is as an entropy source for RNG-tools, or use for
45     computer simulations, I think that it's good enough.  I evaluated
46     it with rngtest of RNG-tools, NIST STS test suite and Dieharder.
47     See the directory neug/test-results/.
48 A0-dash: For better entropy device with embedded test, you could get
49          EntropyKey.  See http://www.entropykey.co.uk/
50 A0-double-dash: STM32F2xx and STM32F4xx have built-in TRNG, it would
51                 be better for you (although the quality of randomness
52                 looks not that good).
53
54 Q1: How fast is NeuG device?
55 A1: It's something around 30 Ki-byte/second.
56
57 Q2: Should we check condition of noise sources?
58 A2: Yes, we should.  Three continuous tests are implemented, following
59     (Draft of) NIST SP 800-90B.  Those are Repetition Count Test,
60     Adaptive Proportion Test (for 64 samples), and another Adaptive
61     Proportion Test (for 4096 samples).  When it detect an error (it
62     is really rare, but it could occur even for normal condition), the
63     generation of random bits restart again.
64
65
66 Targets
67 =======
68
69 FST-01, STBee Mini, Olimex STM32-H103, CQ-STARM, and STBee are
70 supported.
71
72
73 Souce code
74 ==========
75
76 NeuG source code is under src/ directory.
77
78
79 License
80 =======
81
82 It is distributed under GNU General Public Licence version 3 or later
83 (GPLv3+).  Please see src/COPYING.
84
85
86 External source code
87 ====================
88
89 To build NeuG device, we need external source code.
90
91 * chibios/  -- ChibiOS/RT 2.3.x snapshot
92
93   Please get it from http://chibios.sourceforge.net/
94   We use ChibiOS/RT as the kernel for NeuG device.
95
96
97 How to compile
98 ==============
99
100 You need GNU toolchain and newlib for 'arm-none-eabi' target.
101
102 See http://github.com/uwehermann/summon-arm-toolchain/ for preparation
103 of GNU Toolchain for 'arm-none-eabi' target.
104
105 Change directory to `src':
106
107   $ cd neug-VERSION/src
108
109 Then, run `configure':
110
111   $ ./configure
112
113 Type:
114
115   $ make
116
117 Then, we will have "neug.elf".
118
119
120 How to install
121 ==============
122
123 STBee Mini and STBee
124 --------------------
125
126 Reset the board with "USER" switch pushed.  Type following to write
127 to flash:
128
129   # cd ../tool
130   # ./dfuse.py ../src/neug.hex
131
132 Then, reset the board.
133
134
135 Olimex STM32-H103 board
136 -----------------------
137
138 If you are using Olimex JTAG-Tiny, type following to invoke OpenOCD:
139
140   $ openocd -f interface/olimex-jtag-tiny.cfg -f board/olimex_stm32_h103.cfg
141
142 Then, with another terminal, type following to write "gnuk.elf" to Flash ROM:
143
144   $ telnet localhost 4444
145   > reset halt
146   > flash write_image erase neug.elf
147   > reset
148   > exit
149   $ 
150
151
152
153 Use of NeuG device
154 ==================
155
156 It is USB CDC ACM device.  On GNU/Linux, it can be /dev/ttyACM0 or like.
157 Before using /dev/ttyACM0, you need to configure its TTY discipline.
158
159   $ stty -F /dev/ttyACM0 -echo raw
160
161 Then, you can use output of /dev/ttyACM0.
162
163 When you want to get raw output (not conditioned), you can configure:
164
165   $ stty -F /dev/ttyACM0 parenb
166
167 And you can get conditioned output by configuring:
168
169   $ stty -F /dev/ttyACM0 -parenb
170
171
172 Structure of the NeuG
173 =====================
174
175 Here is a figure of the circuit.
176
177
178            Physical-based RNG
179            
180             +--------------+              Noise sources 
181             |              |
182             | Conditioning |   1112 ||<-- LSB of result of [ IN10 ]
183             | Component    |<---/---||
184             |              |        ||<-- LSB of result of [ IN11 ]
185       +-----|  Hash_df     |
186       |     |    by        |
187       |     |  SHA-256     |
188       |     |              |
189       |     |              |   256
190       |     |              |<---/---+
191       |     +--------------+        |
192       |                             |
193       +-----------------------------+
194       |
195       / 256
196       |
197       v
198  Random Number Output
199
200
201 STM32F103 has two built-in A/D converters of 12-bit resolution.  NeuG
202 uses LSBs of A/D converters' outputs as entropy sources.  It is
203 considered noise of quantization error, plus noise from power supply,
204 etc.
205
206 We chose analog inputs of IN10 and IN11, which is not connected to
207 external pin (for the version of 36-pin or 48-pin STM32F103).  The
208 input is configured as digital output 50MHz to get maximum noise of
209 environment.
210
211 By 556 samplings of two channels, we can get 1112-bit, as we can get
212 two bits (LSB of IN10 and LSB of IN11) from one sampling.  We put this
213 1112-bit and previous output of 256-bit to conditioning component.
214
215 Conditioning component is implemented by Hash_df function by SHA-256.
216 Since the noise source is not "white", signal is whiten by this
217 Conditioning component.
218
219 Experiments show that raw noise source of LSBs has more than 6.0
220 bit/byte entropy when it is no computation but just to take samples.
221 The entropy varies among different boards.  It seems that a board with
222 good power supply and capacitor has smaller entropy (6.2 or so), and
223 the one with poor power supply and capacitor has bigger entropy (7.3
224 or so).  That is considered noise of quantization error.
225
226 When there is some activities of MCU, it's more than 7.0 bit/byte
227 entropy for a board even with good power supply and capacitor.
228
229 My experience with STM32F103 and NeuG shows that noise source is
230 stable at least for a year.
231
232
233 Test results
234 ============
235
236 See files under the directory test-results, for test result of
237 "rngtest" in rng-tools, NIST STS 2.1.1, and Dieharder.
238
239 For Dieharder, I correct 13GiB (it took five days and six hours
240 and more), and use scripts to invoke dieharder.
241
242
243 Read-only Git Repository
244 ========================
245
246 You can browse at http://www.gniibe.org/gitweb?p=neug.git;a=summary
247
248 You can get it by:
249
250   $ git clone git://www.gniibe.org/neug.git/
251
252 or
253
254   $ git clone http://www.gniibe.org/git/neug.git/
255
256
257 I put ChibiOS/RT as a submodule of Git.  Please do this:
258
259   $ git submodule init
260   $ git submodule update
261
262
263
264 Information on the Web
265 ======================
266
267 Not yet.
268
269
270 Known Problem(s)
271 ================
272
273 On STBee (high-density device of STM32), sometimes, I observed stall
274 of generation of random number, after two hours, two hours and half,
275 etc.
276
277 Identified somehow.  When it stalls, status is like this (by OpenOCD, GDB):
278
279         adcp->state = ADC_ACTIVE
280         main thread: wait on condition variable at neug_get
281         rng thread: holding rb->m, event wait at rng_gen for ADC_DATA_AVAILABLE
282         idle thread: running
283         LED thread: event wait
284
285 Kicking DMA controller again (note: ADC is continuous mode, no need to
286 kick), by doing following:
287
288   (gdb) set ADCD1.dmastp->channel->CCR = 0
289   (gdb) set ADCD1.dmastp->channel->CNDTR = 8
290   (gdb) set ADCD1.dmastp->channel->CCR = 0x258f
291   (gdb) x/x 0x40020000          # DMA interrupt status register (DMA_ISR)
292   0x40020000:   0x00000007
293
294 Then, it goes again.
295
296 Lost DMA finish interrupt?
297
298
299 Your Contributions
300 ==================
301
302 FSIJ welcomes your contributions.  Please assign your copyright
303 to FSIJ (if possible).
304 --