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