Win64/AMD64 API: what changed

Revision 1 to 2. Removed lines have a minus sign; added lines have a plus sign.

Old	New		Line
1	1		(Windows only)
2	2
3	3		# Old Information
4	4
5	5		As far as I know, there is no offical document yet decribing the win64/amd64 api so the follow information is collected from several sources.
6	6
7	7		Begin in this link <http://msdn.microsoft.com/library/default.asp?url=/library/en-us/win64/win64/getting_ready_for_64_bit_windows.asp>
8	8
9	9		## Data type sizes
10	10
11	11		Basic information at <http://msdn.microsoft.com/library/default.asp?url=/library/en-us/win64/win64/the_new_data_types.asp>
12	12
13	13		# Notes on Win64 for AMD calling conventions
14	14
15	15		## About documentation
16	16
17	17		Documentation about Windows x86-64 calling convention does exist. It can be found online on msdn: <http://msdn.microsoft.com/library/default.asp?url=/library/en-us/Kernel_d/hh/Kernel_d/64bitAMD_6ec00b51-bf75-41bf-8635-caa8653c8bd9.xml.asp>
18	18
19	19		This documentation says that it's preliminary and subject to change, and is dated February 2005.
20	20
21	21		However, there is a SWConventions.doc file in Microsoft Platform SDK, dated May 2005. It's a more recent version of what is published in URL above (in fact there are some important differences). In the file the only warning about "preliminary documentation" is found in "hot patchability" chapter. Since win64 has shipped in the USA I think that this documentation can be assumed as definitive. This file is located in the same directory of binaries for amd64 (cl, ml64, link and so on). I think that it cannot be redistributed (license says that one can copy it for its personal reference, but doesn't say anything about redistribution of the file). That file is the reference upon documentation in this wiki is based.
22	22
23	23		## Preliminary notes:
24	24
25	25		rvas are still 32 bit: maximum file size for an exe file is 2 gb, so there is no need to use larger address space.
26	26
27	27		## Some definitions:
28	28
29	29		leaf function: a function that doesn't call any function, neither allocates stack space by itself. This function doesn't have a frame pointer.
30	30
31	31		frame function: a function that has a frame pointer.
32	32
33	33		## Calling conventions in Win64 for AMD
34	34
35	35		There is only one calling convention. Actually Microsoft include files are shared among Windows 32 bit and 64 bit. Functions modifiers like stdcall, cdecl and fastcall are ignored on 64bit windows since they use an unique calling convention.
36	36
37	37		### Parameter passing
38	38
39	39		The first 4 parameters are passed on registers. Integer parameters (from 1 to 8 bytes long) are passed in RCX, RDX, R8 and R9 registers, where the first parameter (the leftmost) is passed in RCX and the fourth in R9. Floating point parameters are passed in XMM0L, XMM1L, XMM2L and XMM3L. Parameters beyond the fourth are passed on stack. Note: If there are both integer and floating point parameters, use of n-th register is mutually exclusive; if the second parameter is a floating point number and the third is integer, the second one goes in XMM1L and the third in R8. Example:
40	40
41		-	~~`function(int1,real1,int2,real2,int3,real3)`~~
	41	+	``` pascal
	42	+	function(int1,real1,int2,real2,int3,real3)
	43	+	```
42	44
43	45		means:
44	46
45		-	~~`push real3 // passed on stack`\~~
46		-	~~`push int3 // passed on stack`\~~
47		-	~~`XMM3L=real2 `\~~
48		-	~~`R8=int2`\~~
49		-	~~`XMM1L=real1`\~~
50		-	~~`RCX=int1`~~
	47	+	```text
	48	+	push real3 // passed on stack
	49	+	push int3 // passed on stack
	50	+	XMM3L=real2
	51	+	R8=int2
	52	+	XMM1L=real1
	53	+	RCX=int1
	54	+	```
