bs3kit.h@ 93115

Last change on this file since 93115 was 93115, checked in by vboxsync, 3 years ago
scm --update-copyright-year
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 166.4 KB

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

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

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

Download in other formats: