NBI image format. More...

#include <string.h>
#include <errno.h>
#include <assert.h>
#include <realmode.h>
#include <memsizes.h>
#include <basemem_packet.h>
#include <ipxe/uaccess.h>
#include <ipxe/segment.h>
#include <ipxe/init.h>
#include <ipxe/netdevice.h>
#include <ipxe/fakedhcp.h>
#include <ipxe/image.h>
#include <ipxe/features.h>
#include <ipxe/version.h>

Data Structures
struct	imgheader
	An NBI image header. More...
struct	segheader
	An NBI segment header. More...
struct	ebinfo

Macros
#define	NBI_MAGIC 0x1B031336UL
	NBI magic number.
#define	NBI_NONVENDOR_LENGTH(len)
#define	NBI_VENDOR_LENGTH(len)
#define	NBI_LENGTH(len)
#define	NBI_PROGRAM_RETURNS(flags)
#define	NBI_LINEAR_EXEC_ADDR(flags)
#define	NBI_HEADER_LENGTH 512
	NBI header length.
#define	NBI_LOADADDR_FLAGS(flags)
#define	NBI_LOADADDR_ABS 0x00
#define	NBI_LOADADDR_AFTER 0x01
#define	NBI_LOADADDR_END 0x02
#define	NBI_LOADADDR_BEFORE 0x03
#define	NBI_LAST_SEGHEADER(flags)

Functions
	FEATURE (FEATURE_IMAGE, "NBI", DHCP_EB_FEATURE_NBI, 1)
static int	nbi_prepare_segment (struct image image, size_t offset __unused, void dest, size_t filesz, size_t memsz)
	Prepare a segment for an NBI image.
static int	nbi_load_segment (struct image image, size_t offset, void dest, size_t filesz, size_t memsz __unused)
	Load a segment for an NBI image.
static int	nbi_process_segments (struct image image, const struct imgheader imgheader, int(process)(struct image image, size_t offset, void *dest, size_t filesz, size_t memsz))
	Process segments of an NBI image.
static int	nbi_boot16 (struct image image, const struct imgheader imgheader)
	Boot a 16-bit NBI image.
static int	nbi_boot32 (struct image image, const struct imgheader imgheader)
	Boot a 32-bit NBI image.
static int	nbi_prepare_dhcp (struct image *image)
	Prepare DHCP parameter block for NBI image.
static int	nbi_exec (struct image *image)
	Execute a loaded NBI image.
static int	nbi_probe (struct image *image)
	Probe NBI image.
struct image_type nbi_image_type	__image_type (PROBE_NORMAL)
	NBI image type.

Detailed Description

NBI image format.

The Net Boot Image format is defined by the "Draft Net Boot Image Proposal 0.3" by Jamie Honan, Gero Kuhlmann and Ken Yap. It is now considered to be a legacy format, but it still included because a large amount of software (e.g. nymph, LTSP) makes use of NBI files.

Etherboot does not implement the INT 78 callback interface described by the NBI specification. For a callback interface on x86 architecture, use PXE.

Definition in file nbi.c.

Macro Definition Documentation

◆ NBI_MAGIC

#define NBI_MAGIC 0x1B031336UL

NBI magic number.

Definition at line 54 of file nbi.c.

Referenced by nbi_probe().

◆ NBI_NONVENDOR_LENGTH

#define NBI_NONVENDOR_LENGTH ( len )

Value:

( ( (len) & 0x0f ) << 2 )

len

ring len

Length.

Definition dwmac.h:226

Definition at line 57 of file nbi.c.

◆ NBI_VENDOR_LENGTH

#define NBI_VENDOR_LENGTH ( len )

Value:

( ( (len) & 0xf0 ) >> 2 )

Definition at line 58 of file nbi.c.

◆ NBI_LENGTH

#define NBI_LENGTH ( len )

Value:

( NBI_NONVENDOR_LENGTH(len) + NBI_VENDOR_LENGTH(len) )

NBI_NONVENDOR_LENGTH

#define NBI_NONVENDOR_LENGTH(len)

Definition nbi.c:57

NBI_VENDOR_LENGTH

#define NBI_VENDOR_LENGTH(len)

Definition nbi.c:58

Definition at line 59 of file nbi.c.

Referenced by nbi_process_segments().

◆ NBI_PROGRAM_RETURNS