51	55
52	56		Actually cl doesn't use real pushes to put arguments on stack, but we'll talk about it later.
53	57
54	58		Parameters greater than 8 bytes are passed by reference (so it's caller duty to allocate space for a copy of the parameter and then pass a pointer to it).
55	59
56	60		Some notes for vararg/unprototyped functions: if there are floating point arguments, they must be passed both in integer register and in floating point register, without conversion, so that the function can retrieve the parameter if it expected a integer parameter (in other words: if an unprototyped function expects an integer parameter as second parameter it would look in RDX. Since it's not prototyped we don't know it, and if we pass a floating point argument as second parameter we end up with the value in XMM1L and garbage in RDX: so we copy the value in both registers to avoid problems.) If the argument is beyond the fourth there is no special-handling, since callee will look at the same stack location if it expects an integer parameter or a floating point parameter.
57	61
58	62		### Return values
59	63
60	64		Integer values which have length between 1 and 8 bytes are returned in RAX. Floating point values, __m128, __m128i or __m128d values are returned in XMM0.
61	65
62	66		If return value is too big to fit in one of these registers, it's caller duty to allocate stack space before calling the function, and to pass a pointer to this location as first parameter (so there are now only three registers to store other parameters).
63	67
64	68		### Volatile and nonvolatile registers
65	69
66	70		In addition to registers used to pass parameters, RAX, R10, R11, XMM4 and XMM5 aren't preserved by callee and should be saved by the caller if needed (R10 and R11 are used for syscall/sysret, don't know about XMM4 and XMM5). Other registers must be saved by callee if used, even if a special treatment is reserved to x87 and mmx registers.
67	71
68	72		#### About x87 and mmx registers
69	73
70	74		x87 and mmx registers aren't used: all floating points calculations are made in XMM* registers. Although x87 and mmx registers are guaranteed to be preserved across context switching, this is not true for functions calls. Microsoft says that if you use x87 registers you should consider them as volatile registers. There's nothing about mmx registers apart the context-switching thing, so I think that even mmx registers have to be considered volatile.
71	75
72	76		#### x87 and MMX control registers
73	77
74	78		x87 The x87 control word is considered nonvolatile and must be preserved by the callee. When program is started, FPCSR is set this way:
75	79
76		-	~~` FPCSR[0:6] : Exception masks all 1's (all exceptions masked)`\~~
77		-	~~` FPCSR[7] : Reserved - 0`\~~
78		-	~~` FPCSR[8:9] : Precision Control - 10B (double precision)`\~~
79		-	~~` FPCSR[10:11] : Rounding control - 0 (round to nearest)`\~~
80		-	~~` FPCSR[12] : Infinity control - 0 (not used)`~~
	80	+	```text
	81	+	FPCSR[0:6] : Exception masks all 1's (all exceptions masked)
	82	+	FPCSR[7] : Reserved - 0
	83	+	FPCSR[8:9] : Precision Control - 10B (double precision)
	84	+	FPCSR[10:11] : Rounding control - 0 (round to nearest)
	85	+	FPCSR[12] : Infinity control - 0 (not used)
	86	+	```
81	87
82	88		If a function modifies this register it should then reset the register to the original value before returning. It should do the same thing when calling another function (however, if there is a function whose purpose is to modify this register this pass can be skipped. It can be skipped even if it's known that called function doesn't rely on that register). MMX MMX control register bits are considered volatile from 0 through 5, and nonvolatile from 6 and beyond. Same considerations made for FPCSR are valid for nonvolatile part of MXCSR. This is MCXSR setting when program starts:
83	89
84		-	~~` MXCSR[6] : Denormals are zeros - 0`\~~
85		-	~~` MXCSR[7:12] : Exception masks all 1's (all exceptions masked)`\~~
86		-	~~` MXCSR[13:14] : Rounding control - 0 (round to nearest)`\~~
87		-	~~` MXCSR[15] : Flush to zero for masked underflow - 0 (off)`~~
	90	+	```text
	91	+	MXCSR[6] : Denormals are zeros - 0
	92	+	MXCSR[7:12] : Exception masks all 1's (all exceptions masked)
	93	+	MXCSR[13:14] : Rounding control - 0 (round to nearest)
	94	+	MXCSR[15] : Flush to zero for masked underflow - 0 (off)
	95	+	```
