[settings] Add Bus ID setting
[people/mcb30/gpxe.git] / src / include / gpxe / settings.h
1 #ifndef _GPXE_SETTINGS_H
2 #define _GPXE_SETTINGS_H
3
4 /** @file
5  *
6  * Configuration settings
7  *
8  */
9
10 FILE_LICENCE ( GPL2_OR_LATER );
11
12 #include <stdint.h>
13 #include <gpxe/tables.h>
14 #include <gpxe/list.h>
15 #include <gpxe/refcnt.h>
16
17 struct settings;
18 struct in_addr;
19 union uuid;
20
21 /** A setting */
22 struct setting {
23         /** Name
24          *
25          * This is the human-readable name for the setting.
26          */
27         const char *name;
28         /** Description */
29         const char *description;
30         /** Setting type
31          *
32          * This identifies the type of setting (e.g. string, IPv4
33          * address, etc.).
34          */
35         struct setting_type *type;
36         /** DHCP option number, if applicable */
37         unsigned int tag;
38 };
39
40 /** Configuration setting table */
41 #define SETTINGS __table ( struct setting, "settings" )
42
43 /** Declare a configuration setting */
44 #define __setting __table_entry ( SETTINGS, 01 )
45
46 /** Settings block operations */
47 struct settings_operations {
48         /** Store value of setting
49          *
50          * @v settings          Settings block
51          * @v setting           Setting to store
52          * @v data              Setting data, or NULL to clear setting
53          * @v len               Length of setting data
54          * @ret rc              Return status code
55          */
56         int ( * store ) ( struct settings *settings, struct setting *setting,
57                           const void *data, size_t len );
58         /** Fetch value of setting
59          *
60          * @v settings          Settings block
61          * @v setting           Setting to fetch
62          * @v data              Buffer to fill with setting data
63          * @v len               Length of buffer
64          * @ret len             Length of setting data, or negative error
65          *
66          * The actual length of the setting will be returned even if
67          * the buffer was too small.
68          */
69         int ( * fetch ) ( struct settings *settings, struct setting *setting,
70                           void *data, size_t len );
71         /** Clear settings block
72          *
73          * @v settings          Settings block
74          */
75         void ( * clear ) ( struct settings *settings );
76 };
77
78 /** A settings block */
79 struct settings {
80         /** Reference counter */
81         struct refcnt *refcnt;
82         /** Name */
83         const char *name;
84         /** Tag magic
85          *
86          * This value will be ORed in to any numerical tags
87          * constructed by parse_setting_name(), and can be used to
88          * avoid e.g. attempting to retrieve the subnet mask from
89          * SMBIOS, or the system UUID from DHCP.
90          */
91         unsigned int tag_magic;
92         /** Parent settings block */
93         struct settings *parent;
94         /** Sibling settings blocks */
95         struct list_head siblings;
96         /** Child settings blocks */
97         struct list_head children;
98         /** Settings block operations */
99         struct settings_operations *op;
100 };
101
102 /**
103  * A setting type
104  *
105  * This represents a type of setting (e.g. string, IPv4 address,
106  * etc.).
107  */
108 struct setting_type {
109         /** Name
110          *
111          * This is the name exposed to the user (e.g. "string").
112          */
113         const char *name;
114         /** Parse and set value of setting
115          *
116          * @v settings          Settings block
117          * @v setting           Setting to store
118          * @v value             Formatted setting data
119          * @ret rc              Return status code
120          */
121         int ( * storef ) ( struct settings *settings, struct setting *setting,
122                            const char *value );
123         /** Fetch and format value of setting
124          *
125          * @v settings          Settings block
126          * @v setting           Setting to fetch
127          * @v buf               Buffer to contain formatted value
128          * @v len               Length of buffer
129          * @ret len             Length of formatted value, or negative error
130          */
131         int ( * fetchf ) ( struct settings *settings, struct setting *setting,
132                            char *buf, size_t len );
133 };
134
135 /** Configuration setting type table */
136 #define SETTING_TYPES __table ( struct setting_type, "setting_types" )
137
138 /** Declare a configuration setting type */
139 #define __setting_type __table_entry ( SETTING_TYPES, 01 )
140
141 /**
142  * A settings applicator
143  *
144  */
145 struct settings_applicator {
146         /** Apply updated settings
147          *
148          * @ret rc              Return status code
149          */
150         int ( * apply ) ( void );
151 };
152
153 /** Settings applicator table */
154 #define SETTINGS_APPLICATORS \
155         __table ( struct settings_applicator, "settings_applicators" )
156
157 /** Declare a settings applicator */
158 #define __settings_applicator __table_entry ( SETTINGS_APPLICATORS, 01 )
159
160 /**
161  * A generic settings block
162  *
163  */
164 struct generic_settings {
165         /** Settings block */
166         struct settings settings;
167         /** List of generic settings */
168         struct list_head list;
169 };
170
171 extern struct settings_operations generic_settings_operations;
172 extern int generic_settings_store ( struct settings *settings,
173                                     struct setting *setting,
174                                     const void *data, size_t len );
175 extern int generic_settings_fetch ( struct settings *settings,
176                                     struct setting *setting,
177                                     void *data, size_t len );
178 extern void generic_settings_clear ( struct settings *settings );
179
180 extern int register_settings ( struct settings *settings,
181                                struct settings *parent );
182 extern void unregister_settings ( struct settings *settings );
183
184 extern int store_setting ( struct settings *settings, struct setting *setting,
185                            const void *data, size_t len );
186 extern int fetch_setting ( struct settings *settings, struct setting *setting,
187                            void *data, size_t len );
188 extern int fetch_setting_len ( struct settings *settings,
189                                struct setting *setting );
190 extern int fetch_string_setting ( struct settings *settings,
191                                   struct setting *setting,
192                                   char *data, size_t len );
193 extern int fetch_string_setting_copy ( struct settings *settings,
194                                        struct setting *setting,
195                                        char **data );
196 extern int fetch_ipv4_setting ( struct settings *settings,
197                                 struct setting *setting, struct in_addr *inp );
198 extern int fetch_int_setting ( struct settings *settings,
199                                struct setting *setting, long *value );
200 extern int fetch_uint_setting ( struct settings *settings,
201                                 struct setting *setting,
202                                 unsigned long *value );
203 extern long fetch_intz_setting ( struct settings *settings,
204                                  struct setting *setting );
205 extern unsigned long fetch_uintz_setting ( struct settings *settings,
206                                            struct setting *setting );
207 extern int fetch_uuid_setting ( struct settings *settings,
208                                 struct setting *setting, union uuid *uuid );
209 extern void clear_settings ( struct settings *settings );
210 extern int setting_cmp ( struct setting *a, struct setting *b );
211
212 extern struct settings * find_settings ( const char *name );
213
214 extern int storef_setting ( struct settings *settings,
215                             struct setting *setting,
216                             const char *value );
217 extern int storef_named_setting ( const char *name, const char *value );
218 extern int fetchf_named_setting ( const char *name, char *buf, size_t len );
219
220 extern struct setting_type setting_type_string __setting_type;
221 extern struct setting_type setting_type_ipv4 __setting_type;
222 extern struct setting_type setting_type_int8 __setting_type;
223 extern struct setting_type setting_type_int16 __setting_type;
224 extern struct setting_type setting_type_int32 __setting_type;
225 extern struct setting_type setting_type_uint8 __setting_type;
226 extern struct setting_type setting_type_uint16 __setting_type;
227 extern struct setting_type setting_type_uint32 __setting_type;
228 extern struct setting_type setting_type_hex __setting_type;
229 extern struct setting_type setting_type_uuid __setting_type;
230
231 extern struct setting ip_setting __setting;
232 extern struct setting netmask_setting __setting;
233 extern struct setting gateway_setting __setting;
234 extern struct setting dns_setting __setting;
235 extern struct setting domain_setting __setting;
236 extern struct setting hostname_setting __setting;
237 extern struct setting filename_setting __setting;
238 extern struct setting root_path_setting __setting;
239 extern struct setting username_setting __setting;
240 extern struct setting password_setting __setting;
241 extern struct setting priority_setting __setting;
242 extern struct setting uuid_setting __setting;
243 extern struct setting next_server_setting __setting;
244 extern struct setting mac_setting __setting;
245 extern struct setting busid_setting __setting;
246 extern struct setting user_class_setting __setting;
247
248 /**
249  * Initialise a settings block
250  *
251  * @v settings          Settings block
252  * @v op                Settings block operations
253  * @v refcnt            Containing object reference counter, or NULL
254  * @v name              Settings block name
255  * @v tag_magic         Tag magic
256  */
257 static inline void settings_init ( struct settings *settings,
258                                    struct settings_operations *op,
259                                    struct refcnt *refcnt,
260                                    const char *name,
261                                    unsigned int tag_magic ) {
262         INIT_LIST_HEAD ( &settings->siblings );
263         INIT_LIST_HEAD ( &settings->children );
264         settings->op = op;
265         settings->refcnt = refcnt;
266         settings->name = name;
267         settings->tag_magic = tag_magic;
268 }
269
270 /**
271  * Initialise a settings block
272  *
273  * @v generics          Generic settings block
274  * @v refcnt            Containing object reference counter, or NULL
275  * @v name              Settings block name
276  */
277 static inline void generic_settings_init ( struct generic_settings *generics,
278                                            struct refcnt *refcnt,
279                                            const char *name ) {
280         settings_init ( &generics->settings, &generic_settings_operations,
281                         refcnt, name, 0 );
282         INIT_LIST_HEAD ( &generics->list );
283 }
284
285 /**
286  * Delete setting
287  *
288  * @v settings          Settings block
289  * @v setting           Setting to delete
290  * @ret rc              Return status code
291  */
292 static inline int delete_setting ( struct settings *settings,
293                                    struct setting *setting ) {
294         return store_setting ( settings, setting, NULL, 0 );
295 }
296
297 /**
298  * Fetch and format value of setting
299  *
300  * @v settings          Settings block, or NULL to search all blocks
301  * @v setting           Setting to fetch
302  * @v type              Settings type
303  * @v buf               Buffer to contain formatted value
304  * @v len               Length of buffer
305  * @ret len             Length of formatted value, or negative error
306  */
307 static inline int fetchf_setting ( struct settings *settings,
308                                    struct setting *setting,
309                                    char *buf, size_t len ) {
310         return setting->type->fetchf ( settings, setting, buf, len );
311 }
312
313 /**
314  * Delete named setting
315  *
316  * @v name              Name of setting
317  * @ret rc              Return status code
318  */
319 static inline int delete_named_setting ( const char *name ) {
320         return storef_named_setting ( name, NULL );
321 }
322
323 /**
324  * Check existence of setting
325  *
326  * @v settings          Settings block, or NULL to search all blocks
327  * @v setting           Setting to fetch
328  * @ret exists          Setting exists
329  */
330 static inline int setting_exists ( struct settings *settings,
331                                    struct setting *setting ) {
332         return ( fetch_setting_len ( settings, setting ) >= 0 );
333 }
334
335 #endif /* _GPXE_SETTINGS_H */