iPXE
Data Structures | Defines | Typedefs | Functions | Variables
pxe.h File Reference
#include "pxe_types.h"
#include "pxe_error.h"
#include "pxe_api.h"
#include <ipxe/device.h>
#include <ipxe/tables.h>

Go to the source code of this file.

Data Structures

struct  s_PXENV_UNKNOWN
 Parameter block for pxenv_unknown() More...
union  u_PXENV_ANY
struct  pxe_api_call
 A PXE API call. More...
struct  undi_rom_header
 An UNDI expansion ROM header. More...
struct  undi_rom_id
 An UNDI ROM ID structure. More...
struct  pcir_header
 A PCI expansion header. More...

Defines

#define PXENV_UNKNOWN   0xffff
 PXE API invalid function code.
#define PXE_API_CALLS   __table ( struct pxe_api_call, "pxe_api_calls" )
 PXE API call table.
#define __pxe_api_call   __table_entry ( PXE_API_CALLS, 01 )
 Declare a PXE API call.
#define PXE_API_CALL(_opcode, _entry, _params_type)
 Define a PXE API call.
#define ROM_SIGNATURE   0xaa55
 Signature for an expansion ROM.
#define UNDI_ROM_ID_SIGNATURE   ( ( 'U' << 0 ) + ( 'N' << 8 ) + ( 'D' << 16 ) + ( 'I' << 24 ) )
 Signature for an UNDI ROM ID structure.
#define PCIR_SIGNATURE   ( ( 'P' << 0 ) + ( 'C' << 8 ) + ( 'I' << 16 ) + ( 'R' << 24 ) )
 Signature for an UNDI ROM ID structure.

Typedefs

typedef struct s_PXENV_UNKNOWN PXENV_UNKNOWN_t
typedef union u_PXENV_ANY PXENV_ANY_t

Functions

 FILE_LICENCE (GPL2_OR_LATER_OR_UBDL)
void pxe_set_netdev (struct net_device *netdev)
 Set network device as current PXE network device.
void pxe_fake_cached_info (void)
 Construct cached DHCP packets.
PXENV_EXIT_t pxenv_tftp_read_file (struct s_PXENV_TFTP_READ_FILE *tftp_read_file)
 TFTP/MTFTP read file.
PXENV_EXIT_t undi_loader (struct s_UNDI_LOADER *undi_loader)

Variables

struct net_devicepxe_netdev
const char * pxe_cmdline
 PXE command line.

Define Documentation

#define PXENV_UNKNOWN   0xffff

PXE API invalid function code.

Definition at line 13 of file pxe.h.

Referenced by pxe_api_profiler(), and undinet_profiler().

#define PXE_API_CALLS   __table ( struct pxe_api_call, "pxe_api_calls" )

PXE API call table.

Definition at line 95 of file pxe.h.

Referenced by find_pxe_api_call(), and pxenv_file_api_check().

Declare a PXE API call.

Definition at line 98 of file pxe.h.

#define PXE_API_CALL (   _opcode,
  _entry,
  _params_type 
)
Value:
{                             \
        .entry = ( ( ( ( PXENV_EXIT_t ( * ) ( _params_type *params ) ) NULL ) \
                    == ( ( typeof ( _entry ) * ) NULL ) )                     \
                   ? ( ( PXENV_EXIT_t ( * )                                   \
                         ( union u_PXENV_ANY *params ) ) _entry )             \
                   : ( ( PXENV_EXIT_t ( * )                                   \
                         ( union u_PXENV_ANY *params ) ) _entry ) ),          \
        .params_len = sizeof ( _params_type ),                                \
        .opcode = _opcode,                                                    \
        }

Define a PXE API call.

Parameters:
_opcodeOpcode
_entryEntry point
_params_typeType of parameter structure
Return values:
callPXE API call

Definition at line 108 of file pxe.h.

#define ROM_SIGNATURE   0xaa55

Signature for an expansion ROM.

Definition at line 137 of file pxe.h.

Referenced by undirom_probe().

#define UNDI_ROM_ID_SIGNATURE   ( ( 'U' << 0 ) + ( 'N' << 8 ) + ( 'D' << 16 ) + ( 'I' << 24 ) )

Signature for an UNDI ROM ID structure.

Definition at line 171 of file pxe.h.

Referenced by undirom_parse_pxeromid().

#define PCIR_SIGNATURE   ( ( 'P' << 0 ) + ( 'C' << 8 ) + ( 'I' << 16 ) + ( 'R' << 24 ) )

Signature for an UNDI ROM ID structure.

Definition at line 188 of file pxe.h.

Referenced by undirom_parse_pcirheader().


Typedef Documentation

Definition at line 20 of file pxe.h.

typedef union u_PXENV_ANY PXENV_ANY_t

Definition at line 78 of file pxe.h.


Function Documentation