88	96
89	97		### Stack configuration
90	98
91	99		#### Shadow space
92	100
93	101		There is the concept of "shadow space" when calling a function. The caller must always allocate a fixed space of 32 bytes (4*8 bytes) on stack before calling a function: this is called shadow space, and it's used by callee to store arguments that are passed on registers if the callee needs these arguments to be in memory (after storing four register arguments to shadow area, all arguments appear as contiguous array on stack, making it easy to implement functions like printf()). The register parameters are also typically stored into shadow space when generating debugging code, providing the debugger a consistent location where to look for parameter values. Microsoft cl has an option to force storing register parameters to shadow space, which is enabled for debug builds. This stack space must always be allocated, even if function has less than 4 parameters. This space must be adjacent to callee return address: stack pointer must point to the end of this space before calling the function. So if more than 4 parameters are passed, parameters beyond 4 are at higher addresses, then there is shadow space on top of the stack.
94	102
95	103		#### Stack alignment
96	104
97	105		Stack pointer (RSP) must be aligned on multiples of 16 bytes when calling another function. Note: when called functions begins execution, stack isn't aligned in 16-bytes boundary: in fact it is aligned before call instruction, then call instruction places return address on stack (which is 8 bytes long) making stack unaligned. Therefore, in leaf functions the stack stays unaligned (according to the definition of leaf functions, any change to the stack pointer makes the function non-leaf).
98	106
99	107		#### Frame pointer
100	108
101	109		In most cases, Win64 API uses the fixed stack, i.e. value of the stack pointer is changed only in prolog and epilog, not in the function body. This removes the need of having a separate frame pointer. An exclusion to this rule is dynamic stack allocation using alloca() function. Also, a frame pointer can be set pointing into the middle of local variables area, so local variables are addressed at both positive and negative offsets from the FP. Since offsets values below 128 are encoded using shorter instructions, this allows generating smaller code. The frame pointer is not restricted to be RBP, it can be any non-volatile register.
102	110
103	111		#### Parts of function: prolog, body and epilog
104	112
105	113		To make work of exception handler easy, functions are considered "splitted" in three parts: prolog, body of function and epilog. Prolog is described using unwind data, and the epilog has a standard configuration so that exception handler can recognize them properly.
106	114
107	115		##### Function prolog
108	116
109	117		Prolog is the very first part of function. Generally, function prolog does this work:
110	118
111	119		- Copies parameters from registers to shadow space
112	120		- Pushes registers to be preserved on stack
113	121		- Allocates room on stack for local variables
114	122		- Sets a frame pointer (so frame pointer is set AFTER local variables!) if needed
115	123		- Allocates space needed to store volatile registers that must be preserved in function calls
116	124		- Allocates shadow space for called functions.
117	125
118	126		This is what microsoft cl does, although this should not be seen as a restriction, since you can chose other methods. If in the body of function dynamic allocation of memory on stack is needed, no problem: memory is allocated but block stays between frame pointer and rsp-(size of space needed for volatile registers+size of shadow space for called functions), so that shadow space for called functions it's always on top of the stack. This layout might help:
119	127
120		-	~~` --------------- --`\~~
121		-	~~`\| R9 \| \|`\~~
122		-	~~` --------------- \|`\~~
123		-	~~`\| R8 \| \|`\~~
124		-	~~` --------------- \|Shadow space for this function, allocated by caller`\~~
125		-	~~`\| RDX \| \|`\~~
126		-	~~` --------------- \|`\~~
127		-	~~`\| RCX \| \|`\~~
128		-	~~` --------------- --`\~~
129		-	~~`\| Return address\|`\~~
130		-	~~` ---------------`\~~
131		-	~~`\| \|`\~~
132		-	~~`\| \| Local variables of this function`\~~
133		-	~~`\| \|`\~~
134		-	~~`\| \|`\~~
135		-	~~` ---------------`\~~
136		-	~~`\| Frame Pointer \| Optional`\~~
137		-	~~` ---------------`\~~
138		-	~~`\| \|`\~~
139		-	~~`\| \| Memory used for dynamic allocation`\~~
140		-	~~`\| \|`\~~
141		-	~~`\| \|`\~~
142		-	~~` ---------------`\~~
143		-	~~`\| \|`\~~
144		-	~~`\| \| Memory used to save registers that may be modified by callee`\~~
145		-	~~`\| \|`\~~
146		-	~~`\| \|`\~~
147		-	~~` --------------- --`\~~
148		-	~~`\| R9 \| \|`\~~
149		-	~~` --------------- \|`\~~
150		-	~~`\| R8 \| \|`\~~
151		-	~~` --------------- \|Shadow space for callee, allocated by this function`\~~
152		-	~~`\| RDX \| \|`\~~
153		-	~~` --------------- \|`\~~
154		-	~~`\| RCX \| \|`\~~
155		-	~~` --------------- --`~~
	128	+	``` pascal
	129	+	--------------- --
	130	+	\| R9 \| \|
	131	+	--------------- \|
	132	+	\| R8 \| \|
	133	+	--------------- \|Shadow space for this function, allocated by caller
	134	+	\| RDX \| \|
	135	+	--------------- \|
	136	+	\| RCX \| \|
	137	+	--------------- --
	138	+	\| Return address\|
	139	+	---------------
	140	+	\| \|
	141	+	\| \| Local variables of this function
	142	+	\| \|
	143	+	\| \|
	144	+	---------------
	145	+	\| Frame Pointer \| Optional
	146	+	---------------
	147	+	\| \|
	148	+	\| \| Memory used for dynamic allocation
	149	+	\| \|
	150	+	\| \|
	151	+	---------------
	152	+	\| \|
	153	+	\| \| Memory used to save registers that may be modified by callee
	154	+	\| \|
	155	+	\| \|
	156	+	--------------- --
	157	+	\| R9 \| \|
	158	+	--------------- \|
	159	+	\| R8 \| \|
	160	+	--------------- \|Shadow space for callee, allocated by this function
	161	+	\| RDX \| \|
	162	+	--------------- \|
	163	+	\| RCX \| \|
	164	+	--------------- --
	165	+	```
