iPXE
Data Structures | Macros | 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...
 

Macros

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

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. More...
 
void pxe_fake_cached_info (void)
 Construct cached DHCP packets. More...
 
PXENV_EXIT_t pxenv_tftp_read_file (struct s_PXENV_TFTP_READ_FILE *tftp_read_file)
 TFTP/MTFTP read file. More...
 
PXENV_EXIT_t undi_loader (struct s_UNDI_LOADER *undi_loader)
 

Variables

struct net_devicepxe_netdev
 
const char * pxe_cmdline
 PXE command line. More...
 

Macro Definition Documentation

◆ PXENV_UNKNOWN

#define PXENV_UNKNOWN   0xffff

PXE API invalid function code.

Definition at line 13 of file pxe.h.

◆ PXE_API_CALLS

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

PXE API call table.

Definition at line 95 of file pxe.h.

◆ __pxe_api_call

#define __pxe_api_call   __table_entry ( PXE_API_CALLS, 01 )

Declare a PXE API call.

Definition at line 98 of file pxe.h.

◆ PXE_API_CALL

#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, \
}
uint8_t opcode
Opcode.
Definition: ena.h:16
UINT16_t PXENV_EXIT_t
A PXE exit code.
Definition: pxe_types.h:44
#define NULL
NULL pointer (VOID *)
Definition: Base.h:362

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.

◆ ROM_SIGNATURE

#define ROM_SIGNATURE   0xaa55

Signature for an expansion ROM.

Definition at line 137 of file pxe.h.

◆ UNDI_ROM_ID_SIGNATURE

#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.

◆ PCIR_SIGNATURE

#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.

Typedef Documentation

◆ PXENV_UNKNOWN_t

Definition at line 20 of file pxe.h.

◆ PXENV_ANY_t

typedef union u_PXENV_ANY PXENV_ANY_t

Definition at line 78 of file pxe.h.

Function Documentation

◆ FILE_LICENCE()

FILE_LICENCE ( GPL2_OR_LATER_OR_UBDL  )

◆ pxe_set_netdev()

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.

69  {
70 
71  if ( pxe_netdev ) {
74  }
75 
76  pxe_netdev = NULL;
77 
78  if ( netdev )
80 }
static void netdev_put(struct net_device *netdev)
Drop reference to network device.
Definition: netdevice.h:555
static struct net_device * netdev
Definition: gdbudp.c:52
struct net_device * pxe_netdev
Definition: pxe_undi.c:59
static struct net_device * netdev_get(struct net_device *netdev)
Get reference to network device.
Definition: netdevice.h:544
void netdev_rx_unfreeze(struct net_device *netdev)
Unfreeze network device receive queue processing.
Definition: netdevice.c:148
#define NULL
NULL pointer (VOID *)
Definition: Base.h:362

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

Referenced by pxe_activate(), and pxe_deactivate().

◆ pxe_fake_cached_info()

void pxe_fake_cached_info ( void  )

Construct cached DHCP packets.

Definition at line 135 of file pxe_preboot.c.

135  {
136  struct pxe_dhcp_packet_creator *creator;
137  union pxe_cached_info *info;
138  unsigned int i;
139  int rc;
140 
141  /* Sanity check */
142  assert ( pxe_netdev != NULL );
143 
144  /* Erase any stale packets */
145  memset ( cached_info, 0, sizeof ( cached_info ) );
146 
147  /* Construct all DHCP packets */
148  for ( i = 0 ; i < ( sizeof ( pxe_dhcp_packet_creators ) /
149  sizeof ( pxe_dhcp_packet_creators[0] ) ) ; i++ ) {
150 
151  /* Construct DHCP packet */
152  creator = &pxe_dhcp_packet_creators[i];
153  info = &cached_info[i];
154  if ( ( rc = creator->create ( pxe_netdev, info,
155  sizeof ( *info ) ) ) != 0 ) {
156  DBGC ( &pxe_netdev, " failed to build packet: %s\n",
157  strerror ( rc ) );
158  /* Continue constructing remaining packets */
159  }
160  }
161 }
struct arbelprm_rc_send_wqe rc
Definition: arbel.h:14
u32 info
Definition: ar9003_mac.h:67
#define DBGC(...)
Definition: compiler.h:505
static struct pxe_dhcp_packet_creator pxe_dhcp_packet_creators[]
PXE DHCP packet creators.
Definition: pxe_preboot.c:91
assert((readw(&hdr->flags) &(GTF_reading|GTF_writing))==0)
A cached DHCP packet.
Definition: pxe_preboot.c:62
char * strerror(int errno)
Retrieve string representation of error number.
Definition: strerror.c:78
struct net_device * pxe_netdev
Definition: pxe_undi.c:59
#define cached_info
Definition: pxe_preboot.c:129
#define NULL
NULL pointer (VOID *)
Definition: Base.h:362
A PXE DHCP packet creator.
Definition: pxe_preboot.c:78
int(* create)(struct net_device *netdev, void *data, size_t max_len)
Create DHCP packet.
Definition: pxe_preboot.c:86
void * memset(void *dest, int character, size_t len) __nonnull

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().

◆ pxenv_tftp_read_file()

PXENV_EXIT_t pxenv_tftp_read_file ( struct s_PXENV_TFTP_READ_FILE tftp_read_file)

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.