#define NBI_PROGRAM_RETURNS ( flags )

Value:

( (flags) & ( 1U << 8 ) )

flags

uint8_t flags

Flags.

Definition ena.h:7

Definition at line 62 of file nbi.c.

Referenced by nbi_exec().

◆ NBI_LINEAR_EXEC_ADDR

#define NBI_LINEAR_EXEC_ADDR ( flags )

Value:

( (flags) & ( 1U << 31 ) )

Definition at line 63 of file nbi.c.

Referenced by nbi_exec().

◆ NBI_HEADER_LENGTH

#define NBI_HEADER_LENGTH 512

NBI header length.

Definition at line 66 of file nbi.c.

Referenced by nbi_probe(), and nbi_process_segments().

◆ NBI_LOADADDR_FLAGS

#define NBI_LOADADDR_FLAGS ( flags )

Value:

( (flags) & 0x03 )

Definition at line 86 of file nbi.c.

Referenced by nbi_process_segments().

◆ NBI_LOADADDR_ABS

#define NBI_LOADADDR_ABS 0x00

Definition at line 87 of file nbi.c.

Referenced by nbi_process_segments().

◆ NBI_LOADADDR_AFTER

#define NBI_LOADADDR_AFTER 0x01

Definition at line 88 of file nbi.c.

Referenced by nbi_process_segments().

◆ NBI_LOADADDR_END

#define NBI_LOADADDR_END 0x02

Definition at line 89 of file nbi.c.

Referenced by nbi_process_segments().

◆ NBI_LOADADDR_BEFORE

#define NBI_LOADADDR_BEFORE 0x03

Definition at line 90 of file nbi.c.

Referenced by nbi_process_segments().

◆ NBI_LAST_SEGHEADER

#define NBI_LAST_SEGHEADER ( flags )

Value:

( (flags) & ( 1U << 2 ) )

Definition at line 91 of file nbi.c.

Referenced by nbi_process_segments().

Function Documentation

◆ FEATURE()

FEATURE	(	FEATURE_IMAGE	,
		"NBI"	,
		DHCP_EB_FEATURE_NBI	,
		1	)

References DHCP_EB_FEATURE_NBI, and FEATURE_IMAGE.

◆ nbi_prepare_segment()

int nbi_prepare_segment	(	struct image *	image,
		size_t offset	__unused,
		void *	dest,
		size_t	filesz,
		size_t	memsz )

static

Prepare a segment for an NBI image.

Parameters

image	NBI image
offset	Offset within NBI image
filesz	Length of initialised-data portion of the segment
memsz	Total length of the segment
src	Source for initialised data

Return values

rc	Return status code

Definition at line 109 of file nbi.c.

                                                                           {
        int rc;
 
        if ( ( rc = prep_segment ( dest, filesz, memsz ) ) != 0 ) {
                DBGC ( image, "NBI %s could not prepare segment: %s\n",
                       image->name, strerror ( rc ) );
                return rc;
        }
 
        return 0;
}

References __unused, DBGC, dest, memsz, image::name, offset, prep_segment(), rc, and strerror().

Referenced by nbi_exec().

◆ nbi_load_segment()

int nbi_load_segment	(	struct image *	image,
		size_t	offset,
		void *	dest,
		size_t	filesz,
		size_t memsz	__unused )

static

Load a segment for an NBI image.

Parameters

image	NBI image
offset	Offset within NBI image
filesz	Length of initialised-data portion of the segment
memsz	Total length of the segment
src	Source for initialised data

Return values

rc	Return status code

Definition at line 132 of file nbi.c.

                                                      {
        memcpy ( dest, ( image->data + offset ), filesz );
        return 0;
}

References __unused, image::data, dest, memcpy(), memsz, and offset.

Referenced by nbi_exec().

◆ nbi_process_segments()

int nbi_process_segments	(	struct image *	image,
		const struct imgheader *	imgheader,
		int(*	process )(struct image image, size_t offset, void dest, size_t filesz, size_t memsz) )

static

Process segments of an NBI image.

Parameters

image	NBI image
imgheader	Image header information
process	Function to call for each segment

Return values

rc	Return status code

