Sat Dec 17 12:59:22 2011 UTC ()
Add comments for some ioctls and structs; fix a typo in another comment.


(apb)
diff -r1.26 -r1.27 src/sys/sys/rnd.h

cvs diff -r1.26 -r1.27 src/sys/sys/rnd.h (switch to unified diff)

--- src/sys/sys/rnd.h 2011/11/29 03:50:32 1.26
+++ src/sys/sys/rnd.h 2011/12/17 12:59:21 1.27
@@ -1,213 +1,218 @@ @@ -1,213 +1,218 @@
1/* $NetBSD: rnd.h,v 1.26 2011/11/29 03:50:32 tls Exp $ */ 1/* $NetBSD: rnd.h,v 1.27 2011/12/17 12:59:21 apb Exp $ */
2 2
3/*- 3/*-
4 * Copyright (c) 1997 The NetBSD Foundation, Inc. 4 * Copyright (c) 1997 The NetBSD Foundation, Inc.
5 * All rights reserved. 5 * All rights reserved.
6 * 6 *
7 * This code is derived from software contributed to The NetBSD Foundation 7 * This code is derived from software contributed to The NetBSD Foundation
8 * by Michael Graff <explorer@flame.org>. This code uses ideas and 8 * by Michael Graff <explorer@flame.org>. This code uses ideas and
9 * algorithms from the Linux driver written by Ted Ts'o. 9 * algorithms from the Linux driver written by Ted Ts'o.
10 * 10 *
11 * Redistribution and use in source and binary forms, with or without 11 * Redistribution and use in source and binary forms, with or without
12 * modification, are permitted provided that the following conditions 12 * modification, are permitted provided that the following conditions
13 * are met: 13 * are met:
14 * 1. Redistributions of source code must retain the above copyright 14 * 1. Redistributions of source code must retain the above copyright
15 * notice, this list of conditions and the following disclaimer. 15 * notice, this list of conditions and the following disclaimer.
16 * 2. Redistributions in binary form must reproduce the above copyright 16 * 2. Redistributions in binary form must reproduce the above copyright
17 * notice, this list of conditions and the following disclaimer in the 17 * notice, this list of conditions and the following disclaimer in the
18 * documentation and/or other materials provided with the distribution. 18 * documentation and/or other materials provided with the distribution.
19 * 19 *
20 * THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 20 * THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
21 * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 21 * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
22 * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 22 * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
23 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 23 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
24 * BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 24 * BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
25 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 25 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
26 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 26 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
27 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 27 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
28 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 28 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
29 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 29 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
30 * POSSIBILITY OF SUCH DAMAGE. 30 * POSSIBILITY OF SUCH DAMAGE.
31 */ 31 */
32 32
33#ifndef _SYS_RND_H_ 33#ifndef _SYS_RND_H_
34#define _SYS_RND_H_ 34#define _SYS_RND_H_
35 35
36#ifndef _KERNEL 36#ifndef _KERNEL
37#include <sys/cdefs.h> 37#include <sys/cdefs.h>
38#endif /* !_KERNEL */ 38#endif /* !_KERNEL */
39 39
40#include <sys/types.h> 40#include <sys/types.h>
41#include <sys/sha1.h> 41#include <sys/sha1.h>
42 42
43#ifdef _KERNEL 43#ifdef _KERNEL
44#include <sys/queue.h> 44#include <sys/queue.h>
45#endif 45#endif
46 46
47#ifdef _KERNEL 47#ifdef _KERNEL
48#include <sys/rngtest.h> 48#include <sys/rngtest.h>
49#endif 49#endif
50 50
51#define RND_DEV_RANDOM 0 /* minor devices for random and kinda random */ 51#define RND_DEV_RANDOM 0 /* minor devices for random and kinda random */
52#define RND_DEV_URANDOM 1 52#define RND_DEV_URANDOM 1
53 53
54/* 54/*
55 * Exposed "size" of entropy pool, for convenience in load/save 55 * Exposed "size" of entropy pool, for convenience in load/save
56 * from userspace. Do not assume this is the same as the actual in-kernel 56 * from userspace. Do not assume this is the same as the actual in-kernel
57 * pool size! 57 * pool size!
58 */ 58 */
59#define RND_SAVEWORDS 128 59#define RND_SAVEWORDS 128
60typedef struct { 60typedef struct {
61 uint32_t entropy; 61 uint32_t entropy;
62 uint8_t data[RND_SAVEWORDS * sizeof(uint32_t)]; 62 uint8_t data[RND_SAVEWORDS * sizeof(uint32_t)];
63 uint8_t digest[SHA1_DIGEST_LENGTH]; 63 uint8_t digest[SHA1_DIGEST_LENGTH];
64} rndsave_t; 64} rndsave_t;
65 65
 66/* Statistics exposed by RNDGETPOOLSTAT */
