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;. If the
 250 exact result of &lt;x&gt;/&lt;y&gt; is not an integer, the result
 251 is converted to an integer in an implementation-defined way. If
 252 &lt;y&gt; = 0 or if the result cannot be represented in a single
 253 word, the behavior of <code>div</code> is undefined.</dd>
 254
 255 <dt><code>get-byte &lt;base&gt; &lt;offset&gt;</code></dt>
 256 <dd>The value of the byte at address &lt;base&gt; + &lt;offset&gt;.</dd>
 257
 258 <dt><code>get-word &lt;base&gt; &lt;offset&gt;</code></dt>
 259 <dd>The value of the word at address &lt;base&gt; + (WORDSIZE *
 260 &lt;offset&gt;).
 261
 262 The address computed as &lt;base&gt; + (WORDSIZE * &lt;offset&gt;) is
 263 expected to be a multiple of the word size. If this condition is not met,
 264 the behavior of <code>get-word</code> is undefined.</dd>
 265
 266 <dt><code>mod &lt;x&gt; &lt;y&gt;</code></dt>
 267 <dd>Returns the integer n such that
 268 n = &lt;x&gt; - (&lt;y&gt; * z), where z is the result of
 269 <code>div &lt;x&gt; &lt;y&gt;</code>. The behavior of
 270 <code>mod &lt;x&gt; &lt;y&gt;</code> is undefined when the
 271 behavior of <code>div &lt;x&gt; &lt;y&gt;</code> is
 272 undefined.</dd>
 273
 274 <dt><code>mul &lt;x&gt; &lt;y&gt;</code></dt>
 275 <dd>The result of multiplying &lt;x&gt; by &lt;y&gt;.
 276
 277 If the algebraic result of &lt;x&gt; * &lt;y&gt; cannot be represented
 278 in a single word, the result of <code>mul &lt;x&gt; &lt;y&gt;</code>
 279 contains only the low-order bits of the full result.</dd>
 280
 281 <dt><code>not &lt;x&gt;</code></dt>
 282 <dd>The ones' complement of &lt;x&gt;; i.e. all the bits in &lt;x&gt;
 283 inverted.</dd>
 284
 285 <dt><code>or &lt;x&gt; &lt;y&gt;</code></dt>
 286 <dd>The bitwise or of &lt;x&gt; and &lt;y&gt;.</dd>
 287
 288 <dt><code>sub &lt;x&gt; &lt;y&gt;</code></dt>
 289 <dd>The result of subtracting &lt;y&gt; from &lt;x&gt;.
 290
 291 If the result of the subtraction cannot be represented in a single
 292 word, the result of <code>sub</code> is undefined.</dd>
 293
 294 <dt><code>xor &lt;x&gt; &lt;y&gt;</code></dt>
 295 <dd>The bitwise exclusive or of &lt;x&gt; and &lt;y&gt;.</dd>
 296 </dl>
 297
 298 <h2>Conditionals</h2>
 299
 300 <p class="first">Conditionals in Voodoo take the following form:</p>
 301
 302 <pre><code>if&lt;test&gt;
 303     ... some code here ...
 304 else if&lt;test&gt;
 305     ... other code here ...
 306 ... more "else if" parts ...
 307 else
 308     ... some code ...
 309 end if
 310 </code></pre>
 311
 312 <p class="first">There can be any number of <q>else if</q> parts, and
 313 the final <q>else</q> clause is optional. The tests that are provided
 314 are the following:</p>
 315
 316 <dl>
 317 <dt><code>ifeq &lt;x&gt; &lt;y&gt;</code></dt>
 318 <dd>Tests if &lt;x&gt; is equal to &lt;y&gt;.</dd>
 319
 320 <dt><code>ifge &lt;x&gt; &lt;y&gt;</code></dt>
 321 <dd>Tests if &lt;x&gt; is greater than or equal to &lt;y&gt;.</dd>
 322
 323 <dt><code>ifgt &lt;x&gt; &lt;y&gt;</code></dt>
 324 <dd>Tests if &lt;x&gt; is strictly greater than &lt;y&gt;.</dd>
 325
 326 <dt><code>ifle &lt;x&gt; &lt;y&gt;</code></dt>
 327 <dd>Tests if &lt;x&gt; is less than or equal to &lt;y&gt;.</dd>
 328
 329 <dt><code>iflt &lt;x&gt; &lt;y&gt;</code></dt>
 330 <dd>Tests if &lt;x&gt; is strictly less than &lt;y&gt;.</dd>
 331
 332 <dt><code>ifne &lt;x&gt; &lt;y&gt;</code></dt>
 333 <dd>Tests if &lt;x&gt; is different from &lt;y&gt;.</dd>
 334 </dl>
 335
 336 <h2>Function Definitions</h2>
 337
 338 <p class="first">A function definition looks like:</p>
 339
 340 <pre><code>
 341 function x y z
 342     &lt;code&gt;
 343 end function
 344 </code></pre>
 345
 346 <p class="first">Here, the function being defined takes 3 arguments,
 347 which can be referred to as <code>x</code>, <code>y</code>, and
 348 <code>z</code> from the code inside the function body. A function may
 349 have zero or more arguments and is practically always preceded by a
 350 label, so that the function can be referenced from code.</p>
 351
 352 <p>A function should only be entered using <code>call</code> or
 353 <code>tail-call</code>, and should only be left through a
 354 <code>return</code> action. Furthermore, a function should always
 355 be called with the same number of arguments it was defined with.
 356 Failing to meet any of these requirements results in undefined
 357 behavior.</p>
 358
 359 <h2>Sections</h2>
 360
 361 <p class="first">A Voodoo program is divided in a number of sections.
 362 In source code, these are introduced by a directive of the form
 363 <code>section &lt;identifier&gt;</code>, where &lt;identifier&gt; is an
 364 identifier for the section.</p>
 365
 366 <p>The following section identifiers are valid:</p>
 367
 368 <table summary="Section Identifiers"><tr>
 369 <th>Identifier</th>
 370 <th>Meaning</th>
 371 </tr><tr>
 372 <td><code>code</code></td>
 373 <td>This section contains executable code</td>
 374 </tr><tr>
 375 <td><code>data</code></td>
 376 <td>This section contains data</td>
 377 </tr><tr>
 378 <td><code>functions</code></td>
 379 <td>This section contains function definitions</td>
 380 </tr></table>
 381
 382 <p class="first">Example usage of the <code>section</code> directive:</p>
 383
 384 <pre><code>
 385 section data
 386 # define data here ...
 387
 388 section functions
 389 # define functions here ...
 390 </code></pre>
 391
 392 <h2>Alignment</h2>
 393
 394 <p class="first">Many architectures require that data and/or code
 395 obey certain alignment restrictions. For example, an architecture may
 396 require that a word of data be at an address that is a multiple of the
 397 word size. Voodoo provides the <code>align</code> directive, which
 398 specifies the alignment for the next program element.</p>
 399
 400 <p>Without any arguments, <code>align</code> inserts filler bytes
 401 into the current section, so that the next element added to the section
 402 will respect the default alignment for the section. The default
 403 alignment for each section is implementation-dependent, but must ensure
 404 that the alignment restrictions of the target platform are obeyed.</p>
 405
 406 <p>When written as <code>align &lt;n&gt;</code>, where &lt;n&gt; is an
 407 integer, the directive will insert filler bytes as necessary to align
 408 the next element to be added to the section on a multiple of &lt;n&gt;
 409 bytes.</p>
 410
 411 <p>The filler bytes inserted by <code>align</code> are unspecified.
 412 In particular, they are not guaranteed to be valid code.</p>
 413
 414 <p>Example uses of the <code>align</code> directive:</p>
 415
 416 <pre><code>
 417 section data
 418
 419 x:
 420 byte 1
 421
 422 # Ensure that y is aligned according to
 423 # the target platform's alignment restrictions
 424 align
 425 y:
 426 word 42
 427
 428
 429
 430 section functions
 431
 432 # Ensure that foo is aligned according to
 433 # the target platform's alignment restrictions
 434 align
 435 foo:
 436 function n
 437     # some code here
 438 end function
 439 </code></pre>
 440 </div>
 441 </body>
 442 </html>