Definition at line 147 of file nbi.c.

                                                                       {
        const struct segheader *sh;
        size_t offset = 0;
        size_t sh_off;
        void *dest;
        size_t filesz;
        size_t memsz;
        int rc;
        
        /* Copy image header to target location */
        dest = real_to_virt ( imgheader->location.segment,
                              imgheader->location.offset );
        filesz = memsz = NBI_HEADER_LENGTH;
        if ( ( rc = process ( image, offset, dest, filesz, memsz ) ) != 0 )
                return rc;
        offset += filesz;
 
        /* Process segments in turn */
        sh_off = NBI_LENGTH ( imgheader->length );
        do {
                /* Read segment header */
                if ( ( sh_off + sizeof ( *sh ) ) > image->len ) {
                        DBGC ( image, "NBI %s segheader outside file\n",
                               image->name );
                        return -ENOEXEC;
                }
                sh = ( image->data + sh_off );
                if ( sh->length == 0 ) {
                        /* Avoid infinite loop? */
                        DBGC ( image, "NBI %s invalid segheader length 0\n",
                               image->name );
                        return -ENOEXEC;
                }
                
                /* Calculate segment load address */
                switch ( NBI_LOADADDR_FLAGS ( sh->flags ) ) {
                case NBI_LOADADDR_ABS:
                        dest = phys_to_virt ( sh->loadaddr );
                        break;
                case NBI_LOADADDR_AFTER:
                        dest = ( dest + memsz + sh->loadaddr );
                        break;
                case NBI_LOADADDR_BEFORE:
                        dest = ( dest - sh->loadaddr );
                        break;
                case NBI_LOADADDR_END:
                        /* Not correct according to the spec, but
                         * maintains backwards compatibility with
                         * previous versions of Etherboot.
                         */
                        dest = phys_to_virt ( ( extmemsize() + 1024 ) * 1024
                                              - sh->loadaddr );
                        break;
                default:
                        /* Cannot be reached */
                        assert ( 0 );
                }
 
                /* Process this segment */
                filesz = sh->imglength;
                memsz = sh->memlength;
                if ( ( offset > image->len ) ||
                     ( filesz > ( image->len - offset ) ) ) {
                        DBGC ( image, "NBI %s segment outside file\n",
                               image->name );
                        return -ENOEXEC;
                }
                if ( ( rc = process ( image, offset, dest,
                                      filesz, memsz ) ) != 0 ) {
                        return rc;
                }
                offset += filesz;
 
                /* Next segheader */
                sh_off += NBI_LENGTH ( sh->length );
                if ( sh_off >= NBI_HEADER_LENGTH ) {
                        DBGC ( image, "NBI %s header overflow\n",
                               image->name );
                        return -ENOEXEC;
                }
 
        } while ( ! NBI_LAST_SEGHEADER ( sh->flags ) );
 
        if ( offset != image->len ) {
                DBGC ( image, "NBI %s length wrong (file %zd, metadata %zd)\n",
                       image->name, image->len, offset );
                return -ENOEXEC;
        }
 
        return 0;
}

References assert, image::data, DBGC, dest, ENOEXEC, extmemsize(), segheader::flags, segheader::imglength, image::len, imgheader::length, segheader::length, segheader::loadaddr, imgheader::location, segheader::memlength, memsz, image::name, NBI_HEADER_LENGTH, NBI_LAST_SEGHEADER, NBI_LENGTH, NBI_LOADADDR_ABS, NBI_LOADADDR_AFTER, NBI_LOADADDR_BEFORE, NBI_LOADADDR_END, NBI_LOADADDR_FLAGS, offset, segoff::offset, rc, real_to_virt(), and segoff::segment.

Referenced by nbi_exec().

◆ nbi_boot16()

int nbi_boot16	(	struct image *	image,
		const struct imgheader *	imgheader )

static

Boot a 16-bit NBI image.

Parameters

imgheader Image header information

Return values

rc	Return status code, if image returns

