[PXEXT] Update documentation
authorH. Peter Anvin <hpa@zytor.com>
Wed, 26 Mar 2008 22:14:55 +0000 (15:14 -0700)
committerH. Peter Anvin <hpa@zytor.com>
Wed, 26 Mar 2008 22:14:55 +0000 (15:14 -0700)
Add documentation for the FILE_EXEC and FILE_CHECK_API extension
calls, and update the documentation for the FILE_READ call.

src/doc/pxe_extensions

index 0d04fcd..92269cf 100644 (file)
@@ -125,8 +125,9 @@ Output:             PXENV_EXIT_SUCCESS or PXENV_EXIT_FAILURE must be
                This API function is non-blocking.  PXENV_EXIT_SUCCESS
                and PXENV_STATUS_SUCCESS is returned if a data block
                has been transferred into the caller's buffer.
-               PXENV_EXIT_FAILURE and PXENV_STATUS_FAILURE is
-               returned if no data is available to transfer.
+               PXENV_EXIT_FAILURE and PXENV_STATUS_TFTP_OPEN is
+               returned if no data is available to transfer; any
+               other status code reflects an error.
 
 Description:   Read from a previously opened file.
 
@@ -191,3 +192,88 @@ Returned from API service:
 FileSize:      Size of the file in bytes.
 
 Status:                See PXENV_STATUS_xxx constants.
+
+
+
+
+FILE EXEC
+
+Op-Code:       PXENV_FILE_EXEC (00e5h)
+
+Input:         Far pointer to a t_PXENV_FILE_EXEC parameter
+               structure that has been initialized by the caller.
+
+Output:                PXENV_EXIT_SUCCESS or PXENV_EXIT_FAILURE must be
+               returned in AX.  The Status field in the parameter
+               structure must be set to one of the values represented
+               by the PXENV_STATUS_xxx constants.
+
+Description:   Execute a gPXE command.
+
+typedef struct s_PXENV_FILE_EXEC {
+        PXENV_STATUS_t Status;
+        SEGOFF16_t Command;
+} t_PXENV_FILE_EXEC;
+
+
+Set before calling API service:
+
+Command:       Command to execute.  Null terminated.
+
+
+Returned from API service:
+
+Status:                See PXENV_STATUS_xxx constants.
+
+
+
+
+FILE API CHECK
+
+Op-Code:       PXENV_FILE_API_CHECK (00e6h)
+
+Input:         Far pointer to a t_PXENV_FILE_CHECK_API parameter
+               structure that has been initialized by the caller.
+
+               On entry, the Magic field should contain the number
+               0x91d447b2 or the call will fail.
+
+Output:                PXENV_EXIT_SUCCESS or PXENV_EXIT_FAILURE must be
+               returned in AX.  The Status field in the parameter
+               structure must be set to one of the values represented
+               by the PXENV_STATUS_xxx constants.
+
+               If this API is present and the Magic field contains the
+               proper value on entry, AX will contain PXENV_EXIT_SUCCESS,
+               the Status field PXENV_STATUS_SUCCESS, and the Magic field
+               the number 0xe9c17b20.  Any other combination should be
+               considered a failure.
+
+Description:   Detect presence of this API.
+
+
+typedef struct s_PXENV_FILE_CHECK_API {
+       PXENV_STATUS Status;
+       UINT16 Size;
+       UINT32 Magic;
+       UINT32 Provider;
+       UINT32 APIMask;
+       UINT32 Flags;
+} t_PXENV_FILE_CHECK_API;
+
+Set before calling API service:
+
+Size:          Set to sizeof(t_PXENV_FILE_CHECK_API) (20).
+Magic:         Set to 0x91d447b2.
+
+
+Returned from API service:
+
+Size:          Set to the number of bytes filled in (20).
+Magic:         Set to 0xe9c17b20.
+Provider:      Set to 0x45585067 ("gPXE").  Another implementation of this
+               API can use another value, e.g. to indicate a different
+               command set supported by FILE EXEC.
+APIMask:       Bitmask of supported API functions (one bit for each function
+               in the range 00e0h to 00ffh).
+Flags:         Set to zero, reserved for future use.