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