156	166
157	167		Code example:
158	168
159		-	~~`int func2(int i1, int i2, int i3)`\~~
160		-	~~`{`\~~
161		-	~~` int lets_waste_stack_space = 53;`\~~
162		-	~~` return (i1 + i2 + i3);`\~~
163		-	~~`}`\~~
	169	+	```text
	170	+	int func2(int i1, int i2, int i3)
	171	+	{
	172	+	int lets_waste_stack_space = 53;
	173	+	return (i1 + i2 + i3);
	174	+	}
164	175
165		-	~~`int func1(int i1, int i2)`\~~
166		-	~~`{`\~~
167		-	~~` int another_local_variable = 51;`\~~
168		-	~~` void * buf = alloca(100);`\~~
169		-	~~` return (func2(i1, i2, 3));`\~~
170		-	~~`}`\~~
	176	+	int func1(int i1, int i2)
	177	+	{
	178	+	int another_local_variable = 51;
	179	+	void * buf = alloca(100);
	180	+	return (func2(i1, i2, 3));
	181	+	}
171	182
172		-	~~`int main()`\~~
173		-	~~`{`\~~
174		-	~~` int a_local_variable = 50;`\~~
175		-	~~` func1(1,2);`\~~
176		-	~~` return(0);`\~~
177		-	~~`}`~~
	183	+	int main()
	184	+	{
	185	+	int a_local_variable = 50;
	186	+	func1(1,2);
	187	+	return(0);
	188	+	}
	189	+	```