66typedef struct 67typedef struct
67{ 68{
68 uint32_t poolsize; 69 uint32_t poolsize;
69 uint32_t threshold; 70 uint32_t threshold;
70 uint32_t maxentropy; 71 uint32_t maxentropy;
71 72
72 uint32_t added; 73 uint32_t added;
73 uint32_t curentropy; 74 uint32_t curentropy;
74 uint32_t removed; 75 uint32_t removed;
75 uint32_t discarded; 76 uint32_t discarded;
76 uint32_t generated; 77 uint32_t generated;
77} rndpoolstat_t; 78} rndpoolstat_t;
78 79
79/* Sanitized random source view for userspace */ 80/* Sanitized random source view for userspace */
80typedef struct { 81typedef struct {
81 char name[16]; /* device name */ 82 char name[16]; /* device name */
82 uint32_t total; /* entropy from this source */ 83 uint32_t total; /* entropy from this source */
83 uint32_t type; /* type */ 84 uint32_t type; /* type */
84 uint32_t flags; /* flags */ 85 uint32_t flags; /* flags */
85} rndsource_t; 86} rndsource_t;
86 87
87/* 88/*
88 * Flags to control the source. Low byte is type, upper bits are flags. 89 * Flags to control the source. Low byte is type, upper bits are flags.
89 */ 90 */
90#define RND_FLAG_NO_ESTIMATE 0x00000100 /* don't estimate entropy */ 91#define RND_FLAG_NO_ESTIMATE 0x00000100 /* don't estimate entropy */
91#define RND_FLAG_NO_COLLECT 0x00000200 /* don't collect entropy */ 92#define RND_FLAG_NO_COLLECT 0x00000200 /* don't collect entropy */
92 93
93#define RND_TYPE_UNKNOWN 0 /* unknown source */ 94#define RND_TYPE_UNKNOWN 0 /* unknown source */
94#define RND_TYPE_DISK 1 /* source is physical disk */ 95#define RND_TYPE_DISK 1 /* source is physical disk */
95#define RND_TYPE_NET 2 /* source is a network device */ 96#define RND_TYPE_NET 2 /* source is a network device */
96#define RND_TYPE_TAPE 3 /* source is a tape drive */ 97#define RND_TYPE_TAPE 3 /* source is a tape drive */
97#define RND_TYPE_TTY 4 /* source is a tty device */ 98#define RND_TYPE_TTY 4 /* source is a tty device */
98#define RND_TYPE_RNG 5 /* source is a random number 99#define RND_TYPE_RNG 5 /* source is a random number
99 generator */ 100 generator */
100#define RND_TYPE_MAX 5 /* last type id used */ 101#define RND_TYPE_MAX 5 /* last type id used */
101 102
102#ifdef _KERNEL 103#ifdef _KERNEL
103/* 104/*
104 * Size of entropy pool in 32-bit words. This _MUST_ be a power of 2. Don't 105 * Size of entropy pool in 32-bit words. This _MUST_ be a power of 2. Don't
105 * change this unless you really know what you are doing... 106 * change this unless you really know what you are doing...
106 */ 107 */
107#ifndef RND_POOLWORDS 108#ifndef RND_POOLWORDS
108#define RND_POOLWORDS 128 109#define RND_POOLWORDS 128
109#endif 110#endif
110#define RND_POOLBITS (RND_POOLWORDS * 32) 111#define RND_POOLBITS (RND_POOLWORDS * 32)
111 112
112typedef struct krndsource { 113typedef struct krndsource {
113 LIST_ENTRY(krndsource) list; /* the linked list */ 114 LIST_ENTRY(krndsource) list; /* the linked list */
114 char name[16]; /* device name */ 115 char name[16]; /* device name */
115 uint32_t last_time; /* last time recorded */ 116 uint32_t last_time; /* last time recorded */
116 uint32_t last_delta; /* last delta value */ 117 uint32_t last_delta; /* last delta value */
117 uint32_t last_delta2; /* last delta2 value */ 118 uint32_t last_delta2; /* last delta2 value */
118 uint32_t total; /* entropy from this source */ 119 uint32_t total; /* entropy from this source */
119 uint32_t type; /* type */ 120 uint32_t type; /* type */
120 uint32_t flags; /* flags */ 121 uint32_t flags; /* flags */
121 void *state; /* state informaiton */ 122 void *state; /* state information */
122 size_t test_cnt; /* how much test data accumulated? */ 123 size_t test_cnt; /* how much test data accumulated? */
123 rngtest_t *test; /* test data for RNG type sources */ 124 rngtest_t *test; /* test data for RNG type sources */
124} krndsource_t; 125} krndsource_t;
125 126
126typedef struct rndsink { 127typedef struct rndsink {
127 TAILQ_ENTRY(rndsink) tailq; /* the queue */ 128 TAILQ_ENTRY(rndsink) tailq; /* the queue */
128 void (*cb)(void *); /* callback function when ready */ 129 void (*cb)(void *); /* callback function when ready */
129 void *arg; /* callback function argument */ 130 void *arg; /* callback function argument */
130 char name[16]; /* sink name */ 131 char name[16]; /* sink name */
131 size_t len; /* how many bytes wanted/supplied */ 132 size_t len; /* how many bytes wanted/supplied */
132 uint8_t data[64]; /* random data returned here */ 133 uint8_t data[64]; /* random data returned here */
133} rndsink_t; 134} rndsink_t;
134 135
135typedef struct { 136typedef struct {
136 uint32_t cursor; /* current add point in the pool */ 137 uint32_t cursor; /* current add point in the pool */
137 uint32_t rotate; /* how many bits to rotate by */ 138 uint32_t rotate; /* how many bits to rotate by */
138 rndpoolstat_t stats; /* current statistics */ 139 rndpoolstat_t stats; /* current statistics */
139 uint32_t pool[RND_POOLWORDS]; /* random pool data */ 140 uint32_t pool[RND_POOLWORDS]; /* random pool data */
140} rndpool_t; 141} rndpool_t;
141 142
142#define RND_ENABLED(rp) \ 143#define RND_ENABLED(rp) \
143 (((rp)->flags & RND_FLAG_NO_COLLECT) == 0) 144 (((rp)->flags & RND_FLAG_NO_COLLECT) == 0)
144 145
145void rndpool_init(rndpool_t *); 146void rndpool_init(rndpool_t *);
146void rndpool_init_global(void); 147void rndpool_init_global(void);
147uint32_t rndpool_get_entropy_count(rndpool_t *); 148uint32_t rndpool_get_entropy_count(rndpool_t *);
148void rndpool_get_stats(rndpool_t *, void *, int); 149void rndpool_get_stats(rndpool_t *, void *, int);
149void rndpool_increment_entropy_count(rndpool_t *, uint32_t); 150void rndpool_increment_entropy_count(rndpool_t *, uint32_t);
150uint32_t *rndpool_get_pool(rndpool_t *); 151uint32_t *rndpool_get_pool(rndpool_t *);
151uint32_t rndpool_get_poolsize(void); 152uint32_t rndpool_get_poolsize(void);
152void rndpool_add_data(rndpool_t *, void *, uint32_t, uint32_t); 153void rndpool_add_data(rndpool_t *, void *, uint32_t, uint32_t);
153uint32_t rndpool_extract_data(rndpool_t *, void *, uint32_t, uint32_t); 154uint32_t rndpool_extract_data(rndpool_t *, void *, uint32_t, uint32_t);
154void rnd_init(void); 155void rnd_init(void);
155void rnd_add_uint32(krndsource_t *, uint32_t); 156void rnd_add_uint32(krndsource_t *, uint32_t);
156void rnd_add_data(krndsource_t *, const void *const, uint32_t, 157void rnd_add_data(krndsource_t *, const void *const, uint32_t,
157 uint32_t); 158 uint32_t);
158void rnd_attach_source(krndsource_t *, const char *, 159void rnd_attach_source(krndsource_t *, const char *,
159 uint32_t, uint32_t); 160 uint32_t, uint32_t);
160void rnd_detach_source(krndsource_t *); 161void rnd_detach_source(krndsource_t *);
161 162
162void rndsink_attach(rndsink_t *); 163void rndsink_attach(rndsink_t *);
163void rndsink_detach(rndsink_t *); 164void rndsink_detach(rndsink_t *);
164 165
165void rnd_seed(void *, size_t); 166void rnd_seed(void *, size_t);
166 167
167#endif /* _KERNEL */ 168#endif /* _KERNEL */
168 169
169#define RND_MAXSTATCOUNT 10 /* 10 sources at once max */ 170#define RND_MAXSTATCOUNT 10 /* 10 sources at once max */
170 171
171/* 172/*
172 * return "count" random entries, starting at "start" 173 * return "count" random entries, starting at "start"
173 */ 174 */
174typedef struct { 175typedef struct {
175 uint32_t start; 176 uint32_t start;
176 uint32_t count; 177 uint32_t count;
177 rndsource_t source[RND_MAXSTATCOUNT]; 178 rndsource_t source[RND_MAXSTATCOUNT];
178} rndstat_t; 179} rndstat_t;
179 180
180/* 181/*
181 * return information on a specific source by name 182 * return information on a specific source by name
182 */ 183 */
183typedef struct { 184typedef struct {
184 char name[16]; 185 char name[16];
185 rndsource_t source; 186 rndsource_t source;
186} rndstat_name_t; 187} rndstat_name_t;
187 188
188/* 189/*
189 * set/clear device flags. If type is set to 0xff, the name is used 190 * set/clear device flags. If type is set to 0xff, the name is used
190 * instead. Otherwise, the flags set/cleared apply to all devices of 191 * instead. Otherwise, the flags set/cleared apply to all devices of
191 * the specified type, and the name is ignored. 192 * the specified type, and the name is ignored.
192 */ 193 */
193typedef struct { 194typedef struct {
194 char name[16]; /* the name we are adjusting */ 195 char name[16]; /* the name we are adjusting */
195 uint32_t type; /* the type of device we want */ 196 uint32_t type; /* the type of device we want */
196 uint32_t flags; /* flags to set or clear */ 197 uint32_t flags; /* flags to set or clear */
197 uint32_t mask; /* mask for the flags we are setting */ 198 uint32_t mask; /* mask for the flags we are setting */
198} rndctl_t; 199} rndctl_t;
199 200
 201/*
 202 * Add entropy to the pool. len is the data length, in bytes.
 203 * entropy is the number of bits of estimated entropy in the data.
 204 */
