Introduce structured error codes.
[people/xl0/gpxe.git] / src / include / errno.h
1 #ifndef ERRNO_H
2 #define ERRNO_H
3
4 /** @file
5  *
6  * Error codes
7  *
8  * Return status codes as used within gPXE are designed to allow for
9  * maximum visibility into the source of an error even in an end-user
10  * build with no debugging.  They are constructed in three parts: a
11  * PXE error code, a POSIX error code, and a gPXE-specific error code.
12  *
13  * The low byte is the closest equivalent PXE error code
14  * (e.g. PXENV_STATUS_OUT_OF_RESOURCES), and is the only part of the
15  * error that will be returned via the PXE API, since PXE has
16  * predefined error codes.
17  *
18  * The next byte is the closest equivalent POSIX error code
19  * (e.g. ENOMEM).
20  *
21  * The remaining bytes are the gPXE-specific error code, which allow
22  * us to disambiguate between errors which should have the same POSIX
23  * error code but which mean very different things to the user
24  * (e.g. ENOENT due to a DNS name not existing versus ENOENT due to
25  * a web server returning HTTP/404 Not Found).
26  *
27  * The convention within the code is that errors are negative and
28  * expressed as the bitwise OR of a POSIX error code and (optionally)
29  * a gPXE error code, as in
30  *
31  *     return -( ENOENT | NO_SUCH_FILE );
32  *
33  * The POSIX error code is #defined to include the closest matching
34  * PXE error code (which, in most cases, is just
35  * PXENV_STATUS_FAILURE), so we don't need to litter the codebase with
36  * PXEisms.
37  *
38  * Functions that wish to return failure should be declared as
39  * returning an integer @c rc "Return status code".  A return value of
40  * zero indicates success, a non-zero value indicates failure.  The
41  * return value can be passed directly to strerror() in order to
42  * generate a human-readable error message, e.g.
43  *
44  *     if ( ( rc = some_function ( ... ) ) != 0 ) {
45  *         DBG ( "Whatever I was trying to do failed: %s\n", strerror ( rc ) );
46  *         return rc;
47  *     }
48  *
49  * As illustrated in the above example, error returns should generally
50  * be directly propagated upward to the calling function.
51  *
52  */
53
54 /**
55  * @defgroup pxeerrors PXE error codes
56  *
57  * The names, meanings and values of these error codes are defined by
58  * the PXE specification.
59  *
60  * @{
61  */
62
63 /* Generic errors */
64 #define PXENV_STATUS_SUCCESS                                           0x0000
65 #define PXENV_STATUS_FAILURE                                           0x0001
66 #define PXENV_STATUS_BAD_FUNC                                          0x0002
67 #define PXENV_STATUS_UNSUPPORTED                                       0x0003
68 #define PXENV_STATUS_KEEP_UNDI                                         0x0004
69 #define PXENV_STATUS_KEEP_ALL                                          0x0005
70 #define PXENV_STATUS_OUT_OF_RESOURCES                                  0x0006
71
72 /* ARP errors (0x0010 to 0x001f) */
73 #define PXENV_STATUS_ARP_TIMEOUT                                       0x0011
74
75 /* Base-Code state errors */
76 #define PXENV_STATUS_UDP_CLOSED                                        0x0018
77 #define PXENV_STATUS_UDP_OPEN                                          0x0019
78 #define PXENV_STATUS_TFTP_CLOSED                                       0x001a
79 #define PXENV_STATUS_TFTP_OPEN                                         0x001b
80
81 /* BIOS/system errors (0x0020 to 0x002f) */
82 #define PXENV_STATUS_MCOPY_PROBLEM                                     0x0020
83 #define PXENV_STATUS_BIS_INTEGRITY_FAILURE                             0x0021
84 #define PXENV_STATUS_BIS_VALIDATE_FAILURE                              0x0022
85 #define PXENV_STATUS_BIS_INIT_FAILURE                                  0x0023
86 #define PXENV_STATUS_BIS_SHUTDOWN_FAILURE                              0x0024
87 #define PXENV_STATUS_BIS_GBOA_FAILURE                                  0x0025
88 #define PXENV_STATUS_BIS_FREE_FAILURE                                  0x0026
89 #define PXENV_STATUS_BIS_GSI_FAILURE                                   0x0027
90 #define PXENV_STATUS_BIS_BAD_CKSUM                                     0x0028
91
92 /* TFTP/MTFTP errors (0x0030 to 0x003f) */
93 #define PXENV_STATUS_TFTP_CANNOT_ARP_ADDRESS                           0x0030
94 #define PXENV_STATUS_TFTP_OPEN_TIMEOUT                                 0x0032
95 #define PXENV_STATUS_TFTP_UNKNOWN_OPCODE                               0x0033
96 #define PXENV_STATUS_TFTP_READ_TIMEOUT                                 0x0035
97 #define PXENV_STATUS_TFTP_ERROR_OPCODE                                 0x0036
98 #define PXENV_STATUS_TFTP_CANNOT_OPEN_CONNECTION                       0x0038
99 #define PXENV_STATUS_TFTP_CANNOT_READ_FROM_CONNECTION                  0x0039
100 #define PXENV_STATUS_TFTP_TOO_MANY_PACKAGES                            0x003a
101 #define PXENV_STATUS_TFTP_FILE_NOT_FOUND                               0x003b
102 #define PXENV_STATUS_TFTP_ACCESS_VIOLATION                             0x003c
103 #define PXENV_STATUS_TFTP_NO_MCAST_ADDRESS                             0x003d
104 #define PXENV_STATUS_TFTP_NO_FILESIZE                                  0x003e
105 #define PXENV_STATUS_TFTP_INVALID_PACKET_SIZE                          0x003f
106
107 /* Reserved errors 0x0040 to 0x004f) */
108
109 /* DHCP/BOOTP errors (0x0050 to 0x005f) */
110 #define PXENV_STATUS_DHCP_TIMEOUT                                      0x0051
111 #define PXENV_STATUS_DHCP_NO_IP_ADDRESS                                0x0052
112 #define PXENV_STATUS_DHCP_NO_BOOTFILE_NAME                             0x0053
113 #define PXENV_STATUS_DHCP_BAD_IP_ADDRESS                               0x0054
114
115 /* Driver errors (0x0060 to 0x006f) */
116 #define PXENV_STATUS_UNDI_INVALID_FUNCTION                             0x0060
117 #define PXENV_STATUS_UNDI_MEDIATEST_FAILED                             0x0061
118 #define PXENV_STATUS_UNDI_CANNOT_INIT_NIC_FOR_MCAST                    0x0062
119 #define PXENV_STATUS_UNDI_CANNOT_INITIALIZE_NIC                        0x0063
120 #define PXENV_STATUS_UNDI_CANNOT_INITIALIZE_PHY                        0x0064
121 #define PXENV_STATUS_UNDI_CANNOT_READ_CONFIG_DATA                      0x0065
122 #define PXENV_STATUS_UNDI_CANNOT_READ_INIT_DATA                        0x0066
123 #define PXENV_STATUS_UNDI_BAD_MAC_ADDRESS                              0x0067
124 #define PXENV_STATUS_UNDI_BAD_EEPROM_CHECKSUM                          0x0068
125 #define PXENV_STATUS_UNDI_ERROR_SETTING_ISR                            0x0069
126 #define PXENV_STATUS_UNDI_INVALID_STATE                                0x006a
127 #define PXENV_STATUS_UNDI_TRANSMIT_ERROR                               0x006b
128 #define PXENV_STATUS_UNDI_INVALID_PARAMETER                            0x006c
129
130 /* ROM and NBP bootstrap errors (0x0070 to 0x007f) */
131 #define PXENV_STATUS_BSTRAP_PROMPT_MENU                                0x0074
132 #define PXENV_STATUS_BSTRAP_MCAST_ADDR                                 0x0076
133 #define PXENV_STATUS_BSTRAP_MISSING_LIST                               0x0077
134 #define PXENV_STATUS_BSTRAP_NO_RESPONSE                                0x0078
135 #define PXENV_STATUS_BSTRAP_FILE_TOO_BIG                               0x0079
136
137 /* Environment NBP errors (0x0080 to 0x008f) */
138
139 /* Reserved errors (0x0090 to 0x009f) */
140
141 /* Miscellaneous errors (0x00a0 to 0x00af) */
142 #define PXENV_STATUS_BINL_CANCELED_BY_KEYSTROKE                        0x00a0
143 #define PXENV_STATUS_BINL_NO_PXE_SERVER                                0x00a1
144 #define PXENV_STATUS_NOT_AVAILABLE_IN_PMODE                            0x00a2
145 #define PXENV_STATUS_NOT_AVAILABLE_IN_RMODE                            0x00a3
146
147 /* BUSD errors (0x00b0 to 0x00bf) */
148 #define PXENV_STATUS_BUSD_DEVICE_NOT_SUPPORTED                         0x00b0
149
150 /* Loader errors (0x00c0 to 0x00cf) */
151 #define PXENV_STATUS_LOADER_NO_FREE_BASE_MEMORY                        0x00c0
152 #define PXENV_STATUS_LOADER_NO_BC_ROMID                                0x00c1
153 #define PXENV_STATUS_LOADER_BAD_BC_ROMID                               0x00c2
154 #define PXENV_STATUS_LOADER_BAD_BC_RUNTIME_IMAGE                       0x00c3
155 #define PXENV_STATUS_LOADER_NO_UNDI_ROMID                              0x00c4
156 #define PXENV_STATUS_LOADER_BAD_UNDI_ROMID                             0x00c5
157 #define PXENV_STATUS_LOADER_BAD_UNDI_DRIVER_IMAGE                      0x00c6
158 #define PXENV_STATUS_LOADER_NO_PXE_STRUCT                              0x00c8
159 #define PXENV_STATUS_LOADER_NO_PXENV_STRUCT                            0x00c9
160 #define PXENV_STATUS_LOADER_UNDI_START                                 0x00ca
161 #define PXENV_STATUS_LOADER_BC_START                                   0x00cb
162
163 /** @} */
164
165 /**
166  * @defgroup posixerrors POSIX error codes
167  *
168  * The names and meanings (but not the values) of these error codes
169  * are defined by POSIX.  We choose to assign unique values which
170  * incorporate the closest equivalent PXE error code, so that code may
171  * simply use ENOMEM, rather than having to use the cumbersome
172  * (ENOMEM|PXENV_STATUS_OUT_OF_RESOURCES).
173  *
174  * @{
175  */
176
177 /** Operation completed successfully */
178 #define ENOERR                                ( PXENV_STATUS_SUCCESS | 0x0000 )
179
180 /** Arg list too long */
181 #define E2BIG                                ( PXENV_STATUS_BAD_FUNC | 0x0100 )
182
183 /** Permission denied */
184 #define EACCES                  ( PXENV_STATUS_TFTP_ACCESS_VIOLATION | 0x0200 )
185
186 /** Address in use */
187 #define EADDRINUSE                           ( PXENV_STATUS_UDP_OPEN | 0x0300 )
188
189 /** Address not available */
190 #define EADDRNOTAVAIL                        ( PXENV_STATUS_UDP_OPEN | 0x0400 )
191
192 /** Address family not supported */
193 #define EAFNOSUPPORT                      ( PXENV_STATUS_UNSUPPORTED | 0x0500 )
194
195 /** Resource temporarily unavailable */
196 #define EAGAIN                                ( PXENV_STATUS_FAILURE | 0x0600 )
197
198 /** Connection already in progress */
199 #define EALREADY                             ( PXENV_STATUS_UDP_OPEN | 0x0700 )
200
201 /** Bad file descriptor */
202 #define EBADF                              ( PXENV_STATUS_UDP_CLOSED | 0x0800 )
203
204 /** Bad message */
205 #define EBADMSG                               ( PXENV_STATUS_FAILURE | 0x0900 )
206
207 /** Resource busy */
208 #define EBUSY                        ( PXENV_STATUS_OUT_OF_RESOURCES | 0x0a00 )
209
210 /** Operation canceled */
211 #define ECANCELED          ( PXENV_STATUS_BINL_CANCELED_BY_KEYSTROKE | 0x0b00 )
212
213 /** No child processes */
214 #define ECHILD                    ( PXENV_STATUS_TFTP_FILE_NOT_FOUND | 0x0c00 )
215
216 /** Connection aborted */
217 #define ECONNABORTED ( PXENV_STATUS_TFTP_CANNOT_READ_FROM_CONNECTION | 0x0d00 )
218
219 /** Connection refused */
220 #define ECONNREFUSED      ( PXENV_STATUS_TFTP_CANNOT_OPEN_CONNECTION | 0x0e00 )
221
222 /** Connection reset */
223 #define ECONNRESET   ( PXENV_STATUS_TFTP_CANNOT_READ_FROM_CONNECTION | 0x0f00 )
224
225 /** Resource deadlock avoided */
226 #define EDEADLK                               ( PXENV_STATUS_FAILURE | 0x1000 )
227
228 /** Destination address required */
229 #define EDESTADDRREQ                         ( PXENV_STATUS_BAD_FUNC | 0x1100 )
230
231 /** Domain error */
232 #define EDOM                                  ( PXENV_STATUS_FAILURE | 0x1200 )
233
234 /** Reserved */
235 #define EDQUOT                                ( PXENV_STATUS_FAILURE | 0x1300 )
236
237 /** File exists */
238 #define EEXIST                                ( PXENV_STATUS_FAILURE | 0x1400 )
239
240 /** Bad address */
241 #define EFAULT                          ( PXENV_STATUS_MCOPY_PROBLEM | 0x1500 )
242
243 /** File too large */
244 #define EFBIG                           ( PXENV_STATUS_MCOPY_PROBLEM | 0x1600 )
245
246 /** Host is unreachable */
247 #define EHOSTUNREACH                      ( PXENV_STATUS_ARP_TIMEOUT | 0x1700 )
248
249 /** Identifier removed */
250 #define EIDRM                                 ( PXENV_STATUS_FAILURE | 0x1800 )
251
252 /** Illegal byte sequence */
253 #define EILSEQ                                ( PXENV_STATUS_FAILURE | 0x1900 )
254
255 /** Operation in progress */
256 #define EINPROGRESS                           ( PXENV_STATUS_FAILURE | 0x1a00 )
257
258 /** Interrupted function call */
259 #define EINTR                                 ( PXENV_STATUS_FAILURE | 0x1b00 )
260
261 /** Invalid argument */
262 #define EINVAL                               ( PXENV_STATUS_BAD_FUNC | 0x1c00 )
263
264 /** Input/output error */
265 #define EIO          ( PXENV_STATUS_TFTP_CANNOT_READ_FROM_CONNECTION | 0x1d00 )
266
267 /** Socket is connected */
268 #define EISCONN                              ( PXENV_STATUS_UDP_OPEN | 0x1e00 )
269
270 /** Is a directory */
271 #define EISDIR                                ( PXENV_STATUS_FAILURE | 0x1f00 )
272
273 /** Too many levels of symbolic links */
274 #define ELOOP                                 ( PXENV_STATUS_FAILURE | 0x2000 )
275
276 /** Too many open files */
277 #define EMFILE                       ( PXENV_STATUS_OUT_OF_RESOURCES | 0x2100 )
278
279 /** Too many links */
280 #define EMLINK                                ( PXENV_STATUS_FAILURE | 0x2200 )
281
282 /** Inappropriate message buffer length */
283 #define EMSGSIZE                             ( PXENV_STATUS_BAD_FUNC | 0x2300 )
284
285 /** Reserved */
286 #define EMULTIHOP                             ( PXENV_STATUS_FAILURE | 0x2400 )
287
288 /** Filename too long */
289 #define ENAMETOOLONG                          ( PXENV_STATUS_FAILURE | 0x2500 )
290
291 /** Network is down */
292 #define ENETDOWN                          ( PXENV_STATUS_ARP_TIMEOUT | 0x2600 )
293
294 /** Connection aborted by network */
295 #define ENETRESET                             ( PXENV_STATUS_FAILURE | 0x2700 )
296
297 /** Network unreachable */
298 #define ENETUNREACH                       ( PXENV_STATUS_ARP_TIMEOUT | 0x2800 )
299
300 /** Too many open files in system */
301 #define ENFILE                       ( PXENV_STATUS_OUT_OF_RESOURCES | 0x2900 )
302
303 /** No buffer space available */
304 #define ENOBUFS                      ( PXENV_STATUS_OUT_OF_RESOURCES | 0x2a00 )
305
306 /** No message is available on the STREAM head read queue */
307 #define ENODATA                               ( PXENV_STATUS_FAILURE | 0x2b00 )
308
309 /** No such device */
310 #define ENODEV                    ( PXENV_STATUS_TFTP_FILE_NOT_FOUND | 0x2c00 )
311
312 /** No such file or directory */
313 #define ENOENT                    ( PXENV_STATUS_TFTP_FILE_NOT_FOUND | 0x2d00 )
314
315 /** Exec format error */
316 #define ENOEXEC                               ( PXENV_STATUS_FAILURE | 0x2e00 )
317
318 /** No locks available */
319 #define ENOLCK                                ( PXENV_STATUS_FAILURE | 0x2f00 )
320
321 /** Reserved */
322 #define ENOLINK                               ( PXENV_STATUS_FAILURE | 0x3000 )
323
324 /** Not enough space */
325 #define ENOMEM                       ( PXENV_STATUS_OUT_OF_RESOURCES | 0x3100 )
326
327 /** No message of the desired type */
328 #define ENOMSG                                ( PXENV_STATUS_FAILURE | 0x3200 )
329
330 /** Protocol not available */
331 #define ENOPROTOOPT                       ( PXENV_STATUS_UNSUPPORTED | 0x3300 )
332
333 /** No space left on device */
334 #define ENOSPC                       ( PXENV_STATUS_OUT_OF_RESOURCES | 0x3400 )
335
336 /** No STREAM resources */
337 #define ENOSR                        ( PXENV_STATUS_OUT_OF_RESOURCES | 0x3500 )
338
339 /** Not a STREAM */
340 #define ENOSTR                                ( PXENV_STATUS_FAILURE | 0x3600 )
341
342 /** Function not implemented */
343 #define ENOSYS                            ( PXENV_STATUS_UNSUPPORTED | 0x3700 )
344
345 /** The socket is not connected */
346 #define ENOTCONN                              ( PXENV_STATUS_FAILURE | 0x3800 )
347
348 /** Not a directory */
349 #define ENOTDIR                               ( PXENV_STATUS_FAILURE | 0x3900 )
350
351 /** Directory not empty */
352 #define ENOTEMPTY                             ( PXENV_STATUS_FAILURE | 0x3a00 )
353
354 /** Not a socket */
355 #define ENOTSOCK                              ( PXENV_STATUS_FAILURE | 0x3b00 )
356
357 /** Not supported */
358 #define ENOTSUP                           ( PXENV_STATUS_UNSUPPORTED | 0x3c00 )
359
360 /** Inappropriate I/O control operation */
361 #define ENOTTY                                ( PXENV_STATUS_FAILURE | 0x3d00 )
362
363 /** No such device or address */
364 #define ENXIO                     ( PXENV_STATUS_TFTP_FILE_NOT_FOUND | 0x3e00 )
365
366 /** Operation not supported on socket */
367 #define EOPNOTSUPP                        ( PXENV_STATUS_UNSUPPORTED | 0x3f00 )
368
369 /** Value too large to be stored in data type */
370 #define EOVERFLOW                             ( PXENV_STATUS_FAILURE | 0x4000 )
371
372 /** Operation not permitted */
373 #define EPERM                   ( PXENV_STATUS_TFTP_ACCESS_VIOLATION | 0x4100 )
374
375 /** Broken pipe */
376 #define EPIPE                                 ( PXENV_STATUS_FAILURE | 0x4200 )
377
378 /** Protocol error */
379 #define EPROTO                                ( PXENV_STATUS_FAILURE | 0x4300 )
380
381 /** Protocol not supported */
382 #define EPROTONOSUPPORT                   ( PXENV_STATUS_UNSUPPORTED | 0x4400 )
383
384 /** Protocol wrong type for socket */
385 #define EPROTOTYPE                            ( PXENV_STATUS_FAILURE | 0x4500 )
386
387 /** Result too large */
388 #define ERANGE                                ( PXENV_STATUS_FAILURE | 0x4600 )
389
390 /** Read-only file system */
391 #define EROFS                                 ( PXENV_STATUS_FAILURE | 0x4700 )
392
393 /** Invalid seek */
394 #define ESPIPE                                ( PXENV_STATUS_FAILURE | 0x4800 )
395
396 /** No such process */
397 #define ESRCH                     ( PXENV_STATUS_TFTP_FILE_NOT_FOUND | 0x4900 )
398
399 /** Stale file handle */
400 #define ESTALE                                ( PXENV_STATUS_FAILURE | 0x4a00 )
401
402 /** STREAM ioctl() timeout */
403 #define ETIME                                 ( PXENV_STATUS_FAILURE | 0x4b00 )
404
405 /** Operation timed out */
406 #define ETIMEDOUT                   ( PXENV_STATUS_TFTP_READ_TIMEOUT | 0x4c00 )
407
408 /** Text file busy */
409 #define ETXTBSY                               ( PXENV_STATUS_FAILURE | 0x4d00 )
410
411 /** Operation would block */
412 #define EWOULDBLOCK                           ( PXENV_STATUS_FAILURE | 0x4e00 )
413
414 /** Improper link */
415 #define EXDEV                                 ( PXENV_STATUS_FAILURE | 0x4f00 )
416
417 /** @} */
418
419 /**
420  * @defgroup gpxeerrors gPXE-specific error codes
421  *
422  * The names, meanings, and values of these error codes are defined by
423  * this file.  A gPXE-specific error code should be defined only where
424  * the POSIX error code does not identify the error with sufficient
425  * specificity.  For example, ENOMEM probably encapsulates everything
426  * that needs to be known about the error (we've run out of heap
427  * space), while EACCES does not (did the server refuse the
428  * connection, or did we decide that the server failed to provide a
429  * valid SSL/TLS certificate?).
430  *
431  * @{
432  */
433
434 /** @} */
435
436 extern int errno;
437
438 #endif /* ERRNO_H */