Initial directory structure of IntelFrameworkPkg.
[mirror_edk2.git] / IntelFrameworkPkg / Include / Protocol / LegacyBios.h
CommitLineData
79964ac8 1/** @file\r
2 The EFI Legacy BIOS Protocol is used to abstract legacy Option ROM usage\r
3 under EFI and Legacy OS boot.\r
4\r
5 Note: The names for EFI_IA32_REGISTER_SET elements were picked to follow\r
6 well known naming conventions.\r
7\r
8 Thunk - A thunk is a transition from one processor mode to another. A Thunk\r
9 is a transition from native EFI mode to 16-bit mode. A reverse thunk\r
10 would be a transition from 16-bit mode to native EFI mode.\r
11\r
12 You most likely should not use this protocol! Find the EFI way to solve the\r
13 problem to make your code portable\r
14\r
15 Copyright (c) 2007, Intel Corporation\r
16 All rights reserved. This program and the accompanying materials\r
17 are licensed and made available under the terms and conditions of the BSD License\r
18 which accompanies this distribution. The full text of the license may be found at\r
19 http://opensource.org/licenses/bsd-license.php\r
20\r
21 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r
22 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
23\r
24 Module Name: LegacyBios.h\r
25\r
26 @par Revision Reference:\r
27 This protocol is defined in Framework for EFI Compatibility Support Module spec\r
28 Version 0.96\r
29\r
30**/\r
31\r
32#ifndef _EFI_LEGACY_BIOS_H_\r
33#define _EFI_LEGACY_BIOS_H_\r
34\r
35#define EFI_LEGACY_BIOS_PROTOCOL_GUID \\r
36 { \\r
37 0xdb9a1e3d, 0x45cb, 0x4abb, {0x85, 0x3b, 0xe5, 0x38, 0x7f, 0xdb, 0x2e, 0x2d } \\r
38 }\r
39\r
40typedef struct _EFI_LEGACY_BIOS_PROTOCOL EFI_LEGACY_BIOS_PROTOCOL;\r
41\r
42//\r
43/// @bug: These macros appear in no specifications and are kept for backward\r
44// compatibility only.\r
45// Convert from 32-bit address (_Adr) to Segment:Offset 16-bit form\r
46//\r
47#define EFI_SEGMENT(_Adr) (UINT16) ((UINT16) (((UINTN) (_Adr)) >> 4) & 0xf000)\r
48#define EFI_OFFSET(_Adr) (UINT16) (((UINT16) ((UINTN) (_Adr))) & 0xffff)\r
49#define BYTE_GRANULARITY 0x01\r
50#define WORD_GRANULARITY 0x02\r
51#define DWORD_GRANULARITY 0x04\r
52#define QWORD_GRANULARITY 0x08\r
53#define PARAGRAPH_GRANULARITY 0x10\r
54\r
55#define CARRY_FLAG 0x01\r
56\r
57//*********************************************************\r
58// EFI_EFLAGS_REG\r
59//*********************************************************\r
60typedef struct {\r
61 UINT32 CF:1;\r
62 UINT32 Reserved1:1;\r
63 UINT32 PF:1;\r
64 UINT32 Reserved2:1;\r
65 UINT32 AF:1;\r
66 UINT32 Reserved3:1;\r
67 UINT32 ZF:1;\r
68 UINT32 SF:1;\r
69 UINT32 TF:1;\r
70 UINT32 IF:1;\r
71 UINT32 DF:1;\r
72 UINT32 OF:1;\r
73 UINT32 IOPL:2;\r
74 UINT32 NT:1;\r
75 UINT32 Reserved4:2;\r
76 UINT32 VM:1;\r
77 UINT32 Reserved5:14;\r
78} EFI_EFLAGS_REG;\r
79\r
80//*********************************************************\r
81// EFI_DWORD_REGS\r
82//*********************************************************\r
83\r
84typedef struct {\r
85 UINT32 EAX;\r
86 UINT32 EBX;\r
87 UINT32 ECX;\r
88 UINT32 EDX;\r
89 UINT32 ESI;\r
90 UINT32 EDI;\r
91 EFI_EFLAGS_REG EFlags;\r
92 UINT16 ES;\r
93 UINT16 CS;\r
94 UINT16 SS;\r
95 UINT16 DS;\r
96 UINT16 FS;\r
97 UINT16 GS;\r
98 UINT32 EBP;\r
99 UINT32 ESP;\r
100} EFI_DWORD_REGS;\r
101\r
102//*******************************************\r
103// EFI_FLAGS_REG\r
104//*******************************************\r
105typedef struct {\r
106 UINT16 CF:1;\r
107 UINT16 Reserved1:1;\r
108 UINT16 PF:1;\r
109 UINT16 Reserved2:1;\r
110 UINT16 AF:1;\r
111 UINT16 Reserved3:1;\r
112 UINT16 ZF:1;\r
113 UINT16 SF:1;\r
114 UINT16 TF:1;\r
115 UINT16 IF:1;\r
116 UINT16 DF:1;\r
117 UINT16 OF:1;\r
118 UINT16 IOPL:2;\r
119 UINT16 NT:1;\r
120 UINT16 Reserved4:1;\r
121} EFI_FLAGS_REG;\r
122\r
123\r
124//*********************************************************\r
125// EFI_WORD_REGS\r
126//*********************************************************\r
127\r
128typedef struct {\r
129 UINT16 AX;\r
130 UINT16 ReservedAX;\r
131 UINT16 BX;\r
132 UINT16 ReservedBX;\r
133 UINT16 CX;\r
134 UINT16 ReservedCX;\r
135 UINT16 DX;\r
136 UINT16 ReservedDX;\r
137 UINT16 SI;\r
138 UINT16 ReservedSI;\r
139 UINT16 DI;\r
140 UINT16 ReservedDI;\r
141 EFI_FLAGS_REG Flags;\r
142 UINT16 ReservedFlags;\r
143 UINT16 ES;\r
144 UINT16 CS;\r
145 UINT16 SS;\r
146 UINT16 DS;\r
147 UINT16 FS;\r
148 UINT16 GS;\r
149 UINT16 BP;\r
150 UINT16 ReservedBP;\r
151 UINT16 SP;\r
152 UINT16 ReservedSP;\r
153} EFI_WORD_REGS;\r
154\r
155//*********************************************************\r
156// EFI_BYTE_REGS\r
157//*********************************************************\r
158\r
159typedef struct {\r
160 UINT8 AL, AH;\r
161 UINT16 ReservedAX;\r
162 UINT8 BL, BH;\r
163 UINT16 ReservedBX;\r
164 UINT8 CL, CH;\r
165 UINT16 ReservedCX;\r
166 UINT8 DL, DH;\r
167 UINT16 ReservedDX;\r
168} EFI_BYTE_REGS;\r
169\r
170typedef union {\r
171 EFI_DWORD_REGS E;\r
172 EFI_WORD_REGS X;\r
173 EFI_BYTE_REGS H;\r
174} EFI_IA32_REGISTER_SET;\r
175\r
176/**\r
177 Thunk to 16-bit real mode and execute a software interrupt with a vector\r
178 of BiosInt. Regs will contain the 16-bit register context on entry and\r
179 exit.\r
180\r
181 @param This Protocol instance pointer.\r
182 @param BiosInt Processor interrupt vector to invoke\r
183 @param Reg Register contexted passed into (and returned) from thunk to\r
184 16-bit mode\r
185\r
186 @retval FALSE Thunk completed, and there were no BIOS errors in the target code.\r
187 See Regs for status.\r
188 @retval TRUE There was a BIOS erro in the target code.\r
189\r
190**/\r
191typedef\r
192BOOLEAN\r
193(EFIAPI *EFI_LEGACY_BIOS_INT86) (\r
194 IN EFI_LEGACY_BIOS_PROTOCOL *This,\r
195 IN UINT8 BiosInt,\r
196 IN OUT EFI_IA32_REGISTER_SET *Regs\r
197 );\r
198\r
199/**\r
200 Thunk to 16-bit real mode and call Segment:Offset. Regs will contain the\r
201 16-bit register context on entry and exit. Arguments can be passed on\r
202 the Stack argument\r
203\r
204 @param This Protocol instance pointer.\r
205 @param Segment Segemnt of 16-bit mode call\r
206 @param Offset Offset of 16-bit mdoe call\r
207 @param Reg Register contexted passed into (and returned) from thunk to\r
208 16-bit mode\r
209 @param Stack Caller allocated stack used to pass arguments\r
210 @param StackSize Size of Stack in bytes\r
211\r
212 @retval FALSE Thunk completed, and there were no BIOS errors in the target code.\r
213 See Regs for status.\r
214 @retval TRUE There was a BIOS erro in the target code.\r
215\r
216**/\r
217typedef\r
218BOOLEAN\r
219(EFIAPI *EFI_LEGACY_BIOS_FARCALL86) (\r
220 IN EFI_LEGACY_BIOS_PROTOCOL *This,\r
221 IN UINT16 Segment,\r
222 IN UINT16 Offset,\r
223 IN EFI_IA32_REGISTER_SET *Regs,\r
224 IN VOID *Stack,\r
225 IN UINTN StackSize\r
226 );\r
227\r
228/**\r
229 Test to see if a legacy PCI ROM exists for this device. Optionally return\r
230 the Legacy ROM instance for this PCI device.\r
231\r
232 @param This Protocol instance pointer.\r
233 @param PciHandle The PCI PC-AT OPROM from this devices ROM BAR will be loaded\r
234 @param RomImage Return the legacy PCI ROM for this device\r
235 @param RomSize Size of ROM Image\r
236 @param Flags Indicates if ROM found and if PC-AT.\r
237\r
238 @retval EFI_SUCCESS Legacy Option ROM availible for this device\r
239 @retval EFI_UNSUPPORTED Legacy Option ROM not supported.\r
240\r
241**/\r
242typedef\r
243EFI_STATUS\r
244(EFIAPI *EFI_LEGACY_BIOS_CHECK_ROM) (\r
245 IN EFI_LEGACY_BIOS_PROTOCOL *This,\r
246 IN EFI_HANDLE PciHandle,\r
247 OUT VOID **RomImage, OPTIONAL\r
248 OUT UINTN *RomSize, OPTIONAL\r
249 OUT UINTN *Flags\r
250 );\r
251\r
252/**\r
253 Load a legacy PC-AT OPROM on the PciHandle device. Return information\r
254 about how many disks were added by the OPROM and the shadow address and\r
255 size. DiskStart & DiskEnd are INT 13h drive letters. Thus 0x80 is C:\r
256\r
257 @param This Protocol instance pointer.\r
258 @param PciHandle The PCI PC-AT OPROM from this devices ROM BAR will be loaded.\r
259 This value is NULL if RomImage is non-NULL. This is the normal\r
260 case.\r
261 @param RomImage A PCI PC-AT ROM image. This argument is non-NULL if there is\r
262 no hardware associated with the ROM and thus no PciHandle,\r
263 otherwise is must be NULL.\r
264 Example is PXE base code.\r
265 @param Flags Return Status if ROM was found and if was Legacy OPROM.\r
266 @param DiskStart Disk number of first device hooked by the ROM. If DiskStart\r
267 is the same as DiskEnd no disked were hooked.\r
268 @param DiskEnd Disk number of the last device hooked by the ROM.\r
269 @param RomShadowAddress Shadow address of PC-AT ROM\r
270 @param RomShadowSize Size of RomShadowAddress in bytes\r
271\r
272 @retval EFI_SUCCESS Thunk completed, see Regs for status.\r
273 @retval EFI_INVALID_PARAMETER PciHandle not found\r
274\r
275**/\r
276typedef\r
277EFI_STATUS\r
278(EFIAPI *EFI_LEGACY_BIOS_INSTALL_ROM) (\r
279 IN EFI_LEGACY_BIOS_PROTOCOL *This,\r
280 IN EFI_HANDLE PciHandle,\r
281 IN VOID **RomImage,\r
282 OUT UINTN *Flags,\r
283 OUT UINT8 *DiskStart, OPTIONAL\r
284 OUT UINT8 *DiskEnd, OPTIONAL\r
285 OUT VOID **RomShadowAddress, OPTIONAL\r
286 OUT UINT32 *ShadowedRomSize OPTIONAL\r
287 );\r
288\r
289/**\r
290 Attempt to legacy boot the BootOption. If the EFI contexted has been\r
291 compromised this function will not return.\r
292\r
293 @param This Protocol instance pointer.\r
294 @param BootOption EFI Device Path from BootXXXX variable.\r
295 @param LoadOptionSize Size of LoadOption in size.\r
296 @param LoadOption LoadOption from BootXXXX variable\r
297\r
298 @retval EFI_SUCCESS Removable media not present\r
299\r
300**/\r
301typedef\r
302EFI_STATUS\r
303(EFIAPI *EFI_LEGACY_BIOS_BOOT) (\r
304 IN EFI_LEGACY_BIOS_PROTOCOL *This,\r
305 IN BBS_BBS_DEVICE_PATH *BootOption,\r
306 IN UINT32 LoadOptionsSize,\r
307 IN VOID *LoadOptions\r
308 );\r
309\r
310/**\r
311 Update BDA with current Scroll, Num & Cap lock LEDS\r
312\r
313 @param This Protocol instance pointer.\r
314 @param Leds Status of current Scroll, Num & Cap lock LEDS\r
315 Bit 0 is Scroll Lock 0 = Not locked\r
316 Bit 1 is Num Lock\r
317 Bit 2 is Caps Lock\r
318\r
319 @retval EFI_SUCCESS Removable media not present\r
320\r
321**/\r
322typedef\r
323EFI_STATUS\r
324(EFIAPI *EFI_LEGACY_BIOS_UPDATE_KEYBOARD_LED_STATUS) (\r
325 IN EFI_LEGACY_BIOS_PROTOCOL *This,\r
326 IN UINT8 Leds\r
327 );\r
328\r
329/**\r
330 Retrieve legacy BBS info and assign boot priority.\r
331\r
332 @param This Protocol instance pointer.\r
333 @param HddCount Number of HDD_INFO structures\r
334 @param HddInfo Onboard IDE controller information\r
335 @param BbsCount Number of BBS_TABLE structures\r
336 @param BbsTable List BBS entries\r
337\r
338 @retval EFI_SUCCESS Tables returned\r
339\r
340**/\r
341typedef\r
342EFI_STATUS\r
343(EFIAPI *EFI_LEGACY_BIOS_GET_BBS_INFO) (\r
344 IN EFI_LEGACY_BIOS_PROTOCOL *This,\r
345 OUT UINT16 *HddCount,\r
346 OUT HDD_INFO **HddInfo,\r
347 OUT UINT16 *BbsCount,\r
348 IN OUT BBS_TABLE **BbsTable\r
349 );\r
350\r
351/**\r
352 Assign drive number to legacy HDD drives prior to booting an EFI\r
353 aware OS so the OS can access drives without an EFI driver.\r
354\r
355 @param This Protocol instance pointer.\r
356 @param BbsCount Number of BBS_TABLE structures\r
357 @param BbsTable List BBS entries\r
358\r
359 @retval EFI_SUCCESS Drive numbers assigned\r
360\r
361**/\r
362typedef\r
363EFI_STATUS\r
364(EFIAPI *EFI_LEGACY_BIOS_PREPARE_TO_BOOT_EFI) (\r
365 IN EFI_LEGACY_BIOS_PROTOCOL *This,\r
366 OUT UINT16 *BbsCount,\r
367 OUT BBS_TABLE **BbsTable\r
368 );\r
369\r
370/**\r
371 To boot from an unconventional device like parties and/or execute\r
372 HDD diagnostics.\r
373\r
374 @param This Protocol instance pointer.\r
375 @param Attributes How to interpret the other input parameters\r
376 @param BbsEntry The 0-based index into the BbsTable for the parent\r
377 device.\r
378 @param BeerData Pointer to the 128 bytes of ram BEER data.\r
379 @param ServiceAreaData Pointer to the 64 bytes of raw Service Area data. The\r
380 caller must provide a pointer to the specific Service\r
381 Area and not the start all Service Areas.\r
382\r
383 EFI_INVALID_PARAMETER if error. Does NOT return if no error.\r
384\r
385**/\r
386typedef\r
387EFI_STATUS\r
388(EFIAPI *EFI_LEGACY_BIOS_BOOT_UNCONVENTIONAL_DEVICE) (\r
389 IN EFI_LEGACY_BIOS_PROTOCOL *This,\r
390 IN UDC_ATTRIBUTES Attributes,\r
391 IN UINTN BbsEntry,\r
392 IN VOID *BeerData,\r
393 IN VOID *ServiceAreaData\r
394 );\r
395\r
396/**\r
397 Shadow all legacy16 OPROMs that haven't been shadowed.\r
398 Warning: Use this with caution. This routine disconnects all EFI\r
399 drivers. If used externally then caller must re-connect EFI\r
400 drivers.\r
401\r
402 @retval EFI_SUCCESS OPROMs shadowed\r
403\r
404**/\r
405typedef\r
406EFI_STATUS\r
407(EFIAPI *EFI_LEGACY_BIOS_SHADOW_ALL_LEGACY_OPROMS) (\r
408 IN EFI_LEGACY_BIOS_PROTOCOL *This\r
409 );\r
410\r
411/**\r
412 Get a region from the LegacyBios for S3 usage.\r
413\r
414 @param This Protocol instance pointer.\r
415 @param LegacyMemorySize Size of required region\r
416 @param Region Region to use.\r
417 00 = Either 0xE0000 or 0xF0000 block\r
418 Bit0 = 1 0xF0000 block\r
419 Bit1 = 1 0xE0000 block\r
420 @param Alignment Address alignment. Bit mapped. First non-zero\r
421 bit from right is alignment.\r
422 @param LegacyMemoryAddress Region Assigned\r
423\r
424 @retval EFI_SUCCESS Region assigned\r
425 @retval Other Region not assigned\r
426\r
427**/\r
428typedef\r
429EFI_STATUS\r
430(EFIAPI *EFI_LEGACY_BIOS_GET_LEGACY_REGION) (\r
431 IN EFI_LEGACY_BIOS_PROTOCOL *This,\r
432 IN UINTN LegacyMemorySize,\r
433 IN UINTN Region,\r
434 IN UINTN Alignment,\r
435 OUT VOID **LegacyMemoryAddress\r
436 );\r
437\r
438/**\r
439 Get a region from the LegacyBios for Tiano usage. Can only be invoked once.\r
440\r
441 @param This Protocol instance pointer.\r
442 @param LegacyMemorySize Size of data to copy\r
443 @param LegacyMemoryAddress Legacy Region destination address\r
444 Note: must be in region assigned by\r
445 LegacyBiosGetLegacyRegion\r
446 @param LegacyMemorySourceAddress\r
447 Source of data\r
448\r
449 @retval EFI_SUCCESS Region assigned\r
450 @retval EFI_ACCESS_DENIED Destination outside assigned region\r
451\r
452**/\r
453typedef\r
454EFI_STATUS\r
455(EFIAPI *EFI_LEGACY_BIOS_COPY_LEGACY_REGION) (\r
456 IN EFI_LEGACY_BIOS_PROTOCOL *This,\r
457 IN UINTN LegacyMemorySize,\r
458 IN VOID *LegacyMemoryAddress,\r
459 IN VOID *LegacyMemorySourceAddress\r
460 );\r
461\r
462/**\r
463 @par Protocol Description:\r
464 Abstracts the traditional BIOS from the rest of EFI. The LegacyBoot()\r
465 member function allows the BDS to support booting a traditional OS.\r
466 EFI thunks drivers that make EFI bindings for BIOS INT services use\r
467 all the other member functions.\r
468\r
469 @param Int86\r
470 Performs traditional software INT. See the Int86() function description.\r
471\r
472 @param FarCall86\r
473 Performs a far call into Compatibility16 or traditional OpROM code.\r
474\r
475 @param CheckPciRom\r
476 Checks if a traditional OpROM exists for this device.\r
477\r
478 @param InstallPciRom\r
479 Loads a traditional OpROM in traditional OpROM address space.\r
480\r
481 @param LegacyBoot\r
482 Boots a traditional OS.\r
483\r
484 @param UpdateKeyboardLedStatus\r
485 Updates BDA to reflect the current EFI keyboard LED status.\r
486\r
487 @param GetBbsInfo\r
488 Allows an external agent, such as BIOS Setup, to get the BBS data.\r
489\r
490 @param ShadowAllLegacyOproms\r
491 Causes all legacy OpROMs to be shadowed.\r
492\r
493 @param PrepareToBootEfi\r
494 Performs all actions prior to boot. Used when booting an EFI-aware OS\r
495 rather than a legacy OS.\r
496\r
497 @param GetLegacyRegion\r
498 Allows EFI to reserve an area in the 0xE0000 or 0xF0000 block.\r
499\r
500 @param CopyLegacyRegion\r
501 Allows EFI to copy data to the area specified by GetLegacyRegion.\r
502\r
503 @param BootUnconventionalDevice\r
504 Allows the user to boot off an unconventional device such as a PARTIES partition.\r
505\r
506**/\r
507struct _EFI_LEGACY_BIOS_PROTOCOL {\r
508 EFI_LEGACY_BIOS_INT86 Int86;\r
509 EFI_LEGACY_BIOS_FARCALL86 FarCall86;\r
510 EFI_LEGACY_BIOS_CHECK_ROM CheckPciRom;\r
511 EFI_LEGACY_BIOS_INSTALL_ROM InstallPciRom;\r
512 EFI_LEGACY_BIOS_BOOT LegacyBoot;\r
513 EFI_LEGACY_BIOS_UPDATE_KEYBOARD_LED_STATUS UpdateKeyboardLedStatus;\r
514 EFI_LEGACY_BIOS_GET_BBS_INFO GetBbsInfo;\r
515 EFI_LEGACY_BIOS_SHADOW_ALL_LEGACY_OPROMS ShadowAllLegacyOproms;\r
516 EFI_LEGACY_BIOS_PREPARE_TO_BOOT_EFI PrepareToBootEfi;\r
517 EFI_LEGACY_BIOS_GET_LEGACY_REGION GetLegacyRegion;\r
518 EFI_LEGACY_BIOS_COPY_LEGACY_REGION CopyLegacyRegion;\r
519 EFI_LEGACY_BIOS_BOOT_UNCONVENTIONAL_DEVICE BootUnconventionalDevice;\r
520};\r
521\r
522extern EFI_GUID gEfiLegacyBiosProtocolGuid;\r
523\r
524#endif\r