extensions.html 30 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352
  1. <!DOCTYPE html PUBLIC '-//W3C//DTD XHTML 1.0 Strict//EN' 'http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd'>
  2. <html xmlns='http://www.w3.org/1999/xhtml' xml:lang='en' lang='en'>
  3. <head>
  4. <title>GTC Extensions - GTC documentation</title>
  5. <meta http-equiv='Content-Type' content='text/html; charset=utf-8' />
  6. <link rel='stylesheet' type='text/css' href='layout/default.css' />
  7. </head>
  8. <body>
  9. <p><a href='index.html'>◄ Back to index</a></p>
  10. <div class='c0'>
  11. <h1>GTC Extensions</h1>
  12. <p>GTC supports a number of extensions, designed to take advantage of the TI platform, or simply to maintain compatibility with existing programs.</p>
  13. <div class='toc'><div class='toctop'><div class='tocbot'><div class='toc-content'>
  14. <b>Contents:</b><ul>
  15. <li><a href='#GNU.extensions'>GNU extensions</a>
  16. <ul>
  17. <li><a href='#Statements.and.Declarations.in.Expressions'>Statements and Declarations in Expressions</a></li>
  18. <li><a href='#Referring.to.a.Type.with.typeof'>Referring to a Type with typeof</a></li>
  19. <li><a href='#Generalized.Lvalues'>Generalized Lvalues</a></li>
  20. <li><a href='#Conditionals.with.Omitted.Operands'>Conditionals with Omitted Operands</a></li>
  21. <li><a href='#Binary.Numbers'>Binary Numbers</a></li>
  22. <li><a href='#Structures.With.No.Members'>Structures With No Members</a></li>
  23. <li><a href='#Arrays.of.Length.Zero'>Arrays of Length Zero</a></li>
  24. <li><a href='#Macros.with.a.Variable.Number.of.Arguments'>Macros with a Variable Number of Arguments</a></li>
  25. <li><a href='#Arithmetic.on.void.and.Function.Pointers'>Arithmetic on void and Function Pointers</a></li>
  26. <li><a href='#Non-Constant.Initializers'>Non-Constant Initializers</a></li>
  27. <li><a href='#Compound.Literals..28Cast.Constructors.29'>Compound Literals (Cast Constructors)</a></li>
  28. <li><a href='#Designated.Initializers'>Designated Initializers</a></li>
  29. <li><a href='#Case.Ranges'>Case Ranges</a></li>
  30. <li><a href='#Specifying.Attributes.of.Functions'>Specifying Attributes of Functions</a></li>
  31. <li><a href='#C.2b.2b.Style.Comments'>C++ Style Comments</a></li>
  32. <li><a href='#Dollar.Signs.in.Identifier.Names'>Dollar Signs in Identifier Names</a></li>
  33. <li><a href='#Escape.Character.in.Constants'>Escape Character in Constants</a></li>
  34. <li><a href='#Alternate.Keywords'>Alternate Keywords</a></li>
  35. <li><a href='#__builtin_constant_p'>__builtin_constant_p</a></li>
  36. <li><a href='#Mixed.Declarations.and.Code'>Mixed Declarations and Code</a></li>
  37. <li><a href='#Unnamed.struct.2funion.Fields.within.structs.2funions'>Unnamed struct/union Fields within structs/unions</a></li>
  38. </ul></li>
  39. <li><a href='#GTC-specific.extensions'>GTC-specific extensions</a>
  40. <ul>
  41. <li><a href='#incbin.directive'>incbin directive</a>
  42. <ul>
  43. <li><a href='#Using.incbin.to.declare.a.C.array'>Using incbin to declare a C array</a></li>
  44. <li><a href='#Using.incbin.within.an.asm.7b.7d.statement'>Using incbin within an asm{} statement</a></li>
  45. </ul></li>
  46. <li><a href='#asm.7b.7d.statement'>asm{} statement</a>
  47. <ul>
  48. <li><a href='#Inserting.an.asm.7b.7d.statement.in.the.code'>Inserting an asm{} statement in the code</a>
  49. <ul>
  50. <li><a href='#Global.asm.7b.7d.statements'>Global asm{} statements</a></li>
  51. <li><a href='#Inline.asm.7b.7d.statements'>Inline asm{} statements</a></li>
  52. </ul></li>
  53. <li><a href='#Structure.of.an.asm.7b.7d.statement'>Structure of an asm{} statement</a></li>
  54. <li><a href='#asm.7b.7d.interpretation.rules'>asm{} interpretation rules</a></li>
  55. <li><a href='#Extra.features.of.asm.7b.7d.statements'>Extra features of asm{} statements</a></li>
  56. <li><a href='#asm.7b.7d.special.operator.3a.__c__'>asm{} special operator: __c__</a></li>
  57. </ul></li>
  58. <li><a href='#.40.40.prefix'>@@ prefix</a></li>
  59. </ul></li>
  60. </ul>
  61. </div></div></div></div>
  62. <div class='c1'>
  63. <hr class='hr1' /><h1 class='heading'><a name='GNU.extensions'></a>GNU extensions</h1><div class='c1in'><hr class='hr1in' /><div class='c2'>
  64. <hr class='hr2' /><h2 class='heading'><a name='Statements.and.Declarations.in.Expressions'></a>Statements and Declarations in Expressions</h2><div class='c2in'><hr class='hr2in' />
  65. <p>See <a href='http://tigcc.ticalc.org/doc/gnuexts.html#SEC63'> Statements and Declarations in Expressions</a>.</p>
  66. </div></div>
  67. <div class='c2'>
  68. <hr class='hr2' /><h2 class='heading'><a name='Referring.to.a.Type.with.typeof'></a>Referring to a Type with <em>typeof</em></h2><div class='c2in'><hr class='hr2in' />
  69. <p>See <a href='http://tigcc.ticalc.org/doc/gnuexts.html#SEC69'> Referring to a Type with <em>typeof</em></a></p>
  70. </div></div>
  71. <div class='c2'>
  72. <hr class='hr2' /><h2 class='heading'><a name='Generalized.Lvalues'></a>Generalized Lvalues</h2><div class='c2in'><hr class='hr2in' />
  73. <p>See <a href='http://tigcc.ticalc.org/doc/gnuexts.html#SEC70'> Generalized Lvalues</a>.</p>
  74. <p>Note however that weird constructs like<span class='widespace'>&#32;</span><code>(a,b)+=5</code><span class='widespace'>&#32;</span>are rejected by GTC -- commas are not considered legal lvalues.</p>
  75. </div></div>
  76. <div class='c2'>
  77. <hr class='hr2' /><h2 class='heading'><a name='Conditionals.with.Omitted.Operands'></a>Conditionals with Omitted Operands</h2><div class='c2in'><hr class='hr2in' />
  78. <p>See <a href='http://tigcc.ticalc.org/doc/gnuexts.html#SEC71'> Conditionals with Omitted Operands</a>.</p>
  79. </div></div>
  80. <div class='c2'>
  81. <hr class='hr2' /><h2 class='heading'><a name='Binary.Numbers'></a>Binary Numbers</h2><div class='c2in'><hr class='hr2in' />
  82. <p>See <a href='http://tigcc.ticalc.org/doc/gnuexts.html#SEC110'> Binary Numbers</a>.</p>
  83. </div></div>
  84. <div class='c2'>
  85. <hr class='hr2' /><h2 class='heading'><a name='Structures.With.No.Members'></a>Structures With No Members</h2><div class='c2in'><hr class='hr2in' />
  86. <p>See <a href='http://tigcc.ticalc.org/doc/gnuexts.html#SEC111'> Structures With No Members</a>.</p>
  87. </div></div>
  88. <div class='c2'>
  89. <hr class='hr2' /><h2 class='heading'><a name='Arrays.of.Length.Zero'></a>Arrays of Length Zero</h2><div class='c2in'><hr class='hr2in' />
  90. <p>See <a href='http://tigcc.ticalc.org/doc/gnuexts.html#SEC75'> Arrays of Length Zero</a>.</p>
  91. </div></div>
  92. <div class='c2'>
  93. <hr class='hr2' /><h2 class='heading'><a name='Macros.with.a.Variable.Number.of.Arguments'></a>Macros with a Variable Number of Arguments</h2><div class='c2in'><hr class='hr2in' />
  94. <p>See <a href='http://tigcc.ticalc.org/doc/gnuexts.html#SEC77'> Macros with a Variable Number of Arguments</a>.</p>
  95. </div></div>
  96. <div class='c2'>
  97. <hr class='hr2' /><h2 class='heading'><a name='Arithmetic.on.void.and.Function.Pointers'></a>Arithmetic on void and Function Pointers</h2><div class='c2in'><hr class='hr2in' />
  98. <p>See <a href='http://tigcc.ticalc.org/doc/gnuexts.html#SEC79'> Arithmetic on void and Function Pointers</a>.</p>
  99. </div></div>
  100. <div class='c2'>
  101. <hr class='hr2' /><h2 class='heading'><a name='Non-Constant.Initializers'></a>Non-Constant Initializers</h2><div class='c2in'><hr class='hr2in' />
  102. <p>See <a href='http://tigcc.ticalc.org/doc/gnuexts.html#SEC80'> Non-Constant Initializers</a>.</p>
  103. </div></div>
  104. <div class='c2'>
  105. <hr class='hr2' /><h2 class='heading'><a name='Compound.Literals..28Cast.Constructors.29'></a>Compound Literals (Cast Constructors)</h2><div class='c2in'><hr class='hr2in' />
  106. <p>See <a href='http://tigcc.ticalc.org/doc/gnuexts.html#SEC81'> Compound Literals (Cast Constructors)</a>. There is some difference in the handling of static storage duration though, see <a href='faq.html#Differences.between.GTC.and.TIGCC'>Differences between GTC and TIGCC</a>.</p>
  107. </div></div>
  108. <div class='c2'>
  109. <hr class='hr2' /><h2 class='heading'><a name='Designated.Initializers'></a>Designated Initializers</h2><div class='c2in'><hr class='hr2in' />
  110. <p>See <a href='http://tigcc.ticalc.org/doc/gnuexts.html#SEC82'> Designated Initializers</a>, but in GTC this only works for array types.</p>
  111. </div></div>
  112. <div class='c2'>
  113. <hr class='hr2' /><h2 class='heading'><a name='Case.Ranges'></a>Case Ranges</h2><div class='c2in'><hr class='hr2in' />
  114. <p>See <a href='http://tigcc.ticalc.org/doc/gnuexts.html#SEC83'> Case Ranges</a>.</p>
  115. </div></div>
  116. <div class='c2'>
  117. <hr class='hr2' /><h2 class='heading'><a name='Specifying.Attributes.of.Functions'></a>Specifying Attributes of Functions</h2><div class='c2in'><hr class='hr2in' />
  118. <p>See <a href='http://tigcc.ticalc.org/doc/gnuexts.html#SEC85'> Specifying Attributes of Functions</a>, however not all of the specifiers are meaningful in GTC.</p>
  119. </div></div>
  120. <div class='c2'>
  121. <hr class='hr2' /><h2 class='heading'><a name='C.2b.2b.Style.Comments'></a>C++ Style Comments</h2><div class='c2in'><hr class='hr2in' />
  122. <p>See <a href='http://tigcc.ticalc.org/doc/gnuexts.html#SEC87'> C++ Style Comments</a>.</p>
  123. </div></div>
  124. <div class='c2'>
  125. <hr class='hr2' /><h2 class='heading'><a name='Dollar.Signs.in.Identifier.Names'></a>Dollar Signs in Identifier Names</h2><div class='c2in'><hr class='hr2in' />
  126. <p>See <a href='http://tigcc.ticalc.org/doc/gnuexts.html#SEC88'> Dollar Signs in Identifier Names</a>.</p>
  127. </div></div>
  128. <div class='c2'>
  129. <hr class='hr2' /><h2 class='heading'><a name='Escape.Character.in.Constants'></a>Escape Character in Constants</h2><div class='c2in'><hr class='hr2in' />
  130. <p>See <a href='http://tigcc.ticalc.org/doc/gnuexts.html#SEC89'> Escape Character in Constants</a>.</p>
  131. </div></div>
  132. <div class='c2'>
  133. <hr class='hr2' /><h2 class='heading'><a name='Alternate.Keywords'></a>Alternate Keywords</h2><div class='c2in'><hr class='hr2in' />
  134. <p>See <a href='http://tigcc.ticalc.org/doc/gnuexts.html#SEC100'> Alternate Keywords</a>.</p>
  135. </div></div>
  136. <div class='c2'>
  137. <hr class='hr2' /><h2 class='heading'><a name='__builtin_constant_p'></a><a href='extensions.html#__builtin_constant_p'><code>__builtin_constant_p</code></a></h2><div class='c2in'><hr class='hr2in' />
  138. <p>See <a href='http://tigcc.ticalc.org/doc/gnuexts.html#SEC104___builtin_constant_p'> __builtin_constant_p</a>.</p>
  139. </div></div>
  140. <div class='c2'>
  141. <hr class='hr2' /><h2 class='heading'><a name='Mixed.Declarations.and.Code'></a>Mixed Declarations and Code</h2><div class='c2in'><hr class='hr2in' />
  142. <p>See <a href='http://tigcc.ticalc.org/doc/gnuexts.html#SEC107'> Mixed Declarations and Code</a>.</p>
  143. </div></div>
  144. <div class='c2'>
  145. <hr class='hr2' /><h2 class='heading'><a name='Unnamed.struct.2funion.Fields.within.structs.2funions'></a>Unnamed struct/union Fields within structs/unions</h2><div class='c2in'><hr class='hr2in' />
  146. <p>See <a href='http://tigcc.ticalc.org/doc/gnuexts.html#SEC108'> Unnamed struct/union Fields within structs/unions</a>.</p>
  147. </div></div>
  148. </div></div>
  149. <div class='c1'>
  150. <hr class='hr1' /><h1 class='heading'><a name='GTC-specific.extensions'></a>GTC-specific extensions</h1><div class='c1in'><hr class='hr1in' /><div class='c2'>
  151. <hr class='hr2' /><h2 class='heading'><a name='incbin.directive'></a><a href='extensions.html#incbin.directive'><code>incbin</code></a><span class='widespace'>&#32;</span>directive</h2><div class='c2in'><hr class='hr2in' />
  152. <p>It is sometimes convenient to include binary files directly into your program, for example when using sprites. The<span class='widespace'>&#32;</span><a href='extensions.html#incbin.directive'><code>incbin</code></a><span class='widespace'>&#32;</span>directives allows you to do just that, without having to convert your data to a decimal or hexadecimal header (which can be memory-consuming on a TI).</p>
  153. <div class='c3'>
  154. <hr class='hr3' /><h3 class='heading'><a name='Using.incbin.to.declare.a.C.array'></a>Using<span class='widespace'>&#32;</span><a href='extensions.html#incbin.directive'><code>incbin</code></a><span class='widespace'>&#32;</span>to declare a C array</h3><div class='c3in'><hr class='hr3in' />
  155. <p>You can use<span class='widespace'>&#32;</span><a href='extensions.html#incbin.directive'><code>incbin</code></a><span class='widespace'>&#32;</span>to initialize the contents of a C array:</p>
  156. <pre>
  157. // The following declares a sprite using normal C initializers
  158. short sprite1[] = {
  159. 0xFFFF, 0x8008, 0x8008, 0xFFFF,
  160. 0xFF00, 0x8800, 0x8800, 0x8800,
  161. 0x00FF, 0x0088, 0x0088, 0x0088,
  162. 0xFFFF, 0x8008, 0x8008, 0xFFFF,
  163. };
  164. // The following declares a sprite using <a href='extensions.html#incbin.directive'><code>incbin</code></a>,
  165. // reading the contents from the file <em>sprite.bin</em>
  166. short sprite2[] = incbin "sprite.bin";
  167. </pre>
  168. <p>The first declaration creates an array of 16 shorts containing the hexadecimal numbers provided.
  169. The second declaration creates an array of 16 shorts whose representation in memory will be the same as<span class='widespace'>&#32;</span><code>sprite.bin</code>.</p>
  170. <p>Note that for the sake of portability,<span class='widespace'>&#32;</span><a href='http://tigcc.ticalc.org/doc/default.html#import_binary'><code>import_binary</code></a><span class='widespace'>&#32;</span>can be a useful
  171. alternative, although there are several caveats: you will have to manually
  172. declare the size of the array if<span class='widespace'>&#32;</span><code>sizeof</code><span class='widespace'>&#32;</span>is to be used, and you cannot use it
  173. to declare a static array inside a function.</p>
  174. </div></div>
  175. <div class='c3'>
  176. <hr class='hr3' /><h3 class='heading'><a name='Using.incbin.within.an.asm.7b.7d.statement'></a>Using<span class='widespace'>&#32;</span><a href='extensions.html#incbin.directive'><code>incbin</code></a><span class='widespace'>&#32;</span>within an<span class='widespace'>&#32;</span><a href='extensions.html#asm.7b.7d.statement'><code>asm{}</code></a><span class='widespace'>&#32;</span>statement</h3><div class='c3in'><hr class='hr3in' />
  177. <p>Like in <a href='glossary.html#a68k'>a68k</a>, you can also use<span class='widespace'>&#32;</span><a href='extensions.html#incbin.directive'><code>incbin</code></a><span class='widespace'>&#32;</span>inside an<span class='widespace'>&#32;</span><a href='extensions.html#asm.7b.7d.statement'><code>asm{}</code></a><span class='widespace'>&#32;</span>statement to insert binary data.</p>
  178. <pre>
  179. asm {
  180. // Insert the values 1,2,3,4 after <code>label1</code>
  181. label1:
  182. dc.w 1,2
  183. dc.w 3,4
  184. // Insert the content of <code>sprite.bin</code> after <code>label2</code>
  185. label2:
  186. incbin "sprite.bin"
  187. };
  188. </pre></div></div>
  189. </div></div>
  190. <div class='c2'>
  191. <hr class='hr2' /><h2 class='heading'><a name='asm.7b.7d.statement'></a><a href='extensions.html#asm.7b.7d.statement'><code>asm{}</code></a><span class='widespace'>&#32;</span>statement</h2><div class='c2in'><hr class='hr2in' />
  192. <p>GTC allows you to program in <a href='glossary.html#Assembly'>assembly</a>, with a syntax very close to that of <a href='glossary.html#a68k'>a68k</a>. In fact, it is powerful enough to write full assembly programs using only GTC!</p>
  193. <div class='c3'>
  194. <hr class='hr3' /><h3 class='heading'><a name='Inserting.an.asm.7b.7d.statement.in.the.code'></a>Inserting an<span class='widespace'>&#32;</span><a href='extensions.html#asm.7b.7d.statement'><code>asm{}</code></a><span class='widespace'>&#32;</span>statement in the code</h3><div class='c3in'><hr class='hr3in' /><div class='c4'>
  195. <hr class='hr4' /><h4 class='heading'><a name='Global.asm.7b.7d.statements'></a>Global<span class='widespace'>&#32;</span><a href='extensions.html#asm.7b.7d.statement'><code>asm{}</code></a><span class='widespace'>&#32;</span>statements</h4><div class='c4in'><hr class='hr4in' />
  196. <p>You can insert assembly code at the global level, for example:</p>
  197. <pre>
  198. asm {
  199. add_3_and_multiply_by_5:
  200. add.w #3,d0
  201. mulu #5,d0
  202. rts
  203. };
  204. </pre>
  205. <p>This creates an assembly function named<span class='widespace'>&#32;</span><code>add_3_and_multiply_by_5</code><span class='widespace'>&#32;</span>that takes an input argument in<span class='widespace'>&#32;</span><code>d0</code>, adds 3 to it, multiplies it by 5, and returns the result in<span class='widespace'>&#32;</span><code>d0</code>.</p>
  206. <p>To use such a function in C code, you need to <a href='missing.html' class='invalidlink'>prototype</a> it:</p>
  207. <pre>
  208. short add_3_and_multiply_by_5(short x);
  209. </pre>
  210. <p>This tells GTC that your function takes a<span class='widespace'>&#32;</span><code>short</code><span class='widespace'>&#32;</span>named<span class='widespace'>&#32;</span><code>x</code><span class='widespace'>&#32;</span>as an input, and outputs a<span class='widespace'>&#32;</span><code>short</code>. Because of the <a href='specificities.html#Calling.convention'>calling convention</a>,<span class='widespace'>&#32;</span><code>x</code><span class='widespace'>&#32;</span>will be placed in<span class='widespace'>&#32;</span><code>d0</code>: see <a href='specificities.html#Default.calling.convention..28regparm.29'>default calling convention</a> for more information on where input arguments to assembly functions will be located.</p>
  211. </div></div>
  212. <div class='c4'>
  213. <hr class='hr4' /><h4 class='heading'><a name='Inline.asm.7b.7d.statements'></a>Inline<span class='widespace'>&#32;</span><a href='extensions.html#asm.7b.7d.statement'><code>asm{}</code></a><span class='widespace'>&#32;</span>statements</h4><div class='c4in'><hr class='hr4in' />
  214. <p>You can also insert assembly code within a function. This has the advantage over global assembly functions to eliminate the overhead associated with a function call.</p>
  215. <pre>
  216. void do_something(char *command) {
  217. if (!strcmp(command,"off"))
  218. asm { trap #4 };
  219. else
  220. printf("unknown command!\n");
  221. }
  222. </pre>
  223. <p>This functions turns off the calculator when<span class='widespace'>&#32;</span><code>command</code><span class='widespace'>&#32;</span>is<span class='widespace'>&#32;</span><code>"off"</code>, by calling<span class='widespace'>&#32;</span><code>trap #4</code>.</p>
  224. </div></div>
  225. </div></div>
  226. <div class='c3'>
  227. <hr class='hr3' /><h3 class='heading'><a name='Structure.of.an.asm.7b.7d.statement'></a>Structure of an<span class='widespace'>&#32;</span><a href='extensions.html#asm.7b.7d.statement'><code>asm{}</code></a><span class='widespace'>&#32;</span>statement</h3><div class='c3in'><hr class='hr3in' />
  228. <p>An<span class='widespace'>&#32;</span><a href='extensions.html#asm.7b.7d.statement'><code>asm{}</code></a><span class='widespace'>&#32;</span>statement is comprised of a set of declarations between the outer<span class='widespace'>&#32;</span><code>{</code><span class='widespace'>&#32;</span>and<span class='widespace'>&#32;</span><code>}</code><span class='widespace'>&#32;</span>braces.
  229. A declaration can be:</p>
  230. <ul><li> a <a href='glossary.html#68000'>68000</a> instruction, e.g.<span class='widespace'>&#32;</span><code>moveq #123,d0</code><span class='widespace'>&#32;</span></li><li> a label definition, e.g.<span class='widespace'>&#32;</span><code>my_function:</code><span class='widespace'>&#32;</span></li><li> a data declaration, e.g.<span class='widespace'>&#32;</span><code>dc.w 123,456,789</code><span class='widespace'>&#32;</span>or<span class='widespace'>&#32;</span><code>incbin "data.bin"</code><span class='widespace'>&#32;</span></li></ul>
  231. <p>You must separate different declarations either:</p>
  232. <ul><li> by putting them on separate lines
  233. </li><li> by simply concatenating them if the first is a label
  234. </li><li> by separating them with a semicolon (<code>;</code>) -- however you should absolutely avoid doing this outside<span class='widespace'>&#32;</span><a href='preprocessor.html#.23define'><code>#define</code></a>, as the behaviour may change some day
  235. </li></ul></div></div>
  236. <div class='c3'>
  237. <hr class='hr3' /><h3 class='heading'><a name='asm.7b.7d.interpretation.rules'></a><a href='extensions.html#asm.7b.7d.statement'><code>asm{}</code></a><span class='widespace'>&#32;</span>interpretation rules</h3><div class='c3in'><hr class='hr3in' />
  238. <p>The behaviour of GTC is indeed very close to that of<span class='widespace'>&#32;</span><a href='glossary.html#a68k'><code>a68k</code></a>. Like<span class='widespace'>&#32;</span><a href='glossary.html#a68k'><code>a68k</code></a>, GTC tries to optimize instructions when it is possible, for example<span class='widespace'>&#32;</span><code>add.w #3,d0</code><span class='widespace'>&#32;</span>will be optimized to<span class='widespace'>&#32;</span><code>addq.w #3,d0</code>. Like<span class='widespace'>&#32;</span><a href='glossary.html#a68k'><code>a68k</code></a>, you don't need to add a<span class='widespace'>&#32;</span><code>:</code><span class='widespace'>&#32;</span>after label names: however, while with<span class='widespace'>&#32;</span><a href='glossary.html#a68k'><code>a68k</code></a><span class='widespace'>&#32;</span>you can only do so if the label is placed on the first char of the line, with GTC you can do so any time as long as the label does not correspond to an assembly instruction.</p>
  239. <p>The most notable difference is perhaps that, where<span class='widespace'>&#32;</span><a href='glossary.html#a68k'><code>a68k</code></a><span class='widespace'>&#32;</span>uses specific commands like<span class='widespace'>&#32;</span><code>equ</code><span class='widespace'>&#32;</span>and<span class='widespace'>&#32;</span><code>equr</code><span class='widespace'>&#32;</span>to define macros, GTC simply uses the C preprocessor. This is very powerful, as it allows you to define constants just once and reuse them in C code. You can also use normal C conditionals like<span class='widespace'>&#32;</span><code>#if</code><span class='widespace'>&#32;</span>or<span class='widespace'>&#32;</span><code>#ifdef</code>, making conditional compilation easier.
  240. You can also interface your code with C much more easily, for example you have access to the<span class='widespace'>&#32;</span><code>sizeof</code><span class='widespace'>&#32;</span>operator:</p>
  241. <pre>
  242. int table[] = { 1,2,3,4 };
  243. asm {
  244. negate_table:
  245. lea table,a0
  246. moveq #sizeof(table)/2-1,d0
  247. \loop
  248. neg.w (a0)+
  249. dbra d0,\loop
  250. rts
  251. };
  252. </pre>
  253. <p>After execution of<span class='widespace'>&#32;</span><code>negate_table</code>,<span class='widespace'>&#32;</span><code>table</code><span class='widespace'>&#32;</span>will be equal to<span class='widespace'>&#32;</span><code>{ -1,-2,-3,-4 }</code>.</p>
  254. <p>Note the<span class='widespace'>&#32;</span><code>\</code><span class='widespace'>&#32;</span>in<span class='widespace'>&#32;</span><code>\loop</code>: this means that the label is local. However, this notion differs slightly from that of<span class='widespace'>&#32;</span><a href='glossary.html#a68k'><code>a68k</code></a>: while the label is only valid between the surrounding two global labels in<span class='widespace'>&#32;</span><a href='glossary.html#a68k'><code>a68k</code></a>, the label is valid throughout the<span class='widespace'>&#32;</span><a href='extensions.html#asm.7b.7d.statement'><code>asm{}</code></a><span class='widespace'>&#32;</span>statement in GTC. It is often more convenient, as this example shows:</p>
  255. <pre>
  256. asm {
  257. \return_with_error
  258. moveq #-1,d0
  259. rts
  260. my_function:
  261. addq.w #5,d0
  262. bmi.s \return_with_error
  263. tst.w d1
  264. bmi.s \return_with_error
  265. ... very long code (longer than 128 bytes) ...
  266. rts
  267. };
  268. </pre>
  269. <p>In this example,<span class='widespace'>&#32;</span><code>\return_with_error</code><span class='widespace'>&#32;</span>is placed <em>before</em><span class='widespace'>&#32;</span><code>my_function</code><span class='widespace'>&#32;</span>because it allows the branches to<span class='widespace'>&#32;</span><code>\return_with_error</code><span class='widespace'>&#32;</span>to be short branches (<code>bmi.s</code>, 2 bytes) rather than long branches (<code>bmi.w</code>, 4 bytes). If GTC followed the rules of<span class='widespace'>&#32;</span><a href='glossary.html#a68k'><code>a68k</code></a>, then it would require<span class='widespace'>&#32;</span><code>\return_with_error</code><span class='widespace'>&#32;</span>to be a global, which can be inconvenient if you have lots of these. Instead, it allows you to structurally divide your program in logical<span class='widespace'>&#32;</span><a href='extensions.html#asm.7b.7d.statement'><code>asm{}</code></a><span class='widespace'>&#32;</span>blocks.</p>
  270. </div></div>
  271. <div class='c3'>
  272. <hr class='hr3' /><h3 class='heading'><a name='Extra.features.of.asm.7b.7d.statements'></a>Extra features of<span class='widespace'>&#32;</span><a href='extensions.html#asm.7b.7d.statement'><code>asm{}</code></a><span class='widespace'>&#32;</span>statements</h3><div class='c3in'><hr class='hr3in' />
  273. <p>Because<span class='widespace'>&#32;</span><a href='extensions.html#asm.7b.7d.statement'><code>asm{}</code></a><span class='widespace'>&#32;</span>statements rely on the C compiler architecture of GTC, there are lots of nice features, for example:</p>
  274. <pre>
  275. #define USE_KERNEL
  276. #include &lt;std.h&gt;
  277. asm {
  278. _main:
  279. pea "Hello, world!"(pc)
  280. jsr ST_helpMsg
  281. addq.l #4,a7
  282. rts
  283. };
  284. </pre>
  285. <p>What's most interesting in all this is that the C library required <b>no modification whatsoever</b> to allow using ROM calls in such a way: ROM calls are not defined twice, and there isn't even a conditional statement acting differently inside<span class='widespace'>&#32;</span><a href='extensions.html#asm.7b.7d.statement'><code>asm{}</code></a><span class='widespace'>&#32;</span>code and inside C code!
  286. This is possible because the assembler was able to interpret the C construct corresponding to<span class='widespace'>&#32;</span><code>ST_helpMsg</code>.</p>
  287. </div></div>
  288. <div class='c3'>
  289. <hr class='hr3' /><h3 class='heading'><a name='asm.7b.7d.special.operator.3a.__c__'></a><a href='extensions.html#asm.7b.7d.statement'><code>asm{}</code></a><span class='widespace'>&#32;</span>special operator:<span class='widespace'>&#32;</span><a href='extensions.html#asm.7b.7d.special.operator.3a.__c__'><code>__c__</code></a></h3><div class='c3in'><hr class='hr3in' />
  290. <p>This is an operator reserved to operands of instructions in<span class='widespace'>&#32;</span><a href='extensions.html#asm.7b.7d.statement'><code>asm{}</code></a><span class='widespace'>&#32;</span>statements.</p>
  291. <p>The reason why this operator exists is simple: assembly and C each have different arithmetic rules. For example, if you have the following code:</p>
  292. <pre>
  293. int table[] = { 1,2,3,4 };
  294. </pre>
  295. <p>then, while in C<span class='widespace'>&#32;</span><code>table+2</code><span class='widespace'>&#32;</span>will designate the address of<span class='widespace'>&#32;</span><code>table[2]</code><span class='widespace'>&#32;</span>(the number<span class='widespace'>&#32;</span><code>3</code>), in assembly<span class='widespace'>&#32;</span><code>table+2</code><span class='widespace'>&#32;</span>will designate the address of<span class='widespace'>&#32;</span><code>table[0]</code><span class='widespace'>&#32;</span>plus 2 bytes, which happens to be the address of<span class='widespace'>&#32;</span><code>table[1]</code>.</p>
  296. <p>So when you write:</p>
  297. <pre>
  298. asm {
  299. load_address:
  300. lea table+2(pc),a0
  301. rts
  302. };
  303. </pre>
  304. <p>then, as you would expect from assembly code,<span class='widespace'>&#32;</span><code>table+2</code><span class='widespace'>&#32;</span>corresponds to the address given by assembly arithmetic rules.</p>
  305. <p>This works with<span class='widespace'>&#32;</span><a href='preprocessor.html#.23define'><code>#define</code></a><span class='widespace'>&#32;</span>statements too:</p>
  306. <pre>
  307. asm {
  308. load_address:
  309. #define my_item table+2
  310. lea my_item(pc),a0
  311. rts
  312. };
  313. </pre>
  314. <p>But GTC allows you to do much more: you may want to access information that requires access to the full typing system of C, not just the addresses of different objects.
  315. The way you can access this typing system is by the<span class='widespace'>&#32;</span><a href='extensions.html#asm.7b.7d.special.operator.3a.__c__'><code>__c__</code></a><span class='widespace'>&#32;</span>operator: if you write</p>
  316. <pre>
  317. asm {
  318. load_address:
  319. lea __c__(table+2)(pc),a0
  320. rts
  321. };
  322. </pre>
  323. <p>then<span class='widespace'>&#32;</span><code>table+2</code><span class='widespace'>&#32;</span>will not be interpreted according to assembly rules, but according to C rules: that is,<span class='widespace'>&#32;</span><code>__c__(table+2)</code><span class='widespace'>&#32;</span>is the adress of<span class='widespace'>&#32;</span><code>table[2]</code>.</p>
  324. <p>GTC goes one step further, by automatically enclosing<span class='widespace'>&#32;</span><a href='preprocessor.html#.23define'><code>#define</code>s</a> written as part of C code in the<span class='widespace'>&#32;</span><a href='extensions.html#asm.7b.7d.special.operator.3a.__c__'><code>__c__</code></a><span class='widespace'>&#32;</span>operator:</p>
  325. <pre>
  326. int table[] = { 1,2,3,4 };
  327. #define third_item &amp;table[2] // note: <em>table+2</em> would give the same results
  328. int *c_load_address() {
  329. return third_item;
  330. }
  331. asm {
  332. load_address:
  333. lea third_item(pc),a0
  334. rts
  335. };
  336. </pre>
  337. <p>Here both<span class='widespace'>&#32;</span><code>c_load_address()</code><span class='widespace'>&#32;</span>and<span class='widespace'>&#32;</span><code>load_address()</code><span class='widespace'>&#32;</span>do the same thing, without ever having to define<span class='widespace'>&#32;</span><code>third_item</code><span class='widespace'>&#32;</span>twice!</p>
  338. </div></div>
  339. </div></div>
  340. <div class='c2'>
  341. <hr class='hr2' /><h2 class='heading'><a name='.40.40.prefix'></a><a href='extensions.html#.40.40.prefix'><code>@@</code></a><span class='widespace'>&#32;</span>prefix</h2><div class='c2in'><hr class='hr2in' />
  342. <p>The prefix<span class='widespace'>&#32;</span><a href='extensions.html#.40.40.prefix'><code>@@</code></a><span class='widespace'>&#32;</span>can be prepended to any identifier to prevent it from being <a href='missing.html' class='invalidlink'>expanded</a> by the <a href='missing.html' class='invalidlink'>preprocessor</a>.
  343. For example,<span class='widespace'>&#32;</span><code>@@MY_SYMBOL</code><span class='widespace'>&#32;</span>will expand to<span class='widespace'>&#32;</span><code>MY_SYMBOL</code><span class='widespace'>&#32;</span>even if<span class='widespace'>&#32;</span><code>MY_SYMBOL</code><span class='widespace'>&#32;</span>has been<span class='widespace'>&#32;</span><a href='preprocessor.html#.23define'><code>#define</code>d</a> to expand to<span class='widespace'>&#32;</span><code>0x1234</code>.</p>
  344. <p>This is not very useful in normal C code, but it can be useful in conjunction with other GTC extensions, mainly<span class='widespace'>&#32;</span><a href='extensions.html#asm.7b.7d.statement'><code>asm{}</code></a><span class='widespace'>&#32;</span>statements and <a href='missing.html' class='invalidlink'>pre-compiled headers</a>.</p>
  345. </div></div>
  346. </div></div></div>
  347. </body>
  348. </html>