Contents
About this manual
Who it is for
What it does not teach
How it is organised
Conventions
Which version it describes
I  Getting started
1 Introduction
1.1 What Tatara and Tanren are
1.2 Where the names come from
1.3 What they can do
1.4 What you need
1.5 What is next
2 How an assembler and a linker work
2.1 Two steps
2.2 What the assembler does
2.3 What the assembler cannot know
2.4 What the linker does
2.5 A worked example
2.6 Code and data: segments
2.7 Why two steps are worth it
2.8 The words in this chapter
3 Installation
3.1 What you get
3.2 Where the files go
3.3 Installing, step by step
3.4 Setting PATH and TATARA
3.5 Checking the installation
3.6 Updating
4 A first program
4.1 Before you start
4.2 The program
4.3 Assembling it
4.4 Linking it
4.5 Running it
4.6 The build file
4.7 A program in two modules
4.8 What is next
II  The assembler, Tatara
5 Running TATARA
5.1 The command line
5.2 Filenames
5.3 The options
5.4 What TATARA prints
5.5 Listings
5.6 When TATARA does not start
6 Source format
6.1 Lines
6.2 The four fields
6.3 Where a label goes
6.4 Comments
6.5 Upper and lower case
6.6 Spaces, tabs, line length and line endings
7 Names
7.1 The characters of a name
7.2 Length
7.3 Upper and lower case
7.4 Names that are hard to reach
8 Expressions
8.1 Values are 16 bits
8.2 Numbers
8.3 Characters
8.4 Names and the location counter
8.5 Operators
8.6 What kind of value
9 Instructions
9.1 The instruction set
9.2 Operands
9.3 Relative jumps
9.4 The R800 instructions
9.5 The undocumented instructions
9.6 When an operand is wrong
10 Segments and the location counter
10.1 The location counter
10.2 Code, data and absolute
10.3 ORG
10.4 Reserving space: DS
10.5 Named segments
10.6 Transient data segments
10.7 Messages
11 Data
11.1 DB: bytes
11.2 Strings
11.3 DW: words
11.4 DC: strings that mark their own end
11.5 The other names
11.6 Messages
12 Defining and sharing symbols
12.1 Three ways to give a name a value
12.2 Labels
12.3 EQU
12.4 DEFL
12.5 Sharing names between modules
12.6 END and the start address
12.7 Messages
13 Including files
13.1 INCLUDE
13.2 Where TATARA looks
13.3 The TATARA environment variable
13.4 Paths in the filename
13.5 Files that include files
13.6 Including a file twice
13.7 END in an include file
13.8 Messages
14 The include files
14.1 What the files hold
14.2 Including them
14.3 MSXDOS.INC and the system macro
14.4 BIOS.INC and SUBROM.INC
14.5 ERRORS.INC
14.6 The other files
15 Conditional assembly
15.1 IF, ELSE and ENDIF
15.2 The two passes
15.3 IFDEF and IFNDEF
15.4 IF1 and IF2
15.5 IFB, IFNB, IFIDN and IFDIF
15.6 Nesting
15.7 Messages
16 Macros
16.1 Defining and using a macro
16.2 Arguments
16.3 Joining text with &
16.4 Comments in a body
16.5 LOCAL
16.6 EXITM
16.7 Macros inside macros
16.8 Upper and lower case
16.9 Messages
17 Repeat blocks
17.1 REPT
17.2 IRP
17.3 IRPC
17.4 LOCAL, EXITM and nesting
17.5 Messages
18 The listing
18.1 A listing line
18.2 Pages
18.3 Turning the listing off and on
18.4 Macro expansions
18.5 Lines not assembled
18.6 Messages
19 The symbol table dump and the diagnostic switches
19.1 The symbol table
19.2 Reading the table
19.3 The table and the listing
19.4 Diagnostic switches
20 Error messages
20.1 What a message says
20.2 TATARA stops at the first error
20.3 The trail
20.4 Errors found on the second pass
20.5 Internal errors
III  The linker, Tanren
21 Running TANREN
21.1 The command line
21.2 The output file
21.3 The options
21.4 What TANREN prints
21.5 The 127-character command line
21.6 When TANREN does not start
22 Link files
22.1 A first link file
22.2 Writing a link file
22.3 Link files and the command line
22.4 Messages
23 Where TANREN looks for object files
23.1 Three places
23.2 The TANREN environment variable
23.3 Paths in the name
23.4 Where the output file goes
23.5 Messages
24 How a program is laid out
24.1 Code, then data
24.2 Named segments
24.3 Moving the code and the data: /P: and /D:
24.4 Transient segments across modules
24.5 Absolute segments
24.6 Messages
25 Symbols across modules
25.1 How names are matched
25.2 What an external’s value can be
25.3 Names that no module defines
25.4 Names defined twice
25.5 Capitals and small letters
25.6 Every module is linked
25.7 /M in full
25.8 Messages
26 Output formats
26.1 What TANREN writes
26.2 A .COM program
26.3 A raw image for another address
26.4 A file for BLOAD: /B
26.5 The entry address
26.6 A ROM image
26.7 How large a program can be
26.8 When there is nothing to write
26.9 Messages
27 Linker error messages
27.1 What a message says
27.2 TANREN stops at the first error
27.3 Damaged object files
27.4 Segments
27.5 Messages
IV  Worked guides
28 A program in several modules
28.1 The example
28.2 The two modules
28.3 The link file
28.4 Building and running it
28.5 What TANREN did
28.6 Things to try
29 Scratch variables shared through a transient segment
29.1 The example
29.2 The source
29.3 Building it
29.4 Reading the symbol table
29.5 Reading the maps
29.6 Things to try
30 Macros and the listing modes
30.1 The example
30.2 The source
30.3 Building and running it
30.4 The three listing modes
30.5 Things to try
31 Long symbol names and case-sensitive names
31.1 The example
31.2 The source
31.3 Building it
31.4 Reading the two files
31.5 Long symbol names across modules
31.6 Macro names and /C
32 A binary for MSX-BASIC’s BLOAD
32.1 The example
32.2 The source
32.3 Building it
32.4 Running it from BASIC
32.5 Where the file can go
32.6 Things to try
33 A 16 KB ROM cartridge
33.1 The example
33.2 The source
33.3 Building it
33.4 Running it
33.5 Things to try
34 A project in several directories
34.1 The example
34.2 The sources
34.3 Building and running it
34.4 Things to try
35 Building TATARA and TANREN from their own sources
35.1 The sources
35.2 BUILD.BAT
35.3 Running it
35.4 Building the tools with themselves
A Directive reference
A.1 The directives by purpose
A.2 The directives in alphabetical order
A.3 Labels on directive lines
A.4 Other names
B Instruction summary
B.1 How to read the tables
B.2 8-bit loads
B.3 16-bit loads, PUSH and POP
B.4 Exchange, block transfer and search
B.5 8-bit arithmetic and logic
B.6 General purpose and CPU control
B.7 16-bit arithmetic
B.8 Rotate and shift
B.9 Bit set, reset and test
B.10 Jumps
B.11 Calls, returns and restarts
B.12 Input and output
B.13 The undocumented instructions
B.14 The R800 multiplications
B.15 Forms that are not accepted
C Operators and precedence
C.1 The operators
C.2 At the edges
C.3 Values
D Error messages
D.1 How a message is laid out
D.2 TATARA’s messages
D.3 TANREN’s messages
D.4 TANREN’s warnings and notes
E Limits
E.1 TATARA
E.2 TANREN
E.3 The command line
E.4 What has no fixed limit
F The .tro object file format
F.1 What an object file says
F.2 A worked example
F.3 File layout
F.4 The records
F.5 How TANREN reads an object file
G Memory
G.1 The memory map
G.2 What goes into the mapper
G.3 How much memory the tools need to build a program
G.4 When the mapper is full
H Where to get the hardware
H.1 What the tools need
H.2 The cartridges
H.3 The makers and where to buy
H.4 Availability
I Environment variables
I.1 Setting a variable
I.2 PATH
I.3 TATARA
I.4 TANREN
I.5 The rules both share
J Source compatibility with M80
J.1 What carries over
J.2 M80 directives that TATARA does not accept
J.3 Other forms
J.4 What TATARA adds
J.5 Other differences
J.6 Converting a source
K The include files
K.1 MSXDOS.INC
K.2 ERRORS.INC
K.3 BIOS.INC
K.4 WORKAREA.INC
K.5 SUBROM.INC
K.6 HOOKS.INC
K.7 PORTS.INC
K.8 ASCII.INC
K.9 EXTBIO.INC
K.10 Further reading
L Glossary
Index