Contents
About this manual
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.5.1 What TATARA writes for MAIN.AS
2.5.2 What TATARA writes for PUTSTR.AS
2.5.3 What TANREN does
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.2.1 No extension is added
5.2.2 Leaving out the object file
5.2.3 When the object file is written
5.2.4 The object file cannot be the source
5.3 The options
5.3.1 Options for diagnosis
5.4 What TATARA prints
5.4.1 The banner and the summary line
5.4.2 The usage screen
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
6.6.1 Spaces and tabs
6.6.2 Line length
6.6.3 Line endings
6.6.4 Ctrl-Z
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
7.4.1 Names that start with two question marks
7.4.2 The dollar sign on its own
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.5.1 Precedence
8.6 What kind of value
9 Instructions
9.1 The instruction set
9.2 Operands
9.2.1 Values and brackets
9.2.2 Index registers
9.3 Relative jumps
9.4 The R800 instructions
9.4.1 R800 mnemonics
9.5 The undocumented instructions
9.5.1 How the index halves work
9.5.2 What a program may not rely on
9.5.3 Spellings and names
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.6.1 How it works
10.6.2 Using it safely
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
14.6.1 HOOKS.INC
14.6.2 WORKAREA.INC
14.6.3 PORTS.INC
14.6.4 EXTBIO.INC
14.6.5 ASCII.INC
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.2.1 The last page
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.2.1 Sections
19.2.2 Symbol lines
19.2.3 Names with no value
19.3 The table and the listing
19.4 Diagnostic switches
19.4.1 /F: the fields of each line
19.4.2 /M: macro definitions
19.4.3 /H: memory in use
20 Error messages
20.1 What a message says
20.2 TATARA stops at the first error
20.3 The trail
20.3.1 Reading a trail
20.3.2 A redefined macro
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.1.1 The order of the object files
21.1.2 Spaces between names
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.2.1 A program too big for the command line
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.1.1 What goes into the file
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.3.1 Bytes after the end
27.4 Segments
27.4.1 The limits of one module
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
28.6.1 Leave out PUBLIC
28.6.2 Name the modules the other way round
28.6.3 Assemble one module with /C
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
29.6.1 Subtract a label in one group from a label in another
29.6.2 Add a group in another module
29.6.3 Add to a group from another module
29.6.4 Forget TRANSIENT
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.4.1 .XALL, the default
30.4.2 .LALL
30.4.3 .SALL
30.5 Things to try
30.5.1 Leave out LOCAL
30.5.2 Leave out the &
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
32.6.1 Let TANREN place the code
32.6.2 Call it with USR
32.6.3 Leave out /B
33 A 16 KB ROM cartridge
33.1 The example
33.2 The source
33.2.1 The header
33.2.2 INIT
33.2.3 The last two lines
33.3 Building it
33.4 Running it
33.5 Things to try
33.5.1 Return from INIT
33.5.2 Spoil the ID
33.5.3 Let TANREN place the cartridge
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
34.4.1 Leave LIB out of TATARA
34.4.2 A relative directory in TATARA
34.4.3 Build from another directory
34.4.4 Keep the object files apart
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.1.1 Data
A.1.2 Names
A.1.3 Segments and the location counter
A.1.4 Files and the end of the source
A.1.5 Conditional assembly
A.1.6 Macros and repeat blocks
A.1.7 The listing
A.2 The directives in alphabetical order
A.2.1 The directives that begin with a dot
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
C.3.1 Numbers, characters and the location counter
C.3.2 Kinds of value
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
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.5.1 What TATARA writes for MAIN.AS
2.5.2 What TATARA writes for PUTSTR.AS
2.5.3 What TANREN does
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.2.1 No extension is added
5.2.2 Leaving out the object file
5.2.3 When the object file is written
5.2.4 The object file cannot be the source
5.3 The options
5.3.1 Options for diagnosis
5.4 What TATARA prints
5.4.1 The banner and the summary line
5.4.2 The usage screen
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
6.6.1 Spaces and tabs
6.6.2 Line length
6.6.3 Line endings
6.6.4 Ctrl-Z
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
7.4.1 Names that start with two question marks
7.4.2 The dollar sign on its own
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.5.1 Precedence
8.6 What kind of value
9 Instructions
9.1 The instruction set
9.2 Operands
9.2.1 Values and brackets
9.2.2 Index registers
9.3 Relative jumps
9.4 The R800 instructions
9.4.1 R800 mnemonics
9.5 The undocumented instructions
9.5.1 How the index halves work
9.5.2 What a program may not rely on
9.5.3 Spellings and names
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.6.1 How it works
10.6.2 Using it safely
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
14.6.1 HOOKS.INC
14.6.2 WORKAREA.INC
14.6.3 PORTS.INC
14.6.4 EXTBIO.INC
14.6.5 ASCII.INC
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.2.1 The last page
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.2.1 Sections
19.2.2 Symbol lines
19.2.3 Names with no value
19.3 The table and the listing
19.4 Diagnostic switches
19.4.1 /F: the fields of each line
19.4.2 /M: macro definitions
19.4.3 /H: memory in use
20 Error messages
20.1 What a message says
20.2 TATARA stops at the first error
20.3 The trail
20.3.1 Reading a trail
20.3.2 A redefined macro
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.1.1 The order of the object files
21.1.2 Spaces between names
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.2.1 A program too big for the command line
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.1.1 What goes into the file
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.3.1 Bytes after the end
27.4 Segments
27.4.1 The limits of one module
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
28.6.1 Leave out PUBLIC
28.6.2 Name the modules the other way round
28.6.3 Assemble one module with /C
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
29.6.1 Subtract a label in one group from a label in another
29.6.2 Add a group in another module
29.6.3 Add to a group from another module
29.6.4 Forget TRANSIENT
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.4.1 .XALL, the default
30.4.2 .LALL
30.4.3 .SALL
30.5 Things to try
30.5.1 Leave out LOCAL
30.5.2 Leave out the &
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
32.6.1 Let TANREN place the code
32.6.2 Call it with USR
32.6.3 Leave out /B
33 A 16 KB ROM cartridge
33.1 The example
33.2 The source
33.2.1 The header
33.2.2 INIT
33.2.3 The last two lines
33.3 Building it
33.4 Running it
33.5 Things to try
33.5.1 Return from INIT
33.5.2 Spoil the ID
33.5.3 Let TANREN place the cartridge
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
34.4.1 Leave LIB out of TATARA
34.4.2 A relative directory in TATARA
34.4.3 Build from another directory
34.4.4 Keep the object files apart
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.1.1 Data
A.1.2 Names
A.1.3 Segments and the location counter
A.1.4 Files and the end of the source
A.1.5 Conditional assembly
A.1.6 Macros and repeat blocks
A.1.7 The listing
A.2 The directives in alphabetical order
A.2.1 The directives that begin with a dot
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
C.3.1 Numbers, characters and the location counter
C.3.2 Kinds of value
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