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>
  12
  13
  14 <p class="first">This document describes version 1.1 of the Voodoo
  15 programming language. Definitions in this document have been marked
  16 with the version of the language in which they have been
  17 introduced. Definitions first introduced by this document have been
  18 marked with <strong class="since current">1.1</strong>.</p>
  19
  20 <h2>Hello World in Voodoo</h2>
  21
  22 <p class="first">To quickly get a feeling for a programming language,
  23 it is often instructive to look at a simple yet complete program.
  24 The following is an implementation of the traditional
  25 Hello World program in Voodoo:</p>
  26
  27 <pre><code>
  28 # Hello world in Voodoo
  29
  30 section data
  31 greeting:
  32 string "Hello, world!\x00"
  33
  34 section functions
  35 import puts
  36 export main
  37
  38 main:
  39 function argc argv
  40     call puts greeting
  41     return 0
  42 end function
  43 </code></pre>
  44
  45 <p class="first">When compiled and linked with a library that provides
  46 an appropriate implementation of the <code>puts</code> function, this
  47 program will print <q>Hello, world!</q>.</p>
  48
  49 <p>What follows is a more formal description of the Voodoo
  50 programming language.</p>
  51
  52 <h2>Overview</h2>
  53
  54 <p class="first">The source code of a Voodoo program consists of
  55 <em>incantations</em> (e.g. <code>set x 42</code>) that define the code
  56 and data of the program.  Each incantation starts with a <em>magic
  57 word</em> (e.g. <code>set</code>) and may have zero or
  58 more <em>parameters</em>. Any incantation may be preceded by
  59 a <em>label</em> (e.g. <code>foo:</code>), which can then be used in
  60 other parts of the program to refer to the <em>address</em> at which the
  61 incantation starts.</p>
  62
  63 <p>The basic units of data in Voodoo are <em>bytes</em>
  64 and <em>words</em>. The range and size of bytes and words is
  65 <em>implementation-defined</em>, which means that the definition
  66 is allowed to differ from one Voodoo implementation to another,
  67 and even in ways defined by a specific implementation, e.g. the
  68 same Voodoo implementation may use different word sizes for
  69 different target platforms.</p>
  70
  71 <p>Most incantations in Voodoo perform very simple operations, such as
  72 adding two numbers. In addition to these simple operations, Voodoo
  73 supports <em>blocks</em> and <em>functions</em>. A block provides a
  74 scope for <em>local variables</em> and automatically managed memory.
  75 Variables and memory allocated inside a block will automatically be
  76 de-allocated after the end of that block. Functions, like blocks,
  77 provide a scope for local variables and automatically managed memory.
  78 In addition, functions may accept <em>parameters</em>, which are local
  79 variables whose values are supplied by the <em>caller</em> of the
  80 function.</p>
  81
  82 <p>At run-time, entering a function or block creates a
  83 <em>frame</em> and makes it the new <em>active frame</em>. These
  84 frames form a chain which logically runs from the <em>top-level
  85 frame</em> at the top to the active frame at the bottom. The active
  86 frame determines what local variables are <em>accessible</em>.
  87 The magic word <code>goto</code> can be used to continue execution
  88 of the program at a given incantation, provided that incantation
  89 is in the scope corresponding to the active frame.</p>
  90
  91 <p>This document does not define the correct behavior of every
  92 possible Voodoo program. In places where the correct behavior is not
  93 defined (either through omission, or explicitly documented as being
  94 undefined), a Voodoo implementation is not required to implement any
  95 specific behavior. In particular, the behavior of a program that
  96 invokes undefined behavior at any point does not have to be repeatable
  97 or desirable. Later versions of the Voodoo language may define correct
  98 behavior for programs whose behavior is undefined under the current
  99 language version.</p>
 100
 101 <h2>Features</h2>
 102 <p class="first"><strong class="since current">1.1</strong> To aid authors and programs in
 103 generating code that is compatible with a particular Voodoo
 104 implementation, implementations should provide means to query their
 105 features. This document specifies a number of features as key-value
 106 pairs, where the key is the feature name, and the value is a string
 107 that provides additional information about the feature (as described
 108 in the specification of the feature).</p>
 109
 110 <p>Implementations may also advertise features not specified in this
 111 document. To prevent conflicts with future versions of Voodoo, these
 112 features should have names starting in a prefix that identifies the
 113 implementation that introduced the feature. Implementations are
 114 encouraged to use this mechanism to advertise support for extensions
 115 to the language specified by this document.</p>
 116
 117 <p>For language extensions advertised using the feature mechanism, it
 118 is recommended that the value of the feature be a version number, with
 119 higher versions being backward compatible with lower versions.
 120 Incompatible changes can be indicated by a different feature name,
 121 e.g. through a numeric suffix at the end of the feature name.</p>
 122
 123 <table summary="Features">
 124 <thead>
 125 <tr><th>Name</th><th>Description</th></tr>
 126 </thead>
 127 <tbody>
 128 <tr>
 129 <td>bits-per-word</td>
 130 <td>The value indicates the number of bits per word for the given
 131 implementation. E.g. <q>32</q>.</td>
 132 </tr>
 133 <tr>
 134 <td>byte-order</td>
 135 <td>Order of bytes in a word. The following values are defined:
 136 <dl>
 137 <dt>big-endian</dt>
 138 <dd>Bytes are ordered from most significant to least significant</dd>
 139 <dt>little-endian</dt>
 140 <dd>Bytes are ordered from least significant to most significant</dd>
 141 </dl></td>
 142 </tr>
 143 <tr>
 144 <td>bytes-per-word</td>
 145 <td>The number of bytes required to store a word. E.g. <q>4</q>.</td>
 146 </tr>
 147 <tr>
 148 <td>voodoo</td>
 149 <td>Version of the Voodoo language supported by the implementation.
 150 The version described in this document is <q>1.1</q>.</td>
 151 </tr>
 152 </tbody>
 153 </table>
 154 <h2>Tokens</h2>
 155 <h3>Comments</h3>
 156
 157 <p class="first"><strong class="since">1.0</strong> Comments start with a hash mark (#)
 158 and run until the end of the line. The following is an example
 159 comment:</p>
 160
 161 <pre><code>
 162 # This is an example comment
 163 </code></pre>
 164
 165 <h3>Integers</h3>
 166
 167 <p class="first"><strong class="since">1.0</strong> Integers consist of an optional
 168 plus or minus sign, followed by one or more digits. Examples of valid
 169 integers:</p>
 170
 171 <pre><code>
 172 0
 173 +12
 174 -1
 175 </code></pre>
 176
 177 <h3>Strings</h3>
 178
 179 <p class="first"><strong class="since">1.0</strong> Strings consist of zero or more
 180 bytes enclosed in double quotes. An escape mechanism is provided to
 181 allow bytes of any value to be included in strings (see
 182 <a href="#escape_sequences">Escape Sequences</a> for details).
 183 Examples of valid strings:</p>
 184
 185 <pre><code>
 186 ""
 187 "Hello, world!"
 188 "some \"escape\x00 sequences"
 189 </code></pre>
 190
 191 <h3>Symbols</h3>
 192
 193 <p class="first"><strong class="since">1.0</strong> Symbols consist of letters, digits,
 194 underscores, hyphens, and escape sequences. Only a letter, underscore,
 195 or escape sequence may be used for the first byte of a
 196 symbol. Although this definition allows any byte to be part of a
 197 symbol, not all symbol names may be compatible with all target
 198 platforms. This document does not specify how implementations
 199 should represent symbols, and thus does not require that all
 200 syntactically valid symbols be usable on every implementation on
 201 every target platform. Examples of valid symbols:</p>
 202
 203 <pre><code>
 204 foo
 205 some_symbol
 206 </code></pre>
 207
 208 <h3>Substitute Tokens</h3>
 209
 210 <p class="first"><strong class="since current">1.1</strong> To aid in the writing of programs
 211 that are portable to multiple target platforms and Voodoo implementations,
 212 Voodoo defines a number of tokens that implementations must substitute
 213 appropriate values for.</p>
 214
 215 <p>A symbol prefixed by a percent character (%) must be treated as
 216 equivalent to an integer value. The following table shows the percent
 217 substitutes that must be recognized by Voodoo implementations:</p>
 218
 219 <table summary="Percent substitutes"><tr>
 220 <th>Symbol</th>
 221 <th>Meaning</th>
 222 </tr><tr>
 223 <td><code>%saved-frame-size</code></td>
 224 <td>The number of bytes required to save a frame</td>
 225 </tr><tr>
 226 <td>any feature that maps to an integer</td>
 227 <td>the integer value of the feature</td>
 228 </tr></table>
 229
 230 <p class="first">The effect of using a substitute token whose meaning
 231 is not defined above is undefined.</p>
 232
 233 <p>Examples of valid substitute tokens:</p>
 234
 235 <table summary="Substitute token examples"><tr>
 236 <td><code>%bytes-per-word</code></td>
 237 <td>number of bytes per word</td>
 238 </tr></table>
 239
 240 <h2>Escape Sequences</h2>
 241
 242 <p class="first"><strong class="since">1.0</strong> To facilitate entering bytes that
 243 may be treated differently by different systems and to inhibit the
 244 special meaning certain bytes normally have, an escape mechanism is
 245 provided. For example, the escape mechanism can be used to create
 246 strings that contain double quotes, or to spread a single incantation
 247 over multiple lines. Escape sequences start with a backslash, and have
 248 the following meanings:</p>
 249
 250 <table summary="Special bytes"><tr>
 251 <td><code>\\</code></td>
 252 <td>An actual backslash</td>
 253 </tr><tr>
 254 <td><code>\"</code></td>
 255 <td>A double quote</td>
 256 </tr><tr>
 257 <td><code>\n</code></td>
 258 <td>A newline</td>
 259 </tr><tr>
 260 <td><code>\r</code></td>
 261 <td>A carriage return</td>
 262 </tr><tr>
 263 <td><code>\t</code></td>
 264 <td>A tab</td>
 265 </tr><tr>
 266 <td><code>\x<var>XX</var></code></td>
 267 <td>The byte with hexadecimal value <var>XX</var></td>
 268 </tr><tr>
 269 <td><code>\&lt;space&gt;</code></td>
 270 <td>A space</td>
 271 </tr><tr>
 272 <td><code>\&lt;newline&gt;</code></td>
 273 <td>Line continuation. The newline
 274 and any leading whitespace on the next line
 275 is ignored.</td>
 276 </tr></table>
 277
 278 <p class="first">Examples of the usage of escape sequences:</p>
 279
 280 <table summary="Example Escape Sequences"><tr>
 281 <td><code>"Hello&nbsp;world\n"</code></td>
 282 <td>A string with a newline in it</td>
 283 </tr><tr>
 284 <td><code>"\\\""</code></td>
 285 <td>A string consisting of a backslash followed by a double quote</td>
 286 </tr><tr>
 287 <td><code>call foo \<br />
 288  bar</code></td>
 289 <td>Same as: <code>call&nbsp;foo&nbsp;bar</code></td>
 290 </tr></table>
 291
 292 <h2>Labels</h2>
 293
 294 <p class="first"><strong class="since">1.0</strong> Places in a program can be marked
 295 with labels, so that the place can be referred to from the code by
 296 mentioning the label. A label consists of a symbol followed by a
 297 colon. When referring to a label, only the symbol is used, without the
 298 colon.</p>
 299
 300 <p class="first">For example:</p>
 301
 302 <pre><code>
 303 foo:
 304 word 12
 305 </code></pre>
 306
 307 <p class="first">declares a word with the value 12, and a label 'foo'
 308 that refers to the place where this value is stored. For example, if
 309 the value happens to be loaded at the address 71234, writing 'foo' in
 310 the program will have the same effect as writing 71234 in the same
 311 place.</p>
 312
 313 <h2>Values</h2>
 314
 315 <p class="first"><strong class="since">1.0</strong> Values are the smallest unit of
 316 data in a Voodoo program. Examples of values are:</p>
 317
 318 <table summary="Example Values"><tr>
 319 <td><code>12</code></td>
 320 <td>The integer 12</td>
 321 </tr><tr>
 322 <td><code>x</code></td>
 323 <td>The value of x (may be a label or a local variable)</td>
 324 </tr></table>
 325
 326 <h2>At-Expressions</h2>
 327
 328 <p class="first"><strong class="since">1.0</strong> The character @ can be used to
 329 denote the value at some address. An address prefixed with @ denotes
 330 the word stored at that address, rather than the address itself. The
 331 address may be an integer, a local variable, or a label. For
 332 example:</p>
 333
 334 <table summary="Example at-expressions"><tr>
 335 <td><code>@12</code></td>
 336 <td>The word stored at address 12</td>
 337 </tr><tr>
 338 <td><code>@x</code></td>
 339 <td>The word stored at address x</td>
 340 </tr></table>
 341
 342 <p class="first">Syntactically, at-expressions are values. Therefore,
 343 in any place where a value can be used, an at-expression can also be
 344 used.</p>
 345
 346 <h2>Sections</h2>
 347
 348 <p class="first"><strong class="since">1.0</strong> A Voodoo program is divided in a number of sections.
 349 In source code, these are introduced by an incantation of the form
 350 <code>section &lt;identifier&gt;</code>, where &lt;identifier&gt; is an
 351 identifier for the section.</p>
 352
 353 <p>The following section identifiers are valid:</p>
 354
 355 <table summary="Section Identifiers"><tr>
 356 <th>Identifier</th>
 357 <th>Meaning</th>
 358 </tr><tr>
 359 <td><code>code</code></td>
 360 <td>This section contains executable code</td>
 361 </tr><tr>
 362 <td><code>data</code></td>
 363 <td>This section contains data</td>
 364 </tr><tr>
 365 <td><code>functions</code></td>
 366 <td>This section contains function definitions</td>
 367 </tr></table>
 368
 369 <p class="first">Example usage of the <code>section</code> incantation:</p>
 370
 371 <pre><code>
 372 section data
 373 # define data here ...
 374
 375 section functions
 376 # define functions here ...
 377 </code></pre>
 378
 379 <p class="first">Sections may appear in the source code in any order.
 380 The same section name may be used multiple times, in which case the
 381 contents of the section will be the concatenation of the contents of
 382 the multiple places in which it is defined.</p>
 383
 384 <h2>Data Definitions</h2>
 385
 386 <p class="first"><strong class="since">1.0</strong> Data can be inserted into a Voodoo
 387 program by means of the magic
 388 words <code>byte</code>, <code>word</code>, and
 389 <code>string</code>, followed by the value of the byte, word, or
 390 string to be inserted. For example:</p>
 391
 392 <pre><code>
 393 # A byte with value 42
 394 byte 42
 395
 396 # A word with value -1
 397 word -1
 398
 399 # The string "hello"
 400 string "hello"
 401 </code></pre>
 402
 403 <h2>Groups</h2>
 404
 405 <p class="first"><strong class="since current">1.1</strong> Groups are a mechanism to group
 406 multiple data definitions into a single unit. For example, to define
 407 a data structure consisting of a word and two bytes:</p>
 408
 409 <pre><code>
 410 example:
 411 group
 412     word 42
 413     byte 0
 414     byte 1
 415 end group
 416 </code></pre>
 417
 418 <h2>Import and Export</h2>
 419
 420 <p class="first"><strong class="since">1.0</strong> To allow Voodoo programs to refer to definitions in
 421 other files, and to allow other files to refer to definitions in
 422 Voodoo programs, the magic words <code>import</code>
 423 and <code>export</code> are used.</p>
 424
 425 <p>Using <code>import</code>, definitions from elsewhere are made
 426 available to a Voodoo program:</p>
 427
 428 <pre><code>
 429 section data
 430 import stderr
 431
 432 section functions
 433 import fputs
 434
 435 # We can now refer to stderr and fputs
 436 </code></pre>
 437
 438 <p>Data and functions defined in a Voodoo program can be made
 439 available to other programs using <code>export</code>:</p>
 440
 441 <pre><code>
 442 section data
 443 export answer
 444
 445 answer:
 446 word 42
 447
 448 section functions
 449 export foo
 450
 451 foo:
 452 function
 453   # some code here
 454 end function
 455 </code></pre>
 456
 457 <p><code>export</code> exports the first definition that follows it.
 458 Groups can be used to group together data that must be exported as a
 459 single unit.</p>
 460
 461 <p>If symbols are imported or exported, the <code>import</code>
 462 or <code>export</code> must occur before the first use of the symbol
 463 in any section. To ensure portability, implementations should reject
 464 programs that do not obey this constraint.</p>
 465
 466 <h2>Alignment</h2>
 467
 468 <p class="first"><strong class="since">1.0</strong> Many architectures require that data and/or code
 469 observe certain alignment restrictions. For example, an architecture may
 470 require that a word of data be at an address that is a multiple of the
 471 word size. Voodoo provides the magic word <code>align</code>, which
 472 specifies the alignment for the next program element.</p>
 473
 474 <p>Without any parameters, <code>align</code> inserts filler bytes
 475 into the current section, so that the next element added to the section
 476 will respect the default alignment for the section. The default
 477 alignment for each section is implementation-defined, but must ensure
 478 that the alignment restrictions of the target platform are observed.</p>
 479
 480 <p>When written as <code>align &lt;n&gt;</code>, where &lt;n&gt; is an
 481 integer, the incantation will insert filler bytes as necessary to align
 482 the next element to be added to the section on a multiple of &lt;n&gt;
 483 bytes.</p>
 484
 485 <p>The filler bytes inserted by <code>align</code> are unspecified.
 486 In particular, they are not guaranteed to be valid code.</p>
 487
 488 <p>Example uses of the <code>align</code> incantation:</p>
 489
 490 <pre><code>
 491 section data
 492
 493 x:
 494 byte 1
 495
 496 # Ensure that y is aligned according to
 497 # the target platform's alignment restrictions
 498 align
 499 y:
 500 word 42
 501
 502
 503
 504 section functions
 505
 506 # Ensure that foo is aligned according to
 507 # the target platform's alignment restrictions
 508 align
 509 foo:
 510 function n
 511     # some code here
 512 end function
 513 </code></pre>
 514
 515 <h2>Actions</h2>
 516
 517 <p class="first">Voodoo code consists of actions. Actions consist of a
 518 magic word, usually followed by a number of values. This section lists
 519 all actions supported by Voodoo. In the list below, '&lt;x&gt;',
 520 '&lt;y&gt;', and '&lt;z&gt;' denote values, '&lt;symbol&gt;' denotes a
 521 symbol, and '&lt;expr&gt;' denotes an expression.  (expressions are
 522 discussed further on). Ellipsis (&hellip;) is used to denote that more
 523 items may follow, and square brackets ([ and ]) are used to denote
 524 that an item is optional.</p>
 525
 526 <dl>
 527
 528 <dt><strong class="since">1.0</strong> <code>call &lt;x&gt; &lt;y&gt; &lt;z&gt;
 529 &hellip;</code></dt>
 530 <dd><p class="first">Calls the function &lt;x&gt; with the parameters &lt;y&gt;
 531 &lt;z&gt; &hellip;. There may be zero or more parameters.</p></dd>
 532
 533 <dt><strong class="since">1.0</strong> <code>goto &lt;x&gt;</code></dt>
 534 <dd><p class="first">Continues the program at location &lt;x&gt;,
 535 rather than at the next action after the goto.</p>
 536
 537 <p>Any value can be used as the location to go to. However, the
 538 consequences of using <code>goto</code> to jump to a label outside
 539 the active frame are undefined. Since frames are introduced by
 540 blocks and functions, this means that <code>goto</code> should
 541 not jump to a label in a different block or function, unless the
 542 frame of that block or function has been restored using
 543 <code>restore-frame</code>.</p></dd>
 544
 545 <dt><strong class="since">1.0</strong> <code>let &lt;symbol&gt; &lt;expr&gt;</code></dt>
 546 <dd><p class="first">Introduces a local variable &lt;symbol&gt;, and
 547 initializes it to the result of evaluating &lt;expr&gt;.</p>
 548
 549 <p>This action is only allowed inside functions or blocks, that is,
 550 between <code>function</code> and the corresponding
 551 <code>end function</code>, or between <code>block</code> and the
 552 corresponding <code>end block</code>.</p>
 553
 554 <p>The scope of a variable introduced by <code>let</code> includes
 555 every statement after the <code>let</code> action and before the
 556 <code>end function</code> or <code>end block</code> that ends the
 557 function or block in which the variable is introduced.</p></dd>
 558
 559 <dt><strong class="since current">1.1</strong> <code>restore-frame &lt;x&gt;</code></dt>
 560
 561 <dd><p class="first">Restores a frame that was saved at address
 562 &lt;x&gt;. After this action, any frames below the restored frame
 563 are no longer valid. The behavior of <code>restore-frame</code> is
 564 undefined if &lt;x&gt; does not contain valid frame information.
 565 The values of local variables are undefined after
 566 <code>restore-frame</code> is performed.</p></dd>
 567
 568 <dt><strong class="since current">1.1</strong> <code>restore-locals &lt;x&gt;
 569     [&lt;locals&gt;]</code></dt>
 570
 571 <dd><p class="first">Sets local variables to values that have been
 572 stored at address &lt;x&gt;. If one or more local variables are
 573 specified, restores the specified local variables. Else, restores
 574 all local variables in scope. The behavior is undefined if the
 575 information saved at &lt;x&gt; does not contain a value for any of
 576 the variables to be restored.</p></dd>
 577
 578 <dt><strong class="since">1.0</strong> <code>return [&lt;expr&gt;]</code></dt>
 579 <dd><p class="first">Returns from the current function.
 580 If &lt;expr&gt; is specified, it is evaluated and the function returns
 581 the result of the evaluation. Otherwise, the return value is
 582 unspecified.</p></dd>
 583
 584 <dt><strong class="since current">1.1</strong> <code>save-frame &lt;x&gt;</code></dt>
 585
 586 <dd><p class="first">Saves information about the current frame to
 587 a block of memory at address &lt;x&gt;. The block of memory must be
 588 large enough to hold the required information. Allocating
 589 <code>%saved-frame-size</code> bytes ensures a block of memory large
 590 enough to hold a saved frame.</p></dd>
 591
 592 <dt><strong class="since current">1.1</strong> <code>save-frame-and-locals &lt;x&gt;
 593     [&lt;locals&gt;]</code></dt>
 594
 595 <dd><p class="first">Saves information about the current frame and
 596 local variables to a block of memory at address &lt;x&gt;. If one or
 597 more local variables are specified, at least the named local variables
 598 are saved. If no local variables are specified, all local variables
 599 are saved.</p>
 600
 601 <p>The block of memory starting at &lt;x&gt; must be large enough to
 602 hold the required
 603 information. Allocating <code>%saved-frame-size</code> bytes ensures a
 604 block of memory large enough to hold a saved frame plus local
 605 variables.</p></dd>
 606
 607 <dt><strong class="since current">1.1</strong> <code>save-locals &lt;x&gt; [&lt;locals&gt;]</code></dt>
 608
 609 <dd><p class="first">Saves local variables to a block of memory at
 610 address &lt;x&gt;. If one or more local variables are specified, at least the
 611 named local variables are saved. If no local variables are specified,
 612 all local variables are saved.</p>
 613
 614 <p>The block of memory starting at &lt;x&gt; must be large enough to
 615 hold the required
 616 information. Allocating <code>%saved-frame-size</code> bytes ensures a
 617 block of memory that is large enough.</p>
 618
 619 <p>This action does not invalidate frame information or local
 620 variables previously stored at &lt;x&gt;, except for updating the
 621 stored values for the local variables it saves to the values these
 622 local variables currently have.</p>
 623 </dd>
 624
 625 <dt><strong class="since">1.0</strong> <code>set &lt;symbol&gt; &lt;expr&gt;</code></dt>
 626 <dd><p class="first">Evaluates &lt;expr&gt; and assigns the result to
 627 &lt;symbol&gt;. &lt;symbol&gt; may not be a label, because labels cannot be
 628 assigned to.</p></dd>
 629
 630 <dt><strong class="since current">1.1</strong> <code>set &lt;at-expr&gt; &lt;expr&gt;</code></dt>
 631 <dd><p class="first">Evaluates &lt;expr&gt; and stores the result at
 632 the address specified by the at-expression &lt;at-expr&gt;.</p></dd>
 633
 634 <dt><strong class="since">1.0</strong> <code>set-byte &lt;base&gt; &lt;offset&gt; &lt;x&gt;</code></dt>
 635 <dd><p class="first">Sets the byte at &lt;base&gt; + &lt;offset&gt; to &lt;x&gt;.
 636 &lt;offset&gt; is given as a number of bytes.</p></dd>
 637
 638 <dt><strong class="since">1.0</strong> <code>set-word &lt;base&gt; &lt;offset&gt; &lt;x&gt;</code></dt>
 639 <dd><p class="first">Sets the word at &lt;base&gt; + WORDSIZE *
 640 &lt;offset&gt; to &lt;x&gt;.</p>
 641
 642 <p>The address computed by &lt;base&gt; + WORDSIZE * &lt;offset&gt;
 643 is expected to be a multiple of the word size.
 644 The behavior of <code>set-word</code> is undefined if this condition
 645 is not satisfied.
 646 </p></dd>
 647
 648 <dt><strong class="since">1.0</strong> <code>tail-call &lt;x&gt; &lt;y&gt; &lt;z&gt; ...</code></dt>
 649 <dd><p class="first">Performs a tail call to the function &lt;x&gt;
 650 with parameters &lt;y&gt; &lt;z&gt; &hellip;. This has an effect
 651 similar to 'return call &lt;x&gt; &lt;y&gt; &lt;z&gt; ...', but
 652 re-uses the call frame of the current function. This means that if
 653 &lt;x&gt; takes fewer or at most as many parameters as the current
 654 function, the tail call requires no extra space.</p></dd>
 655 </dl>
 656
 657 <h2>Expressions</h2>
 658
 659 <p class="first">Certain actions have the ability to evaluate
 660 expressions. Expressions can be simple values, but expressions can
 661 also perform computations on values. The following are valid
 662 expressions:</p>
 663
 664 <dl>
 665 <dt><strong class="since">1.0</strong> <code>add &lt;x&gt; &lt;y&gt;</code></dt>
 666 <dd><p class="first">The result of adding &lt;y&gt; to &lt;x&gt;.</p>
 667
 668 <p>If the result of the addition cannot be represented in a single word,
 669 the result of <code>add</code> is undefined.</p></dd>
 670
 671 <dt><strong class="since">1.0</strong> <code>and &lt;x&gt; &lt;y&gt;</code></dt>
 672 <dd><p class="first">The bitwise and of &lt;x&gt; and &lt;y&gt;.</p></dd>
 673
 674 <dt><strong class="since">1.0</strong> <code>asr &lt;x&gt; &lt;y&gt;</code></dt>
 675 <dd><p class="first">Performs an arithmetic right shift. The bits in
 676 &lt;x&gt; are shifted &lt;y&gt; positions to the right. The sign of
 677 &lt;x&gt; is preserved, so that the result has the same sign as
 678 &lt;x&gt;. The result is undefined if &lt;y&gt; is negative.</p></dd>
 679
 680 <dt><strong class="since current">1.1</strong> <code>auto-bytes &lt;x&gt;</code></dt>
 681 <dd><p class="first">Allocates &lt;x&gt; bytes of memory. The
 682 allocated bytes will automatically be released after the current frame
 683 ends. The result is the address of the allocated bytes.</p></dd>
 684
 685 <dt><strong class="since current">1.1</strong> <code>auto-words &lt;x&gt;</code></dt>
 686 <dd><p class="first">Allocates &lt;x&gt; words of memory. The
 687 allocated words will automatically be released after the current frame
 688 ends. The result is the address of the allocated words.</p></dd>
 689
 690 <dt><strong class="since">1.0</strong> <code>bsr &lt;x&gt; &lt;y&gt;</code></dt>
 691 <dd><p class="first">Performs a bitwise right shift. The bits in
 692 &lt;x&gt; are shifted &lt;y&gt; positions to the right. &lt;y&gt;
 693 zero-valued bits are shifted in from the left. The result does
 694 not necessarily have the same sign as &lt;x&gt;. The result is
 695 undefined if &lt;y&gt; is negative.</p></dd>
 696
 697 <dt><strong class="since">1.0</strong> <code>call &lt;x&gt; &lt;y&gt; &lt;z&gt; ...</code></dt>
 698 <dd><p class="first">Similar to the action call, this calls the
 699 function &lt;x&gt; with the parameters &lt;y&gt; &lt;z&gt; ... (there
 700 may be zero or more parameters). The result of this expression is the
 701 value returned from the function.</p></dd>
 702
 703 <dt><strong class="since">1.0</strong> <code>div &lt;x&gt; &lt;y&gt;</code></dt>
 704 <dd><p class="first">The (integer) result of dividing &lt;x&gt; by
 705 &lt;y&gt;.</p>
 706
 707 <p>If &lt;x&gt; &ge; 0 and &lt;y&gt; &gt; 0, the result is the largest
 708 integer equal to or less than the algebraic quotient of &lt;x&gt;
 709 and &lt;y&gt;.</p>
 710
 711 <p>If either &lt;x&gt; or &lt;y&gt; is negative, the result is
 712 implementation-defined.</p>
 713
 714 <p>If &lt;y&gt; is zero, or if the quotient cannot be represented in a
 715 single machine word, the result is undefined.</p></dd>
 716
 717 <dt><strong class="since">1.0</strong> <code>get-byte &lt;base&gt; &lt;offset&gt;</code></dt>
 718 <dd><p class="first">The value of the byte at address &lt;base&gt; + &lt;offset&gt;.</p></dd>
 719
 720 <dt><strong class="since">1.0</strong> <code>get-word &lt;base&gt; &lt;offset&gt;</code></dt>
 721 <dd><p class="first">The value of the word at address &lt;base&gt; +
 722 (WORDSIZE * &lt;offset&gt;).</p>
 723
 724 <p>The address computed as &lt;base&gt; + (WORDSIZE * &lt;offset&gt;) is
 725 expected to be a multiple of the word size. If this condition is not met,
 726 the behavior of <code>get-word</code> is undefined.</p></dd>
 727
 728 <dt><strong class="since">1.0</strong> <code>mod &lt;x&gt; &lt;y&gt;</code></dt>
 729 <dd><p class="first">For &lt;x&gt; &ge; 0 and &lt;y&gt; &gt; 0, returns
 730 &lt;x&gt; modulo &lt;y&gt;.</p>
 731
 732 <p>If either &lt;x&gt; or &lt;y&gt; is negative, the result is
 733 implementation-defined.</p>
 734
 735 <p>If &lt;y&gt; is zero, the result is undefined.</p></dd>
 736
 737 <dt><strong class="since">1.0</strong> <code>mul &lt;x&gt; &lt;y&gt;</code></dt>
 738 <dd><p class="first">The result of multiplying &lt;x&gt; by &lt;y&gt;.</p>
 739
 740 <p>If the algebraic result of &lt;x&gt; * &lt;y&gt; cannot be represented
 741 in a single word, the result of <code>mul &lt;x&gt; &lt;y&gt;</code>
 742 contains only the low-order bits of the full result.</p></dd>
 743
 744 <dt><strong class="since">1.0</strong> <code>not &lt;x&gt;</code></dt>
 745 <dd><p class="first">The ones' complement of &lt;x&gt;; i.e. all the
 746 bits in &lt;x&gt; inverted.</p></dd>
 747
 748 <dt><strong class="since">1.0</strong> <code>or &lt;x&gt; &lt;y&gt;</code></dt>
 749 <dd><p class="first">The bitwise or of &lt;x&gt; and &lt;y&gt;.</p></dd>
 750
 751 <dt><strong class="since">1.0</strong> <code>rol &lt;x&gt; &lt;y&gt;</code></dt>
 752 <dd><p class="first">Rotates the bits in &lt;x&gt; to the left by
 753 &lt;y&gt; positions. Bits that are rotated off the left are inserted
 754 on the right.
 755 The result is undefined if &lt;y&gt; is negative.</p></dd>
 756
 757 <dt><strong class="since">1.0</strong> <code>ror &lt;x&gt; &lt;y&gt;</code></dt>
 758 <dd><p class="first">Rotates the bits in &lt;x&gt; to the right by
 759 &lt;y&gt; positions. Bits that are rotated off the right are inserted
 760 on the left.
 761 The result is undefined if &lt;y&gt; is negative.</p></dd>
 762
 763 <dt><strong class="since">1.0</strong> <code>shl &lt;x&gt; &lt;y&gt;</code></dt>
 764 <dd><p class="first">Performs a left shift. The bits in
 765 &lt;x&gt; are shifted &lt;y&gt; positions to the left.
 766 The result is undefined if &lt;y&gt; is negative.</p></dd>
 767
 768 <dt><strong class="since">1.0</strong> <code>shr &lt;x&gt; &lt;y&gt;</code></dt>
 769 <dd><p class="first">Performs a right shift. The bits in
 770 &lt;x&gt; are shifted &lt;y&gt; positions to the right. It is
 771 implementation-defined whether this operation preserves the sign
 772 of &lt;x&gt; (for operations with specific sign-preservation
 773 properties, use asr or bsr).
 774 The result is undefined if &lt;y&gt; is negative.</p></dd>
 775
 776 <dt><strong class="since">1.0</strong> <code>sub &lt;x&gt; &lt;y&gt;</code></dt>
 777 <dd><p class="first">The result of subtracting &lt;y&gt; from &lt;x&gt;.</p>
 778
 779 <p>If the result of the subtraction cannot be represented in a single
 780 word, the result of <code>sub</code> is undefined.</p></dd>
 781
 782 <dt><strong class="since">1.0</strong> <code>xor &lt;x&gt; &lt;y&gt;</code></dt>
 783 <dd><p class="first">The bitwise exclusive or of &lt;x&gt; and
 784 &lt;y&gt;.</p></dd>
 785 </dl>
 786
 787 <h2>Conditionals</h2>
 788
 789 <p class="first"><strong class="since">1.0</strong> Conditionals in Voodoo take the following form:</p>
 790
 791 <pre><code>if&lt;test&gt;
 792     ... some code here ...
 793 else if&lt;test&gt;
 794     ... other code here ...
 795 ... more "else if" parts ...
 796 else
 797     ... some code ...
 798 end if
 799 </code></pre>
 800
 801 <p class="first">There can be any number of <q>else if</q> parts, and
 802 the final <q>else</q> clause is optional. The tests that are provided
 803 are the following:</p>
 804
 805 <dl>
 806 <dt><code>ifeq &lt;x&gt; &lt;y&gt;</code></dt>
 807 <dd><p class="first">Tests if &lt;x&gt; is equal to &lt;y&gt;.</p></dd>
 808
 809 <dt><code>ifge &lt;x&gt; &lt;y&gt;</code></dt>
 810 <dd><p class="first">Tests if &lt;x&gt; is greater than or equal to
 811 &lt;y&gt;.</p></dd>
 812
 813 <dt><code>ifgt &lt;x&gt; &lt;y&gt;</code></dt>
 814 <dd><p class="first">Tests if &lt;x&gt; is strictly greater than
 815 &lt;y&gt;.</p></dd>
 816
 817 <dt><code>ifle &lt;x&gt; &lt;y&gt;</code></dt>
 818 <dd><p class="first">Tests if &lt;x&gt; is less than or equal to
 819 &lt;y&gt;.</p></dd>
 820
 821 <dt><code>iflt &lt;x&gt; &lt;y&gt;</code></dt>
 822 <dd><p class="first">Tests if &lt;x&gt; is strictly less than
 823 &lt;y&gt;.</p></dd>
 824
 825 <dt><code>ifne &lt;x&gt; &lt;y&gt;</code></dt>
 826 <dd><p class="first">Tests if &lt;x&gt; is different from &lt;y&gt;.</p></dd>
 827 </dl>
 828
 829 <h2>Function Definitions</h2>
 830
 831 <p class="first"><strong class="since">1.0</strong> A function definition looks like:</p>
 832
 833 <pre><code>
 834 function x y z
 835     &lt;code&gt;
 836 end function
 837 </code></pre>
 838
 839 <p class="first">Here, the function being defined takes 3 parameters,
 840 which can be referred to as <code>x</code>, <code>y</code>, and
 841 <code>z</code> from the code inside the function body. A function may
 842 have zero or more parameters and is practically always preceded by a
 843 label, so that the function can be referenced from code.</p>
 844
 845 <p>A function should only be entered using <code>call</code>,
 846 <code>tail-call</code>, or entering a prior invocation of the function
 847 using <code>restore-frame</code> and <code>goto</code>. When calling
 848 a function, the number of supplied parameters should equal the number
 849 of parameters the function was declared with.
 850 A function should only be left through <code>return</code>,
 851 <code>tail-call</code>, or a valid combination
 852 of <code>restore-frame</code> and <code>goto</code>.
 853 Failing to meet these requirements results in undefined behavior.</p>
 854
 855 <h2>Blocks</h2>
 856
 857 <p class="first"><strong class="since">1.0</strong> Blocks can be used to define a scope in which local
 858 variables (introduced with <code>let</code>) can be referred to. A
 859 block looks like:</p>
 860
 861 <pre><code>
 862 block
 863     &lt;code&gt;
 864 end block
 865 </code></pre>
 866
 867 <p class="first">Inside a block, variables may be introduced using
 868 <code>let</code>. Such a variable is in scope (can be referred to)
 869 from the first statement after the <code>let</code> until the
 870 <code>end block</code> that terminates the block.</p>
 871
 872 <p>Blocks can be placed anywhere an action can be placed: at
 873 top-level, inside functions, inside blocks, and inside conditionals.</p>
 874 </div>
 875 </body>
 876 </html>