Migrating to v0.11

Migrating to v0.11

General

• The assembler now works in multiple iterations, attempting to resolve instructions until their sizes stabilize and stop changing (e.g. due to rule cascading). You can set the maximum number of iterations via the -t command-line flag. Rule cascading is more powerful as a result, allowing you to automatically select the best representation for an instruction more often.
• Values now can be intrinsically sized or unsized. Binary and hex literals are sized, as well as any bit-sliced value. Only sized values can be concatenated or output by instructions.
• Symbols can now have many layers like ...label: (which will only work if all layers above have also been declared). You can now also fully-qualify references to access symbols from other parents, like some_global.nested1.nested2.
• $ is now a synonym for pc, the current address.

cpudef

• #cpudef has been renamed to #ruledef, though it will still work as the former. You can now have as many #ruledef blocks as you want in the same project.
• You don't need to give a name to the #ruledef, though if you do, you must use a simple identifier without quotation marks.
• The -> separator has been changed to =>, and you can now use <- and -> in patterns.
• Pattern matching is more tolerant now, and will accept patterns previously marked as "potentially ambiguous".
• #bits should be taken out into the global scope. You can now set #bits individually for banks, too.
• #tokendef has been renamed to #subruledef, and it should be taken out into the global scope. = should be changed to =>.
• #subruledef is now a fully-fledged pattern matcher, identical to #ruledef. You can use complex patterns, and nest them indefinitely.
• You now have the option to use simpler bit-slices like `8 (which is equivalent to [7:0]).

Example:

Old

#cpudef
{
    #bits 16

    #tokendef reg
    {
        A = 0x00
        B = 0x01
        C = 0x02
    }

    load {r: reg}, {value} -> 0x11 @ r[7:0] @ value[15:0]
}

New

#bits 16

#subruledef reg
{
    A => 0x00
    B => 0x01
    C => 0x02
}

#ruledef
{
    load {r: reg}, {value} => 0x11 @ r`8 @ value`16
}

d

• The data directive can now have an unspecified size, like #d 0x1234. It will only work with sized values (hex literals or any bit-sliced value, for example).

str

• #str "abc" should be replaced by #d "abc". You can now use strings in any expression, and they'll be treated as UTF-8-encoded integers.

incbin, incbinstr, inchexstr

• These directives have been converted to regular functions, able to be used in any expression. To get the old behavior, you can replace them by #d incbin("file.bin"), for example.

include

• #include can now accept .. to navigate up a folder, but it won't navigate out of the folder containing the initial file specified on the command-line.

bankdef

• You can now set the #bits directive for individual banks, otherwise they'll use the current global #bits setting. Using #bankdef with a new #bits setting, or changing banks with #bank will override the global setting, so be careful.
• The #outp directive is now expressed in bits. You should multiply it by 8 to get the old behavior (you can evaluate it inline).