[fdt] Add ability to parse a MAC address from a flattened device tree
[ipxe.git] / 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.