Definition at line 251 of file nbi.c.

                                                            {
        int discard_D, discard_S, discard_b;
        int32_t rc;
 
        DBGC ( image, "NBI %s executing 16-bit image at %04x:%04x\n",
               image->name, imgheader->execaddr.segoff.segment,
               imgheader->execaddr.segoff.offset );
 
        __asm__ __volatile__ (
                REAL_CODE ( "pushl %%ebp\n\t"   /* gcc bug */
                            "pushw %%ds\n\t"    /* far pointer to bootp data */
                            "pushw %%bx\n\t"
                            "pushl %%esi\n\t"   /* location */
                            "pushw %%cs\n\t"    /* lcall execaddr */
                            "call 1f\n\t"
                            "jmp 2f\n\t"
                            "\n1:\n\t"
                            "pushl %%edi\n\t"
                            "lret\n\t"
                            "\n2:\n\t"
                            "addw $8,%%sp\n\t"  /* clean up stack */
                            "popl %%ebp\n\t"    /* gcc bug */ )
                : "=a" ( rc ), "=D" ( discard_D ), "=S" ( discard_S ),
                  "=b" ( discard_b )
                : "D" ( imgheader->execaddr.segoff ),
                  "S" ( imgheader->location ),
                  "b" ( __from_data16 ( basemem_packet ) )
                : "ecx", "edx" );
 
        return rc;
}

References __asm__(), __from_data16, __volatile__(), basemem_packet, DBGC, discard_D, discard_S, imgheader::execaddr, imgheader::location, image::name, segoff::offset, rc, REAL_CODE, segoff::segment, and imgheader::segoff.

Referenced by nbi_exec().

◆ nbi_boot32()

int nbi_boot32	(	struct image *	image,
		const struct imgheader *	imgheader )

static

Boot a 32-bit NBI image.

Parameters

imgheader Image header information

Return values

rc	Return status code, if image returns

Definition at line 290 of file nbi.c.

                                                            {
        struct ebinfo loaderinfo = {
                product_major_version, product_minor_version,
                0
        };
        int discard_D, discard_S, discard_b;
        int32_t rc;
 
        DBGC ( image, "NBI %s executing 32-bit image at %lx\n",
               image->name, imgheader->execaddr.linear );
 
        /* Jump to OS with flat physical addressing */
        __asm__ __volatile__ (
                PHYS_CODE ( "pushl %%ebp\n\t" /* gcc bug */
                            "pushl %%ebx\n\t" /* bootp data */
                            "pushl %%esi\n\t" /* imgheader */
                            "pushl %%eax\n\t" /* loaderinfo */
                            "call *%%edi\n\t"
                            "addl $12, %%esp\n\t" /* clean up stack */
                            "popl %%ebp\n\t" /* gcc bug */ )
                : "=a" ( rc ), "=D" ( discard_D ), "=S" ( discard_S ),
                  "=b" ( discard_b )
                : "D" ( imgheader->execaddr.linear ),
                  "S" ( ( imgheader->location.segment << 4 ) +
                        imgheader->location.offset ),
                  "b" ( virt_to_phys ( basemem_packet ) ),
                  "a" ( virt_to_phys ( &loaderinfo ) )
                : "ecx", "edx", "memory" );
 
        return rc;
}

References __asm__(), __volatile__(), basemem_packet, DBGC, discard_D, discard_S, imgheader::execaddr, imgheader::linear, imgheader::location, image::name, segoff::offset, PHYS_CODE, product_major_version, product_minor_version, rc, and segoff::segment.

Referenced by nbi_exec().

◆ nbi_prepare_dhcp()

int nbi_prepare_dhcp ( struct image * image )

static

Prepare DHCP parameter block for NBI image.

Parameters

image NBI image

Return values

rc	Return status code

Definition at line 329 of file nbi.c.

                                                    {
        struct net_device *boot_netdev;
        int rc;
 
        boot_netdev = last_opened_netdev();
        if ( ! boot_netdev ) {
                DBGC ( image, "NBI %s could not identify a network device\n",
                       image->name );
                return -ENODEV;
        }
 
        if ( ( rc = create_fakedhcpack ( boot_netdev, basemem_packet,
                                         sizeof ( basemem_packet ) ) ) != 0 ) {
                DBGC ( image, "NBI %s failed to build DHCP packet\n",
                       image->name );
                return rc;
        }
 
        return 0;
}

References basemem_packet, create_fakedhcpack(), DBGC, ENODEV, last_opened_netdev(), image::name, and rc.

Referenced by nbi_exec().

◆ nbi_exec()

int nbi_exec ( struct image * image )

static

Execute a loaded NBI image.

Parameters

image NBI image

Return values

rc	Return status code

