PageRenderTime 56ms CodeModel.GetById 20ms RepoModel.GetById 1ms app.codeStats 0ms

/third_party/SoftWire/Readme.html

https://bitbucket.org/e_smirnov/gp_optimizer
HTML | 528 lines | 528 code | 0 blank | 0 comment | 0 complexity | 5b6b7fb2df739b9aef9c5f1fd65269df MD5 | raw file
Possible License(s): Apache-2.0, LGPL-2.1, MPL-2.0-no-copyleft-exception, LGPL-2.0
  1. <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
  2. <html>
  3. <head>
  4. <meta http-equiv="content-type" content="text/html; charset=UTF-8">
  5. <title>Readme</title>
  6. </head>
  7. <body>
  8. <div>
  9. <p>
  10. <u><strong>Summary</strong></u></p>
  11. <p>
  12. SoftWire is a class library written in object-oriented C++ for compiling assembly
  13. code. It can be used in projects to generate x86 machine code at run-time as an
  14. alternative to self-modifying code. Scripting languages might also benefit by using
  15. SoftWire as a JIT-compiler back-end. It also allows to eliminate jumps for variables
  16. which are temporarily constant during run-time, like for efficient graphics processing
  17. by constructing an optimised pipeline. Because of its possibility for 'instruction
  18. rewiring' by run-time conditional compilation, I named it "SoftWire". It is targeted
  19. only at developers with a good knowledge of C++ and x86 assembly.</p>
  20. <p>
  21. This document applies to SoftWire 4.0.1 and newer versions.</p>
  22. <p>
  23. <strong><u>Content</u></strong></p>
  24. <ol>
  25. <li>Demo</li>
  26. <li>Compilation</li>
  27. <li>Syntax</li>
  28. <li>Run-Time Intrinsics</li>
  29. <li>Automatic Register Allocation</li>
  30. <li>Design</li>
  31. <li>Licence Conditions</li>
  32. <li>Contributions &amp; Credits</li>
  33. <li>Bugs &amp; Feature Requests</li>
  34. <li>Acknowledgements</li>
  35. </ol>
  36. <p>
  37. <u><strong>1. Demo</strong></u></p>
  38. <p>
  39. The demo application assembles seven test routines: HelloWorld.asm shows that it
  40. is possible to call external functions, like printf. SetBits.asm is a function to
  41. set a number of bits in a buffer, starting from a given bit. CrossProduct.asm shows
  42. the use of floating-point instructions, macros and inline functions. AlpahBlend.asm
  43. uses MMX instructions for blending 32-bit colors, and conditionally compiles for
  44. Katmai compatible or older processors. It also shows how to define static data.
  45. Factorial.asm calculates a factorial by recursively calling itself. Mandelbrot.asm
  46. draws the Mandelbrot fractal in ASCII. The last test shows the use of run-time intrinsics.</p>
  47. <p>
  48. Execute SoftWire.exe at your own risk! It has been tested on many systems, but I
  49. make no guarantee that it will work on yours.</p>
  50. <p>
  51. For more projects that use SoftWire, check out <a href="http://softwire.sourceforge.net/extra.html">
  52. http://softwire.sourceforge.net/extra.html</a>.</p>
  53. <p>
  54. <u><strong>2. Compilation</strong></u></p>
  55. <p>
  56. This library was developed with Visual C++ .NET&nbsp;and has project and workspace
  57. files for this compiler included. Solution files for Visual C++ 6.0 and makefiles
  58. for Dev-C++ and GCC are also included. For GCC you will need a recent version which
  59. supports nameless structs. Should you have any problems compiling the code, please
  60. mail me at <a href="mailto:nicolas@capens.net">nicolas@capens.net</a>.</p>
  61. <p>
  62. Compilation with GCC requires the -fno-operator-names option. This is needed to
  63. avoid an error with functions named <font face="Courier New" size="2">and</font>,
  64. <font face="Courier New" size="2">not</font>, <font face="Courier New" size="2">or</font>
  65. and <font face="Courier New" size="2">xor</font>, which are according to the C++
  66. standard reserved keyword. For more information see the Run-Time Intrinsics section.</p>
  67. <p>
  68. <u><strong>3. Syntax</strong></u></p>
  69. <p>
  70. Before reading this detailed information it is best to take a look at Test.cpp and
  71. the .asm files to see the basics of what SoftWire has to offer...</p>
  72. <p>
  73. The source line layout is similar to that from NASM and the Visual C++ inline assembler:<br>
  74. <font face="Courier New" size="2">label:&nbsp;&nbsp;&nbsp; instruction operands&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
  75. ; comment</font></p>
  76. <p>
  77. The assembler can accept a file with the .asm extension. This file is treated as
  78. one block of code, but subroutines and data can be created with labels. Execution
  79. will start at the lablel with the same name as the file, unless an other entry point
  80. has been defined. The assembler generates only 32-bit code for processors compatible
  81. with the 386 or above.</p>
  82. <p>
  83. C/C++ comments are also supported. The assembler is case-sensitive, except for instructions
  84. and registers. Labels are like in inline assembler and cannot have special characters
  85. like $, #, @, ~, ?, etc.</p>
  86. <p>
  87. Specifiers are always optional, but when the assembler has multiple possible instructions
  88. you can't predict the behaviour without using a specifier. For example, the assembler
  89. can't know if the code <font face="Courier New" size="2">fld [esi]</font> uses single
  90. or double precision floating-point numbers without a <font face="Courier New" size="2">
  91. DWORD</font> or <font face="Courier New" size="2">QWORD</font> specifier. The
  92. <font face="Courier New" size="2">PTR</font> keyword is optional. The <font face="Courier New"
  93. size="2">NEAR</font> or <font face="Courier New" size="2">SHORT</font> keywords
  94. can be used for jumps or calls and are equivalent.</p>
  95. <p>
  96. The assembler supports the MMX, 3DNow!, Pentium Pro, SSE and SSE2 instruction set.
  97. Some specific instructions have been removed because they are unsafe and/or not
  98. useful for 32-bit protected mode:</p>
  99. <ul>
  100. <li>
  101. Privileged instructions
  102. <li>
  103. FAR calls and jumps
  104. <li>
  105. Undocumented instructions
  106. <li>
  107. Extended precision 80-bit FPU instructions
  108. <li>
  109. State save/restore instructions
  110. <li>Segment/debug/control/table registers</li></ul>
  111. <p>
  112. This is very similar to the Visual C++ inline assembler. It should not limit you
  113. for 'normal' use of this run-time assembler. For more details, take a look at the
  114. InstructionSet.cpp file. You can always write your own machine-code by defining
  115. it as static data.</p>
  116. <p>
  117. You can define static data with the <font face="Courier New" size="2">DB</font>,
  118. <font face="Courier New" size="2">DW</font> and <font face="Courier New" size="2">DD</font>
  119. keywords. By using a label, the address of this data can be referenced. The data
  120. will be created at the location of the definition, so it's advisable to put it after
  121. the return or before the function label. Since there is no standard way to declare
  122. local data, you should put everything on the stack yourself. Local data is not that
  123. usefull for a run-time assembler anyway. You could use the 'cdecl' calling convention
  124. (standard in Visual C++) to let the caller push the arguments on the stack and remove
  125. them after the function has been called. Subroutines can also be created by using
  126. labels. To create arrays of static data, you can use <font face="Courier New" size="2">
  127. DB[#]</font>, <font face="Courier New" size="2">DW[#]</font> and <font face="Courier New"
  128. size="2">DD[#]</font>. All variables will be aligned on their natural boundaries.</p>
  129. <p>
  130. To align data or code yourself, you can use the <font face="Courier New" size="2">ALIGN</font>
  131. keyword. For efficiency, jump labels should be 16 byte aligned, and for most SSE
  132. instructions the data also has to be 16 byte aligned. The assembler will use <font
  133. face="Courier New" size="2">NOP</font> instructions for padding for both data
  134. and code alignment.</p>
  135. <p>
  136. External data can be declared by using the <font face="Courier New" size="2">Assembler::defineExternal</font>
  137. method in your C++ code. A handy macro defined in <em>Assembler.hpp</em> makes it
  138. possible to export a function like printf with <font face="Courier New" size="2">ASM_EXPORT(printf)</font>.
  139. Externals can be any kind of data defined in your C++ application, and are treated
  140. like void pointers. Externals should be declared before assembling the file. They
  141. do not have to be re-declared in the assembly code.</p>
  142. <p>
  143. For constants, only numbers and character constants are supported. They can be in
  144. binary, octal, decimal or hexadecimal base, with the usual pre- or postfixes. All
  145. constant expressions are evaluated, inclusing those of data definitions and memory
  146. references. String literals can be created by using <font face="Courier New" size="2">
  147. DB</font> and double quotation marks.</p>
  148. <p>
  149. Conditional compilation can be controlled with the <font face="Courier New" size="2">
  150. #if</font>, <font face="Courier New" size="2">#elif</font>, <font face="Courier New"
  151. size="2">#else</font> and <font face="Courier New" size="2">#endif</font>
  152. precompiler directives. The <font face="Courier New" size="2">ASM_DEFINE</font>
  153. macro can be used to send an integer to the assembler which can be used after the
  154. <font face="Courier New" size="2">#if</font> and <font face="Courier New" size="2">#elif</font>
  155. directives. Boolean expressions are evaluated as in C/C++.</p>
  156. <p>
  157. This powerful feature can be used to generate many different specific functions
  158. without having to code completely new ones. It can eliminate jumps in the assembly
  159. code to generate exactly the optmized function you need. An example of this is an
  160. SIMD optimized vertex pipeline for 3D graphics. Without conditional compilation,
  161. many comparisons and jumps would be needed per vertex to transform and light it
  162. correctly for the current settings. With run-time conditional compilation, these
  163. instructions can be eliminated, leaving only the wanted instructions, while still
  164. being able to handle thousands of setting combinations. It also allows to write
  165. different code for other processors, without needing a control statement in your
  166. high-performance assembly code and without the need to write it as separate functions
  167. which are difficult to maintain.</p>
  168. <p>
  169. The preprocessor also supports <font face="Courier New" size="2">#include</font>
  170. and <font face="Courier New" size="2">#define</font>. There is also an <font face="Courier New"
  171. size="2">inline</font> keyword, which behaves like <font face="Courier New" size="2">
  172. #define</font> but produces less error-prone code (caused by nested macros)
  173. and has a nicer syntax for multiple lines:</p>
  174. <p>
  175. <font face="Courier New" size="2">inline macroName(argument1, argument2, ...)<br>
  176. {<br>
  177. &nbsp;&nbsp;&nbsp; code block<br>
  178. }</font></p>
  179. <p>
  180. It is a nice way of defining new instructions, and it even allows to define 'instructions'
  181. to be emulated with x86 assembly, like DirectX shader instructions! With normal
  182. macros, the only problem for doing this would be that you need parenthesis around
  183. the arguments. But even this is solved with the inline macros. You can simply use
  184. the above macro like this:</p>
  185. <pre>macroName argument1, argument2, ...</pre>
  186. <p>
  187. When you don't write an open parenthesis, SoftWire will automatically assume that
  188. you want to use this 'implicit' argument list. The argument list stops at the end
  189. of the line, so it is not possible to nest multiple macros without using parenthesis.</p>
  190. <p>
  191. Sometimes it can be rather unhandy to work with the Assembler class if all you need
  192. is the machine code. To&nbsp;have the&nbsp;control&nbsp;over the code and safely
  193. delete the Assembler instance without destroying the code, use the <font face="Courier New"
  194. size="2">Assembler::aquire()</font> method. This method returns the pointer
  195. to the machine code, and tells the Assembler not to delete it at the destructor.
  196. Note that it is still necessary to first use <font face="Courier New" size="2">Assembler::callable(entryLabel)</font>
  197. to get the pointer(s) to your function(s). If <font face="Courier New" size="2">aquire()</font>
  198. is called before any call to <font face="Courier New" size="2">callable()</font>,
  199. it will return zero.</p>
  200. <p>
  201. To minimize memory usage,&nbsp;call Assembler::finalize() after retrieving the pointers
  202. to the functions. This is especially useful for sub-classing Assembler. It will
  203. delete all temporary memory used by the scanner, parser, instruction table and intermediate
  204. code. Any futher assembling tasks like using a run-time intrinsic will result in
  205. an exception to be thrown. The generated machine code is still property of Assembler
  206. unless you also call aquire().</p>
  207. <p>
  208. <strong><u>4. Run-Time Intrinsics</u></strong></p>
  209. <p>
  210. SoftWire also supports another form of run-time code generation. With every assembly
  211. instruction corresponds a member function of Assembler with the same name. These
  212. functions encode the corresponding instruction and put it in the Loader so it is
  213. ready to execute. These run-time intrinsics are ideal for writing a compiler back-end.
  214. Because it is all written in C++, things like conditional compilation become trivial.
  215. Check the tutorial at softwire.sourceforge.net for practical information.</p>
  216. <p>
  217. You need to construct a <font face="Courier New" size="2">SoftWire::CodeGenerator</font>,
  218. after including <em>CodeGenerator.hpp</em>.</p>
  219. <p>
  220. You can use the usual register names directly when deriving from <font face="Courier New"
  221. size="2">CodeGenerator</font> . For example <font face="Courier New" size="2">add(eax,
  222. ebx);</font> is valid in&nbsp;<font face="Courier New" size="2">CodeGenerator</font>
  223. 's scope and its subclasses. For memory operands, you need to use <font face="Courier New"
  224. size="2">dword_ptr [...]</font> and the like. Note that all syntax checks should
  225. happen at compile-time. An exception is that it's impossible to check the scale
  226. factor in a memory reference.</p>
  227. <p>
  228. To add labels, you need to use the <font face="Courier New" size="2">Assembler::label()</font>
  229. method. For example to create an array of 100 uninitialized bytes:</p>
  230. <pre>label("table");<br>db(byte_ptr [100]);</pre>
  231. <p>
  232. Note that it doesn't matter if you use <font face="Courier New" size="2">byte_ptr</font>
  233. or any other specifier here, it is only needed to have a valid C++ syntax. To reference
  234. the data or function at&nbsp;a label, also use a string literal. This works on any
  235. instruction which can accept a 32-bit immediate, like <font face="Courier New" size="2">
  236. jmp</font>, <font face="Courier New" size="2">call</font>, <font face="Courier New"
  237. size="2">push</font>, <font face="Courier New" size="2">dd</font>, etc.</p>
  238. <p>
  239. Take a look at <font face="Courier New" size="2">testIntrinsics()</font> in Test.cpp
  240. for&nbsp;some simple working example code. Check the tutorial at softwire.sourceforge.net
  241. for detailed examples. The swShader project (sw-shader.sourceforge.net) also uses
  242. run-time intrinsics intensively.</p>
  243. <p>
  244. Because <font face="Courier New" size="2">and</font>, <font face="Courier New" size="2">
  245. not</font>, <font face="Courier New" size="2">or</font> and <font face="Courier New"
  246. size="2">xor</font> are both assembly instructions and reserved C++ keywords,
  247. the compiler should ignore them. In Visual C++ they are not recognised as keywords,
  248. but with GCC you need the <font face="Courier New" size="2">-fno-operator-names</font>
  249. option to allow run-time intrinsics.</p>
  250. <p>
  251. To simplify debugging of a code generator which uses intrinsics, there is an <font
  252. face="Courier New" size="2">Assembler::setEchoFile</font> method. This function
  253. takes the name of a file where SoftWire will copy the textual assembly code corresponding
  254. with the&nbsp;intrinsic. This way you can check the output without using a disassembler.
  255. There's also an <font face="Courier New" size="2">Assembler::annotate</font> method
  256. to comment your generated code.&nbsp;It will put a&nbsp;semicolon at the start of
  257. the line,&nbsp;so the echo file can also be used as the input for SoftWire.</p>
  258. <p>
  259. The <em>Intrinsics.hpp</em> file can take a while to compile.&nbsp;If run-time intrinsics
  260. are not needed in your project but fast compilation is a must, define <font face="Courier New"
  261. size="2">SOFTWIRE_NO_INTRINSICS</font> before including <em>Assembler.hpp</em>.</p>
  262. <p>
  263. <strong><u>5. Automatic Register Allocation</u></strong></p>
  264. <p>
  265. Now that you know how run-time intrinsics work, let's take this to the next level.
  266. I already mentioned that things like conditional compilation become trivial because
  267. it's all written in C++, but we can do lot's more like eliminating redundant operation
  268. with peephole optimization, and automatic register allocation.</p>
  269. <p>
  270. The latter has been integrated into SoftWire 4.0.0 and newer versions. Basically
  271. what it does is mapping variables in memory to registers. When there are more variables
  272. than physical registers, it automatically spills registers. This enables you to
  273. implement any kind of compiler, from a full-blown C++ compiler to a simple scripting
  274. language without worrying about the low-level stuff. It's almost like directly writing
  275. intermediate code!</p>
  276. <p>
  277. Because this adds an extra level of abstraction it is not implemented in the Assembler
  278. class, but in a subclass called <font face="Courier New" size="2">CodeGenerator</font>
  279. . The main reason it was not added to Assembler is because if you only need a simple
  280. assembler you can define <font face="Courier New" size="2">SOFTWIRE_NO_INTRINSICS </font>
  281. to keep things lightweight. The CodeGenerator class could later also feature optimizations
  282. like scheduling which do not guarantee a 1-to-1 mapping of the assembly code to
  283. the machine code.</p>
  284. <p>
  285. The first and most important new method is <font face="Courier New" size="2">CodeGenerator::r32()</font>.
  286. It takes a memory reference as argument and returns a general purpose register (not
  287. including esp and ebp). For MMX and SSE registers you can use <font face="Courier New"
  288. size="2">CodeGenerator::r64()</font> and <font face="Courier New" size="2">CodeGenerator::r128()</font>
  289. respectively. It is advisable to derive your own code generator from&nbsp;<font face="Courier New"
  290. size="2">CodeGenerator</font> so the class name can be ommited. Example:</p>
  291. <p dir="ltr" style="margin-right: 0px">
  292. <font face="Courier New" size="2">class ScriptCompiler : pulic CodeGenerator<br>
  293. {<br>
  294. public:<br>
  295. void generateCode()<br>
  296. {</font><font face="Courier New" size="2">
  297. <br>
  298. &nbsp; static int foo;</font><font face="Courier New" size="2">
  299. <br>
  300. &nbsp; mov(r32(&amp;foo), 0x12345678);</font><font face="Courier New" size="2">
  301. <br>
  302. ...</font></p>
  303. <p>
  304. It works just as well with non-static variables, like variables on the stack:</p>
  305. <pre>mov(r32(esp+12), 0x12345678);</pre>
  306. <p>
  307. <font face="Times New Roman">Or if you're indexing an array of ints 'array' with an
  308. index 'index' and store that in 'value':</font></p>
  309. <pre>mov(r32(&amp;value), dword_ptr[r32(&amp;array)+r32(&amp;index)*4]);</pre>
  310. <p>
  311. So there is no need to worry anymore what register is used where or if it is available.
  312. You treat them all like variables in memory and SoftWire automatically places them
  313. into registers.</p>
  314. <p>
  315. After the operations on the variable are done, we would like to write it back to
  316. memory. This&nbsp;can be&nbsp;done with the&nbsp;<font face="Courier New" size="2">spill()</font>
  317. method, which takes&nbsp;a register or&nbsp;reference as argument. The register
  318. to which the variable is allocated then becomes available again. Another method
  319. that does this is <font face="Courier New" size="2">free()</font>. The difference
  320. with spill is that&nbsp;free does not write the variable's data back to memory.
  321. This is useful for registers that are only needed temporarily, more about that later.
  322. When an instruction can only work on for example eax, you should spill or free eax
  323. before using this instruction. Also beware that at branches you have to spill all
  324. used variables. This can also be done with the <font face="Courier New" size="2">spillAll()
  325. <font face="Times New Roman" size="3">method, or with <font face="Courier New" size="2">
  326. freeAll()</font> if you've written back all results yourself.</font></font></p>
  327. <p>
  328. The above example is not optimal, since SoftWire will copy the data from [esp+12]
  329. to the allocated register, and it then immediately gets overwritten with 0x12345678.
  330. To eliminate this redundant copying, use the <font face="Courier New" size="2">x32()</font>
  331. method instead, or x64/x128 for MMX/SSE. This function works just like r32 but does
  332. not copy the data from the memory reference to the register. This is mainly useful
  333. for temporary registers. Have a look at the <font face="Courier New" size="2">TestRegisterAllocator</font>
  334. class in Test.cpp for a working example.</p>
  335. <p>
  336. Because some intermediate instructions can be complex and require temporary variables
  337. in physical registers for speed, there's also the <font face="Courier New" size="2">
  338. t32()</font> method, or t64/t128 for MMX/SSE. This function does not take a
  339. reference to a memory location as argument, but only an index.&nbsp;The function
  340. returns a register that will never be spilled. Therefore you can only use indices
  341. 0 to 5 for 32-bit registers and 0 to 7 for MMX/SSE registers. The difference with
  342. using the registers directly is that it does not interfere with the regiser allocator,
  343. and if necessary it spills the register with lowest priority first. So there is
  344. no 1-to-1 mapping of t32 registers to the physical registers. Free them as soon
  345. as possible to avoid unnecessary spilling or running out of registers! To avoid
  346. this complexity, just stick to the r32 or x32 functions. The only advantage of t32
  347. is that you don't need a memory location where the register can be written to if
  348. it needs to be spilled.</p>
  349. <p>
  350. To optimize memory accesses, there is also a <font face="Courier New" size="2">m32()</font>
  351. method, or m64/m128 for MMX/SSE. This function returns either a register or a memory
  352. reference. many instructions can accept a r/m32 argument, and of course registers
  353. are more efficient. If the variable is already located in a register, m32 will return
  354. that register, else it will return the memory reference.
  355. </p>
  356. <p>
  357. The register allocator assumes that all six general purpose registers are available,
  358. and all MMX and SSE registers. It is your task to save and restore registers before
  359. using automatic register allocation.</p>
  360. <p>
  361. The spilling heuristic uses&nbsp;the access frequency to find the best candidate
  362. for spilling. When a register is allocated, it has the highest priority, meaning
  363. that it is the worst candidate for the next spill. For every access of a register,
  364. all other registers loose priority. This also means that less recently used registers
  365. have a lower priority. When spilling is needed, the register with lowest priority
  366. is written back to its memory location.</p>
  367. <p>
  368. The <font face="Courier New" size="2">CodeGenerator</font> class automatically does
  369. some trivial peephole optimizations. To disable this behaviour, define <font face="Courier New"
  370. size="2">SOFTWIRE_NO_PEEPHOLE</font> before including <em>CodeGenerator.hpp</em>.</p>
  371. <p>
  372. <u><strong>6. Design</strong></u></p>
  373. <p>
  374. The whole library is encapsulated in a namespace called <font face="Courier New"
  375. size="2">SoftWire</font>. This is to prevent name clashes with other projects.</p>
  376. <p>
  377. The only class you'll need for assembling a file and getting a pointer to the callable
  378. code is <font face="Courier New" size="2">Assembler</font>. It has to be constructed
  379. with the name of the .asm file which contains the assembly code. The assembler treats
  380. it as one block of code, and you can get a void pointer to the assembled code by
  381. calling the <font face="Courier New" size="2">callable()</font> method. By default
  382. the entry point will be a label with the same name as the file. You can also pass
  383. the name of a label as the entry point if you want to start excecution from another
  384. line. To effectively call the function, you first need to cast it to an appropriate&nbsp;function
  385. pointer. When the Assembler is destructed, it also deletes the assembled code. To
  386. prevent this and control the lifetime of the code yourself, call the <font face="Courier New"
  387. size="2">acquire()</font> method. This will return a pointer to the start of
  388. the code. This is not necessarily the entry point of the code, so you still need
  389. to use <font face="Courier New" size="2">callable()<font face="Times New Roman" size="3">.</font></font></p>
  390. <p>
  391. The first class the assembler will use for processing the assembly file is the <font
  392. face="Courier New" size="2">Scanner</font>. This class has the task to break
  393. up the source code into words, called tokens. It is also resposible for the preprocessing
  394. tasks like file inclusion, conditional compilation and macro expansion. The <font
  395. face="Courier New" size="2">Macro</font> class helps with this last task.</p>
  396. <p>
  397. The tokens are stored in a <font face="Courier New" size="2">Token</font> class.
  398. The scanner also recognizes tokens as being identifiers, constants or punctuators.
  399. The scanner does not recognize keywords (except preprocessor directives) and does
  400. no syntax checking. The whole file is scanned at once and the tokens are placed
  401. in a <font face="Courier New" size="2">TokenList</font> class.</p>
  402. <p>
  403. Every source line of tokens then goes to the <font face="Courier New" size="2">Parser</font>.
  404. It will recognize the keywords, check the syntax and pass the information like mnemonic
  405. and registers to the code generator.</p>
  406. <p>
  407. The code generation is done with the <font face="Courier New" size="2">Synthesizer</font>
  408. class. It will put the information from the parsed instruction into bytes for the
  409. machine code.</p>
  410. <p>
  411. The rules for the code generation are stored in the <font face="Courier New" size="2">
  412. InstructionSet</font> class. The parser uses this class to select the matching
  413. instruction(s), and the synthesizer uses it to know how to encode the instruction.</p>
  414. <p>
  415. The bytes from the synthesizer are stored into an <font face="Courier New" size="2">
  416. Encoding</font> class. It also stores information about labels and references
  417. to labels to resolve jump addresses.</p>
  418. <p>
  419. All encodings are stored in the <font face="Courier New" size="2">Loader</font>
  420. class. After all instructions have been assembled, this class will resolve all the
  421. references and write the machine-code bytes into a buffer. Externally declared data
  422. will be resolved by the assembler's <font face="Courier New" size="2">Linker</font>
  423. class. The loader also searches for the code entry point. When the assembler is
  424. destructed, the assembled code is also destroyed, except when using <font face="Courier New"
  425. size="2">acquire()</font>. The linker data is also cleared.</p>
  426. <p>
  427. When a syntax error occurs, the assembler throws an <font face="Courier New" size="2">
  428. Error</font> class. This class simply holds a string with the error description.
  429. This message will be printed to the console by using the <font face="Courier New"
  430. size="2">DebugOutput::printf</font> method. You can easily use your custom error
  431. output system by deriving from the DebugOutput class. Besides syntax errors, the
  432. assembler might also throw internal errors. This is an alternative to <font face="Courier New"
  433. size="2">assert()</font>, so it should not happen. If you get an internal error,
  434. or worse, an unhandled exception, please contact the author.</p>
  435. <p>
  436. Run-time intrinsics are generated by the <font face="Courier New" size="2">InstructionSet</font>,
  437. and stored in <em>Intrinsics.hpp</em> . You need to uncomment the&nbsp;<font face="Courier New"
  438. size="2">generateIntrinsics()</font> line in the <font face="Courier New" size="2">InstructionSet</font>
  439. constructor when you've made changes to the instruction set and need new intrinsics.
  440. Do not attempt to modify the <em>Intrinsics.hpp</em> file manually. The arguments
  441. for the intrinsics are defined in <em>Operand.hpp</em>.</p>
  442. <p>
  443. Automatic register allocation is controlled by the&nbsp;<font face="Courier New"
  444. size="2">CodeGenerator</font> class. For every physical register it keeps a
  445. reference to the memory location it is associated with. When spilling is needed
  446. it writes the least frequently used register back to memory.</p>
  447. <p>
  448. <u><strong>7. License Conditions</strong></u></p>
  449. <p>
  450. All source files&nbsp;fall under the LGPL (License.txt)&nbsp;and are Copyright (C)
  451. 2002-2003 Nicolas Capens:</p>
  452. <p>
  453. If you extend the possibilities of the classes in these files, please send your
  454. changes to the copyright holder(s). Do not change this file or License.txt, but
  455. use a change log. If you only derive from a class to write your own specific implementation,
  456. you don't have to release the source code of your whole project, just give credit
  457. where due. This can be done by mentioning my name in your credits list and/or providing
  458. a link to the original SoftWire source code (e.g.<a href="http://softwire.sourceforge.net">http://softwire.sourceforge.net</a>).</p>
  459. <p>
  460. Don't hesitate to contact me and show what you've created with&nbsp;SoftWire!</p>
  461. <p>
  462. <u><strong>8. Contributions &amp; Credits</strong></u></p>
  463. <ul>
  464. <li>Jude Venn: helped porting SoftWire to UNIX/Linux by providing alternative functions
  465. for the Microsoft specific code (File.hpp, String.hpp, CharType.hpp). He also wrote
  466. Makefile.gcc to easily compile SoftWire with GCC.</li>
  467. <li>'Carrot': reported and fixed missing FMULP and other variants and JNEA misspelling.</li>
  468. <li>Walt Woods: reported and fixed memory leak in InstructionSet. Reported bug with
  469. "push imm" instruction not pushing dwords for small integers. Fixed stack overflow
  470. with TokenLink destructor.</li>
  471. <li>Edwin Young: reported 16-bit register bug in Factorial.asm.</li>
  472. <li>'tawai': reported bug with single-argument IMUL instruction.</li>
  473. <li>Rene Dudfield: reported 3DNow! instruction encoding bugs. Helped SoftWire 3.0.0
  474. to compiler under Linux.</li>
  475. <li>Oscar Fuentes: reported missing&nbsp;addressing mode&nbsp;for run-time intrinsics
  476. and helped SoftWire 3 to compile with GCC and Intel compilers. Suggested methods
  477. to change ownership of machine code.</li>
  478. <li>Florian Bosch: Reported bugs in run-time intrinsics with references to labels.</li>
  479. <li>Blake Pelton: Reported small memory leaks caused by strdup() use.</li>
  480. <li>'IanM': Contributed changes to assemble from source string.</li>
  481. <li>Dario Pelella: Fixed "push imm" bug with specifiers. Reported FPU instructions bug
  482. with '+r' encoding.</li>
  483. <li>Parzival Herzog: Detected and corrected several GCC compilation issues</li></ul>
  484. <p>
  485. If you feel like you should also have been mentioned on this list (or be removed
  486. or have something changed), please do not hesitate to contact me to&nbsp;correct
  487. this mistake.</p>
  488. <p>
  489. Why are contributions, bug fixes and copyrights not indicated in the code? I do
  490. not like this because in my opinion source files should be kept as readable as possible.
  491. I think it is very annoying that you first have to scroll past a huge block of comments
  492. that don't have anything to do with the code itself. Source files are for code.
  493. Licence and readme files are for the things not directly related to the code but
  494. to the library as a whole. If you cannot agree with this point of view and have
  495. some strong arguments, please contact me to discuss it.</p>
  496. <p>
  497. <u><strong>9. Bugs &amp; Feature Requests</strong></u></p>
  498. <p>
  499. SoftWire is a work-in-progress, so every kind of feedback is welcome, good or bad.
  500. I'm also always willing to help you out if you don't get something working. If you're
  501. a C++ guru and you would have designed some parts differently, I'm all ears. Contact
  502. me via e-mail at <a href="mailto:nicolas@capens.net">nicolas@capens.net</a>.</p>
  503. <p>
  504. <u><strong>10. Acknowledgements</strong></u></p>
  505. <p>
  506. Special thanks to:</p>
  507. <ul>
  508. <li>
  509. The creators of NASM, for their detailed overview of the x86 instruction set
  510. <li><a href="http://www.sandpile.org">www.sandpile.org</a>, for its great resources
  511. about IA-32 encoding rules
  512. <li>Everyone at <a href="http://www.flipcode.com">www.flipcode.com</a> who has helped
  513. me directly or indirectly to make this project possible: <a href="http://www.flipcode.com/cgi-bin/msg.cgi?showThread=COTD-SoftWire&amp;forum=cotd&amp;id=-1">
  514. http://www.flipcode.com/cgi-bin/msg.cgi?showThread=COTD-SoftWire&amp;forum=cotd&amp;id=-1</a>
  515. <li>
  516. Jude Venn, for helping me get started with UNIX and GCC.
  517. <li>Paul Nettle, author of the memory manager (<a href="http://www.FluidStudios.com">http://www.FluidStudios.com</a>
  518. ).
  519. <li>Anyone who reported bugs or suggested useful features.</li></ul>
  520. <p>
  521. Kind regards,</p>
  522. <p>
  523. Nicolas Capens</p>
  524. <p>
  525. Copyright (C) 2002-2006 Nicolas Capens - <a href="mailto:nicolas@capens.net">nicolas@capens.net</a></p>
  526. </div>
  527. </body>
  528. </html>