a3311d1a1b3b937d38006c93cb7607ce31c17aa8
[gpxe.git] / src / include / gpxe / dhcp.h
1 #ifndef _GPXE_DHCP_H
2 #define _GPXE_DHCP_H
3
4 /** @file
5  *
6  * Dynamic Host Configuration Protocol
7  *
8  */
9
10 #include <stdint.h>
11 #include <gpxe/list.h>
12 #include <gpxe/in.h>
13 #include <gpxe/udp.h>
14 #include <gpxe/async.h>
15 #include <gpxe/retry.h>
16 #include <gpxe/hotplug.h>
17
18 /** BOOTP/DHCP server port */
19 #define BOOTPS_PORT 67
20
21 /** BOOTP/DHCP client port */
22 #define BOOTPC_PORT 68
23
24 /** Construct a tag value for an encapsulated option
25  *
26  * This tag value can be passed to Etherboot functions when searching
27  * for DHCP options in order to search for a tag within an
28  * encapsulated options block.
29  */
30 #define DHCP_ENCAP_OPT( encapsulator, encapsulated ) \
31         ( ( (encapsulator) << 8 ) | (encapsulated) )
32 /** Extract encapsulating option block tag from encapsulated tag value */
33 #define DHCP_ENCAPSULATOR( encap_opt ) ( (encap_opt) >> 8 )
34 /** Extract encapsulated option tag from encapsulated tag value */
35 #define DHCP_ENCAPSULATED( encap_opt ) ( (encap_opt) & 0xff )
36 /** Option is encapsulated */
37 #define DHCP_IS_ENCAP_OPT( opt ) DHCP_ENCAPSULATOR( opt )
38
39 /**
40  * @defgroup dhcpopts DHCP option tags
41  * @{
42  */
43
44 /** Padding
45  *
46  * This tag does not have a length field; it is always only a single
47  * byte in length.
48  */
49 #define DHCP_PAD 0
50
51 /** Minimum normal DHCP option */
52 #define DHCP_MIN_OPTION 1
53
54 /** Subnet mask */
55 #define DHCP_SUBNET_MASK 1
56
57 /** Routers */
58 #define DHCP_ROUTERS 3
59
60 /** DNS servers */
61 #define DHCP_DNS_SERVERS 6
62
63 /** Host name */
64 #define DHCP_HOST_NAME 12
65
66 /** Domain name */
67 #define DHCP_DOMAIN_NAME 15
68
69 /** Root path */
70 #define DHCP_ROOT_PATH 17
71
72 /** Vendor encapsulated options */
73 #define DHCP_VENDOR_ENCAP 43
74
75 /** Requested IP address */
76 #define DHCP_REQUESTED_ADDRESS 50
77
78 /** Lease time */
79 #define DHCP_LEASE_TIME 51
80
81 /** Option overloading
82  *
83  * The value of this option is the bitwise-OR of zero or more
84  * DHCP_OPTION_OVERLOAD_XXX constants.
85  */
86 #define DHCP_OPTION_OVERLOAD 52
87
88 /** The "file" field is overloaded to contain extra DHCP options */
89 #define DHCP_OPTION_OVERLOAD_FILE 1
90
91 /** The "sname" field is overloaded to contain extra DHCP options */
92 #define DHCP_OPTION_OVERLOAD_SNAME 2
93
94 /** DHCP message type */
95 #define DHCP_MESSAGE_TYPE 53
96 #define DHCPDISCOVER 1
97 #define DHCPOFFER 2
98 #define DHCPREQUEST 3
99 #define DHCPDECLINE 4
100 #define DHCPACK 5
101 #define DHCPNAK 6
102 #define DHCPRELEASE 7
103 #define DHCPINFORM 8
104
105 /** DHCP server identifier */
106 #define DHCP_SERVER_IDENTIFIER 54
107
108 /** Parameter request list */
109 #define DHCP_PARAMETER_REQUEST_LIST 55
110
111 /** Maximum DHCP message size */
112 #define DHCP_MAX_MESSAGE_SIZE 57
113
114 /** Vendor class identifier */
115 #define DHCP_VENDOR_CLASS_ID 60
116
117 /** Client identifier */
118 #define DHCP_CLIENT_ID 61
119
120 /** TFTP server name
121  *
122  * This option replaces the fixed "sname" field, when that field is
123  * used to contain overloaded options.
124  */
125 #define DHCP_TFTP_SERVER_NAME 66
126
127 /** Bootfile name
128  *
129  * This option replaces the fixed "file" field, when that field is
130  * used to contain overloaded options.
131  */
132 #define DHCP_BOOTFILE_NAME 67
133
134 /** Etherboot-specific encapsulated options
135  *
136  * This encapsulated options field is used to contain all options
137  * specific to Etherboot (i.e. not assigned by IANA or other standards
138  * bodies).
139  */
140 #define DHCP_EB_ENCAP 175
141
142 /** Priority of this options block
143  *
144  * This is a signed 8-bit integer field indicating the priority of
145  * this block of options.  It can be used to specify the relative
146  * priority of multiple option blocks (e.g. options from non-volatile
147  * storage versus options from a DHCP server).
148  */
149 #define DHCP_EB_PRIORITY DHCP_ENCAP_OPT ( DHCP_EB_ENCAP, 1 )
150
151 /** "Your" IP address
152  *
153  * This option is used internally to contain the value of the "yiaddr"
154  * field, in order to provide a consistent approach to storing and
155  * processing options.  It should never be present in a DHCP packet.
156  */
157 #define DHCP_EB_YIADDR DHCP_ENCAP_OPT ( DHCP_EB_ENCAP, 2 )
158
159 /** "Server" IP address
160  *
161  * This option is used internally to contain the value of the "siaddr"
162  * field, in order to provide a consistent approach to storing and
163  * processing options.  It should never be present in a DHCP packet.
164  */
165 #define DHCP_EB_SIADDR DHCP_ENCAP_OPT ( DHCP_EB_ENCAP, 3 )
166
167 /** BIOS drive number
168  *
169  * This is the drive number for a drive emulated via INT 13.  0x80 is
170  * the first hard disk, 0x81 is the second hard disk, etc.
171  */
172 #define DHCP_EB_BIOS_DRIVE DHCP_ENCAP_OPT ( DHCP_EB_ENCAP, 0xbd )
173
174 /** Username
175  *
176  * This will be used as the username for any required authentication.
177  * It is expected that this option's value will be held in
178  * non-volatile storage, rather than transmitted as part of a DHCP
179  * packet.
180  */
181 #define DHCP_EB_USERNAME DHCP_ENCAP_OPT ( DHCP_EB_ENCAP, 0xbe )
182
183 /** Password
184  *
185  * This will be used as the password for any required authentication.
186  * It is expected that this option's value will be held in
187  * non-volatile storage, rather than transmitted as part of a DHCP
188  * packet.
189  */
190 #define DHCP_EB_PASSWORD DHCP_ENCAP_OPT ( DHCP_EB_ENCAP, 0xbf )
191
192 /** iSCSI primary target IQN */
193 #define DHCP_ISCSI_PRIMARY_TARGET_IQN 201
194
195 /** iSCSI secondary target IQN */
196 #define DHCP_ISCSI_SECONDARY_TARGET_IQN 202
197
198 /** iSCSI initiator IQN */
199 #define DHCP_ISCSI_INITIATOR_IQN 203
200
201 /** Maximum normal DHCP option */
202 #define DHCP_MAX_OPTION 254
203
204 /** End of options
205  *
206  * This tag does not have a length field; it is always only a single
207  * byte in length.
208  */
209 #define DHCP_END 255
210
211 /** @} */
212
213 /**
214  * Count number of arguments to a variadic macro
215  *
216  * This rather neat, non-iterative solution is courtesy of Laurent
217  * Deniau.
218  *
219  */
220 #define _VA_ARG_COUNT(  _1,  _2,  _3,  _4,  _5,  _6,  _7,  _8,          \
221                         _9, _10, _11, _12, _13, _14, _15, _16,          \
222                        _17, _18, _19, _20, _21, _22, _23, _24,          \
223                        _25, _26, _27, _28, _29, _30, _31, _32,          \
224                        _33, _34, _35, _36, _37, _38, _39, _40,          \
225                        _41, _42, _43, _44, _45, _46, _47, _48,          \
226                        _49, _50, _51, _52, _53, _54, _55, _56,          \
227                        _57, _58, _59, _60, _61, _62, _63,   N, ... ) N
228 #define VA_ARG_COUNT( ... )                                             \
229         _VA_ARG_COUNT ( __VA_ARGS__,                                    \
230                         63, 62, 61, 60, 59, 58, 57, 56,                 \
231                         55, 54, 53, 52, 51, 50, 49, 48,                 \
232                         47, 46, 45, 44, 43, 42, 41, 40,                 \
233                         39, 38, 37, 36, 35, 34, 33, 32,                 \
234                         31, 30, 29, 28, 27, 26, 25, 24,                 \
235                         23, 22, 21, 20, 19, 18, 17, 16,                 \
236                         15, 14, 13, 12, 11, 10,  9,  8,                 \
237                          7,  6,  5,  4,  3,  2,  1,  0 )
238
239 /** Construct a DHCP option from a list of bytes */
240 #define DHCP_OPTION( ... ) VA_ARG_COUNT ( __VA_ARGS__ ), __VA_ARGS__
241
242 /** Construct a DHCP option from a list of characters */
243 #define DHCP_STRING( ... ) DHCP_OPTION ( __VA_ARGS__ )
244
245 /** Construct a byte-valued DHCP option */
246 #define DHCP_BYTE( value ) DHCP_OPTION ( value )
247
248 /** Construct a word-valued DHCP option */
249 #define DHCP_WORD( value ) DHCP_OPTION ( ( ( (value) >> 8 ) & 0xff ),   \
250                                          ( ( (value) >> 0  ) & 0xff ) )
251
252 /** Construct a dword-valued DHCP option */
253 #define DHCP_DWORD( value ) DHCP_OPTION ( ( ( (value) >> 24 ) & 0xff ), \
254                                           ( ( (value) >> 16 ) & 0xff ), \
255                                           ( ( (value) >> 8  ) & 0xff ), \
256                                           ( ( (value) >> 0  ) & 0xff ) )
257
258 /** Construct a DHCP encapsulated options field */
259 #define DHCP_ENCAP( ... ) DHCP_OPTION ( __VA_ARGS__, DHCP_END )
260
261 /**
262  * A DHCP option
263  *
264  * DHCP options consist of a mandatory tag, a length field that is
265  * mandatory for all options except @c DHCP_PAD and @c DHCP_END, and a
266  * payload.  
267  */
268 struct dhcp_option {
269         /** Tag
270          *
271          * Must be a @c DHCP_XXX value.
272          */
273         uint8_t tag;
274         /** Length
275          *
276          * This is the length of the data field (i.e. excluding the
277          * tag and length fields).  For the two tags @c DHCP_PAD and
278          * @c DHCP_END, the length field is implicitly zero and is
279          * also missing, i.e. these DHCP options are only a single
280          * byte in length.
281          */
282         uint8_t len;
283         /** Option data
284          *
285          * Interpretation of the content is entirely dependent upon
286          * the tag.  For fields containing a multi-byte integer, the
287          * field is defined to be in network-endian order (unless you
288          * are Intel and feel like violating the spec for fun).
289          */
290         union {
291                 uint8_t byte;
292                 uint16_t word;
293                 uint32_t dword;
294                 struct in_addr in;
295                 uint8_t bytes[0];
296                 char string[0];
297         } data;
298 } __attribute__ (( packed ));
299
300 /**
301  * Length of a DHCP option header
302  *
303  * The header is the portion excluding the data, i.e. the tag and the
304  * length.
305  */
306 #define DHCP_OPTION_HEADER_LEN ( offsetof ( struct dhcp_option, data ) )
307
308 /** Maximum length for a single DHCP option */
309 #define DHCP_MAX_LEN 0xff
310
311 /** A DHCP options block */
312 struct dhcp_option_block {
313         /** List of option blocks */
314         struct list_head list;
315         /** Option block raw data */
316         void *data;
317         /** Option block length */
318         size_t len;
319         /** Option block maximum length */
320         size_t max_len;
321         /** Block priority
322          *
323          * This is determined at the time of the call to
324          * register_options() by searching for the @c DHCP_EB_PRIORITY
325          * option.
326          */
327         signed int priority;
328 };
329
330 /**
331  * A DHCP header
332  *
333  */
334 struct dhcphdr {
335         /** Operation
336          *
337          * This must be either @c BOOTP_REQUEST or @c BOOTP_REPLY.
338          */
339         uint8_t op;
340         /** Hardware address type
341          *
342          * This is an ARPHRD_XXX constant.  Note that ARPHRD_XXX
343          * constants are nominally 16 bits wide; this could be
344          * considered to be a bug in the BOOTP/DHCP specification.
345          */
346         uint8_t htype;
347         /** Hardware address length */
348         uint8_t hlen;
349         /** Number of hops from server */
350         uint8_t hops;
351         /** Transaction ID */
352         uint32_t xid;
353         /** Seconds since start of acquisition */
354         uint16_t secs;
355         /** Flags */
356         uint16_t flags;
357         /** "Client" IP address
358          *
359          * This is filled in if the client already has an IP address
360          * assigned and can respond to ARP requests.
361          */
362         struct in_addr ciaddr;
363         /** "Your" IP address
364          *
365          * This is the IP address assigned by the server to the client.
366          */
367         struct in_addr yiaddr;
368         /** "Server" IP address
369          *
370          * This is the IP address of the next server to be used in the
371          * boot process.
372          */
373         struct in_addr siaddr;
374         /** "Gateway" IP address
375          *
376          * This is the IP address of the DHCP relay agent, if any.
377          */
378         struct in_addr giaddr;
379         /** Client hardware address */
380         uint8_t chaddr[16];
381         /** Server host name (null terminated)
382          *
383          * This field may be overridden and contain DHCP options
384          */
385         uint8_t sname[64];
386         /** Boot file name (null terminated)
387          *
388          * This field may be overridden and contain DHCP options
389          */
390         uint8_t file[128];
391         /** DHCP magic cookie
392          *
393          * Must have the value @c DHCP_MAGIC_COOKIE.
394          */
395         uint32_t magic;
396         /** DHCP options
397          *
398          * Variable length; extends to the end of the packet.  Minimum
399          * length (for the sake of sanity) is 1, to allow for a single
400          * @c DHCP_END tag.
401          */
402         uint8_t options[1];
403 };
404
405 /** Opcode for a request from client to server */
406 #define BOOTP_REQUEST 1
407
408 /** Opcode for a reply from server to client */
409 #define BOOTP_REPLY 2
410
411 /** DHCP magic cookie */
412 #define DHCP_MAGIC_COOKIE 0x63825363UL
413
414 /** DHCP packet option block fill order
415  *
416  * This is the order in which option blocks are filled when
417  * reassembling a DHCP packet.  We fill the smallest field ("sname")
418  * first, to maximise the chances of being able to fit large options
419  * within fields which are large enough to contain them.
420  */
421 enum dhcp_packet_option_block_fill_order {
422         OPTS_SNAME = 0,
423         OPTS_FILE,
424         OPTS_MAIN,
425         NUM_OPT_BLOCKS
426 };
427
428 /**
429  * A DHCP packet
430  *
431  */
432 struct dhcp_packet {
433         /** The DHCP packet contents */
434         struct dhcphdr *dhcphdr;
435         /** Maximum length of the DHCP packet buffer */
436         size_t max_len;
437         /** Used length of the DHCP packet buffer */
438         size_t len;
439         /** DHCP option blocks within a DHCP packet
440          *
441          * A DHCP packet contains three fields which can be used to
442          * contain options: the actual "options" field plus the "file"
443          * and "sname" fields (which can be overloaded to contain
444          * options).
445          */
446         struct dhcp_option_block options[NUM_OPT_BLOCKS];
447 };
448
449 /** A DHCP session */
450 struct dhcp_session {
451         /** UDP connection for this session */
452         struct udp_connection udp;
453
454         /** Network device being configured */
455         struct net_device *netdev;
456         /** Persistent reference to network device */
457         struct reference netdev_ref;
458
459         /** Options obtained from server */
460         struct dhcp_option_block *options;
461
462         /** State of the session
463          *
464          * This is a value for the @c DHCP_MESSAGE_TYPE option
465          * (e.g. @c DHCPDISCOVER).
466          */
467         int state;
468         /** Asynchronous operation for this DHCP session */
469         struct async async;
470         /** Retransmission timer */
471         struct retry_timer timer;
472 };
473
474 extern unsigned long dhcp_num_option ( struct dhcp_option *option );
475 extern void dhcp_ipv4_option ( struct dhcp_option *option,
476                                struct in_addr *inp );
477 extern int dhcp_snprintf ( char *buf, size_t size,
478                            struct dhcp_option *option );
479 extern struct dhcp_option *
480 find_dhcp_option ( struct dhcp_option_block *options, unsigned int tag );
481 extern void register_dhcp_options ( struct dhcp_option_block *options );
482 extern void unregister_dhcp_options ( struct dhcp_option_block *options );
483 extern void init_dhcp_options ( struct dhcp_option_block *options,
484                                 void *data, size_t max_len );
485 extern struct dhcp_option_block * alloc_dhcp_options ( size_t max_len );
486 extern void free_dhcp_options ( struct dhcp_option_block *options );
487 extern struct dhcp_option *
488 set_dhcp_option ( struct dhcp_option_block *options, unsigned int tag,
489                   const void *data, size_t len );
490 extern struct dhcp_option * find_global_dhcp_option ( unsigned int tag );
491 extern unsigned long find_dhcp_num_option ( struct dhcp_option_block *options,
492                                             unsigned int tag );
493 extern unsigned long find_global_dhcp_num_option ( unsigned int tag );
494 extern void find_dhcp_ipv4_option ( struct dhcp_option_block *options,
495                                     unsigned int tag, struct in_addr *inp );
496 extern void find_global_dhcp_ipv4_option ( unsigned int tag,
497                                            struct in_addr *inp );
498 extern void delete_dhcp_option ( struct dhcp_option_block *options,
499                                  unsigned int tag );
500
501 extern struct dhcp_option_block dhcp_request_options;
502 extern int create_dhcp_packet ( struct net_device *netdev, uint8_t msgtype,
503                                 void *data, size_t max_len,
504                                 struct dhcp_packet *dhcppkt );
505 extern int copy_dhcp_packet_options ( struct dhcp_packet *dhcppkt,
506                                       struct dhcp_option_block *options );
507 extern int start_dhcp ( struct dhcp_session *dhcp, struct async *parent );
508
509 #endif /* _GPXE_DHCP_H */