iPXE
nbi.c
Go to the documentation of this file.
00001 #include <errno.h>
00002 #include <assert.h>
00003 #include <realmode.h>
00004 #include <memsizes.h>
00005 #include <basemem_packet.h>
00006 #include <ipxe/uaccess.h>
00007 #include <ipxe/segment.h>
00008 #include <ipxe/init.h>
00009 #include <ipxe/netdevice.h>
00010 #include <ipxe/fakedhcp.h>
00011 #include <ipxe/image.h>
00012 #include <ipxe/features.h>
00013 #include <ipxe/version.h>
00014 
00015 /** @file
00016  *
00017  * NBI image format.
00018  *
00019  * The Net Boot Image format is defined by the "Draft Net Boot Image
00020  * Proposal 0.3" by Jamie Honan, Gero Kuhlmann and Ken Yap.  It is now
00021  * considered to be a legacy format, but it still included because a
00022  * large amount of software (e.g. nymph, LTSP) makes use of NBI files.
00023  *
00024  * Etherboot does not implement the INT 78 callback interface
00025  * described by the NBI specification.  For a callback interface on
00026  * x86 architecture, use PXE.
00027  *
00028  */
00029 
00030 FEATURE ( FEATURE_IMAGE, "NBI", DHCP_EB_FEATURE_NBI, 1 );
00031 
00032 /**
00033  * An NBI image header
00034  *
00035  * Note that the length field uses a peculiar encoding; use the
00036  * NBI_LENGTH() macro to decode the actual header length.
00037  *
00038  */
00039 struct imgheader {
00040         unsigned long magic;            /**< Magic number (NBI_MAGIC) */
00041         union {
00042                 unsigned char length;   /**< Nibble-coded header length */
00043                 unsigned long flags;    /**< Image flags */
00044         };
00045         segoff_t location;              /**< 16-bit seg:off header location */
00046         union {
00047                 segoff_t segoff;        /**< 16-bit seg:off entry point */
00048                 unsigned long linear;   /**< 32-bit entry point */
00049         } execaddr;
00050 } __attribute__ (( packed ));
00051 
00052 /** NBI magic number */
00053 #define NBI_MAGIC 0x1B031336UL
00054 
00055 /* Interpretation of the "length" fields */
00056 #define NBI_NONVENDOR_LENGTH(len)       ( ( (len) & 0x0f ) << 2 )
00057 #define NBI_VENDOR_LENGTH(len)          ( ( (len) & 0xf0 ) >> 2 )
00058 #define NBI_LENGTH(len) ( NBI_NONVENDOR_LENGTH(len) + NBI_VENDOR_LENGTH(len) )
00059 
00060 /* Interpretation of the "flags" fields */
00061 #define NBI_PROGRAM_RETURNS(flags)      ( (flags) & ( 1 << 8 ) )
00062 #define NBI_LINEAR_EXEC_ADDR(flags)     ( (flags) & ( 1 << 31 ) )
00063 
00064 /** NBI header length */
00065 #define NBI_HEADER_LENGTH       512
00066 
00067 /**
00068  * An NBI segment header
00069  *
00070  * Note that the length field uses a peculiar encoding; use the
00071  * NBI_LENGTH() macro to decode the actual header length.
00072  *
00073  */
00074 struct segheader {
00075         unsigned char length;           /**< Nibble-coded header length */
00076         unsigned char vendortag;        /**< Vendor-defined private tag */
00077         unsigned char reserved;
00078         unsigned char flags;            /**< Segment flags */
00079         unsigned long loadaddr;         /**< Load address */
00080         unsigned long imglength;        /**< Segment length in NBI file */
00081         unsigned long memlength;        /**< Segment length in memory */
00082 };
00083 
00084 /* Interpretation of the "flags" fields */
00085 #define NBI_LOADADDR_FLAGS(flags)       ( (flags) & 0x03 )
00086 #define NBI_LOADADDR_ABS                0x00
00087 #define NBI_LOADADDR_AFTER              0x01
00088 #define NBI_LOADADDR_END                0x02
00089 #define NBI_LOADADDR_BEFORE             0x03
00090 #define NBI_LAST_SEGHEADER(flags)       ( (flags) & ( 1 << 2 ) )
00091 
00092 /* Define a type for passing info to a loaded program */
00093 struct ebinfo {
00094         uint8_t  major, minor;  /* Version */
00095         uint16_t flags;         /* Bit flags */
00096 };
00097 
00098 /**
00099  * Prepare a segment for an NBI image
00100  *
00101  * @v image             NBI image
00102  * @v offset            Offset within NBI image
00103  * @v filesz            Length of initialised-data portion of the segment
00104  * @v memsz             Total length of the segment
00105  * @v src               Source for initialised data
00106  * @ret rc              Return status code
00107  */
00108 static int nbi_prepare_segment ( struct image *image, size_t offset __unused,
00109                                  userptr_t dest, size_t filesz, size_t memsz ){
00110         int rc;
00111 
00112         if ( ( rc = prep_segment ( dest, filesz, memsz ) ) != 0 ) {
00113                 DBGC ( image, "NBI %p could not prepare segment: %s\n",
00114                        image, strerror ( rc ) );
00115                 return rc;
00116         }
00117 
00118         return 0;
00119 }
00120 
00121 /**
00122  * Load a segment for an NBI image
00123  *
00124  * @v image             NBI image
00125  * @v offset            Offset within NBI image
00126  * @v filesz            Length of initialised-data portion of the segment
00127  * @v memsz             Total length of the segment
00128  * @v src               Source for initialised data
00129  * @ret rc              Return status code
00130  */
00131 static int nbi_load_segment ( struct image *image, size_t offset,
00132                               userptr_t dest, size_t filesz,
00133                               size_t memsz __unused ) {
00134         memcpy_user ( dest, 0, image->data, offset, filesz );
00135         return 0;
00136 }
00137 
00138 /**
00139  * Process segments of an NBI image
00140  *
00141  * @v image             NBI image
00142  * @v imgheader         Image header information
00143  * @v process           Function to call for each segment
00144  * @ret rc              Return status code
00145  */
00146 static int nbi_process_segments ( struct image *image,
00147                                   struct imgheader *imgheader,
00148                                   int ( * process ) ( struct image *image,
00149                                                       size_t offset,
00150                                                       userptr_t dest,
00151                                                       size_t filesz,
00152                                                       size_t memsz ) ) {
00153         struct segheader sh;
00154         size_t offset = 0;
00155         size_t sh_off;
00156         userptr_t dest;
00157         size_t filesz;
00158         size_t memsz;
00159         int rc;
00160         
00161         /* Copy image header to target location */
00162         dest = real_to_user ( imgheader->location.segment,
00163                               imgheader->location.offset );
00164         filesz = memsz = NBI_HEADER_LENGTH;
00165         if ( ( rc = process ( image, offset, dest, filesz, memsz ) ) != 0 )
00166                 return rc;
00167         offset += filesz;
00168 
00169         /* Process segments in turn */
00170         sh_off = NBI_LENGTH ( imgheader->length );
00171         do {
00172                 /* Read segment header */
00173                 copy_from_user ( &sh, image->data, sh_off, sizeof ( sh ) );
00174                 if ( sh.length == 0 ) {
00175                         /* Avoid infinite loop? */
00176                         DBGC ( image, "NBI %p invalid segheader length 0\n",
00177                                image );
00178                         return -ENOEXEC;
00179                 }
00180                 
00181                 /* Calculate segment load address */
00182                 switch ( NBI_LOADADDR_FLAGS ( sh.flags ) ) {
00183                 case NBI_LOADADDR_ABS:
00184                         dest = phys_to_user ( sh.loadaddr );
00185                         break;
00186                 case NBI_LOADADDR_AFTER:
00187                         dest = userptr_add ( dest, memsz + sh.loadaddr );
00188                         break;
00189                 case NBI_LOADADDR_BEFORE:
00190                         dest = userptr_add ( dest, -sh.loadaddr );
00191                         break;
00192                 case NBI_LOADADDR_END:
00193                         /* Not correct according to the spec, but
00194                          * maintains backwards compatibility with
00195                          * previous versions of Etherboot.
00196                          */
00197                         dest = phys_to_user ( ( extmemsize() + 1024 ) * 1024
00198                                               - sh.loadaddr );
00199                         break;
00200                 default:
00201                         /* Cannot be reached */
00202                         assert ( 0 );
00203                 }
00204 
00205                 /* Process this segment */
00206                 filesz = sh.imglength;
00207                 memsz = sh.memlength;
00208                 if ( ( offset + filesz ) > image->len ) {
00209                         DBGC ( image, "NBI %p segment outside file\n", image );
00210                         return -ENOEXEC;
00211                 }
00212                 if ( ( rc = process ( image, offset, dest,
00213                                       filesz, memsz ) ) != 0 ) {
00214                         return rc;
00215                 }
00216                 offset += filesz;
00217 
00218                 /* Next segheader */
00219                 sh_off += NBI_LENGTH ( sh.length );
00220                 if ( sh_off >= NBI_HEADER_LENGTH ) {
00221                         DBGC ( image, "NBI %p header overflow\n", image );
00222                         return -ENOEXEC;
00223                 }
00224 
00225         } while ( ! NBI_LAST_SEGHEADER ( sh.flags ) );
00226 
00227         if ( offset != image->len ) {
00228                 DBGC ( image, "NBI %p length wrong (file %zd, metadata %zd)\n",
00229                        image, image->len, offset );
00230                 return -ENOEXEC;
00231         }
00232 
00233         return 0;
00234 }
00235 
00236 /**
00237  * Boot a 16-bit NBI image
00238  *
00239  * @v imgheader         Image header information
00240  * @ret rc              Return status code, if image returns
00241  */
00242 static int nbi_boot16 ( struct image *image, struct imgheader *imgheader ) {
00243         int discard_D, discard_S, discard_b;
00244         int32_t rc;
00245 
00246         DBGC ( image, "NBI %p executing 16-bit image at %04x:%04x\n", image,
00247                imgheader->execaddr.segoff.segment,
00248                imgheader->execaddr.segoff.offset );
00249 
00250         __asm__ __volatile__ (
00251                 REAL_CODE ( "pushl %%ebp\n\t"   /* gcc bug */
00252                             "pushw %%ds\n\t"    /* far pointer to bootp data */
00253                             "pushw %%bx\n\t"
00254                             "pushl %%esi\n\t"   /* location */
00255                             "pushw %%cs\n\t"    /* lcall execaddr */
00256                             "call 1f\n\t"
00257                             "jmp 2f\n\t"
00258                             "\n1:\n\t"
00259                             "pushl %%edi\n\t"
00260                             "lret\n\t"
00261                             "\n2:\n\t"
00262                             "addw $8,%%sp\n\t"  /* clean up stack */
00263                             "popl %%ebp\n\t"    /* gcc bug */ )
00264                 : "=a" ( rc ), "=D" ( discard_D ), "=S" ( discard_S ),
00265                   "=b" ( discard_b )
00266                 : "D" ( imgheader->execaddr.segoff ),
00267                   "S" ( imgheader->location ),
00268                   "b" ( __from_data16 ( basemem_packet ) )
00269                 : "ecx", "edx" );
00270 
00271         return rc;
00272 }
00273 
00274 /**
00275  * Boot a 32-bit NBI image
00276  *
00277  * @v imgheader         Image header information
00278  * @ret rc              Return status code, if image returns
00279  */
00280 static int nbi_boot32 ( struct image *image, struct imgheader *imgheader ) {
00281         struct ebinfo loaderinfo = {
00282                 product_major_version, product_minor_version,
00283                 0
00284         };
00285         int discard_D, discard_S, discard_b;
00286         int32_t rc;
00287 
00288         DBGC ( image, "NBI %p executing 32-bit image at %lx\n",
00289                image, imgheader->execaddr.linear );
00290 
00291         /* Jump to OS with flat physical addressing */
00292         __asm__ __volatile__ (
00293                 PHYS_CODE ( "pushl %%ebp\n\t" /* gcc bug */
00294                             "pushl %%ebx\n\t" /* bootp data */
00295                             "pushl %%esi\n\t" /* imgheader */
00296                             "pushl %%eax\n\t" /* loaderinfo */
00297                             "call *%%edi\n\t"
00298                             "addl $12, %%esp\n\t" /* clean up stack */
00299                             "popl %%ebp\n\t" /* gcc bug */ )
00300                 : "=a" ( rc ), "=D" ( discard_D ), "=S" ( discard_S ),
00301                   "=b" ( discard_b )
00302                 : "D" ( imgheader->execaddr.linear ),
00303                   "S" ( ( imgheader->location.segment << 4 ) +
00304                         imgheader->location.offset ),
00305                   "b" ( virt_to_phys ( basemem_packet ) ),
00306                   "a" ( virt_to_phys ( &loaderinfo ) )
00307                 : "ecx", "edx", "memory" );
00308 
00309         return rc;
00310 }
00311 
00312 /**
00313  * Prepare DHCP parameter block for NBI image
00314  *
00315  * @v image             NBI image
00316  * @ret rc              Return status code
00317  */
00318 static int nbi_prepare_dhcp ( struct image *image ) {
00319         struct net_device *boot_netdev;
00320         int rc;
00321 
00322         boot_netdev = last_opened_netdev();
00323         if ( ! boot_netdev ) {
00324                 DBGC ( image, "NBI %p could not identify a network device\n",
00325                        image );
00326                 return -ENODEV;
00327         }
00328 
00329         if ( ( rc = create_fakedhcpack ( boot_netdev, basemem_packet,
00330                                          sizeof ( basemem_packet ) ) ) != 0 ) {
00331                 DBGC ( image, "NBI %p failed to build DHCP packet\n", image );
00332                 return rc;
00333         }
00334 
00335         return 0;
00336 }
00337 
00338 /**
00339  * Execute a loaded NBI image
00340  *
00341  * @v image             NBI image
00342  * @ret rc              Return status code
00343  */
00344 static int nbi_exec ( struct image *image ) {
00345         struct imgheader imgheader;
00346         int may_return;
00347         int rc;
00348 
00349         /* Retrieve image header */
00350         copy_from_user ( &imgheader, image->data, 0, sizeof ( imgheader ) );
00351 
00352         DBGC ( image, "NBI %p placing header at %hx:%hx\n", image,
00353                imgheader.location.segment, imgheader.location.offset );
00354 
00355         /* NBI files can have overlaps between segments; the bss of
00356          * one segment may overlap the initialised data of another.  I
00357          * assume this is a design flaw, but there are images out
00358          * there that we need to work with.  We therefore do two
00359          * passes: first to initialise the segments, then to copy the
00360          * data.  This avoids zeroing out already-copied data.
00361          */
00362         if ( ( rc = nbi_process_segments ( image, &imgheader,
00363                                            nbi_prepare_segment ) ) != 0 )
00364                 return rc;
00365         if ( ( rc = nbi_process_segments ( image, &imgheader,
00366                                            nbi_load_segment ) ) != 0 )
00367                 return rc;
00368 
00369         /* Prepare DHCP option block */
00370         if ( ( rc = nbi_prepare_dhcp ( image ) ) != 0 )
00371                 return rc;
00372 
00373         /* Shut down now if NBI image will not return */
00374         may_return = NBI_PROGRAM_RETURNS ( imgheader.flags );
00375         if ( ! may_return )
00376                 shutdown_boot();
00377 
00378         /* Execute NBI image */
00379         if ( NBI_LINEAR_EXEC_ADDR ( imgheader.flags ) ) {
00380                 rc = nbi_boot32 ( image, &imgheader );
00381         } else {
00382                 rc = nbi_boot16 ( image, &imgheader );
00383         }
00384 
00385         if ( ! may_return ) {
00386                 /* Cannot continue after shutdown() called */
00387                 DBGC ( image, "NBI %p returned %d from non-returnable image\n",
00388                        image, rc  );
00389                 while ( 1 ) {}
00390         }
00391 
00392         DBGC ( image, "NBI %p returned %d\n", image, rc );
00393 
00394         return rc;
00395 }
00396 
00397 /**
00398  * Probe NBI image
00399  *
00400  * @v image             NBI image
00401  * @ret rc              Return status code
00402  */
00403 static int nbi_probe ( struct image *image ) {
00404         struct imgheader imgheader;
00405 
00406         /* If we don't have enough data give up */
00407         if ( image->len < NBI_HEADER_LENGTH ) {
00408                 DBGC ( image, "NBI %p too short for an NBI image\n", image );
00409                 return -ENOEXEC;
00410         }
00411 
00412         /* Check image header */
00413         copy_from_user ( &imgheader, image->data, 0, sizeof ( imgheader ) );
00414         if ( imgheader.magic != NBI_MAGIC ) {
00415                 DBGC ( image, "NBI %p has no NBI signature\n", image );
00416                 return -ENOEXEC;
00417         }
00418 
00419         return 0;
00420 }
00421 
00422 /** NBI image type */
00423 struct image_type nbi_image_type __image_type ( PROBE_NORMAL ) = {
00424         .name = "NBI",
00425         .probe = nbi_probe,
00426         .exec = nbi_exec,
00427 };