178	190
179	191		This is memory layout in func1:
180	192
181		-	~~`xxxxxxxx`\~~
182		-	~~`xxxxxxxx`\~~
183		-	~~`i2 = rdx`\~~
184		-	~~`i1 = rcx`\~~
185		-	~~`retaddr`\~~
186		-	~~`old rbp \| local variables`\~~
187		-	~~`buf \|`\~~
188		-	~~`another_local_variable <= rbp \|`\~~
189		-	~~`xxxxxxxx \| shadow for \| room for buf`\~~
190		-	~~`xxxxxxxx \| func2 \| dinamically`\~~
191		-	~~`xxxxxxxx \| before \| allocated`\~~
192		-	~~`xxxxxxxx <= rsp1 \| alloca \|`\~~
193		-	~~`xxxxxxxx \|`\~~
194		-	~~`xxxxxxxx \|`\~~
195		-	~~`xxxxxxxx \|`\~~
196		-	~~`xxxxxxxx \|`\~~
197		-	~~`xxxxxxxx \|`\~~
198		-	~~`xxxxxxxx \|`\~~
199		-	~~`xxxxxxxx \|`\~~
200		-	~~`xxxxxxxx \|`\~~
201		-	~~`xxxxxxxx \|`\~~
202		-	~~`xxxxxxxx <= buf__________________\|`\~~
203		-	~~`xxxxxxxx \| shadow for`\~~
204		-	~~`xxxxxxxx \| func2`\~~
205		-	~~`xxxxxxxx \|`\~~
206		-	~~`xxxxxxxx <= rsp2______________________________ \|`~~
	193	+	```text
	194	+	xxxxxxxx
	195	+	xxxxxxxx
	196	+	i2 = rdx
	197	+	i1 = rcx
	198	+	retaddr
	199	+	old rbp \| local variables
	200	+	buf \|
	201	+	another_local_variable <= rbp \|
	202	+	xxxxxxxx \| shadow for \| room for buf
	203	+	xxxxxxxx \| func2 \| dinamically
	204	+	xxxxxxxx \| before \| allocated
	205	+	xxxxxxxx <= rsp1 \| alloca \|
	206	+	xxxxxxxx \|
	207	+	xxxxxxxx \|
	208	+	xxxxxxxx \|
	209	+	xxxxxxxx \|
	210	+	xxxxxxxx \|
	211	+	xxxxxxxx \|
	212	+	xxxxxxxx \|
	213	+	xxxxxxxx \|
	214	+	xxxxxxxx \|
	215	+	xxxxxxxx <= buf__________________\|
	216	+	xxxxxxxx \| shadow for
	217	+	xxxxxxxx \| func2
	218	+	xxxxxxxx \|
	219	+	xxxxxxxx <= rsp2______________________________ \|
	220	+	```
