Odule Assembler V1.5 – 2018
Total Page:16
File Type:pdf, Size:1020Kb
[M]ultiple [P]rocessor [M]odule Assembler V1.5 – 2018 MMMMM MMMMM PPPPPPPPPPPPP MMMMM MMMMM MMMMMM MMMMMM PPPPPPPPPPPPPPP MMMMMM MMMMMM MMMMMMMMMMMMMMM PPPP PPPP MMMMMMMMMMMMMMM MMMM MMMMM MMMM PPPPPPPPPPPP MMMM MMMMM MMMM MMMM MMMM PPPP MMMM MMMM MMMM MMMM PPPP MMMM MMMM MMMMMM MMMMMM PPPPPP MMMMMM MMMMMM https://gitlab.com/bits4fun/mpm 1 Contents Introduction 7 History 7 Future Mpm developments (V2.x) 8 Compiling Mpm from source code 8 Using Qt Creator 8 Using Mingw on Windows 8 Using Make & GCC on Unix platforms 8 Runtime library dependencies 8 Installing Mpm from binary application package 8 Windows XP and newer 8 MAC OSX 8 Linux 9 Mpm filename patterns 9 Source code 9 Error files 9 Object files 9 Static library files 9 Executable files 9 Listing files 9 Source code symbol files 9 Label address (of executable code) map files 9 Exported global label address files 9 Instructing the assembler on the command shell 9 Syntax overview 9 Display syntax of available options and features 10 Getting Mpm help from man pages (Unix only) 10 Specify to disable an option 10 Grouping of enabling/disabling options 10 Compiling sources as object files without linking 10 Create object files, always 10 Creating a static linkable library of modules 10 Compiling sources to executable code 10 First filename is template for compiled output files 10 Split executable code into 16K segments (Z80 only) 11 Creating a CRC-32 checksum of executable code 11 Creating a SHA-256 checksum of executable code 11 Creating Intel Hex output of executable code 11 Linking executable code with calls from a static library 11 Compile only updated source code 11 Using a project file for executable code and libraries 11 Defining source code dependency files (includes) 11 Creating listing files 11 Creating executable address map file 11 2 Exporting global address labels as definition file 11 Change default assembly source file extension 11 Change default object file extension 11 Specify file system search path for INCLUDE directive 11 Specify file system search path for static libraries 11 Specify base address of executable code (ORG) 12 Create address-independent executable code (Z80 only) 12 Override default executable code filename 12 Pre-defined boolean true symbols for source code 12 Enable external line number mode (for LINE directive) 12 Display Mpm's version information 12 Mpm version information for scripts 12 Verbose information while compiling 12 Mpm's use of operating system environment variables 12 MPM_INCLUDEPATH 12 MPM_LIBPATH 12 MPM_STDLIBRARY 12 Macros 12 Introduction 13 Using macros 13 Macro definition 13 Rules of macro definition 13 Macro definition syntax 14 Macro call 14 Macro expansion 15 Macro default parameter arguments 15 Examples 15 Assembler Directive Reference 16 ALIGN 17 ASCII 17 ASCIIZ 17 BINARY 17 BYTE 17 DB 17 DC 17 DEFB 17 DEFC 17 DEFGROUP 17 DEFINE 17 DEFL 17 DEFM 17 DEFMZ 17 DEFP 17 DEFS 18 DEFSYM 18 DEFVARS 18 DEFW 18 3 DL 18 DM 18 DMZ 18 DP 18 DS 18 DV 18 ENUM 18 EQU 18 ERROR 18 EXTERN 18 GLOBAL 19 IF – ELSE - ENDIF 19 INCLUDE 19 LIB 19 LIBRARY 19 LINE 19 LONG 19 LSTOFF 19 LSTON 19 MACRO 19 MODULE 19 ORG 19 SPACE 19 STRING 19 UNDEFINE 19 VARAREA 20 WORD 20 XDEF 20 XLIB 20 XREF 20 Assembler Function Reference 21 $DAY 21 $EVAL 21 $HOUR 21 $LINKADDR 21 $MINUTE 21 $MONTH 21 $MPMVERSION 21 $PC (and $ as program counter) 21 $SECOND 21 $YEAR 21 Z80 CPU Instruction set implementation 22 Optional Z80 mnemonic instruction syntax 22 Using [] as alternate for expression brackets 22 The undocumented Z80 instructions 22 Supporting address-independent executable code 23 Appendix 26 4 Mpm Object file format 26 The standard platform identifier symbol 27 5 Copyright Copyright (C) 1991-2018, Gunther Strube, [email protected] This document is part of Mpm. Mpm is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2, or (at your option) any later version. Mpm is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with Mpm; see the file COPYING. If not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. 1 Introduction The Mpm Macro Cross Assembler currently supports compilation of Zilog Z80 CPU assembly language and is able to run on any major OS performing cross-compilation of assembly source code files into Z80 CPU executable binaries. Mpm is an assembler and linker combined as one tool. Mpm is available on all major operating system platforms such as Windows, Mac OS X and Linux, also supporting embedded platforms such as the Raspberry Pi. Mpm is implemented in Ansi-C supporting executables on 32bit and 64bit architectures. It is designed to be a multi-platform tool, automatically handling file naming conventions and correct code generation, byte ordering, no matter which architecture it is being executed on. Mpm is designed as an easy command line interface compiling source files into stand-alone applications. Mpm assists the assembly language programmer with these typical high-level features: Mpm as a command line shell tool, usually integrated into scripts for projects assembler and (static) linking functionality integrated as one tool include file referencing project-oriented modularized source code organisation macros as a way to inline grouped assembly instructions or data-structures support for defining meta data structures project source file-level dependencies compile only updated sources generate object files and libraries for static application linking Z80 CPU code generation Mpm has been designed with the focus on flexibility and extensibility and is available as Open Source through the GPL v2 license. This document provides all information about Mpm assembler functionality thoroughly explained with examples. This document also provides a reference for easy access to command line options and directives and assembler source code 6 directives. 1.1 H istory Mpm was originally written in SuperBasic running on a Sinclair QL in 1991 to assist the development of Cambridge Z88 applications (compiling code on the QL and transfer the executable binaries to Z88 via serial port). At the time, only proprietary (and very pricey for a Z88 enthusiast) Z80 assembler tools were provided by Cambridge Computer, the company selling the Cambridge Z88 portable computer. The idea was to create a complete development toolset, available for free, enabling the community to make applications for the Cambridge Z88. It was later ported to Lattice C using the Sinclair QL's C68 C compiler. The final port was done to Ansi C to allow easier compilation on more platforms, beginning with MS DOS and Linux/Unix. After a couple of years, "z80asm" was adopted by the Z88dk (Small-C) project for being the final step of executable code generation to the Small-C compiler on Z80-based systems. z80asm has since then been improved vastly to be a perfect companion for the Small-C compiler tool-chain. Around 1996, z80asm was forked into Mpm as becoming a more CPU-agnostic assembly language compiler tool. A proof-of-concept were done for the Sony PlayStation 2 hacker community in Denmark, generating Mips R5900 CPU code. This implementation was never released to the public, yet the internal optimisations of data structures and algorithms, general source code & expression parsing and 64bit code generation – were re-integrated for the Z80 CPU target. Mpm has since then been the core tool for the Cambridge Z88 development project on Sourceforge and now on cambridgez88.jira.com and continues to be fine-tuned for today's 64bit operating systems. 1.2 F uture Mpm developments (V2.x) Mpm currently supports it's own object file format and code generation for the Z80 CPU. Future releases will support ELF binary executable output for Z80, Arm (Raspberry Pi as first target) & Mips CPU's (r5900 as first target). 2 Compiling Mpm from source code The source code of Mpm packaged as Zip or Tar.gz can be downloaded from here: 2.1 Using Qt Creator ... 2.2 Using Mingw on Windows ... 2.3 Using Make & GCC on Unix platforms ... 2.4 Runtime library dependencies ... 7 3 Installing Mpm from binary application package Mpm is a command line tool and as such you decide where to install the executable and ensure that it is available via the operating system program search PATH. Mpm is run via a command line shell and is typically integrated into scripts. Installation packages have been provided for all major platforms. 3.1 Windows XP and newer … 3.2 MAC OSX … 3.3 Linux ... 4 Mpm filename patterns 4.1 Source code … 4.2 Error files … 4.3 Object files … 4.4 Static library files … 4.5 Executable files … 4.6 Listing files … 4.7 Source code symbol files ... 4.8 Label address (of executable code) map files … 4.9 Exported global label address files ... 8 5 Instructing the assembler on the command shell Mpm is executed using the operating system standard command line environment (CLI). On Unix platforms this will be a terminal shell such as Bash. On Windows platforms, it is identified as the command prompt also known as the MS-DOS prompt. 5.1 Syntax overview When executing the assembler from the command line without options, i.e. mpm<ENTER>, a help page is automatically displayed where after control is returned to the operating system command line.