FILE_LICENCE ( GPL2_OR_LATER_OR_UBDL  )
void pxe_set_netdev ( struct net_device netdev)

Set network device as current PXE network device.

Parameters:
netdevNetwork device, or NULL

Definition at line 69 of file pxe_undi.c.

References netdev_get(), netdev_put(), netdev_rx_unfreeze(), and NULL.

Referenced by pxe_activate(), and pxe_deactivate().

                                                  {

        if ( pxe_netdev ) {
                netdev_rx_unfreeze ( pxe_netdev );
                netdev_put ( pxe_netdev );
        }

        pxe_netdev = NULL;

        if ( netdev )
                pxe_netdev = netdev_get ( netdev );
}
void pxe_fake_cached_info ( void  )

Construct cached DHCP packets.

Definition at line 135 of file pxe_preboot.c.

References assert, cached_info, pxe_dhcp_packet_creator::create, DBGC, info, memset(), NULL, pxe_dhcp_packet_creators, pxe_netdev, rc, and strerror().

Referenced by pxe_exec().

                                   {
        struct pxe_dhcp_packet_creator *creator;
        union pxe_cached_info *info;
        unsigned int i;
        int rc;

        /* Sanity check */
        assert ( pxe_netdev != NULL );

        /* Erase any stale packets */
        memset ( cached_info, 0, sizeof ( cached_info ) );

        /* Construct all DHCP packets */
        for ( i = 0 ; i < ( sizeof ( pxe_dhcp_packet_creators ) /
                            sizeof ( pxe_dhcp_packet_creators[0] ) ) ; i++ ) {

                /* Construct DHCP packet */
                creator = &pxe_dhcp_packet_creators[i];
                info = &cached_info[i];
                if ( ( rc = creator->create ( pxe_netdev, info,
                                              sizeof ( *info ) ) ) != 0 ) {
                        DBGC ( &pxe_netdev, " failed to build packet: %s\n",
                               strerror ( rc ) );
                        /* Continue constructing remaining packets */
                }
        }
}

TFTP/MTFTP read file.

Parameters:
tftp_read_filePointer to a struct s_PXENV_TFTP_READ_FILE
s_PXENV_TFTP_READ_FILE::FileNameFile name
s_PXENV_TFTP_READ_FILE::BufferSizeSize of the receive buffer
s_PXENV_TFTP_READ_FILE::BufferAddress of the receive buffer
s_PXENV_TFTP_READ_FILE::ServerIPAddressTFTP server IP address
s_PXENV_TFTP_READ_FILE::GatewayIPAddressRelay agent IP address
s_PXENV_TFTP_READ_FILE::McastIPAddressFile's multicast IP address
s_PXENV_TFTP_READ_FILE::TFTPClntPortClient multicast UDP port
s_PXENV_TFTP_READ_FILE::TFTPSrvPortServer multicast UDP port
s_PXENV_TFTP_READ_FILE::TFTPOpenTimeOutTime to wait for first packet
s_PXENV_TFTP_READ_FILE::TFTPReopenDelayMTFTP inactivity timeout
Return values:
PXENV_EXIT_SUCCESSFile downloaded successfully
PXENV_EXIT_FAILUREFile not downloaded
s_PXENV_TFTP_READ_FILE::StatusPXE status code
s_PXENV_TFTP_READ_FILE::BufferSizeLength of downloaded file

Downloads an entire file via either TFTP or MTFTP into the buffer pointed to by s_PXENV_TFTP_READ_FILE::Buffer.

The PXE specification does not make it clear how the caller requests that MTFTP be used rather than TFTP (or vice versa). One reasonable guess is that setting s_PXENV_TFTP_READ_FILE::McastIPAddress to 0.0.0.0 would cause TFTP to be used instead of MTFTP, though it is conceivable that some PXE stacks would interpret that as "use the DHCP-provided multicast IP address" instead. Some PXE stacks will not implement MTFTP at all, and will always use TFTP.

It is not specified whether or not s_PXENV_TFTP_READ_FILE::TFTPSrvPort will be used as the TFTP server port for TFTP (rather than MTFTP) downloads. Callers should assume that the only way to access a TFTP server on a non-standard port is to use pxenv_tftp_open() and pxenv_tftp_read().

If s_PXENV_TFTP_READ_FILE::GatewayIPAddress is 0.0.0.0, normal IP routing will take place. See the relevant implementation note for more details.

It is interesting to note that s_PXENV_TFTP_READ_FILE::Buffer is an ADDR32_t type, i.e. nominally a flat physical address. Some PXE NBPs (e.g. NTLDR) are known to call pxenv_tftp_read_file() in real mode with s_PXENV_TFTP_READ_FILE::Buffer set to an address above 1MB. This means that PXE stacks must be prepared to write to areas outside base memory. Exactly how this is to be achieved is not specified, though using INT 15,87 is as close to a standard method as any, and should probably be used. Switching to protected-mode in order to access high memory will fail if pxenv_tftp_read_file() is called in V86 mode; it is reasonably to expect that a V86 monitor would intercept the relatively well-defined INT 15,87 if it wants the PXE stack to be able to write to high memory.

