ASM-11(1) Retro Project Manual ASM-11(1) NNAAMMEE asm-11 - simple assembler for MACRO-11 style PDP-11 code SSYYNNOOPPSSIISS aassmm--1111 [_O_P_T_I_O_N]... _F_I_L_E_._._. aassmm--1111 ----hheellpp DDEESSCCRRIIPPTTIIOONN aassmm--1111 is a simple assembler for MACRO-11 style PDP-11 code that di- rectly generates a load module for an absolute loader. It is mainly used to compile test bench code or other small bare-metal programs into a loadable format. aassmm--1111 accepts a subset of the MACRO-11 language and generates an abso- lute binary in the formats - llddaa--1111(5): the DEC standard absolute binary format, can be directly used with the paper tape loader. Activated with the ----llddaa or ----oollddaa options. - ccooff--1111(5): a custom format that contains the full symbol table and the absolute binary. Very useful when access to the symbol table is needed, for example in test bench codes. Activated with the ----ccooff or ----ooccooff options. - llssmm--1111(5): very simple word wise 'addr:data' memory dump. Useful when used in combination with some w11 tools, e.g. ddaassmm--1111. Acti- vated with the ----llssmm or ----oollssmm options. aassmm--1111 can create a listing in a format very close to that generated by the MACRO-11 assembler. Activated with the ----llsstt or ----oollsstt options. aassmm--1111 provides many basic assembler directives .ascii stores ascii string .asciz stores ascii string with trailing zero .asect absolute program section (current default, dummy imp) .blkb allocate bytes of storage .blkw allocate words of storage .byte store bytes of data .end end of source .endc end of .if conditional block .endm end of macro .endr end of .rept repeat block .error raise error .even ensure word aligment .include include another source file .if assembles block if condition is met .iff assembles block if condition tests false .ift assembles block if condition tests true .iftf assembles block regardless of condition .list minimal support for cnd,me,meb .nlist minimal support for cnd,me,meb .macro starts macro defintion (subset) .mcall load macro definitions .mdelete delete macro definitions .mexit terminate macro or .rept expansion .narg number of macro arguments .nchr calculate string length .ntype evaluate addressing mode .odd align to odd byte address .print insert output into listing .rept starts repeat block definition .word store words of data and thus restricted macro support and no psect support. DDiiffffeerreenncceess bbeettwweeeenn aassmm--1111 aanndd MMAACCRROO--1111 - only single .asect supported, no .psect support - assembler stops with error code 'S' when '.' exceeds 160000 - registers must be named r0,..,r5,sp,pc - the %n notation and register expressions are not supported - labeled assignment statements cause a 'Q' error (MACRO-11 accepts) - the .emt and .trap instruction must have the trap number specified - a .macro definition must end with .endm (.endr not accepted) - a .rept block must end with .endr (.endm not accepted) - macros: the \ operator accepts only symbols, no expressions - a .if dif/idn doesn't work with blank arguments - a .if df/ndf sees opcodes as defined (MACRO-11 doesn't) - a .if df/ndf sees register names as undefined (MACRO-11 doesn't) - error codes on invail statements differ, especially 'A' and 'Q' - the .(n)list acts only on cnd, me and meb, ignores other values - the .(n)list default is cnd=0,me=0,meb=1 (MACRO-11 cnd=1,meb=0) - the following directives are not supported: .cross, .csect, .dsabl, .enabl, .flt2, .flt4, .globl, .ident, .iif, .irp, .irpc, .library, .limit, .nocross, .packed, .page, .psect, .rad50, .radix, .rem, .restore, .save, .sbttl, .title, .weak DDeessiiggnn ggooaall ffoorr ddiirreeccttiivvee ssuuppppoorrtt The following directives will be added in future releases .flt2 store 32 bit float .flt4 store 64 bit float OOPPTTIIOONNSS --II _p_a_t_h adds _p_a_t_h to the .include search path. The default search path is '.' plus _$_R_E_T_R_O_B_A_S_E_/_t_o_o_l_s_/_a_s_m_-_1_1 if RREETTRROOBBAASSEE is defined. Each --II adds _p_a_t_h after '.'. --II can be given multiple times und must have a single path name. --LL _p_a_t_h adds _p_a_t_h to the .library search path used by the .mcall direc- tive. The default search path is _$_R_E_T_R_O_B_A_S_E_/_t_o_o_l_s_/_a_s_m_-_1_1 if RREETTRROOBBAASSEE is defined. --LL can be given multiple times und must have a single path name. --EE write .include processed code to _s_t_d_o_u_t and stop after 1st pass. No other outputs are created, options like ----llsstt are ignored. Useful for the generation of self-contained macro files that are free of .include and .mcall directives and thus free of external references. Was inspired by the -E option of gcc(1). --MM write rules to _s_t_d_o_u_t suitable for mmaakkee(1) describing the depen- dencies of generated .lda and .lst files from the source files. Outputs for .lda and .lst targets one rule per input or included file. Only useful when _F_I_L_E is not '-'. Was inspired by the -M option of gcc(1). ----llsstt create listing with a default file name built from the basename of the last _F_I_L_E plus a _._l_s_t extension. If _F_I_L_E is '-' the out- put is written to _s_t_d_o_u_t. ----oollsstt==_f_n_a_m create a listing and write it to file _f_n_a_m. If _f_n_a_m is '-' the listing is written to _s_t_d_o_u_t. ----llddaa create absolute loader output in llddaa--1111(5) format with a default file name built from the basename of the last _F_I_L_E plus a _._l_d_a extension. If _F_I_L_E is '-' the output is written to _s_t_d_o_u_t. ----oollddaa==_f_n_a_m create absolute loader output in llddaa--1111(5) format and write it to file _f_n_a_m. If _f_n_a_m is '-' the compound output is written to _s_t_d_o_u_t. ----ccooff create compound output in ccooff--1111(5) format with a default file name built from the basename of the last _F_I_L_E plus a _._c_o_f exten- sion. If _F_I_L_E is '-' the output is written to _s_t_d_o_u_t. ----ooccooff==_f_n_a_m create compound output in ccooff--1111(5) format and write it to file _f_n_a_m. If _f_n_a_m is '-' the compound output is written to _s_t_d_o_u_t. If both ----oollsstt==-- and ----ooccooff==-- and are specified, the listing output comes first, followed by the compound output. ----llssmm create lsmem style memory dump in llssmm--1111(5) format with a de- fault file name built from the basename of the last _F_I_L_E plus a _._l_s_m extension. If _F_I_L_E is '-' the output is written to _s_t_d_o_u_t. ----oollssmm==_f_n_a_m create lsmem style memory dump in llssmm--1111(5) format and write it to file _f_n_a_m. If _f_n_a_m is '-' the compound output is written to _s_t_d_o_u_t. --lliisstt _o_p_t is equivalent to a '.list _o_p_t' directive at the beginning of the code. Supported values for _o_p_t are 'cnd', 'me' and 'meb'. Startup default is 'cnd' and 'me' disabled and 'meb' enabled. --lliisstt can be given multiple times. --nnlliisstt _o_p_t is equivalent to a '.nlist _o_p_t' directive at the beginning of the code. --nnlliisstt can be given multiple times. --nnlliisstt options are processed after --lliisstt options. --hheellpp print full help text and exit. OOPPTTIIOONNSS FFOORR DDEEBBUUGG ----ttppaassss11 trace line context in pass 1. ----ttppaassss22 trace line context in pass 2. ----ddssyymm11 dump psect and ust tables after pass 1. ----ddssyymm22 dump psect and ust tables after pass 2. ----ttttookkeenn trace tokenizer. ----ttppaarrssee trace parser. ----tteemmiitt trace code emit. ----ttoouutt trace output file write. EENNVVIIRROONNMMEENNTT RREETTRROOBBAASSEE If defined adds an include path to the aassmm--1111 standard library. EEXXIITT SSTTAATTUUSS If files can't be opened or an assembler error is detected an exit sta- tus 1 is returned. EEXXAAMMPPLLEESS DDiirreecctt uussaaggee aassmm--1111 --llsstt --llddaa tteesstt..mmaacc Compiles _t_e_s_t_._m_a_c and creates listing file _t_e_s_t_._l_s_t and absolute loader file _t_e_s_t_._l_d_a. aassmm--1111 ----oollsstt==-- ----ooccooff==-- -- Reads the input from _s_t_d_i_n and writes a listing followed by a com- pound output to _s_t_d_o_u_t. This usage style is convenient when inte- grating aassmm--1111 with other tools. EEmmbbeeddddeedd uussaaggee ffrroomm ttii__ww1111 ccoommmmaanndd lliinnee The --ee option of the ttii__ww1111 command uses aassmm--1111 to compile a _._m_a_c source file and load the binary in either a w11 design on an FGPA or a test bench. Example ti_w11 -n4d -e $RETROBASE/tools/mcode/dl11/dl11echo.mac ffrroomm ttii__ww1111 ccoommmmaanndd pprroommpptt The llssaassmm subcommand of a CPU object uses aassmm--1111 to compile a _._m_a_c source file, load the binary, and capture the listing and the sym- bol table. cpu0 ldasm -file "test.mac" -sym sym -lst lst cpu0 cp stapc $sym(...end) compiles _t_e_s_t_._m_a_c and leaves the listing in Tcl variable _s_y_m and the symbol table in Tcl array _l_s_t. If the code specified a start address via a _._e_n_d directive it can be accessed via _$_s_y_m_(_._._._e_n_d_). cpu0 ldasm -lst lst -sym sym { ... MACRO-11 code ... } compiles and loads a code snippet embedded in the Tcl script. Again, the symbol table in Tcl array _l_s_t. This usage style is heavily used in test benches. The direct and easy access to the symbol table allows a very tight interaction between the verifica- tion code in the test bench and the code executed on the target system. SSEEEE AALLSSOO aassmm--1111__eexxppeecctt(1), ttii__ww1111(1), ddaassmm--1111(1), llddaa--1111(5), ccooff--1111(5), llssmm--1111(5) AAUUTTHHOORR Walter F.J. Mueller Retro Project 2023-01-27 ASM-11(1)