207	221
208	222		Main allocates shadow space of func1: 32 bytes even if only 2 parameters are used. It puts 1 in rcx and 2 in rdx, then call instruction places return address on stack. This is what func1 does in its prolog:
209	223
210	224		- Copies parameters from registers to shadow space:
211	225		- Copies rdx in rsp+16 and rcx in rsp+8
212	226		- Pushes registers to be preserved on stack:
213	227		- Pushes ebp.
214	228		- Allocates room on stack for local variables:
215	229		- Decrements rsp by 16 to reserve room for buf and another_local_variable
216	230		- Sets a frame pointer:
217	231		- rbp now points to rsp (that is, to another_local_variable address)
218	232		- Allocates space needed to store volatile registers that must be preserved in function calls:
219	233		- no space needed
220	234		- Allocates shadow space for called functions:
221	235		- Decrements rsp by 32. rsp position is rsp1 in previous scheme.
222	236
223	237		End of prolog.
224	238
225	239		In function body, alloca is called: rsp is decremented by 112 (alloca allocates memory aligned on 16-bytes boundary). rsp position is rsp2 in schema now. Buf doesn't point to same location of rsp since shadow space for callee must stay on top of the stack: instead it points 32 bytes before rsp, so that buf stays between rbp+8 and rsp-32. When func2 is called, it finds its shadow space where it should be (adjacent to return address).
226	240
227	241		Note that this is modus operandi of microsoft cl, but it's perfectly legal to use other strategies (this is even remarked by microsoft). It is perfectly legal to push registers to be preserved and to allocate shadow space before a function call, and then release memory after the call.
228	242
229	243		##### Function epilog
230	244
231	245		Epilog is the last part of function. Function epilog does this work:
232	246
233	247		- Release stack space
234	248		- Pops registers that were saved
235	249		- returns
236	250
237	251		It should not do other things: function result should be set before epilog. Microsoft suggests that for functions without frame pointer stack is released adding a constant value to rsp. For function with frame pointer this can be accomplished in two ways: adding a costant to rsp or loading rsp with rbp address. This restrictions are needed so that exception handler can easily detect function epilog.
238	252
239	253		This is ML64 assembly listing for func1 in previous example; Comments and exception-related stuff has been removed. You can see that cl uses a more optimized approach: instead of reserve space for local variables, set frame pointer and reserve space for shadow it reserves space in an unique operation and then sets frame pointer to the right value.
240	254
241		-	~~`PUBLIC func1`\~~
242		-	~~`_TEXT SEGMENT`\~~
243		-	~~`func1 PROC NEAR`\~~
244		-	~~` mov DWORD PTR [rsp+16], edx ; save second parameter`\~~
245		-	~~` mov DWORD PTR [rsp+8], ecx ; save first parameter`\~~
246		-	~~` push rbp ; save old rbp value`\~~
247		-	~~` sub rsp, 48 ; room for local vars + shadow space for called function`\~~
248		-	~~` lea rbp, QWORD PTR [rsp+32] ; sets frame pointer to the end of local variables block.`\~~
249		-	~~` ; end of prolog`\~~
250		-	~~` `\~~
251		-	~~` mov DWORD PTR [rbp], 51 ; another_local_variable = 51;`\~~
252		-	~~` `\~~
253		-	~~` mov eax, 112 ; make room for buf`\~~
254		-	~~` sub rsp, rax`\~~
255		-	~~` lea rax, QWORD PTR [rsp+32] ;`\~~
256		-	~~` mov ecx, DWORD PTR [rax] ; buf now points to rsp+32. Shadow space lies between`\~~
257		-	~~` mov QWORD PTR 8[rbp], rax ; rsp+32 and rsp.`\~~
258		-	~~` `\~~
259		-	~~` mov r8d, 3 ; third parameter of func2: 3`\~~
260		-	~~` mov edx, DWORD PTR 40[rbp] ; second parameter: i2`\~~
261		-	~~` mov ecx, DWORD PTR 32[rbp] ; first parameter: i1`\~~
262		-	~~` call func2 ; call to func2`\~~
263		-	~~` `\~~
264		-	~~` ; here starts epilog`\~~
265		-	~~` lea rsp, QWORD PTR [rbp+16] ; frame function, use lea to release stack`\~~
266		-	~~` pop rbp ; pop ebp register that was saved`\~~
267		-	~~` ret 0 ; return`\~~
268		-	~~`func1 ENDP`\~~
269		-	~~`_TEXT ENDS`~~
	255	+	``` pascal
	256	+	PUBLIC func1
	257	+	_TEXT SEGMENT
	258	+	func1 PROC NEAR
	259	+	mov DWORD PTR [rsp+16], edx ; save second parameter
	260	+	mov DWORD PTR [rsp+8], ecx ; save first parameter
	261	+	push rbp ; save old rbp value
	262	+	sub rsp, 48 ; room for local vars + shadow space for called function
	263	+	lea rbp, QWORD PTR [rsp+32] ; sets frame pointer to the end of local variables block.
	264	+	; end of prolog
	265	+
	266	+	mov DWORD PTR [rbp], 51 ; another_local_variable = 51;
	267	+
	268	+	mov eax, 112 ; make room for buf
	269	+	sub rsp, rax
	270	+	lea rax, QWORD PTR [rsp+32] ;
	271	+	mov ecx, DWORD PTR [rax] ; buf now points to rsp+32. Shadow space lies between
	272	+	mov QWORD PTR 8[rbp], rax ; rsp+32 and rsp.
	273	+
	274	+	mov r8d, 3 ; third parameter of func2: 3
	275	+	mov edx, DWORD PTR 40[rbp] ; second parameter: i2
	276	+	mov ecx, DWORD PTR 32[rbp] ; first parameter: i1
	277	+	call func2 ; call to func2
	278	+
	279	+	; here starts epilog
	280	+	lea rsp, QWORD PTR [rbp+16] ; frame function, use lea to release stack
	281	+	pop rbp ; pop ebp register that was saved
	282	+	ret 0 ; return
	283	+	func1 ENDP
	284	+	_TEXT ENDS
	285	+	```
