1 // AsmJit - Complete JIT Assembler for C++ Language.
3 // Copyright (c) 2008-2010, Petr Kobalicek <kobalicek.petr@gmail.com>
5 // Permission is hereby granted, free of charge, to any person
6 // obtaining a copy of this software and associated documentation
7 // files (the "Software"), to deal in the Software without
8 // restriction, including without limitation the rights to use,
9 // copy, modify, merge, publish, distribute, sublicense, and/or sell
10 // copies of the Software, and to permit persons to whom the
11 // Software is furnished to do so, subject to the following
14 // The above copyright notice and this permission notice shall be
15 // included in all copies or substantial portions of the Software.
17 // THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
18 // EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
19 // OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
20 // NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
21 // HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
22 // WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
23 // FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
24 // OTHER DEALINGS IN THE SOFTWARE.
32 //! @brief AsmJit is complete x86/x64 JIT Assembler for C++ language
34 //! It supports FPU, MMX, 3dNow, SSE, SSE2, SSE3 and SSE4 intrinsics, powerful
35 //! compiler that helps to write portable functions for 32-bit (x86) and 64-bit
36 //! (x64) architectures. AsmJit can be used to create functions at runtime that
37 //! can be called from existing (but also generated) C/C++ code.
39 //! AsmJit is crossplatform library that supports various compilers and
40 //! operating systems. Currently only limitation is x86 (32-bit) or x64 (64-bit)
41 //! processor. Currently tested operating systems are Windows (32-bit and 64-bit),
42 //! Linux (32-bit and 64-bit) and MacOSX (32-bit).
44 //! @section AsmJit_Main_Introduction Introduction
46 //! AsmJit library contains two main classes for code generation with different
47 //! goals. First main code generation class is called @c AsmJit::Assembler and
48 //! contains low level API that can be used to generate JIT binary code. It
49 //! directly emits binary stream that represents encoded x86/x64 assembler
50 //! opcodes. Together with operands and labels it can be used to generate
51 //! complete code. For details look to @ref AsmJit_Core and @ref AsmJit_Compiler
54 //! There is also class named @c AsmJit::Compiler that allows to develop
55 //! cross-platform assembler code without worring about function calling
56 //! conventions and registers allocation. It can be also used to write 32-bit
57 //! and 64-bit portable code. Compiler is recommended class to use for code
60 //! Everything in AsmJit library is in @c AsmJit namespace.
62 //! @section AsmJit_Main_CodeGeneration Code Generation
64 //! - @ref AsmJit_Core "Assembler core" - Operands, intrinsics and low-level assembler.
65 //! - @ref AsmJit_Compiler "Compiler" - High level code generation.
66 //! - @ref AsmJit_CpuInfo "Cpu Information" - Get information about host processor.
67 //! - @ref AsmJit_Logging "Logging" - Logging and error handling.
68 //! - @ref AsmJit_MemoryManagement "Memory Management" - Virtual memory management.
70 //! @section AsmJit_Main_Configuration Configuration, Definitions and Utilities
72 //! - @ref AsmJit_Config "Configuration" - Macros used to configure AsmJit.
73 //! - @ref AsmJit_Util "Utilities" - Utilities and helper classes.
75 //! @section AsmJit_Main_HomePage AsmJit Homepage
77 //! - http://code.google.com/p/asmjit/
79 //! @section AsmJit_Main_X86X64Resources External X86/X64 Assembler Resources
80 //! - http://www.agner.org/optimize/
81 //! - http://www.mark.masmcode.com/ (Assembler Tips)
82 //! - http://avisynth.org/mediawiki/Filter_SDK/Assembler_optimizing (Optimizing)
83 //! - http://www.ragestorm.net/distorm/ (Disassembling)
85 //! @section AsmJit_Main_Terminology Terminology
87 //! - <b>Non-volatile (preserved) register</b> - Register that can't be changed
88 //! by callee (callee must save and restore it if it want to use it inside).
90 //! - <b>Volatile (non-preserved) register</b> - The opossite. Register that can
91 //! be freely used by callee. The caller must free all registers before calling
95 //! @defgroup AsmJit_Core Assembler core (operands, intrinsics and low-level assembler).
97 //! Contains classes related to @c AsmJit::Assembler that're directly used
98 //! to generate machine code stream. It's one of oldest and fastest method
99 //! to generate machine code using AsmJit library.
101 //! - See @c AsmJit::Assembler class for low level code generation
103 //! - See @c AsmJit::Operand for AsmJit operand's overview.
105 //! @section AsmJit_Core_Registers Registers
107 //! There are static objects that represents X86 and X64 registers. They can
108 //! be used directly (like @c eax, @c mm, @c xmm, ...) or created through
111 //! - @c AsmJit::mk_gpb() - make general purpose byte register
112 //! - @c AsmJit::mk_gpw() - make general purpose word register
113 //! - @c AsmJit::mk_gpd() - make general purpose dword register
114 //! - @c AsmJit::mk_gpq() - make general purpose qword register
115 //! - @c AsmJit::mk_mm() - make mmx register
116 //! - @c AsmJit::mk_xmm() - make sse register
117 //! - @c AsmJit::st() - make x87 register
119 //! @section AsmJit_Core_Addressing Addressing
121 //! X86 and x64 architectures contains several addressing modes and most ones
122 //! are possible with AsmJit library. Memory represents are represented by
123 //! @c AsmJit::Mem class. These functions are used to make operands that
124 //! represents memory addresses:
126 //! - @c AsmJit::ptr()
127 //! - @c AsmJit::byte_ptr()
128 //! - @c AsmJit::word_ptr()
129 //! - @c AsmJit::dword_ptr()
130 //! - @c AsmJit::qword_ptr()
131 //! - @c AsmJit::tword_ptr()
132 //! - @c AsmJit::dqword_ptr()
133 //! - @c AsmJit::mmword_ptr()
134 //! - @c AsmJit::xmmword_ptr()
135 //! - @c AsmJit::sysint_ptr()
137 //! Most useful function to make pointer should be @c AsmJit::ptr(). It creates
138 //! pointer to the target with unspecified size. Unspecified size works in all
139 //! intrinsics where are used registers (this means that size is specified by
140 //! register operand or by instruction itself). For example @c AsmJit::ptr()
141 //! can't be used with @c AsmJit::Assembler::inc() instruction. In this case
142 //! size must be specified and it's also reason to make difference between
145 //! Supported are simple address forms (register + displacement) and complex
146 //! address forms (register + (register << shift) + displacement).
148 //! @section AsmJit_Core_Immediates Immediates
150 //! Immediate values are constants thats passed directly after instruction
151 //! opcode. To create such value use @c AsmJit::imm() or @c AsmJit::uimm()
152 //! methods to create signed or unsigned immediate value.
154 //! @sa @c AsmJit::Compiler.
157 //! @defgroup AsmJit_Compiler Compiler (high-level code generation).
159 //! Contains classes related to @c AsmJit::Compiler that can be used
160 //! to generate code using high-level constructs.
162 //! - See @c AsmJit::Compiler class for high level code generation
163 //! documentation - calling conventions, function declaration
164 //! and variables management.
166 //! @defgroup AsmJit_Config Configuration.
168 //! Contains macros that can be redefined to fit into any project.
171 //! @defgroup AsmJit_CpuInfo CPU information.
173 //! X86 or x64 cpuid instruction allows to get information about processor
174 //! vendor and it's features. It's always used to detect features like MMX,
175 //! SSE and other newer ones.
177 //! AsmJit library supports low level cpuid call implemented internally as
178 //! C++ function using inline assembler or intrinsics and also higher level
179 //! CPU features detection. The low level function (also used by higher level
180 //! one) is @c AsmJit::cpuid().
182 //! AsmJit library also contains higher level function @c AsmJit::getCpuInfo()
183 //! that returns features detected by the library. The detection process is
184 //! done only once and it's cached for all next calls. @c AsmJit::CpuInfo
185 //! structure not contains only information through @c AsmJit::cpuid(), but
186 //! there is also small multiplatform code to detect number of processors
187 //! (or cores) throught operating system API.
189 //! It's recommended to use @c AsmJit::cpuInfo to detect and check for
190 //! host processor features.
192 //! Example how to use AsmJit::cpuid():
195 //! // All functions and structures are in AsmJit namesapce.
196 //! using namespace AsmJit;
198 //! // Here will be retrieved result of cpuid call.
201 //! // Use cpuid function to do the job.
202 //! cpuid(0 /* eax */, &out /* eax, ebx, ecx, edx */);
204 //! // Id eax argument to cpuid is 0, ebx, ecx and edx registers
205 //! // are filled with cpu vendor.
207 //! memcpy(i->vendor, &out.ebx, 4);
208 //! memcpy(i->vendor + 4, &out.edx, 4);
209 //! memcpy(i->vendor + 8, &out.ecx, 4);
210 //! vendor[12] = '\0';
216 //! If you want to use AsmJit::cpuid() function instead of higher level
217 //! @c AsmJit::getCpuInfo(), please read processor manuals provided by Intel,
218 //! AMD or other manufacturers for cpuid instruction details.
220 //! Example of using @c AsmJit::getCpuInfo():
223 //! // All functions and structures are in AsmJit namesapce.
224 //! using namespace AsmJit;
226 //! // Call to cpuInfo return CpuInfo structure that shouldn't be modified.
227 //! // Make it const by default.
228 //! const CpuInfo *i = getCpuInfo();
230 //! // Now you are able to get specific features.
232 //! // Processor has SSE2
233 //! if (i->features & CPU_FEATURE_SSE2)
237 //! // Processor has MMX
238 //! else if (i->features & CPU_FEATURE__MMX)
242 //! // Processor is old, no SSE2 or MMX support.
249 //! Better example is in AsmJit/Test/testcpu.cpp file.
251 //! @sa AsmJit::cpuid, @c AsmJit::cpuInfo.
254 //! @defgroup AsmJit_Logging Logging and error handling.
256 //! Contains classes related to loging assembler output. Currently logging
257 //! is implemented in @c AsmJit::Logger class.You can override
258 //! @c AsmJit::Logger::log() to log messages into your stream. There is also
259 //! @c FILE based logger implemented in @c AsmJit::FileLogger class.
261 //! To log your assembler output to FILE stream use this code:
264 //! // Create assembler
267 //! // Create and set file based logger
268 //! FileLogger logger(stderr);
269 //! a.setLogger(&logger);
272 //! You can see that logging goes through @c AsmJit::Assembler. If you are
273 //! using @c AsmJit::Compiler and you want to log messages in correct assembler
274 //! order, you should look at @c AsmJit::Compiler::comment() method. It allows
275 //! you to insert text message into @c AsmJit::Emittable list and
276 //! @c AsmJit::Compiler will send your message to @c AsmJit::Assembler in
279 //! @sa @c AsmJit::Logger, @c AsmJit::FileLogger.
282 //! @defgroup AsmJit_MemoryManagement Virtual memory management.
284 //! Using @c AsmJit::Assembler or @c AsmJit::Compiler to generate machine
285 //! code is not final step. Each generated code needs to run in memory
286 //! that is not protected against code execution. To alloc this code it's
287 //! needed to use operating system functions provided to enable execution
288 //! code in specified memory block or to allocate memory that is not
289 //! protected. The solution is always to use @c See AsmJit::Assembler::make()
290 //! and @c AsmJit::Compiler::make() functions that can allocate memory and
291 //! relocate code for you. But AsmJit also contains classes for manual memory
292 //! management thats internally used by AsmJit but can be used by programmers
295 //! Memory management contains low level and high level classes related to
296 //! allocating and freeing virtual memory. Low level class is
297 //! @c AsmJit::VirtualMemory that can allocate and free full pages of
298 //! virtual memory provided by operating system. Higher level class is
299 //! @c AsmJit::MemoryManager that is able to manage complete allocation and
300 //! free mechanism. It internally uses larger chunks of memory to make
301 //! allocation fast and effective.
303 //! Using @c AsmJit::VirtualMemory::alloc() is crossplatform way how to
304 //! allocate this kind of memory without worrying about operating system
305 //! and it's API. Each memory block that is no longer needed should be
306 //! freed by @c AsmJit::VirtualMemory::free() method. If you want better
307 //! comfort and malloc()/free() interface, look at the
308 //! @c AsmJit::MemoryManager class.
310 //! @sa @c AsmJit::VirtualMemory, @ AsmJit::MemoryManager.
313 //! @defgroup AsmJit_Util Utilities and helper classes.
315 //! Contains some helper classes that's used by AsmJit library.
319 //! @addtogroup AsmJit_Config
322 //! @def ASMJIT_WINDOWS
323 //! @brief Macro that is declared if AsmJit is compiled for Windows.
325 //! @def ASMJIT_POSIX
326 //! @brief Macro that is declared if AsmJit is compiled for unix like
327 //! operating system.
330 //! @brief Attribute that's added to classes that can be exported if AsmJit
331 //! is compiled as a dll library.
333 //! @def ASMJIT_MALLOC
334 //! @brief Function to call to allocate dynamic memory.
336 //! @def ASMJIT_REALLOC
337 //! @brief Function to call to reallocate dynamic memory.
340 //! @brief Function to call to free dynamic memory.
342 //! @def ASMJIT_ASSERT
343 //! @brief Assertion macro. Default implementation calls
344 //! @c AsmJit::assertionFailure() function.
349 //! @namespace AsmJit
350 //! @brief Main AsmJit library namespace.
352 //! There are not other namespaces used in AsmJit library.
357 #include "Assembler.h"
358 #include "CodeGenerator.h"
359 #include "Compiler.h"
363 #include "MemoryManager.h"
365 #include "Platform.h"