200typedef struct { 205typedef struct {
201 uint32_t len; 206 uint32_t len;
202 uint32_t entropy; 207 uint32_t entropy;
203 u_char data[RND_SAVEWORDS * sizeof(uint32_t)]; 208 u_char data[RND_SAVEWORDS * sizeof(uint32_t)];
204} rnddata_t; 209} rnddata_t;
205 210
206#define RNDGETENTCNT _IOR('R', 101, uint32_t) /* get entropy count */ 211#define RNDGETENTCNT _IOR('R', 101, uint32_t) /* get entropy count */
207#define RNDGETSRCNUM _IOWR('R', 102, rndstat_t) /* get rnd source info */ 212#define RNDGETSRCNUM _IOWR('R', 102, rndstat_t) /* get rnd source info */
208#define RNDGETSRCNAME _IOWR('R', 103, rndstat_name_t) /* get src by name */ 213#define RNDGETSRCNAME _IOWR('R', 103, rndstat_name_t) /* get src by name */
209#define RNDCTL _IOW('R', 104, rndctl_t) /* set/clear source flags */ 214#define RNDCTL _IOW('R', 104, rndctl_t) /* set/clear source flags */
210#define RNDADDDATA _IOW('R', 105, rnddata_t) /* add data to the pool */ 215#define RNDADDDATA _IOW('R', 105, rnddata_t) /* add data to the pool */
211#define RNDGETPOOLSTAT _IOR('R', 106, rndpoolstat_t) 216#define RNDGETPOOLSTAT _IOR('R', 106, rndpoolstat_t) /* get statistics */
212 217
213#endif /* !_SYS_RND_H_ */ 218#endif /* !_SYS_RND_H_ */