481  {
482  int rc;
483 
484  DBG ( "PXENV_TFTP_READ_FILE to %08x+%x", tftp_read_file->Buffer,
485  tftp_read_file->BufferSize );
486 
487  /* Open TFTP file */
488  if ( ( rc = pxe_tftp_open ( tftp_read_file->ServerIPAddress, 0,
489  tftp_read_file->FileName, 0 ) ) != 0 ) {
490  tftp_read_file->Status = PXENV_STATUS ( rc );
491  return PXENV_EXIT_FAILURE;
492  }
493 
494  /* Read entire file */
495  pxe_tftp.buffer = phys_to_user ( tftp_read_file->Buffer );
496  pxe_tftp.size = tftp_read_file->BufferSize;
497  while ( ( rc = pxe_tftp.rc ) == -EINPROGRESS )
498  step();
500  tftp_read_file->BufferSize = pxe_tftp.max_offset;
501 
502  /* Close TFTP file */
503  pxe_tftp_close ( &pxe_tftp, rc );
504 
505  tftp_read_file->Status = PXENV_STATUS ( rc );
507 }
static int pxe_tftp_open(IP4_t ipaddress, UDP_PORT_t port, UINT8_t *filename, UINT16_t blksize)
Open PXE TFTP connection.
Definition: pxe_tftp.c:171
IP4_t ServerIPAddress
TFTP server IP address.
Definition: pxe_api.h:650
struct arbelprm_rc_send_wqe rc
Definition: arbel.h:14
#define PXENV_EXIT_FAILURE
An error occurred.
Definition: pxe_types.h:46
userptr_t phys_to_user(unsigned long phys_addr)
Convert physical address to user pointer.
size_t size
Size of data buffer.
Definition: pxe_tftp.c:54
UINT32_t BufferSize
Size of data buffer.
Definition: pxe_api.h:648
UINT8_t FileName[128]
File name.
Definition: pxe_api.h:647
userptr_t buffer
Data buffer.
Definition: pxe_tftp.c:52
static void pxe_tftp_close(struct pxe_tftp_connection *pxe_tftp, int rc)
Close PXE TFTP connection.
Definition: pxe_tftp.c:75
size_t max_offset
Maximum file position.
Definition: pxe_tftp.c:60
static struct pxe_tftp_connection pxe_tftp
The PXE TFTP connection.
Definition: pxe_tftp.c:158
#define EINPROGRESS
Operation in progress.
Definition: errno.h:418
int rc
Overall return status code.
Definition: pxe_tftp.c:66
PXENV_STATUS_t Status
PXE status code.
Definition: pxe_api.h:646
#define PXENV_EXIT_SUCCESS
No error occurred.
Definition: pxe_types.h:45
#define UNULL
Equivalent of NULL for user pointers.
Definition: uaccess.h:36
void step(void)
Single-step a single process.
Definition: process.c:98
ADDR32_t Buffer
Address of data buffer.
Definition: pxe_api.h:649
#define DBG(...)
Print a debugging message.
Definition: compiler.h:498
#define PXENV_STATUS(rc)
Derive PXENV_STATUS code from iPXE error number.
Definition: pxe_error.h:121

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, 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().

◆ undi_loader()

PXENV_EXIT_t undi_loader ( struct s_UNDI_LOADER undi_loader)

Definition at line 39 of file pxe_loader.c.

39  {
40 
41  /* Perform one-time initialisation (e.g. heap) */
42  initialise();
43 
44  DBG ( "[PXENV_UNDI_LOADER to CS %04x DS %04x]",
45  undi_loader->UNDI_CS, undi_loader->UNDI_DS );
46 
47  /* Fill in UNDI loader structure */
48  undi_loader->PXEptr.segment = rm_cs;
49  undi_loader->PXEptr.offset = __from_text16 ( &ppxe );
50  undi_loader->PXENVptr.segment = rm_cs;
51  undi_loader->PXENVptr.offset = __from_text16 ( &pxenv );
52 
54  return PXENV_EXIT_SUCCESS;
55 }
PXENV_EXIT_t undi_loader(struct s_UNDI_LOADER *undi_loader)
Definition: pxe_loader.c:39
#define ppxe
Definition: pxe_call.h:28
#define __from_text16(pointer)
Definition: libkir.h:23
void initialise(void)
Initialise iPXE.
Definition: init.c:52
#define PXENV_EXIT_SUCCESS
No error occurred.
Definition: pxe_types.h:45
#define rm_cs
Definition: libkir.h:38
#define PXENV_STATUS_SUCCESS
Definition: pxe_error.h:19
#define DBG(...)
Print a debugging message.
Definition: compiler.h:498
#define pxenv
Definition: pxe_call.h:32

References __from_text16, DBG, initialise(), ppxe, pxenv, PXENV_EXIT_SUCCESS, PXENV_STATUS_SUCCESS, rm_cs, and undi_loader().

Referenced by undi_loader().

Variable Documentation

◆ pxe_netdev

struct net_device* pxe_netdev

◆ pxe_cmdline

const char* pxe_cmdline

PXE command line.

Definition at line 48 of file pxe_image.c.

Referenced by pxe_exec(), and pxenv_file_cmdline().