270	286
271	287		## Data alignment
272	288
273	289		For performance reasons, data should be aligned to its natural alignment. Arrays should be aligned on their elements' natural alignment. Fields inside structures should be aligned on their natural alignment, and structure itself should be aligned according to alignment of its wider field (so if a record is made of a byte and a qword, record is aligned on 8-byte boundary, byte starts at record+0 and qword at record+8).
274	290
275	291		Functions must be aligned on 4 byte multiples, but 16-byte alignment is encouraged for performance reasons.
276	292
277	293		## Constants
278	294
279	295		Enums and integer constants are treated as 32-bit integers. Bitfields can't be larger than 64 bits.
280	296
281	297		## Exception
282	298
283	299		Win64 doesn't support the old i386 way of doing exception handling using fs:(0) as a linked list of exception handlers. Instead, it uses table based exception handling. However, FPC uses it's own code to unwind exceptions so it needs a way to intercept exceptions before the table based exception handling jumps in. This can be done using vectored exception handling which is new in Windows XP: <http://windowssdk.msdn.microsoft.com/library/default.asp?url=/library/en-us/Debug/base/using_a_vectored_exception_handler.asp>
284	300
285	301		Don't get fooled by the comment at the top of the article, it only means that the code below uses fields in the context record which aren't available in win64 (eip vs. rip) so adapting this, the code works.
286	302
287	303		## Debugger support
288	304
289	305		## Differences between PE and PE+ exe format
290	306
291	307		PE32+ Magic number (in optional header) is 0x20b while PE32 is 0x10b
292	308
293	309		There is no BaseOfData field in Standard Fields of Optional Header
294	310
295	311		Windows Nt Specific Fields (Optional Header): ImageBase, SizeOfStackReserve, SizeOfStackCommit, SizeOfHeapReserve, SizeOfHeapCommit are 8 bytes long instead of 4
296	312
297	313		Import Lookup Table entries are 64 bits long instead of 32. Bit 63 is Ordinal/Name flag, bits 62 through 0 are Ordinal Number or Hint/Name Table RVA when Ordinal/Name flag is 1 or 0 respectively
298	314
299	315		Import Address Table has same structure as Import Lookup Table
300	316
301	317		TLS Directory Raw Data Start VA, Raw Data End VA, Address of Index, Address of Callbacks are 8 bytes long instead of 4.
302	318
303	319		## Things that must be done on FreePascal
304	320
305	321		First of all: I'm not a fpc developer nor I know fpc internals (I only have some ideas of what files do what thing) so I might be wrong :P It has been said that it's useless to make a win64 port before gcc has been ported, since fpc relies on gas, ld and gdb. But maybe something can start already, so that fpc is already "one step forward" when gcc arrives on win64.
306	322
307	323		### Calling convention
308	324
309	325		First of all, a new calling convention is required. Here there are two choices:
310	326
311	327		- Make a brand new calling convention (win64amd?)
312	328		- Make cdecl, stdcall and safecall as "aliases" to this new calling convention on x86_64-win64
313	329
314	330		Second choice is microsoft choice: since microsoft c compiler considers these conventions all the same thing, logical consequence is that every other c compiler will use this convention in the future. Old calling conventions have no meaning in win64.
315	331
316	332		First choice can be used if there is the possibility that some c compiler uses these conventions even on win64. This means that freepascal headers for windows apis should be rearranged: on i386 there should be a
317	333
318		-	~~`{$calling stdcall}`~~
	334	+	```text
	335	+	{$calling stdcall}
	336	+	```
