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