bs3kit.h@ 102127

Last change on this file since 102127 was 102127, checked in by vboxsync, 18 months ago
ValKit/bs3kit: Added Bs3SelLnkCodePtrToCurPtr and Bs3SelRealModeCodeToProtFar16; fixed some wlink segment name typos (harmless); and added a segment between BS3X1TEXT16_END and BS3TEXT32 to better tell linker errors apart. bugref:10371
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 184.2 KB

Line
1	/* $Id: bs3kit.h 102127 2023-11-16 22:39:49Z vboxsync $ */
2	/** @file
3	* BS3Kit - structures, symbols, macros and stuff.
4	*/
5
6	/*
7	* Copyright (C) 2007-2023 Oracle and/or its affiliates.
8	*
9	* This file is part of VirtualBox base platform packages, as
10	* available from https://www.215389.xyz.
11	*
12	* This program is free software; you can redistribute it and/or
13	* modify it under the terms of the GNU General Public License
14	* as published by the Free Software Foundation, in version 3 of the
15	* License.
16	*
17	* This program is distributed in the hope that it will be useful, but
18	* WITHOUT ANY WARRANTY; without even the implied warranty of
19	* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
20	* General Public License for more details.
21	*
22	* You should have received a copy of the GNU General Public License
23	* along with this program; if not, see <https://www.gnu.org/licenses>.
24	*
25	* The contents of this file may alternatively be used under the terms
26	* of the Common Development and Distribution License Version 1.0
27	* (CDDL), a copy of it is provided in the "COPYING.CDDL" file included
28	* in the VirtualBox distribution, in which case the provisions of the
29	* CDDL are applicable instead of those of the GPL.
30	*
31	* You may elect to license modified versions of this file under the
32	* terms and conditions of either the GPL or the CDDL or both.
33	*
34	* SPDX-License-Identifier: GPL-3.0-only OR CDDL-1.0
35	*/
36
37	#ifndef BS3KIT_INCLUDED_bs3kit_h
38	#define BS3KIT_INCLUDED_bs3kit_h
39	#ifndef RT_WITHOUT_PRAGMA_ONCE
40	# pragma once
41	#endif
42
43	#ifndef DOXYGEN_RUNNING
44	# undef IN_RING0
45	# define IN_RING0
46	#endif
47
48	#define RT_NO_STRICT /* Don't drag in IPRT assertion code in inline code we may use (asm.h). */
49	#include <iprt/cdefs.h>
50	#include <iprt/types.h>
51
52	#ifndef DOXYGEN_RUNNING
53	# undef IN_RING0
54	#endif
55
56	/*
57	* Make asm.h and friend compatible with our 64-bit assembly config (ASM_CALL64_MSC).
58	*/
59	#if defined(__GNUC__) && ARCH_BITS == 64
60	# undef DECLASM
61	# ifdef __cplusplus
62	# define DECLASM(type) extern "C" type BS3_CALL
63	# else
64	# define DECLASM(type) type BS3_CALL
65	# endif
66	#endif
67
68
69	/*
70	* Work around ms_abi trouble in the gcc camp (gcc bugzilla #50818).
71	* ASSUMES all va_lists are in functions with
72	*/
73	#if defined(__GNUC__) && ARCH_BITS == 64
74	# undef va_list
75	# undef va_start
76	# undef va_end
77	# undef va_copy
78	# define va_list __builtin_ms_va_list
79	# define va_start(a_Va, a_Arg) __builtin_ms_va_start(a_Va, a_Arg)
80	# define va_end(a_Va) __builtin_ms_va_end(a_Va)
81	# define va_copy(a_DstVa, a_SrcVa) __builtin_ms_va_copy(a_DstVa, a_SrcVa)
82	#endif
83
84
85	/** @def BS3_USE_ALT_16BIT_TEXT_SEG
86	* @ingroup grp_bs3kit
87	* Combines the BS3_USE_RM_TEXT_SEG, BS3_USE_X0_TEXT_SEG, and
88	* BS3_USE_X1_TEXT_SEG indicators into a single one.
89	*/
90	#if defined(BS3_USE_RM_TEXT_SEG) \|\| defined(BS3_USE_X0_TEXT_SEG) \|\| defined(BS3_USE_X1_TEXT_SEG) \|\| defined(DOXYGEN_RUNNING)
91	# define BS3_USE_ALT_16BIT_TEXT_SEG
92	#else
93	# undef BS3_USE_ALT_16BIT_TEXT_SEG
94	#endif
95
96	/** @def BS3_USE_X0_TEXT_SEG
97	* @ingroup grp_bs3kit
98	* Emit 16-bit code to the BS3X0TEXT16 segment - ignored for 32-bit and 64-bit.
99	*
100	* Calling directly into the BS3X0TEXT16 segment is only possible in real-mode
101	* and v8086 mode. In protected mode the real far pointer have to be converted
102	* to a protected mode pointer that uses BS3_SEL_X0TEXT16_CS, Bs3TestDoModes and
103	* associates does this automatically.
104	*/
105	#ifdef DOXYGEN_RUNNING
106	# define BS3_USE_X0_TEXT_SEG
107	#endif
108
109	/** @def BS3_USE_X1_TEXT_SEG
110	* @ingroup grp_bs3kit
111	* Emit 16-bit code to the BS3X1TEXT16 segment - ignored for 32-bit and 64-bit.
112	*
113	* Calling directly into the BS3X1TEXT16 segment is only possible in real-mode
114	* and v8086 mode. In protected mode the real far pointer have to be converted
115	* to a protected mode pointer that uses BS3_SEL_X1TEXT16_CS, Bs3TestDoModes and
116	* associates does this automatically.
117	*/
118	#ifdef DOXYGEN_RUNNING
119	# define BS3_USE_X1_TEXT_SEG
120	#endif
121
122	/** @def BS3_USE_RM_TEXT_SEG
123	* @ingroup grp_bs3kit
124	* Emit 16-bit code to the BS3RMTEXT16 segment - ignored for 32-bit and 64-bit.
125	*
126	* This segment is normally used for real-mode only code, though
127	* BS3_SEL_RMTEXT16_CS can be used to call it from protected mode. Unlike the
128	* BS3X0TEXT16 and BS3X1TEXT16 segments which are empty by default, this segment
129	* is used by common BS3Kit code.
130	*/
131	#ifdef DOXYGEN_RUNNING
132	# define BS3_USE_X0_TEXT_SEG
133	#endif
134
135	/** @def BS3_MODEL_FAR_CODE
136	* @ingroup grp_bs3kit
137	* Default compiler model indicates far code.
138	*/
139	#ifdef DOXYGEN_RUNNING
140	# define BS3_MODEL_FAR_CODE
141	#elif !defined(BS3_MODEL_FAR_CODE) && (defined(__LARGE__) \|\| defined(__MEDIUM__) \|\| defined(__HUGE__)) && ARCH_BITS == 16
142	# define BS3_MODEL_FAR_CODE
143	#endif
144
145
146	/*
147	* We normally don't want the noreturn / aborts attributes as they mess up stack traces.
148	*
149	* Note! pragma aux <fnname> aborts can only be used with functions
150	* implemented in C and functions that does not have parameters.
151	*/
152	#define BS3_KIT_WITH_NO_RETURN
153	#ifndef BS3_KIT_WITH_NO_RETURN
154	# undef DECL_NO_RETURN
155	# define DECL_NO_RETURN(type) type
156	#endif
157
158
159	/*
160	* We may want to reuse some IPRT code in the common name space, so we
161	* redefine the RT_MANGLER to work like BS3_CMN_NM. (We cannot use
162	* BS3_CMN_NM yet, as we need to include IPRT headers with function
163	* declarations before we can define it. Thus the duplciate effort.)
164	*/
165	#if ARCH_BITS == 16
166	# undef RTCALL
167	# if defined(BS3_USE_ALT_16BIT_TEXT_SEG)
168	# define RTCALL __cdecl __far
169	# define RT_MANGLER(a_Name) RT_CONCAT(a_Name,_f16)
170	# else
171	# define RTCALL __cdecl __near
172	# define RT_MANGLER(a_Name) RT_CONCAT(a_Name,_c16)
173	# endif
174	#else
175	# define RT_MANGLER(a_Name) RT_CONCAT3(a_Name,_c,ARCH_BITS)
176	#endif
177	#include <iprt/mangling.h>
178	#include <iprt/x86.h>
179	#include <iprt/err.h>
180
181	/*
182	* Include data symbol mangling (function mangling/mapping must be done
183	* after the protypes).
184	*/
185	#include "bs3kit-mangling-data.h"
186
187
188
189	RT_C_DECLS_BEGIN
190
191	/** @defgroup grp_bs3kit BS3Kit - Boot Sector Kit \#3
192	*
193	* The BS3Kit is a framework for bare metal floppy/usb image tests,
194	* see the @ref pg_bs3kit "doc page" for more.
195	*
196	* @{ */
197
198	/** @name Execution modes.
199	* @{ */
200	#define BS3_MODE_INVALID UINT8_C(0x00)
201	#define BS3_MODE_RM UINT8_C(0x01) /*< real mode. /
202	#define BS3_MODE_PE16 UINT8_C(0x11) /*< 16-bit protected mode kernel+tss, running 16-bit code, unpaged. /
203	#define BS3_MODE_PE16_32 UINT8_C(0x12) /*< 16-bit protected mode kernel+tss, running 32-bit code, unpaged. /
204	#define BS3_MODE_PE16_V86 UINT8_C(0x18) /*< 16-bit protected mode kernel+tss, running virtual 8086 mode code, unpaged. /
205	#define BS3_MODE_PE32 UINT8_C(0x22) /*< 32-bit protected mode kernel+tss, running 32-bit code, unpaged. /
206	#define BS3_MODE_PE32_16 UINT8_C(0x21) /*< 32-bit protected mode kernel+tss, running 16-bit code, unpaged. /
207	#define BS3_MODE_PEV86 UINT8_C(0x28) /*< 32-bit protected mode kernel+tss, running virtual 8086 mode code, unpaged. /
208	#define BS3_MODE_PP16 UINT8_C(0x31) /*< 16-bit protected mode kernel+tss, running 16-bit code, paged. /
209	#define BS3_MODE_PP16_32 UINT8_C(0x32) /*< 16-bit protected mode kernel+tss, running 32-bit code, paged. /
210	#define BS3_MODE_PP16_V86 UINT8_C(0x38) /*< 16-bit protected mode kernel+tss, running virtual 8086 mode code, paged. /
211	#define BS3_MODE_PP32 UINT8_C(0x42) /*< 32-bit protected mode kernel+tss, running 32-bit code, paged. /
212	#define BS3_MODE_PP32_16 UINT8_C(0x41) /*< 32-bit protected mode kernel+tss, running 16-bit code, paged. /
213	#define BS3_MODE_PPV86 UINT8_C(0x48) /*< 32-bit protected mode kernel+tss, running virtual 8086 mode code, paged. /
214	#define BS3_MODE_PAE16 UINT8_C(0x51) /*< 16-bit protected mode kernel+tss, running 16-bit code, PAE paging. /
215	#define BS3_MODE_PAE16_32 UINT8_C(0x52) /*< 16-bit protected mode kernel+tss, running 32-bit code, PAE paging. /
216	#define BS3_MODE_PAE16_V86 UINT8_C(0x58) /*< 16-bit protected mode kernel+tss, running virtual 8086 mode, PAE paging. /
217	#define BS3_MODE_PAE32 UINT8_C(0x62) /*< 32-bit protected mode kernel+tss, running 32-bit code, PAE paging. /
218	#define BS3_MODE_PAE32_16 UINT8_C(0x61) /*< 32-bit protected mode kernel+tss, running 16-bit code, PAE paging. /
219	#define BS3_MODE_PAEV86 UINT8_C(0x68) /*< 32-bit protected mode kernel+tss, running virtual 8086 mode, PAE paging. /
220	#define BS3_MODE_LM16 UINT8_C(0x71) /*< 16-bit long mode (paged), kernel+tss always 64-bit. /
221	#define BS3_MODE_LM32 UINT8_C(0x72) /*< 32-bit long mode (paged), kernel+tss always 64-bit. /
222	#define BS3_MODE_LM64 UINT8_C(0x74) /*< 64-bit long mode (paged), kernel+tss always 64-bit. /
223
224	#define BS3_MODE_CODE_MASK UINT8_C(0x0f) /*< Running code mask. /
225	#define BS3_MODE_CODE_16 UINT8_C(0x01) /*< Running 16-bit code. /
226	#define BS3_MODE_CODE_32 UINT8_C(0x02) /*< Running 32-bit code. /
227	#define BS3_MODE_CODE_64 UINT8_C(0x04) /*< Running 64-bit code. /
228	#define BS3_MODE_CODE_V86 UINT8_C(0x08) /*< Running 16-bit virtual 8086 code. /
229
230	#define BS3_MODE_SYS_MASK UINT8_C(0xf0) /*< kernel+tss mask. /
231	#define BS3_MODE_SYS_RM UINT8_C(0x00) /*< Real mode kernel+tss. /
232	#define BS3_MODE_SYS_PE16 UINT8_C(0x10) /*< 16-bit protected mode kernel+tss. /
233	#define BS3_MODE_SYS_PE32 UINT8_C(0x20) /*< 32-bit protected mode kernel+tss. /
234	#define BS3_MODE_SYS_PP16 UINT8_C(0x30) /*< 16-bit paged protected mode kernel+tss. /
235	#define BS3_MODE_SYS_PP32 UINT8_C(0x40) /*< 32-bit paged protected mode kernel+tss. /
236	#define BS3_MODE_SYS_PAE16 UINT8_C(0x50) /*< 16-bit PAE paged protected mode kernel+tss. /
237	#define BS3_MODE_SYS_PAE32 UINT8_C(0x60) /*< 32-bit PAE paged protected mode kernel+tss. /
238	#define BS3_MODE_SYS_LM UINT8_C(0x70) /*< 64-bit (paged) long mode protected mode kernel+tss. /
239
240	/** Whether the mode has paging enabled. */
241	#define BS3_MODE_IS_PAGED(a_fMode) ((a_fMode) >= BS3_MODE_PP16)
242	/** Whether the mode has legacy paging enabled (legacy as opposed to PAE or
243	* long mode). */
244	#define BS3_MODE_IS_LEGACY_PAGING(a_fMode) ((a_fMode) >= BS3_MODE_PP16 && (a_fMode) < BS3_MODE_PAE16)
245
246	/** Whether the mode is running v8086 code. */
247	#define BS3_MODE_IS_V86(a_fMode) (((a_fMode) & BS3_MODE_CODE_MASK) == BS3_MODE_CODE_V86)
248	/** Whether the we're executing in real mode or v8086 mode. */
249	#define BS3_MODE_IS_RM_OR_V86(a_fMode) ((a_fMode) == BS3_MODE_RM \|\| BS3_MODE_IS_V86(a_fMode))
250	/** Whether the mode is running 16-bit code, except v8086. */
251	#define BS3_MODE_IS_16BIT_CODE_NO_V86(a_fMode) (((a_fMode) & BS3_MODE_CODE_MASK) == BS3_MODE_CODE_16)
252	/** Whether the mode is running 16-bit code (includes v8086). */
253	#define BS3_MODE_IS_16BIT_CODE(a_fMode) (BS3_MODE_IS_16BIT_CODE_NO_V86(a_fMode) \|\| BS3_MODE_IS_V86(a_fMode))
254	/** Whether the mode is running 32-bit code. */
255	#define BS3_MODE_IS_32BIT_CODE(a_fMode) (((a_fMode) & BS3_MODE_CODE_MASK) == BS3_MODE_CODE_32)
256	/** Whether the mode is running 64-bit code. */
257	#define BS3_MODE_IS_64BIT_CODE(a_fMode) (((a_fMode) & BS3_MODE_CODE_MASK) == BS3_MODE_CODE_64)
258
259	/** Whether the system is in real mode. */
260	#define BS3_MODE_IS_RM_SYS(a_fMode) (((a_fMode) & BS3_MODE_SYS_MASK) == BS3_MODE_SYS_RM)
261	/** Whether the system is some 16-bit mode that isn't real mode. */
262	#define BS3_MODE_IS_16BIT_SYS_NO_RM(a_fMode) ( ((a_fMode) & BS3_MODE_SYS_MASK) == BS3_MODE_SYS_PE16 \
263	\|\| ((a_fMode) & BS3_MODE_SYS_MASK) == BS3_MODE_SYS_PP16 \
264	\|\| ((a_fMode) & BS3_MODE_SYS_MASK) == BS3_MODE_SYS_PAE16)
265	/** Whether the system is some 16-bit mode (includes real mode). */
266	#define BS3_MODE_IS_16BIT_SYS(a_fMode) (BS3_MODE_IS_16BIT_SYS_NO_RM(a_fMode) \|\| BS3_MODE_IS_RM_SYS(a_fMode))
267	/** Whether the system is some 32-bit mode. */
268	#define BS3_MODE_IS_32BIT_SYS(a_fMode) ( ((a_fMode) & BS3_MODE_SYS_MASK) == BS3_MODE_SYS_PE32 \
269	\|\| ((a_fMode) & BS3_MODE_SYS_MASK) == BS3_MODE_SYS_PP32 \
270	\|\| ((a_fMode) & BS3_MODE_SYS_MASK) == BS3_MODE_SYS_PAE32)
271	/** Whether the system is long mode. */
272	#define BS3_MODE_IS_64BIT_SYS(a_fMode) (((a_fMode) & BS3_MODE_SYS_MASK) == BS3_MODE_SYS_LM)
273
274	/** Whether the system is in protected mode (with or without paging).
275	* @note Long mode is not included. */
276	#define BS3_MODE_IS_PM_SYS(a_fMode) ((a_fMode) >= BS3_MODE_SYS_PE16 && (a_fMode) < BS3_MODE_SYS_LM)
277
278	/** @todo testcase: How would long-mode handle a 16-bit TSS loaded prior to the switch? (mainly stack switching wise) Hopefully, it will tripple fault, right? */
279	/** @} */
280
281
282	/** @name BS3_ADDR_XXX - Static Memory Allocation
283	* @{ */
284	/** The flat load address for the code after the bootsector. */
285	#define BS3_ADDR_LOAD 0x10000
286	/** Where we save the boot registers during init.
287	* Located right before the code. */
288	#define BS3_ADDR_REG_SAVE (BS3_ADDR_LOAD - sizeof(BS3REGCTX) - 8)
289	/** Where the stack starts (initial RSP value).
290	* Located 16 bytes (assumed by boot sector) before the saved registers.
291	* SS.BASE=0. The size is a little short of 32KB */
292	#define BS3_ADDR_STACK (BS3_ADDR_REG_SAVE - 16)
293	/** The ring-0 stack (8KB) for ring transitions. */
294	#define BS3_ADDR_STACK_R0 0x06000
295	/** The ring-1 stack (8KB) for ring transitions. */
296	#define BS3_ADDR_STACK_R1 0x04000
297	/** The ring-2 stack (8KB) for ring transitions. */
298	#define BS3_ADDR_STACK_R2 0x02000
299	/** IST1 ring-0 stack for long mode (4KB), used for double faults elsewhere. */
300	#define BS3_ADDR_STACK_R0_IST1 0x09000
301	/** IST2 ring-0 stack for long mode (3KB), used for spare 0 stack elsewhere. */
302	#define BS3_ADDR_STACK_R0_IST2 0x08000
303	/** IST3 ring-0 stack for long mode (1KB). */
304	#define BS3_ADDR_STACK_R0_IST3 0x07400
305	/** IST4 ring-0 stack for long mode (1KB), used for spare 1 stack elsewhere. */
306	#define BS3_ADDR_STACK_R0_IST4 0x07000
307	/** IST5 ring-0 stack for long mode (1KB). */
308	#define BS3_ADDR_STACK_R0_IST5 0x06c00
309	/** IST6 ring-0 stack for long mode (1KB). */
310	#define BS3_ADDR_STACK_R0_IST6 0x06800
311	/** IST7 ring-0 stack for long mode (1KB). */
312	#define BS3_ADDR_STACK_R0_IST7 0x06400
313
314	/** The base address of the BS3TEXT16 segment (same as BS3_LOAD_ADDR).
315	* @sa BS3_SEL_TEXT16 */
316	#define BS3_ADDR_BS3TEXT16 0x10000
317	/** The base address of the BS3SYSTEM16 segment.
318	* @sa BS3_SEL_SYSTEM16 */
319	#define BS3_ADDR_BS3SYSTEM16 0x20000
320	/** The base address of the BS3DATA16/BS3KIT_GRPNM_DATA16 segment.
321	* @sa BS3_SEL_DATA16 */
322	#define BS3_ADDR_BS3DATA16 0x29000
323	/** @} */
324
325	/** @name BS3_SEL_XXX - GDT selector assignments.
326	*
327	* The real mode segment numbers for BS16TEXT, BS16DATA and BS16SYSTEM are
328	* present in the GDT, this allows the 16-bit C/C++ and assembly code to
329	* continue using the real mode segment values in ring-0 protected mode.
330	*
331	* The three segments have fixed locations:
332	* \| segment \| flat address \| real mode segment \|
333	* \| ----------- \| ------------ \| ----------------- \|
334	* \| BS3TEXT16 \| 0x00010000 \| 1000h \|
335	* \| BS3SYSTEM16 \| 0x00020000 \| 2000h \|
336	* \| BS3DATA16 \| 0x00029000 \| 2900h \|
337	*
338	* This means that we've got a lot of GDT space to play around with.
339	*
340	* @{ */
341	#define BS3_SEL_LDT 0x0010 /*< The LDT selector for Bs3Ldt. /
342	#define BS3_SEL_TSS16 0x0020 /*< The 16-bit TSS selector. /
343	#define BS3_SEL_TSS16_DF 0x0028 /*< The 16-bit TSS selector for double faults. /
344	#define BS3_SEL_TSS16_SPARE0 0x0030 /*< The 16-bit TSS selector for testing. /
345	#define BS3_SEL_TSS16_SPARE1 0x0038 /*< The 16-bit TSS selector for testing. /
346	#define BS3_SEL_TSS32 0x0040 /*< The 32-bit TSS selector. /
347	#define BS3_SEL_TSS32_DF 0x0048 /*< The 32-bit TSS selector for double faults. /
348	#define BS3_SEL_TSS32_SPARE0 0x0050 /*< The 32-bit TSS selector for testing. /
349	#define BS3_SEL_TSS32_SPARE1 0x0058 /*< The 32-bit TSS selector for testing. /
350	#define BS3_SEL_TSS32_IOBP_IRB 0x0060 /*< The 32-bit TSS selector with I/O permission and interrupt redirection bitmaps. /
351	#define BS3_SEL_TSS32_IRB 0x0068 /*< The 32-bit TSS selector with only interrupt redirection bitmap (IOPB stripped by limit). /
352	#define BS3_SEL_TSS64 0x0070 /*< The 64-bit TSS selector. /
353	#define BS3_SEL_TSS64_SPARE0 0x0080 /*< The 64-bit TSS selector. /
354	#define BS3_SEL_TSS64_SPARE1 0x0090 /*< The 64-bit TSS selector. /
355	#define BS3_SEL_TSS64_IOBP 0x00a0 /*< The 64-bit TSS selector. /
356
357	#define BS3_SEL_RMTEXT16_CS 0x00e0 /*< Conforming code selector for accessing the BS3RMTEXT16 segment. Runtime config. /
358	#define BS3_SEL_X0TEXT16_CS 0x00e8 /*< Conforming code selector for accessing the BS3X0TEXT16 segment. Runtime config. /
359	#define BS3_SEL_X1TEXT16_CS 0x00f0 /*< Conforming code selector for accessing the BS3X1TEXT16 segment. Runtime config. /
360	#define BS3_SEL_VMMDEV_MMIO16 0x00f8 /*< Selector for accessing the VMMDev MMIO segment at 00df000h from 16-bit code. /
361
362	/** Checks if @a uSel is in the BS3_SEL_RX_XXX range. */
363	#define BS3_SEL_IS_IN_RING_RANGE(uSel) ( (unsigned)(uSel - BS3_SEL_R0_FIRST) < (unsigned)(4 << BS3_SEL_RING_SHIFT) )
364	#define BS3_SEL_RING_SHIFT 8 /*< For the formula: BS3_SEL_R0_XXX + ((cs & 3) << BS3_SEL_RING_SHIFT) /
365	#define BS3_SEL_RING_SUB_MASK 0x00f8 /*< Mask for getting the sub-selector. For use with BS3_SEL_R_FIRST. */
366
367	/** Checks if @a uSel is in the BS3_SEL_R0_XXX range. */
368	#define BS3_SEL_IS_IN_R0_RANGE(uSel) ( (unsigned)(uSel - BS3_SEL_R0_FIRST) < (unsigned)(1 << BS3_SEL_RING_SHIFT) )
369	#define BS3_SEL_R0_FIRST 0x0100 /*< The first selector in the ring-0 block. /
370	#define BS3_SEL_R0_CS16 0x0100 /*< ring-0: 16-bit code selector, base 0x10000. /
371	#define BS3_SEL_R0_DS16 0x0108 /*< ring-0: 16-bit data selector, base 0x23000. /
372	#define BS3_SEL_R0_SS16 0x0110 /*< ring-0: 16-bit stack selector, base 0x00000. /
373	#define BS3_SEL_R0_CS32 0x0118 /*< ring-0: 32-bit flat code selector. /
374	#define BS3_SEL_R0_DS32 0x0120 /*< ring-0: 32-bit flat data selector. /
375	#define BS3_SEL_R0_SS32 0x0128 /*< ring-0: 32-bit flat stack selector. /
376	#define BS3_SEL_R0_CS64 0x0130 /*< ring-0: 64-bit flat code selector. /
377	#define BS3_SEL_R0_DS64 0x0138 /*< ring-0: 64-bit flat data & stack selector. /
378	#define BS3_SEL_R0_CS16_EO 0x0140 /*< ring-0: 16-bit execute-only code selector, not accessed, 0xfffe limit, CS16 base. /
379	#define BS3_SEL_R0_CS16_CNF 0x0148 /*< ring-0: 16-bit conforming code selector, not accessed, 0xfffe limit, CS16 base. /
380	#define BS3_SEL_R0_CS16_CNF_EO 0x0150 /*< ring-0: 16-bit execute-only conforming code selector, not accessed, 0xfffe limit, CS16 base. /
381	#define BS3_SEL_R0_CS32_EO 0x0158 /*< ring-0: 32-bit execute-only code selector, not accessed, flat. /
382	#define BS3_SEL_R0_CS32_CNF 0x0160 /*< ring-0: 32-bit conforming code selector, not accessed, flat. /
383	#define BS3_SEL_R0_CS32_CNF_EO 0x0168 /*< ring-0: 32-bit execute-only conforming code selector, not accessed, flat. /
384	#define BS3_SEL_R0_CS64_EO 0x0170 /*< ring-0: 64-bit execute-only code selector, not accessed, flat. /
385	#define BS3_SEL_R0_CS64_CNF 0x0178 /*< ring-0: 64-bit conforming code selector, not accessed, flat. /
386	#define BS3_SEL_R0_CS64_CNF_EO 0x0180 /*< ring-0: 64-bit execute-only conforming code selector, not accessed, flat. /
387
388	#define BS3_SEL_R1_FIRST 0x0200 /*< The first selector in the ring-1 block. /
389	#define BS3_SEL_R1_CS16 0x0200 /*< ring-1: 16-bit code selector, base 0x10000. /
390	#define BS3_SEL_R1_DS16 0x0208 /*< ring-1: 16-bit data selector, base 0x23000. /
391	#define BS3_SEL_R1_SS16 0x0210 /*< ring-1: 16-bit stack selector, base 0x00000. /
392	#define BS3_SEL_R1_CS32 0x0218 /*< ring-1: 32-bit flat code selector. /
393	#define BS3_SEL_R1_DS32 0x0220 /*< ring-1: 32-bit flat data selector. /
394	#define BS3_SEL_R1_SS32 0x0228 /*< ring-1: 32-bit flat stack selector. /
395	#define BS3_SEL_R1_CS64 0x0230 /*< ring-1: 64-bit flat code selector. /
396	#define BS3_SEL_R1_DS64 0x0238 /*< ring-1: 64-bit flat data & stack selector. /
397	#define BS3_SEL_R1_CS16_EO 0x0240 /*< ring-1: 16-bit execute-only code selector, not accessed, 0xfffe limit, CS16 base. /
398	#define BS3_SEL_R1_CS16_CNF 0x0248 /*< ring-1: 16-bit conforming code selector, not accessed, 0xfffe limit, CS16 base. /
399	#define BS3_SEL_R1_CS16_CNF_EO 0x0250 /*< ring-1: 16-bit execute-only conforming code selector, not accessed, 0xfffe limit, CS16 base. /
400	#define BS3_SEL_R1_CS32_EO 0x0258 /*< ring-1: 32-bit execute-only code selector, not accessed, flat. /
401	#define BS3_SEL_R1_CS32_CNF 0x0260 /*< ring-1: 32-bit conforming code selector, not accessed, flat. /
402	#define BS3_SEL_R1_CS32_CNF_EO 0x0268 /*< ring-1: 32-bit execute-only conforming code selector, not accessed, flat. /
403	#define BS3_SEL_R1_CS64_EO 0x0270 /*< ring-1: 64-bit execute-only code selector, not accessed, flat. /
404	#define BS3_SEL_R1_CS64_CNF 0x0278 /*< ring-1: 64-bit conforming code selector, not accessed, flat. /
405	#define BS3_SEL_R1_CS64_CNF_EO 0x0280 /*< ring-1: 64-bit execute-only conforming code selector, not accessed, flat. /
406
407	#define BS3_SEL_R2_FIRST 0x0300 /*< The first selector in the ring-2 block. /
408	#define BS3_SEL_R2_CS16 0x0300 /*< ring-2: 16-bit code selector, base 0x10000. /
409	#define BS3_SEL_R2_DS16 0x0308 /*< ring-2: 16-bit data selector, base 0x23000. /
410	#define BS3_SEL_R2_SS16 0x0310 /*< ring-2: 16-bit stack selector, base 0x00000. /
411	#define BS3_SEL_R2_CS32 0x0318 /*< ring-2: 32-bit flat code selector. /
412	#define BS3_SEL_R2_DS32 0x0320 /*< ring-2: 32-bit flat data selector. /
413	#define BS3_SEL_R2_SS32 0x0328 /*< ring-2: 32-bit flat stack selector. /
414	#define BS3_SEL_R2_CS64 0x0330 /*< ring-2: 64-bit flat code selector. /
415	#define BS3_SEL_R2_DS64 0x0338 /*< ring-2: 64-bit flat data & stack selector. /
416	#define BS3_SEL_R2_CS16_EO 0x0340 /*< ring-2: 16-bit execute-only code selector, not accessed, 0xfffe limit, CS16 base. /
417	#define BS3_SEL_R2_CS16_CNF 0x0348 /*< ring-2: 16-bit conforming code selector, not accessed, 0xfffe limit, CS16 base. /
418	#define BS3_SEL_R2_CS16_CNF_EO 0x0350 /*< ring-2: 16-bit execute-only conforming code selector, not accessed, 0xfffe limit, CS16 base. /
419	#define BS3_SEL_R2_CS32_EO 0x0358 /*< ring-2: 32-bit execute-only code selector, not accessed, flat. /
420	#define BS3_SEL_R2_CS32_CNF 0x0360 /*< ring-2: 32-bit conforming code selector, not accessed, flat. /
421	#define BS3_SEL_R2_CS32_CNF_EO 0x0368 /*< ring-2: 32-bit execute-only conforming code selector, not accessed, flat. /
422	#define BS3_SEL_R2_CS64_EO 0x0370 /*< ring-2: 64-bit execute-only code selector, not accessed, flat. /
423	#define BS3_SEL_R2_CS64_CNF 0x0378 /*< ring-2: 64-bit conforming code selector, not accessed, flat. /
424	#define BS3_SEL_R2_CS64_CNF_EO 0x0380 /*< ring-2: 64-bit execute-only conforming code selector, not accessed, flat. /
425
426	#define BS3_SEL_R3_FIRST 0x0400 /*< The first selector in the ring-3 block. /
427	#define BS3_SEL_R3_CS16 0x0400 /*< ring-3: 16-bit code selector, base 0x10000. /
428	#define BS3_SEL_R3_DS16 0x0408 /*< ring-3: 16-bit data selector, base 0x23000. /
429	#define BS3_SEL_R3_SS16 0x0410 /*< ring-3: 16-bit stack selector, base 0x00000. /
430	#define BS3_SEL_R3_CS32 0x0418 /*< ring-3: 32-bit flat code selector. /
431	#define BS3_SEL_R3_DS32 0x0420 /*< ring-3: 32-bit flat data selector. /
432	#define BS3_SEL_R3_SS32 0x0428 /*< ring-3: 32-bit flat stack selector. /
433	#define BS3_SEL_R3_CS64 0x0430 /*< ring-3: 64-bit flat code selector. /
434	#define BS3_SEL_R3_DS64 0x0438 /*< ring-3: 64-bit flat data & stack selector. /
435	#define BS3_SEL_R3_CS16_EO 0x0440 /*< ring-3: 16-bit execute-only code selector, not accessed, 0xfffe limit, CS16 base. /
436	#define BS3_SEL_R3_CS16_CNF 0x0448 /*< ring-3: 16-bit conforming code selector, not accessed, 0xfffe limit, CS16 base. /
437	#define BS3_SEL_R3_CS16_CNF_EO 0x0450 /*< ring-3: 16-bit execute-only conforming code selector, not accessed, 0xfffe limit, CS16 base. /
438	#define BS3_SEL_R3_CS32_EO 0x0458 /*< ring-3: 32-bit execute-only code selector, not accessed, flat. /
439	#define BS3_SEL_R3_CS32_CNF 0x0460 /*< ring-3: 32-bit conforming code selector, not accessed, flat. /
440	#define BS3_SEL_R3_CS32_CNF_EO 0x0468 /*< ring-3: 32-bit execute-only conforming code selector, not accessed, flat. /
441	#define BS3_SEL_R3_CS64_EO 0x0470 /*< ring-3: 64-bit execute-only code selector, not accessed, flat. /
442	#define BS3_SEL_R3_CS64_CNF 0x0478 /*< ring-3: 64-bit conforming code selector, not accessed, flat. /
443	#define BS3_SEL_R3_CS64_CNF_EO 0x0480 /*< ring-3: 64-bit execute-only conforming code selector, not accessed, flat. /
444
445	#define BS3_SEL_R3_LAST 0x04f8 /*< ring-3: Last of the BS3_SEL_RX_XXX range. /
446
447	#define BS3_SEL_SPARE_FIRST 0x0500 /*< The first selector in the spare block /
448	#define BS3_SEL_SPARE_00 0x0500 /*< Spare selector number 00h. /
449	#define BS3_SEL_SPARE_01 0x0508 /*< Spare selector number 01h. /
450	#define BS3_SEL_SPARE_02 0x0510 /*< Spare selector number 02h. /
451	#define BS3_SEL_SPARE_03 0x0518 /*< Spare selector number 03h. /
452	#define BS3_SEL_SPARE_04 0x0520 /*< Spare selector number 04h. /
453	#define BS3_SEL_SPARE_05 0x0528 /*< Spare selector number 05h. /
454	#define BS3_SEL_SPARE_06 0x0530 /*< Spare selector number 06h. /
455	#define BS3_SEL_SPARE_07 0x0538 /*< Spare selector number 07h. /
456	#define BS3_SEL_SPARE_08 0x0540 /*< Spare selector number 08h. /
457	#define BS3_SEL_SPARE_09 0x0548 /*< Spare selector number 09h. /
458	#define BS3_SEL_SPARE_0a 0x0550 /*< Spare selector number 0ah. /
459	#define BS3_SEL_SPARE_0b 0x0558 /*< Spare selector number 0bh. /
460	#define BS3_SEL_SPARE_0c 0x0560 /*< Spare selector number 0ch. /
461	#define BS3_SEL_SPARE_0d 0x0568 /*< Spare selector number 0dh. /
462	#define BS3_SEL_SPARE_0e 0x0570 /*< Spare selector number 0eh. /
463	#define BS3_SEL_SPARE_0f 0x0578 /*< Spare selector number 0fh. /
464	#define BS3_SEL_SPARE_10 0x0580 /*< Spare selector number 10h. /
465	#define BS3_SEL_SPARE_11 0x0588 /*< Spare selector number 11h. /
466	#define BS3_SEL_SPARE_12 0x0590 /*< Spare selector number 12h. /
467	#define BS3_SEL_SPARE_13 0x0598 /*< Spare selector number 13h. /
468	#define BS3_SEL_SPARE_14 0x05a0 /*< Spare selector number 14h. /
469	#define BS3_SEL_SPARE_15 0x05a8 /*< Spare selector number 15h. /
470	#define BS3_SEL_SPARE_16 0x05b0 /*< Spare selector number 16h. /
471	#define BS3_SEL_SPARE_17 0x05b8 /*< Spare selector number 17h. /
472	#define BS3_SEL_SPARE_18 0x05c0 /*< Spare selector number 18h. /
473	#define BS3_SEL_SPARE_19 0x05c8 /*< Spare selector number 19h. /
474	#define BS3_SEL_SPARE_1a 0x05d0 /*< Spare selector number 1ah. /
475	#define BS3_SEL_SPARE_1b 0x05d8 /*< Spare selector number 1bh. /
476	#define BS3_SEL_SPARE_1c 0x05e0 /*< Spare selector number 1ch. /
477	#define BS3_SEL_SPARE_1d 0x05e8 /*< Spare selector number 1dh. /
478	#define BS3_SEL_SPARE_1e 0x05f0 /*< Spare selector number 1eh. /
479	#define BS3_SEL_SPARE_1f 0x05f8 /*< Spare selector number 1fh. /
480
481	#define BS3_SEL_TILED 0x0600 /*< 16-bit data tiling: First - base=0x00000000, limit=64KB, DPL=3. /
482	#define BS3_SEL_TILED_LAST 0x0df8 /*< 16-bit data tiling: Last - base=0x00ff0000, limit=64KB, DPL=3. /
483	#define BS3_SEL_TILED_AREA_SIZE 0x001000000 /*< 16-bit data tiling: Size of addressable area, in bytes. (16 MB) /
484
485	#define BS3_SEL_FREE_PART1 0x0e00 /*< Free selector space - part \#1. /
486	#define BS3_SEL_FREE_PART1_LAST 0x0ff8 /*< Free selector space - part \#1, last entry. /
487
488	#define BS3_SEL_TEXT16 0x1000 /*< The BS3TEXT16 selector. /
489
490	#define BS3_SEL_FREE_PART2 0x1008 /*< Free selector space - part \#2. /
491	#define BS3_SEL_FREE_PART2_LAST 0x17f8 /*< Free selector space - part \#2, last entry. /
492
493	#define BS3_SEL_TILED_R0 0x1800 /*< 16-bit data/stack tiling: First - base=0x00000000, limit=64KB, DPL=0. /
494	#define BS3_SEL_TILED_R0_LAST 0x1ff8 /*< 16-bit data/stack tiling: Last - base=0x00ff0000, limit=64KB, DPL=0. /
495
496	#define BS3_SEL_SYSTEM16 0x2000 /*< The BS3SYSTEM16 selector. /
497
498	#define BS3_SEL_FREE_PART3 0x2008 /*< Free selector space - part \#3. /
499	#define BS3_SEL_FREE_PART3_LAST 0x28f8 /*< Free selector space - part \#3, last entry. /
500
501	#define BS3_SEL_DATA16 0x2900 /*< The BS3DATA16/BS3KIT_GRPNM_DATA16 selector. /
502
503	#define BS3_SEL_FREE_PART4 0x2908 /*< Free selector space - part \#4. /
504	#define BS3_SEL_FREE_PART4_LAST 0x2f98 /*< Free selector space - part \#4, last entry. /
505
506	#define BS3_SEL_PRE_TEST_PAGE_08 0x2fa0 /*< Selector located 8 selectors before the test page. /
507	#define BS3_SEL_PRE_TEST_PAGE_07 0x2fa8 /*< Selector located 7 selectors before the test page. /
508	#define BS3_SEL_PRE_TEST_PAGE_06 0x2fb0 /*< Selector located 6 selectors before the test page. /
509	#define BS3_SEL_PRE_TEST_PAGE_05 0x2fb8 /*< Selector located 5 selectors before the test page. /
510	#define BS3_SEL_PRE_TEST_PAGE_04 0x2fc0 /*< Selector located 4 selectors before the test page. /
511	#define BS3_SEL_PRE_TEST_PAGE_03 0x2fc8 /*< Selector located 3 selectors before the test page. /
512	#define BS3_SEL_PRE_TEST_PAGE_02 0x2fd0 /*< Selector located 2 selectors before the test page. /
513	#define BS3_SEL_PRE_TEST_PAGE_01 0x2fd8 /*< Selector located 1 selector before the test page. /
514	#define BS3_SEL_TEST_PAGE 0x2fe0 /*< Start of the test page intended for playing around with paging and GDT. /
515	#define BS3_SEL_TEST_PAGE_00 0x2fe0 /*< Test page selector number 00h (convenience). /
516	#define BS3_SEL_TEST_PAGE_01 0x2fe8 /*< Test page selector number 01h (convenience). /
517	#define BS3_SEL_TEST_PAGE_02 0x2ff0 /*< Test page selector number 02h (convenience). /
518	#define BS3_SEL_TEST_PAGE_03 0x2ff8 /*< Test page selector number 03h (convenience). /
519	#define BS3_SEL_TEST_PAGE_04 0x3000 /*< Test page selector number 04h (convenience). /
520	#define BS3_SEL_TEST_PAGE_05 0x3008 /*< Test page selector number 05h (convenience). /
521	#define BS3_SEL_TEST_PAGE_06 0x3010 /*< Test page selector number 06h (convenience). /
522	#define BS3_SEL_TEST_PAGE_07 0x3018 /*< Test page selector number 07h (convenience). /
523	#define BS3_SEL_TEST_PAGE_LAST 0x3fd0 /*< The last selector in the spare page. /
524
525	#define BS3_SEL_GDT_LIMIT 0x3fd8 /*< The GDT limit. /
526	/** @} */
527
528	/** @name BS3_SEL_IS_XXX - Predicates for standard selectors.
529	*
530	* Standard selectors are in the range BS3_SEL_R0_FIRST thru BS3_SEL_R3_LAST.
531	*
532	* @{ */
533	#define BS3_SEL_IS_CS16(a_uSel) (((a_uSel) & 0xf8) == 0x00)
534	#define BS3_SEL_IS_CS32(a_uSel) (((a_uSel) & 0xf8) == 0x18)
535	#define BS3_SEL_IS_CS64(a_uSel) (((a_uSel) & 0xf8) == 0x30)
536
537	#define BS3_SEL_IS_ANY_CS16(a_uSel) ( ((a_uSel) & 0xf8) == 0x00 \
538	\|\| ((a_uSel) & 0xf8) == 0x40 \
539	\|\| ((a_uSel) & 0xf8) == 0x48 \
540	\|\| ((a_uSel) & 0xf8) == 0x50 )
541	#define BS3_SEL_IS_ANY_CS32(a_uSel) ( ((a_uSel) & 0xf8) == 0x18 \
542	\|\| ((a_uSel) & 0xf8) == 0x58 \
543	\|\| ((a_uSel) & 0xf8) == 0x60 \
544	\|\| ((a_uSel) & 0xf8) == 0x68 )
545	#define BS3_SEL_IS_ANY_CS64(a_uSel) ( ((a_uSel) & 0xf8) == 0x18 \
546	\|\| ((a_uSel) & 0xf8) == 0x58 \
547	\|\| ((a_uSel) & 0xf8) == 0x60 \
548	\|\| ((a_uSel) & 0xf8) == 0x68 )
549
550	#define BS3_SEL_IS_DS16(a_uSel) (((a_uSel) & 0xf8) == 0x08)
551	#define BS3_SEL_IS_DS32(a_uSel) (((a_uSel) & 0xf8) == 0x20)
552	#define BS3_SEL_IS_DS64(a_uSel) (((a_uSel) & 0xf8) == 0x38)
553
554	#define BS3_SEL_IS_SS16(a_uSel) (((a_uSel) & 0xf8) == 0x10)
555	#define BS3_SEL_IS_SS32(a_uSel) (((a_uSel) & 0xf8) == 0x28)
556	/** @} */
557
558
559	/** @def BS3_FAR
560	* For indicating far pointers in 16-bit code.
561	* Does nothing in 32-bit and 64-bit code. */
562	/** @def BS3_NEAR
563	* For indicating near pointers in 16-bit code.
564	* Does nothing in 32-bit and 64-bit code. */
565	/** @def BS3_FAR_CODE
566	* For indicating far 16-bit functions.
567	* Does nothing in 32-bit and 64-bit code. */
568	/** @def BS3_NEAR_CODE
569	* For indicating near 16-bit functions.
570	* Does nothing in 32-bit and 64-bit code. */
571	/** @def BS3_FAR_DATA
572	* For indicating far 16-bit external data, i.e. in a segment other than DATA16.
573	* Does nothing in 32-bit and 64-bit code. */
574	#ifdef M_I86
575	# define BS3_FAR __far
576	# define BS3_NEAR __near
577	# define BS3_FAR_CODE __far
578	# define BS3_NEAR_CODE __near
579	# define BS3_FAR_DATA __far
580	#else
581	# define BS3_FAR
582	# define BS3_NEAR
583	# define BS3_FAR_CODE
584	# define BS3_NEAR_CODE
585	# define BS3_FAR_DATA
586	#endif
587
588	#if ARCH_BITS == 16 \|\| defined(DOXYGEN_RUNNING)
589	/** @def BS3_FP_SEG
590	* Get the selector (segment) part of a far pointer.
591	*
592	* @returns selector.
593	* @param a_pv Far pointer.
594	*/
595	# define BS3_FP_SEG(a_pv) ((uint16_t)(__segment)(void BS3_FAR *)(a_pv))
596	/** @def BS3_FP_OFF
597	* Get the segment offset part of a far pointer.
598	*
599	* For sake of convenience, this works like a uintptr_t cast in 32-bit and
600	* 64-bit code.
601	*
602	* @returns offset.
603	* @param a_pv Far pointer.
604	*/
605	# define BS3_FP_OFF(a_pv) ((uint16_t)(void __near *)(a_pv))
606	/** @def BS3_FP_MAKE
607	* Create a far pointer.
608	*
609	* @returns Far pointer.
610	* @param a_uSeg The selector/segment.
611	* @param a_off The offset into the segment.
612	*/
613	# define BS3_FP_MAKE(a_uSeg, a_off) (((__segment)(a_uSeg)) :> ((void __near *)(a_off)))
614	#else
615	# define BS3_FP_OFF(a_pv) ((uintptr_t)(a_pv))
616	#endif
617
618	/** @def BS3_MAKE_PROT_R0PTR_FROM_FLAT
619	* Creates a protected mode pointer from a flat address.
620	*
621	* For sake of convenience, this macro also works in 32-bit and 64-bit mode,
622	* only there it doesn't return a far pointer but a flat point.
623	*
624	* @returns far void pointer if 16-bit code, near/flat void pointer in 32-bit
625	* and 64-bit.
626	* @param a_uFlat Flat address in the first 16MB. */
627	#if ARCH_BITS == 16
628	# define BS3_MAKE_PROT_R0PTR_FROM_FLAT(a_uFlat) \
629	BS3_FP_MAKE(((uint16_t)(a_uFlat >> 16) << 3) + BS3_SEL_TILED, (uint16_t)(a_uFlat))
630	#else
631	# define BS3_MAKE_PROT_R0PTR_FROM_FLAT(a_uFlat) ((void *)(uintptr_t)(a_uFlat))
632	#endif
633
634	/** @def BS3_MAKE_PROT_R0PTR_FROM_REAL
635	* Creates a protected mode pointer from a far real mode address.
636	*
637	* For sake of convenience, this macro also works in 32-bit and 64-bit mode,
638	* only there it doesn't return a far pointer but a flat point.
639	*
640	* @returns far void pointer if 16-bit code, near/flat void pointer in 32-bit
641	* and 64-bit.
642	* @param a_uSeg The selector/segment.
643	* @param a_off The offset into the segment.
644	*/
645	#if ARCH_BITS == 16
646	# define BS3_MAKE_PROT_R0PTR_FROM_REAL(a_uSeg, a_off) BS3_MAKE_PROT_R0PTR_FROM_FLAT(((uint32_t)(a_uSeg) << 4) + (uint16_t)(a_off))
647	#else
648	# define BS3_MAKE_PROT_R0PTR_FROM_REAL(a_uSeg, a_off) ( (void *)(uintptr_t)(((uint32_t)(a_uSeg) << 4) + (uint16_t)(a_off)) )
649	#endif
650
651
652	/** @def BS3_CALL
653	* The calling convension used by BS3 functions. */
654	#if ARCH_BITS != 64
655	# define BS3_CALL __cdecl
656	#elif !defined(_MSC_VER)
657	# define BS3_CALL __attribute__((__ms_abi__))
658	#else
659	# define BS3_CALL
660	#endif
661
662	/** @def IN_BS3KIT
663	* Indicates that we're in the same link job as the BS3Kit code. */
664	#ifdef DOXYGEN_RUNNING
665	# define IN_BS3KIT
666	#endif
667
668	/** @def BS3_DECL
669	* Declares a BS3Kit function with default far/near.
670	*
671	* Until we outgrow BS3TEXT16, we use all near functions in 16-bit.
672	*
673	* @param a_Type The return type. */
674	#if ARCH_BITS != 16 \|\| !defined(BS3_USE_ALT_16BIT_TEXT_SEG)
675	# define BS3_DECL(a_Type) BS3_DECL_NEAR(a_Type)
676	#else
677	# define BS3_DECL(a_Type) BS3_DECL_FAR(a_Type)
678	#endif
679
680	/** @def BS3_DECL_NEAR
681	* Declares a BS3Kit function, always near everywhere.
682	*
683	* Until we outgrow BS3TEXT16, we use all near functions in 16-bit.
684	*
685	* @param a_Type The return type. */
686	#ifdef IN_BS3KIT
687	# define BS3_DECL_NEAR(a_Type) DECLEXPORT(a_Type) BS3_NEAR_CODE BS3_CALL
688	#else
689	# define BS3_DECL_NEAR(a_Type) DECLIMPORT(a_Type) BS3_NEAR_CODE BS3_CALL
690	#endif
691
692	/** @def BS3_DECL_FAR
693	* Declares a BS3Kit function, far 16-bit, otherwise near.
694	*
695	* Until we outgrow BS3TEXT16, we use all near functions in 16-bit.
696	*
697	* @param a_Type The return type. */
698	#ifdef IN_BS3KIT
699	# define BS3_DECL_FAR(a_Type) DECLEXPORT(a_Type) BS3_FAR_CODE BS3_CALL
700	#else
701	# define BS3_DECL_FAR(a_Type) DECLIMPORT(a_Type) BS3_FAR_CODE BS3_CALL
702	#endif
703
704	/** @def BS3_DECL_CALLBACK
705	* Declares a BS3Kit callback function (typically static).
706	*
707	* @param a_Type The return type. */
708	#ifdef IN_BS3KIT
709	# define BS3_DECL_CALLBACK(a_Type) a_Type BS3_FAR_CODE BS3_CALL
710	#else
711	# define BS3_DECL_CALLBACK(a_Type) a_Type BS3_FAR_CODE BS3_CALL
712	#endif
713
714	/** @def BS3_DECL_NEAR_CALLBACK
715	* Declares a near BS3Kit callback function (typically static).
716	*
717	* 16-bit users must be in CGROUP16!
718	*
719	* @param a_Type The return type. */
720	#ifdef IN_BS3KIT
721	# define BS3_DECL_NEAR_CALLBACK(a_Type) a_Type BS3_NEAR_CODE BS3_CALL
722	#else
723	# define BS3_DECL_NEAR_CALLBACK(a_Type) a_Type BS3_NEAR_CODE BS3_CALL
724	#endif
725
726	/**
727	* Constructs a common name.
728	*
729	* Example: BS3_CMN_NM(Bs3Shutdown)
730	*
731	* @param a_Name The name of the function or global variable.
732	*/
733	#define BS3_CMN_NM(a_Name) RT_CONCAT3(a_Name,_c,ARCH_BITS)
734
735	/**
736	* Constructs a common function name, far in 16-bit code.
737	*
738	* Example: BS3_CMN_FAR_NM(Bs3Shutdown)
739	*
740	* @param a_Name The name of the function.
741	*/
742	#if ARCH_BITS == 16
743	# define BS3_CMN_FAR_NM(a_Name) RT_CONCAT(a_Name,_f16)
744	#else
745	# define BS3_CMN_FAR_NM(a_Name) RT_CONCAT3(a_Name,_c,ARCH_BITS)
746	#endif
747
748	/**
749	* Constructs a common function name, far or near as defined by the source.
750	*
751	* Which to use in 16-bit mode is defined by BS3_USE_ALT_16BIT_TEXT_SEG. In
752	* 32-bit and 64-bit mode there are no far symbols, only near ones.
753	*
754	* Example: BS3_CMN_FN_NM(Bs3Shutdown)
755	*
756	* @param a_Name The name of the function.
757	*/
758	#if ARCH_BITS != 16 \|\| !defined(BS3_USE_ALT_16BIT_TEXT_SEG)
759	# define BS3_CMN_FN_NM(a_Name) BS3_CMN_NM(a_Name)
760	#else
761	# define BS3_CMN_FN_NM(a_Name) BS3_CMN_FAR_NM(a_Name)
762	#endif
763
764
765	/**
766	* Constructs a data name.
767	*
768	* This glosses over the underscore prefix usage of our 16-bit, 32-bit and
769	* 64-bit compilers.
770	*
771	* Example: @code{.c}
772	* \#define Bs3Gdt BS3_DATA_NM(Bs3Gdt)
773	* extern X86DESC BS3_FAR_DATA Bs3Gdt
774	* @endcode
775	*
776	* @param a_Name The name of the global variable.
777	* @remarks Mainly used in bs3kit-mangling.h, internal headers and templates.
778	*/
779	//converter does this now//#if ARCH_BITS == 64
780	//converter does this now//# define BS3_DATA_NM(a_Name) RT_CONCAT(_,a_Name)
781	//converter does this now//#else
782	# define BS3_DATA_NM(a_Name) a_Name
783	//converter does this now//#endif
784
785	/**
786	* Template for creating a pointer union type.
787	* @param a_BaseName The base type name.
788	* @param a_Modifiers The type modifier.
789	*/
790	#define BS3_PTR_UNION_TEMPLATE(a_BaseName, a_Modifiers) \
791	typedef union a_BaseName \
792	{ \
793	/** Pointer into the void. */ \
794	a_Modifiers void BS3_FAR *pv; \
795	/** As a signed integer. */ \
796	intptr_t i; \
797	/** As an unsigned integer. */ \
798	uintptr_t u; \
799	/** Pointer to char value. */ \
800	a_Modifiers char BS3_FAR *pch; \
801	/** Pointer to char value. */ \
802	a_Modifiers unsigned char BS3_FAR *puch; \
803	/** Pointer to a int value. */ \
804	a_Modifiers int BS3_FAR *pi; \
805	/** Pointer to a unsigned int value. */ \
806	a_Modifiers unsigned int BS3_FAR *pu; \
807	/** Pointer to a long value. */ \
808	a_Modifiers long BS3_FAR *pl; \
809	/** Pointer to a long value. */ \
810	a_Modifiers unsigned long BS3_FAR *pul; \
811	/** Pointer to a memory size value. */ \
812	a_Modifiers size_t BS3_FAR *pcb; \
813	/** Pointer to a byte value. */ \
814	a_Modifiers uint8_t BS3_FAR *pb; \
815	/** Pointer to a 8-bit unsigned value. */ \
816	a_Modifiers uint8_t BS3_FAR *pu8; \
817	/** Pointer to a 16-bit unsigned value. */ \
818	a_Modifiers uint16_t BS3_FAR *pu16; \
819	/** Pointer to a 32-bit unsigned value. */ \
820	a_Modifiers uint32_t BS3_FAR *pu32; \
821	/** Pointer to a 64-bit unsigned value. */ \
822	a_Modifiers uint64_t BS3_FAR *pu64; \
823	/** Pointer to a UTF-16 character. */ \
824	a_Modifiers RTUTF16 BS3_FAR *pwc; \
825	/** Pointer to a UUID character. */ \
826	a_Modifiers RTUUID BS3_FAR *pUuid; \
827	} a_BaseName; \
828	/** Pointer to a pointer union. */ \
829	typedef a_BaseName *RT_CONCAT(P,a_BaseName)
830	BS3_PTR_UNION_TEMPLATE(BS3PTRUNION, RT_NOTHING);
831	BS3_PTR_UNION_TEMPLATE(BS3CPTRUNION, const);
832	BS3_PTR_UNION_TEMPLATE(BS3VPTRUNION, volatile);
833	BS3_PTR_UNION_TEMPLATE(BS3CVPTRUNION, const volatile);
834
835	/** Generic far function type. */
836	typedef BS3_DECL_FAR(void) FNBS3FAR(void);
837	/** Generic far function pointer type. */
838	typedef FNBS3FAR *FPFNBS3FAR;
839
840	/** Generic near function type. */
841	typedef BS3_DECL_NEAR(void) FNBS3NEAR(void);
842	/** Generic near function pointer type. */
843	typedef FNBS3NEAR *PFNBS3NEAR;
844
845	/** Generic far 16:16 function pointer type for address conversion functions. */
846	#if ARCH_BITS == 16
847	typedef FPFNBS3FAR PFNBS3FARADDRCONV;
848	#else
849	typedef uint32_t PFNBS3FARADDRCONV;
850	#endif
851
852	/** The system call vector. */
853	#define BS3_TRAP_SYSCALL UINT8_C(0x20)
854
855	/** @name System call numbers (ax).
856	* Paramenters are generally passed in registers specific to each system call,
857	* however cx:xSI is used for passing a pointer parameter.
858	* @{ */
859	/** Print char (cl). */
860	#define BS3_SYSCALL_PRINT_CHR UINT16_C(0x0001)
861	/** Print string (pointer in cx:xSI, length in dx). */
862	#define BS3_SYSCALL_PRINT_STR UINT16_C(0x0002)
863	/** Switch to ring-0. */
864	#define BS3_SYSCALL_TO_RING0 UINT16_C(0x0003)
865	/** Switch to ring-1. */
866	#define BS3_SYSCALL_TO_RING1 UINT16_C(0x0004)
867	/** Switch to ring-2. */
868	#define BS3_SYSCALL_TO_RING2 UINT16_C(0x0005)
869	/** Switch to ring-3. */
870	#define BS3_SYSCALL_TO_RING3 UINT16_C(0x0006)
871	/** Restore context (pointer in cx:xSI, flags in dx). */
872	#define BS3_SYSCALL_RESTORE_CTX UINT16_C(0x0007)
873	/** Set DRx register (value in ESI, register number in dl). */
874	#define BS3_SYSCALL_SET_DRX UINT16_C(0x0008)
875	/** Get DRx register (register number in dl, value returned in ax:dx). */
876	#define BS3_SYSCALL_GET_DRX UINT16_C(0x0009)
877	/** Set CRx register (value in ESI, register number in dl). */
878	#define BS3_SYSCALL_SET_CRX UINT16_C(0x000a)
879	/** Get CRx register (register number in dl, value returned in ax:dx). */
880	#define BS3_SYSCALL_GET_CRX UINT16_C(0x000b)
881	/** Set the task register (value in ESI). */
882	#define BS3_SYSCALL_SET_TR UINT16_C(0x000c)
883	/** Get the task register (value returned in ax). */
884	#define BS3_SYSCALL_GET_TR UINT16_C(0x000d)
885	/** Set the LDT register (value in ESI). */
886	#define BS3_SYSCALL_SET_LDTR UINT16_C(0x000e)
887	/** Get the LDT register (value returned in ax). */
888	#define BS3_SYSCALL_GET_LDTR UINT16_C(0x000f)
889	/** Set XCR0 register (value in edx:esi). */
890	#define BS3_SYSCALL_SET_XCR0 UINT16_C(0x0010)
891	/** Get XCR0 register (value returned in edx:eax). */
892	#define BS3_SYSCALL_GET_XCR0 UINT16_C(0x0011)
893	/** The last system call value. */
894	#define BS3_SYSCALL_LAST BS3_SYSCALL_GET_XCR0
895	/** @} */
896
897
898
899	/** @defgroup grp_bs3kit_system System Structures
900	* @{ */
901	/** The GDT, indexed by BS3_SEL_XXX shifted by 3. */
902	extern X86DESC BS3_FAR_DATA Bs3Gdt[(BS3_SEL_GDT_LIMIT + 1) / 8];
903
904	extern X86DESC64 BS3_FAR_DATA Bs3Gdt_Ldt; /*< @see BS3_SEL_LDT /
905	extern X86DESC BS3_FAR_DATA Bs3Gdte_Tss16; /*< @see BS3_SEL_TSS16 /
906	extern X86DESC BS3_FAR_DATA Bs3Gdte_Tss16DoubleFault; /*< @see BS3_SEL_TSS16_DF /
907	extern X86DESC BS3_FAR_DATA Bs3Gdte_Tss16Spare0; /*< @see BS3_SEL_TSS16_SPARE0 /
908	extern X86DESC BS3_FAR_DATA Bs3Gdte_Tss16Spare1; /*< @see BS3_SEL_TSS16_SPARE1 /
909	extern X86DESC BS3_FAR_DATA Bs3Gdte_Tss32; /*< @see BS3_SEL_TSS32 /
910	extern X86DESC BS3_FAR_DATA Bs3Gdte_Tss32DoubleFault; /*< @see BS3_SEL_TSS32_DF /
911	extern X86DESC BS3_FAR_DATA Bs3Gdte_Tss32Spare0; /*< @see BS3_SEL_TSS32_SPARE0 /
912	extern X86DESC BS3_FAR_DATA Bs3Gdte_Tss32Spare1; /*< @see BS3_SEL_TSS32_SPARE1 /
913	extern X86DESC BS3_FAR_DATA Bs3Gdte_Tss32IobpIntRedirBm; /*< @see BS3_SEL_TSS32_IOBP_IRB /
914	extern X86DESC BS3_FAR_DATA Bs3Gdte_Tss32IntRedirBm; /*< @see BS3_SEL_TSS32_IRB /
915	extern X86DESC BS3_FAR_DATA Bs3Gdte_Tss64; /*< @see BS3_SEL_TSS64 /
916	extern X86DESC BS3_FAR_DATA Bs3Gdte_Tss64Spare0; /*< @see BS3_SEL_TSS64_SPARE0 /
917	extern X86DESC BS3_FAR_DATA Bs3Gdte_Tss64Spare1; /*< @see BS3_SEL_TSS64_SPARE1 /
918	extern X86DESC BS3_FAR_DATA Bs3Gdte_Tss64Iobp; /*< @see BS3_SEL_TSS64_IOBP /
919	extern X86DESC BS3_FAR_DATA Bs3Gdte_RMTEXT16_CS; /*< @see BS3_SEL_RMTEXT16_CS /
920	extern X86DESC BS3_FAR_DATA Bs3Gdte_X0TEXT16_CS; /*< @see BS3_SEL_X0TEXT16_CS /
921	extern X86DESC BS3_FAR_DATA Bs3Gdte_X1TEXT16_CS; /*< @see BS3_SEL_X1TEXT16_CS /
922	extern X86DESC BS3_FAR_DATA Bs3Gdte_R0_MMIO16; /*< @see BS3_SEL_VMMDEV_MMIO16 /
923
924	extern X86DESC BS3_FAR_DATA Bs3Gdte_R0_First; /*< @see BS3_SEL_R0_FIRST /
925	extern X86DESC BS3_FAR_DATA Bs3Gdte_R0_CS16; /*< @see BS3_SEL_R0_CS16 /
926	extern X86DESC BS3_FAR_DATA Bs3Gdte_R0_DS16; /*< @see BS3_SEL_R0_DS16 /
927	extern X86DESC BS3_FAR_DATA Bs3Gdte_R0_SS16; /*< @see BS3_SEL_R0_SS16 /
928	extern X86DESC BS3_FAR_DATA Bs3Gdte_R0_CS32; /*< @see BS3_SEL_R0_CS32 /
929	extern X86DESC BS3_FAR_DATA Bs3Gdte_R0_DS32; /*< @see BS3_SEL_R0_DS32 /
930	extern X86DESC BS3_FAR_DATA Bs3Gdte_R0_SS32; /*< @see BS3_SEL_R0_SS32 /
931	extern X86DESC BS3_FAR_DATA Bs3Gdte_R0_CS64; /*< @see BS3_SEL_R0_CS64 /
932	extern X86DESC BS3_FAR_DATA Bs3Gdte_R0_DS64; /*< @see BS3_SEL_R0_DS64 /
933	extern X86DESC BS3_FAR_DATA Bs3Gdte_R0_CS16_EO; /*< @see BS3_SEL_R0_CS16_EO /
934	extern X86DESC BS3_FAR_DATA Bs3Gdte_R0_CS16_CNF; /*< @see BS3_SEL_R0_CS16_CNF /
935	extern X86DESC BS3_FAR_DATA Bs3Gdte_R0_CS16_CND_EO; /*< @see BS3_SEL_R0_CS16_CNF_EO /
936	extern X86DESC BS3_FAR_DATA Bs3Gdte_R0_CS32_EO; /*< @see BS3_SEL_R0_CS32_EO /
937	extern X86DESC BS3_FAR_DATA Bs3Gdte_R0_CS32_CNF; /*< @see BS3_SEL_R0_CS32_CNF /
938	extern X86DESC BS3_FAR_DATA Bs3Gdte_R0_CS32_CNF_EO; /*< @see BS3_SEL_R0_CS32_CNF_EO /
939	extern X86DESC BS3_FAR_DATA Bs3Gdte_R0_CS64_EO; /*< @see BS3_SEL_R0_CS64_EO /
940	extern X86DESC BS3_FAR_DATA Bs3Gdte_R0_CS64_CNF; /*< @see BS3_SEL_R0_CS64_CNF /
941	extern X86DESC BS3_FAR_DATA Bs3Gdte_R0_CS64_CNF_EO; /*< @see BS3_SEL_R0_CS64_CNF_EO /
942
943	extern X86DESC BS3_FAR_DATA Bs3Gdte_R1_First; /*< @see BS3_SEL_R1_FIRST /
944	extern X86DESC BS3_FAR_DATA Bs3Gdte_R1_CS16; /*< @see BS3_SEL_R1_CS16 /
945	extern X86DESC BS3_FAR_DATA Bs3Gdte_R1_DS16; /*< @see BS3_SEL_R1_DS16 /
946	extern X86DESC BS3_FAR_DATA Bs3Gdte_R1_SS16; /*< @see BS3_SEL_R1_SS16 /
947	extern X86DESC BS3_FAR_DATA Bs3Gdte_R1_CS32; /*< @see BS3_SEL_R1_CS32 /
948	extern X86DESC BS3_FAR_DATA Bs3Gdte_R1_DS32; /*< @see BS3_SEL_R1_DS32 /
949	extern X86DESC BS3_FAR_DATA Bs3Gdte_R1_SS32; /*< @see BS3_SEL_R1_SS32 /
950	extern X86DESC BS3_FAR_DATA Bs3Gdte_R1_CS64; /*< @see BS3_SEL_R1_CS64 /
951	extern X86DESC BS3_FAR_DATA Bs3Gdte_R1_DS64; /*< @see BS3_SEL_R1_DS64 /
952	extern X86DESC BS3_FAR_DATA Bs3Gdte_R1_CS16_EO; /*< @see BS3_SEL_R1_CS16_EO /
953	extern X86DESC BS3_FAR_DATA Bs3Gdte_R1_CS16_CNF; /*< @see BS3_SEL_R1_CS16_CNF /
954	extern X86DESC BS3_FAR_DATA Bs3Gdte_R1_CS16_CND_EO; /*< @see BS3_SEL_R1_CS16_CNF_EO /
955	extern X86DESC BS3_FAR_DATA Bs3Gdte_R1_CS32_EO; /*< @see BS3_SEL_R1_CS32_EO /
956	extern X86DESC BS3_FAR_DATA Bs3Gdte_R1_CS32_CNF; /*< @see BS3_SEL_R1_CS32_CNF /
957	extern X86DESC BS3_FAR_DATA Bs3Gdte_R1_CS32_CNF_EO; /*< @see BS3_SEL_R1_CS32_CNF_EO /
958	extern X86DESC BS3_FAR_DATA Bs3Gdte_R1_CS64_EO; /*< @see BS3_SEL_R1_CS64_EO /
959	extern X86DESC BS3_FAR_DATA Bs3Gdte_R1_CS64_CNF; /*< @see BS3_SEL_R1_CS64_CNF /
960	extern X86DESC BS3_FAR_DATA Bs3Gdte_R1_CS64_CNF_EO; /*< @see BS3_SEL_R1_CS64_CNF_EO /
961
962	extern X86DESC BS3_FAR_DATA Bs3Gdte_R2_First; /*< @see BS3_SEL_R2_FIRST /
963	extern X86DESC BS3_FAR_DATA Bs3Gdte_R2_CS16; /*< @see BS3_SEL_R2_CS16 /
964	extern X86DESC BS3_FAR_DATA Bs3Gdte_R2_DS16; /*< @see BS3_SEL_R2_DS16 /
965	extern X86DESC BS3_FAR_DATA Bs3Gdte_R2_SS16; /*< @see BS3_SEL_R2_SS16 /
966	extern X86DESC BS3_FAR_DATA Bs3Gdte_R2_CS32; /*< @see BS3_SEL_R2_CS32 /
967	extern X86DESC BS3_FAR_DATA Bs3Gdte_R2_DS32; /*< @see BS3_SEL_R2_DS32 /
968	extern X86DESC BS3_FAR_DATA Bs3Gdte_R2_SS32; /*< @see BS3_SEL_R2_SS32 /
969	extern X86DESC BS3_FAR_DATA Bs3Gdte_R2_CS64; /*< @see BS3_SEL_R2_CS64 /
970	extern X86DESC BS3_FAR_DATA Bs3Gdte_R2_DS64; /*< @see BS3_SEL_R2_DS64 /
971	extern X86DESC BS3_FAR_DATA Bs3Gdte_R2_CS16_EO; /*< @see BS3_SEL_R2_CS16_EO /
972	extern X86DESC BS3_FAR_DATA Bs3Gdte_R2_CS16_CNF; /*< @see BS3_SEL_R2_CS16_CNF /
973	extern X86DESC BS3_FAR_DATA Bs3Gdte_R2_CS16_CND_EO; /*< @see BS3_SEL_R2_CS16_CNF_EO /
974	extern X86DESC BS3_FAR_DATA Bs3Gdte_R2_CS32_EO; /*< @see BS3_SEL_R2_CS32_EO /
975	extern X86DESC BS3_FAR_DATA Bs3Gdte_R2_CS32_CNF; /*< @see BS3_SEL_R2_CS32_CNF /
976	extern X86DESC BS3_FAR_DATA Bs3Gdte_R2_CS32_CNF_EO; /*< @see BS3_SEL_R2_CS32_CNF_EO /
977	extern X86DESC BS3_FAR_DATA Bs3Gdte_R2_CS64_EO; /*< @see BS3_SEL_R2_CS64_EO /
978	extern X86DESC BS3_FAR_DATA Bs3Gdte_R2_CS64_CNF; /*< @see BS3_SEL_R2_CS64_CNF /
979	extern X86DESC BS3_FAR_DATA Bs3Gdte_R2_CS64_CNF_EO; /*< @see BS3_SEL_R2_CS64_CNF_EO /
980
981	extern X86DESC BS3_FAR_DATA Bs3Gdte_R3_First; /*< @see BS3_SEL_R3_FIRST /
982	extern X86DESC BS3_FAR_DATA Bs3Gdte_R3_CS16; /*< @see BS3_SEL_R3_CS16 /
983	extern X86DESC BS3_FAR_DATA Bs3Gdte_R3_DS16; /*< @see BS3_SEL_R3_DS16 /
984	extern X86DESC BS3_FAR_DATA Bs3Gdte_R3_SS16; /*< @see BS3_SEL_R3_SS16 /
985	extern X86DESC BS3_FAR_DATA Bs3Gdte_R3_CS32; /*< @see BS3_SEL_R3_CS32 /
986	extern X86DESC BS3_FAR_DATA Bs3Gdte_R3_DS32; /*< @see BS3_SEL_R3_DS32 /
987	extern X86DESC BS3_FAR_DATA Bs3Gdte_R3_SS32; /*< @see BS3_SEL_R3_SS32 /
988	extern X86DESC BS3_FAR_DATA Bs3Gdte_R3_CS64; /*< @see BS3_SEL_R3_CS64 /
989	extern X86DESC BS3_FAR_DATA Bs3Gdte_R3_DS64; /*< @see BS3_SEL_R3_DS64 /
990	extern X86DESC BS3_FAR_DATA Bs3Gdte_R3_CS16_EO; /*< @see BS3_SEL_R3_CS16_EO /
991	extern X86DESC BS3_FAR_DATA Bs3Gdte_R3_CS16_CNF; /*< @see BS3_SEL_R3_CS16_CNF /
992	extern X86DESC BS3_FAR_DATA Bs3Gdte_R3_CS16_CND_EO; /*< @see BS3_SEL_R3_CS16_CNF_EO /
993	extern X86DESC BS3_FAR_DATA Bs3Gdte_R3_CS32_EO; /*< @see BS3_SEL_R3_CS32_EO /
994	extern X86DESC BS3_FAR_DATA Bs3Gdte_R3_CS32_CNF; /*< @see BS3_SEL_R3_CS32_CNF /
995	extern X86DESC BS3_FAR_DATA Bs3Gdte_R3_CS32_CNF_EO; /*< @see BS3_SEL_R3_CS32_CNF_EO /
996	extern X86DESC BS3_FAR_DATA Bs3Gdte_R3_CS64_EO; /*< @see BS3_SEL_R3_CS64_EO /
997	extern X86DESC BS3_FAR_DATA Bs3Gdte_R3_CS64_CNF; /*< @see BS3_SEL_R3_CS64_CNF /
998	extern X86DESC BS3_FAR_DATA Bs3Gdte_R3_CS64_CNF_EO; /*< @see BS3_SEL_R3_CS64_CNF_EO /
999
1000	extern X86DESC BS3_FAR_DATA Bs3GdteSpare00; /*< GDT entry for playing with in testcases. @see BS3_SEL_SPARE_00 /
1001	extern X86DESC BS3_FAR_DATA Bs3GdteSpare01; /*< GDT entry for playing with in testcases. @see BS3_SEL_SPARE_01 /
1002	extern X86DESC BS3_FAR_DATA Bs3GdteSpare02; /*< GDT entry for playing with in testcases. @see BS3_SEL_SPARE_02 /
1003	extern X86DESC BS3_FAR_DATA Bs3GdteSpare03; /*< GDT entry for playing with in testcases. @see BS3_SEL_SPARE_03 /
1004	extern X86DESC BS3_FAR_DATA Bs3GdteSpare04; /*< GDT entry for playing with in testcases. @see BS3_SEL_SPARE_04 /
1005	extern X86DESC BS3_FAR_DATA Bs3GdteSpare05; /*< GDT entry for playing with in testcases. @see BS3_SEL_SPARE_05 /
1006	extern X86DESC BS3_FAR_DATA Bs3GdteSpare06; /*< GDT entry for playing with in testcases. @see BS3_SEL_SPARE_06 /
1007	extern X86DESC BS3_FAR_DATA Bs3GdteSpare07; /*< GDT entry for playing with in testcases. @see BS3_SEL_SPARE_07 /
1008	extern X86DESC BS3_FAR_DATA Bs3GdteSpare08; /*< GDT entry for playing with in testcases. @see BS3_SEL_SPARE_08 /
1009	extern X86DESC BS3_FAR_DATA Bs3GdteSpare09; /*< GDT entry for playing with in testcases. @see BS3_SEL_SPARE_09 /
1010	extern X86DESC BS3_FAR_DATA Bs3GdteSpare0a; /*< GDT entry for playing with in testcases. @see BS3_SEL_SPARE_0a /
1011	extern X86DESC BS3_FAR_DATA Bs3GdteSpare0b; /*< GDT entry for playing with in testcases. @see BS3_SEL_SPARE_0b /
1012	extern X86DESC BS3_FAR_DATA Bs3GdteSpare0c; /*< GDT entry for playing with in testcases. @see BS3_SEL_SPARE_0c /
1013	extern X86DESC BS3_FAR_DATA Bs3GdteSpare0d; /*< GDT entry for playing with in testcases. @see BS3_SEL_SPARE_0d /
1014	extern X86DESC BS3_FAR_DATA Bs3GdteSpare0e; /*< GDT entry for playing with in testcases. @see BS3_SEL_SPARE_0e /
1015	extern X86DESC BS3_FAR_DATA Bs3GdteSpare0f; /*< GDT entry for playing with in testcases. @see BS3_SEL_SPARE_0f /
1016	extern X86DESC BS3_FAR_DATA Bs3GdteSpare10; /*< GDT entry for playing with in testcases. @see BS3_SEL_SPARE_10 /
1017	extern X86DESC BS3_FAR_DATA Bs3GdteSpare11; /*< GDT entry for playing with in testcases. @see BS3_SEL_SPARE_11 /
1018	extern X86DESC BS3_FAR_DATA Bs3GdteSpare12; /*< GDT entry for playing with in testcases. @see BS3_SEL_SPARE_12 /
1019	extern X86DESC BS3_FAR_DATA Bs3GdteSpare13; /*< GDT entry for playing with in testcases. @see BS3_SEL_SPARE_13 /
1020	extern X86DESC BS3_FAR_DATA Bs3GdteSpare14; /*< GDT entry for playing with in testcases. @see BS3_SEL_SPARE_14 /
1021	extern X86DESC BS3_FAR_DATA Bs3GdteSpare15; /*< GDT entry for playing with in testcases. @see BS3_SEL_SPARE_15 /
1022	extern X86DESC BS3_FAR_DATA Bs3GdteSpare16; /*< GDT entry for playing with in testcases. @see BS3_SEL_SPARE_16 /
1023	extern X86DESC BS3_FAR_DATA Bs3GdteSpare17; /*< GDT entry for playing with in testcases. @see BS3_SEL_SPARE_17 /
1024	extern X86DESC BS3_FAR_DATA Bs3GdteSpare18; /*< GDT entry for playing with in testcases. @see BS3_SEL_SPARE_18 /
1025	extern X86DESC BS3_FAR_DATA Bs3GdteSpare19; /*< GDT entry for playing with in testcases. @see BS3_SEL_SPARE_19 /
1026	extern X86DESC BS3_FAR_DATA Bs3GdteSpare1a; /*< GDT entry for playing with in testcases. @see BS3_SEL_SPARE_1a /
1027	extern X86DESC BS3_FAR_DATA Bs3GdteSpare1b; /*< GDT entry for playing with in testcases. @see BS3_SEL_SPARE_1b /
1028	extern X86DESC BS3_FAR_DATA Bs3GdteSpare1c; /*< GDT entry for playing with in testcases. @see BS3_SEL_SPARE_1c /
1029	extern X86DESC BS3_FAR_DATA Bs3GdteSpare1d; /*< GDT entry for playing with in testcases. @see BS3_SEL_SPARE_1d /
1030	extern X86DESC BS3_FAR_DATA Bs3GdteSpare1e; /*< GDT entry for playing with in testcases. @see BS3_SEL_SPARE_1e /
1031	extern X86DESC BS3_FAR_DATA Bs3GdteSpare1f; /*< GDT entry for playing with in testcases. @see BS3_SEL_SPARE_1f /
1032
1033	/** GDTs setting up the tiled 16-bit access to the first 16 MBs of memory.
1034	* @see BS3_SEL_TILED, BS3_SEL_TILED_LAST, BS3_SEL_TILED_AREA_SIZE */
1035	extern X86DESC BS3_FAR_DATA Bs3GdteTiled[256];
1036	/** Free GDTes, part \#1. */
1037	extern X86DESC BS3_FAR_DATA Bs3GdteFreePart1[64];
1038	/** The BS3TEXT16/BS3CLASS16CODE GDT entry. @see BS3_SEL_TEXT16 */
1039	extern X86DESC BS3_FAR_DATA Bs3Gdte_CODE16;
1040	/** Free GDTes, part \#2. */
1041	extern X86DESC BS3_FAR_DATA Bs3GdteFreePart2[511];
1042	/** The BS3SYSTEM16 GDT entry. */
1043	extern X86DESC BS3_FAR_DATA Bs3Gdte_SYSTEM16;
1044	/** Free GDTes, part \#3. */
1045	extern X86DESC BS3_FAR_DATA Bs3GdteFreePart3[223];
1046	/** The BS3DATA16/BS3KIT_GRPNM_DATA16 GDT entry. */
1047	extern X86DESC BS3_FAR_DATA Bs3Gdte_DATA16;
1048
1049	/** Free GDTes, part \#4. */
1050	extern X86DESC BS3_FAR_DATA Bs3GdteFreePart4[211];
1051
1052	extern X86DESC BS3_FAR_DATA Bs3GdtePreTestPage08; /*< GDT entry 8 selectors prior to the test page, testcase resource. @see BS3_SEL_PRE_TEST_PAGE_08 /
1053	extern X86DESC BS3_FAR_DATA Bs3GdtePreTestPage07; /*< GDT entry 7 selectors prior to the test page, testcase resource. @see BS3_SEL_PRE_TEST_PAGE_07 /
1054	extern X86DESC BS3_FAR_DATA Bs3GdtePreTestPage06; /*< GDT entry 6 selectors prior to the test page, testcase resource. @see BS3_SEL_PRE_TEST_PAGE_06 /
1055	extern X86DESC BS3_FAR_DATA Bs3GdtePreTestPage05; /*< GDT entry 5 selectors prior to the test page, testcase resource. @see BS3_SEL_PRE_TEST_PAGE_05 /
1056	extern X86DESC BS3_FAR_DATA Bs3GdtePreTestPage04; /*< GDT entry 4 selectors prior to the test page, testcase resource. @see BS3_SEL_PRE_TEST_PAGE_04 /
1057	extern X86DESC BS3_FAR_DATA Bs3GdtePreTestPage03; /*< GDT entry 3 selectors prior to the test page, testcase resource. @see BS3_SEL_PRE_TEST_PAGE_03 /
1058	extern X86DESC BS3_FAR_DATA Bs3GdtePreTestPage02; /*< GDT entry 2 selectors prior to the test page, testcase resource. @see BS3_SEL_PRE_TEST_PAGE_02 /
1059	extern X86DESC BS3_FAR_DATA Bs3GdtePreTestPage01; /*< GDT entry 1 selectors prior to the test page, testcase resource. @see BS3_SEL_PRE_TEST_PAGE_01 /
1060	/** Array of GDT entries starting on a page boundrary and filling (almost) the
1061	* whole page. This is for playing with paging and GDT usage.
1062	* @see BS3_SEL_TEST_PAGE */
1063	extern X86DESC BS3_FAR_DATA Bs3GdteTestPage[2043];
1064	extern X86DESC BS3_FAR_DATA Bs3GdteTestPage00; /*< GDT entry 0 on the test page (convenience). @see BS3_SEL_TEST_PAGE_00 /
1065	extern X86DESC BS3_FAR_DATA Bs3GdteTestPage01; /*< GDT entry 1 on the test page (convenience). @see BS3_SEL_TEST_PAGE_01 /
1066	extern X86DESC BS3_FAR_DATA Bs3GdteTestPage02; /*< GDT entry 2 on the test page (convenience). @see BS3_SEL_TEST_PAGE_02 /
1067	extern X86DESC BS3_FAR_DATA Bs3GdteTestPage03; /*< GDT entry 3 on the test page (convenience). @see BS3_SEL_TEST_PAGE_03 /
1068	extern X86DESC BS3_FAR_DATA Bs3GdteTestPage04; /*< GDT entry 4 on the test page (convenience). @see BS3_SEL_TEST_PAGE_04 /
1069	extern X86DESC BS3_FAR_DATA Bs3GdteTestPage05; /*< GDT entry 5 on the test page (convenience). @see BS3_SEL_TEST_PAGE_05 /
1070	extern X86DESC BS3_FAR_DATA Bs3GdteTestPage06; /*< GDT entry 6 on the test page (convenience). @see BS3_SEL_TEST_PAGE_06 /
1071	extern X86DESC BS3_FAR_DATA Bs3GdteTestPage07; /*< GDT entry 7 on the test page (convenience). @see BS3_SEL_TEST_PAGE_07 /
1072
1073	/** The end of the GDT (exclusive - contains eye-catcher string). */
1074	extern X86DESC BS3_FAR_DATA Bs3GdtEnd;
1075
1076	/** The default 16-bit TSS. */
1077	extern X86TSS16 BS3_FAR_DATA Bs3Tss16;
1078	extern X86TSS16 BS3_FAR_DATA Bs3Tss16DoubleFault;
1079	extern X86TSS16 BS3_FAR_DATA Bs3Tss16Spare0;
1080	extern X86TSS16 BS3_FAR_DATA Bs3Tss16Spare1;
1081	/** The default 32-bit TSS. */
1082	extern X86TSS32 BS3_FAR_DATA Bs3Tss32;
1083	extern X86TSS32 BS3_FAR_DATA Bs3Tss32DoubleFault;
1084	extern X86TSS32 BS3_FAR_DATA Bs3Tss32Spare0;
1085	extern X86TSS32 BS3_FAR_DATA Bs3Tss32Spare1;
1086	/** The default 64-bit TSS. */
1087	extern X86TSS64 BS3_FAR_DATA Bs3Tss64;
1088	extern X86TSS64 BS3_FAR_DATA Bs3Tss64Spare0;
1089	extern X86TSS64 BS3_FAR_DATA Bs3Tss64Spare1;
1090	extern X86TSS64 BS3_FAR_DATA Bs3Tss64WithIopb;
1091	extern X86TSS32 BS3_FAR_DATA Bs3Tss32WithIopb;
1092	/** Interrupt redirection bitmap used by Bs3Tss32WithIopb. */
1093	extern uint8_t BS3_FAR_DATA Bs3SharedIntRedirBm[32];
1094	/** I/O permission bitmap used by Bs3Tss32WithIopb and Bs3Tss64WithIopb. */
1095	extern uint8_t BS3_FAR_DATA Bs3SharedIobp[8192+2];
1096	/** End of the I/O permission bitmap (exclusive). */
1097	extern uint8_t BS3_FAR_DATA Bs3SharedIobpEnd;
1098	/** 16-bit IDT. */
1099	extern X86DESC BS3_FAR_DATA Bs3Idt16[256];
1100	/** 32-bit IDT. */
1101	extern X86DESC BS3_FAR_DATA Bs3Idt32[256];
1102	/** 64-bit IDT. */
1103	extern X86DESC64 BS3_FAR_DATA Bs3Idt64[256];
1104	/** Structure for the LIDT instruction for loading the 16-bit IDT. */
1105	extern X86XDTR64 BS3_FAR_DATA Bs3Lidt_Idt16;
1106	/** Structure for the LIDT instruction for loading the 32-bit IDT. */
1107	extern X86XDTR64 BS3_FAR_DATA Bs3Lidt_Idt32;
1108	/** Structure for the LIDT instruction for loading the 64-bit IDT. */
1109	extern X86XDTR64 BS3_FAR_DATA Bs3Lidt_Idt64;
1110	/** Structure for the LIDT instruction for loading the real mode interrupt
1111	* vector table. */
1112	extern X86XDTR64 BS3_FAR_DATA Bs3Lidt_Ivt;
1113	/** Structure for the LGDT instruction for loading the current GDT. */
1114	extern X86XDTR64 BS3_FAR_DATA Bs3Lgdt_Gdt;
1115	/** Structure for the LGDT instruction for loading the default GDT. */
1116	extern X86XDTR64 BS3_FAR_DATA Bs3LgdtDef_Gdt;
1117	/** The LDT (all entries are empty, fill in for testing). */
1118	extern X86DESC BS3_FAR_DATA Bs3Ldt[116];
1119	/** The end of the LDT (exclusive). */
1120	extern X86DESC BS3_FAR_DATA Bs3LdtEnd;
1121
1122	/** @} */
1123
1124
1125	/** @name Segment start and end markers, sizes.
1126	* @{ */
1127	/** Start of the BS3TEXT16 segment. */
1128	extern uint8_t BS3_FAR_DATA Bs3Text16_StartOfSegment;
1129	/** End of the BS3TEXT16 segment. */
1130	extern uint8_t BS3_FAR_DATA Bs3Text16_EndOfSegment;
1131	/** The size of the BS3TEXT16 segment. */
1132	extern uint16_t BS3_FAR_DATA Bs3Text16_Size;
1133
1134	/** Start of the BS3SYSTEM16 segment. */
1135	extern uint8_t BS3_FAR_DATA Bs3System16_StartOfSegment;
1136	/** End of the BS3SYSTEM16 segment. */
1137	extern uint8_t BS3_FAR_DATA Bs3System16_EndOfSegment;
1138
1139	/** Start of the BS3DATA16/BS3KIT_GRPNM_DATA16 segment. */
1140	extern uint8_t BS3_FAR_DATA Bs3Data16_StartOfSegment;
1141	/** End of the BS3DATA16/BS3KIT_GRPNM_DATA16 segment. */
1142	extern uint8_t BS3_FAR_DATA Bs3Data16_EndOfSegment;
1143
1144	/** Start of the BS3RMTEXT16 segment. */
1145	extern uint8_t BS3_FAR_DATA Bs3RmText16_StartOfSegment;
1146	/** End of the BS3RMTEXT16 segment. */
1147	extern uint8_t BS3_FAR_DATA Bs3RmText16_EndOfSegment;
1148	/** The size of the BS3RMTEXT16 segment. */
1149	extern uint16_t BS3_FAR_DATA Bs3RmText16_Size;
1150	/** The flat start address of the BS3X0TEXT16 segment. */
1151	extern uint32_t BS3_FAR_DATA Bs3RmText16_FlatAddr;
1152
1153	/** Start of the BS3X0TEXT16 segment. */
1154	extern uint8_t BS3_FAR_DATA Bs3X0Text16_StartOfSegment;
1155	/** End of the BS3X0TEXT16 segment. */
1156	extern uint8_t BS3_FAR_DATA Bs3X0Text16_EndOfSegment;
1157	/** The size of the BS3X0TEXT16 segment. */
1158	extern uint16_t BS3_FAR_DATA Bs3X0Text16_Size;
1159	/** The flat start address of the BS3X0TEXT16 segment. */
1160	extern uint32_t BS3_FAR_DATA Bs3X0Text16_FlatAddr;
1161
1162	/** Start of the BS3X1TEXT16 segment. */
1163	extern uint8_t BS3_FAR_DATA Bs3X1Text16_StartOfSegment;
1164	/** End of the BS3X1TEXT16 segment. */
1165	extern uint8_t BS3_FAR_DATA Bs3X1Text16_EndOfSegment;
1166	/** The size of the BS3X1TEXT16 segment. */
1167	extern uint16_t BS3_FAR_DATA Bs3X1Text16_Size;
1168	/** The flat start address of the BS3X1TEXT16 segment. */
1169	extern uint32_t BS3_FAR_DATA Bs3X1Text16_FlatAddr;
1170
1171	/** Start of the BS3TEXT32 segment. */
1172	extern uint8_t BS3_FAR_DATA Bs3Text32_StartOfSegment;
1173	/** Start of the BS3TEXT32 segment. */
1174	extern uint8_t BS3_FAR_DATA Bs3Text32_EndOfSegment;
1175
1176	/** Start of the BS3DATA32 segment. */
1177	extern uint8_t BS3_FAR_DATA Bs3Data32_StartOfSegment;
1178	/** Start of the BS3DATA32 segment. */
1179	extern uint8_t BS3_FAR_DATA Bs3Data32_EndOfSegment;
1180
1181	/** Start of the BS3TEXT64 segment. */
1182	extern uint8_t BS3_FAR_DATA Bs3Text64_StartOfSegment;
1183	/** Start of the BS3TEXT64 segment. */
1184	extern uint8_t BS3_FAR_DATA Bs3Text64_EndOfSegment;
1185
1186	/** Start of the BS3DATA64 segment. */
1187	extern uint8_t BS3_FAR_DATA Bs3Data64_StartOfSegment;
1188	/** Start of the BS3DATA64 segment. */
1189	extern uint8_t BS3_FAR_DATA Bs3Data64_EndOfSegment;
1190
1191	/** The size of the Data16, Text32, Text64, Data32 and Data64 blob. */
1192	extern uint32_t BS3_FAR_DATA Bs3Data16Thru64Text32And64_TotalSize;
1193	/** The total image size (from Text16 thu Data64). */
1194	extern uint32_t BS3_FAR_DATA Bs3TotalImageSize;
1195	/** @} */
1196
1197
1198	/** Lower case hex digits. */
1199	extern char const g_achBs3HexDigits[16+1];
1200	/** Upper case hex digits. */
1201	extern char const g_achBs3HexDigitsUpper[16+1];
1202
1203
1204	/** The current mode (BS3_MODE_XXX) of CPU \#0. */
1205	extern uint8_t g_bBs3CurrentMode;
1206
1207	/** Hint for 16-bit trap handlers regarding the high word of EIP. */
1208	extern uint32_t g_uBs3TrapEipHint;
1209
1210	/** Set to disable special V8086 \#GP and \#UD handling in Bs3TrapDefaultHandler.
1211	* This is useful for getting */
1212	extern bool volatile g_fBs3TrapNoV86Assist;
1213
1214	/** Copy of the original real-mode interrupt vector table. */
1215	extern RTFAR16 g_aBs3RmIvtOriginal[256];
1216
1217
1218	#ifdef __WATCOMC__
1219	/**
1220	* Executes the SMSW instruction and returns the value.
1221	*
1222	* @returns Machine status word.
1223	*/
1224	uint16_t Bs3AsmSmsw(void);
1225	# pragma aux Bs3AsmSmsw = \
1226	".286" \
1227	"smsw ax" \
1228	value [ax] modify exact [ax] nomemory;
1229	#endif
1230
1231
1232	/** @defgroup bs3kit_cross_ptr Cross Context Pointer Type
1233	*
1234	* The cross context pointer type is
1235	*
1236	* @{ */
1237
1238	/**
1239	* Cross context pointer base type.
1240	*/
1241	typedef union BS3XPTR
1242	{
1243	/** The flat pointer. */
1244	uint32_t uFlat;
1245	/** 16-bit view. */
1246	struct
1247	{
1248	uint16_t uLow;
1249	uint16_t uHigh;
1250	} u;
1251	#if ARCH_BITS == 16
1252	/** 16-bit near pointer. */
1253	void __near *pvNear;
1254	#elif ARCH_BITS == 32
1255	/** 32-bit pointer. */
1256	void *pvRaw;
1257	#endif
1258	} BS3XPTR;
1259	AssertCompileSize(BS3XPTR, 4);
1260
1261
1262	/** @def BS3_XPTR_DEF_INTERNAL
1263	* Internal worker.
1264	*
1265	* @param a_Scope RT_NOTHING if structure or global, static or extern
1266	* otherwise.
1267	* @param a_Type The type we're pointing to.
1268	* @param a_Name The member or variable name.
1269	* @internal
1270	*/
1271	#if ARCH_BITS == 16
1272	# define BS3_XPTR_DEF_INTERNAL(a_Scope, a_Type, a_Name) \
1273	a_Scope union \
1274	{ \
1275	BS3XPTR XPtr; \
1276	a_Type __near *pNearTyped; \
1277	} a_Name
1278	#elif ARCH_BITS == 32
1279	# define BS3_XPTR_DEF_INTERNAL(a_Scope, a_Type, a_Name) \
1280	a_Scope union \
1281	{ \
1282	BS3XPTR XPtr; \
1283	a_Type *pTyped; \
1284	} a_Name
1285	#elif ARCH_BITS == 64
1286	# define BS3_XPTR_DEF_INTERNAL(a_Scope, a_Type, a_Name) \
1287	a_Scope union \
1288	{ \
1289	BS3XPTR XPtr; \
1290	} a_Name
1291	#else
1292	# error "ARCH_BITS"
1293	#endif
1294
1295	/** @def BS3_XPTR_MEMBER
1296	* Defines a pointer member that can be shared by all CPU modes.
1297	*
1298	* @param a_Type The type we're pointing to.
1299	* @param a_Name The member or variable name.
1300	*/
1301	#define BS3_XPTR_MEMBER(a_Type, a_Name) BS3_XPTR_DEF_INTERNAL(RT_NOTHING, a_Type, a_Name)
1302
1303	/** @def BS3_XPTR_AUTO
1304	* Defines a pointer static variable for working with an XPTR.
1305	*
1306	* This is typically used to convert flat pointers into context specific
1307	* pointers.
1308	*
1309	* @param a_Type The type we're pointing to.
1310	* @param a_Name The member or variable name.
1311	*/
1312	#define BS3_XPTR_AUTO(a_Type, a_Name) BS3_XPTR_DEF_INTERNAL(RT_NOTHING, a_Type, a_Name)
1313
1314	/** @def BS3_XPTR_SET_FLAT
1315	* Sets a cross context pointer.
1316	*
1317	* @param a_Type The type we're pointing to.
1318	* @param a_Name The member or variable name.
1319	* @param a_uFlatPtr The flat pointer value to assign. If the x-pointer is
1320	* used in real mode, this must be less than 1MB.
1321	* Otherwise the limit is 16MB (due to selector tiling).
1322	*/
1323	#define BS3_XPTR_SET_FLAT(a_Type, a_Name, a_uFlatPtr) \
1324	do { a_Name.XPtr.uFlat = (a_uFlatPtr); } while (0)
1325
1326	/** @def BS3_XPTR_GET_FLAT
1327	* Gets the flat address of a cross context pointer.
1328	*
1329	* @returns 32-bit flat pointer.
1330	* @param a_Type The type we're pointing to.
1331	* @param a_Name The member or variable name.
1332	*/
1333	#define BS3_XPTR_GET_FLAT(a_Type, a_Name) (a_Name.XPtr.uFlat)
1334
1335	/** @def BS3_XPTR_GET_FLAT_LOW
1336	* Gets the low 16 bits of the flat address.
1337	*
1338	* @returns Low 16 bits of the flat pointer.
1339	* @param a_Type The type we're pointing to.
1340	* @param a_Name The member or variable name.
1341	*/
1342	#define BS3_XPTR_GET_FLAT_LOW(a_Type, a_Name) (a_Name.XPtr.u.uLow)
1343
1344
1345	#if ARCH_BITS == 16
1346
1347	/**
1348	* Gets the current ring number.
1349	* @returns Ring number.
1350	*/
1351	DECLINLINE(uint16_t) Bs3Sel16GetCurRing(void);
1352	# pragma aux Bs3Sel16GetCurRing = \
1353	"mov ax, ss" \
1354	"and ax, 3" \
1355	value [ax] modify exact [ax] nomemory;
1356
1357	/**
1358	* Converts the high word of a flat pointer into a 16-bit selector.
1359	*
1360	* This makes use of the tiled area. It also handles real mode.
1361	*
1362	* @returns Segment selector value.
1363	* @param uHigh The high part of flat pointer.
1364	* @sa BS3_XPTR_GET, BS3_XPTR_SET
1365	*/
1366	DECLINLINE(__segment) Bs3Sel16HighFlatPtrToSelector(uint16_t uHigh)
1367	{
1368	if (!BS3_MODE_IS_RM_OR_V86(g_bBs3CurrentMode))
1369	return (__segment)(((uHigh << 3) + BS3_SEL_TILED) \| Bs3Sel16GetCurRing());
1370	return (__segment)(uHigh << 12);
1371	}
1372
1373	#endif /* ARCH_BITS == 16 */
1374
1375	/** @def BS3_XPTR_GET
1376	* Gets the current context pointer value.
1377	*
1378	* @returns Usable pointer.
1379	* @param a_Type The type we're pointing to.
1380	* @param a_Name The member or variable name.
1381	*/
1382	#if ARCH_BITS == 16
1383	# define BS3_XPTR_GET(a_Type, a_Name) \
1384	((a_Type BS3_FAR *)BS3_FP_MAKE(Bs3Sel16HighFlatPtrToSelector((a_Name).XPtr.u.uHigh), (a_Name).pNearTyped))
1385	#elif ARCH_BITS == 32
1386	# define BS3_XPTR_GET(a_Type, a_Name) ((a_Name).pTyped)
1387	#elif ARCH_BITS == 64
1388	# define BS3_XPTR_GET(a_Type, a_Name) ((a_Type *)(uintptr_t)(a_Name).XPtr.uFlat)
1389	#else
1390	# error "ARCH_BITS"
1391	#endif
1392
1393	/** @def BS3_XPTR_SET
1394	* Gets the current context pointer value.
1395	*
1396	* @returns Usable pointer.
1397	* @param a_Type The type we're pointing to.
1398	* @param a_Name The member or variable name.
1399	* @param a_pValue The new pointer value, current context pointer.
1400	*/
1401	#if ARCH_BITS == 16
1402	# define BS3_XPTR_SET(a_Type, a_Name, a_pValue) \
1403	do { \
1404	a_Type BS3_FAR *pTypeCheck = (a_pValue); \
1405	if (BS3_MODE_IS_RM_OR_V86(g_bBs3CurrentMode)) \
1406	(a_Name).XPtr.uFlat = BS3_FP_OFF(pTypeCheck) + ((uint32_t)BS3_FP_SEG(pTypeCheck) << 4); \
1407	else \
1408	{ \
1409	(a_Name).XPtr.u.uLow = BS3_FP_OFF(pTypeCheck); \
1410	(a_Name).XPtr.u.uHigh = ((BS3_FP_SEG(pTypeCheck) & UINT16_C(0xfff8)) - BS3_SEL_TILED) >> 3; \
1411	} \
1412	} while (0)
1413	#elif ARCH_BITS == 32
1414	# define BS3_XPTR_SET(a_Type, a_Name, a_pValue) \
1415	do { (a_Name).pTyped = (a_pValue); } while (0)
1416	#elif ARCH_BITS == 64
1417	# define BS3_XPTR_SET(a_Type, a_Name, a_pValue) \
1418	do { \
1419	a_Type *pTypeCheck = (a_pValue); \
1420	(a_Name).XPtr.uFlat = (uint32_t)(uintptr_t)pTypeCheck; \
1421	} while (0)
1422	#else
1423	# error "ARCH_BITS"
1424	#endif
1425
1426
1427	/** @def BS3_XPTR_IS_NULL
1428	* Checks if the cross context pointer is NULL.
1429	*
1430	* @returns true if NULL, false if not.
1431	* @param a_Type The type we're pointing to.
1432	* @param a_Name The member or variable name.
1433	*/
1434	#define BS3_XPTR_IS_NULL(a_Type, a_Name) ((a_Name).XPtr.uFlat == 0)
1435
1436	/**
1437	* Gets a working pointer from a flat address.
1438	*
1439	* @returns Current context pointer.
1440	* @param uFlatPtr The flat address to convert (32-bit or 64-bit).
1441	*/
1442	DECLINLINE(void BS3_FAR *) Bs3XptrFlatToCurrent(RTCCUINTXREG uFlatPtr)
1443	{
1444	BS3_XPTR_AUTO(void, pTmp);
1445	BS3_XPTR_SET_FLAT(void, pTmp, uFlatPtr);
1446	return BS3_XPTR_GET(void, pTmp);
1447	}
1448
1449	/** @} */
1450
1451
1452
1453	/** @defgroup grp_bs3kit_cmn Common Functions and Data
1454	*
1455	* The common functions comes in three variations: 16-bit, 32-bit and 64-bit.
1456	* Templated code uses the #BS3_CMN_NM macro to mangle the name according to the
1457	* desired
1458	*
1459	* @{
1460	*/
1461
1462	/** @def BS3_CMN_PROTO_INT
1463	* Internal macro for prototyping all the variations of a common function.
1464	* @param a_RetType The return type.
1465	* @param a_Name The function basename.
1466	* @param a_Params The parameter list (in parentheses).
1467	* @sa BS3_CMN_PROTO_STUB, BS3_CMN_PROTO_NOSB
1468	*/
1469	#if ARCH_BITS == 16
1470	# ifndef BS3_USE_ALT_16BIT_TEXT_SEG
1471	# define BS3_CMN_PROTO_INT(a_RetType, a_Name, a_Params) \
1472	BS3_DECL_NEAR(a_RetType) BS3_CMN_NM(a_Name) a_Params; \
1473	BS3_DECL_FAR(a_RetType) BS3_CMN_FAR_NM(a_Name) a_Params
1474	# else
1475	# define BS3_CMN_PROTO_INT(a_RetType, a_Name, a_Params) \
1476	BS3_DECL_FAR(a_RetType) BS3_CMN_FAR_NM(a_Name) a_Params
1477	# endif
1478	#else
1479	# define BS3_CMN_PROTO_INT(a_RetType, a_Name, a_Params) \
1480	BS3_DECL_NEAR(a_RetType) BS3_CMN_NM(a_Name) a_Params
1481	#endif
1482
1483	/** @def BS3_CMN_PROTO_STUB
1484	* Macro for prototyping all the variations of a common function with automatic
1485	* near -> far stub.
1486	*
1487	* @param a_RetType The return type.
1488	* @param a_Name The function basename.
1489	* @param a_Params The parameter list (in parentheses).
1490	* @sa BS3_CMN_PROTO_NOSB
1491	*/
1492	#define BS3_CMN_PROTO_STUB(a_RetType, a_Name, a_Params) BS3_CMN_PROTO_INT(a_RetType, a_Name, a_Params)
1493
1494	/** @def BS3_CMN_PROTO_NOSB
1495	* Macro for prototyping all the variations of a common function without any
1496	* near > far stub.
1497	*
1498	* @param a_RetType The return type.
1499	* @param a_Name The function basename.
1500	* @param a_Params The parameter list (in parentheses).
1501	* @sa BS3_CMN_PROTO_STUB
1502	*/
1503	#define BS3_CMN_PROTO_NOSB(a_RetType, a_Name, a_Params) BS3_CMN_PROTO_INT(a_RetType, a_Name, a_Params)
1504
1505	/** @def BS3_CMN_PROTO_FARSTUB
1506	* Macro for prototyping all the variations of a common function with automatic
1507	* far -> near stub.
1508	*
1509	* @param a_cbParam16 The size of the 16-bit parameter list in bytes.
1510	* @param a_RetType The return type.
1511	* @param a_Name The function basename.
1512	* @param a_Params The parameter list (in parentheses).
1513	* @sa BS3_CMN_PROTO_STUB
1514	*/
1515	#define BS3_CMN_PROTO_FARSTUB(a_cbParam16, a_RetType, a_Name, a_Params) BS3_CMN_PROTO_INT(a_RetType, a_Name, a_Params)
1516
1517
1518	/** @def BS3_CMN_DEF
1519	* Macro for defining a common function.
1520	*
1521	* This makes 16-bit common function far, while 32-bit and 64-bit are near.
1522	*
1523	* @param a_RetType The return type.
1524	* @param a_Name The function basename.
1525	* @param a_Params The parameter list (in parentheses).
1526	*/
1527	#if ARCH_BITS == 16
1528	# define BS3_CMN_DEF(a_RetType, a_Name, a_Params) \
1529	BS3_DECL_FAR(a_RetType) BS3_CMN_FAR_NM(a_Name) a_Params
1530	#else
1531	# define BS3_CMN_DEF(a_RetType, a_Name, a_Params) \
1532	BS3_DECL_NEAR(a_RetType) BS3_CMN_NM(a_Name) a_Params
1533	#endif
1534
1535	/** @def BS3_ASSERT
1536	* Assert that an expression is true.
1537	*
1538	* Calls Bs3Panic if false and it's a strict build. Does nothing in
1539	* non-strict builds. */
1540	#ifdef BS3_STRICT
1541	# define BS3_ASSERT(a_Expr) do { if (!!(a_Expr)) { /* likely / } else { Bs3Panic(); } } while (0) /< @todo later /
1542	#else
1543	# define BS3_ASSERT(a_Expr) do { } while (0)
1544	#endif
1545
1546	/**
1547	* Panic, never return.
1548	*
1549	* The current implementation will only halt the CPU.
1550	*/
1551	BS3_CMN_PROTO_NOSB(DECL_NO_RETURN(void), Bs3Panic,(void));
1552	#if !defined(BS3_KIT_WITH_NO_RETURN) && defined(__WATCOMC__)
1553	# pragma aux Bs3Panic_c16 __aborts
1554	# pragma aux Bs3Panic_f16 __aborts
1555	# pragma aux Bs3Panic_c32 __aborts
1556	#endif
1557
1558
1559	/**
1560	* Translate a mode into a string.
1561	*
1562	* @returns Pointer to read-only mode name string.
1563	* @param bMode The mode value (BS3_MODE_XXX).
1564	*/
1565	BS3_CMN_PROTO_STUB(const char BS3_FAR *, Bs3GetModeName,(uint8_t bMode));
1566
1567	/**
1568	* Translate a mode into a short lower case string.
1569	*
1570	* @returns Pointer to read-only short mode name string.
1571	* @param bMode The mode value (BS3_MODE_XXX).
1572	*/
1573	BS3_CMN_PROTO_STUB(const char BS3_FAR *, Bs3GetModeNameShortLower,(uint8_t bMode));
1574
1575	/** CPU vendors. */
1576	typedef enum BS3CPUVENDOR
1577	{
1578	BS3CPUVENDOR_INVALID = 0,
1579	BS3CPUVENDOR_INTEL,
1580	BS3CPUVENDOR_AMD,
1581	BS3CPUVENDOR_VIA,
1582	BS3CPUVENDOR_CYRIX,
1583	BS3CPUVENDOR_SHANGHAI,
1584	BS3CPUVENDOR_HYGON,
1585	BS3CPUVENDOR_UNKNOWN,
1586	BS3CPUVENDOR_END
1587	} BS3CPUVENDOR;
1588
1589	/**
1590	* Tries to detect the CPU vendor.
1591	*
1592	* @returns CPU vendor.
1593	*/
1594	BS3_CMN_PROTO_STUB(BS3CPUVENDOR, Bs3GetCpuVendor,(void));
1595
1596	/**
1597	* Shutdown the system, never returns.
1598	*
1599	* This currently only works for VMs. When running on real systems it will
1600	* just halt the CPU.
1601	*/
1602	BS3_CMN_PROTO_NOSB(void, Bs3Shutdown,(void));
1603
1604	/**
1605	* Prints a 32-bit unsigned value as decimal to the screen.
1606	*
1607	* @param uValue The 32-bit value.
1608	*/
1609	BS3_CMN_PROTO_NOSB(void, Bs3PrintU32,(uint32_t uValue));
1610
1611	/**
1612	* Prints a 32-bit unsigned value as hex to the screen.
1613	*
1614	* @param uValue The 32-bit value.
1615	*/
1616	BS3_CMN_PROTO_NOSB(void, Bs3PrintX32,(uint32_t uValue));
1617
1618	/**
1619	* Formats and prints a string to the screen.
1620	*
1621	* See #Bs3StrFormatV for supported format types.
1622	*
1623	* @param pszFormat The format string.
1624	* @param ... Format arguments.
1625	*/
1626	BS3_CMN_PROTO_STUB(size_t, Bs3Printf,(const char BS3_FAR *pszFormat, ...));
1627
1628	/**
1629	* Formats and prints a string to the screen, va_list version.
1630	*
1631	* See #Bs3StrFormatV for supported format types.
1632	*
1633	* @param pszFormat The format string.
1634	* @param va Format arguments.
1635	*/
1636	BS3_CMN_PROTO_STUB(size_t, Bs3PrintfV,(const char BS3_FAR *pszFormat, va_list BS3_FAR va));
1637
1638	/**
1639	* Prints a string to the screen.
1640	*
1641	* @param pszString The string to print.
1642	*/
1643	BS3_CMN_PROTO_STUB(void, Bs3PrintStr,(const char BS3_FAR *pszString));
1644
1645	/**
1646	* Prints a string to the screen.
1647	*
1648	* @param pszString The string to print. Any terminator charss will be printed.
1649	* @param cchString The exact number of characters to print.
1650	*/
1651	BS3_CMN_PROTO_NOSB(void, Bs3PrintStrN,(const char BS3_FAR *pszString, size_t cchString));
1652
1653	/**
1654	* Prints a char to the screen.
1655	*
1656	* @param ch The character to print.
1657	*/
1658	BS3_CMN_PROTO_NOSB(void, Bs3PrintChr,(char ch));
1659
1660
1661	/**
1662	* An output function for #Bs3StrFormatV.
1663	*
1664	* @returns Number of characters written.
1665	* @param ch The character to write. Zero in the final call.
1666	* @param pvUser User argument supplied to #Bs3StrFormatV.
1667	*/
1668	typedef BS3_DECL_CALLBACK(size_t) FNBS3STRFORMATOUTPUT(char ch, void BS3_FAR *pvUser);
1669	/** Pointer to an output function for #Bs3StrFormatV. */
1670	typedef FNBS3STRFORMATOUTPUT *PFNBS3STRFORMATOUTPUT;
1671
1672	/**
1673	* Formats a string, sending the output to @a pfnOutput.
1674	*
1675	* Supported types:
1676	* - %RI8, %RI16, %RI32, %RI64
1677	* - %RU8, %RU16, %RU32, %RU64
1678	* - %RX8, %RX16, %RX32, %RX64
1679	* - %i, %d
1680	* - %u
1681	* - %x
1682	* - %c
1683	* - %p (far pointer)
1684	* - %s (far pointer)
1685	*
1686	* @returns Sum of @a pfnOutput return values.
1687	* @param pszFormat The format string.
1688	* @param va Format arguments.
1689	* @param pfnOutput The output function.
1690	* @param pvUser The user argument for the output function.
1691	*/
1692	BS3_CMN_PROTO_STUB(size_t, Bs3StrFormatV,(const char BS3_FAR *pszFormat, va_list BS3_FAR va,
1693	PFNBS3STRFORMATOUTPUT pfnOutput, void BS3_FAR *pvUser));
1694
1695	/**
1696	* Formats a string into a buffer.
1697	*
1698	* See #Bs3StrFormatV for supported format types.
1699	*
1700	* @returns The length of the formatted string (excluding terminator).
1701	* This will be higher or equal to @c cbBuf in case of an overflow.
1702	* @param pszBuf The output buffer.
1703	* @param cbBuf The size of the output buffer.
1704	* @param pszFormat The format string.
1705	* @param va Format arguments.
1706	*/
1707	BS3_CMN_PROTO_STUB(size_t, Bs3StrPrintfV,(char BS3_FAR pszBuf, size_t cbBuf, const char BS3_FAR pszFormat, va_list BS3_FAR va));
1708
1709	/**
1710	* Formats a string into a buffer.
1711	*
1712	* See #Bs3StrFormatV for supported format types.
1713	*
1714	* @returns The length of the formatted string (excluding terminator).
1715	* This will be higher or equal to @c cbBuf in case of an overflow.
1716	* @param pszBuf The output buffer.
1717	* @param cbBuf The size of the output buffer.
1718	* @param pszFormat The format string.
1719	* @param ... Format arguments.
1720	*/
1721	BS3_CMN_PROTO_STUB(size_t, Bs3StrPrintf,(char BS3_FAR pszBuf, size_t cbBuf, const char BS3_FAR pszFormat, ...));
1722
1723
1724	/**
1725	* Finds the length of a zero terminated string.
1726	*
1727	* @returns String length in chars/bytes.
1728	* @param pszString The string to examine.
1729	*/
1730	BS3_CMN_PROTO_STUB(size_t, Bs3StrLen,(const char BS3_FAR *pszString));
1731
1732	/**
1733	* Finds the length of a zero terminated string, but with a max length.
1734	*
1735	* @returns String length in chars/bytes, or @a cchMax if no zero-terminator
1736	* was found before we reached the limit.
1737	* @param pszString The string to examine.
1738	* @param cchMax The max length to examine.
1739	*/
1740	BS3_CMN_PROTO_STUB(size_t, Bs3StrNLen,(const char BS3_FAR *pszString, size_t cchMax));
1741
1742	/**
1743	* CRT style unsafe strcpy.
1744	*
1745	* @returns pszDst.
1746	* @param pszDst The destination buffer. Must be large enough to
1747	* hold the source string.
1748	* @param pszSrc The source string.
1749	*/
1750	BS3_CMN_PROTO_STUB(char BS3_FAR , Bs3StrCpy,(char BS3_FAR pszDst, const char BS3_FAR *pszSrc));
1751
1752	/**
1753	* CRT style memcpy.
1754	*
1755	* @returns pvDst
1756	* @param pvDst The destination buffer.
1757	* @param pvSrc The source buffer.
1758	* @param cbToCopy The number of bytes to copy.
1759	*/
1760	BS3_CMN_PROTO_STUB(void BS3_FAR , Bs3MemCpy,(void BS3_FAR pvDst, const void BS3_FAR *pvSrc, size_t cbToCopy));
1761
1762	/**
1763	* GNU (?) style mempcpy.
1764	*
1765	* @returns pvDst + cbCopy
1766	* @param pvDst The destination buffer.
1767	* @param pvSrc The source buffer.
1768	* @param cbToCopy The number of bytes to copy.
1769	*/
1770	BS3_CMN_PROTO_STUB(void BS3_FAR , Bs3MemPCpy,(void BS3_FAR pvDst, const void BS3_FAR *pvSrc, size_t cbToCopy));
1771
1772	/**
1773	* CRT style memmove (overlapping buffers is fine).
1774	*
1775	* @returns pvDst
1776	* @param pvDst The destination buffer.
1777	* @param pvSrc The source buffer.
1778	* @param cbToCopy The number of bytes to copy.
1779	*/
1780	BS3_CMN_PROTO_STUB(void BS3_FAR , Bs3MemMove,(void BS3_FAR pvDst, const void BS3_FAR *pvSrc, size_t cbToCopy));
1781
1782	/**
1783	* BSD style bzero.
1784	*
1785	* @param pvDst The buffer to be zeroed.
1786	* @param cbDst The number of bytes to zero.
1787	*/
1788	BS3_CMN_PROTO_NOSB(void, Bs3MemZero,(void BS3_FAR *pvDst, size_t cbDst));
1789
1790	/**
1791	* CRT style memset.
1792	*
1793	* @param pvDst The buffer to be fill.
1794	* @param bFiller The filler byte.
1795	* @param cbDst The number of bytes to fill.
1796	*/
1797	BS3_CMN_PROTO_NOSB(void, Bs3MemSet,(void BS3_FAR *pvDst, uint8_t bFiller, size_t cbDst));
1798
1799	/**
1800	* CRT style memchr.
1801	*
1802	* @param pvHaystack The memory to scan for @a bNeedle.
1803	* @param bNeedle The byte to search for.
1804	* @param cbHaystack The amount of memory to search.
1805	*/
1806	BS3_CMN_PROTO_NOSB(void BS3_FAR , Bs3MemChr,(void const BS3_FAR pvHaystack, uint8_t bNeedle, size_t cbHaystack));
1807
1808	/**
1809	* CRT style memcmp.
1810	*
1811	* @returns 0 if equal. Negative if the left side is 'smaller' than the right
1812	* side, and positive in the other case.
1813	* @param pv1 The left hand memory.
1814	* @param pv2 The right hand memory.
1815	* @param cb The number of bytes to compare.
1816	*/
1817	BS3_CMN_PROTO_NOSB(int, Bs3MemCmp,(void const BS3_FAR pv1, void const BS3_FAR pv2, size_t cb));
1818
1819	BS3_CMN_PROTO_STUB(void, Bs3UInt64Div,(RTUINT64U uDividend, RTUINT64U uDivisor, RTUINT64U BS3_FAR *paQuotientReminder));
1820	BS3_CMN_PROTO_STUB(void, Bs3UInt32Div,(RTUINT32U uDividend, RTUINT32U uDivisor, RTUINT32U BS3_FAR *paQuotientReminder));
1821
1822
1823	/**
1824	* Converts a protected mode 32-bit far pointer to a 32-bit flat address.
1825	*
1826	* @returns 32-bit flat address.
1827	* @param off The segment offset.
1828	* @param uSel The protected mode segment selector.
1829	*/
1830	BS3_CMN_PROTO_STUB(uint32_t, Bs3SelProtFar32ToFlat32,(uint32_t off, uint16_t uSel));
1831
1832	/**
1833	* Converts a current mode 32-bit far pointer to a 32-bit flat address.
1834	*
1835	* @returns 32-bit flat address.
1836	* @param off The segment offset.
1837	* @param uSel The current mode segment selector.
1838	*/
1839	BS3_CMN_PROTO_STUB(uint32_t, Bs3SelFar32ToFlat32,(uint32_t off, uint16_t uSel));
1840
1841	/**
1842	* Wrapper around Bs3SelFar32ToFlat32 that makes it easier to use in tight
1843	* assembly spots.
1844	*
1845	* @returns 32-bit flat address.
1846	* @param off The segment offset.
1847	* @param uSel The current mode segment selector.
1848	* @remarks All register are preserved, except return.
1849	* @remarks No 20h scratch space required in 64-bit mode.
1850	*/
1851	BS3_CMN_PROTO_FARSTUB(6, uint32_t, Bs3SelFar32ToFlat32NoClobber,(uint32_t off, uint16_t uSel));
1852
1853	/**
1854	* Converts a real mode code segment to a protected mode code segment selector.
1855	*
1856	* @returns protected mode segment selector.
1857	* @param uRealSeg Real mode code segment.
1858	* @remarks All register are preserved, except return and parameter.
1859	*/
1860	BS3_CMN_PROTO_NOSB(uint16_t, Bs3SelRealModeCodeToProtMode,(uint16_t uRealSeg));
1861
1862	/**
1863	* Converts a real mode code segment to a protected mode code segment selector.
1864	*
1865	* @returns protected mode segment selector.
1866	* @param uProtSel Real mode code segment.
1867	* @remarks All register are preserved, except return and parameter.
1868	*/
1869	BS3_CMN_PROTO_NOSB(uint16_t, Bs3SelProtModeCodeToRealMode,(uint16_t uProtSel));
1870
1871	/**
1872	* Converts a flat code address to a real mode segment and offset.
1873	*
1874	* @returns Far real mode address (high 16-bit is segment, low is offset).
1875	* @param uFlatAddr Flat code address.
1876	* @remarks All register are preserved, except return and parameter.
1877	*/
1878	BS3_CMN_PROTO_NOSB(uint32_t, Bs3SelFlatCodeToRealMode,(uint32_t uFlatAddr));
1879
1880	/**
1881	* Converts a flat code address to a protected mode 16-bit far pointer (ring-0).
1882	*
1883	* @returns Far 16-bit protected mode address (high 16-bit is segment selector,
1884	* low is segment offset).
1885	* @param uFlatAddr Flat code address.
1886	* @remarks All register are preserved, except return and parameter.
1887	*/
1888	BS3_CMN_PROTO_NOSB(uint32_t, Bs3SelFlatCodeToProtFar16,(uint32_t uFlatAddr));
1889
1890	/**
1891	* Converts a far 16:16 real mode (code) address to a flat address.
1892	*
1893	* @returns 32-bit flat address.
1894	* @param uFar1616 Far real mode address (high 16-bit is segment, low
1895	* is offset).
1896	* @remarks All register are preserved, except return.
1897	* @remarks No 20h scratch space required in 64-bit mode.
1898	* @remarks Exactly the same as Bs3SelRealModeDataToFlat, except for param.
1899	*/
1900	BS3_CMN_PROTO_FARSTUB(4, uint32_t, Bs3SelRealModeCodeToFlat,(PFNBS3FARADDRCONV uFar1616));
1901
1902	/**
1903	* Converts a far 16:16 real mode (code) address to a 16-bit protected mode
1904	* address.
1905	*
1906	* This is mainly for converting X0TEXT16 and X1TEXT16 linker pointers to
1907	* protected mode ones.
1908	*
1909	* @returns Protected mode function pointer.
1910	* @param uFar1616 Far real mode address (high 16-bit is segment, low
1911	* is offset). In 16-bit code, this is also the same
1912	* as a linker address.
1913	*/
1914	BS3_CMN_PROTO_FARSTUB(4, PFNBS3FARADDRCONV, Bs3SelRealModeCodeToProtFar16,(PFNBS3FARADDRCONV uFar1616));
1915
1916	/**
1917	* Converts a flat data address to a real mode segment and offset.
1918	*
1919	* @returns Far real mode address (high 16-bit is segment, low is offset)
1920	* @param uFlatAddr Flat code address.
1921	* @remarks All register are preserved, except return.
1922	* @remarks No 20h scratch space required in 64-bit mode.
1923	*/
1924	BS3_CMN_PROTO_FARSTUB(4, uint32_t, Bs3SelFlatDataToRealMode,(uint32_t uFlatAddr));
1925
1926	/**
1927	* Converts a flat data address to a real mode segment and offset.
1928	*
1929	* @returns Far 16-bit protected mode address (high 16-bit is segment selector,
1930	* low is segment offset).
1931	* @param uFlatAddr Flat code address.
1932	* @remarks All register are preserved, except return.
1933	* @remarks No 20h scratch space required in 64-bit mode.
1934	*/
1935	BS3_CMN_PROTO_FARSTUB(4, uint32_t, Bs3SelFlatDataToProtFar16,(uint32_t uFlatAddr));
1936
1937	/**
1938	* Converts a far 16:16 data address to a real mode segment and offset.
1939	*
1940	* @returns Far real mode address (high 16-bit is segment, low is offset)
1941	* @param uFar1616 Far 16-bit protected mode address (high 16-bit is
1942	* segment selector, low is segment offset).
1943	* @remarks All register are preserved, except return.
1944	* @remarks No 20h scratch space required in 64-bit mode.
1945	*/
1946	BS3_CMN_PROTO_FARSTUB(4, uint32_t, Bs3SelProtFar16DataToRealMode,(uint32_t uFar1616));
1947
1948	/**
1949	* Converts a far 16:16 real mode address to a 16-bit protected mode address.
1950	*
1951	* @returns Far real mode address (high 16-bit is segment, low is offset)
1952	* @param uFar1616 Far real mode address (high 16-bit is segment, low
1953	* is offset).
1954	* @remarks All register are preserved, except return.
1955	* @remarks No 20h scratch space required in 64-bit mode.
1956	*/
1957	BS3_CMN_PROTO_FARSTUB(4, uint32_t, Bs3SelRealModeDataToProtFar16,(uint32_t uFar1616));
1958
1959	/**
1960	* Converts a far 16:16 data address to a flat 32-bit address.
1961	*
1962	* @returns 32-bit flat address.
1963	* @param uFar1616 Far 16-bit protected mode address (high 16-bit is
1964	* segment selector, low is segment offset).
1965	* @remarks All register are preserved, except return.
1966	* @remarks No 20h scratch space required in 64-bit mode.
1967	*/
1968	BS3_CMN_PROTO_FARSTUB(4, uint32_t, Bs3SelProtFar16DataToFlat,(uint32_t uFar1616));
1969
1970	/**
1971	* Converts a far 16:16 real mode address to a flat address.
1972	*
1973	* @returns 32-bit flat address.
1974	* @param uFar1616 Far real mode address (high 16-bit is segment, low
1975	* is offset).
1976	* @remarks All register are preserved, except return.
1977	* @remarks No 20h scratch space required in 64-bit mode.
1978	*/
1979	BS3_CMN_PROTO_FARSTUB(4, uint32_t, Bs3SelRealModeDataToFlat,(uint32_t uFar1616));
1980
1981	/**
1982	* Converts a link-time data pointer to a current context pointer.
1983	*
1984	* @returns Converted pointer.
1985	* @param pvLnkPtr The pointer the linker produced.
1986	*/
1987	BS3_CMN_PROTO_FARSTUB(4, void BS3_FAR , Bs3SelLnkPtrToCurPtr,(void BS3_FAR pvLnkPtr));
1988
1989	/**
1990	* Converts a link-time data pointer to a flat address.
1991	*
1992	* @returns 32-bit flag address.
1993	* @param pvLnkPtr The pointer the linker produced.
1994	*/
1995	BS3_CMN_PROTO_FARSTUB(4, uint32_t, Bs3SelLnkPtrToFlat,(void BS3_FAR *pvLnkPtr));
1996
1997	/**
1998	* Converts a link-time code pointer to a current context pointer.
1999	*
2000	* @returns Converted function pointer.
2001	* @param pfnLnkPtr The function pointer the linker produced.
2002	*/
2003	BS3_CMN_PROTO_FARSTUB(4, FPFNBS3FAR, Bs3SelLnkCodePtrToCurPtr,(FPFNBS3FAR pfnLnkPtr));
2004
2005	/**
2006	* Gets a flat address from a working poitner.
2007	*
2008	* @returns flat address (32-bit or 64-bit).
2009	* @param pv Current context pointer.
2010	*/
2011	DECLINLINE(RTCCUINTXREG) Bs3SelPtrToFlat(void BS3_FAR *pv)
2012	{
2013	#if ARCH_BITS == 16
2014	return BS3_CMN_FN_NM(Bs3SelFar32ToFlat32)(BS3_FP_OFF(pv), BS3_FP_SEG(pv));
2015	#else
2016	return (uintptr_t)pv;
2017	#endif
2018	}
2019
2020	/**
2021	* Sets up a 16-bit read-write data selector with ring-3 access and 64KB limit.
2022	*
2023	* @param pDesc Pointer to the descriptor table entry.
2024	* @param uBaseAddr The base address of the descriptor.
2025	*/
2026	BS3_CMN_PROTO_STUB(void, Bs3SelSetup16BitData,(X86DESC BS3_FAR *pDesc, uint32_t uBaseAddr));
2027
2028	/**
2029	* Sets up a 16-bit execute-read selector with a 64KB limit.
2030	*
2031	* @param pDesc Pointer to the descriptor table entry.
2032	* @param uBaseAddr The base address of the descriptor.
2033	* @param bDpl The descriptor privilege level.
2034	*/
2035	BS3_CMN_PROTO_STUB(void, Bs3SelSetup16BitCode,(X86DESC BS3_FAR *pDesc, uint32_t uBaseAddr, uint8_t bDpl));
2036
2037	/**
2038	* Sets up a 32-bit execute-read selector with a user specified limit.
2039	*
2040	* @param pDesc Pointer to the descriptor table entry.
2041	* @param uBaseAddr The base address of the descriptor.
2042	* @param uLimit The limit. (This is included here and not in the 16-bit
2043	* functions because we're more likely to want to set it
2044	* than for 16-bit selectors.)
2045	* @param bDpl The descriptor privilege level.
2046	*/
2047	BS3_CMN_PROTO_STUB(void, Bs3SelSetup32BitCode,(X86DESC BS3_FAR *pDesc, uint32_t uBaseAddr, uint32_t uLimit, uint8_t bDpl));
2048
2049	/**
2050	* Sets up a 16-bit or 32-bit gate descriptor.
2051	*
2052	* This can be used both for GDT/LDT and IDT.
2053	*
2054	* @param pDesc Pointer to the descriptor table entry.
2055	* @param bType The gate type.
2056	* @param bDpl The gate DPL.
2057	* @param uSel The gate selector value.
2058	* @param off The gate IP/EIP value.
2059	* @param cParams Number of parameters to copy if call-gate.
2060	*/
2061	BS3_CMN_PROTO_STUB(void, Bs3SelSetupGate,(X86DESC BS3_FAR *pDesc, uint8_t bType, uint8_t bDpl,
2062	uint16_t uSel, uint32_t off, uint8_t cParams));
2063
2064	/**
2065	* Sets up a 64-bit gate descriptor.
2066	*
2067	* This can be used both for GDT/LDT and IDT.
2068	*
2069	* @param pDescPair Pointer to the _two_ descriptor table entries.
2070	* @param bType The gate type.
2071	* @param bDpl The gate DPL.
2072	* @param uSel The gate selector value.
2073	* @param off The gate IP/EIP value.
2074	*/
2075	BS3_CMN_PROTO_STUB(void, Bs3SelSetupGate64,(X86DESC BS3_FAR *pDescPair, uint8_t bType, uint8_t bDpl, uint16_t uSel, uint64_t off));
2076
2077
2078	/**
2079	* Slab control structure list head.
2080	*
2081	* The slabs on the list must all have the same chunk size.
2082	*/
2083	typedef struct BS3SLABHEAD
2084	{
2085	/** Pointer to the first slab. */
2086	BS3_XPTR_MEMBER(struct BS3SLABCTL, pFirst);
2087	/** The allocation chunk size. */
2088	uint16_t cbChunk;
2089	/** Number of slabs in the list. */
2090	uint16_t cSlabs;
2091	/** Number of chunks in the list. */
2092	uint32_t cChunks;
2093	/** Number of free chunks. */
2094	uint32_t cFreeChunks;
2095	} BS3SLABHEAD;
2096	AssertCompileSize(BS3SLABHEAD, 16);
2097	/** Pointer to a slab list head. */
2098	typedef BS3SLABHEAD BS3_FAR *PBS3SLABHEAD;
2099
2100	/**
2101	* Allocation slab control structure.
2102	*
2103	* This may live at the start of the slab for 4KB slabs, while in a separate
2104	* static location for the larger ones.
2105	*/
2106	typedef struct BS3SLABCTL
2107	{
2108	/** Pointer to the next slab control structure in this list. */
2109	BS3_XPTR_MEMBER(struct BS3SLABCTL, pNext);
2110	/** Pointer to the slab list head. */
2111	BS3_XPTR_MEMBER(BS3SLABHEAD, pHead);
2112	/** The base address of the slab. */
2113	BS3_XPTR_MEMBER(uint8_t, pbStart);
2114	/** Number of chunks in this slab. */
2115	uint16_t cChunks;
2116	/** Number of currently free chunks. */
2117	uint16_t cFreeChunks;
2118	/** The chunk size. */
2119	uint16_t cbChunk;
2120	/** The shift count corresponding to cbChunk.
2121	* This is for turning a chunk number into a byte offset and vice versa. */
2122	uint16_t cChunkShift;
2123	/** Bitmap where set bits indicates allocated blocks (variable size,
2124	* multiple of 4). */
2125	uint8_t bmAllocated[4];
2126	} BS3SLABCTL;
2127	/** Pointer to a bs3kit slab control structure. */
2128	typedef BS3SLABCTL BS3_FAR *PBS3SLABCTL;
2129
2130	/** The chunks must all be in the same 16-bit segment tile. */
2131	#define BS3_SLAB_ALLOC_F_SAME_TILE UINT16_C(0x0001)
2132
2133	/**
2134	* Initializes a slab.
2135	*
2136	* @param pSlabCtl The slab control structure to initialize.
2137	* @param cbSlabCtl The size of the slab control structure.
2138	* @param uFlatSlabPtr The base address of the slab.
2139	* @param cbSlab The size of the slab.
2140	* @param cbChunk The chunk size.
2141	*/
2142	BS3_CMN_PROTO_STUB(void, Bs3SlabInit,(PBS3SLABCTL pSlabCtl, size_t cbSlabCtl, uint32_t uFlatSlabPtr,
2143	uint32_t cbSlab, uint16_t cbChunk));
2144
2145	/**
2146	* Allocates one chunk from a slab.
2147	*
2148	* @returns Pointer to a chunk on success, NULL if we're out of chunks.
2149	* @param pSlabCtl The slab control structure to allocate from.
2150	*/
2151	BS3_CMN_PROTO_STUB(void BS3_FAR *, Bs3SlabAlloc,(PBS3SLABCTL pSlabCtl));
2152
2153	/**
2154	* Allocates one or more chunks rom a slab.
2155	*
2156	* @returns Pointer to the request number of chunks on success, NULL if we're
2157	* out of chunks.
2158	* @param pSlabCtl The slab control structure to allocate from.
2159	* @param cChunks The number of contiguous chunks we want.
2160	* @param fFlags Flags, see BS3_SLAB_ALLOC_F_XXX
2161	*/
2162	BS3_CMN_PROTO_STUB(void BS3_FAR *, Bs3SlabAllocEx,(PBS3SLABCTL pSlabCtl, uint16_t cChunks, uint16_t fFlags));
2163
2164	/**
2165	* Frees one or more chunks from a slab.
2166	*
2167	* @returns Number of chunks actually freed. When correctly used, this will
2168	* match the @a cChunks parameter, of course.
2169	* @param pSlabCtl The slab control structure to free from.
2170	* @param uFlatChunkPtr The flat address of the chunks to free.
2171	* @param cChunks The number of contiguous chunks to free.
2172	*/
2173	BS3_CMN_PROTO_STUB(uint16_t, Bs3SlabFree,(PBS3SLABCTL pSlabCtl, uint32_t uFlatChunkPtr, uint16_t cChunks));
2174
2175
2176	/**
2177	* Initializes the given slab list head.
2178	*
2179	* @param pHead The slab list head.
2180	* @param cbChunk The chunk size.
2181	*/
2182	BS3_CMN_PROTO_STUB(void, Bs3SlabListInit,(PBS3SLABHEAD pHead, uint16_t cbChunk));
2183
2184	/**
2185	* Adds an initialized slab control structure to the list.
2186	*
2187	* @param pHead The slab list head to add it to.
2188	* @param pSlabCtl The slab control structure to add.
2189	*/
2190	BS3_CMN_PROTO_STUB(void, Bs3SlabListAdd,(PBS3SLABHEAD pHead, PBS3SLABCTL pSlabCtl));
2191
2192	/**
2193	* Allocates one chunk.
2194	*
2195	* @returns Pointer to a chunk on success, NULL if we're out of chunks.
2196	* @param pHead The slab list to allocate from.
2197	*/
2198	BS3_CMN_PROTO_STUB(void BS3_FAR *, Bs3SlabListAlloc,(PBS3SLABHEAD pHead));
2199
2200	/**
2201	* Allocates one or more chunks.
2202	*
2203	* @returns Pointer to the request number of chunks on success, NULL if we're
2204	* out of chunks.
2205	* @param pHead The slab list to allocate from.
2206	* @param cChunks The number of contiguous chunks we want.
2207	* @param fFlags Flags, see BS3_SLAB_ALLOC_F_XXX
2208	*/
2209	BS3_CMN_PROTO_STUB(void BS3_FAR *, Bs3SlabListAllocEx,(PBS3SLABHEAD pHead, uint16_t cChunks, uint16_t fFlags));
2210
2211	/**
2212	* Frees one or more chunks from a slab list.
2213	*
2214	* @param pHead The slab list to allocate from.
2215	* @param pvChunks Pointer to the first chunk to free.
2216	* @param cChunks The number of contiguous chunks to free.
2217	*/
2218	BS3_CMN_PROTO_STUB(void, Bs3SlabListFree,(PBS3SLABHEAD pHead, void BS3_FAR *pvChunks, uint16_t cChunks));
2219
2220	/**
2221	* Allocation addressing constraints.
2222	*/
2223	typedef enum BS3MEMKIND
2224	{
2225	/** Invalid zero type. */
2226	BS3MEMKIND_INVALID = 0,
2227	/** Real mode addressable memory. */
2228	BS3MEMKIND_REAL,
2229	/** Memory addressable using the 16-bit protected mode tiling. */
2230	BS3MEMKIND_TILED,
2231	/** Memory addressable using 32-bit flat addressing. */
2232	BS3MEMKIND_FLAT32,
2233	/** Memory addressable using 64-bit flat addressing. */
2234	BS3MEMKIND_FLAT64,
2235	/** End of valid types. */
2236	BS3MEMKIND_END,
2237	} BS3MEMKIND;
2238
2239	/**
2240	* Allocates low memory.
2241	*
2242	* @returns Pointer to a chunk on success, NULL if we're out of chunks.
2243	* @param enmKind The kind of addressing constraints imposed on the
2244	* allocation.
2245	* @param cb How much to allocate.
2246	*/
2247	BS3_CMN_PROTO_STUB(void BS3_FAR *, Bs3MemAlloc,(BS3MEMKIND enmKind, size_t cb));
2248
2249	/**
2250	* Allocates zero'ed memory.
2251	*
2252	* @param enmKind The kind of addressing constraints imposed on the
2253	* allocation.
2254	* @param cb How much to allocate.
2255	*/
2256	BS3_CMN_PROTO_STUB(void BS3_FAR *, Bs3MemAllocZ,(BS3MEMKIND enmKind, size_t cb));
2257
2258	/**
2259	* Frees memory.
2260	*
2261	* @returns Pointer to a chunk on success, NULL if we're out of chunks.
2262	* @param pv The memory to free (returned by #Bs3MemAlloc).
2263	* @param cb The size of the allocation.
2264	*/
2265	BS3_CMN_PROTO_STUB(void, Bs3MemFree,(void BS3_FAR *pv, size_t cb));
2266
2267	/**
2268	* Allocates a page with non-present pages on each side.
2269	*
2270	* @returns Pointer to the usable page. NULL on failure. Use
2271	* Bs3MemGuardedTestPageFree to free the allocation.
2272	* @param enmKind The kind of addressing constraints imposed on the
2273	* allocation.
2274	*/
2275	BS3_CMN_PROTO_STUB(void BS3_FAR *, Bs3MemGuardedTestPageAlloc,(BS3MEMKIND enmKind));
2276
2277	/**
2278	* Allocates a page with pages on each side to the @a fPte specification.
2279	*
2280	* @returns Pointer to the usable page. NULL on failure. Use
2281	* Bs3MemGuardedTestPageFree to free the allocation.
2282	* @param enmKind The kind of addressing constraints imposed on the
2283	* allocation.
2284	* @param fPte The page table entry specification for the guard pages.
2285	*/
2286	BS3_CMN_PROTO_STUB(void BS3_FAR *, Bs3MemGuardedTestPageAllocEx,(BS3MEMKIND enmKind, uint64_t fPte));
2287
2288	/**
2289	* Frees guarded page allocated by Bs3MemGuardedTestPageAlloc or
2290	* Bs3MemGuardedTestPageAllocEx.
2291	*
2292	* @param pvGuardedPage Pointer returned by Bs3MemGuardedTestPageAlloc or
2293	* Bs3MemGuardedTestPageAllocEx. NULL is ignored.
2294	*/
2295	BS3_CMN_PROTO_STUB(void, Bs3MemGuardedTestPageFree,(void BS3_FAR *pvGuardedPage));
2296
2297	/**
2298	* Print all heap info.
2299	*/
2300	BS3_CMN_PROTO_STUB(void, Bs3MemPrintInfo, (void));
2301
2302	/** The end RAM address below 4GB (approximately). */
2303	extern uint32_t g_uBs3EndOfRamBelow4G;
2304	/** The end RAM address above 4GB, zero if no memory above 4GB. */
2305	extern uint64_t g_uBs3EndOfRamAbove4G;
2306
2307
2308	/**
2309	* Enables the A20 gate.
2310	*/
2311	BS3_CMN_PROTO_NOSB(void, Bs3A20Enable,(void));
2312
2313	/**
2314	* Enables the A20 gate via the keyboard controller
2315	*/
2316	BS3_CMN_PROTO_NOSB(void, Bs3A20EnableViaKbd,(void));
2317
2318	/**
2319	* Enables the A20 gate via the PS/2 control port A.
2320	*/
2321	BS3_CMN_PROTO_NOSB(void, Bs3A20EnableViaPortA,(void));
2322
2323	/**
2324	* Disables the A20 gate.
2325	*/
2326	BS3_CMN_PROTO_NOSB(void, Bs3A20Disable,(void));
2327
2328	/**
2329	* Disables the A20 gate via the keyboard controller
2330	*/
2331	BS3_CMN_PROTO_NOSB(void, Bs3A20DisableViaKbd,(void));
2332
2333	/**
2334	* Disables the A20 gate via the PS/2 control port A.
2335	*/
2336	BS3_CMN_PROTO_NOSB(void, Bs3A20DisableViaPortA,(void));
2337
2338
2339	/**
2340	* Initializes root page tables for page protected mode (PP16, PP32).
2341	*
2342	* @returns IPRT status code.
2343	* @remarks Must not be called in real-mode!
2344	*/
2345	BS3_CMN_PROTO_STUB(int, Bs3PagingInitRootForPP,(void));
2346
2347	/**
2348	* Initializes root page tables for PAE page protected mode (PAE16, PAE32).
2349	*
2350	* @returns IPRT status code.
2351	* @remarks The default long mode page tables depends on the PAE ones.
2352	* @remarks Must not be called in real-mode!
2353	*/
2354	BS3_CMN_PROTO_STUB(int, Bs3PagingInitRootForPAE,(void));
2355
2356	/**
2357	* Initializes root page tables for long mode (LM16, LM32, LM64).
2358	*
2359	* @returns IPRT status code.
2360	* @remarks The default long mode page tables depends on the PAE ones.
2361	* @remarks Must not be called in real-mode!
2362	*/
2363	BS3_CMN_PROTO_STUB(int, Bs3PagingInitRootForLM,(void));
2364
2365	/**
2366	* Maps all RAM above 4GB into the long mode page tables.
2367	*
2368	* This requires Bs3PagingInitRootForLM to have been called first.
2369	*
2370	* @returns IPRT status code.
2371	* @retval VERR_WRONG_ORDER if Bs3PagingInitRootForLM wasn't called.
2372	* @retval VINF_ALREADY_INITIALIZED if already called or someone mapped
2373	* something else above 4GiB already.
2374	* @retval VERR_OUT_OF_RANGE if too much RAM (more than 2^47 bytes).
2375	* @retval VERR_NO_MEMORY if no more memory for paging structures.
2376	* @retval VERR_UNSUPPORTED_ALIGNMENT if the bs3kit allocator malfunctioned and
2377	* didn't give us page aligned memory as it should.
2378	*
2379	* @param puFailurePoint Where to return the address where we encountered
2380	* a failure. Optional.
2381	*
2382	* @remarks Must be called in 32-bit or 64-bit mode as paging structures will be
2383	* allocated using BS3MEMKIND_FLAT32, as there might not be sufficient
2384	* BS3MEMKIND_TILED memory around. (Also, too it's simply too much of
2385	* a bother to deal with 16-bit for something that's long-mode only.)
2386	*/
2387	BS3_CMN_PROTO_STUB(int, Bs3PagingMapRamAbove4GForLM,(uint64_t *puFailurePoint));
2388
2389	/**
2390	* Modifies the page table protection of an address range.
2391	*
2392	* This only works on the lowest level of the page tables in the current mode.
2393	*
2394	* Since we generally use the largest pages available when setting up the
2395	* initial page tables, this function will usually have to allocate and create
2396	* more tables. This may fail if we're low on memory.
2397	*
2398	* @returns IPRT status code.
2399	* @param uFlat The flat address of the first page in the range (rounded
2400	* down nearest page boundrary).
2401	* @param cb The range size from @a pv (rounded up to nearest page boundrary).
2402	* @param fSet Mask of zero or more X86_PTE_XXX values to set for the range.
2403	* @param fClear Mask of zero or more X86_PTE_XXX values to clear for the range.
2404	*/
2405	BS3_CMN_PROTO_STUB(int, Bs3PagingProtect,(uint64_t uFlat, uint64_t cb, uint64_t fSet, uint64_t fClear));
2406
2407	/**
2408	* Modifies the page table protection of an address range.
2409	*
2410	* This only works on the lowest level of the page tables in the current mode.
2411	*
2412	* Since we generally use the largest pages available when setting up the
2413	* initial page tables, this function will usually have to allocate and create
2414	* more tables. This may fail if we're low on memory.
2415	*
2416	* @returns IPRT status code.
2417	* @param pv The address of the first page in the range (rounded
2418	* down nearest page boundrary).
2419	* @param cb The range size from @a pv (rounded up to nearest page boundrary).
2420	* @param fSet Mask of zero or more X86_PTE_XXX values to set for the range.
2421	* @param fClear Mask of zero or more X86_PTE_XXX values to clear for the range.
2422	*/
2423	BS3_CMN_PROTO_STUB(int, Bs3PagingProtectPtr,(void BS3_FAR *pv, size_t cb, uint64_t fSet, uint64_t fClear));
2424
2425	/**
2426	* Aliases (maps) one or more contiguous physical pages to a virtual range.
2427	*
2428	* @returns VBox status code.
2429	* @retval VERR_INVALID_PARAMETER if we're in legacy paging mode and @a uDst or
2430	* @a uPhysToAlias are not compatible with legacy paging.
2431	* @retval VERR_OUT_OF_RANGE if we cannot traverse the page tables in this mode
2432	* (typically real mode or v86, maybe 16-bit PE).
2433	* @retval VERR_NO_MEMORY if we cannot allocate page tables for splitting up
2434	* the necessary large pages. No aliasing was performed.
2435	*
2436	* @param uDst The virtual address to map it at. Rounded down
2437	* to the nearest page (@a cbHowMuch is adjusted
2438	* up).
2439	* @param uPhysToAlias The physical address of the first page in the
2440	* (contiguous) range to map. Chopped down to
2441	* nearest page boundrary (@a cbHowMuch is not
2442	* adjusted).
2443	* @param cbHowMuch How much to map. Rounded up to nearest page.
2444	* @param fPte The PTE flags.
2445	*/
2446	BS3_CMN_PROTO_STUB(int, Bs3PagingAlias,(uint64_t uDst, uint64_t uPhysToAlias, uint32_t cbHowMuch, uint64_t fPte));
2447
2448	/**
2449	* Unaliases memory, i.e. restores the 1:1 mapping.
2450	*
2451	* @returns VBox status code. Cannot fail if @a uDst and @a cbHowMuch specify
2452	* the range of a successful Bs3PagingAlias call, however it may run
2453	* out of memory if it's breaking new ground.
2454	*
2455	* @param uDst The virtual address to restore to 1:1 mapping.
2456	* Rounded down to the nearest page (@a cbHowMuch
2457	* is adjusted up).
2458	* @param cbHowMuch How much to restore. Rounded up to nearest page.
2459	*/
2460	BS3_CMN_PROTO_STUB(int, Bs3PagingUnalias,(uint64_t uDst, uint32_t cbHowMuch));
2461
2462	/**
2463	* Get the pointer to the PTE for the given address.
2464	*
2465	* @returns Pointer to the PTE.
2466	* @param uFlat The flat address of the page which PTE we want.
2467	* @param prc Where to return additional error info. Optional.
2468	*/
2469	BS3_CMN_PROTO_STUB(void BS3_FAR , Bs3PagingGetPte,(uint64_t uFlat, int prc));
2470
2471	/**
2472	* Paging information for an address.
2473	*/
2474	typedef struct BS3PAGINGINFO4ADDR
2475	{
2476	/** The depth of the system's paging mode.
2477	* This is always 2 for legacy, 3 for PAE and 4 for long mode. */
2478	uint8_t cEntries;
2479	/** The size of the page structures (the entires). */
2480	uint8_t cbEntry;
2481	/** Flags defined for future fun, currently zero. */
2482	uint16_t fFlags;
2483	/** Union display different view on the entry pointers. */
2484	union
2485	{
2486	/** Pointer to the page structure entries, starting with the PTE as 0.
2487	* If large pages are involved, the first entry will be NULL (first two if 1GB
2488	* page). Same if the address is invalid on a higher level. */
2489	uint8_t BS3_FAR *apbEntries[4];
2490	/** Alternative view for legacy mode. */
2491	struct
2492	{
2493	X86PTE BS3_FAR *pPte;
2494	X86PDE BS3_FAR *pPde;
2495	void *pvUnused2;
2496	void *pvUnused3;
2497	} Legacy;
2498	/** Alternative view for PAE and Long mode. */
2499	struct
2500	{
2501	X86PTEPAE BS3_FAR *pPte;
2502	X86PDEPAE BS3_FAR *pPde;
2503	X86PDPE BS3_FAR *pPdpe;
2504	X86PML4E BS3_FAR *pPml4e;
2505	} Pae;
2506	} u;
2507	} BS3PAGINGINFO4ADDR;
2508	/** Pointer to paging information for and address. */
2509	typedef BS3PAGINGINFO4ADDR BS3_FAR *PBS3PAGINGINFO4ADDR;
2510
2511	/**
2512	* Queries paging information about the given virtual address.
2513	*
2514	* @returns VBox status code.
2515	* @param uFlat The flat address to query information about.
2516	* @param pPgInfo Where to return the information.
2517	*/
2518	BS3_CMN_PROTO_STUB(int, Bs3PagingQueryAddressInfo,(uint64_t uFlat, PBS3PAGINGINFO4ADDR pPgInfo));
2519
2520
2521	/** The physical / flat address of the buffer backing the canonical traps.
2522	* This buffer is spread equally on each side of the 64-bit non-canonical
2523	* address divide. Non-64-bit code can use this to setup trick shots and
2524	* inspect their results. */
2525	extern uint32_t g_uBs3PagingCanonicalTrapsAddr;
2526	/** The size of the buffer at g_uPagingCanonicalTraps (both sides). */
2527	extern uint16_t g_cbBs3PagingCanonicalTraps;
2528	/** The size of one trap buffer (low or high).
2529	* This is g_cbBs3PagingCanonicalTraps divided by two. */
2530	extern uint16_t g_cbBs3PagingOneCanonicalTrap;
2531
2532	/**
2533	* Sets up the 64-bit canonical address space trap buffers, if neceessary.
2534	*
2535	* @returns Pointer to the buffers (i.e. the first page of the low one) on
2536	* success. NULL on failure.
2537	*/
2538	BS3_CMN_PROTO_STUB(void BS3_FAR *, Bs3PagingSetupCanonicalTraps,(void));
2539
2540
2541	/**
2542	* Call 16-bit prot mode function from v8086 mode.
2543	*
2544	* This switches from v8086 mode to 16-bit protected mode (code) and executed
2545	* @a fpfnCall with @a cbParams bytes of parameters pushed on the stack.
2546	* Afterwards it switches back to v8086 mode and returns a 16-bit status code.
2547	*
2548	* @returns 16-bit status code if the function returned anything.
2549	* @param fpfnCall Far real mode pointer to the function to call.
2550	* @param cbParams The size of the parameter list, in bytes.
2551	* @param ... The parameters.
2552	* @sa Bs3SwitchTo32BitAndCallC
2553	*/
2554	BS3_CMN_PROTO_STUB(int, Bs3SwitchFromV86To16BitAndCallC,(FPFNBS3FAR fpfnCall, unsigned cbParams, ...));
2555
2556
2557	/**
2558	* BS3 integer register.
2559	*/
2560	typedef union BS3REG
2561	{
2562	/** 8-bit unsigned integer. */
2563	uint8_t u8;
2564	/** 16-bit unsigned integer. */
2565	uint16_t u16;
2566	/** 32-bit unsigned integer. */
2567	uint32_t u32;
2568	/** 64-bit unsigned integer. */
2569	uint64_t u64;
2570	/** Full unsigned integer. */
2571	uint64_t u;
2572	/** High/low byte view. */
2573	struct
2574	{
2575	uint8_t bLo;
2576	uint8_t bHi;
2577	} b;
2578	/** 8-bit view. */
2579	uint8_t au8[8];
2580	/** 16-bit view. */
2581	uint16_t au16[4];
2582	/** 32-bit view. */
2583	uint32_t au32[2];
2584	/** Unsigned integer, depending on compiler context.
2585	* This generally follows ARCH_BITS. */
2586	RTCCUINTREG uCcReg;
2587	/** Extended unsigned integer, depending on compiler context.
2588	* This is 32-bit in 16-bit and 32-bit compiler contexts, and 64-bit in
2589	* 64-bit. */
2590	RTCCUINTXREG uCcXReg;
2591	} BS3REG;
2592	/** Pointer to an integer register. */
2593	typedef BS3REG BS3_FAR *PBS3REG;
2594	/** Pointer to a const integer register. */
2595	typedef BS3REG const BS3_FAR *PCBS3REG;
2596
2597	/**
2598	* Register context (without FPU).
2599	*/
2600	typedef struct BS3REGCTX
2601	{
2602	BS3REG rax; /*< 0x00 /
2603	BS3REG rcx; /*< 0x08 /
2604	BS3REG rdx; /*< 0x10 /
2605	BS3REG rbx; /*< 0x18 /
2606	BS3REG rsp; /*< 0x20 /
2607	BS3REG rbp; /*< 0x28 /
2608	BS3REG rsi; /*< 0x30 /
2609	BS3REG rdi; /*< 0x38 /
2610	BS3REG r8; /*< 0x40 /
2611	BS3REG r9; /*< 0x48 /
2612	BS3REG r10; /*< 0x50 /
2613	BS3REG r11; /*< 0x58 /
2614	BS3REG r12; /*< 0x60 /
2615	BS3REG r13; /*< 0x68 /
2616	BS3REG r14; /*< 0x70 /
2617	BS3REG r15; /*< 0x78 /
2618	BS3REG rflags; /*< 0x80 /
2619	BS3REG rip; /*< 0x88 /
2620	uint16_t cs; /*< 0x90 /
2621	uint16_t ds; /*< 0x92 /
2622	uint16_t es; /*< 0x94 /
2623	uint16_t fs; /*< 0x96 /
2624	uint16_t gs; /*< 0x98 /
2625	uint16_t ss; /*< 0x9a /
2626	uint16_t tr; /*< 0x9c /
2627	uint16_t ldtr; /*< 0x9e /
2628	uint8_t bMode; /*< 0xa0: BS3_MODE_XXX. /
2629	uint8_t bCpl; /*< 0xa1: 0-3, 0 is used for real mode. /
2630	uint8_t fbFlags; /*< 0xa2: BS3REG_CTX_F_XXX /
2631	uint8_t abPadding[5]; /*< 0xa3 /
2632	BS3REG cr0; /*< 0xa8 /
2633	BS3REG cr2; /*< 0xb0 /
2634	BS3REG cr3; /*< 0xb8 /
2635	BS3REG cr4; /*< 0xc0 /
2636	uint64_t uUnused; /*< 0xc8 /
2637	} BS3REGCTX;
2638	AssertCompileSize(BS3REGCTX, 0xd0);
2639	/** Pointer to a register context. */
2640	typedef BS3REGCTX BS3_FAR *PBS3REGCTX;
2641	/** Pointer to a const register context. */
2642	typedef BS3REGCTX const BS3_FAR *PCBS3REGCTX;
2643
2644	/** @name BS3REG_CTX_F_XXX - BS3REGCTX::fbFlags masks.
2645	* @{ */
2646	/** The CR0 is MSW (only low 16-bit). */
2647	#define BS3REG_CTX_F_NO_CR0_IS_MSW UINT8_C(0x01)
2648	/** No CR2 and CR3 values. Not in CPL 0 or CPU too old for CR2 & CR3. */
2649	#define BS3REG_CTX_F_NO_CR2_CR3 UINT8_C(0x02)
2650	/** No CR4 value. The CPU is too old for CR4. */
2651	#define BS3REG_CTX_F_NO_CR4 UINT8_C(0x04)
2652	/** No TR and LDTR values. Context gathered in real mode or v8086 mode. */
2653	#define BS3REG_CTX_F_NO_TR_LDTR UINT8_C(0x08)
2654	/** The context doesn't have valid values for AMD64 GPR extensions. */
2655	#define BS3REG_CTX_F_NO_AMD64 UINT8_C(0x10)
2656	/** @} */
2657
2658	/**
2659	* Saves the current register context.
2660	*
2661	* @param pRegCtx Where to store the register context.
2662	*/
2663	BS3_CMN_PROTO_NOSB(void, Bs3RegCtxSave,(PBS3REGCTX pRegCtx));
2664
2665	/**
2666	* Switch to the specified CPU bitcount, reserve additional stack and save the
2667	* CPU context.
2668	*
2669	* This is for writing more flexible test drivers that can test more than the
2670	* CPU bitcount (16-bit, 32-bit, 64-bit, and virtual 8086) of the driver itself.
2671	* For instance a 32-bit driver can do V86 and 16-bit testing, thus saving space
2672	* by avoiding duplicate 16-bit driver code.
2673	*
2674	* @param pRegCtx Where to store the register context.
2675	* @param bBitMode Bit mode to switch to, BS3_MODE_CODE_XXX. Only
2676	* BS3_MODE_CODE_MASK is used, other bits are ignored
2677	* to make it possible to pass a full mode value.
2678	* @param cbExtraStack Number of bytes of additional stack to allocate.
2679	*/
2680	BS3_CMN_PROTO_FARSTUB(8, void, Bs3RegCtxSaveEx,(PBS3REGCTX pRegCtx, uint8_t bBitMode, uint16_t cbExtraStack));
2681
2682	/**
2683	* This is Bs3RegCtxSaveEx with automatic Bs3RegCtxConvertV86ToRm thrown in.
2684	*
2685	* This is for simplifying writing 32-bit test drivers that covers real-mode as
2686	* well as virtual 8086, 16-bit, 32-bit, and 64-bit modes.
2687	*
2688	* @param pRegCtx Where to store the register context.
2689	* @param bMode The mode to get a context for. If this isn't
2690	* BS3_MODE_RM, the BS3_MODE_SYS_MASK has to match the
2691	* one of the current mode.
2692	* @param cbExtraStack Number of bytes of additional stack to allocate.
2693	*/
2694	BS3_CMN_PROTO_STUB(void, Bs3RegCtxSaveForMode,(PBS3REGCTX pRegCtx, uint8_t bMode, uint16_t cbExtraStack));
2695
2696	/**
2697	* Transforms a register context to a different ring.
2698	*
2699	* @param pRegCtx The register context.
2700	* @param bRing The target ring (0..3).
2701	*
2702	* @note Do _NOT_ call this for creating real mode or v8086 contexts, because
2703	* it will always output a protected mode context!
2704	*/
2705	BS3_CMN_PROTO_STUB(void, Bs3RegCtxConvertToRingX,(PBS3REGCTX pRegCtx, uint8_t bRing));
2706
2707	/**
2708	* Transforms a V8086 register context to a real mode one.
2709	*
2710	* @param pRegCtx The register context.
2711	*
2712	* @note Will assert if called on a non-V8086 context.
2713	*/
2714	BS3_CMN_PROTO_STUB(void, Bs3RegCtxConvertV86ToRm,(PBS3REGCTX pRegCtx));
2715
2716	/**
2717	* Restores a register context.
2718	*
2719	* @param pRegCtx The register context to be restored and resumed.
2720	* @param fFlags BS3REGCTXRESTORE_F_XXX.
2721	*
2722	* @remarks Will switch to ring-0.
2723	* @remarks Does not return.
2724	*/
2725	BS3_CMN_PROTO_NOSB(DECL_NO_RETURN(void), Bs3RegCtxRestore,(PCBS3REGCTX pRegCtx, uint16_t fFlags));
2726	#if !defined(BS3_KIT_WITH_NO_RETURN) && defined(__WATCOMC__)
2727	# pragma aux Bs3RegCtxRestore_c16 "_Bs3RegCtxRestore_aborts_c16" __aborts
2728	# pragma aux Bs3RegCtxRestore_f16 "_Bs3RegCtxRestore_aborts_f16" __aborts
2729	# pragma aux Bs3RegCtxRestore_c32 "_Bs3RegCtxRestore_aborts_c32" __aborts
2730	#endif
2731
2732	/** @name Flags for Bs3RegCtxRestore
2733	* @{ */
2734	/** Skip restoring the CRx registers. */
2735	#define BS3REGCTXRESTORE_F_SKIP_CRX UINT16_C(0x0001)
2736	/** Sets g_fBs3TrapNoV86Assist. */
2737	#define BS3REGCTXRESTORE_F_NO_V86_ASSIST UINT16_C(0x0002)
2738	/** @} */
2739
2740	/**
2741	* Prints the register context.
2742	*
2743	* @param pRegCtx The register context to be printed.
2744	*/
2745	BS3_CMN_PROTO_STUB(void, Bs3RegCtxPrint,(PCBS3REGCTX pRegCtx));
2746
2747	/**
2748	* Sets a GPR and segment register to point at the same location as @a uFlat.
2749	*
2750	* @param pRegCtx The register context.
2751	* @param pGpr The general purpose register to set (points within
2752	* @a pRegCtx).
2753	* @param pSel The selector register (points within @a pRegCtx).
2754	* @param uFlat Flat location address.
2755	*/
2756	BS3_CMN_PROTO_STUB(void, Bs3RegCtxSetGrpSegFromFlat,(PBS3REGCTX pRegCtx, PBS3REG pGpr, PRTSEL pSel, RTCCUINTXREG uFlat));
2757
2758	/**
2759	* Sets a GPR and segment register to point at the same location as @a ovPtr.
2760	*
2761	* @param pRegCtx The register context.
2762	* @param pGpr The general purpose register to set (points within
2763	* @a pRegCtx).
2764	* @param pSel The selector register (points within @a pRegCtx).
2765	* @param pvPtr Current context pointer.
2766	*/
2767	BS3_CMN_PROTO_STUB(void, Bs3RegCtxSetGrpSegFromCurPtr,(PBS3REGCTX pRegCtx, PBS3REG pGpr, PRTSEL pSel, void BS3_FAR *pvPtr));
2768
2769	/**
2770	* Sets a GPR and DS to point at the same location as @a pvPtr.
2771	*
2772	* @param pRegCtx The register context.
2773	* @param pGpr The general purpose register to set (points within
2774	* @a pRegCtx).
2775	* @param pvPtr Current context pointer.
2776	*/
2777	BS3_CMN_PROTO_STUB(void, Bs3RegCtxSetGrpDsFromCurPtr,(PBS3REGCTX pRegCtx, PBS3REG pGpr, void BS3_FAR *pvPtr));
2778
2779	/**
2780	* Sets CS:RIP to point at the same piece of code as @a uFlatCode.
2781	*
2782	* @param pRegCtx The register context.
2783	* @param uFlatCode Flat code pointer
2784	* @sa Bs3RegCtxSetRipCsFromLnkPtr, Bs3RegCtxSetRipCsFromCurPtr
2785	*/
2786	BS3_CMN_PROTO_STUB(void, Bs3RegCtxSetRipCsFromFlat,(PBS3REGCTX pRegCtx, RTCCUINTXREG uFlatCode));
2787
2788	/**
2789	* Sets CS:RIP to point at the same piece of code as @a pfnCode.
2790	*
2791	* The 16-bit edition of this function expects a far 16:16 address as written by
2792	* the linker (i.e. real mode).
2793	*
2794	* @param pRegCtx The register context.
2795	* @param pfnCode Pointer to the code. In 32-bit and 64-bit mode this is a
2796	* flat address, while in 16-bit it's a far 16:16 address
2797	* as fixed up by the linker (real mode selector). This
2798	* address is converted to match the mode of the context.
2799	* @sa Bs3RegCtxSetRipCsFromCurPtr, Bs3RegCtxSetRipCsFromFlat
2800	*/
2801	BS3_CMN_PROTO_STUB(void, Bs3RegCtxSetRipCsFromLnkPtr,(PBS3REGCTX pRegCtx, FPFNBS3FAR pfnCode));
2802
2803	/**
2804	* Sets CS:RIP to point at the same piece of code as @a pfnCode.
2805	*
2806	* @param pRegCtx The register context.
2807	* @param pfnCode Pointer to the code. Current mode pointer.
2808	* @sa Bs3RegCtxSetRipCsFromLnkPtr, Bs3RegCtxSetRipCsFromFlat
2809	*/
2810	BS3_CMN_PROTO_STUB(void, Bs3RegCtxSetRipCsFromCurPtr,(PBS3REGCTX pRegCtx, FPFNBS3FAR pfnCode));
2811
2812	/**
2813	* Sets a GPR by number.
2814	*
2815	* @return true if @a iGpr is valid, false if not.
2816	* @param pRegCtx The register context.
2817	* @param iGpr The GPR number.
2818	* @param uValue The new value.
2819	* @param cbValue The size of the value: 1, 2, 4 or 8.
2820	*/
2821	BS3_CMN_PROTO_STUB(bool, Bs3RegCtxSetGpr,(PBS3REGCTX pRegCtx, uint8_t iGpr, uint64_t uValue, uint8_t cb));
2822
2823	/**
2824	* Gets the stack pointer as a current context pointer.
2825	*
2826	* @return Pointer to the top of the stack. NULL on failure.
2827	* @param pRegCtx The register context.
2828	*/
2829	BS3_CMN_PROTO_STUB(void BS3_FAR *, Bs3RegCtxGetRspSsAsCurPtr,(PBS3REGCTX pRegCtx));
2830
2831
2832	/**
2833	* The method to be used to save and restore the extended context.
2834	*/
2835	typedef enum BS3EXTCTXMETHOD
2836	{
2837	BS3EXTCTXMETHOD_INVALID = 0,
2838	BS3EXTCTXMETHOD_ANCIENT, /*< Ancient fnsave/frstor format. /
2839	BS3EXTCTXMETHOD_FXSAVE, /*< fxsave/fxrstor format. /
2840	BS3EXTCTXMETHOD_XSAVE, /*< xsave/xrstor format. /
2841	BS3EXTCTXMETHOD_END,
2842	} BS3EXTCTXMETHOD;
2843
2844
2845	/**
2846	* Extended CPU context (FPU, SSE, AVX, ++).
2847	*
2848	* @remarks Also in bs3kit.inc
2849	*/
2850	typedef struct BS3EXTCTX
2851	{
2852	/** Dummy/magic value. */
2853	uint16_t u16Magic;
2854	/** The size of the structure. */
2855	uint16_t cb;
2856	/** The method used to save and restore the context (BS3EXTCTXMETHOD). */
2857	uint8_t enmMethod;
2858	uint8_t abPadding0[3];
2859	/** Nominal XSAVE_C_XXX. */
2860	uint64_t fXcr0Nominal;
2861	/** The saved XCR0 mask (restored after xrstor). */
2862	uint64_t fXcr0Saved;
2863
2864	/** Explicit alignment padding. */
2865	uint8_t abPadding[64 - 2 - 2 - 1 - 3 - 8 - 8];
2866
2867	/** The context, variable size (see above).
2868	* This must be aligned on a 64 byte boundrary. */
2869	union
2870	{
2871	/** fnsave/frstor. */
2872	X86FPUSTATE Ancient;
2873	/** fxsave/fxrstor */
2874	X86FXSTATE x87;
2875	/** xsave/xrstor */
2876	X86XSAVEAREA x;
2877	/** Byte array view. */
2878	uint8_t ab[sizeof(X86XSAVEAREA)];
2879	} Ctx;
2880	} BS3EXTCTX;
2881	AssertCompileMemberAlignment(BS3EXTCTX, Ctx, 64);
2882	/** Pointer to an extended CPU context. */
2883	typedef BS3EXTCTX BS3_FAR *PBS3EXTCTX;
2884	/** Pointer to a const extended CPU context. */
2885	typedef BS3EXTCTX const BS3_FAR *PCBS3EXTCTX;
2886
2887	/** Magic value for BS3EXTCTX. */
2888	#define BS3EXTCTX_MAGIC UINT16_C(0x1980)
2889
2890	/**
2891	* Allocates and initializes the extended CPU context structure.
2892	*
2893	* @returns The new extended CPU context structure.
2894	* @param enmKind The kind of allocation to make.
2895	*/
2896	BS3_CMN_PROTO_STUB(PBS3EXTCTX, Bs3ExtCtxAlloc,(BS3MEMKIND enmKind));
2897
2898	/**
2899	* Frees an extended CPU context structure.
2900	*
2901	* @param pExtCtx The extended CPU context (returned by
2902	* Bs3ExtCtxAlloc).
2903	*/
2904	BS3_CMN_PROTO_STUB(void, Bs3ExtCtxFree,(PBS3EXTCTX pExtCtx));
2905
2906	/**
2907	* Get the size required for a BS3EXTCTX structure.
2908	*
2909	* @returns size in bytes of the whole structure.
2910	* @param pfFlags Where to return flags for Bs3ExtCtxInit.
2911	* @note Use Bs3ExtCtxAlloc when possible.
2912	*/
2913	BS3_CMN_PROTO_STUB(uint16_t, Bs3ExtCtxGetSize,(uint64_t *pfFlags));
2914
2915	/**
2916	* Initializes the extended CPU context structure.
2917	* @returns pExtCtx
2918	* @param pExtCtx The extended CPU context.
2919	* @param cbExtCtx The size of the @a pExtCtx allocation.
2920	* @param fFlags XSAVE_C_XXX flags.
2921	*/
2922	BS3_CMN_PROTO_STUB(PBS3EXTCTX, Bs3ExtCtxInit,(PBS3EXTCTX pExtCtx, uint16_t cbExtCtx, uint64_t fFlags));
2923
2924	/**
2925	* Saves the extended CPU state to the given structure.
2926	*
2927	* @param pExtCtx The extended CPU context.
2928	* @remarks All GPRs preserved.
2929	*/
2930	BS3_CMN_PROTO_FARSTUB(4, void, Bs3ExtCtxSave,(PBS3EXTCTX pExtCtx));
2931
2932	/**
2933	* Saves the extended CPU state to the given structure, when in long mode this
2934	* is done from 64-bit mode to capture YMM8 thru YMM15.
2935	*
2936	* This is for testing 64-bit code from a 32-bit test driver.
2937	*
2938	* @param pExtCtx The extended CPU context.
2939	* @note Only safe to call from ring-0 at present.
2940	* @remarks All GPRs preserved.
2941	* @sa Bs3ExtCtxRestoreEx
2942	*/
2943	BS3_CMN_PROTO_FARSTUB(4, void, Bs3ExtCtxSaveEx,(PBS3EXTCTX pExtCtx));
2944
2945	/**
2946	* Restores the extended CPU state from the given structure.
2947	*
2948	* @param pExtCtx The extended CPU context.
2949	* @remarks All GPRs preserved.
2950	*/
2951	BS3_CMN_PROTO_FARSTUB(4, void, Bs3ExtCtxRestore,(PCBS3EXTCTX pExtCtx));
2952
2953	/**
2954	* Restores the extended CPU state from the given structure and in long mode
2955	* switch to 64-bit mode to do this so YMM8-YMM15 are also loaded.
2956	*
2957	* This is for testing 64-bit code from a 32-bit test driver.
2958	*
2959	* @param pExtCtx The extended CPU context.
2960	* @note Only safe to call from ring-0 at present.
2961	* @remarks All GPRs preserved.
2962	* @sa Bs3ExtCtxSaveEx
2963	*/
2964	BS3_CMN_PROTO_FARSTUB(4, void, Bs3ExtCtxRestoreEx,(PCBS3EXTCTX pExtCtx));
2965
2966	/**
2967	* Copies the state from one context to another.
2968	*
2969	* @returns pDst
2970	* @param pDst The destination extended CPU context.
2971	* @param pSrc The source extended CPU context.
2972	*/
2973	BS3_CMN_PROTO_STUB(PBS3EXTCTX, Bs3ExtCtxCopy,(PBS3EXTCTX pDst, PCBS3EXTCTX pSrc));
2974
2975	/**
2976	* Gets the FCW register value from @a pExtCtx.
2977	*
2978	* @returns FCW value.
2979	* @param pExtCtx The extended CPU context.
2980	*/
2981	BS3_CMN_PROTO_STUB(uint16_t, Bs3ExtCtxGetFcw,(PCBS3EXTCTX pExtCtx));
2982
2983	/**
2984	* Sets the FCW register value in @a pExtCtx.
2985	*
2986	* @param pExtCtx The extended CPU context.
2987	* @param uValue The new FCW value.
2988	*/
2989	BS3_CMN_PROTO_STUB(void, Bs3ExtCtxSetFcw,(PBS3EXTCTX pExtCtx, uint16_t uValue));
2990
2991	/**
2992	* Gets the FSW register value from @a pExtCtx.
2993	*
2994	* @returns FSW value.
2995	* @param pExtCtx The extended CPU context.
2996	*/
2997	BS3_CMN_PROTO_STUB(uint16_t, Bs3ExtCtxGetFsw,(PCBS3EXTCTX pExtCtx));
2998
2999	/**
3000	* Sets the FSW register value in @a pExtCtx.
3001	*
3002	* @param pExtCtx The extended CPU context.
3003	* @param uValue The new FSW value.
3004	*/
3005	BS3_CMN_PROTO_STUB(void, Bs3ExtCtxSetFsw,(PBS3EXTCTX pExtCtx, uint16_t uValue));
3006
3007	/**
3008	* Gets the abridged FTW register value from @a pExtCtx.
3009	*
3010	* @returns FTW value.
3011	* @param pExtCtx The extended CPU context.
3012	*/
3013	BS3_CMN_PROTO_STUB(uint16_t, Bs3ExtCtxGetAbridgedFtw,(PCBS3EXTCTX pExtCtx));
3014
3015	/**
3016	* Sets the abridged FTW register value in @a pExtCtx.
3017	*
3018	* Currently this requires that the state stores teh abridged FTW, no conversion
3019	* to the two-bit variant will be attempted.
3020	*
3021	* @returns true if set successfully, false if not.
3022	* @param pExtCtx The extended CPU context.
3023	* @param uValue The new FTW value.
3024	*/
3025	BS3_CMN_PROTO_STUB(bool, Bs3ExtCtxSetAbridgedFtw,(PBS3EXTCTX pExtCtx, uint16_t uValue));
3026
3027	/**
3028	* Gets the MXCSR register value from @a pExtCtx.
3029	*
3030	* @returns MXCSR value, 0 if not part of context.
3031	* @param pExtCtx The extended CPU context.
3032	*/
3033	BS3_CMN_PROTO_STUB(uint32_t, Bs3ExtCtxGetMxCsr,(PCBS3EXTCTX pExtCtx));
3034
3035	/**
3036	* Sets the MXCSR register value in @a pExtCtx.
3037	*
3038	* @returns true if set, false if not supported by the format.
3039	* @param pExtCtx The extended CPU context.
3040	* @param uValue The new MXCSR value.
3041	*/
3042	BS3_CMN_PROTO_STUB(bool, Bs3ExtCtxSetMxCsr,(PBS3EXTCTX pExtCtx, uint32_t uValue));
3043
3044	/**
3045	* Gets the MXCSR MASK value from @a pExtCtx.
3046	*
3047	* @returns MXCSR MASK value, 0 if not part of context.
3048	* @param pExtCtx The extended CPU context.
3049	*/
3050	BS3_CMN_PROTO_STUB(uint32_t, Bs3ExtCtxGetMxCsrMask,(PCBS3EXTCTX pExtCtx));
3051
3052	/**
3053	* Sets the MXCSR MASK value in @a pExtCtx.
3054	*
3055	* @returns true if set, false if not supported by the format.
3056	* @param pExtCtx The extended CPU context.
3057	* @param uValue The new MXCSR MASK value.
3058	*/
3059	BS3_CMN_PROTO_STUB(bool, Bs3ExtCtxSetMxCsrMask,(PBS3EXTCTX pExtCtx, uint32_t uValue));
3060
3061	/**
3062	* Gets the value of MM register number @a iReg from @a pExtCtx.
3063	*
3064	* @returns The MM register value.
3065	* @param pExtCtx The extended CPU context.
3066	* @param iReg The register to get (0 thru 7).
3067	*/
3068	BS3_CMN_PROTO_STUB(uint64_t, Bs3ExtCtxGetMm,(PCBS3EXTCTX pExtCtx, uint8_t iReg));
3069
3070	/** What to do about the 16-bit above the MM QWORD. */
3071	typedef enum BS3EXTCTXTOPMM
3072	{
3073	/** Invalid zero value. */
3074	BS3EXTCTXTOPMM_INVALID = 0,
3075	/** Set to 0FFFFh like real CPUs typically does when updating an MM register. */
3076	BS3EXTCTXTOPMM_SET,
3077	/** Set to zero. */
3078	BS3EXTCTXTOPMM_ZERO,
3079	/** Don't change the value, leaving it as-is. */
3080	BS3EXTCTXTOPMM_AS_IS,
3081	/** End of valid values. */
3082	BS3EXTCTXTOPMM_END
3083	} BS3EXTCTXTOPMM;
3084
3085	/**
3086	* Sets the value of YMM register number @a iReg in @a pExtCtx to @a pValue.
3087	*
3088	* @returns True if set, false if not.
3089	* @param pExtCtx The extended CPU context.
3090	* @param iReg The register to set.
3091	* @param uValue The new register value.
3092	* @param enmTop What to do about the 16-bit value above the MM
3093	* QWord.
3094	*/
3095	BS3_CMN_PROTO_STUB(bool, Bs3ExtCtxSetMm,(PBS3EXTCTX pExtCtx, uint8_t iReg, uint64_t uValue, BS3EXTCTXTOPMM enmTop));
3096
3097	/**
3098	* Gets the value of XMM register number @a iReg from @a pExtCtx.
3099	*
3100	* @returns pValue
3101	* @param pExtCtx The extended CPU context.
3102	* @param iReg The register to get.
3103	* @param pValue Where to return the value. Zeroed if the state
3104	* doesn't support SSE or if @a iReg is invalid.
3105	*/
3106	BS3_CMN_PROTO_STUB(PRTUINT128U, Bs3ExtCtxGetXmm,(PCBS3EXTCTX pExtCtx, uint8_t iReg, PRTUINT128U pValue));
3107
3108	/**
3109	* Sets the value of XMM register number @a iReg in @a pExtCtx to @a pValue.
3110	*
3111	* @returns True if set, false if not set (not supported by state format or
3112	* invalid iReg).
3113	* @param pExtCtx The extended CPU context.
3114	* @param iReg The register to set.
3115	* @param pValue The new register value.
3116	*/
3117	BS3_CMN_PROTO_STUB(bool, Bs3ExtCtxSetXmm,(PBS3EXTCTX pExtCtx, uint8_t iReg, PCRTUINT128U pValue));
3118
3119	/**
3120	* Gets the value of YMM register number @a iReg from @a pExtCtx.
3121	*
3122	* @returns pValue
3123	* @param pExtCtx The extended CPU context.
3124	* @param iReg The register to get.
3125	* @param pValue Where to return the value. Parts not in the
3126	* extended state are zeroed. For absent or invalid
3127	* @a iReg values this is set to zero.
3128	*/
3129	BS3_CMN_PROTO_STUB(PRTUINT256U, Bs3ExtCtxGetYmm,(PCBS3EXTCTX pExtCtx, uint8_t iReg, PRTUINT256U pValue));
3130
3131	/**
3132	* Sets the value of YMM register number @a iReg in @a pExtCtx to @a pValue.
3133	*
3134	* @returns true if set (even if only partially). False if not set (not
3135	* supported by state format, unsupported/invalid iReg).
3136	* @param pExtCtx The extended CPU context.
3137	* @param iReg The register to set.
3138	* @param pValue The new register value.
3139	* @param cbValue Number of bytes to take from @a pValue, either 16 or
3140	* 32. If 16, the high part will be zeroed when present
3141	* in the state.
3142	*/
3143	BS3_CMN_PROTO_STUB(bool, Bs3ExtCtxSetYmm,(PBS3EXTCTX pExtCtx, uint8_t iReg, PCRTUINT256U pValue, uint8_t cbValue));
3144
3145
3146	/** @name Debug register accessors for V8086 mode (works everwhere).
3147	* @{ */
3148	BS3_CMN_PROTO_NOSB(RTCCUINTXREG, Bs3RegGetDr0,(void));
3149	BS3_CMN_PROTO_NOSB(RTCCUINTXREG, Bs3RegGetDr1,(void));
3150	BS3_CMN_PROTO_NOSB(RTCCUINTXREG, Bs3RegGetDr2,(void));
3151	BS3_CMN_PROTO_NOSB(RTCCUINTXREG, Bs3RegGetDr3,(void));
3152	BS3_CMN_PROTO_NOSB(RTCCUINTXREG, Bs3RegGetDr6,(void));
3153	BS3_CMN_PROTO_NOSB(RTCCUINTXREG, Bs3RegGetDr7,(void));
3154
3155	BS3_CMN_PROTO_NOSB(void, Bs3RegSetDr0,(RTCCUINTXREG uValue));
3156	BS3_CMN_PROTO_NOSB(void, Bs3RegSetDr1,(RTCCUINTXREG uValue));
3157	BS3_CMN_PROTO_NOSB(void, Bs3RegSetDr2,(RTCCUINTXREG uValue));
3158	BS3_CMN_PROTO_NOSB(void, Bs3RegSetDr3,(RTCCUINTXREG uValue));
3159	BS3_CMN_PROTO_NOSB(void, Bs3RegSetDr6,(RTCCUINTXREG uValue));
3160	BS3_CMN_PROTO_NOSB(void, Bs3RegSetDr7,(RTCCUINTXREG uValue));
3161
3162	BS3_CMN_PROTO_NOSB(RTCCUINTXREG, Bs3RegGetDrX,(uint8_t iReg));
3163	BS3_CMN_PROTO_NOSB(void, Bs3RegSetDrX,(uint8_t iReg, RTCCUINTXREG uValue));
3164	/** @} */
3165
3166
3167	/** @name Control register accessors for V8086 mode (works everwhere).
3168	* @{ */
3169	BS3_CMN_PROTO_NOSB(RTCCUINTXREG, Bs3RegGetCr0,(void));
3170	BS3_CMN_PROTO_NOSB(RTCCUINTXREG, Bs3RegGetCr2,(void));
3171	BS3_CMN_PROTO_NOSB(RTCCUINTXREG, Bs3RegGetCr3,(void));
3172	BS3_CMN_PROTO_NOSB(RTCCUINTXREG, Bs3RegGetCr4,(void));
3173	BS3_CMN_PROTO_NOSB(uint16_t, Bs3RegGetTr,(void));
3174	BS3_CMN_PROTO_NOSB(uint16_t, Bs3RegGetLdtr,(void));
3175	BS3_CMN_PROTO_NOSB(uint64_t, Bs3RegGetXcr0,(void));
3176
3177	BS3_CMN_PROTO_NOSB(void, Bs3RegSetCr0,(RTCCUINTXREG uValue));
3178	BS3_CMN_PROTO_NOSB(void, Bs3RegSetCr2,(RTCCUINTXREG uValue));
3179	BS3_CMN_PROTO_NOSB(void, Bs3RegSetCr3,(RTCCUINTXREG uValue));
3180	BS3_CMN_PROTO_NOSB(void, Bs3RegSetCr4,(RTCCUINTXREG uValue));
3181	BS3_CMN_PROTO_NOSB(void, Bs3RegSetTr,(uint16_t uValue));
3182	BS3_CMN_PROTO_NOSB(void, Bs3RegSetLdtr,(uint16_t uValue));
3183	BS3_CMN_PROTO_NOSB(void, Bs3RegSetXcr0,(uint64_t uValue));
3184	/** @} */
3185
3186
3187	/**
3188	* Trap frame.
3189	*/
3190	typedef struct BS3TRAPFRAME
3191	{
3192	/** 0x00: Exception/interrupt number. */
3193	uint8_t bXcpt;
3194	/** 0x01: The size of the IRET frame. */
3195	uint8_t cbIretFrame;
3196	/** 0x02: The handler CS. */
3197	uint16_t uHandlerCs;
3198	/** 0x04: The handler SS. */
3199	uint16_t uHandlerSs;
3200	/** 0x06: Explicit alignment. */
3201	uint16_t usAlignment;
3202	/** 0x08: The handler RSP (pointer to the iret frame, skipping ErrCd). */
3203	uint64_t uHandlerRsp;
3204	/** 0x10: The handler RFLAGS value. */
3205	uint64_t fHandlerRfl;
3206	/** 0x18: The error code (if applicable). */
3207	uint64_t uErrCd;
3208	/** 0x20: The register context. */
3209	BS3REGCTX Ctx;
3210	} BS3TRAPFRAME;
3211	AssertCompileSize(BS3TRAPFRAME, 0x20 + 0xd0);
3212	/** Pointer to a trap frame. */
3213	typedef BS3TRAPFRAME BS3_FAR *PBS3TRAPFRAME;
3214	/** Pointer to a const trap frame. */
3215	typedef BS3TRAPFRAME const BS3_FAR *PCBS3TRAPFRAME;
3216
3217
3218	/**
3219	* Re-initializes the trap handling for the current mode.
3220	*
3221	* Useful after a test that messes with the IDT/IVT.
3222	*
3223	* @sa Bs3TrapInit
3224	*/
3225	BS3_CMN_PROTO_STUB(void, Bs3TrapReInit,(void));
3226
3227	/**
3228	* Initializes real mode and v8086 trap handling.
3229	*
3230	* @remarks Does not install RM/V86 trap handling, just initializes the
3231	* structures.
3232	*/
3233	BS3_CMN_PROTO_STUB(void, Bs3TrapRmV86Init,(void));
3234
3235	/**
3236	* Initializes real mode and v8086 trap handling, extended version.
3237	*
3238	* @param f386Plus Set if the CPU is 80386 or later and
3239	* extended registers should be saved. Once initialized
3240	* with this parameter set to @a true, the effect cannot be
3241	* reversed.
3242	*
3243	* @remarks Does not install RM/V86 trap handling, just initializes the
3244	* structures.
3245	*/
3246	BS3_CMN_PROTO_STUB(void, Bs3TrapRmV86InitEx,(bool f386Plus));
3247
3248	/**
3249	* Initializes 16-bit (protected mode) trap handling.
3250	*
3251	* @remarks Does not install 16-bit trap handling, just initializes the
3252	* structures.
3253	*/
3254	BS3_CMN_PROTO_STUB(void, Bs3Trap16Init,(void));
3255
3256	/**
3257	* Initializes 16-bit (protected mode) trap handling, extended version.
3258	*
3259	* @param f386Plus Set if the CPU is 80386 or later and
3260	* extended registers should be saved. Once initialized
3261	* with this parameter set to @a true, the effect cannot be
3262	* reversed.
3263	*
3264	* @remarks Does not install 16-bit trap handling, just initializes the
3265	* structures.
3266	*/
3267	BS3_CMN_PROTO_STUB(void, Bs3Trap16InitEx,(bool f386Plus));
3268
3269	/**
3270	* Initializes 32-bit trap handling.
3271	*
3272	* @remarks Does not install 32-bit trap handling, just initializes the
3273	* structures.
3274	*/
3275	BS3_CMN_PROTO_STUB(void, Bs3Trap32Init,(void));
3276
3277	/**
3278	* Initializes 64-bit trap handling
3279	*
3280	* @remarks Does not install 64-bit trap handling, just initializes the
3281	* structures.
3282	*/
3283	BS3_CMN_PROTO_STUB(void, Bs3Trap64Init,(void));
3284
3285	/**
3286	* Initializes 64-bit trap handling, extended version.
3287	*
3288	* @remarks Does not install 64-bit trap handling, just initializes the
3289	* structures.
3290	* @param fMoreIstUsage Use the interrupt stacks for more CPU exceptions.
3291	* Default (false) is to only IST1 for the double fault
3292	* handler and the rest uses IST0.
3293	*/
3294	BS3_CMN_PROTO_STUB(void, Bs3Trap64InitEx,(bool fMoreIstUsage));
3295
3296	/**
3297	* Modifies the real-mode / V86 IVT entry specified by @a iIvt.
3298	*
3299	* @param iIvt The index of the IDT entry to set.
3300	* @param uSeg The handler real-mode segment.
3301	* @param off The handler offset.
3302	*/
3303	BS3_CMN_PROTO_STUB(void, Bs3TrapRmV86SetGate,(uint8_t iIvt, uint16_t uSeg, uint16_t off));
3304
3305	/**
3306	* Modifies the 16-bit IDT entry (protected mode) specified by @a iIdt.
3307	*
3308	* @param iIdt The index of the IDT entry to set.
3309	* @param bType The gate type (X86_SEL_TYPE_SYS_XXX).
3310	* @param bDpl The DPL.
3311	* @param uSel The handler selector.
3312	* @param off The handler offset (if applicable).
3313	* @param cParams The parameter count (for call gates).
3314	*/
3315	BS3_CMN_PROTO_STUB(void, Bs3Trap16SetGate,(uint8_t iIdt, uint8_t bType, uint8_t bDpl,
3316	uint16_t uSel, uint16_t off, uint8_t cParams));
3317
3318	/** The address of Bs3Trap16GenericEntries.
3319	* Bs3Trap16GenericEntries is an array of interrupt/trap/whatever entry
3320	* points, 8 bytes each, that will create a register frame and call the generic
3321	* C compatible trap handlers. */
3322	extern uint32_t g_Bs3Trap16GenericEntriesFlatAddr;
3323
3324	/**
3325	* Modifies the 32-bit IDT entry specified by @a iIdt.
3326	*
3327	* @param iIdt The index of the IDT entry to set.
3328	* @param bType The gate type (X86_SEL_TYPE_SYS_XXX).
3329	* @param bDpl The DPL.
3330	* @param uSel The handler selector.
3331	* @param off The handler offset (if applicable).
3332	* @param cParams The parameter count (for call gates).
3333	*/
3334	BS3_CMN_PROTO_STUB(void, Bs3Trap32SetGate,(uint8_t iIdt, uint8_t bType, uint8_t bDpl,
3335	uint16_t uSel, uint32_t off, uint8_t cParams));
3336
3337	/** The address of Bs3Trap32GenericEntries.
3338	* Bs3Trap32GenericEntries is an array of interrupt/trap/whatever entry
3339	* points, 10 bytes each, that will create a register frame and call the generic
3340	* C compatible trap handlers. */
3341	extern uint32_t g_Bs3Trap32GenericEntriesFlatAddr;
3342
3343	/**
3344	* Modifies the 64-bit IDT entry specified by @a iIdt.
3345	*
3346	* @param iIdt The index of the IDT entry to set.
3347	* @param bType The gate type (X86_SEL_TYPE_SYS_XXX).
3348	* @param bDpl The DPL.
3349	* @param uSel The handler selector.
3350	* @param off The handler offset (if applicable).
3351	* @param bIst The interrupt stack to use.
3352	*/
3353	BS3_CMN_PROTO_STUB(void, Bs3Trap64SetGate,(uint8_t iIdt, uint8_t bType, uint8_t bDpl, uint16_t uSel, uint64_t off, uint8_t bIst));
3354
3355	/** The address of Bs3Trap64GenericEntries.
3356	* Bs3Trap64GenericEntries is an array of interrupt/trap/whatever entry
3357	* points, 8 bytes each, that will create a register frame and call the generic
3358	* C compatible trap handlers. */
3359	extern uint32_t g_Bs3Trap64GenericEntriesFlatAddr;
3360
3361	/**
3362	* Adjusts the DPL the IDT entry specified by @a iIdt.
3363	*
3364	* The change is applied to the 16-bit, 32-bit and 64-bit IDTs.
3365	*
3366	* @returns Old DPL (from 64-bit IDT).
3367	* @param iIdt The index of the IDT and IVT entry to set.
3368	* @param bDpl The DPL.
3369	*/
3370	BS3_CMN_PROTO_STUB(uint8_t, Bs3TrapSetDpl,(uint8_t iIdt, uint8_t bDpl));
3371
3372	/**
3373	* C-style trap handler.
3374	*
3375	* The caller will resume the context in @a pTrapFrame upon return.
3376	*
3377	* @param pTrapFrame The trap frame. Registers can be modified.
3378	* @note The 16-bit versions must be in CGROUP16!
3379	*/
3380	typedef BS3_DECL_NEAR_CALLBACK(void) FNBS3TRAPHANDLER(PBS3TRAPFRAME pTrapFrame);
3381	/** Pointer to a trap handler (current template context). */
3382	typedef FNBS3TRAPHANDLER *PFNBS3TRAPHANDLER;
3383
3384	#if ARCH_BITS == 16
3385	/** @copydoc FNBS3TRAPHANDLER */
3386	typedef FNBS3FAR FNBS3TRAPHANDLER32;
3387	/** @copydoc FNBS3TRAPHANDLER */
3388	typedef FNBS3FAR FNBS3TRAPHANDLER64;
3389	#else
3390	/** @copydoc FNBS3TRAPHANDLER */
3391	typedef FNBS3TRAPHANDLER FNBS3TRAPHANDLER32;
3392	/** @copydoc FNBS3TRAPHANDLER */
3393	typedef FNBS3TRAPHANDLER FNBS3TRAPHANDLER64;
3394	#endif
3395	/** @copydoc PFNBS3TRAPHANDLER */
3396	typedef FNBS3TRAPHANDLER32 *PFNBS3TRAPHANDLER32;
3397	/** @copydoc PFNBS3TRAPHANDLER */
3398	typedef FNBS3TRAPHANDLER64 *PFNBS3TRAPHANDLER64;
3399
3400
3401	/**
3402	* C-style trap handler, near 16-bit (CGROUP16).
3403	*
3404	* The caller will resume the context in @a pTrapFrame upon return.
3405	*
3406	* @param pTrapFrame The trap frame. Registers can be modified.
3407	*/
3408	typedef BS3_DECL_NEAR_CALLBACK(void) FNBS3TRAPHANDLER16(PBS3TRAPFRAME pTrapFrame);
3409	/** Pointer to a trap handler (current template context). */
3410	typedef FNBS3TRAPHANDLER16 *PFNBS3TRAPHANDLER16;
3411
3412	/**
3413	* C-style trap handler, near 16-bit (CGROUP16).
3414	*
3415	* The caller will resume the context in @a pTrapFrame upon return.
3416	*
3417	* @param pTrapFrame The trap frame. Registers can be modified.
3418	*/
3419	typedef BS3_DECL_CALLBACK(void) FNBS3TRAPHANDLER3264(PBS3TRAPFRAME pTrapFrame);
3420	/** Pointer to a trap handler (current template context). */
3421	typedef FNBS3TRAPHANDLER3264 *FPFNBS3TRAPHANDLER3264;
3422
3423
3424	/**
3425	* Sets a trap handler (C/C++/assembly) for the current bitcount.
3426	*
3427	* @returns Previous handler.
3428	* @param iIdt The index of the IDT entry to set.
3429	* @param pfnHandler Pointer to the handler.
3430	* @sa Bs3TrapSetHandlerEx
3431	*/
3432	BS3_CMN_PROTO_STUB(PFNBS3TRAPHANDLER, Bs3TrapSetHandler,(uint8_t iIdt, PFNBS3TRAPHANDLER pfnHandler));
3433
3434	/**
3435	* Sets a trap handler (C/C++/assembly) for all the bitcounts.
3436	*
3437	* @param iIdt The index of the IDT and IVT entry to set.
3438	* @param pfnHandler16 Pointer to the 16-bit handler. (Assumes linker addresses.)
3439	* @param pfnHandler32 Pointer to the 32-bit handler. (Assumes linker addresses.)
3440	* @param pfnHandler64 Pointer to the 64-bit handler. (Assumes linker addresses.)
3441	* @sa Bs3TrapSetHandler
3442	*/
3443	BS3_CMN_PROTO_STUB(void, Bs3TrapSetHandlerEx,(uint8_t iIdt, PFNBS3TRAPHANDLER16 pfnHandler16,
3444	PFNBS3TRAPHANDLER32 pfnHandler32, PFNBS3TRAPHANDLER64 pfnHandler64));
3445
3446	/**
3447	* Default C/C++ trap handler.
3448	*
3449	* This will check trap record and panic if no match was found.
3450	*
3451	* @param pTrapFrame Trap frame of the trap to handle.
3452	*/
3453	BS3_CMN_PROTO_STUB(void, Bs3TrapDefaultHandler,(PBS3TRAPFRAME pTrapFrame));
3454
3455	/**
3456	* Prints the trap frame (to screen).
3457	* @param pTrapFrame Trap frame to print.
3458	*/
3459	BS3_CMN_PROTO_STUB(void, Bs3TrapPrintFrame,(PCBS3TRAPFRAME pTrapFrame));
3460
3461	/**
3462	* Sets up a long jump from a trap handler.
3463	*
3464	* The long jump will only be performed once, but will catch any kind of trap,
3465	* fault, interrupt or irq.
3466	*
3467	* @retval true on the initial call.
3468	* @retval false on trap return.
3469	* @param pTrapFrame Where to store the trap information when
3470	* returning @c false.
3471	* @sa #Bs3TrapUnsetJmp
3472	*/
3473	BS3_CMN_PROTO_NOSB(DECL_RETURNS_TWICE(bool),Bs3TrapSetJmp,(PBS3TRAPFRAME pTrapFrame));
3474
3475	/**
3476	* Combination of #Bs3TrapSetJmp and #Bs3RegCtxRestore.
3477	*
3478	* @param pCtxRestore The context to restore.
3479	* @param pTrapFrame Where to store the trap information.
3480	*/
3481	BS3_CMN_PROTO_STUB(void, Bs3TrapSetJmpAndRestore,(PCBS3REGCTX pCtxRestore, PBS3TRAPFRAME pTrapFrame));
3482
3483	/**
3484	* Variation of Bs3TrapSetJmpAndRestore that includes
3485	* #Bs3TrapSetJmpAndRestoreInRm and calls is if pCtxRestore is a real mode
3486	* context and we're not in real mode.
3487	*
3488	* This is useful for 32-bit test drivers running via #Bs3TestDoModesByOne using
3489	* BS3TESTMODEBYONEENTRY_F_REAL_MODE_READY to allow them to test real-mode too.
3490	*
3491	* @param pCtxRestore The context to restore.
3492	* @param pTrapFrame Where to store the trap information.
3493	*/
3494	BS3_CMN_PROTO_STUB(void, Bs3TrapSetJmpAndRestoreWithRm,(PCBS3REGCTX pCtxRestore, PBS3TRAPFRAME pTrapFrame));
3495
3496	/**
3497	* Combination of #Bs3ExtCtxRestoreEx, #Bs3TrapSetJmp, #Bs3RegCtxRestore and
3498	* #Bs3ExtCtxSaveEx.
3499	*
3500	* @param pCtxRestore The context to restore.
3501	* @param pExtCtxRestore The extended context to restore.
3502	* @param pTrapFrame Where to store the trap information.
3503	* @param pExtCtxTrap Where to store the extended context after the trap.
3504	* Note, the saving isn't done from the trap handler,
3505	* but after #Bs3TrapSetJmp returns zero (i.e. for the
3506	* 2nd time).
3507	*/
3508	BS3_CMN_PROTO_STUB(void, Bs3TrapSetJmpAndRestoreWithExtCtx,(PCBS3REGCTX pCtxRestore, PCBS3EXTCTX pExtCtxRestore,
3509	PBS3TRAPFRAME pTrapFrame, PBS3EXTCTX pExtCtxTrap));
3510
3511	/**
3512	* Variation of Bs3TrapSetJmpAndRestoreWithExtCtx that includes
3513	* #Bs3TrapSetJmpAndRestoreInRm and calls is if pCtxRestore is a real mode
3514	* context and we're not in real mode.
3515	*
3516	* This is useful for 32-bit test drivers running via #Bs3TestDoModesByOne using
3517	* BS3TESTMODEBYONEENTRY_F_REAL_MODE_READY to allow them to test real-mode too.
3518	*
3519	* @param pCtxRestore The context to restore.
3520	* @param pExtCtxRestore The extended context to restore.
3521	* @param pTrapFrame Where to store the trap information.
3522	* @param pExtCtxTrap Where to store the extended context after the trap.
3523	* Note, the saving isn't done from the trap handler,
3524	* but after #Bs3TrapSetJmp returns zero (i.e. for the
3525	* 2nd time).
3526	*/
3527	BS3_CMN_PROTO_STUB(void, Bs3TrapSetJmpAndRestoreWithExtCtxAndRm,(PCBS3REGCTX pCtxRestore, PCBS3EXTCTX pExtCtxRestore,
3528	PBS3TRAPFRAME pTrapFrame, PBS3EXTCTX pExtCtxTrap));
3529
3530	/**
3531	* Combination of Bs3SwitchToRM, #Bs3TrapSetJmp and #Bs3RegCtxRestore.
3532	*
3533	* @param pCtxRestore The context to restore. Must be real-mode
3534	* addressable.
3535	* @param pTrapFrame Where to store the trap information. Must be
3536	* real-mode addressable.
3537	*/
3538	BS3_CMN_PROTO_STUB(void, Bs3TrapSetJmpAndRestoreInRm,(PCBS3REGCTX pCtxRestore, PBS3TRAPFRAME pTrapFrame));
3539
3540	/**
3541	* Disables a previous #Bs3TrapSetJmp call.
3542	*/
3543	BS3_CMN_PROTO_STUB(void, Bs3TrapUnsetJmp,(void));
3544
3545
3546	/**
3547	* The current test step.
3548	*/
3549	extern uint16_t g_usBs3TestStep;
3550
3551	/**
3552	* Equivalent to RTTestCreate + RTTestBanner.
3553	*
3554	* @param pszTest The test name.
3555	*/
3556	BS3_CMN_PROTO_STUB(void, Bs3TestInit,(const char BS3_FAR *pszTest));
3557
3558
3559	/**
3560	* Equivalent to RTTestSummaryAndDestroy.
3561	*/
3562	BS3_CMN_PROTO_STUB(void, Bs3TestTerm,(void));
3563
3564	/**
3565	* Equivalent to RTTestISub.
3566	*/
3567	BS3_CMN_PROTO_STUB(void, Bs3TestSub,(const char BS3_FAR *pszSubTest));
3568
3569	/**
3570	* Equivalent to RTTestIFailedF.
3571	*/
3572	BS3_CMN_PROTO_STUB(void, Bs3TestSubF,(const char BS3_FAR *pszFormat, ...));
3573
3574	/**
3575	* Equivalent to RTTestISubV.
3576	*/
3577	BS3_CMN_PROTO_STUB(void, Bs3TestSubV,(const char BS3_FAR *pszFormat, va_list BS3_FAR va));
3578
3579	/**
3580	* Equivalent to RTTestISubDone.
3581	*/
3582	BS3_CMN_PROTO_STUB(void, Bs3TestSubDone,(void));
3583
3584	/**
3585	* Equivalent to RTTestIValue.
3586	*/
3587	BS3_CMN_PROTO_STUB(void, Bs3TestValue,(const char BS3_FAR *pszName, uint64_t u64Value, uint8_t bUnit));
3588
3589	/**
3590	* Equivalent to RTTestSubErrorCount.
3591	*/
3592	BS3_CMN_PROTO_STUB(uint16_t, Bs3TestSubErrorCount,(void));
3593
3594	/**
3595	* Get nanosecond host timestamp.
3596	*
3597	* This only works when testing is enabled and will not work in VMs configured
3598	* with a 286, 186 or 8086/8088 CPU profile.
3599	*/
3600	BS3_CMN_PROTO_STUB(uint64_t, Bs3TestNow,(void));
3601
3602
3603	/**
3604	* Queries an unsigned 8-bit configuration value.
3605	*
3606	* @returns Value.
3607	* @param uCfg A VMMDEV_TESTING_CFG_XXX value.
3608	*/
3609	BS3_CMN_PROTO_STUB(uint8_t, Bs3TestQueryCfgU8,(uint16_t uCfg));
3610
3611	/**
3612	* Queries an unsigned 8-bit configuration value.
3613	*
3614	* @returns Value.
3615	* @param uCfg A VMMDEV_TESTING_CFG_XXX value.
3616	*/
3617	BS3_CMN_PROTO_STUB(bool, Bs3TestQueryCfgBool,(uint16_t uCfg));
3618
3619	/**
3620	* Queries an unsigned 32-bit configuration value.
3621	*
3622	* @returns Value.
3623	* @param uCfg A VMMDEV_TESTING_CFG_XXX value.
3624	*/
3625	BS3_CMN_PROTO_STUB(uint32_t, Bs3TestQueryCfgU32,(uint16_t uCfg));
3626
3627	/**
3628	* Equivalent to RTTestIPrintf with RTTESTLVL_ALWAYS.
3629	*
3630	* @param pszFormat What to print, format string. Explicit newline char.
3631	* @param ... String format arguments.
3632	*/
3633	BS3_CMN_PROTO_STUB(void, Bs3TestPrintf,(const char BS3_FAR *pszFormat, ...));
3634
3635	/**
3636	* Equivalent to RTTestIPrintfV with RTTESTLVL_ALWAYS.
3637	*
3638	* @param pszFormat What to print, format string. Explicit newline char.
3639	* @param va String format arguments.
3640	*/
3641	BS3_CMN_PROTO_STUB(void, Bs3TestPrintfV,(const char BS3_FAR *pszFormat, va_list BS3_FAR va));
3642
3643	/**
3644	* Same as Bs3TestPrintf, except no guest screen echo.
3645	*
3646	* @param pszFormat What to print, format string. Explicit newline char.
3647	* @param ... String format arguments.
3648	*/
3649	BS3_CMN_PROTO_STUB(void, Bs3TestHostPrintf,(const char BS3_FAR *pszFormat, ...));
3650
3651	/**
3652	* Same as Bs3TestPrintfV, except no guest screen echo.
3653	*
3654	* @param pszFormat What to print, format string. Explicit newline char.
3655	* @param va String format arguments.
3656	*/
3657	BS3_CMN_PROTO_STUB(void, Bs3TestHostPrintfV,(const char BS3_FAR *pszFormat, va_list BS3_FAR va));
3658
3659	/**
3660	* Equivalent to RTTestIFailed.
3661	* @returns false.
3662	*/
3663	BS3_CMN_PROTO_STUB(bool, Bs3TestFailed,(const char BS3_FAR *pszMessage));
3664
3665	/**
3666	* Equivalent to RTTestIFailedF.
3667	* @returns false.
3668	*/
3669	BS3_CMN_PROTO_STUB(bool, Bs3TestFailedF,(const char BS3_FAR *pszFormat, ...));
3670
3671	/**
3672	* Equivalent to RTTestIFailedV.
3673	* @returns false.
3674	*/
3675	BS3_CMN_PROTO_STUB(bool, Bs3TestFailedV,(const char BS3_FAR *pszFormat, va_list BS3_FAR va));
3676
3677	/**
3678	* Equivalent to RTTestISkipped.
3679	*
3680	* @param pszWhy Optional reason why it's being skipped.
3681	*/
3682	BS3_CMN_PROTO_STUB(void, Bs3TestSkipped,(const char BS3_FAR *pszWhy));
3683
3684	/**
3685	* Equivalent to RTTestISkippedF.
3686	*
3687	* @param pszFormat Optional reason why it's being skipped.
3688	* @param ... Format arguments.
3689	*/
3690	BS3_CMN_PROTO_STUB(void, Bs3TestSkippedF,(const char BS3_FAR *pszFormat, ...));
3691
3692	/**
3693	* Equivalent to RTTestISkippedV.
3694	*
3695	* @param pszFormat Optional reason why it's being skipped.
3696	* @param va Format arguments.
3697	*/
3698	BS3_CMN_PROTO_STUB(void, Bs3TestSkippedV,(const char BS3_FAR *pszFormat, va_list BS3_FAR va));
3699
3700	/**
3701	* Compares two register contexts, with PC and SP adjustments.
3702	*
3703	* Differences will be reported as test failures.
3704	*
3705	* @returns true if equal, false if not.
3706	* @param pActualCtx The actual register context.
3707	* @param pExpectedCtx Expected register context.
3708	* @param cbPcAdjust Program counter adjustment (applied to @a pExpectedCtx).
3709	* @param cbSpAdjust Stack pointer adjustment (applied to @a pExpectedCtx).
3710	* @param fExtraEfl Extra EFLAGS to OR into @a pExepctedCtx.
3711	* @param pszMode CPU mode or some other helpful text.
3712	* @param idTestStep Test step identifier.
3713	*/
3714	BS3_CMN_PROTO_STUB(bool, Bs3TestCheckRegCtxEx,(PCBS3REGCTX pActualCtx, PCBS3REGCTX pExpectedCtx, uint16_t cbPcAdjust,
3715	int16_t cbSpAdjust, uint32_t fExtraEfl,
3716	const char BS3_FAR *pszMode, uint16_t idTestStep));
3717
3718	/**
3719	* Compares two extended register contexts.
3720	*
3721	* Differences will be reported as test failures.
3722	*
3723	* @returns true if equal, false if not.
3724	* @param pActualExtCtx The actual register context.
3725	* @param pExpectedExtCtx Expected register context.
3726	* @param fFlags Reserved, pass 0.
3727	* @param pszMode CPU mode or some other helpful text.
3728	* @param idTestStep Test step identifier.
3729	*/
3730	BS3_CMN_PROTO_STUB(bool, Bs3TestCheckExtCtx,(PCBS3EXTCTX pActualExtCtx, PCBS3EXTCTX pExpectedExtCtx, uint16_t fFlags,
3731	const char BS3_FAR *pszMode, uint16_t idTestStep));
3732
3733	/**
3734	* Performs the testing for the given mode.
3735	*
3736	* This is called with the CPU already switch to that mode.
3737	*
3738	* @returns 0 on success or directly Bs3TestFailed calls, non-zero to indicate
3739	* where the test when wrong. Special value BS3TESTDOMODE_SKIPPED
3740	* should be returned to indicate that the test has been skipped.
3741	* @param bMode The current CPU mode.
3742	*/
3743	typedef BS3_DECL_CALLBACK(uint8_t) FNBS3TESTDOMODE(uint8_t bMode);
3744	/** Pointer (far) to a test (for 32-bit and 64-bit code, will be flatten). */
3745	typedef FNBS3TESTDOMODE *PFNBS3TESTDOMODE;
3746
3747	/** Special FNBS3TESTDOMODE return code for indicating a skipped mode test. */
3748	#define BS3TESTDOMODE_SKIPPED UINT8_MAX
3749
3750	/**
3751	* Mode sub-test entry.
3752	*
3753	* This can only be passed around to functions with the same bit count, as it
3754	* contains function pointers. In 16-bit mode, the 16-bit pointers are near and
3755	* implies BS3TEXT16, whereas the 32-bit and 64-bit pointers are far real mode
3756	* addresses that will be converted to flat address prior to calling them.
3757	* Similarly, in 32-bit and 64-bit the addresses are all flat and the 16-bit
3758	* ones will be converted to BS3TEXT16 based addresses prior to calling.
3759	*/
3760	typedef struct BS3TESTMODEENTRY
3761	{
3762	/** The sub-test name to be passed to Bs3TestSub if not NULL. */
3763	const char * BS3_FAR pszSubTest;
3764
3765	PFNBS3TESTDOMODE pfnDoRM;
3766
3767	PFNBS3TESTDOMODE pfnDoPE16;
3768	PFNBS3TESTDOMODE pfnDoPE16_32;
3769	PFNBS3TESTDOMODE pfnDoPE16_V86;
3770	PFNBS3TESTDOMODE pfnDoPE32;
3771	PFNBS3TESTDOMODE pfnDoPE32_16;
3772	PFNBS3TESTDOMODE pfnDoPEV86;
3773
3774	PFNBS3TESTDOMODE pfnDoPP16;
3775	PFNBS3TESTDOMODE pfnDoPP16_32;
3776	PFNBS3TESTDOMODE pfnDoPP16_V86;
3777	PFNBS3TESTDOMODE pfnDoPP32;
3778	PFNBS3TESTDOMODE pfnDoPP32_16;
3779	PFNBS3TESTDOMODE pfnDoPPV86;
3780
3781	PFNBS3TESTDOMODE pfnDoPAE16;
3782	PFNBS3TESTDOMODE pfnDoPAE16_32;
3783	PFNBS3TESTDOMODE pfnDoPAE16_V86;
3784	PFNBS3TESTDOMODE pfnDoPAE32;
3785	PFNBS3TESTDOMODE pfnDoPAE32_16;
3786	PFNBS3TESTDOMODE pfnDoPAEV86;
3787
3788	PFNBS3TESTDOMODE pfnDoLM16;
3789	PFNBS3TESTDOMODE pfnDoLM32;
3790	PFNBS3TESTDOMODE pfnDoLM64;
3791
3792	} BS3TESTMODEENTRY;
3793	/** Pointer to a mode sub-test entry. */
3794	typedef BS3TESTMODEENTRY const *PCBS3TESTMODEENTRY;
3795
3796	/** @def BS3TESTMODEENTRY_CMN
3797	* Produces a BS3TESTMODEENTRY initializer for common (c16,c32,c64) test
3798	* functions. */
3799	#define BS3TESTMODEENTRY_CMN(a_szTest, a_BaseNm) \
3800	{ /pszSubTest =/ a_szTest, \
3801	/RM/ RT_CONCAT(a_BaseNm, _c16), \
3802	/PE16/ RT_CONCAT(a_BaseNm, _c16), \
3803	/PE16_32/ RT_CONCAT(a_BaseNm, _c32), \
3804	/PE16_V86/ RT_CONCAT(a_BaseNm, _c16), \
3805	/PE32/ RT_CONCAT(a_BaseNm, _c32), \
3806	/PE32_16/ RT_CONCAT(a_BaseNm, _c16), \
3807	/PEV86/ RT_CONCAT(a_BaseNm, _c16), \
3808	/PP16/ RT_CONCAT(a_BaseNm, _c16), \
3809	/PP16_32/ RT_CONCAT(a_BaseNm, _c32), \
3810	/PP16_V86/ RT_CONCAT(a_BaseNm, _c16), \
3811	/PP32/ RT_CONCAT(a_BaseNm, _c32), \
3812	/PP32_16/ RT_CONCAT(a_BaseNm, _c16), \
3813	/PPV86/ RT_CONCAT(a_BaseNm, _c16), \
3814	/PAE16/ RT_CONCAT(a_BaseNm, _c16), \
3815	/PAE16_32/ RT_CONCAT(a_BaseNm, _c32), \
3816	/PAE16_V86/ RT_CONCAT(a_BaseNm, _c16), \
3817	/PAE32/ RT_CONCAT(a_BaseNm, _c32), \
3818	/PAE32_16/ RT_CONCAT(a_BaseNm, _c16), \
3819	/PAEV86/ RT_CONCAT(a_BaseNm, _c16), \
3820	/LM16/ RT_CONCAT(a_BaseNm, _c16), \
3821	/LM32/ RT_CONCAT(a_BaseNm, _c32), \
3822	/LM64/ RT_CONCAT(a_BaseNm, _c64), \
3823	}
3824
3825	/** @def BS3TESTMODE_PROTOTYPES_CMN
3826	* A set of standard protypes to go with #BS3TESTMODEENTRY_CMN. */
3827	#define BS3TESTMODE_PROTOTYPES_CMN(a_BaseNm) \
3828	FNBS3TESTDOMODE /BS3_FAR_CODE/ RT_CONCAT(a_BaseNm, _c16); \
3829	FNBS3TESTDOMODE /BS3_FAR_CODE/ RT_CONCAT(a_BaseNm, _c32); \
3830	FNBS3TESTDOMODE /BS3_FAR_CODE/ RT_CONCAT(a_BaseNm, _c64)
3831
3832	/** @def BS3TESTMODEENTRY_CMN_64
3833	* Produces a BS3TESTMODEENTRY initializer for common 64-bit test functions. */
3834	#define BS3TESTMODEENTRY_CMN_64(a_szTest, a_BaseNm) \
3835	{ /pszSubTest =/ a_szTest, \
3836	/RM/ NULL, \
3837	/PE16/ NULL, \
3838	/PE16_32/ NULL, \
3839	/PE16_V86/ NULL, \
3840	/PE32/ NULL, \
3841	/PE32_16/ NULL, \
3842	/PEV86/ NULL, \
3843	/PP16/ NULL, \
3844	/PP16_32/ NULL, \
3845	/PP16_V86/ NULL, \
3846	/PP32/ NULL, \
3847	/PP32_16/ NULL, \
3848	/PPV86/ NULL, \
3849	/PAE16/ NULL, \
3850	/PAE16_32/ NULL, \
3851	/PAE16_V86/ NULL, \
3852	/PAE32/ NULL, \
3853	/PAE32_16/ NULL, \
3854	/PAEV86/ NULL, \
3855	/LM16/ NULL, \
3856	/LM32/ NULL, \
3857	/LM64/ RT_CONCAT(a_BaseNm, _c64), \
3858	}
3859
3860	/** @def BS3TESTMODE_PROTOTYPES_CMN
3861	* Standard protype to go with #BS3TESTMODEENTRY_CMN_64. */
3862	#define BS3TESTMODE_PROTOTYPES_CMN_64(a_BaseNm) \
3863	FNBS3TESTDOMODE /BS3_FAR_CODE/ RT_CONCAT(a_BaseNm, _c64)
3864
3865	/** @def BS3TESTMODEENTRY_MODE
3866	* Produces a BS3TESTMODEENTRY initializer for a full set of mode test
3867	* functions. */
3868	#define BS3TESTMODEENTRY_MODE(a_szTest, a_BaseNm) \
3869	{ /pszSubTest =/ a_szTest, \
3870	/RM/ RT_CONCAT(a_BaseNm, _rm), \
3871	/PE16/ RT_CONCAT(a_BaseNm, _pe16), \
3872	/PE16_32/ RT_CONCAT(a_BaseNm, _pe16_32), \
3873	/PE16_V86/ RT_CONCAT(a_BaseNm, _pe16_v86), \
3874	/PE32/ RT_CONCAT(a_BaseNm, _pe32), \
3875	/PE32_16/ RT_CONCAT(a_BaseNm, _pe32_16), \
3876	/PEV86/ RT_CONCAT(a_BaseNm, _pev86), \
3877	/PP16/ RT_CONCAT(a_BaseNm, _pp16), \
3878	/PP16_32/ RT_CONCAT(a_BaseNm, _pp16_32), \
3879	/PP16_V86/ RT_CONCAT(a_BaseNm, _pp16_v86), \
3880	/PP32/ RT_CONCAT(a_BaseNm, _pp32), \
3881	/PP32_16/ RT_CONCAT(a_BaseNm, _pp32_16), \
3882	/PPV86/ RT_CONCAT(a_BaseNm, _ppv86), \
3883	/PAE16/ RT_CONCAT(a_BaseNm, _pae16), \
3884	/PAE16_32/ RT_CONCAT(a_BaseNm, _pae16_32), \
3885	/PAE16_V86/ RT_CONCAT(a_BaseNm, _pae16_v86), \
3886	/PAE32/ RT_CONCAT(a_BaseNm, _pae32), \
3887	/PAE32_16/ RT_CONCAT(a_BaseNm, _pae32_16), \
3888	/PAEV86/ RT_CONCAT(a_BaseNm, _paev86), \
3889	/LM16/ RT_CONCAT(a_BaseNm, _lm16), \
3890	/LM32/ RT_CONCAT(a_BaseNm, _lm32), \
3891	/LM64/ RT_CONCAT(a_BaseNm, _lm64), \
3892	}
3893
3894	/** @def BS3TESTMODE_PROTOTYPES_MODE
3895	* A set of standard protypes to go with #BS3TESTMODEENTRY_MODE. */
3896	#define BS3TESTMODE_PROTOTYPES_MODE(a_BaseNm) \
3897	FNBS3TESTDOMODE RT_CONCAT(a_BaseNm, _rm); \
3898	FNBS3TESTDOMODE RT_CONCAT(a_BaseNm, _pe16); \
3899	FNBS3TESTDOMODE RT_CONCAT(a_BaseNm, _pe16_32); \
3900	FNBS3TESTDOMODE RT_CONCAT(a_BaseNm, _pe16_v86); \
3901	FNBS3TESTDOMODE RT_CONCAT(a_BaseNm, _pe32); \
3902	FNBS3TESTDOMODE RT_CONCAT(a_BaseNm, _pe32_16); \
3903	FNBS3TESTDOMODE RT_CONCAT(a_BaseNm, _pev86); \
3904	FNBS3TESTDOMODE RT_CONCAT(a_BaseNm, _pp16); \
3905	FNBS3TESTDOMODE RT_CONCAT(a_BaseNm, _pp16_32); \
3906	FNBS3TESTDOMODE RT_CONCAT(a_BaseNm, _pp16_v86); \
3907	FNBS3TESTDOMODE RT_CONCAT(a_BaseNm, _pp32); \
3908	FNBS3TESTDOMODE RT_CONCAT(a_BaseNm, _pp32_16); \
3909	FNBS3TESTDOMODE RT_CONCAT(a_BaseNm, _ppv86); \
3910	FNBS3TESTDOMODE RT_CONCAT(a_BaseNm, _pae16); \
3911	FNBS3TESTDOMODE RT_CONCAT(a_BaseNm, _pae16_32); \
3912	FNBS3TESTDOMODE RT_CONCAT(a_BaseNm, _pae16_v86); \
3913	FNBS3TESTDOMODE RT_CONCAT(a_BaseNm, _pae32); \
3914	FNBS3TESTDOMODE RT_CONCAT(a_BaseNm, _pae32_16); \
3915	FNBS3TESTDOMODE RT_CONCAT(a_BaseNm, _paev86); \
3916	FNBS3TESTDOMODE RT_CONCAT(a_BaseNm, _lm16); \
3917	FNBS3TESTDOMODE RT_CONCAT(a_BaseNm, _lm32); \
3918	FNBS3TESTDOMODE RT_CONCAT(a_BaseNm, _lm64)
3919
3920
3921	/**
3922	* Mode sub-test entry, max bit-count driven
3923	*
3924	* This is an alternative to BS3TESTMODEENTRY where a few workers (test drivers)
3925	* does all the work, using faster 32-bit and 64-bit code where possible. This
3926	* avoids executing workers in V8086 mode. It allows for modifying and checking
3927	* 64-bit register content when testing LM16 and LM32.
3928	*
3929	* The 16-bit workers are only used for real mode and 16-bit protected mode.
3930	* So, the 16-bit version of the code template can be stripped of anything
3931	* related to paging and/or v8086, saving code space.
3932	*/
3933	typedef struct BS3TESTMODEBYMAXENTRY
3934	{
3935	/** The sub-test name to be passed to Bs3TestSub if not NULL. */
3936	const char * BS3_FAR pszSubTest;
3937
3938	PFNBS3TESTDOMODE pfnDoRM;
3939	PFNBS3TESTDOMODE pfnDoPE16;
3940	PFNBS3TESTDOMODE pfnDoPE16_32;
3941	PFNBS3TESTDOMODE pfnDoPE32;
3942	PFNBS3TESTDOMODE pfnDoPP16_32;
3943	PFNBS3TESTDOMODE pfnDoPP32;
3944	PFNBS3TESTDOMODE pfnDoPAE16_32;
3945	PFNBS3TESTDOMODE pfnDoPAE32;
3946	PFNBS3TESTDOMODE pfnDoLM64;
3947
3948	bool fDoRM : 1;
3949
3950	bool fDoPE16 : 1;
3951	bool fDoPE16_32 : 1;
3952	bool fDoPE16_V86 : 1;
3953	bool fDoPE32 : 1;
3954	bool fDoPE32_16 : 1;
3955	bool fDoPEV86 : 1;
3956
3957	bool fDoPP16 : 1;
3958	bool fDoPP16_32 : 1;
3959	bool fDoPP16_V86 : 1;
3960	bool fDoPP32 : 1;
3961	bool fDoPP32_16 : 1;
3962	bool fDoPPV86 : 1;
3963
3964	bool fDoPAE16 : 1;
3965	bool fDoPAE16_32 : 1;
3966	bool fDoPAE16_V86 : 1;
3967	bool fDoPAE32 : 1;
3968	bool fDoPAE32_16 : 1;
3969	bool fDoPAEV86 : 1;
3970
3971	bool fDoLM16 : 1;
3972	bool fDoLM32 : 1;
3973	bool fDoLM64 : 1;
3974
3975	} BS3TESTMODEBYMAXENTRY;
3976	/** Pointer to a mode-by-max sub-test entry. */
3977	typedef BS3TESTMODEBYMAXENTRY const *PCBS3TESTMODEBYMAXENTRY;
3978
3979	/** @def BS3TESTMODEBYMAXENTRY_CMN
3980	* Produces a BS3TESTMODEBYMAXENTRY initializer for common (c16,c32,c64) test
3981	* functions. */
3982	#define BS3TESTMODEBYMAXENTRY_CMN(a_szTest, a_BaseNm) \
3983	{ /pszSubTest =/ a_szTest, \
3984	/RM/ RT_CONCAT(a_BaseNm, _c16), \
3985	/PE16/ RT_CONCAT(a_BaseNm, _c16), \
3986	/PE16_32/ RT_CONCAT(a_BaseNm, _c32), \
3987	/PE32/ RT_CONCAT(a_BaseNm, _c32), \
3988	/PP16_32/ RT_CONCAT(a_BaseNm, _c32), \
3989	/PP32/ RT_CONCAT(a_BaseNm, _c32), \
3990	/PAE16_32/ RT_CONCAT(a_BaseNm, _c32), \
3991	/PAE32/ RT_CONCAT(a_BaseNm, _c32), \
3992	/LM64/ RT_CONCAT(a_BaseNm, _c64), \
3993	/fDoRM/ true, \
3994	/fDoPE16/ true, \
3995	/fDoPE16_32/ true, \
3996	/fDoPE16_V86/ true, \
3997	/fDoPE32/ true, \
3998	/fDoPE32_16/ true, \
3999	/fDoPEV86/ true, \
4000	/fDoPP16/ true, \
4001	/fDoPP16_32/ true, \
4002	/fDoPP16_V86/ true, \
4003	/fDoPP32/ true, \
4004	/fDoPP32_16/ true, \
4005	/fDoPPV86/ true, \
4006	/fDoPAE16/ true, \
4007	/fDoPAE16_32/ true, \
4008	/fDoPAE16_V86/ true, \
4009	/fDoPAE32/ true, \
4010	/fDoPAE32_16/ true, \
4011	/fDoPAEV86/ true, \
4012	/fDoLM16/ true, \
4013	/fDoLM32/ true, \
4014	/fDoLM64/ true, \
4015	}
4016
4017	/** @def BS3TESTMODEBYMAX_PROTOTYPES_CMN
4018	* A set of standard protypes to go with #BS3TESTMODEBYMAXENTRY_CMN. */
4019	#define BS3TESTMODEBYMAX_PROTOTYPES_CMN(a_BaseNm) \
4020	FNBS3TESTDOMODE /BS3_FAR_CODE/ RT_CONCAT(a_BaseNm, _c16); \
4021	FNBS3TESTDOMODE /BS3_FAR_CODE/ RT_CONCAT(a_BaseNm, _c32); \
4022	FNBS3TESTDOMODE /BS3_FAR_CODE/ RT_CONCAT(a_BaseNm, _c64)
4023
4024
4025	/** @def BS3TESTMODEBYMAXENTRY_MODE
4026	* Produces a BS3TESTMODEBYMAXENTRY initializer for a full set of mode test
4027	* functions. */
4028	#define BS3TESTMODEBYMAXENTRY_MODE(a_szTest, a_BaseNm) \
4029	{ /pszSubTest =/ a_szTest, \
4030	/RM/ RT_CONCAT(a_BaseNm, _rm), \
4031	/PE16/ RT_CONCAT(a_BaseNm, _pe16), \
4032	/PE16_32/ RT_CONCAT(a_BaseNm, _pe16_32), \
4033	/PE32/ RT_CONCAT(a_BaseNm, _pe32), \
4034	/PP16_32/ RT_CONCAT(a_BaseNm, _pp16_32), \
4035	/PP32/ RT_CONCAT(a_BaseNm, _pp32), \
4036	/PAE16_32/ RT_CONCAT(a_BaseNm, _pae16_32), \
4037	/PAE32/ RT_CONCAT(a_BaseNm, _pae32), \
4038	/LM64/ RT_CONCAT(a_BaseNm, _lm64), \
4039	/fDoRM/ true, \
4040	/fDoPE16/ true, \
4041	/fDoPE16_32/ true, \
4042	/fDoPE16_V86/ true, \
4043	/fDoPE32/ true, \
4044	/fDoPE32_16/ true, \
4045	/fDoPEV86/ true, \
4046	/fDoPP16/ true, \
4047	/fDoPP16_32/ true, \
4048	/fDoPP16_V86/ true, \
4049	/fDoPP32/ true, \
4050	/fDoPP32_16/ true, \
4051	/fDoPPV86/ true, \
4052	/fDoPAE16/ true, \
4053	/fDoPAE16_32/ true, \
4054	/fDoPAE16_V86/ true, \
4055	/fDoPAE32/ true, \
4056	/fDoPAE32_16/ true, \
4057	/fDoPAEV86/ true, \
4058	/fDoLM16/ true, \
4059	/fDoLM32/ true, \
4060	/fDoLM64/ true, \
4061	}
4062
4063	/** @def BS3TESTMODEBYMAX_PROTOTYPES_MODE
4064	* A set of standard protypes to go with #BS3TESTMODEBYMAXENTRY_MODE. */
4065	#define BS3TESTMODEBYMAX_PROTOTYPES_MODE(a_BaseNm) \
4066	FNBS3TESTDOMODE RT_CONCAT(a_BaseNm, _rm); \
4067	FNBS3TESTDOMODE RT_CONCAT(a_BaseNm, _pe16); \
4068	FNBS3TESTDOMODE RT_CONCAT(a_BaseNm, _pe16_32); \
4069	FNBS3TESTDOMODE RT_CONCAT(a_BaseNm, _pe32); \
4070	FNBS3TESTDOMODE RT_CONCAT(a_BaseNm, _pp16_32); \
4071	FNBS3TESTDOMODE RT_CONCAT(a_BaseNm, _pp32); \
4072	FNBS3TESTDOMODE RT_CONCAT(a_BaseNm, _pae16_32); \
4073	FNBS3TESTDOMODE RT_CONCAT(a_BaseNm, _pae32); \
4074	FNBS3TESTDOMODE RT_CONCAT(a_BaseNm, _lm64)
4075
4076
4077	/**
4078	* One worker drives all modes.
4079	*
4080	* This is an alternative to BS3TESTMODEENTRY where one worker, typically
4081	* 16-bit, does all the test driver work. It's called repeatedly from all
4082	* the modes being tested.
4083	*/
4084	typedef struct BS3TESTMODEBYONEENTRY
4085	{
4086	const char * BS3_FAR pszSubTest;
4087	PFNBS3TESTDOMODE pfnWorker;
4088	/** BS3TESTMODEBYONEENTRY_F_XXX. */
4089	uint32_t fFlags;
4090	} BS3TESTMODEBYONEENTRY;
4091	/** Pointer to a mode-by-one sub-test entry. */
4092	typedef BS3TESTMODEBYONEENTRY const *PCBS3TESTMODEBYONEENTRY;
4093
4094	/** @name BS3TESTMODEBYONEENTRY_F_XXX - flags.
4095	* @{ */
4096	/** Only test modes that has paging enabled. */
4097	#define BS3TESTMODEBYONEENTRY_F_ONLY_PAGING RT_BIT_32(0)
4098	/** Minimal mode selection. */
4099	#define BS3TESTMODEBYONEENTRY_F_MINIMAL RT_BIT_32(1)
4100	/** The 32-bit worker is ready to handle real-mode by mode switching. */
4101	#define BS3TESTMODEBYONEENTRY_F_REAL_MODE_READY RT_BIT_32(2)
4102	/** @} */
4103
4104
4105	/**
4106	* Sets the full GDTR register.
4107	*
4108	* @param cbLimit The limit.
4109	* @param uBase The base address - 24, 32 or 64 bit depending on the
4110	* CPU mode.
4111	*/
4112	BS3_CMN_PROTO_NOSB(void, Bs3UtilSetFullGdtr,(uint16_t cbLimit, uint64_t uBase));
4113
4114	/**
4115	* Sets the full IDTR register.
4116	*
4117	* @param cbLimit The limit.
4118	* @param uBase The base address - 24, 32 or 64 bit depending on the
4119	* CPU mode.
4120	*/
4121	BS3_CMN_PROTO_NOSB(void, Bs3UtilSetFullIdtr,(uint16_t cbLimit, uint64_t uBase));
4122
4123
4124	/** @} */
4125
4126
4127	/**
4128	* Initializes all of boot sector kit \#3.
4129	*/
4130	BS3_DECL(void) Bs3InitAll_rm(void);
4131
4132	/**
4133	* Initializes the REAL and TILED memory pools.
4134	*
4135	* For proper operation on OLDer CPUs, call #Bs3CpuDetect_mmm first.
4136	*/
4137	BS3_DECL_FAR(void) Bs3InitMemory_rm_far(void);
4138
4139	/**
4140	* Initializes the X0TEXT16 and X1TEXT16 GDT entries.
4141	*/
4142	BS3_DECL_FAR(void) Bs3InitGdt_rm_far(void);
4143
4144
4145
4146	/** @defgroup grp_bs3kit_mode Mode Specific Functions and Data
4147	*
4148	* The mode specific functions come in bit count variations and CPU mode
4149	* variations. The bs3kit-template-header.h/mac defines the BS3_NM macro to
4150	* mangle a function or variable name according to the target CPU mode. In
4151	* non-templated code, it's common to spell the name out in full.
4152	*
4153	* @{
4154	*/
4155
4156
4157	/** @def BS3_MODE_PROTO_INT
4158	* Internal macro for emitting prototypes for mode functions.
4159	*
4160	* @param a_RetType The return type.
4161	* @param a_Name The function basename.
4162	* @param a_Params The parameter list (in parentheses).
4163	* @sa BS3_MODE_PROTO_STUB, BS3_MODE_PROTO_NOSB
4164	*/
4165	#define BS3_MODE_PROTO_INT(a_RetType, a_Name, a_Params) \
4166	BS3_DECL_NEAR(a_RetType) RT_CONCAT(a_Name,_rm) a_Params; \
4167	BS3_DECL_NEAR(a_RetType) RT_CONCAT(a_Name,_pe16) a_Params; \
4168	BS3_DECL_NEAR(a_RetType) RT_CONCAT(a_Name,_pe16_32) a_Params; \
4169	BS3_DECL_NEAR(a_RetType) RT_CONCAT(a_Name,_pe16_v86) a_Params; \
4170	BS3_DECL_NEAR(a_RetType) RT_CONCAT(a_Name,_pe32) a_Params; \
4171	BS3_DECL_NEAR(a_RetType) RT_CONCAT(a_Name,_pe32_16) a_Params; \
4172	BS3_DECL_NEAR(a_RetType) RT_CONCAT(a_Name,_pev86) a_Params; \
4173	BS3_DECL_NEAR(a_RetType) RT_CONCAT(a_Name,_pp16) a_Params; \
4174	BS3_DECL_NEAR(a_RetType) RT_CONCAT(a_Name,_pp16_32) a_Params; \
4175	BS3_DECL_NEAR(a_RetType) RT_CONCAT(a_Name,_pp16_v86) a_Params; \
4176	BS3_DECL_NEAR(a_RetType) RT_CONCAT(a_Name,_pp32) a_Params; \
4177	BS3_DECL_NEAR(a_RetType) RT_CONCAT(a_Name,_pp32_16) a_Params; \
4178	BS3_DECL_NEAR(a_RetType) RT_CONCAT(a_Name,_ppv86) a_Params; \
4179	BS3_DECL_NEAR(a_RetType) RT_CONCAT(a_Name,_pae16) a_Params; \
4180	BS3_DECL_NEAR(a_RetType) RT_CONCAT(a_Name,_pae16_32) a_Params; \
4181	BS3_DECL_NEAR(a_RetType) RT_CONCAT(a_Name,_pae16_v86) a_Params; \
4182	BS3_DECL_NEAR(a_RetType) RT_CONCAT(a_Name,_pae32) a_Params; \
4183	BS3_DECL_NEAR(a_RetType) RT_CONCAT(a_Name,_pae32_16) a_Params; \
4184	BS3_DECL_NEAR(a_RetType) RT_CONCAT(a_Name,_paev86) a_Params; \
4185	BS3_DECL_NEAR(a_RetType) RT_CONCAT(a_Name,_lm16) a_Params; \
4186	BS3_DECL_NEAR(a_RetType) RT_CONCAT(a_Name,_lm32) a_Params; \
4187	BS3_DECL_NEAR(a_RetType) RT_CONCAT(a_Name,_lm64) a_Params; \
4188	BS3_DECL_FAR(a_RetType) RT_CONCAT(a_Name,_rm_far) a_Params; \
4189	BS3_DECL_FAR(a_RetType) RT_CONCAT(a_Name,_pe16_far) a_Params; \
4190	BS3_DECL_FAR(a_RetType) RT_CONCAT(a_Name,_pe16_v86_far) a_Params; \
4191	BS3_DECL_FAR(a_RetType) RT_CONCAT(a_Name,_pe32_16_far) a_Params; \
4192	BS3_DECL_FAR(a_RetType) RT_CONCAT(a_Name,_pev86_far) a_Params; \
4193	BS3_DECL_FAR(a_RetType) RT_CONCAT(a_Name,_pp16_far) a_Params; \
4194	BS3_DECL_FAR(a_RetType) RT_CONCAT(a_Name,_pp16_v86_far) a_Params; \
4195	BS3_DECL_FAR(a_RetType) RT_CONCAT(a_Name,_pp32_16_far) a_Params; \
4196	BS3_DECL_FAR(a_RetType) RT_CONCAT(a_Name,_ppv86_far) a_Params; \
4197	BS3_DECL_FAR(a_RetType) RT_CONCAT(a_Name,_pae16_far) a_Params; \
4198	BS3_DECL_FAR(a_RetType) RT_CONCAT(a_Name,_pae16_v86_far)a_Params; \
4199	BS3_DECL_FAR(a_RetType) RT_CONCAT(a_Name,_pae32_16_far) a_Params; \
4200	BS3_DECL_FAR(a_RetType) RT_CONCAT(a_Name,_paev86_far) a_Params; \
4201	BS3_DECL_FAR(a_RetType) RT_CONCAT(a_Name,_lm16_far) a_Params
4202
4203	/** @def BS3_MODE_PROTO_STUB
4204	* Macro for prototyping all the variations of a mod function with automatic
4205	* near -> far stub.
4206	*
4207	* @param a_RetType The return type.
4208	* @param a_Name The function basename.
4209	* @param a_Params The parameter list (in parentheses).
4210	* @sa BS3_MODE_PROTO_STUB, BS3_MODE_PROTO_NOSB
4211	*/
4212	#define BS3_MODE_PROTO_STUB(a_RetType, a_Name, a_Params) BS3_MODE_PROTO_INT(a_RetType, a_Name, a_Params)
4213
4214	/** @def BS3_MODE_PROTO_STUB
4215	* Macro for prototyping all the variations of a mod function without any
4216	* near -> far stub.
4217	*
4218	* @param a_RetType The return type.
4219	* @param a_Name The function basename.
4220	* @param a_Params The parameter list (in parentheses).
4221	* @sa BS3_MODE_PROTO_STUB, BS3_MODE_PROTO_NOSB
4222	*/
4223	#define BS3_MODE_PROTO_NOSB(a_RetType, a_Name, a_Params) BS3_MODE_PROTO_INT(a_RetType, a_Name, a_Params)
4224
4225
4226	/**
4227	* Macro for reducing typing.
4228	*
4229	* Doxygen knows how to expand this, well, kind of.
4230	*
4231	* @remarks Variables instantiated in assembly code should define two labels,
4232	* with and without leading underscore. Variables instantiated from
4233	* C/C++ code doesn't need to as the object file convert does this for
4234	* 64-bit object files.
4235	*/
4236	#define BS3_MODE_EXPAND_EXTERN_DATA16(a_VarType, a_VarName, a_Suffix) \
4237	extern a_VarType BS3_FAR_DATA RT_CONCAT(a_VarName,_rm) a_Suffix; \
4238	extern a_VarType BS3_FAR_DATA RT_CONCAT(a_VarName,_pe16) a_Suffix; \
4239	extern a_VarType BS3_FAR_DATA RT_CONCAT(a_VarName,_pe16_32) a_Suffix; \
4240	extern a_VarType BS3_FAR_DATA RT_CONCAT(a_VarName,_pe16_v86) a_Suffix; \
4241	extern a_VarType BS3_FAR_DATA RT_CONCAT(a_VarName,_pe32) a_Suffix; \
4242	extern a_VarType BS3_FAR_DATA RT_CONCAT(a_VarName,_pe32_16) a_Suffix; \
4243	extern a_VarType BS3_FAR_DATA RT_CONCAT(a_VarName,_pev86) a_Suffix; \
4244	extern a_VarType BS3_FAR_DATA RT_CONCAT(a_VarName,_pp16) a_Suffix; \
4245	extern a_VarType BS3_FAR_DATA RT_CONCAT(a_VarName,_pp16_32) a_Suffix; \
4246	extern a_VarType BS3_FAR_DATA RT_CONCAT(a_VarName,_pp16_v86) a_Suffix; \
4247	extern a_VarType BS3_FAR_DATA RT_CONCAT(a_VarName,_pp32) a_Suffix; \
4248	extern a_VarType BS3_FAR_DATA RT_CONCAT(a_VarName,_pp32_16) a_Suffix; \
4249	extern a_VarType BS3_FAR_DATA RT_CONCAT(a_VarName,_ppv86) a_Suffix; \
4250	extern a_VarType BS3_FAR_DATA RT_CONCAT(a_VarName,_pae16) a_Suffix; \
4251	extern a_VarType BS3_FAR_DATA RT_CONCAT(a_VarName,_pae16_32) a_Suffix; \
4252	extern a_VarType BS3_FAR_DATA RT_CONCAT(a_VarName,_pae16_v86)a_Suffix; \
4253	extern a_VarType BS3_FAR_DATA RT_CONCAT(a_VarName,_pae32) a_Suffix; \
4254	extern a_VarType BS3_FAR_DATA RT_CONCAT(a_VarName,_pae32_16) a_Suffix; \
4255	extern a_VarType BS3_FAR_DATA RT_CONCAT(a_VarName,_paev86) a_Suffix; \
4256	extern a_VarType BS3_FAR_DATA RT_CONCAT(a_VarName,_lm16) a_Suffix; \
4257	extern a_VarType BS3_FAR_DATA RT_CONCAT(a_VarName,_lm32) a_Suffix; \
4258	extern a_VarType BS3_FAR_DATA RT_CONCAT(a_VarName,_lm64) a_Suffix
4259
4260
4261	/** The TMPL_MODE_STR value for each mode.
4262	* These are all in DATA16 so they can be accessed from any code. */
4263	BS3_MODE_EXPAND_EXTERN_DATA16(const char, g_szBs3ModeName, []);
4264	/** The TMPL_MODE_LNAME value for each mode.
4265	* These are all in DATA16 so they can be accessed from any code. */
4266	BS3_MODE_EXPAND_EXTERN_DATA16(const char, g_szBs3ModeNameShortLower, []);
4267
4268
4269	/**
4270	* Basic CPU detection.
4271	*
4272	* This sets the #g_uBs3CpuDetected global variable to the return value.
4273	*
4274	* @returns BS3CPU_XXX value with the BS3CPU_F_CPUID flag set depending on
4275	* capabilities.
4276	*/
4277	BS3_MODE_PROTO_NOSB(uint8_t, Bs3CpuDetect,(void));
4278
4279	/** @name BS3CPU_XXX - CPU detected by BS3CpuDetect_c16() and friends.
4280	* @{ */
4281	#define BS3CPU_8086 UINT16_C(0x0001) /*< Both 8086 and 8088. /
4282	#define BS3CPU_V20 UINT16_C(0x0002) /*< Both NEC V20, V30 and relatives. /
4283	#define BS3CPU_80186 UINT16_C(0x0003) /*< Both 80186 and 80188. /
4284	#define BS3CPU_80286 UINT16_C(0x0004)
4285	#define BS3CPU_80386 UINT16_C(0x0005)
4286	#define BS3CPU_80486 UINT16_C(0x0006)
4287	#define BS3CPU_Pentium UINT16_C(0x0007)
4288	#define BS3CPU_PPro UINT16_C(0x0008)
4289	#define BS3CPU_PProOrNewer UINT16_C(0x0009)
4290	/** CPU type mask. This is a full byte so it's possible to use byte access
4291	* without and AND'ing to get the type value. */
4292	#define BS3CPU_TYPE_MASK UINT16_C(0x00ff)
4293	/** Flag indicating that the CPUID instruction is supported by the CPU. */
4294	#define BS3CPU_F_CPUID UINT16_C(0x0100)
4295	/** Flag indicating that extend CPUID leaves are available (at least two). */
4296	#define BS3CPU_F_CPUID_EXT_LEAVES UINT16_C(0x0200)
4297	/** Flag indicating that the CPU supports PAE. */
4298	#define BS3CPU_F_PAE UINT16_C(0x0400)
4299	/** Flag indicating that the CPU supports the page size extension (4MB pages). */
4300	#define BS3CPU_F_PSE UINT16_C(0x0800)
4301	/** Flag indicating that the CPU supports long mode. */
4302	#define BS3CPU_F_LONG_MODE UINT16_C(0x1000)
4303	/** Flag indicating that the CPU supports NX. */
4304	#define BS3CPU_F_NX UINT16_C(0x2000)
4305	/** @} */
4306
4307	/** The return value of #Bs3CpuDetect_mmm. (Initial value is BS3CPU_TYPE_MASK.) */
4308	extern uint16_t g_uBs3CpuDetected;
4309
4310	/**
4311	* Call 32-bit prot mode C function.
4312	*
4313	* This switches to 32-bit mode and calls the 32-bit @a fpfnCall C code with @a
4314	* cbParams on the stack, then returns in the original mode. When called in
4315	* real mode, this will switch to PE32.
4316	*
4317	* @returns 32-bit status code if the function returned anything.
4318	* @param fpfnCall Address of the 32-bit C function to call. When
4319	* called from 16-bit code, this is a far real mode
4320	* function pointer, i.e. as fixed up by the linker.
4321	* In 32-bit and 64-bit code, this is a flat address.
4322	* @param cbParams The size of the parameter list, in bytes.
4323	* @param ... The parameters.
4324	* @sa Bs3SwitchFromV86To16BitAndCallC
4325	*
4326	* @remarks WARNING! This probably doesn't work in 64-bit mode yet.
4327	* Only tested for 16-bit real mode.
4328	*/
4329	BS3_MODE_PROTO_STUB(int32_t, Bs3SwitchTo32BitAndCallC,(FPFNBS3FAR fpfnCall, unsigned cbParams, ...));
4330
4331	/**
4332	* Initializes trap handling for the current system.
4333	*
4334	* Calls the appropriate Bs3Trap16Init, Bs3Trap32Init or Bs3Trap64Init function.
4335	*/
4336	BS3_MODE_PROTO_STUB(void, Bs3TrapInit,(void));
4337
4338	/**
4339	* Executes the array of tests in every possibly mode.
4340	*
4341	* @param paEntries The mode sub-test entries.
4342	* @param cEntries The number of sub-test entries.
4343	*/
4344	BS3_MODE_PROTO_NOSB(void, Bs3TestDoModes,(PCBS3TESTMODEENTRY paEntries, size_t cEntries));
4345
4346	/**
4347	* Executes the array of tests in every possibly mode, unified driver.
4348	*
4349	* This requires much less code space than Bs3TestDoModes as there is only one
4350	* instace of each sub-test driver code, instead of 3 (cmn) or 22 (per-mode)
4351	* copies.
4352	*
4353	* @param paEntries The mode sub-test-by-one entries.
4354	* @param cEntries The number of sub-test-by-one entries.
4355	* @param fFlags BS3TESTMODEBYONEENTRY_F_XXX.
4356	*/
4357	BS3_MODE_PROTO_NOSB(void, Bs3TestDoModesByOne,(PCBS3TESTMODEBYONEENTRY paEntries, size_t cEntries, uint32_t fFlags));
4358
4359	/**
4360	* Executes the array of tests in every possibly mode, using the max bit-count
4361	* worker for each.
4362	*
4363	* @param paEntries The mode sub-test entries.
4364	* @param cEntries The number of sub-test entries.
4365	*/
4366	BS3_MODE_PROTO_NOSB(void, Bs3TestDoModesByMax,(PCBS3TESTMODEBYMAXENTRY paEntries, size_t cEntries));
4367
4368	/** @} */
4369
4370
4371	/** @defgroup grp_bs3kit_bios_int15 BIOS - int 15h
4372	* @{ */
4373
4374	/** An INT15E820 data entry. */
4375	typedef struct INT15E820ENTRY
4376	{
4377	uint64_t uBaseAddr;
4378	uint64_t cbRange;
4379	/** Memory type this entry describes, see INT15E820_TYPE_XXX. */
4380	uint32_t uType;
4381	/** Optional. */
4382	uint32_t fAcpi3;
4383	} INT15E820ENTRY;
4384	AssertCompileSize(INT15E820ENTRY,24);
4385
4386
4387	/** @name INT15E820_TYPE_XXX - Memory types returned by int 15h function 0xe820.
4388	* @{ */
4389	#define INT15E820_TYPE_USABLE 1 /*< Usable RAM. /
4390	#define INT15E820_TYPE_RESERVED 2 /*< Reserved by the system, unusable. /
4391	#define INT15E820_TYPE_ACPI_RECLAIMABLE 3 /*< ACPI reclaimable memory, whatever that means. /
4392	#define INT15E820_TYPE_ACPI_NVS 4 /*< ACPI non-volatile storage? /
4393	#define INT15E820_TYPE_BAD 5 /*< Bad memory, unusable. /
4394	/** @} */
4395
4396
4397	/**
4398	* Performs an int 15h function 0xe820 call.
4399	*
4400	* @returns Success indicator.
4401	* @param pEntry The return buffer.
4402	* @param pcbEntry Input: The size of the buffer (min 20 bytes);
4403	* Output: The size of the returned data.
4404	* @param puContinuationValue Where to get and return the continuation value (EBX)
4405	* Set to zero the for the first call. Returned as zero
4406	* after the last entry.
4407	*/
4408	BS3_MODE_PROTO_STUB(bool, Bs3BiosInt15hE820,(INT15E820ENTRY BS3_FAR pEntry, uint32_t BS3_FAR pcbEntry,
4409	uint32_t BS3_FAR *puContinuationValue));
4410
4411	/**
4412	* Performs an int 15h function 0x88 call.
4413	*
4414	* @returns UINT32_MAX on failure, number of KBs above 1MB otherwise.
4415	*/
4416	#if ARCH_BITS != 16 \|\| !defined(BS3_BIOS_INLINE_RM)
4417	BS3_MODE_PROTO_STUB(uint32_t, Bs3BiosInt15h88,(void));
4418	#else
4419	BS3_DECL(uint32_t) Bs3BiosInt15h88(void);
4420	# pragma aux Bs3BiosInt15h88 = \
4421	".286" \
4422	"clc" \
4423	"mov ax, 08800h" \
4424	"int 15h" \
4425	"jc failed" \
4426	"xor dx, dx" \
4427	"jmp done" \
4428	"failed:" \
4429	"xor ax, ax" \
4430	"dec ax" \
4431	"mov dx, ax" \
4432	"done:" \
4433	value [ax dx] \
4434	modify exact [ax bx cx dx es];
4435	#endif
4436
4437	/** @} */
4438
4439
4440	/** @defgroup grp_bs3kit_kbd Keyboard
4441	* @{
4442	*/
4443
4444	/**
4445	* Waits for the keyboard controller to become ready.
4446	*/
4447	BS3_CMN_PROTO_NOSB(void, Bs3KbdWait,(void));
4448
4449	/**
4450	* Sends a read command to the keyboard controller and gets the result.
4451	*
4452	* The caller is responsible for making sure the keyboard controller is ready
4453	* for a command (call #Bs3KbdWait if unsure).
4454	*
4455	* @returns The value read is returned (in al).
4456	* @param bCmd The read command.
4457	*/
4458	BS3_CMN_PROTO_NOSB(uint8_t, Bs3KbdRead,(uint8_t bCmd));
4459
4460	/**
4461	* Sends a write command to the keyboard controller and then sends the data.
4462	*
4463	* The caller is responsible for making sure the keyboard controller is ready
4464	* for a command (call #Bs3KbdWait if unsure).
4465	*
4466	* @param bCmd The write command.
4467	* @param bData The data to write.
4468	*/
4469	BS3_CMN_PROTO_NOSB(void, Bs3KbdWrite,(uint8_t bCmd, uint8_t bData));
4470
4471	/** @} */
4472
4473
4474	/** @defgroup grp_bs3kit_pic PIC
4475	* @{
4476	*/
4477
4478	/**
4479	* Configures the PIC, once only.
4480	*
4481	* Subsequent calls to this function will not do anything.
4482	*
4483	* The PIC will be programmed to use IDT/IVT vectors 0x70 thru 0x7f, auto
4484	* end-of-interrupt, and all IRQs masked. The individual PIC users will have to
4485	* use #Bs3PicUpdateMask unmask their IRQ once they've got all the handlers
4486	* installed.
4487	*
4488	* @param fForcedReInit Force a reinitialization.
4489	*/
4490	BS3_CMN_PROTO_STUB(void, Bs3PicSetup,(bool fForcedReInit));
4491
4492	/**
4493	* Updates the PIC masks.
4494	*
4495	* @returns The new mask - master in low, slave in high byte.
4496	* @param fAndMask Things to keep as-is. Master in low, slave in high byte.
4497	* @param fOrMask Things to start masking. Ditto wrt bytes.
4498	*/
4499	BS3_CMN_PROTO_STUB(uint16_t, Bs3PicUpdateMask,(uint16_t fAndMask, uint16_t fOrMask));
4500
4501	/**
4502	* Disables all IRQs on the PIC.
4503	*/
4504	BS3_CMN_PROTO_STUB(void, Bs3PicMaskAll,(void));
4505
4506	/** @} */
4507
4508
4509	/** @defgroup grp_bs3kit_pit PIT
4510	* @{
4511	*/
4512
4513	/**
4514	* Sets up the PIT for periodic callback.
4515	*
4516	* @param cHzDesired The desired Hz. Zero means max interval length
4517	* (18.2Hz). Plase check the various PIT globals for
4518	* the actual interval length.
4519	*/
4520	BS3_CMN_PROTO_STUB(void, Bs3PitSetupAndEnablePeriodTimer,(uint16_t cHzDesired));
4521
4522	/**
4523	* Disables the PIT if active.
4524	*/
4525	BS3_CMN_PROTO_STUB(void, Bs3PitDisable,(void));
4526
4527	/** The RIP/EIP value of where the PIT IRQ handle will return to. */
4528	extern BS3REG volatile g_Bs3PitIrqRip;
4529	/** Nanoseconds (approx) since last the PIT timer was started. */
4530	extern uint64_t volatile g_cBs3PitNs;
4531	/** Milliseconds seconds (very approx) since last the PIT timer was started. */
4532	extern uint64_t volatile g_cBs3PitMs;
4533	/** Number of ticks since last the PIT timer was started. */
4534	extern uint32_t volatile g_cBs3PitTicks;
4535	/** The current interval in nanoseconds.
4536	* This is 0 if not yet started (cleared by Bs3PitDisable). */
4537	extern uint32_t g_cBs3PitIntervalNs;
4538	/** The current interval in milliseconds (approximately).
4539	* This is 0 if not yet started (cleared by Bs3PitDisable). */
4540	extern uint16_t g_cBs3PitIntervalMs;
4541	/** The current PIT frequency (approximately).
4542	* 0 if not yet started (cleared by Bs3PitDisable; used for checking the
4543	* state internally). */
4544	extern uint16_t volatile g_cBs3PitIntervalHz;
4545
4546	/** @} */
4547
4548
4549	/** @} */
4550
4551	RT_C_DECLS_END
4552
4553
4554	/*
4555	* Include default function symbol mangling.
4556	*/
4557	#include "bs3kit-mangling-code.h"
4558
4559	/*
4560	* Change 16-bit text segment if requested.
4561	*/
4562	#if defined(BS3_USE_ALT_16BIT_TEXT_SEG) && ARCH_BITS == 16 && !defined(BS3_DONT_CHANGE_TEXT_SEG)
4563	# if (defined(BS3_USE_RM_TEXT_SEG) + defined(BS3_USE_X0_TEXT_SEG) + defined(BS3_USE_X1_TEXT_SEG)) != 1
4564	# error "Cannot set more than one alternative 16-bit text segment!"
4565	# elif defined(BS3_USE_RM_TEXT_SEG)
4566	# pragma code_seg("BS3RMTEXT16", "BS3CLASS16RMCODE")
4567	# elif defined(BS3_USE_X0_TEXT_SEG)
4568	# pragma code_seg("BS3X0TEXT16", "BS3CLASS16X0CODE")
4569	# elif defined(BS3_USE_X1_TEXT_SEG)
4570	# pragma code_seg("BS3X1TEXT16", "BS3CLASS16X1CODE")
4571	# else
4572	# error "Huh? Which alternative text segment did you want again?"
4573	# endif
4574	#endif
4575
4576	#endif /* !BS3KIT_INCLUDED_bs3kit_h */
4577

Note: See TracBrowser for help on using the repository browser.

source: vbox/trunk/src/VBox/ValidationKit/bootsectors/bs3kit/bs3kit.h@ 102127

Download in other formats: