iPXE
nbi.c
Go to the documentation of this file.
1 #include <errno.h>
2 #include <assert.h>
3 #include <realmode.h>
4 #include <memsizes.h>
5 #include <basemem_packet.h>
6 #include <ipxe/uaccess.h>
7 #include <ipxe/segment.h>
8 #include <ipxe/init.h>
9 #include <ipxe/netdevice.h>
10 #include <ipxe/fakedhcp.h>
11 #include <ipxe/image.h>
12 #include <ipxe/features.h>
13 #include <ipxe/version.h>
14 
15 /** @file
16  *
17  * NBI image format.
18  *
19  * The Net Boot Image format is defined by the "Draft Net Boot Image
20  * Proposal 0.3" by Jamie Honan, Gero Kuhlmann and Ken Yap. It is now
21  * considered to be a legacy format, but it still included because a
22  * large amount of software (e.g. nymph, LTSP) makes use of NBI files.
23  *
24  * Etherboot does not implement the INT 78 callback interface
25  * described by the NBI specification. For a callback interface on
26  * x86 architecture, use PXE.
27  *
28  */
29 
31 
32 /**
33  * An NBI image header
34  *
35  * Note that the length field uses a peculiar encoding; use the
36  * NBI_LENGTH() macro to decode the actual header length.
37  *
38  */
39 struct imgheader {
40  unsigned long magic; /**< Magic number (NBI_MAGIC) */
41  union {
42  unsigned char length; /**< Nibble-coded header length */
43  unsigned long flags; /**< Image flags */
44  };
45  segoff_t location; /**< 16-bit seg:off header location */
46  union {
47  segoff_t segoff; /**< 16-bit seg:off entry point */
48  unsigned long linear; /**< 32-bit entry point */
49  } execaddr;
50 } __attribute__ (( packed ));
51 
52 /** NBI magic number */
53 #define NBI_MAGIC 0x1B031336UL
54 
55 /* Interpretation of the "length" fields */
56 #define NBI_NONVENDOR_LENGTH(len) ( ( (len) & 0x0f ) << 2 )
57 #define NBI_VENDOR_LENGTH(len) ( ( (len) & 0xf0 ) >> 2 )
58 #define NBI_LENGTH(len) ( NBI_NONVENDOR_LENGTH(len) + NBI_VENDOR_LENGTH(len) )
59 
60 /* Interpretation of the "flags" fields */
61 #define NBI_PROGRAM_RETURNS(flags) ( (flags) & ( 1 << 8 ) )
62 #define NBI_LINEAR_EXEC_ADDR(flags) ( (flags) & ( 1 << 31 ) )
63 
64 /** NBI header length */
65 #define NBI_HEADER_LENGTH 512
66 
67 /**
68  * An NBI segment header
69  *
70  * Note that the length field uses a peculiar encoding; use the
71  * NBI_LENGTH() macro to decode the actual header length.
72  *
73  */
74 struct segheader {
75  unsigned char length; /**< Nibble-coded header length */
76  unsigned char vendortag; /**< Vendor-defined private tag */
77  unsigned char reserved;
78  unsigned char flags; /**< Segment flags */
79  unsigned long loadaddr; /**< Load address */
80  unsigned long imglength; /**< Segment length in NBI file */
81  unsigned long memlength; /**< Segment length in memory */
82 };
83 
84 /* Interpretation of the "flags" fields */
85 #define NBI_LOADADDR_FLAGS(flags) ( (flags) & 0x03 )
86 #define NBI_LOADADDR_ABS 0x00
87 #define NBI_LOADADDR_AFTER 0x01
88 #define NBI_LOADADDR_END 0x02
89 #define NBI_LOADADDR_BEFORE 0x03
90 #define NBI_LAST_SEGHEADER(flags) ( (flags) & ( 1 << 2 ) )
91 
92 /* Define a type for passing info to a loaded program */
93 struct ebinfo {
94  uint8_t major, minor; /* Version */
95  uint16_t flags; /* Bit flags */
96 };
97 
98 /**
99  * Prepare a segment for an NBI image
100  *
101  * @v image NBI image
102  * @v offset Offset within NBI image
103  * @v filesz Length of initialised-data portion of the segment
104  * @v memsz Total length of the segment
105  * @v src Source for initialised data
106  * @ret rc Return status code
107  */
108 static int nbi_prepare_segment ( struct image *image, size_t offset __unused,
109  userptr_t dest, size_t filesz, size_t memsz ){
110  int rc;
111 
112  if ( ( rc = prep_segment ( dest, filesz, memsz ) ) != 0 ) {
113  DBGC ( image, "NBI %p could not prepare segment: %s\n",
114  image, strerror ( rc ) );
115  return rc;
116  }
117 
118  return 0;
119 }
120 
121 /**
122  * Load a segment for an NBI image
123  *
124  * @v image NBI image
125  * @v offset Offset within NBI image
126  * @v filesz Length of initialised-data portion of the segment
127  * @v memsz Total length of the segment
128  * @v src Source for initialised data
129  * @ret rc Return status code
130  */
131 static int nbi_load_segment ( struct image *image, size_t offset,
132  userptr_t dest, size_t filesz,
133  size_t memsz __unused ) {
134  memcpy_user ( dest, 0, image->data, offset, filesz );
135  return 0;
136 }
137 
138 /**
139  * Process segments of an NBI image
140  *
141  * @v image NBI image
142  * @v imgheader Image header information
143  * @v process Function to call for each segment
144  * @ret rc Return status code
145  */
146 static int nbi_process_segments ( struct image *image,
147  struct imgheader *imgheader,
148  int ( * process ) ( struct image *image,
149  size_t offset,
150  userptr_t dest,
151  size_t filesz,
152  size_t memsz ) ) {
153  struct segheader sh;
154  size_t offset = 0;
155  size_t sh_off;
156  userptr_t dest;
157  size_t filesz;
158  size_t memsz;
159  int rc;
160 
161  /* Copy image header to target location */
164  filesz = memsz = NBI_HEADER_LENGTH;
165  if ( ( rc = process ( image, offset, dest, filesz, memsz ) ) != 0 )
166  return rc;
167  offset += filesz;
168 
169  /* Process segments in turn */
170  sh_off = NBI_LENGTH ( imgheader->length );
171  do {
172  /* Read segment header */
173  copy_from_user ( &sh, image->data, sh_off, sizeof ( sh ) );
174  if ( sh.length == 0 ) {
175  /* Avoid infinite loop? */
176  DBGC ( image, "NBI %p invalid segheader length 0\n",
177  image );
178  return -ENOEXEC;
179  }
180 
181  /* Calculate segment load address */
182  switch ( NBI_LOADADDR_FLAGS ( sh.flags ) ) {
183  case NBI_LOADADDR_ABS:
184  dest = phys_to_user ( sh.loadaddr );
185  break;
186  case NBI_LOADADDR_AFTER:
187  dest = userptr_add ( dest, memsz + sh.loadaddr );
188  break;
189  case NBI_LOADADDR_BEFORE:
190  dest = userptr_add ( dest, -sh.loadaddr );
191  break;
192  case NBI_LOADADDR_END:
193  /* Not correct according to the spec, but
194  * maintains backwards compatibility with
195  * previous versions of Etherboot.
196  */
197  dest = phys_to_user ( ( extmemsize() + 1024 ) * 1024
198  - sh.loadaddr );
199  break;
200  default:
201  /* Cannot be reached */
202  assert ( 0 );
203  }
204 
205  /* Process this segment */
206  filesz = sh.imglength;
207  memsz = sh.memlength;
208  if ( ( offset + filesz ) > image->len ) {
209  DBGC ( image, "NBI %p segment outside file\n", image );
210  return -ENOEXEC;
211  }
212  if ( ( rc = process ( image, offset, dest,
213  filesz, memsz ) ) != 0 ) {
214  return rc;
215  }
216  offset += filesz;
217 
218  /* Next segheader */
219  sh_off += NBI_LENGTH ( sh.length );
220  if ( sh_off >= NBI_HEADER_LENGTH ) {
221  DBGC ( image, "NBI %p header overflow\n", image );
222  return -ENOEXEC;
223  }
224 
225  } while ( ! NBI_LAST_SEGHEADER ( sh.flags ) );
226 
227  if ( offset != image->len ) {
228  DBGC ( image, "NBI %p length wrong (file %zd, metadata %zd)\n",
229  image, image->len, offset );
230  return -ENOEXEC;
231  }
232 
233  return 0;
234 }
235 
236 /**
237  * Boot a 16-bit NBI image
238  *
239  * @v imgheader Image header information
240  * @ret rc Return status code, if image returns
241  */
242 static int nbi_boot16 ( struct image *image, struct imgheader *imgheader ) {
243  int discard_D, discard_S, discard_b;
244  int32_t rc;
245 
246  DBGC ( image, "NBI %p executing 16-bit image at %04x:%04x\n", image,
249 
251  REAL_CODE ( "pushl %%ebp\n\t" /* gcc bug */
252  "pushw %%ds\n\t" /* far pointer to bootp data */
253  "pushw %%bx\n\t"
254  "pushl %%esi\n\t" /* location */
255  "pushw %%cs\n\t" /* lcall execaddr */
256  "call 1f\n\t"
257  "jmp 2f\n\t"
258  "\n1:\n\t"
259  "pushl %%edi\n\t"
260  "lret\n\t"
261  "\n2:\n\t"
262  "addw $8,%%sp\n\t" /* clean up stack */
263  "popl %%ebp\n\t" /* gcc bug */ )
264  : "=a" ( rc ), "=D" ( discard_D ), "=S" ( discard_S ),
265  "=b" ( discard_b )
266  : "D" ( imgheader->execaddr.segoff ),
267  "S" ( imgheader->location ),
268  "b" ( __from_data16 ( basemem_packet ) )
269  : "ecx", "edx" );
270 
271  return rc;
272 }
273 
274 /**
275  * Boot a 32-bit NBI image
276  *
277  * @v imgheader Image header information
278  * @ret rc Return status code, if image returns
279  */
280 static int nbi_boot32 ( struct image *image, struct imgheader *imgheader ) {
281  struct ebinfo loaderinfo = {
283  0
284  };
285  int discard_D, discard_S, discard_b;
286  int32_t rc;
287 
288  DBGC ( image, "NBI %p executing 32-bit image at %lx\n",
290 
291  /* Jump to OS with flat physical addressing */
293  PHYS_CODE ( "pushl %%ebp\n\t" /* gcc bug */
294  "pushl %%ebx\n\t" /* bootp data */
295  "pushl %%esi\n\t" /* imgheader */
296  "pushl %%eax\n\t" /* loaderinfo */
297  "call *%%edi\n\t"
298  "addl $12, %%esp\n\t" /* clean up stack */
299  "popl %%ebp\n\t" /* gcc bug */ )
300  : "=a" ( rc ), "=D" ( discard_D ), "=S" ( discard_S ),
301  "=b" ( discard_b )
302  : "D" ( imgheader->execaddr.linear ),
303  "S" ( ( imgheader->location.segment << 4 ) +
305  "b" ( virt_to_phys ( basemem_packet ) ),
306  "a" ( virt_to_phys ( &loaderinfo ) )
307  : "ecx", "edx", "memory" );
308 
309  return rc;
310 }
311 
312 /**
313  * Prepare DHCP parameter block for NBI image
314  *
315  * @v image NBI image
316  * @ret rc Return status code
317  */
318 static int nbi_prepare_dhcp ( struct image *image ) {
319  struct net_device *boot_netdev;
320  int rc;
321 
322  boot_netdev = last_opened_netdev();
323  if ( ! boot_netdev ) {
324  DBGC ( image, "NBI %p could not identify a network device\n",
325  image );
326  return -ENODEV;
327  }
328 
329  if ( ( rc = create_fakedhcpack ( boot_netdev, basemem_packet,
330  sizeof ( basemem_packet ) ) ) != 0 ) {
331  DBGC ( image, "NBI %p failed to build DHCP packet\n", image );
332  return rc;
333  }
334 
335  return 0;
336 }
337 
338 /**
339  * Execute a loaded NBI image
340  *
341  * @v image NBI image
342  * @ret rc Return status code
343  */
344 static int nbi_exec ( struct image *image ) {
345  struct imgheader imgheader;
346  int may_return;
347  int rc;
348 
349  /* Retrieve image header */
350  copy_from_user ( &imgheader, image->data, 0, sizeof ( imgheader ) );
351 
352  DBGC ( image, "NBI %p placing header at %hx:%hx\n", image,
354 
355  /* NBI files can have overlaps between segments; the bss of
356  * one segment may overlap the initialised data of another. I
357  * assume this is a design flaw, but there are images out
358  * there that we need to work with. We therefore do two
359  * passes: first to initialise the segments, then to copy the
360  * data. This avoids zeroing out already-copied data.
361  */
362  if ( ( rc = nbi_process_segments ( image, &imgheader,
363  nbi_prepare_segment ) ) != 0 )
364  return rc;
365  if ( ( rc = nbi_process_segments ( image, &imgheader,
366  nbi_load_segment ) ) != 0 )
367  return rc;
368 
369  /* Prepare DHCP option block */
370  if ( ( rc = nbi_prepare_dhcp ( image ) ) != 0 )
371  return rc;
372 
373  /* Shut down now if NBI image will not return */
374  may_return = NBI_PROGRAM_RETURNS ( imgheader.flags );
375  if ( ! may_return )
376  shutdown_boot();
377 
378  /* Execute NBI image */
380  rc = nbi_boot32 ( image, &imgheader );
381  } else {
382  rc = nbi_boot16 ( image, &imgheader );
383  }
384 
385  if ( ! may_return ) {
386  /* Cannot continue after shutdown() called */
387  DBGC ( image, "NBI %p returned %d from non-returnable image\n",
388  image, rc );
389  while ( 1 ) {}
390  }
391 
392  DBGC ( image, "NBI %p returned %d\n", image, rc );
393 
394  return rc;
395 }
396 
397 /**
398  * Probe NBI image
399  *
400  * @v image NBI image
401  * @ret rc Return status code
402  */
403 static int nbi_probe ( struct image *image ) {
404  struct imgheader imgheader;
405 
406  /* If we don't have enough data give up */
407  if ( image->len < NBI_HEADER_LENGTH ) {
408  DBGC ( image, "NBI %p too short for an NBI image\n", image );
409  return -ENOEXEC;
410  }
411 
412  /* Check image header */
413  copy_from_user ( &imgheader, image->data, 0, sizeof ( imgheader ) );
414  if ( imgheader.magic != NBI_MAGIC ) {
415  DBGC ( image, "NBI %p has no NBI signature\n", image );
416  return -ENOEXEC;
417  }
418 
419  return 0;
420 }
421 
422 /** NBI image type */
423 struct image_type nbi_image_type __image_type ( PROBE_NORMAL ) = {
424  .name = "NBI",
425  .probe = nbi_probe,
426  .exec = nbi_exec,
427 };
union imgheader::@428 execaddr
uint16_t segment
Definition: registers.h:193
A process.
Definition: process.h:17
#define __attribute__(x)
Definition: compiler.h:10
#define PHYS_CODE(asm_code_str)
Definition: librm.h:279
unsigned long magic
Magic number (NBI_MAGIC)
Definition: nbi.c:40
struct arbelprm_rc_send_wqe rc
Definition: arbel.h:14
unsigned short uint16_t
Definition: stdint.h:11
userptr_t data
Raw file image.
Definition: image.h:41
#define NBI_LOADADDR_AFTER
Definition: nbi.c:87
An NBI image header.
Definition: nbi.c:39
#define NBI_LOADADDR_ABS
Definition: nbi.c:86
uint8_t major
Definition: nbi.c:94
Error codes.
static int nbi_boot32(struct image *image, struct imgheader *imgheader)
Boot a 32-bit NBI image.
Definition: nbi.c:280
void * discard_S
Definition: bigint.h:57
#define ENOEXEC
Exec format error.
Definition: errno.h:519
static __always_inline void copy_from_user(void *dest, userptr_t src, off_t src_off, size_t len)
Copy data from user buffer.
Definition: uaccess.h:337
unsigned long memlength
Segment length in memory.
Definition: nbi.c:81
Definition: nbi.c:93
int create_fakedhcpack(struct net_device *netdev, void *data, size_t max_len)
Create fake DHCPACK packet.
Definition: fakedhcp.c:136
#define DBGC(...)
Definition: compiler.h:505
An executable image type.
Definition: image.h:76
segoff_t segoff
16-bit seg:off entry point
Definition: nbi.c:47
#define PROBE_NORMAL
Normal image probe priority.
Definition: image.h:129
userptr_t phys_to_user(unsigned long phys_addr)
Convert physical address to user pointer.
#define DHCP_EB_FEATURE_NBI
NBI format.
Definition: features.h:48
uint8_t minor
Definition: nbi.c:94
An executable image.
Definition: image.h:24
#define FEATURE_IMAGE
Image formats.
Definition: features.h:22
unsigned char reserved
Definition: nbi.c:77
#define NBI_LOADADDR_FLAGS(flags)
Definition: nbi.c:85
unsigned long loadaddr
Load address.
Definition: nbi.c:79
static __always_inline unsigned long virt_to_phys(volatile const void *addr)
Convert virtual address to a physical address.
Definition: uaccess.h:287
Access to external ("user") memory.
#define NBI_LAST_SEGHEADER(flags)
Definition: nbi.c:90
#define NBI_LOADADDR_BEFORE
Definition: nbi.c:89
char * name
Name of this image type.
Definition: image.h:78
unsigned char vendortag
Vendor-defined private tag.
Definition: nbi.c:76
Executable image segments.
userptr_t userptr_add(userptr_t userptr, off_t offset)
Add offset to user pointer.
#define NBI_HEADER_LENGTH
NBI header length.
Definition: nbi.c:65
static int nbi_boot16(struct image *image, struct imgheader *imgheader)
Boot a 16-bit NBI image.
Definition: nbi.c:242
Assertions.
assert((readw(&hdr->flags) &(GTF_reading|GTF_writing))==0)
int prep_segment(userptr_t segment, size_t filesz, size_t memsz)
Prepare segment for loading.
Definition: segment.c:60
Executable images.
#define NBI_PROGRAM_RETURNS(flags)
Definition: nbi.c:61
static int nbi_prepare_dhcp(struct image *image)
Prepare DHCP parameter block for NBI image.
Definition: nbi.c:318
unsigned int extmemsize(void)
Get size of extended memory.
Definition: memmap.c:156
#define NBI_LINEAR_EXEC_ADDR(flags)
Definition: nbi.c:62
static int nbi_probe(struct image *image)
Probe NBI image.
Definition: nbi.c:403
static userptr_t size_t offset
Offset of the first segment within the content.
Definition: deflate.h:259
struct net_device * last_opened_netdev(void)
Get most recently opened network device.
Definition: netdevice.c:973
Feature list.
uint16_t offset
Definition: registers.h:192
unsigned char flags
Segment flags.
Definition: nbi.c:78
unsigned long imglength
Segment length in NBI file.
Definition: nbi.c:80
static void * dest
Definition: strings.h:176
An NBI segment header.
Definition: nbi.c:74
#define basemem_packet
char * strerror(int errno)
Retrieve string representation of error number.
Definition: strerror.c:78
size_t len
Length of raw file image.
Definition: image.h:43
segoff_t location
16-bit seg:off header location
Definition: nbi.c:45
#define NBI_LENGTH(len)
Definition: nbi.c:58
static int nbi_prepare_segment(struct image *image, size_t offset __unused, userptr_t dest, size_t filesz, size_t memsz)
Prepare a segment for an NBI image.
Definition: nbi.c:108
A network device.
Definition: netdevice.h:348
#define ENODEV
No such device.
Definition: errno.h:509
unsigned char uint8_t
Definition: stdint.h:10
void * discard_D
Definition: bigint.h:29
Version number.
__asm__ __volatile__("\n1:\n\t" "movb -1(%2,%1), %%al\n\t" "stosb\n\t" "loop 1b\n\t" "xorl %%eax, %%eax\n\t" "mov %3, %1\n\t" "rep stosb\n\t" :"=&D"(discard_D), "=&c"(discard_c) :"r"(data), "g"(pad_len), "0"(value0), "1"(len) :"eax")
#define NBI_LOADADDR_END
Definition: nbi.c:88
Network device management.
#define __unused
Declare a variable or data structure as unused.
Definition: compiler.h:573
const int product_major_version
Product major version.
Definition: version.c:63
__asm__(".section \".rodata\", \"a\", " PROGBITS "\n\t" "\nprivate_key_data:\n\t" ".size private_key_data, ( . - private_key_data )\n\t" ".equ private_key_len, ( . - private_key_data )\n\t" ".previous\n\t")
signed int int32_t
Definition: stdint.h:17
unsigned long flags
Image flags.
Definition: nbi.c:43
unsigned long linear
32-bit entry point
Definition: nbi.c:48
static int nbi_load_segment(struct image *image, size_t offset, userptr_t dest, size_t filesz, size_t memsz __unused)
Load a segment for an NBI image.
Definition: nbi.c:131
unsigned char length
Nibble-coded header length.
Definition: nbi.c:42
#define __from_data16(pointer)
Definition: libkir.h:22
static int nbi_exec(struct image *image)
Execute a loaded NBI image.
Definition: nbi.c:344
FEATURE(FEATURE_IMAGE, "NBI", DHCP_EB_FEATURE_NBI, 1)
static __always_inline userptr_t real_to_user(unsigned int segment, unsigned int offset)
Convert segment:offset address to user buffer.
Definition: realmode.h:75
unsigned char length
Nibble-coded header length.
Definition: nbi.c:75
static int nbi_process_segments(struct image *image, struct imgheader *imgheader, int(*process)(struct image *image, size_t offset, userptr_t dest, size_t filesz, size_t memsz))
Process segments of an NBI image.
Definition: nbi.c:146
uint16_t flags
Definition: nbi.c:95
static void shutdown_boot(void)
Shut down system for OS boot.
Definition: init.h:76
#define REAL_CODE(asm_code_str)
Definition: libkir.h:226
const int product_minor_version
Product minor version.
Definition: version.c:66
struct image_type nbi_image_type __image_type(PROBE_NORMAL)
NBI image type.
Fake DHCP packets.
void memcpy_user(userptr_t dest, off_t dest_off, userptr_t src, off_t src_off, size_t len)
Copy data between user buffers.
unsigned long userptr_t
A pointer to a user buffer.
Definition: uaccess.h:33
#define NBI_MAGIC
NBI magic number.
Definition: nbi.c:53