doc/language.html

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
   3     "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
   4     <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" >
   5 <head>
   6 <title>The Voodoo Programming Language</title>
   7 <link rel="stylesheet" href="style.css" type="text/css" />
   8 </head>
   9 <body>
  10 <div class="body">
  11 <h1>The Voodoo Programming Language</h1><p class="first">A Voodoo program consists of a data, function
  12 definitions, and code. All of these are introduced by magic words such
  13 as <code>function</code>, <code>call</code>, and
  14 <code>string</code>. Any part of the program may be preceded by a
  15 label, and labels can be referred to from the code. Finally, a program
  16 is divided into a data section and a code section.</p>
  17
  18 <h2>Hello World in Voodoo</h2>
  19
  20 <p class="first">To quickly get a feeling for a programming language,
  21 it is often instructive to look at a simple yet complete program.
  22 The following is an implementation of the traditional
  23 Hello World program in Voodoo:</p>
  24
  25 <pre><code>
  26 #### Hello world in Voodoo
  27
  28 section data
  29 greeting:
  30 string "Hello, world!\x00"
  31
  32 section functions
  33 import puts
  34 export main
  35
  36 main:
  37 function argc argv
  38     call puts greeting
  39     return 0
  40 end function
  41 </code></pre>
  42
  43 <p class="first">When compiled and linked with a library that provides
  44 an appropriate implementation of the <code>puts</code> function, this
  45 program will print <q>Hello, world!</q>.</p>
  46
  47 <p>What follows is a more formal description of the Voodoo
  48 programming language.</p>
  49
  50 <h2>Tokens</h2>
  51
  52 <h3>Comments</h3>
  53
  54 <p class="first">Comments start with a hash mark (#) and run until
  55 the end of the line. The following is an example comment:</p>
  56
  57 <pre><code>
  58 # This is an example comment
  59 </code></pre>
  60
  61 <h3>Integers</h3>
  62
  63 <p class="first">Integers consist of an optional plus or minus sign,
  64 followed by one or more digits. Examples of valid integers:</p>
  65
  66 <pre><code>
  67 0
  68 +12
  69 -1
  70 </code></pre>
  71
  72 <h3>Strings</h3>
  73
  74 <p class="first">Strings consist of zero or more characters enclosed in double
  75 quotes. Examples of valid strings:</p>
  76
  77 <pre><code>
  78 ""
  79 "Hello, world!"
  80 </code></pre>
  81
  82 <h3>Symbols</h3>
  83
  84 <p class="first">Symbols consist of letters, digits, underscores, and
  85 hyphens, although only a letter or an underscore is allowed as the first
  86 character of a symbol. Examples of valid symbols:</p>
  87
  88 <pre><code>
  89 foo
  90 some-symbol
  91 </code></pre>
  92
  93 <h2>Escape Sequences</h2>
  94
  95 <p class="first">To facilitate entering special characters and to
  96 inhibit the special meaning certain characters normally have, an
  97 escape mechanism is provided. Escape sequences start with a backslash,
  98 and have the following meanings:</p>
  99
 100 <pre>
 101 \\        An actual backslash character
 102 \"        A double quote character
 103 \n        A newline
 104 \r        A carriage return character
 105 \t        A tab character
 106 \xXX      The character with hexadecimal value XX
 107 \&lt;space&gt;  A space character
 108 \&lt;newline&gt; Line continuation character. The newline
 109            and any leading whitespace on the next line
 110            is ignored.
 111 </pre>
 112
 113 <p class="first">Examples of the usage of the escape characters:</p>
 114
 115 <table summary="Example Escape Sequences"><tr>
 116 <td><code>"Hello&nbsp;world\n"</code></td>
 117 <td>A string with a newline in it</td>
 118 </tr><tr>
 119 <td><code>"\\\""</code></td>
 120 <td>A string consisting of a backslash followed by a double quote</td>
 121 </tr><tr>
 122 <td><code>call foo \<br />
 123  bar</code></td>
 124 <td>Same as: <code>call&nbsp;foo&nbsp;bar</code></td>
 125 </tr></table>
 126
 127 <h2>Labels</h2>
 128
 129 <p class="first">Places in a program can be marked with labels, so
 130 that the place can be referred to from the code by mentioning the
 131 label. A label consists of a symbol followed by a colon. When
 132 referring to a label, only the symbol is used.</p>
 133
 134 <p class="first">For example:</p>
 135
 136 <pre><code>
 137 foo:
 138 word 12
 139 </code></pre>
 140
 141 <p class="first">declares a word with the value 12, and a label 'foo'
 142 that refers to the place where this value is stored. For example, if
 143 the value happens to be loaded at the address 71234, writing 'foo' in
 144 the program will have the same effect as writing 71234 in the same
 145 place.</p>
 146
 147 <h2>Values</h2>
 148
 149 <p class="first">Values are the smallest unit of data in a Voodoo
 150 program. Examples of values are:</p>
 151
 152 <table summary="Example Values"><tr>
 153 <td><code>12</code></td>
 154 <td>The integer 12</td>
 155 </tr><tr>
 156 <td><code>x</code></td>
 157 <td>The value of x (may be a label or a local variable)</td>
 158 </tr></table>
 159
 160 <p class="first">In the rest of this document, '&lt;x&gt;',
 161 '&lt;y&gt;' and '&lt;z&gt;' will be used to indicate
 162 arbitrary values.</p>
 163
 164 <h2>Actions</h2>
 165
 166 <p class="first">Voodoo code consists of actions. Actions consist of a
 167 magic word, usually followed by a number of values. This section lists
 168 all actions supported by Voodoo. In the list below, '&lt;x&gt;',
 169 '&lt;y&gt;', and '&lt;z&gt;' denote values, '&lt;symbol&gt;' denotes a
 170 symbol, and '&lt;expr&gt;' denotes an expression.
 171 (expressions are discussed further on).</p>
 172
 173 <dl>
 174 <dt><code>call &lt;x&gt; &lt;y&gt; &lt;z&gt; &hellip;</code></dt>
 175 <dd>Calls the function &lt;x&gt; with the arguments &lt;y&gt;
 176 &lt;z&gt; &hellip;. There may be zero or more arguments.</dd>
 177
 178 <dt><code>goto &lt;x&gt;</code></dt>
 179 <dd>Continues the program at location &lt;x&gt;, rather than at the
 180 next action after the goto.</dd>
 181
 182 <dt><code>let &lt;symbol&gt; &lt;expr&gt;</code></dt>
 183 <dd>Introduces a local variable &lt;symbol&gt;, and initializes it to
 184 the result of evaluating &lt;expr&gt;.
 185
 186 This action is only allowed on function level; that is, between
 187 <code>function</code> and the corresponding <code>end function</code>,
 188 and not inside an <code>if&hellip; end if</code> block.
 189
 190 The scope of a variable introduced by <code>let</code> includes
 191 every statement after the <code>let</code> action and before the
 192 <code>end function</code> that ends the function in which the
 193 variable is introduced.</dd>
 194
 195 <dt><code>return &lt;expr&gt;</code></dt>
 196 <dd>Evaluates &lt;expr&gt; and returns the result from the current
 197 function.</dd>
 198
 199 <dt><code>set &lt;symbol&gt; &lt;expr&gt;</code></dt>
 200 <dd>Evaluates &lt;expr&gt; and assigns the result to
 201 &lt;symbol&gt;. &lt;symbol&gt; may not be a label, because labels cannot be
 202 assigned to.</dd>
 203
 204 <dt><code>set-byte &lt;base&gt; &lt;offset&gt; &lt;x&gt;</code></dt>
 205 <dd>Sets the byte at &lt;base&gt; + &lt;offset&gt; to &lt;x&gt;.
 206 &lt;offset&gt; is given as a number of bytes.</dd>
 207
 208 <dt><code>set-word &lt;base&gt; &lt;offset&gt; &lt;x&gt;</code></dt>
 209 <dd>Sets the word at &lt;base&gt; + WORDSIZE * &lt;offset&gt; to &lt;x&gt;.
 210
 211 The address computed by &lt;base&gt; + WORDSIZE * &lt;offset&gt;
 212 is expected to be a multiple of the word size.
 213 The behavior of <code>set-word</code> is undefined if this condition
 214 is not satisfied.
 215 </dd>
 216
 217 <dt><code>tail-call &lt;x&gt; &lt;y&gt; &lt;z&gt; ...</code></dt>
 218 <dd>Performs a tail call to the function &lt;x&gt; with arguments
 219 &lt;y&gt; &lt;z&gt; &hellip;. This has an effect similar to
 220 'return call &lt;x&gt; &lt;y&gt; &lt;z&gt; ...', but re-uses
 221 the call frame of the current function. This means that if &lt;x&gt;
 222 takes fewer or at most as many arguments as the current function,
 223 the tail call requires no extra space.</dd>
 224 </dl>
 225
 226 <h2>Expressions</h2>
 227
 228 <p class="first">Certain actions have the ability to evaluate
 229 expressions. Expressions can be simple values, but expressions can
 230 also perform computations on values. The following are valid
 231 expressions:</p>
 232
 233 <dl>
 234 <dt><code>add &lt;x&gt; &lt;y&gt;</code></dt>
 235 <dd>The result of adding &lt;y&gt; to &lt;x&gt;.
 236
 237 If the result of the addition cannot be represented in a single word,
 238 the result of <code>add</code> is undefined.</dd>
 239
 240 <dt><code>and &lt;x&gt; &lt;y&gt;</code></dt>
 241 <dd>The bitwise and of &lt;x&gt; and &lt;y&gt;.</dd>
 242
 243 <dt><code>call &lt;x&gt; &lt;y&gt; &lt;z&gt; ...</code></dt>
 244 <dd>Similar to the action call, this calls the function &lt;x&gt; with the
 245   arguments &lt;y&gt; &lt;z&gt; ... (there may be zero or more arguments). The
 246   result of this expression is the value returned from the function.</dd>
 247
 248 <dt><code>div &lt;x&gt; &lt;y&gt;</code></dt>
 249 <dd>The (integer) result of dividing &lt;x&gt; by &lt;y&gt;.
 250
 251 If &lt;x&gt; &ge; 0 and &lt;y&gt; &gt; 0, the result is the largest
 252 integer equal to or less than the algebraic quotient of &lt;x&gt;
 253 and &lt;y&gt;.
 254
 255 If either &lt;x&gt; or &lt;y&gt; is negative, the result is
 256 implementation-defined.
 257
 258 If &lt;y&gt; is zero, the result is undefined.</dd>
 259
 260 <dt><code>get-byte &lt;base&gt; &lt;offset&gt;</code></dt>
 261 <dd>The value of the byte at address &lt;base&gt; + &lt;offset&gt;.</dd>
 262
 263 <dt><code>get-word &lt;base&gt; &lt;offset&gt;</code></dt>
 264 <dd>The value of the word at address &lt;base&gt; + (WORDSIZE *
 265 &lt;offset&gt;).
 266
 267 The address computed as &lt;base&gt; + (WORDSIZE * &lt;offset&gt;) is
 268 expected to be a multiple of the word size. If this condition is not met,
 269 the behavior of <code>get-word</code> is undefined.</dd>
 270
 271 <dt><code>mod &lt;x&gt; &lt;y&gt;</code></dt>
 272 <dd>For &lt;x&gt; &ge; 0 and &lt;y&gt; &gt; 0, returns
 273 &lt;x&gt; modulo &lt;y&gt;.
 274
 275 If either &lt;x&gt; or &lt;y&gt; is negative, the result is
 276 implementation-defined.
 277
 278 If &lt;y&gt; is zero, the result is undefined.</dd>
 279
 280 <dt><code>mul &lt;x&gt; &lt;y&gt;</code></dt>
 281 <dd>The result of multiplying &lt;x&gt; by &lt;y&gt;.
 282
 283 If the algebraic result of &lt;x&gt; * &lt;y&gt; cannot be represented
 284 in a single word, the result of <code>mul &lt;x&gt; &lt;y&gt;</code>
 285 contains only the low-order bits of the full result.</dd>
 286
 287 <dt><code>not &lt;x&gt;</code></dt>
 288 <dd>The ones' complement of &lt;x&gt;; i.e. all the bits in &lt;x&gt;
 289 inverted.</dd>
 290
 291 <dt><code>or &lt;x&gt; &lt;y&gt;</code></dt>
 292 <dd>The bitwise or of &lt;x&gt; and &lt;y&gt;.</dd>
 293
 294 <dt><code>sub &lt;x&gt; &lt;y&gt;</code></dt>
 295 <dd>The result of subtracting &lt;y&gt; from &lt;x&gt;.
 296
 297 If the result of the subtraction cannot be represented in a single
 298 word, the result of <code>sub</code> is undefined.</dd>
 299
 300 <dt><code>xor &lt;x&gt; &lt;y&gt;</code></dt>
 301 <dd>The bitwise exclusive or of &lt;x&gt; and &lt;y&gt;.</dd>
 302 </dl>
 303
 304 <h2>Conditionals</h2>
 305
 306 <p class="first">Conditionals in Voodoo take the following form:</p>
 307
 308 <pre><code>if&lt;test&gt;
 309     ... some code here ...
 310 else if&lt;test&gt;
 311     ... other code here ...
 312 ... more "else if" parts ...
 313 else
 314     ... some code ...
 315 end if
 316 </code></pre>
 317
 318 <p class="first">There can be any number of <q>else if</q> parts, and
 319 the final <q>else</q> clause is optional. The tests that are provided
 320 are the following:</p>
 321
 322 <dl>
 323 <dt><code>ifeq &lt;x&gt; &lt;y&gt;</code></dt>
 324 <dd>Tests if &lt;x&gt; is equal to &lt;y&gt;.</dd>
 325
 326 <dt><code>ifge &lt;x&gt; &lt;y&gt;</code></dt>
 327 <dd>Tests if &lt;x&gt; is greater than or equal to &lt;y&gt;.</dd>
 328
 329 <dt><code>ifgt &lt;x&gt; &lt;y&gt;</code></dt>
 330 <dd>Tests if &lt;x&gt; is strictly greater than &lt;y&gt;.</dd>
 331
 332 <dt><code>ifle &lt;x&gt; &lt;y&gt;</code></dt>
 333 <dd>Tests if &lt;x&gt; is less than or equal to &lt;y&gt;.</dd>
 334
 335 <dt><code>iflt &lt;x&gt; &lt;y&gt;</code></dt>
 336 <dd>Tests if &lt;x&gt; is strictly less than &lt;y&gt;.</dd>
 337
 338 <dt><code>ifne &lt;x&gt; &lt;y&gt;</code></dt>
 339 <dd>Tests if &lt;x&gt; is different from &lt;y&gt;.</dd>
 340 </dl>
 341
 342 <h2>Function Definitions</h2>
 343
 344 <p class="first">A function definition looks like:</p>
 345
 346 <pre><code>
 347 function x y z
 348     &lt;code&gt;
 349 end function
 350 </code></pre>
 351
 352 <p class="first">Here, the function being defined takes 3 arguments,
 353 which can be referred to as <code>x</code>, <code>y</code>, and
 354 <code>z</code> from the code inside the function body. A function may
 355 have zero or more arguments and is practically always preceded by a
 356 label, so that the function can be referenced from code.</p>
 357
 358 <p>A function should only be entered using <code>call</code> or
 359 <code>tail-call</code>, and should only be left through a
 360 <code>return</code> action. Furthermore, a function should always
 361 be called with the same number of arguments it was defined with.
 362 Failing to meet any of these requirements results in undefined
 363 behavior.</p>
 364
 365 <h2>Sections</h2>
 366
 367 <p class="first">A Voodoo program is divided in a number of sections.
 368 In source code, these are introduced by a directive of the form
 369 <code>section &lt;identifier&gt;</code>, where &lt;identifier&gt; is an
 370 identifier for the section.</p>
 371
 372 <p>The following section identifiers are valid:</p>
 373
 374 <table summary="Section Identifiers"><tr>
 375 <th>Identifier</th>
 376 <th>Meaning</th>
 377 </tr><tr>
 378 <td><code>code</code></td>
 379 <td>This section contains executable code</td>
 380 </tr><tr>
 381 <td><code>data</code></td>
 382 <td>This section contains data</td>
 383 </tr><tr>
 384 <td><code>functions</code></td>
 385 <td>This section contains function definitions</td>
 386 </tr></table>
 387
 388 <p class="first">Example usage of the <code>section</code> directive:</p>
 389
 390 <pre><code>
 391 section data
 392 # define data here ...
 393
 394 section functions
 395 # define functions here ...
 396 </code></pre>
 397
 398 <h2>Alignment</h2>
 399
 400 <p class="first">Many architectures require that data and/or code
 401 obey certain alignment restrictions. For example, an architecture may
 402 require that a word of data be at an address that is a multiple of the
 403 word size. Voodoo provides the <code>align</code> directive, which
 404 specifies the alignment for the next program element.</p>
 405
 406 <p>Without any arguments, <code>align</code> inserts filler bytes
 407 into the current section, so that the next element added to the section
 408 will respect the default alignment for the section. The default
 409 alignment for each section is implementation-dependent, but must ensure
 410 that the alignment restrictions of the target platform are obeyed.</p>
 411
 412 <p>When written as <code>align &lt;n&gt;</code>, where &lt;n&gt; is an
 413 integer, the directive will insert filler bytes as necessary to align
 414 the next element to be added to the section on a multiple of &lt;n&gt;
 415 bytes.</p>
 416
 417 <p>The filler bytes inserted by <code>align</code> are unspecified.
 418 In particular, they are not guaranteed to be valid code.</p>
 419
 420 <p>Example uses of the <code>align</code> directive:</p>
 421
 422 <pre><code>
 423 section data
 424
 425 x:
 426 byte 1
 427
 428 # Ensure that y is aligned according to
 429 # the target platform's alignment restrictions
 430 align
 431 y:
 432 word 42
 433
 434
 435
 436 section functions
 437
 438 # Ensure that foo is aligned according to
 439 # the target platform's alignment restrictions
 440 align
 441 foo:
 442 function n
 443     # some code here
 444 end function
 445 </code></pre>
 446 </div>
 447 </body>
 448 </html>