5accbc7262939817403ee9b717b083ae7a9c43f3
[gnuk/neug.git] / README
1 NeuG - a random number generator implementation (for STM32F103)
2
3                                                            Version 0.01
4                                                              2011-11-14
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
25 Release notes
26 =============
27
28 This is the second release of NeuG, which is experimental.  You can
29 enjoy NeuG device, but I don't know how it is good yet.  Note that you
30 need the snapshot of ChibiOS/RT (from trunk).  This means that it is
31 covered by GNU GPL.  No "linking exception" option is available for
32 the snapshot.
33
34
35 FAQ
36 ===
37
38 Q0: How NeuG device is good?
39 A0: I believe it's good enough.  I evaluated it with rngtest of
40     RNG-tools, NIST STS test and Dieharder.
41     See the directory neug/test-results/.
42 A0-dash: For better entropy device, you can get EntropyKey.
43          See http://www.entropykey.co.uk/
44 A0-double-dash: STM32F2xx has built-in TRNG, it would be better for you.
45
46 Q1: How fast is NeuG device?
47 A1: It's something around 24 Ki-byte/second.
48
49 Q2: Should we check condition of noise sources?
50 A2: Yes, we should.  It's not implemented yet, and I don't have an
51     good idea how to implement.  Please let me know your idea.
52
53
54 Targets
55 =======
56
57 STBee Mini, Olimex STM32-H103, CQ-STARM, and STBee are supported.
58
59
60 Souce code
61 ==========
62
63 NeuG source code is under src/ directory.
64
65
66 License
67 =======
68
69 It is distributed under GNU General Public Licence version 3 or later
70 (GPLv3+).  Please see src/COPYING.
71
72
73 External source code
74 ====================
75
76 To build NeuG device, we need external source code.
77
78 * chibios/  -- ChibiOS/RT 2.3.x snapshot
79
80   Please get it from http://chibios.sourceforge.net/
81   We use ChibiOS/RT as the kernel for NeuG device.
82
83
84 How to compile
85 ==============
86
87 You need GNU toolchain and newlib for 'arm-none-eabi' target.
88
89 See http://github.com/uwehermann/summon-arm-toolchain/ for preparation
90 of GNU Toolchain for 'arm-none-eabi' target.
91
92 Change directory to `src':
93
94   $ cd neug-VERSION/src
95
96 Then, run `configure':
97
98   $ ./configure
99
100 Type:
101
102   $ make
103
104 Then, we will have "neug.elf".
105
106
107 How to install
108 ==============
109
110 STBee Mini and STBee
111 --------------------
112
113 Reset the board with "USER" switch pushed.  Type following to write
114 to flash:
115
116   # cd ../tool
117   # ./dfuse.py ../src/neug.hex
118
119 Then, reset the board.
120
121
122 Olimex STM32-H103 board
123 -----------------------
124
125 If you are using Olimex JTAG-Tiny, type following to invoke OpenOCD:
126
127   $ openocd -f interface/olimex-jtag-tiny.cfg -f board/olimex_stm32_h103.cfg
128
129 Then, with another terminal, type following to write "gnuk.elf" to Flash ROM:
130
131   $ telnet localhost 4444
132   > reset halt
133   > flash write_image erase neug.elf
134   > reset
135   > exit
136   $ 
137
138
139
140 Use of NeuG device
141 ==================
142
143 It is USB CDC ACM device.  On GNU/Linux, it can be /dev/ttyACM0 or like.
144 Before using /dev/ttyACM0, you need to configure its TTY discipline.
145
146   $ stty -F /dev/ttyACM0 -echo raw
147
148 Then, you can use output of /dev/ttyACM0.
149
150
151
152 Structure of the NeuG
153 =====================
154
155 NeuG consists of two RNG, one is the RNG based on physical noise, and
156 another is Pseudo RNG.  Outputs of RNGs are exclusive or-ed
157 to generate final output.  Here is a figure of the circuit.
158
159
160                         Entropy Pool (16-byte)
161                        +----------------+
162                        |                |
163                        | 8 parallel     |   8  ||<-- [ Vref ]
164                  +---- |  CRC-16        |<--/--||
165                  |     | shift registers|      ||<-- [ Temperature Sensor ]
166                  |     |                |
167                  |     |                |<----/------ SysTick
168                  |     +----------------+     1
169                  |     Physical-based RNG
170                  / 8
171                  |
172                  v
173                ===== Output function
174                  |
175                  / 32
176                  |
177                  +-------------+
178                  |             |
179                  / 32          / 32  Seed
180                  |             |
181                  |             v
182   Random     32  v      32 +--------+
183   Number  <--/--[XOR]<--/--| TinyMT |
184   Output                   +--------+
185                            Pseudo RNG
186
187
188 STM32F103 has built-in Vref (voltage reference) and Temperature Sensor
189 which are connected to A/D converter of 12-bit resolution.  NeuG uses
190 LSBs of A/D converter's outputs and A/D converter's interrupt timings
191 as entropy sources.
192
193 By four samplings of two channels, we can get 8-bit, as we can get two
194 bits (LSB of Vref and LSB of Temperature Sensor) from one sampling.
195 We put this 8-bit noise to entropy pool.  Entropy pool consist of
196 16-byte buffer, which is 8 parallel CRC-16 shift registers.  The noise
197 source is not "white", but it can be used as RNG with this CRC-16
198 filter.  An experiment shows that raw noise source of LSBs has more
199 than 6 bit/byte entropy.  So, we put 7-byte to get 4-byte (32-bit)
200 output.
201
202 I don't know how stable the noise source is.
203
204 So, NeuG comes with second RNG.  It is pseudo RNG timings.  We use
205 TinyMT for pseudo RNG.  Please see following page for TinyMT:
206
207    "Tiny Mersenne Twister (TinyMT): A small-sized variant of Mersenne Twister"
208    by Mutsuo Saito and Makoto Matsumoto
209      http://www.math.sci.hiroshima-u.ac.jp/~m-mat/MT/TINYMT/
210
211
212 Test results
213 ============
214
215 See files under the directory test-results, for test result of
216 "rngtest" in rng-tools, and NIST STS 2.1.1.  Currently, I am testing
217 NeuG device by dieharder, but it seems that it takes a month or so (8
218 days passed, it's running RGB Bit distribution test ntup=9).
219
220
221 Read-only Git Repository
222 ========================
223
224 You can browse at http://www.gniibe.org/gitweb?p=neug.git;a=summary
225
226 You can get it by:
227
228   $ git clone git://www.gniibe.org/neug.git/
229
230 or
231
232   $ git clone http://www.gniibe.org/git/neug.git/
233
234
235 I put ChibiOS/RT as a submodule of Git.  Please do this:
236
237   $ git submodule init
238   $ git submodule update
239
240
241
242 Information on the Web
243 ======================
244
245 Not yet.
246
247
248 Known Problem(s)
249 ================
250
251 On STBee (high-density device of STM32), sometimes, I observed stall
252 of generation of random number, after two hours, two hours and half,
253 etc.
254
255 Identified somehow.  When it stalls, status is like this (by OpenOCD, GDB):
256
257         adcp->state = ADC_ACTIVE
258         main thread: wait on condition variable at neug_get
259         rng thread: holding rb->m, event wait at rng_gen for ADC_DATA_AVAILABLE
260         idle thread: running
261         LED thread: event wait
262
263 Kicking DMA controller again (note: ADC is continuous mode, no need to
264 kick), by doing following:
265
266   (gdb) set ADCD1.dmastp->channel->CCR = 0
267   (gdb) set ADCD1.dmastp->channel->CNDTR = 8
268   (gdb) set ADCD1.dmastp->channel->CCR = 0x258f
269   (gdb) x/x 0x40020000          # DMA interrupt status register (DMA_ISR)
270   0x40020000:   0x00000007
271
272 Then, it goes again.
273
274 Lost DMA finish interrupt?
275
276
277 Your Contributions
278 ==================
279
280 FSIJ welcomes your contributions.  Please assign your copyright
281 to FSIJ (if possible).
282 --