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