Macros for the 9x8 micro controller

Copyright 2012, Sinclair R.F., Inc.

This document describes the macros for 9x8 micro controller.

Macros are used to access opcodes that cannot be used directly or to help improve code readability and provide syntax checking for some opcodes.

call, callc, jump, and jumpc

The unconditional and the conditional call and jump instructions are three instruction sequences. The first instructions pushes the 8 lsb of the target address onto the stack, the second instruction is the jump or call with the 5 msb of the target address encoded into the instruction, and the third instruction is the instruction that is always executed immediately after the jump or call. Because the first two instructions are dependent on the target address a macro is required to generate the push and the call or jump instruction. Also, because the instruction immediately after the call or jump is always executed immediately after the call or jump it is also generated by the macro. The default value for this third instruction can be changed by including it as the optional second argument to the macro.

fetch, fetch+, fetch-, store, store+, and store-

The fetch and store instructions required the 2 bit memory bank index to be encoded as part of the fetch or store instruction. The memory bank is specified by its name.

The macros also ensure that the provided symbol is a memory bank name.

fetchvalue and storevalue

These macros are used read a value from or write a value to memory by variable name. The offset of the variable within the memory bank is pushed onto the data stack and the memory bank associated with the variable is encoded into the fetch or store instruction. The storevalue macro also consumes the top of the data stack by adding a third, drop instruction.

These macros ensure that the provided symbol is a variable name.

fetchvector and storevector

These macros are used to generate multi-instructions sequences to transfer two or more values between the memory and the data stack. The storevector macro transfers the data stack to memory with the top of the data stack stored at the specified variable, the next value stored at the next location in memory and so forth. The fetchvector macro reads the values from memory in the reverse order in which they were stored so that the fetchvector and storevector macros are inverses of each other.

If the MSB of a multi-byte value is stored at the top of the data stack as per the Forth convention, then the storevector macro places the MSB at the specified variable and the subsequent less significant bytes at subsequent locations in memory.

These macros ensure that the provided symbol is a variable name.

fetchindexed and storeindex

If the top of the data stack is an index into a multi-byte value, these macros can be used to fetch or store the associated value from the specified variable. Using the macro ensures the correct memory bank is used for the specified variable.

These macros ensure that the provided symbol is a variable name.

inport and outport

The inport and outport instructions can be specified directly in the assembly file. However, the code reliability and readability can be improved by using the macros. For example, if the top of the data stack is to be output to the specified port and then dropped, the macro .outport(O_NAME) will generate the required three instruction sequence.

These macros also ensure that and input port or an output port respectively are specified to the macro, thus helping to identify coding mistakes.

return

Because the instruction immediately following the return instruction is executed immediately after the return instruction, a macro is used to ensure that the two instruction sequence is properly generated. The default instruction can be changed by providing the optional argument to the macro.

Macros

Alphebetic listing: .call, .callc, .fetch, .fetch+, .fetch-, .fetchindexed, .fetchvalue, .fetchvector, .inport, .jump, .jumpc, .outport, .return, .store, .store+, .store-, .storeindexed, .storevalue, and .storevector.

.call

Description: Generate the 3 instruction sequence associated with a call instruction.

Operation(1): .call(label) generates the following 3 instructions:
  1 — push the 8 lsb of the label address onto the data stack
  2 — call with the 5 msb of the label address encoded in the call instruction
  3 — no operation

Operation(2): .call(label,op) where "op" is an instruction generates the following 3 instructions:
  1 — push the 8 lsb of the label address onto the data stack
  2 — call with the 5 msb of the label address encoded in the call instruction
  3 — op

Note that Operation(1) is a special case of Operation(2) with "op" being the nop instruction.

.callc

Description: Generate the 3 instruction sequence associated with a callc instruction.

Operation(1): .callc(label) generates the following 3 instructions:
  1 — push the 8 lsb of the label address onto the data stack
  2 — callc with the 5 msb of the label address encoded in the callc instruction
  3 — drop

Operation(2): .callc(label,op) where "op" is an instruction generates the following 3 instructions:
  1 — push the 8 lsb of the label address onto the data stack
  2 — callc with the 5 msb of the label address encoded in the callc instruction
  3 — op

Note that Operation(1) is a special case of Operation(2) with "op" being the drop instruction.

.fetch

Description: Generate the fetch instruction.

Operation: .fetch(ram) generates the following instruction:
1 — fetch with the 2 bit memory index encoded in the fetch instruction.

.fetch+

Description: Generate the fetch+ instruction.

Operation: .fetch+(ram) generates the following instruction:
1 — fetch+ with the 2 bit memory index encoded in the fetch+ instruction.

.fetch-

Description: Generate the fetch- instruction.

Operation: .fetch-(ram) generates the following instruction:
1 — fetch- with the 2 bit memory index encoded in the fetch- instruction.

.fetchindexed

TODO

.fetchvalue

TODO

.fetchvector

TODO

.inport

Description: Generate the 2 instruction sequence associated with a inport instruction.

Operation: .inport(label) generates the following 3 instructions:
1 — push the 8 lsb of the label address onto the data stack
2 — inport

.jump

Description: Generate the 3 instruction sequence associated with a jump instruction.

Operation(1): .jump(label) generates the following 3 instructions:
  1 — push the 8 lsb of the label address onto the data stack
  2 — jump with the 5 msb of the label address encoded in the jump instruction
  3 — no operation

Operation(2): .jump(label,op) where "op" is an instruction generates the following 3 instructions:
  1 — push the 8 lsb of the label address onto the data stack
  2 — jump with the 5 msb of the label address encoded in the jump instruction
  3 — op

Note that Operation(1) is a special case of Operation(2) with "op" being the nop instruction.

.jumpc

Description: Generate the 3 instruction sequence associated with a jumpc instruction.

Operation(1): .jumpc(label) generates the following 3 instructions:
  1 — push the 8 lsb of the label address onto the data stack
  2 — jumpc with the 5 msb of the label address encoded in the jumpc instruction
  3 — drop

Operation(2): .jumpc(label,op) where "op" is an instruction generates the following 3 instructions:
  1 — push the 8 lsb of the label address onto the data stack
  2 — jumpc with the 5 msb of the label address encoded in the jumpc instruction
  3 — op

Note that Operation(1) is a special case of Operation(2) with "op" being the drop instruction.

.outport

Description: Generate the 3 instruction sequence associated with a outport instruction.

Operation(1): .outport(label) generates the following 3 instructions:
  1 — push the 8 lsb of the label address onto the data stack
  2 — outport
  3 — drop

Operation(2): .outport(label,op) generates the following 3 instructions:
  1 — push the 8 lsb of the label address onto the data stack
  2 — outport
  3 — op

Note that Operation(1) is a special case of Operation(2) with "op" being the drop instruction.