Definition at line 356 of file nbi.c.

                                            {
        const struct imgheader *imgheader;
        int may_return;
        int rc;
 
        /* Retrieve image header */
        imgheader = image->data;
 
        DBGC ( image, "NBI %s placing header at %hx:%hx\n", image->name,
               imgheader->location.segment, imgheader->location.offset );
 
        /* NBI files can have overlaps between segments; the bss of
         * one segment may overlap the initialised data of another.  I
         * assume this is a design flaw, but there are images out
         * there that we need to work with.  We therefore do two
         * passes: first to initialise the segments, then to copy the
         * data.  This avoids zeroing out already-copied data.
         */
        if ( ( rc = nbi_process_segments ( image, imgheader,
                                           nbi_prepare_segment ) ) != 0 )
                return rc;
        if ( ( rc = nbi_process_segments ( image, imgheader,
                                           nbi_load_segment ) ) != 0 )
                return rc;
 
        /* Prepare DHCP option block */
        if ( ( rc = nbi_prepare_dhcp ( image ) ) != 0 )
                return rc;
 
        /* Shut down now if NBI image will not return */
        may_return = NBI_PROGRAM_RETURNS ( imgheader->flags );
        if ( ! may_return )
                shutdown_boot();
 
        /* Execute NBI image */
        if ( NBI_LINEAR_EXEC_ADDR ( imgheader->flags ) ) {
                rc = nbi_boot32 ( image, imgheader );
        } else {
                rc = nbi_boot16 ( image, imgheader );
        }
 
        if ( ! may_return ) {
                /* Cannot continue after shutdown() called */
                DBGC ( image, "NBI %s returned %d from non-returnable image\n",
                       image->name, rc  );
                while ( 1 ) {}
        }
 
        DBGC ( image, "NBI %s returned %d\n", image->name, rc );
 
        return rc;
}

References image::data, DBGC, imgheader::flags, imgheader::location, image::name, nbi_boot16(), nbi_boot32(), NBI_LINEAR_EXEC_ADDR, nbi_load_segment(), nbi_prepare_dhcp(), nbi_prepare_segment(), nbi_process_segments(), NBI_PROGRAM_RETURNS, segoff::offset, rc, segoff::segment, and shutdown_boot().

Referenced by __image_type().

◆ nbi_probe()

int nbi_probe ( struct image * image )

static

Probe NBI image.

Parameters

image NBI image

Return values

rc	Return status code

Definition at line 415 of file nbi.c.

                                             {
        const struct imgheader *imgheader;
 
        /* If we don't have enough data give up */
        if ( image->len < NBI_HEADER_LENGTH ) {
                DBGC ( image, "NBI %s too short for an NBI image\n",
                       image->name );
                return -ENOEXEC;
        }
        imgheader = image->data;
 
        /* Check image header */
        if ( imgheader->magic != NBI_MAGIC ) {
                DBGC ( image, "NBI %s has no NBI signature\n", image->name );
                return -ENOEXEC;
        }
 
        return 0;
}

References image::data, DBGC, ENOEXEC, image::len, imgheader::magic, image::name, NBI_HEADER_LENGTH, and NBI_MAGIC.

Referenced by __image_type().

◆ __image_type()

struct image_type nbi_image_type __image_type ( PROBE_NORMAL )

NBI image type.

References __image_type, nbi_exec(), nbi_probe(), and PROBE_NORMAL.

Data Structures

Macros

Functions

Detailed Description

Macro Definition Documentation

◆ NBI_MAGIC

◆ NBI_NONVENDOR_LENGTH

◆ NBI_VENDOR_LENGTH

◆ NBI_LENGTH

◆ NBI_PROGRAM_RETURNS

◆ NBI_LINEAR_EXEC_ADDR

◆ NBI_HEADER_LENGTH

◆ NBI_LOADADDR_FLAGS

◆ NBI_LOADADDR_ABS

◆ NBI_LOADADDR_AFTER

◆ NBI_LOADADDR_END

◆ NBI_LOADADDR_BEFORE

◆ NBI_LAST_SEGHEADER

Function Documentation

◆ FEATURE()

◆ nbi_prepare_segment()

◆ nbi_load_segment()

◆ nbi_process_segments()

◆ nbi_boot16()

◆ nbi_boot32()

◆ nbi_prepare_dhcp()

◆ nbi_exec()

◆ nbi_probe()

◆ __image_type()