Make building projects stress-free and enjoyable with the best VASM syntax module for Mega Drive development. Assemblers In Your Community. With that nonsense out of the way, let's get into the meat of this post. For quite some time now, VASM has been floated among a few programmers within the community as a potentially good assembler option/alternative to the assembler that the main branch of the Sonic 1 disassembly formerly used, Psy-Q ASM68K. On paper, it does sound appealing; in addition to being lightweight and feature-competitive with most of the more commonly used functionality of ASM68K, it's open-source, cross-platform, actively maintained, modular, and supports M68K and Z80 assembly, among multiple other target architectures. However, those who attempted to make the switch quickly encountered something of a dilemma; of the syntax module options available officially... none of them quite match what users of ASM68K have come to expect. From oddities such as the "Motorola" syntax not allowing for named macro arguments, to appealing features such as structures being locked behind an "Oldstyle" syntax ill-suited to working with M68K assembly, it felt as though no matter what syntax you chose, you were making the wrong choice; you were giving up a lot in terms of features and comfortable developer-experience all in a seemingly folly effort to be less dependent on an ancient 32-bit windows application that, for the time being, still works just fine. This is the point where many have, quite understandably, dropped VASM in the past. After making the effort to switch myself, it became clear to me that for VASM to be a viable alternative to ASM68K, it needed to be given a syntax that types much closer to what users looking to migrate expected from it, and it needed to pull in useful features from other existing syntax styles to ensure that no useful functionality was being left on the table. For the past half a month or so, I've been trying to achieve precisely that. I've been hard at work learning my way around VASM's codebase and un-fucking it as much as possible to create what I'm calling the Psi-X (short for psionics) fork of VASM. While some directives are absent, users familiar with ASM68K will notice that most of the more commonly used directives (and some rarely used ones as well) are present and type exactly how you'd expect. Rather than go through every directive one-by-one and list the differences (if there are any), I think it would be best if I split this up into 3 lists; a list of currently absent ASM68K directives, a list of new directives present that may be unfamiliar to users of ASM68K, and a list of directives which have meaningful differences in syntax/usage, which is further elaborated upon in the documentation attached to this post. For more general information regarding usage of the VASM assembler, please consult VASM's Official Documentation. Spoiler: Absent Directives - ALIAS/DISABLE [Update 8/6/24: Added to the latest version of the repo] - HEX [Update 8/10/24: Added to the latest version of the repo] - DATA/DATASIZE [Update 8/10/24: Added to the latest version of the repo (only supports up to 128-bit numbers as opposed to 2048-bit numbers as in ASM68K)] - IEEE32/IEEE64 [Update 8/6/24: Added to the latest version of the repo] - CASE/ENDCASE [Update 8/12/24: This functionality has been added to the latest version of the repo, but the syntax is closer to AS than ASM68K. The new directives associated with this are listed under the "New Directives" spoiler tag.] - WHILE/ENDW [Update 8/15/24: Added to the latest version of the repo] - DO/UNTIL [Update 8/16/24: Added to the latest version of the repo] - MACROS [Update 8/20/24: Added to the latest version of the repo] - PUSHP/POPP [Update 8/25/24: Added to the latest version of the repo] - LOCAL [Update 8/19/24: Added to the latest version of the repo] - GROUP - PUSHO/POPO [Update 8/25/24: Added to the latest version of the repo] - PUBLIC [Update 8/7/24: Added to the latest version of the repo] - SUBSTR [Update 8/25/24: Added to the latest version of the repo] Spoiler: New Directives - ALIGN - COMMENT/COMEND - IFB/IFNB - IFC/IFNC - IFD/IFND - IIF - INCDIR - IRP/IRPC - RSEVEN - STRUCT/STREND [Update 8/7/24: struct-end directive changed to ENDS going forward] - SWITCH/CASE/DEFAULT [Update 8/12/24: Added to the latest version of the repo] Spoiler: Directives with Notable Differences - EQUS (Defined string symbols must be encapsulated in curly braces ({symbol}) rather than backslashes (\symbol\)) [Update 8/25/24: The backslash encapsulation is now also supported] - EQUR/REG (Part of the M68K CPU module; requires the option "-regsymredef" to be specified in the build command to be recognized) - MACRO (Up to 64 named arguments can be specified, but only 9 unnamed arguments are available without the use of the SHIFT directive. All arguments within a macro must be preceded by a '\' character, which was optional in ASM68K. [Update 8/25/24: '\' is no longer required] Some special parameters are absent/different. No NARG internal symbol is currently present; '\#' will expand to the passed argument count instead. [Update 8/6/24: NARG has been added to the latest version of the repo]) - PURGE (Multiple macros can be purged at once; accepts a list of macros instead of just one at a time) - SECTION (Definitions of sections function far more closely to how they do in standard VASM rather than imitating ASM68K's approach; relevant if you plan on using a linker in your projects) - OPT (Part of the M68K CPU module; options are currently Devpac/VASM as this module is currently unmodified from stock VASM. May change in the future.) [Update 8/25/24: Added. No support for M68K-specific optimization toggles, but the generic syntax option codes are all accepted] - LIST (Does not currently accept an "indicator" operand. May change in the future.) - INFORM (Does not currently handle text parameters to insert expressions into the message string.) - XREF (Does not currently accept a size qualifier) If a directive is not listed in any of the spoilers above, it should work precisely as it does in ASM68K already. In all likelihood, the list of absent directives will shrink as I continue to work on replicating ASM68K's functionality or offering suitable alternatives to said functionality to the extent that it is reasonable to do so. There are some additional differences between this fork of VASM and ASM68K that are worth noting as well. At this point in time, the built-in functions from ASM68K are not present, as function handling will require deeper modifications to the assembler than I have currently made and I'd like to add handling for user-defined functions at the same time. The listing output format is different and there's not currently an option to output a Psy-Q compatible listing, object, or symbol files, so tools and resources that currently accept or rely on those in order to function may not work. However, I do not say all of this to undermine how comfortable this is to use in its current state. I would estimate that for all but the most advanced users/abusers of ASM68K's unique directives, macro capabilities, built-in functions, and other Psy-Q development tools, switching to this would be pretty painless and offer up new features that I'm sure many would find quite useful. The most common problem most are likely to have stems from the requirement to place a '\' character in front of named arguments within macro definitions, as that what optional in ASM68K, which is basically just enforcing "good practice" anyway. But don't just take my word for it. I encourage anyone interested to try this, give feedback and advice, report bugs, and even contribute to the codebase if you know C and feel inclined to do so. The repository can be found here. If you're more of an "I need this in a Sonic 1 disassembly to make any use of it" type of person, fear not; I've attached an S1 disassembly that builds to bit-perfection using a compiled windows version of this VASM fork. It's based on the seemingly abandoned ASM68K branch of the S1 disassembly, so it's not exactly current and doesn't take full advantage of all this has to offer, but it's functional. As stated above, I have also attached documentation of the fork's syntax in the form of a PDF document; again, more general VASM documentation can be found here. There also exists an HTML version of the syntax documentation in the psi-x folder of the repository. I would've preferred to upload that but was restricted from doing so on here for what I assume are security reasons. I look forward to hearing what others think of this.
Update: A few things have been added to the latest version of the repository, including some ASM68K directives missing from the original release: Spoiler: 8/6 - 8/7 Additions ALIAS DISABLE IEEE32 IEEE64 PUBLIC NARG (symbol) DATA and DATASIZE are also currently in the works, but a bit more work is needed to get them to play nicely with the M68K CPU module since it seems to not like parsing values of varying bit-width at the moment. Here's hoping I can get it to work. It's also seeming more and more likely that I can get a few more of the absent directives in fairly soon; I may as well add HEX if I can get DATA/DATASIZE implemented, adding WHILE and DO/UNTIL loops would be another good thing to explore implementing. Adding LOCAL and the remaining special parameters ('\*' & '\_') for use within macros might be something I give a closer look soon as well. Overall, things are coming along.
18 days later, all the directives and important features for the first major release have been added! It should be much more compatible with most ASM68K-based projects out of the box now even though some functionality ('\*' & '\_' special macro parameters, string and math functions, complex expressions referencing external symbols, carrot-notation control characters, etc.) is still currently unsupported; all the basics and creature comforts of the Psy-Q assemblers is present. I'll figure out how to get binaries for the major platforms rolled out on GitHub later, but for now, I've attached a compiled windows version of the M68K assembler as well as the documentation for v1.0. As for future versions, I believe the focus for the next major release will be on including and modifying VASM's Linker (VLink) to better match the capabilities of Psy-Link, as the assembler does not currently allow complex operations to take place on external symbols due to no linkable object format generated by the assembler and, consequently, accepted by the linker supporting such a thing. This makes things like determining the Z80 bank and window location from a 68K address basically impossible for the moment, which is a big hurdle. Additionally, VLink does not currently support linking object files of differing endianness, which also stands in the way of linking Z80 code to 68K code together, which is pretty vital for MD development in general. However, any sound driver where the Z80-code is more or less isolated from the 68K-code should still work fine (S1's DAC Driver, DualPCM, MegaPCM, SONAR, etc.). In theory, Fully-Z80 based drivers could be modified to work around this limitation as well, but it would be a bit of a pain. After that, there's not a specific roadmap in place, but I'm thinking I'd like to add the SuperH CPU architecture to facilitate this fork's use in 32X, Saturn, and Dreamcast development. For now though, enjoy and let me know if there are any bugs you run into; I'll be starting my Fall-semester on Monday, but I'll try to keep chipping away at this as best I can amongst the havoc of higher-ed.