Things get even more interesting if pxenv_tftp_read_file() is called in protected mode, because there is then absolutely no way for the PXE stack to write to an absolute physical address. You can't even get around the problem by creating a special "access everything" segment in the s_PXE data structure, because the #SEGDESC_t descriptors are limited to 64kB in size.

Previous versions of the PXE specification (e.g. WfM 1.1a) provide a separate API call, pxenv_tftp_read_file_pmode(), specifically to work around this problem. The s_PXENV_TFTP_READ_FILE_PMODE parameter block splits s_PXENV_TFTP_READ_FILE::Buffer into s_PXENV_TFTP_READ_FILE_PMODE::BufferSelector and s_PXENV_TFTP_READ_FILE_PMODE::BufferOffset, i.e. it provides a protected-mode segment:offset address for the data buffer. This API call is no longer present in version 2.1 of the PXE specification.

Etherboot makes the assumption that s_PXENV_TFTP_READ_FILE::Buffer is an offset relative to the caller's data segment, when pxenv_tftp_read_file() is called in protected mode.

On x86, you must set the s_PXE::StatusCallout field to a nonzero value before calling this function in protected mode. You cannot call this function with a 32-bit stack segment. (See the relevant implementation note for more details.)

Definition at line 480 of file pxe_tftp.c.

References pxe_tftp_connection::buffer, s_PXENV_TFTP_READ_FILE::Buffer, s_PXENV_TFTP_READ_FILE::BufferSize, DBG, EINPROGRESS, s_PXENV_TFTP_READ_FILE::FileName, pxe_tftp_connection::max_offset, phys_to_user(), pxe_tftp_close(), pxe_tftp_open(), PXENV_EXIT_FAILURE, PXENV_EXIT_SUCCESS, PXENV_STATUS, pxe_tftp_connection::rc, rc, s_PXENV_TFTP_READ_FILE::ServerIPAddress, pxe_tftp_connection::size, s_PXENV_TFTP_READ_FILE::Status, step(), and UNULL.

Referenced by pxenv_restart_tftp().

                                                      {
        int rc;

        DBG ( "PXENV_TFTP_READ_FILE to %08x+%x", tftp_read_file->Buffer,
              tftp_read_file->BufferSize );

        /* Open TFTP file */
        if ( ( rc = pxe_tftp_open ( tftp_read_file->ServerIPAddress, 0,
                                    tftp_read_file->FileName, 0 ) ) != 0 ) {
                tftp_read_file->Status = PXENV_STATUS ( rc );
                return PXENV_EXIT_FAILURE;
        }

        /* Read entire file */
        pxe_tftp.buffer = phys_to_user ( tftp_read_file->Buffer );
        pxe_tftp.size = tftp_read_file->BufferSize;
        while ( ( rc = pxe_tftp.rc ) == -EINPROGRESS )
                step();
        pxe_tftp.buffer = UNULL;
        tftp_read_file->BufferSize = pxe_tftp.max_offset;

        /* Close TFTP file */
        pxe_tftp_close ( &pxe_tftp, rc );

        tftp_read_file->Status = PXENV_STATUS ( rc );
        return ( rc ? PXENV_EXIT_FAILURE : PXENV_EXIT_SUCCESS );
}
PXENV_EXIT_t undi_loader ( struct s_UNDI_LOADER undi_loader)

Definition at line 39 of file pxe_loader.c.

References __from_text16, DBG, initialise(), ppxe, pxenv, PXENV_EXIT_SUCCESS, PXENV_STATUS_SUCCESS, s_UNDI_LOADER::PXENVptr, s_UNDI_LOADER::PXEptr, rm_cs, s_UNDI_LOADER::Status, s_UNDI_LOADER::UNDI_CS, and s_UNDI_LOADER::UNDI_DS.

                                                               {

        /* Perform one-time initialisation (e.g. heap) */
        initialise();

        DBG ( "[PXENV_UNDI_LOADER to CS %04x DS %04x]",
              undi_loader->UNDI_CS, undi_loader->UNDI_DS );

        /* Fill in UNDI loader structure */
        undi_loader->PXEptr.segment = rm_cs;
        undi_loader->PXEptr.offset = __from_text16 ( &ppxe );
        undi_loader->PXENVptr.segment = rm_cs;
        undi_loader->PXENVptr.offset = __from_text16 ( &pxenv );

        undi_loader->Status = PXENV_STATUS_SUCCESS;
        return PXENV_EXIT_SUCCESS;
}

Variable Documentation

const char* pxe_cmdline

PXE command line.

Definition at line 48 of file pxe_image.c.

Referenced by pxe_exec(), and pxenv_file_cmdline().