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" >
6 <title>The Voodoo Programming Language
</title>
7 <link rel=
"stylesheet" href=
"style.css" type=
"text/css" />
11 <h1>The Voodoo Programming Language
</h1>
13 <p class=
"first">A Voodoo program consists of data, function
14 definitions, and code. All of these are introduced by magic words such
15 as
<code>function
</code>,
<code>call
</code>, and
16 <code>string
</code>. Any part of the program may be preceded by a
17 label, and labels can be referred to from the code.
</p>
19 <h2>Hello World in Voodoo
</h2>
21 <p class=
"first">To quickly get a feeling for a programming language,
22 it is often instructive to look at a simple yet complete program.
23 The following is an implementation of the traditional
24 Hello World program in Voodoo:
</p>
27 #### Hello world in Voodoo
31 string
"Hello, world!\x00"
44 <p class=
"first">When compiled and linked with a library that provides
45 an appropriate implementation of the
<code>puts
</code> function, this
46 program will print
<q>Hello, world!
</q>.
</p>
48 <p>What follows is a more formal description of the Voodoo
49 programming language.
</p>
55 <p class=
"first">Comments start with a hash mark (#) and run until
56 the end of the line. The following is an example comment:
</p>
59 # This is an example comment
64 <p class=
"first">Integers consist of an optional plus or minus sign,
65 followed by one or more digits. Examples of valid integers:
</p>
75 <p class=
"first">Strings consist of zero or more characters enclosed in double
76 quotes. Examples of valid strings:
</p>
85 <p class=
"first">Symbols consist of letters, digits, underscores, and
86 hyphens, although only a letter or an underscore is allowed as the first
87 character of a symbol. Examples of valid symbols:
</p>
94 <h2>Escape Sequences
</h2>
96 <p class=
"first">To facilitate entering special characters and to
97 inhibit the special meaning certain characters normally have, an
98 escape mechanism is provided. Escape sequences start with a backslash,
99 and have the following meanings:
</p>
101 <table summary=
"Special characters"><tr>
102 <td><code>\\
</code></td>
103 <td>An actual backslash character
</td>
105 <td><code>\
"</code></td>
106 <td>A double quote character</td>
108 <td><code>\n</code></td>
111 <td><code>\r</code></td>
112 <td>A carriage return character</td>
114 <td><code>\t</code></td>
115 <td>A tab character</td>
117 <td><code>\x<var>XX</var></code></td>
118 <td>The character with hexadecimal value <var>XX</var></td>
120 <td><code>\<space></code></td>
121 <td>A space character</td>
123 <td><code>\<newline></code></td>
124 <td>Line continuation character. The newline
125 and any leading whitespace on the next line
129 <p class="first
">Examples of the usage of the escape characters:</p>
131 <table summary="Example Escape Sequences
"><tr>
132 <td><code>"Hello
world\n
"</code></td>
133 <td>A string with a newline in it</td>
135 <td><code>"\\\
""</code></td>
136 <td>A string consisting of a backslash followed by a double quote
</td>
138 <td><code>call foo \
<br />
140 <td>Same as:
<code>call
foo
bar
</code></td>
145 <p class=
"first">Places in a program can be marked with labels, so
146 that the place can be referred to from the code by mentioning the
147 label. A label consists of a symbol followed by a colon. When
148 referring to a label, only the symbol is used, without the colon.
</p>
150 <p class=
"first">For example:
</p>
157 <p class=
"first">declares a word with the value
12, and a label 'foo'
158 that refers to the place where this value is stored. For example, if
159 the value happens to be loaded at the address
71234, writing 'foo' in
160 the program will have the same effect as writing
71234 in the same
165 <p class=
"first">Values are the smallest unit of data in a Voodoo
166 program. Examples of values are:
</p>
168 <table summary=
"Example Values"><tr>
169 <td><code>12</code></td>
170 <td>The integer
12</td>
172 <td><code>x
</code></td>
173 <td>The value of x (may be a label or a local variable)
</td>
176 <h2>At-Expressions
</h2>
178 <p class=
"first">The character @ can be used to denote the value at
179 some address. An address prefixed with @ denotes the word stored at
180 that address, rather than the address itself. The address may be an
181 integer, a local variable, or a label. For example:
</p>
183 <table summary=
"Example at-expressions"><tr>
184 <td><code>@
12</code></td>
185 <td>The word stored at address
12</td>
187 <td><code>@x
</code></td>
188 <td>The word stored at address x
</td>
191 <p class=
"first">Syntactically, at-expressions are values. Therefore,
192 in any place where a value can be used, an at-expression can also be
195 <h2>Data Definitions
</h2>
197 <p class=
"first">Data can be inserted into a Voodoo program by means
198 of the magic words
<code>byte
</code>,
<code>word
</code>, and
199 <code>string
</code>, followed by the value of the byte, word, or
200 string to be inserted. For example:
</p>
203 # A byte with value
42
206 # A word with value -
1
215 <p class=
"first">Voodoo code consists of actions. Actions consist of a
216 magic word, usually followed by a number of values. This section lists
217 all actions supported by Voodoo. In the list below, '
<x
>',
218 '
<y
>', and '
<z
>' denote values, '
<symbol
>' denotes a
219 symbol, and '
<expr
>' denotes an expression.
220 (expressions are discussed further on). Ellipsis (
…) is used to
221 denote that more items may follow, and square brackets ([ and ]) are
222 used to denote that an item is optional.
</p>
225 <dt><code>call
<x
> <y
> <z
> …</code></dt>
226 <dd><p class=
"first">Calls the function
<x
> with the arguments
<y
>
227 <z
> …. There may be zero or more arguments.
</p></dd>
229 <dt><code>goto
<x
></code></dt>
230 <dd><p class=
"first">Continues the program at location
<x
>,
231 rather than at the next action after the goto.
</p>
233 <p>Any value can be used as the location to go to. However, the
234 consequences of using
<code>goto
</code> to cross function or block
235 boundaries (e.g. performing a
<code>goto
</code> to a label inside
236 a different function) are undefined.
</p></dd>
238 <dt><code>let
<symbol
> <expr
></code></dt>
239 <dd><p class=
"first">Introduces a local variable
<symbol
>, and
240 initializes it to the result of evaluating
<expr
>.
</p>
242 <p>This action is only allowed inside functions or blocks, that is,
243 between
<code>function
</code> and the corresponding
244 <code>end function
</code>, or between
<code>block
</code> and the
245 corresponding
<code>end block
</code>.
</p>
247 <p>The scope of a variable introduced by
<code>let
</code> includes
248 every statement after the
<code>let
</code> action and before the
249 <code>end function
</code> or
<code>end block
</code> that ends the
250 function or block in which the variable is introduced.
</p></dd>
252 <dt><code>return [
<expr
>]
</code></dt>
253 <dd><p class=
"first">Returns from the current function.
254 If
<expr
> is specified, it is evaluated and the function returns
255 the result of the evaluation. Otherwise, the return value is
256 unspecified.
</p></dd>
258 <dt><code>set
<symbol
> <expr
></code></dt>
259 <dd><p class=
"first">Evaluates
<expr
> and assigns the result to
260 <symbol
>.
<symbol
> may not be a label, because labels cannot be
261 assigned to.
</p></dd>
263 <dt><code>set-byte
<base
> <offset
> <x
></code></dt>
264 <dd><p class=
"first">Sets the byte at
<base
> +
<offset
> to
<x
>.
265 <offset
> is given as a number of bytes.
</p></dd>
267 <dt><code>set-word
<base
> <offset
> <x
></code></dt>
268 <dd><p class=
"first">Sets the word at
<base
> + WORDSIZE *
269 <offset
> to
<x
>.
</p>
271 <p>The address computed by
<base
> + WORDSIZE *
<offset
>
272 is expected to be a multiple of the word size.
273 The behavior of
<code>set-word
</code> is undefined if this condition
277 <dt><code>tail-call
<x
> <y
> <z
> ...
</code></dt>
278 <dd><p class=
"first">Performs a tail call to the function
<x
>
279 with arguments
<y
> <z
> …. This has an effect
280 similar to 'return call
<x
> <y
> <z
> ...', but
281 re-uses the call frame of the current function. This means that if
282 <x
> takes fewer or at most as many arguments as the current
283 function, the tail call requires no extra space.
</p></dd>
288 <p class=
"first">Certain actions have the ability to evaluate
289 expressions. Expressions can be simple values, but expressions can
290 also perform computations on values. The following are valid
294 <dt><code>add
<x
> <y
></code></dt>
295 <dd><p class=
"first">The result of adding
<y
> to
<x
>.
</p>
297 <p>If the result of the addition cannot be represented in a single word,
298 the result of
<code>add
</code> is undefined.
</p></dd>
300 <dt><code>and
<x
> <y
></code></dt>
301 <dd><p class=
"first">The bitwise and of
<x
> and
<y
>.
</p></dd>
303 <dt><code>asr
<x
> <y
></code></dt>
304 <dd><p class=
"first">Performs an arithmetic right shift. The bits in
305 <x
> are shifted
<y
> positions to the right. The sign of
306 <x
> is preserved, so that the result has the same sign as
307 <x
>. The result is undefined if
<y
> is negative.
</p></dd>
309 <dt><code>bsr
<x
> <y
></code></dt>
310 <dd><p class=
"first">Performs a bitwise right shift. The bits in
311 <x
> are shifted
<y
> positions to the right.
<y
>
312 zero-valued bits are shifted in from the left. The result does
313 not necessarily have the same sign as
<x
>. The result is
314 undefined if
<y
> is negative.
</p></dd>
316 <dt><code>call
<x
> <y
> <z
> ...
</code></dt>
317 <dd><p class=
"first">Similar to the action call, this calls the
318 function
<x
> with the arguments
<y
> <z
> ... (there
319 may be zero or more arguments). The result of this expression is the
320 value returned from the function.
</p></dd>
322 <dt><code>div
<x
> <y
></code></dt>
323 <dd><p class=
"first">The (integer) result of dividing
<x
> by
326 <p>If
<x
> ≥ 0 and
<y
> > 0, the result is the largest
327 integer equal to or less than the algebraic quotient of
<x
>
330 <p>If either
<x
> or
<y
> is negative, the result is
331 implementation-defined.
</p>
333 <p>If
<y
> is zero, or if the quotient cannot be represented in a
334 single machine word, the result is undefined.
</p></dd>
336 <dt><code>get-byte
<base
> <offset
></code></dt>
337 <dd><p class=
"first">The value of the byte at address
<base
> +
<offset
>.
</p></dd>
339 <dt><code>get-word
<base
> <offset
></code></dt>
340 <dd><p class=
"first">The value of the word at address
<base
> +
341 (WORDSIZE *
<offset
>).
</p>
343 <p>The address computed as
<base
> + (WORDSIZE *
<offset
>) is
344 expected to be a multiple of the word size. If this condition is not met,
345 the behavior of
<code>get-word
</code> is undefined.
</p></dd>
347 <dt><code>mod
<x
> <y
></code></dt>
348 <dd><p class=
"first">For
<x
> ≥ 0 and
<y
> > 0, returns
349 <x
> modulo
<y
>.
</p>
351 <p>If either
<x
> or
<y
> is negative, the result is
352 implementation-defined.
</p>
354 <p>If
<y
> is zero, the result is undefined.
</p></dd>
356 <dt><code>mul
<x
> <y
></code></dt>
357 <dd><p class=
"first">The result of multiplying
<x
> by
<y
>.
</p>
359 <p>If the algebraic result of
<x
> *
<y
> cannot be represented
360 in a single word, the result of
<code>mul
<x
> <y
></code>
361 contains only the low-order bits of the full result.
</p></dd>
363 <dt><code>not
<x
></code></dt>
364 <dd><p class=
"first">The ones' complement of
<x
>; i.e. all the
365 bits in
<x
> inverted.
</p></dd>
367 <dt><code>or
<x
> <y
></code></dt>
368 <dd><p class=
"first">The bitwise or of
<x
> and
<y
>.
</p></dd>
370 <dt><code>rol
<x
> <y
></code></dt>
371 <dd><p class=
"first">Rotates the bits in
<x
> to the left by
372 <y
> positions. Bits that are rotated off the left are inserted
374 The result is undefined if
<y
> is negative.
</p></dd>
376 <dt><code>ror
<x
> <y
></code></dt>
377 <dd><p class=
"first">Rotates the bits in
<x
> to the right by
378 <y
> positions. Bits that are rotated off the right are inserted
380 The result is undefined if
<y
> is negative.
</p></dd>
382 <dt><code>shl
<x
> <y
></code></dt>
383 <dd><p class=
"first">Performs a left shift. The bits in
384 <x
> are shifted
<y
> positions to the left.
385 The result is undefined if
<y
> is negative.
</p></dd>
387 <dt><code>shr
<x
> <y
></code></dt>
388 <dd><p class=
"first">Performs a right shift. The bits in
389 <x
> are shifted
<y
> positions to the right. It is
390 implementation-defined whether this operation preserves the sign
391 of
<x
> (for operations with specific sign-preservation
392 properties, use asr or bsr).
393 The result is undefined if
<y
> is negative.
</p></dd>
395 <dt><code>sub
<x
> <y
></code></dt>
396 <dd><p class=
"first">The result of subtracting
<y
> from
<x
>.
</p>
398 <p>If the result of the subtraction cannot be represented in a single
399 word, the result of
<code>sub
</code> is undefined.
</p></dd>
401 <dt><code>xor
<x
> <y
></code></dt>
402 <dd><p class=
"first">The bitwise exclusive or of
<x
> and
406 <h2>Conditionals
</h2>
408 <p class=
"first">Conditionals in Voodoo take the following form:
</p>
410 <pre><code>if
<test
>
411 ... some code here ...
413 ... other code here ...
414 ... more
"else if" parts ...
420 <p class=
"first">There can be any number of
<q>else if
</q> parts, and
421 the final
<q>else
</q> clause is optional. The tests that are provided
422 are the following:
</p>
425 <dt><code>ifeq
<x
> <y
></code></dt>
426 <dd><p class=
"first">Tests if
<x
> is equal to
<y
>.
</p></dd>
428 <dt><code>ifge
<x
> <y
></code></dt>
429 <dd><p class=
"first">Tests if
<x
> is greater than or equal to
432 <dt><code>ifgt
<x
> <y
></code></dt>
433 <dd><p class=
"first">Tests if
<x
> is strictly greater than
436 <dt><code>ifle
<x
> <y
></code></dt>
437 <dd><p class=
"first">Tests if
<x
> is less than or equal to
440 <dt><code>iflt
<x
> <y
></code></dt>
441 <dd><p class=
"first">Tests if
<x
> is strictly less than
444 <dt><code>ifne
<x
> <y
></code></dt>
445 <dd><p class=
"first">Tests if
<x
> is different from
<y
>.
</p></dd>
448 <h2>Function Definitions
</h2>
450 <p class=
"first">A function definition looks like:
</p>
458 <p class=
"first">Here, the function being defined takes
3 arguments,
459 which can be referred to as
<code>x
</code>,
<code>y
</code>, and
460 <code>z
</code> from the code inside the function body. A function may
461 have zero or more arguments and is practically always preceded by a
462 label, so that the function can be referenced from code.
</p>
464 <p>A function should only be entered using
<code>call
</code> or
465 <code>tail-call
</code>, and should only be left through a
466 <code>return
</code> action. Furthermore, a function should always
467 be called with the same number of arguments it was defined with.
468 Failing to meet any of these requirements results in undefined
473 <p class=
"first">Blocks can be used to define a scope in which local
474 variables (introduced with
<code>let
</code>) can be referred to. A
475 block looks like:
</p>
483 <p class=
"first">Inside a block, variables may be introduced using
484 <code>let
</code>. Such a variable is in scope (can be referred to)
485 from the first statement after the
<code>let
</code> until the
486 <code>end block
</code> that terminates the block.
</p>
488 <p>Blocks can be placed anywhere an action can be placed: at
489 top-level, inside functions, inside blocks, and inside conditionals.
</p>
493 <p class=
"first">A Voodoo program is divided in a number of sections.
494 In source code, these are introduced by a directive of the form
495 <code>section
<identifier
></code>, where
<identifier
> is an
496 identifier for the section.
</p>
498 <p>The following section identifiers are valid:
</p>
500 <table summary=
"Section Identifiers"><tr>
504 <td><code>code
</code></td>
505 <td>This section contains executable code
</td>
507 <td><code>data
</code></td>
508 <td>This section contains data
</td>
510 <td><code>functions
</code></td>
511 <td>This section contains function definitions
</td>
514 <p class=
"first">Example usage of the
<code>section
</code> directive:
</p>
518 # define data here ...
521 # define functions here ...
524 <h2>Import and Export
</h2>
526 <p class=
"first">To allow Voodoo programs to refer to definitions in
527 other files, and to allow other files to refer to definitions in
528 Voodoo programs, the magic words
<code>import
</code>
529 and
<code>export
</code> are used.
</p>
531 <p>Using
<code>import
</code>, definitions from elsewhere are made
532 available to a Voodoo program:
</p>
541 # We can now refer to stderr and fputs
544 <p>Data and functions defined in a Voodoo program can be made
545 available to other programs using
<code>export
</code>:
</p>
565 <p class=
"first">Many architectures require that data and/or code
566 obey certain alignment restrictions. For example, an architecture may
567 require that a word of data be at an address that is a multiple of the
568 word size. Voodoo provides the
<code>align
</code> directive, which
569 specifies the alignment for the next program element.
</p>
571 <p>Without any arguments,
<code>align
</code> inserts filler bytes
572 into the current section, so that the next element added to the section
573 will respect the default alignment for the section. The default
574 alignment for each section is implementation-dependent, but must ensure
575 that the alignment restrictions of the target platform are obeyed.
</p>
577 <p>When written as
<code>align
<n
></code>, where
<n
> is an
578 integer, the directive will insert filler bytes as necessary to align
579 the next element to be added to the section on a multiple of
<n
>
582 <p>The filler bytes inserted by
<code>align
</code> are unspecified.
583 In particular, they are not guaranteed to be valid code.
</p>
585 <p>Example uses of the
<code>align
</code> directive:
</p>
593 # Ensure that y is aligned according to
594 # the target platform's alignment restrictions
603 # Ensure that foo is aligned according to
604 # the target platform's alignment restrictions