319	337
320	338		while on win64 for amd there should be a
321	339
322		-	~~`{$calling win64amd}`~~
	340	+	```text
	341	+	{$calling win64amd}
	342	+	```
323	343
324	344		and parts where calling convention is directly specified as function modifiers should be carefully modified/moved to inc files.
325	345
326	346		If second option is chosed it could be useful to temporary set this name to "win64amd" so that it can be tested and debugged on linux-x86_64, where we have gdb (making functions with win64amd modifier and calling them in pascal source files, and test and debug the calling convention). When everything is ok it will be an alias to cdecl, stdcall and safecall on win64 for amd and name will be removed.
327	347
328	348		A function that is declared to use this convention should do these things:
329	349
330	350		- if RCX, RDX, R8, R9, XMM0, XMM1, XMM2, XMM3 are used, their value should be saved in shadow space
331	351		- other nonvolatile registers, if used, should be pushed on stack. These registers are R12 through R15, RDI, RSI, RBX, XMM6 through XMM15
332	352		- MXCSR and FPCSR, if used, should be pushed on stack.
333	353
334	354		A function that call a function that uses this convention should do these things:
335	355
336	356		- Save volatile registers, if used. These are RCX, RDX, R8, R9, XMM0, XMM1, XMM2, XMM3, RAX, R10, R11, XMM4, XMM5.
337	357		- Save x87 and MMX registers, if used.
338	358		- If MXCSR and FPCSR have been modified, their original value should be restored.
339	359		- Push parameters beyond the fourth on stack and align stack on 16-byte boundary if needed. Stack must be padded before pushing parameters according to current stack alignment and number of parameter beyond fourth, so that when last parameter that must be on stack is pushed, stack is 16 byte aligned.
340	360		- Put parameters 1..4 on registers.
341	361		- Allocate 32 bytes on stack for shadow space of callee.
342	362
343	363		### Output format
344	364
345	365		Okay, there is no gas for win64. Since rtl and windows api should be adjusted, a temporary way to start working on it could be to use masm output and compile with ml64. There is a masm writer, and it looks like it has been upgraded (if not upgraded, something has started to move) to handle ml64 syntax too. While this is a good thing, since it's good to have masm output option even if gas would be available, it can be seen as a useless effort. So, binary writer could be improved to handle x86_64 as well. x86_64 is i386 with larger pointers, a couple of instruction were added and some removed: it should be easy to adapt i386 binary writer so that it can write x86_64 code too. Another good thing is that this can be tested and debugged under linux for x86_64, and this platform would benefit from binary writer too. There is the PE+ coff format to implement, but it's not very different to PE coff: maybe differences will be written in this wiki too.
346	366
347	367		### Adapt rtl
348	368
349	369		Having binary writer and calling convention, link can be performed with microsoft link until binutils are ported to win64: we could start adapting windows rtl.
350	370
351	371		Of course, debugging support will still be missed, and I think that adding support for another debugger like windbg should be a big and useless effort, but while gcc isn't available for win64 freepascal could be almost-ready and win64 could be considered an experimental platform, not ready yet to be included to the official ones.
352	372
353	373		---
354	374		From the Free Pascal wiki, page "Win64/AMD64 API", as it stood on 2015-01-06 after a change by Jwdietrich, out of the wiki's dump of 2024-05-26. Copyright stays with the author who wrote it, according to the old wiki's [[Licensing]] page. If you have concerns about this material, [message the admin](/wiki-contact).
355	375		Category: Assembler
356	376		Category: Windows

Back to history