• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1[/
2          Copyright Oliver Kowalke 2014.
3 Distributed under the Boost Software License, Version 1.0.
4    (See accompanying file LICENSE_1_0.txt or copy at
5          http://www.boost.org/LICENSE_1_0.txt
6]
7
8[section:rationale Rationale]
9
10[heading No inline-assembler]
11
12Some newer compiler (for instance MSVC 10 for x86_64 and itanium) do not
13support inline assembler.
14[footnote [@http://msdn.microsoft.com/en-us/library/4ks26t93.aspx MSDN article
15'Inline Assembler']].
16Inlined assembler generates code bloating which is not welcome on embedded
17systems.
18
19
20[heading fcontext_t]
21
22__boost_context__ provides the low level API fcontext_t which is
23implemented in assembler to provide context swapping operations.
24fcontext_t is the part to port to new platforms.
25
26[note Context switches do not preserve the signal mask on UNIX systems.]
27
28__fcontext__ is an opaque pointer.
29
30
31
32[section Other APIs ]
33
34[heading setjmp()/longjmp()]
35
36C99 defines `setjmp()`/`longjmp()` to provide non-local jumps but it does not
37require that ['longjmp()] preserves the current stack frame. Therefore, jumping
38into a function which was exited via a call to ['longjmp()] is undefined
39[footnote ISO/IEC 9899:1999, 2005, 7.13.2.1:2].
40
41
42[#ucontext]
43[heading ucontext_t]
44
45Since POSIX.1-2004 `ucontext_t` is deprecated and was removed in POSIX.1-2008!
46The function signature of `makecontext()` is:
47
48    void makecontext(ucontext_t *ucp, void (*func)(), int argc, ...);
49
50The third argument of `makecontext()` specifies the number of integer arguments
51that follow which will require function pointer cast if `func` will accept those
52arguments which is undefined in C99
53[footnote ISO/IEC 9899:1999, 2005, J.2].
54
55The arguments in the var-arg list are required to be integers, passing pointers
56in var-arg list is not guaranteed to work, especially it will fail for
57architectures where pointers are larger than integers.
58
59`ucontext_t` preserves signal mask between context switches which involves system
60calls consuming a lot of CPU cycles (ucontext_t is slower; a context switch
61takes [link performance ['two magnitutes of order more CPU cycles]] more than
62__fcontext__).
63
64
65[heading Windows fibers]
66
67A drawback of Windows Fiber API is that `CreateFiber()` does not accept a
68pointer to user allocated stack space preventing the reuse of stacks for other
69context instances. Because the Windows Fiber API requires to call
70`ConvertThreadToFiber()` if `SwitchFiber()` is called for a thread which has not
71been converted to a fiber. For the same reason `ConvertFiberToThread()`
72must be called after return from `SwitchFiber()` if the thread was forced to be
73converted to a fiber before (which is inefficient).
74
75        if ( ! is_a_fiber() )
76        {
77            ConvertThreadToFiber( 0);
78            SwitchToFiber( ctx);
79            ConvertFiberToThread();
80        }
81
82If the condition `_WIN32_WINNT >= _WIN32_WINNT_VISTA` is met function
83`IsThreadAFiber()` is provided in order to detect if the current thread was
84already converted. Unfortunately Windows XP + SP 2/3 defines
85`_WIN32_WINNT >= _WIN32_WINNT_VISTA` without providing `IsThreadAFiber()`.
86
87[endsect]
88
89
90[section x86 and floating-point env]
91
92[heading i386]
93
94"The FpCsr and the MxCsr register must be saved and restored before any call or return
95by any procedure that needs to modify them ..."
96[footnote 'Calling Conventions', Agner Fog].
97
98
99[heading x86_64]
100
101[heading Windows]
102
103MxCsr - "A callee that modifies any of the non-volatile fields within MxCsr must restore
104them before returning to its caller. Furthermore, a caller that has modified any
105of these fields must restore them to their standard values before invoking a callee ..."
106[footnote [@http://http://msdn.microsoft.com/en-us/library/yxty7t75.aspx MSDN article
107'MxCsr']].
108
109FpCsr - "A callee that modifies any of the fields within FpCsr must restore them before
110returning to its caller. Furthermore, a caller that has modified any of these
111fields must restore them to their standard values before invoking a callee ..."
112[footnote [@http://http://msdn.microsoft.com/en-us/library/ms235300.aspx MSDN article
113'FpCsr']].
114
115"The MMX and floating-point stack registers (MM0-MM7/ST0-ST7) are preserved across
116context switches. There is no explicit calling convention for these registers."
117[footnote [@http://msdn.microsoft.com/en-us/library/a32tsf7t%28VS.80%29.aspx MSDN article
118'Legacy Floating-Point Support']].
119
120"The 64-bit Microsoft compiler does not use ST(0)-ST(7)/MM0-MM7".
121[footnote 'Calling Conventions', Agner Fog].
122
123"XMM6-XMM15 must be preserved"
124[footnote [@http://msdn.microsoft.com/en-us/library/9z1stfyw%28v=vs.100%29.aspx MSDN
125article 'Register Usage']]
126
127[heading SysV]
128
129"The control bits of the MxCsr register are callee-saved (preserved across calls),
130while the status bits are caller-saved (not preserved). The x87 status word register is
131caller-saved, whereas the x87 control word (FpCsr) is callee-saved."
132[footnote SysV ABI AMD64 Architecture Processor Supplement Draft Version 0.99.4, 3.2.1].
133
134[endsect]
135
136
137[endsect]
138