qemu/roms/ipxe/src/doc/pxe_extensions

   1 FILE OPEN
   2
   3 Op-Code:        PXENV_FILE_OPEN (00e0h)
   4
   5 Input:          Far pointer to a t_PXENV_FILE_OPEN parameter structure
   6                 that has been initialised by the caller.
   7
   8 Output:         PXENV_EXIT_SUCCESS or PXENV_EXIT_FAILURE must be
   9                 returned in AX.  The status field in the parameter
  10                 structure must be set to one of the values represented
  11                 by the PXENV_STATUS_xxx constants.
  12
  13 Description:    Opens a file specified by a URL for reading.  Multiple
  14                 files may be opened and used concurrently.
  15
  16
  17 typedef struct s_PXENV_FILE_OPEN {
  18         PXENV_STATUS Status;
  19         UINT16 FileHandle;
  20         SEGOFF16 FileName;
  21         UINT32 Reserved;
  22 } t_PXENV_FILE_OPEN;
  23
  24
  25 Set before calling API service:
  26
  27 FileName:       URL of file to be opened.  Null terminated.
  28
  29 Reserved:       Must be zero.
  30
  31
  32 Returned from API service:
  33
  34 FileHandle:     Handle for use in subsequent PXE FILE API calls.
  35
  36 Status:         See PXENV_STATUS_xxx constants.
  37
  38
  39
  40
  41 FILE CLOSE
  42
  43 Op-Code:        PXENV_FILE_CLOSE (00e1h)
  44
  45 Input:          Far pointer to a t_PXENV_FILE_CLOSE parameter structure
  46                 that has been initialised by the caller.
  47
  48 Output:         PXENV_EXIT_SUCCESS or PXENV_EXIT_FAILURE must be
  49                 returned in AX.  The status field in the parameter
  50                 structure must be set to one of the values represented
  51                 by the PXENV_STATUS_xxx constants.
  52
  53 Description:    Closes a previously opened file.
  54
  55
  56 typedef struct s_PXENV_FILE_CLOSE {
  57         PXENV_STATUS Status;
  58         UINT16 FileHandle;
  59 } t_PXENV_FILE_CLOSE;
  60
  61
  62 Set before calling API service:
  63
  64 FileHandle:     Handle obtained when file was opened.
  65
  66
  67 Returned from API service:
  68
  69 Status:         See PXENV_STATUS_xxx constants.
  70
  71
  72
  73
  74 FILE SELECT
  75
  76 Op-Code:        PXENV_FILE_SELECT (00e2h)
  77
  78 Input:          Far pointer to a t_PXENV_FILE_SELECT parameter structure
  79                 that has been initialised by the caller.
  80
  81 Output:         PXENV_EXIT_SUCCESS or PXENV_EXIT_FAILURE must be
  82                 returned in AX.  The status field in the parameter
  83                 structure must be set to one of the values represented
  84                 by the PXENV_STATUS_xxx constants.
  85
  86 Description:    Check a previously opened file's readiness for I/O.
  87
  88
  89 typedef struct s_PXENV_FILE_SELECT {
  90         PXENV_STATUS Status;
  91         UINT16 FileHandle;
  92         UINT16 Ready;
  93 #define RDY_READ 0x0001
  94 } t_PXENV_FILE_SELECT;
  95
  96
  97 Set before calling API service:
  98
  99 FileHandle:     Handle obtained when file was opened.
 100
 101
 102 Returned from API service:
 103
 104 Ready:          Indication of readiness.  This can be zero, or more,
 105                 of the RDY_xxx constants.  Multiple values are
 106                 arithmetically or-ed together.
 107
 108 Status:         See PXENV_STATUS_xxx constants.
 109
 110
 111
 112
 113 FILE READ
 114
 115 Op-Code:        PXENV_FILE_READ (00e3h)
 116
 117 Input:          Far pointer to a t_PXENV_FILE_READ parameter structure
 118                 that has been initialised by the caller.
 119
 120 Output:         PXENV_EXIT_SUCCESS or PXENV_EXIT_FAILURE must be
 121                 returned in AX.  The status field in the parameter
 122                 structure must be set to one of the values represented
 123                 by the PXENV_STATUS_xxx constants.
 124
 125                 This API function is non-blocking.  PXENV_EXIT_SUCCESS
 126                 and PXENV_STATUS_SUCCESS is returned if a data block
 127                 has been transferred into the caller's buffer.
 128                 PXENV_EXIT_FAILURE and PXENV_STATUS_TFTP_OPEN is
 129                 returned if no data is available to transfer; any
 130                 other status code reflects an error.
 131
 132 Description:    Read from a previously opened file.
 133
 134
 135 typedef struct s_PXENV_FILE_READ {
 136         PXENV_STATUS Status;
 137         UINT16 FileHandle;
 138         UINT16 BufferSize;
 139         SEGOFF16 Buffer;
 140 } t_PXENV_FILE_READ;
 141
 142
 143 Set before calling API service:
 144
 145 FileHandle:     Handle obtained when file was opened.
 146
 147 BufferSize:     Maximum number of data bytes that can be copied into
 148                 Buffer.
 149
 150 Buffer:         Segment:Offset address of data buffer.
 151
 152
 153 Returned from API service:
 154
 155 BufferSize:     Number of bytes written to the data buffer.  End of
 156                 file if this is zero.
 157
 158 Status:         See PXENV_STATUS_xxx constants.
 159
 160
 161
 162
 163 GET FILE SIZE
 164
 165 Op-Code:        PXENV_GET_FILE_SIZE (00e4h)
 166
 167 Input:          Far pointer to a t_PXENV_GET_FILE_SIZE parameter
 168                 structure that has been initialised by the caller.
 169
 170 Output:         PXENV_EXIT_SUCCESS or PXENV_EXIT_FAILURE must be
 171                 returned in AX.  The status field in the parameter
 172                 structure must be set to one of the values represented
 173                 by the PXENV_STATUS_xxx constants.
 174
 175 Description:    Determine size of a previously opened file.
 176
 177
 178 typedef struct s_PXENV_GET_FILE_SIZE {
 179         PXENV_STATUS Status;
 180         UINT16 FileHandle;
 181         UINT32 FileSize;
 182 } t_PXENV_GET_FILE_SIZE;
 183
 184
 185 Set before calling API service:
 186
 187 FileHandle:     Handle obtained when file was opened.
 188
 189
 190 Returned from API service:
 191
 192 FileSize:       Size of the file in bytes.
 193
 194 Status:         See PXENV_STATUS_xxx constants.
 195
 196
 197
 198
 199 FILE EXEC
 200
 201 Op-Code:        PXENV_FILE_EXEC (00e5h)
 202
 203 Input:          Far pointer to a t_PXENV_FILE_EXEC parameter
 204                 structure that has been initialized by the caller.
 205
 206 Output:         PXENV_EXIT_SUCCESS or PXENV_EXIT_FAILURE must be
 207                 returned in AX.  The Status field in the parameter
 208                 structure must be set to one of the values represented
 209                 by the PXENV_STATUS_xxx constants.
 210
 211 Description:    Execute a iPXE command.
 212
 213 typedef struct s_PXENV_FILE_EXEC {
 214         PXENV_STATUS_t Status;
 215         SEGOFF16_t Command;
 216 } t_PXENV_FILE_EXEC;
 217
 218
 219 Set before calling API service:
 220
 221 Command:        Command to execute.  Null terminated.
 222
 223
 224 Returned from API service:
 225
 226 Status:         See PXENV_STATUS_xxx constants.
 227
 228
 229
 230
 231 FILE API CHECK
 232
 233 Op-Code:        PXENV_FILE_API_CHECK (00e6h)
 234
 235 Input:          Far pointer to a t_PXENV_FILE_CHECK_API parameter
 236                 structure that has been initialized by the caller.
 237
 238                 On entry, the Magic field should contain the number
 239                 0x91d447b2 or the call will fail.
 240
 241 Output:         PXENV_EXIT_SUCCESS or PXENV_EXIT_FAILURE must be
 242                 returned in AX.  The Status field in the parameter
 243                 structure must be set to one of the values represented
 244                 by the PXENV_STATUS_xxx constants.
 245
 246                 If this API is present and the Magic field contains the
 247                 proper value on entry, AX will contain PXENV_EXIT_SUCCESS,
 248                 the Status field PXENV_STATUS_SUCCESS, and the Magic field
 249                 the number 0xe9c17b20.  Any other combination should be
 250                 considered a failure.
 251
 252 Description:    Detect presence of this API.
 253
 254
 255 typedef struct s_PXENV_FILE_CHECK_API {
 256         PXENV_STATUS Status;
 257         UINT16 Size;
 258         UINT32 Magic;
 259         UINT32 Provider;
 260         UINT32 APIMask;
 261         UINT32 Flags;
 262 } t_PXENV_FILE_CHECK_API;
 263
 264 Set before calling API service:
 265
 266 Size:           Set to sizeof(t_PXENV_FILE_CHECK_API) (20).
 267 Magic:          Set to 0x91d447b2.
 268
 269
 270 Returned from API service:
 271
 272 Size:           Set to the number of bytes filled in (20).
 273 Magic:          Set to 0xe9c17b20.
 274 Provider:       Set to 0x45585067 ("iPXE").  Another implementation of this
 275                 API can use another value, e.g. to indicate a different
 276                 command set supported by FILE EXEC.
 277 APIMask:        Bitmask of supported API functions (one bit for each function
 278                 in the range 00e0h to 00ffh).
 279 Flags:          Set to zero, reserved for future use.
 280
 281
 282
 283
 284 FILE EXIT HOOK
 285
 286 Op-Code:        PXENV_FILE_EXIT_HOOK (00e7h)
 287
 288 Input:          Far pointer to a t_PXENV_FILE_EXIT_HOOK parameter
 289                 structure that has been initialized by the caller.
 290
 291 Output:         PXENV_EXIT_SUCCESS or PXENV_EXIT_FAILURE must be
 292                 returned in AX.  The Status field in the parameter
 293                 structure must be set to one of the values represented
 294                 by the PXENV_STATUS_xxx constants.
 295
 296 Description:    Modify the exit path to jump to the specified code.
 297                 Only valid for pxeprefix-based builds.
 298
 299 typedef struct s_PXENV_FILE_EXIT_HOOK {
 300         PXENV_STATUS_t Status;
 301         SEGOFF16_t Hook;
 302 } t_PXENV_FILE_EXIT_HOOK;
 303
 304
 305 Set before calling API service:
 306
 307 Hook:           The SEG16:OFF16 of the code to jump to.
 308
 309
 310 Returned from API service:
 311
 312 Status:         See PXENV_STATUS_xxx constants.