2 Real Mode Thunk Functions for IA32 and x64.
4 Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR>
5 SPDX-License-Identifier: BSD-2-Clause-Patent
9 #include "BaseLibInternals.h"
11 extern CONST UINT8 m16Start
;
12 extern CONST UINT16 m16Size
;
13 extern CONST UINT16 mThunk16Attr
;
14 extern CONST UINT16 m16Gdt
;
15 extern CONST UINT16 m16GdtrBase
;
16 extern CONST UINT16 mTransition
;
19 Invokes 16-bit code in big real mode and returns the updated register set.
21 This function transfers control to the 16-bit code specified by CS:EIP using
22 the stack specified by SS:ESP in RegisterSet. The updated registers are saved
23 on the real mode stack and the starting address of the save area is returned.
25 @param RegisterSet Values of registers before invocation of 16-bit code.
26 @param Transition The pointer to the transition code under 1MB.
28 @return The pointer to a IA32_REGISTER_SET structure containing the updated
35 IN IA32_REGISTER_SET
*RegisterSet
,
36 IN OUT VOID
*Transition
40 Retrieves the properties for 16-bit thunk functions.
42 Computes the size of the buffer and stack below 1MB required to use the
43 AsmPrepareThunk16(), AsmThunk16() and AsmPrepareAndThunk16() functions. This
44 buffer size is returned in RealModeBufferSize, and the stack size is returned
45 in ExtraStackSize. If parameters are passed to the 16-bit real mode code,
46 then the actual minimum stack size is ExtraStackSize plus the maximum number
47 of bytes that need to be passed to the 16-bit real mode code.
49 If RealModeBufferSize is NULL, then ASSERT().
50 If ExtraStackSize is NULL, then ASSERT().
52 @param RealModeBufferSize A pointer to the size of the buffer below 1MB
53 required to use the 16-bit thunk functions.
54 @param ExtraStackSize A pointer to the extra size of stack below 1MB
55 that the 16-bit thunk functions require for
56 temporary storage in the transition to and from
62 AsmGetThunk16Properties (
63 OUT UINT32
*RealModeBufferSize
,
64 OUT UINT32
*ExtraStackSize
67 ASSERT (RealModeBufferSize
!= NULL
);
68 ASSERT (ExtraStackSize
!= NULL
);
70 *RealModeBufferSize
= m16Size
;
73 // Extra 4 bytes for return address, and another 4 bytes for mode transition
75 *ExtraStackSize
= sizeof (IA32_DWORD_REGS
) + 8;
79 Prepares all structures a code required to use AsmThunk16().
81 Prepares all structures and code required to use AsmThunk16().
83 This interface is limited to be used in either physical mode or virtual modes with paging enabled where the
84 virtual to physical mappings for ThunkContext.RealModeBuffer is mapped 1:1.
86 If ThunkContext is NULL, then ASSERT().
88 @param ThunkContext A pointer to the context structure that describes the
89 16-bit real mode code to call.
95 IN OUT THUNK_CONTEXT
*ThunkContext
98 IA32_SEGMENT_DESCRIPTOR
*RealModeGdt
;
100 ASSERT (ThunkContext
!= NULL
);
101 ASSERT ((UINTN
)ThunkContext
->RealModeBuffer
< 0x100000);
102 ASSERT (ThunkContext
->RealModeBufferSize
>= m16Size
);
103 ASSERT ((UINTN
)ThunkContext
->RealModeBuffer
+ m16Size
<= 0x100000);
105 CopyMem (ThunkContext
->RealModeBuffer
, &m16Start
, m16Size
);
108 // Point RealModeGdt to the GDT to be used in transition
110 // RealModeGdt[0]: Reserved as NULL descriptor
111 // RealModeGdt[1]: Code Segment
112 // RealModeGdt[2]: Data Segment
113 // RealModeGdt[3]: Call Gate
115 RealModeGdt
= (IA32_SEGMENT_DESCRIPTOR
*)(
116 (UINTN
)ThunkContext
->RealModeBuffer
+ m16Gdt
);
119 // Update Code & Data Segment Descriptor
121 RealModeGdt
[1].Bits
.BaseLow
=
122 (UINT32
)(UINTN
)ThunkContext
->RealModeBuffer
& ~0xf;
123 RealModeGdt
[1].Bits
.BaseMid
=
124 (UINT32
)(UINTN
)ThunkContext
->RealModeBuffer
>> 16;
127 // Update transition code entry point offset
129 *(UINT32
*)((UINTN
)ThunkContext
->RealModeBuffer
+ mTransition
) +=
130 (UINT32
)(UINTN
)ThunkContext
->RealModeBuffer
& 0xf;
133 // Update Segment Limits for both Code and Data Segment Descriptors
135 if ((ThunkContext
->ThunkAttributes
& THUNK_ATTRIBUTE_BIG_REAL_MODE
) == 0) {
137 // Set segment limits to 64KB
139 RealModeGdt
[1].Bits
.LimitHigh
= 0;
140 RealModeGdt
[1].Bits
.G
= 0;
141 RealModeGdt
[2].Bits
.LimitHigh
= 0;
142 RealModeGdt
[2].Bits
.G
= 0;
146 // Update GDTBASE for this thunk context
148 *(VOID
**)((UINTN
)ThunkContext
->RealModeBuffer
+ m16GdtrBase
) = RealModeGdt
;
151 // Update Thunk Attributes
153 *(UINT32
*)((UINTN
)ThunkContext
->RealModeBuffer
+ mThunk16Attr
) =
154 ThunkContext
->ThunkAttributes
;
158 Transfers control to a 16-bit real mode entry point and returns the results.
160 Transfers control to a 16-bit real mode entry point and returns the results.
161 AsmPrepareThunk16() must be called with ThunkContext before this function is used.
162 This function must be called with interrupts disabled.
164 The register state from the RealModeState field of ThunkContext is restored just prior
165 to calling the 16-bit real mode entry point. This includes the EFLAGS field of RealModeState,
166 which is used to set the interrupt state when a 16-bit real mode entry point is called.
167 Control is transferred to the 16-bit real mode entry point specified by the CS and Eip fields of RealModeState.
168 The stack is initialized to the SS and ESP fields of RealModeState. Any parameters passed to
169 the 16-bit real mode code must be populated by the caller at SS:ESP prior to calling this function.
170 The 16-bit real mode entry point is invoked with a 16-bit CALL FAR instruction,
171 so when accessing stack contents, the 16-bit real mode code must account for the 16-bit segment
172 and 16-bit offset of the return address that were pushed onto the stack. The 16-bit real mode entry
173 point must exit with a RETF instruction. The register state is captured into RealModeState immediately
174 after the RETF instruction is executed.
176 If EFLAGS specifies interrupts enabled, or any of the 16-bit real mode code enables interrupts,
177 or any of the 16-bit real mode code makes a SW interrupt, then the caller is responsible for making sure
178 the IDT at address 0 is initialized to handle any HW or SW interrupts that may occur while in 16-bit real mode.
180 If EFLAGS specifies interrupts enabled, or any of the 16-bit real mode code enables interrupts,
181 then the caller is responsible for making sure the 8259 PIC is in a state compatible with 16-bit real mode.
182 This includes the base vectors, the interrupt masks, and the edge/level trigger mode.
184 If THUNK_ATTRIBUTE_BIG_REAL_MODE is set in the ThunkAttributes field of ThunkContext, then the user code
185 is invoked in big real mode. Otherwise, the user code is invoked in 16-bit real mode with 64KB segment limits.
187 If neither THUNK_ATTRIBUTE_DISABLE_A20_MASK_INT_15 nor THUNK_ATTRIBUTE_DISABLE_A20_MASK_KBD_CTRL are set in
188 ThunkAttributes, then it is assumed that the user code did not enable the A20 mask, and no attempt is made to
189 disable the A20 mask.
191 If THUNK_ATTRIBUTE_DISABLE_A20_MASK_INT_15 is set and THUNK_ATTRIBUTE_DISABLE_A20_MASK_KBD_CTRL is clear in
192 ThunkAttributes, then attempt to use the INT 15 service to disable the A20 mask. If this INT 15 call fails,
193 then attempt to disable the A20 mask by directly accessing the 8042 keyboard controller I/O ports.
195 If THUNK_ATTRIBUTE_DISABLE_A20_MASK_INT_15 is clear and THUNK_ATTRIBUTE_DISABLE_A20_MASK_KBD_CTRL is set in
196 ThunkAttributes, then attempt to disable the A20 mask by directly accessing the 8042 keyboard controller I/O ports.
198 If ThunkContext is NULL, then ASSERT().
199 If AsmPrepareThunk16() was not previously called with ThunkContext, then ASSERT().
200 If both THUNK_ATTRIBUTE_DISABLE_A20_MASK_INT_15 and THUNK_ATTRIBUTE_DISABLE_A20_MASK_KBD_CTRL are set in
201 ThunkAttributes, then ASSERT().
203 This interface is limited to be used in either physical mode or virtual modes with paging enabled where the
204 virtual to physical mappings for ThunkContext.RealModeBuffer is mapped 1:1.
206 @param ThunkContext A pointer to the context structure that describes the
207 16-bit real mode code to call.
213 IN OUT THUNK_CONTEXT
*ThunkContext
216 IA32_REGISTER_SET
*UpdatedRegs
;
218 ASSERT (ThunkContext
!= NULL
);
219 ASSERT ((UINTN
)ThunkContext
->RealModeBuffer
< 0x100000);
220 ASSERT (ThunkContext
->RealModeBufferSize
>= m16Size
);
221 ASSERT ((UINTN
)ThunkContext
->RealModeBuffer
+ m16Size
<= 0x100000);
223 ((ThunkContext
->ThunkAttributes
& (THUNK_ATTRIBUTE_DISABLE_A20_MASK_INT_15
| THUNK_ATTRIBUTE_DISABLE_A20_MASK_KBD_CTRL
)) != \
224 (THUNK_ATTRIBUTE_DISABLE_A20_MASK_INT_15
| THUNK_ATTRIBUTE_DISABLE_A20_MASK_KBD_CTRL
))
227 UpdatedRegs
= InternalAsmThunk16 (
228 ThunkContext
->RealModeState
,
229 ThunkContext
->RealModeBuffer
232 CopyMem (ThunkContext
->RealModeState
, UpdatedRegs
, sizeof (*UpdatedRegs
));
236 Prepares all structures and code for a 16-bit real mode thunk, transfers
237 control to a 16-bit real mode entry point, and returns the results.
239 Prepares all structures and code for a 16-bit real mode thunk, transfers
240 control to a 16-bit real mode entry point, and returns the results. If the
241 caller only need to perform a single 16-bit real mode thunk, then this
242 service should be used. If the caller intends to make more than one 16-bit
243 real mode thunk, then it is more efficient if AsmPrepareThunk16() is called
244 once and AsmThunk16() can be called for each 16-bit real mode thunk.
246 This interface is limited to be used in either physical mode or virtual modes with paging enabled where the
247 virtual to physical mappings for ThunkContext.RealModeBuffer is mapped 1:1.
249 See AsmPrepareThunk16() and AsmThunk16() for the detailed description and ASSERT() conditions.
251 @param ThunkContext A pointer to the context structure that describes the
252 16-bit real mode code to call.
257 AsmPrepareAndThunk16 (
258 IN OUT THUNK_CONTEXT
*ThunkContext
261 AsmPrepareThunk16 (ThunkContext
);
262 AsmThunk16 (ThunkContext
);