Ninerpedia - User contributions [en]

Geneve physical memory map

2024-06-02T12:15:12Z

Mizapf: /* Memory map */

The physical memory map declares which physical addresses are used to access memory regions or devices.

== Native mode ==

=== Memory map ===

{| class="memory"
! class="top" | Address
! class="top" | Pages
! class="top" | Region
!
|-
! 000000
| class="bank" | 00-3F
| class="dramb" | 512 KiB On-board DRAM
| class="descr" | Slow RAM (1 ws)
|-
! 080000
| class="bank" | 40-7F
| class="b512" | 512 KiB On-board DRAM expansion
| class="descr" | Allocated, but technically infeasible (no sockets or signal lines)
|-
! 100000
| class="bank" | 80-B7
| class="b64" | 448 KiB P-Box space
| class="descr" | May be used by MEMEX card
|-
! 170000
| class="bank" | B8-BF
| class="b64" | 64 KiB P-Box space
| class="descr" | Used by current expansion cards
|-
! 180000
| class="bank" | C0-E7
| class="b64" | Future SRAM expansion
| class="descr" | On-board, but with 1 WS
|-
! 1D0000
| class="bank" | E8-EB
| class="sram" | 32 KiB On-board SRAM expansion
| class="descr" | Soldered on top of the existing 32 KiB chip
|-
! 1D8000
| class="bank" | EC-EF
| class="sram" | 32 KiB On-board SRAM
| class="descr" | Original SRAM memory (0 ws)
|-
! 1E0000
| class="bank" | F0-FF
| class="b128" | 128 KiB Boot EPROM
| class="descr" | Originally, only 16 KiB installed at F0,F1; mirrored
|}

=== Memory expansions ===

The page area 40-7F is assigned to a "Future on-board memory expansion". In fact, the external bus (to the PEB) is not activated during accesses in that area, which means that external cards cannot populate this space. However, the Geneve main board does not offer sockets for such additional on-board memory. It is not possible to add these chips on top of the existing DRAM chips either. The only way to make use of this area is by using the MEMEX in a Genmod configuration.

The page area C0-E7 is assigned to SRAM (0 ws) fast memory. For accesses in that area, the external bus is activated, which means that SRAM chips for that area must be put on a card that plugs into the PEB.

=== Boot EPROM space ===

The Boot EPROM region may have up to 128 KiB space as 16 pages of 8 KiB. This is used with the [[Programmable Flash Memory Expansion | PFM]].

On reset, page F8 is mapped into the 0000-1FFF logical address region. The EPROM on the stock Geneve defines all even pages as mirrors of F0, and all odd pages as mirrors of F1.

== GPL mode ==

=== Memory map ===

{| class="memory"
! class="top" | Address
! class="top" | Pages
! class="top" | Region
!
|-
! 000000
| class="bank" | 00-35
| class="dramb" | 432 KiB On-board DRAM
| class="descr" | Slow RAM (1 ws)
|-
! 06C000
| class="bank" | 36
| class="dram" | 8 KiB Cartridge ROM space (bank 1)
| class="descr" | First bank of cartridge (Extended Basic style)
|-
! 06E000
| class="bank" | 37
| class="dram" | 8 KiB Cartridge ROM space (bank 2)
| class="descr" | Second bank of cartridge (Extended Basic style)
|-
! 070000
| class="bank" | 38-3F
| class="dram" | 64 KiB GRAM Cartridge space
| class="descr" | [[Geneve paged memory organization | Mapper byte 06]] must be set to 0x03 to enable GROM/GRAM
|-
! 080000
| class="bank" | 40-7F
| class="b512" | 512 KiB On-board DRAM expansion
| class="descr" | Allocated, but technically infeasible (no sockets or signal lines)
|-
! 100000
| class="bank" | 80-B7
| class="b128" | 448 KiB P-Box space
| class="descr" | May be used by MEMEX card
|-
! 170000
| class="bank" | B8-BF
| class="b64" | 64 KiB P-Box space
| class="descr" | Used by current expansion cards
|-
! 180000
| class="bank" | C0-E7
| class="b64" | Future SRAM expansion
| class="descr" | On-board, but with 1 WS
|-
! 1D0000
| class="bank" | E8-EB
| class="sram" | 32 KiB On-board SRAM expansion
| class="descr" | Soldered on top of the existing 32 KiB chip
|-
! 1D8000
| class="bank" | EC-EF
| class="sram" | 32 KiB On-board SRAM
| class="descr" | Original SRAM memory (0 ws)
|-
! 1E0000
| class="bank" | F0-FF
| class="b128" | 128 KiB Boot EPROM
| class="descr" | Originally, only 16 KiB installed at F0,F1; mirrored
|}

=== Cartridge emulation ===

The cartridge emulation in the Gate array shows some peculiarities.

* The mapper byte 06 (F116 / 8006) must be set to 03 to enable the GROM/GRAM cartridge space. Otherwise, no GROM/GRAM handling is emulated.
* In GPL mode, logical addresses 6000-7FFF are always mapped to page 36/37, regardless of the mapper byte 03 (F113 / 8003).
* CRU address 1EF8 is used to switch between single or dual bank cartridge ROM. When set to 0, only page 36 is used. When set to 1, writing to cartridge space addresses 6000 + n*4 selects page 36, while writing to 6002 + n*4 selects page 37.
* Cartridge GRAM regions are 8 KiB large, unlike real GROMs with 6 KiB.
* Address wrapping occurs at 8K boundaries (3FFF+1 = 2000).
* Reading via the GROM read address delivers the byte at the current GROM address, then advances the address by 1. Writing puts the byte at the current address, then advances the address by 1.
* Reading the GROM address pointer delivers the MSB, then on every subsequent read access the LSB. The counter contains the former LSB in both bytes after reading and must be restored.

== Genmod ==

The Genmod (Geneve modification) can be run in two modes, selectable by a switch. The TI mode activates the on-board slow DRAM, which is required to run the GPL mode. The reason is that the Gate array maps the GROM accesses to the DRAM on the board, which cannot be changed to the external RAM.

=== TI mode ===

{| class="memory"
! class="top" | Address
! class="top" | Pages
! class="top" | Region
!
|-
! 000000
| class="bank" | 00-35
| class="dramb" | 432 KiB On-board DRAM
| class="descr" | Slow RAM (1 ws)
|-
! 06C000
| class="bank" | 36
| class="dram" | 8 KiB Cartridge ROM space (bank 1)
| class="descr" | First bank of cartridge (Extended Basic style)
|-
! 06E000
| class="bank" | 37
| class="dram" | 8 KiB Cartridge ROM space (bank 2)
| class="descr" | Second bank of cartridge (Extended Basic style)
|-
! 070000
| class="bank" | 38-3F
| class="dram" | 64 KiB GRAM Cartridge space
| class="descr" | [[Geneve paged memory organization | Map byte 06]] must be set to 0x03 to enable GRAM
|--
! 080000
| class="bank" | 40-EF
| class="sraml" | 1408 KiB P-Box memory expansion (MEMEX)
| class="descr" | SRAM (0 ws)
|-
! 1E0000
| class="bank" | F0-FF
| class="b128" | 128 KiB Boot EPROM
| class="descr" | Originally, only 16 KiB installed at F0,F1; mirrored
|}

=== Non-TI mode ===

{| class="memory"
! class="top" | Address
! class="top" | Pages
! class="top" | Region
!
|-
! 000000
| class="bank" | 00-EF
| class="sraml" | 1920 KiB P-Box memory expansion (MEMEX)
| class="descr" | SRAM (0 ws)
|-
! 1E0000
| class="bank" | F0-FF
| class="b128" | 128 KiB Boot EPROM
| class="descr" | Originally, only 16 KiB installed at F0,F1; mirrored
|}

[[Category:Geneve]]

Geneve physical memory map

2024-06-02T12:14:40Z

Mizapf: /* Memory map */

The physical memory map declares which physical addresses are used to access memory regions or devices.

== Native mode ==

=== Memory map ===

{| class="memory"
! class="top" | Address
! class="top" | Pages
! class="top" | Region
!
|-
! 000000
| class="bank" | 00-3F
| class="dramb" | 512 KiB On-board DRAM
| class="descr" | Slow RAM (1 ws)
|-
! 080000
| class="bank" | 40-7F
| class="b512" | 512 KiB On-board DRAM expansion
| class="descr" | Allocated, but technically infeasible (no sockets or signal lines)
|-
! 100000
| class="bank" | 80-B7
| class="b64" | 448 KiB P-Box space
| class="descr" | May be used by MEMEX card
|-
! 170000
| class="bank" | B8-BF
| class="b64" | 64 KiB P-Box space
| class="descr" | Used by current expansion cards
|-
! 180000
| class="bank" | C0-E7
| class="b64" | Future SRAM expansion
| class="descr" | On-board, but with 1 WS
|-
! 1D0000
| class="bank" | E8-EB
| class="sram" | 32 KiB On-board SRAM expansion
| class="descr" | Soldered on top of the existing 32 KiB chip
|-
! 1D8000
| class="bank" | EC-EF
| class="sram" | 32 KiB On-board SRAM
| class="descr" | Original SRAM memory (0 ws)
|-
! 1E0000
| class="bank" | F0-FF
| class="b128" | 128 KiB Boot EPROM
| class="descr" | Originally, only 16 KiB installed at F0,F1; mirrored
|}

=== Memory expansions ===

The page area 40-7F is assigned to a "Future on-board memory expansion". In fact, the external bus (to the PEB) is not activated during accesses in that area, which means that external cards cannot populate this space. However, the Geneve main board does not offer sockets for such additional on-board memory. It is not possible to add these chips on top of the existing DRAM chips either. The only way to make use of this area is by using the MEMEX in a Genmod configuration.

The page area C0-E7 is assigned to SRAM (0 ws) fast memory. For accesses in that area, the external bus is activated, which means that SRAM chips for that area must be put on a card that plugs into the PEB.

=== Boot EPROM space ===

The Boot EPROM region may have up to 128 KiB space as 16 pages of 8 KiB. This is used with the [[Programmable Flash Memory Expansion | PFM]].

On reset, page F8 is mapped into the 0000-1FFF logical address region. The EPROM on the stock Geneve defines all even pages as mirrors of F0, and all odd pages as mirrors of F1.

== GPL mode ==

=== Memory map ===

{| class="memory"
! class="top" | Address
! class="top" | Pages
! class="top" | Region
!
|-
! 000000
| class="bank" | 00-35
| class="dramb" | 432 KiB On-board DRAM
| class="descr" | Slow RAM (1 ws)
|-
! 06C000
| class="bank" | 36
| class="dram" | 8 KiB Cartridge ROM space (bank 1)
| class="descr" | First bank of cartridge (Extended Basic style)
|-
! 06E000
| class="bank" | 37
| class="dram" | 8 KiB Cartridge ROM space (bank 2)
| class="descr" | Second bank of cartridge (Extended Basic style)
|-
! 070000
| class="bank" | 38-3F
| class="dram" | 64 KiB GRAM Cartridge space
| class="descr" | [[Geneve paged memory organization | Mapper byte 06]] must be set to 0x03 to enable GROM/GRAM
|-
! 080000
| class="bank" | 40-7F
| class="b512" | 512 KiB On-board DRAM expansion
| class="descr" | Allocated, but technically infeasible (no sockets or signal lines)
|-
! 100000
| class="bank" | 80-B7
| class="b128" | 448 KiB P-Box space
| class="descr" | May be used by MEMEX card
|-
! 170000
| class="bank" | B8-BF
| class="b64" | 64 KiB P-Box space
| class="descr" | Used by current expansion cards
|-
! 180000
| class="bank" | C0-E7
| class="b64" | Future SRAM expansion
| class="descr" | Only in P-Box
|-
! 1D0000
| class="bank" | E8-EB
| class="sram" | 32 KiB On-board SRAM expansion
| class="descr" | Soldered on top of the existing 32 KiB chip
|-
! 1D8000
| class="bank" | EC-EF
| class="sram" | 32 KiB On-board SRAM
| class="descr" | Original SRAM memory (0 ws)
|-
! 1E0000
| class="bank" | F0-FF
| class="b128" | 128 KiB Boot EPROM
| class="descr" | Originally, only 16 KiB installed at F0,F1; mirrored
|}

=== Cartridge emulation ===

The cartridge emulation in the Gate array shows some peculiarities.

* The mapper byte 06 (F116 / 8006) must be set to 03 to enable the GROM/GRAM cartridge space. Otherwise, no GROM/GRAM handling is emulated.
* In GPL mode, logical addresses 6000-7FFF are always mapped to page 36/37, regardless of the mapper byte 03 (F113 / 8003).
* CRU address 1EF8 is used to switch between single or dual bank cartridge ROM. When set to 0, only page 36 is used. When set to 1, writing to cartridge space addresses 6000 + n*4 selects page 36, while writing to 6002 + n*4 selects page 37.
* Cartridge GRAM regions are 8 KiB large, unlike real GROMs with 6 KiB.
* Address wrapping occurs at 8K boundaries (3FFF+1 = 2000).
* Reading via the GROM read address delivers the byte at the current GROM address, then advances the address by 1. Writing puts the byte at the current address, then advances the address by 1.
* Reading the GROM address pointer delivers the MSB, then on every subsequent read access the LSB. The counter contains the former LSB in both bytes after reading and must be restored.

== Genmod ==

The Genmod (Geneve modification) can be run in two modes, selectable by a switch. The TI mode activates the on-board slow DRAM, which is required to run the GPL mode. The reason is that the Gate array maps the GROM accesses to the DRAM on the board, which cannot be changed to the external RAM.

=== TI mode ===

{| class="memory"
! class="top" | Address
! class="top" | Pages
! class="top" | Region
!
|-
! 000000
| class="bank" | 00-35
| class="dramb" | 432 KiB On-board DRAM
| class="descr" | Slow RAM (1 ws)
|-
! 06C000
| class="bank" | 36
| class="dram" | 8 KiB Cartridge ROM space (bank 1)
| class="descr" | First bank of cartridge (Extended Basic style)
|-
! 06E000
| class="bank" | 37
| class="dram" | 8 KiB Cartridge ROM space (bank 2)
| class="descr" | Second bank of cartridge (Extended Basic style)
|-
! 070000
| class="bank" | 38-3F
| class="dram" | 64 KiB GRAM Cartridge space
| class="descr" | [[Geneve paged memory organization | Map byte 06]] must be set to 0x03 to enable GRAM
|--
! 080000
| class="bank" | 40-EF
| class="sraml" | 1408 KiB P-Box memory expansion (MEMEX)
| class="descr" | SRAM (0 ws)
|-
! 1E0000
| class="bank" | F0-FF
| class="b128" | 128 KiB Boot EPROM
| class="descr" | Originally, only 16 KiB installed at F0,F1; mirrored
|}

=== Non-TI mode ===

{| class="memory"
! class="top" | Address
! class="top" | Pages
! class="top" | Region
!
|-
! 000000
| class="bank" | 00-EF
| class="sraml" | 1920 KiB P-Box memory expansion (MEMEX)
| class="descr" | SRAM (0 ws)
|-
! 1E0000
| class="bank" | F0-FF
| class="b128" | 128 KiB Boot EPROM
| class="descr" | Originally, only 16 KiB installed at F0,F1; mirrored
|}

[[Category:Geneve]]

Geneve video wait states

2024-01-13T00:38:11Z

Mizapf:

The Geneve video wait state handling is controlled by the PAL chip on the board. Unfortunately, there are no public specifications on that custom chip, so all we can do is to try by experiment.

(Update: We do have the PAL equations, found by reverse engineering, but the effects mentioned below still cannot fully be explained.)

Video wait states are created after the access has occured. On that occasion, 14 wait states are created by the counter in the PAL, pulling down the READY line for that period of time. Before this, one or two wait states are inserted since the video access is an external one.

The long wait state period starts after the access, which causes this very access to terminate, and then to start the period for the next command. This means that those wait states are completely ineffective in the following case:

// Assume workspace at F000
F040 MOVB @VDPRD,R3
F044 NOP
F046 DEC R1
F048 JNE F040

The instruction at address F040 requires 5 cycles: get MOVB @,R3, get the source address, read from the source address, 1 WS for this external access, write to register 3. Then the next command is read (NOP) which is in the on-chip RAM (check the addresses). For that reason, the READY pin is ignored, which has been pulled low in the meantime. NOP takes three cycles, as does DEC R1, still ignoring the low READY. JNE also takes three cycles. If R1 is not 0, we jump back, and the command is executed again.

Obviously, the counter is now reset, because we measure that the command again takes only 5 cycles, despite the fact that the 14 WS from last iteration are not yet over.

However, if we add an access to SRAM, we will notice a delay:

// Assume workspace at F000
F040 MOVB @VDPRD,R3 * 5 cycles
F044 MOVB @SRAM,R4 * 15 cycles (4 cycles + 11 WS)
F048 DEC R1 * 3 cycles
F04A JNE F040 * 3 cycles

But we only get 11 WS, not 14. This is reasonable if we remember that the access to SRAM does not occur immediately after the VDP access but after writing to R3 and getting the next command. This can be shown more easily in the following way. ADDR is the constant, symbolizing the memory location; *ADDR means an access to the memory location at address ADDR, < is reading, > is writing. PC is the program counter. The opcode, which is read in the first cycle, contains information about the types of source and destination locations, as well as the register numbers.

{| class="waitstate"
! 1 !! 2 !! 3 !! 4 !! 5 !! 6 !! 7 !! 8 !! 9 !! 10 !! 11 !! 12 !! 13 !! 14 !! 15
|-
| MOVB @,R3
| VDPRD
| class="wait" | wait
| < *VDPRD
| class="wait1" | > R3
|-
| class="wait1" | MOVB @,R4
| class="wait1" | SRAM
| class="wait1" | wait
| class="wait1" | wait
| class="wait1" | wait
| class="wait1" | wait
| class="wait1" | wait
| class="wait1" | wait
| class="wait1" | wait
| class="wait1" | wait
| class="wait1" | wait
| class="wait1" | wait
| class="wait1" | wait
| < *SRAM
| > R3
|-
| DEC R1
| < R1
| > R1
|-
| JNE
| < PC
| > PC
|-
|}

There are several activities going on while the wait states are active "in the background", as symbolized by the blue background. Only when the next access to external memory occurs the wait states become effective. As said above, the read operations only terminate when the READY line gets high again, so we put the termination of the read access in the last box. You should keep in mind that the read access starts right after the last activity.

We can spend so much time inside the on-chip address space that all wait states pass without effect. The following code is executed at the same speed, whether the video wait state bit is set of not:

// Assume workspace at F000
F040 MOVB @VDPRD,R3
NOP
DEC @>F006
DEC @>F006
MOVB @SRAM,R4
DEC R1
JNE F040

as you can see here:

{| class="waitstate"
! 1 !! 2 !! 3 !! 4 !! 5
|-
| MOVB @,R3
| VDPRD
| class="wait" | wait
| < *VDPRD
| class="wait1" | > R3
|-
| class="wait1" | NOP
| class="wait1" | < PC
| class="wait1" | > PC
|-
| class="wait1" | DEC @
| class="wait1" | F006
| class="wait1" | < *F006
| class="wait1" | > *F006
|-
| class="wait1" | DEC @
| class="wait1" | F006
| class="wait1" | < *F006
| class="wait1" | > *F006
|-
| class="wait1" | MOVB @,R4
| class="wait1" | SRAM
| < *SRAM
| > R3
|-
| DEC R1
| < R1
| > R1
|-
| JNE
| < PC
| > PC
|-
|}

Now an example on writing to VDP.

F040 MOVB R3,@>VDPWD
NOP
NOP
NOP
MOVB @SRAM,@>F000
DEC R1
JNE F040

Again as a diagram. Note that box 5 in the first line is not backgrounded: The READY line must be high, or the command will not be completed. We assume that the data are written to VDPWD in box 4 already.

{| class="waitstate"
! 1 !! 2 !! 3 !! 4 !! 5 !! 6 !! 7 !! 8 !! 9
|-
| MOVB R3,@
| < R3
| VDPWD
| class="wait" | > *VDPWD
| wait
|-
| class="wait1" | NOP
| class="wait1" | < PC
| class="wait1" | > PC
|-
| class="wait1" | NOP
| class="wait1" | < PC
| class="wait1" | > PC
|-
| class="wait1" | NOP
| class="wait1" | < PC
| class="wait1" | > PC
|-
| class="wait1" | MOVB @,@
| class="wait1" | SRAM
| class="wait1" | wait
| class="wait1" | wait
| class="wait1" | wait
| class="wait1" | wait
| < *SRAM
| F000
| > *F000
|-
| DEC R1
| < R1
| > R1
|-
| JNE
| < PC
| > PC
|-
|}

There is one peculiarity: We now have 15 wait states, not 14. Indeed, as my measurements prove, the complete code requires 29 cycles, and by using commands in the on-chip RAM as shown in the previous example one can see that the second MOVB line requires 9 cycles, including 4 wait states. As it seems, video writing requires ''one wait state more'' than reading. This may be a design issue of the PAL, but it won't cause any trouble.

Finally we should look at the case when we get wait states by different reasons. Assume we set up the system to use video wait states '''and''' extra wait states.

F040 MOVB R3,@>VDPWD
NOP
NOP
DEC @>F000
MOVB @SRAM,R4
DEC R1
JNE F040

{| class="waitstate"
! 1 !! 2 !! 3 !! 4 !! 5 !! 6 !! 7 !! 8 !! 9
|-
| MOVB R3,@
| < R3
| VDPWD
| class="wait" | > *VDPWD
| class="wait" | wait
| wait
|-
| class="wait1" | NOP
| class="wait1" | < PC
| class="wait1" | > PC
|-
| class="wait1" | NOP
| class="wait1" | < PC
| class="wait1" | > PC
|-
| class="wait1" | DEC @
| class="wait1" | F000
| class="wait1" | < *F000
| class="wait1" | > *F000
|-
| class="wait1" | MOVB @,R4
| class="wait1" | SRAM
| class="wait2" | wait
| class="wait2" | wait
| class="wait1" | wait
| < *SRAM
| > R4
|-
| DEC R1
| < R1
| > R1
|-
| JNE
| < PC
| > PC
|-
|}

First thing to notice is that the first line gets another wait state, since we have requested additional wait states, and VDPWD is an external address. Also, we have 15 wait states from video (blue).

What happens to the additional wait states for the SRAM access in line 5? They occur at the same time as the video wait states, and therefore are not effective. As it seems, the counters for the wait states do not add on each other. The SRAM access is still delayed by 3 wait states (not 2) because there is one wait state left from the video access. After this one is over, the access occurs.

== Unsolved questions ==

There are some '''unsolved questions''', unfortunately. They are not really a problem, but they make it difficult to understand the actual implementation and the way how this could be used within an emulation.

=== VDP write causes one more wait state ===

Why do VDP write accesses cause 1 more wait state than read accesses?

F040 MOVB R3,@>VDPWD
NOP
NOP
NOP
NOP
MOVB @SRAM,R4
DEC R1
JNE F040

{| class="waitstate"
! 1 !! 2 !! 3 !! 4 !! 5 !! 6 !! 7 !! 8 !! 9 !! 10 !! 11 !! 12
|-
| MOVB R3,@
| < R3
| VDPWD
| class="wait" | > *VDPWD
| wait
|-
| class="wait1" | NOP
| class="wait1" | < PC
| class="wait1" | > PC
|-
| class="wait1" | NOP
| class="wait1" | < PC
| class="wait1" | > PC
|-
| class="wait1" | NOP
| class="wait1" | < PC
| class="wait1" | > PC
|-
| class="wait1" | NOP
| class="wait1" | < PC
| class="wait1" | > PC
|-
| class="wait1" | MOVB @,R4
| class="wait1" | SRAM
| class="wait1" | wait
| < SRAM
| > R4
|-
| DEC R1
| < R1
| > R1
|-
| JNE
| < PC
| > PC
|-
|}

When you turn off the video wait states, the above code runs at 27 cycles. With video wait states, it needs 28 cycles. This clearly indicates that all but one wait state have passed in the background, and that last wait state delays the reading of the SRAM memory location. If we assumed that only 14 wait states were produced, the code should not have slowed down by one cycle.

=== Less wait states when next access is write? ===

Compare this:

F040 MOVB @>VDPRD,R3
MOVB @SRAM,R4
DEC R1
JNE F040

{| class="waitstate"
! 1 !! 2 !! 3 !! 4 !! 5 !! 6 !! 7 !! 8 !! 9 !! 10 !! 11 !! 12 !! 13 !! 14 !! 15
|-
| MOVB @
| VDPWD
| class="wait" | wait
| < *VDPRD
| class="wait1" | > R3
|-
| class="wait1" | MOVB @,R4
| class="wait1" | SRAM
| class="wait1" | wait
| class="wait1" | wait
| class="wait1" | wait
| class="wait1" | wait
| class="wait1" | wait
| class="wait1" | wait
| class="wait1" | wait
| class="wait1" | wait
| class="wait1" | wait
| class="wait1" | wait
| class="wait1" | wait
| < *SRAM
| > R4
|-
| DEC R1
| < R1
| > R1
|-
| JNE
| < PC
| > PC
|-
|}

with this one:

F040 MOVB @>VDPRD,R3
MOVB R4,@SRAM
DEC R1
JNE F040

{| class="waitstate"
! 1 !! 2 !! 3 !! 4 !! 5 !! 6 !! 7 !! 8 !! 9 !! 10 !! 11 !! 12 !! 13
|-
| MOVB @
| VDPWD
| class="wait" | wait
| < *VDPRD
| class="wait1" | > R3
|-
| class="wait1" | MOVB R4,@
| class="wait1" | < R4
| class="wait1" | SRAM
| class="wait1" | > *SRAM
| class="wait1" | wait
| class="wait1" | wait
| class="wait1" | wait
| class="wait1" | wait
| class="wait1" | wait
| class="wait1" | wait
| class="wait1" | wait
| class="wait1" | wait
| wait
|-
| DEC R1
| < R1
| > R1
|-
| JNE
| < PC
| > PC
|-
|}

It seems as if the number of wait states depends on the next memory access type, whether read or write. Remember that the last wait state in the second example must show a high READY line, or the operation will not be complete. Accordingly, in the first example, READY is low for 14 cycles, while in the second example we cannot have more than 13 cycles.

=== One more wait state when acquiring instructions? ===

If we put the code in SRAM and access video, the following command should be delayed by 14 WS. However, it turns out to require 15 WS. Have a look:

First we assume that instructions are in on-chip memory, also the registers.

F040 MOVB @>VDPRD,R3
NOP
MOVB @SRAM,R4
DEC R1
JNE F040

{| class="waitstate"
! 1 !! 2 !! 3 !! 4 !! 5 !! 6 !! 7 !! 8 !! 9 !! 10 !! 11 !! 12
|-
| MOVB @,R3
| VDPRD
| class="wait" | wait
| < *VDPRD
| class="wait1" | > R3
|-
| class="wait1" | NOP
| class="wait1" | < PC
| class="wait1" | > PC
|-
| class="wait1" | MOVB @,R4
| class="wait1" | SRAM
| class="wait1" | wait+
| class="wait1" | wait
| class="wait1" | wait
| class="wait1" | wait
| class="wait1" | wait
| class="wait1" | wait
| class="wait1" | wait
| class="wait1" | wait
| < SRAM
| > R4
|-
| DEC R1
| < R1
| > R1
|-
| JNE
| < PC
| > PC
|-
|}

+ At this point the processor attempts to fetch the contents of the memory location at SRAM. The access is delayed until READY goes high.

Tests show that the code as listed above requires 26 cycles. Without video wait states we would get 18 cycles.

Now have a look at this sample. We assume that registers are in on-chip memory and the program code is now in SRAM. This also means that for each command and operand acquisition we need two memory accesses.

A040 MOVB @>VDPRD,R3
NOP
MOVB @SRAM,R4
DEC R1
JNE A040

{| class="waitstate"
! 1 !! 2 !! 3 !! 4 !! 5 !! 6 !! 7 !! 8 !! 9 !! 10
|-
| colspan="2" | MOVB @,R3
| colspan="2" | VDPRD
| class="wait" | wait
| < *VDPRD
| class="wait1" | > R3
|-
| class="wait1" | wait+
| class="wait1" | wait
| class="wait1" | wait
| class="wait1" | wait
| class="wait1" | wait
| class="wait1" | wait
| class="wait1" | wait
| class="wait1" | wait
| class="wait1" | wait
| class="wait1" | wait
|-
| class="wait1" | wait
| class="wait1" | wait
| class="wait1" | wait
| class="wait1" | wait
| colspan="2" | NOP
| < PC
| > PC
|-
| colspan="2" | MOVB @,R4
| colspan="2" | SRAM
| < SRAM
| > R4
|-
| colspan="2" | DEC R1
| < R1
| > R1
|-
| colspan="2" | JNE
| < PC
| > PC
|-
|}

+ At this point the processor tries to acquire the NOP command.

If this code is executed in the on-chip RAM it takes 25 cycles. When executed in SRAM it requires 39 cycles. This seems at first a good number, as we said reading causes 14 wait states. But we forgot that one wait state occurs while writing to R3 (on-chip), so we should only have 13 effective WS.

The command acquision from SRAM begins in the second line but completes exactly when the READY line goes high again, reading the first and then the second byte of NOP. We must therefore assume 15 WS.

Still, cause comes before effect: the PAL cannot "know" after line 1 that it must set the counter 1 higher. The PAL may possibly know that the current read cycle is an instruction acquisition, as the IAQ line is connected to one of its pins. When acquiring an opcode, the line gets asserted (high), unlike for operand acquisitions where it remains low.

=== Instruction prefetch as a possible reason ===

There may also be an effect from the processor's [[instruction prefetch]] capability. As mentioned, the TMS9995 is highly efficient in its usage of clock cycles, which is only possible when it can get the next instruction during internal operations. The additional wait state is probably be caused by the fact that external accesses are still blocked by the READY line, so one more cycle may be required.

__NOTOC__

[[Category:Geneve]]

File systems

2023-08-31T20:50:40Z

Mizapf: /* Volume Information Block (HFDC) */

== Floppy Disk File System ==

Floppy file systems had no notion of subdirectories for most of the time. Disk controllers like the Myarc FDC and HFDC introduced a directory scheme where the root directory may have up to three subdirectories. These subdirectories may have no subdirectories by themselves.

=== Volume Information Block ===

{| class="filesys"
|-
! 00
| rowspan="5" colspan="2" | Volume name
| rowspan="5" class="descr" | May not contain a dot (".") because this is used as the path separator. Padded with spaces.
|-
! 02
|-
! 04
|-
! 06
|-
! 08
|-
! 0A
| colspan="2"| Total number of sectors
|-
! 0C
| Sectors per track
| "D"
|-
! 0E
| "S"
| "K"
|-
! 10
| Protection
| Tracks per side
|-
! 12
| Number of sides
| Density
| class="descr" | Density may have values 0 .. 4 (see below)
|-
! 14
| colspan="2" rowspan="5" | Directory 1 name
| rowspan="5" class="descr" | Same constraints as for file or volume name
|-
! 16
|-
! 18
|-
! 1A
|-
! 1C
|-
! 1E
| colspan="2" | Sector number of FDIR of dir 1
| class="descr" | Null if no directory exists. Only on start of AU.
|-
! 20
| colspan="2" rowspan="5" | Directory 2 name
|-
! 22
|-
! 24
|-
! 26
|-
! 28
|-
! 2A
| colspan="2" | Sector number of FDIR of dir 2
|-
! 2C
| colspan="2" rowspan="5" | Directory 3 name
|-
! 2E
|-
! 30
|-
! 32
|-
! 34
|-
! 36
| colspan="2" | Sector number of FDIR of dir 3
|-
! 38
| colspan="2" rowspan="5" | Allocation bit map
| rowspan="5" class="descr" | Each bit represents a collection of sectors on the disk (see below)
|-
! 3A
|-
! 3C
|-
! ...
|-
! FE
|-
|}

Density values:
* Single (0,1): 125 kBit/s FM
* Double (2): 250 kBit/s MFM
* High (3): 500 kBit/s MFM
* Ultra (4): 1MBit/s MFM

=== File Descriptor Index Record ===

The File Descriptor Index Record (FDIR) contains pointers to the File Descriptor Records. The pointers are arranged so that the list of files has a lexicographic order (alphabetic sorting). The FDIR of the root directory is always in sector 1. The FDIRs of the subdirectories are pointed to by the respective fields in sector 0.

The end of the list is marked by the first null pointer.

{| class="filesys"
|-
! 00
| Sector number of first file descriptor record
| class="descr" | Always sector number, not AU
|-
! 02
| Sector number of second file descriptor record
|-
! 04
| Sector number of third file descriptor record
|-
! 06
| Sector number of fourth file descriptor record
|-
! ...
|-
! FC
| Sector number of 127th file descriptor record
|-
! FE
| 0
|-
|}

Unlike the FDIRs in the hard disk file system there is no pointer back to the parent directory as the floppy file system does not allow nested subdirectories, and thus the parent is always the root directory.

=== File Descriptor Records ===

Each file entry in the diretory is defined by a file descriptor record.

{| class="filesys" style="width:90%"
|-
! 00
| colspan="2" rowspan="5" | File name
|-
! 02
|-
! 04
|-
! 06
|-
! 08
|-
! 0A
| colspan="2" | Extended record length
| class="descr" | used for logical record lengths beyond 255
|-
! 0C
| File status flags
| Number of records/sec
|-
! 0E
| colspan="2" | Number of sectors currently allocated
|-
! 10
| End-of-file offset
| Logical record length
|-
! 12
| colspan="2" | Level 3 record count (little-endian)
|-
! 14
| colspan="2" rowspan="2" | Date and time of creation
| class="descr" | hhhh.hmmm.mmms.ssss (2 seconds resolution)
|-
! 16
| class="descr" | yyyy.yyyM.MMMd.dddd
|-
! 18
| colspan="2" rowspan="2" | Date and time of last update
|-
! 1A
|-
! 1C
| rowspan="4" colspan="2" | Data chain pointer blocks
|-
! 1E
|-
! ...
|-
! FE
|-
|}

The '''Extended record length''' field (offset 0x0A) is used for record lengths beyond 255; up to 255 bytes the length is given by the byte at offset 0x11. The HFDC introduced this field, but it is unknown whether it was ever used. According to [1], the Extended Record Length field defines the length of records of data files when the ''Logical Record Length'' field (offset 0x11) is 0.

The '''File status flags''' are defined as follows (see also [[TIFILES format]]):

{| class="tfiflags"
|-
!
! MSB
!
!
!
!
!
!
! LSB
|-
| 0
| FIXED
| rowspan="2" style="background-color:#eeeeee"| Reserved
| normal
| Unmodified
| Unprotected
| rowspan="2" style="background-color:#eeeeee" | Reserved
| DISPLAY
| Data
|-
| 1
| VARIABLE
| [[Emulate File format|Emulate File]]
| Modified
| Protected
| INTERNAL
| Program
|}

The '''EOF offset''' is the location in the last sector where the EOF marker is found. Only variable length data files have an EOF marker (0xff). For program files and fixed length files this field points to the first byte after the file contents. If the EOF offset contains 0, the last sector is completely filled with data.

To recreate the actual file length,

* the total number of sectors must be multiplied by 256
* the number of bytes past the EOF marker must be subtracted (if the offset is not 0).

That is, if the number of sectors is 10 and the EOF offset is 36, the file length is (10*256) - (256-36) = 2340. If the EOF offset is zero, we get the full 2560 bytes.

The '''Level 3 record count''' (offset 0x12 and 0x13) specifies the number of [[records]] in [[data files]]; this means the number of times you can execute an INPUT operation on that file. In the case of fixed length records, the field "Number of Level-3 records" contains the highest record actually written to. If the last sector is filled as far as possible, we have

:''L3 = Records/Sector * Total number of sectors''

This number is required to determine the highest record number, especially if the last sector is not filled completely.

In the case of variable length records, it contains the highest sector actually written to and should therefore be equal to the field "Total number of sectors".

For program files, 0x0000 is usually found in this field.

'''NOTE''': The bytes in this field are in '''reverse order''' (little-endian).

The '''Creation''' and '''Update time specification''' are two 16-bit words, the bits having the following meaning:

* hhhh.hmmm.mmms.ssss
* yyyy.yyyM.MMMd.dddd

With only 5 bits for seconds, the timestamp has a resolution of 2 seconds. The years reach from 1970 (values 70..99) to 2069 (values 0..69).

These bytes were reserved for future expansion, and will always be 0 on a disk formatted with the TI Disk Manager Module.

The '''Data chain pointers''' are used to refer to sections on the disk where fragments of the file will be found. There is always at least one data chain pointer; if there are more, the file is ''fragmented''.

Every data chain pointer consists of three bytes with two hex digits each, so we have six hex digits

{| style="width:40%; text-align:center"
|-
| 1
| 2
| 3
| 4
| 5
| 6
|-
| M2
| M1
| N1
| M3
| N3
| N2
|-
|}

from where we get the 16-bit numbers

* M = 0 M3 M2 M1: Sector or AU number of start of chain element
* N = 0 N3 N2 N1: Highest file sector count (starting at 0) for this chain element

This may sound a bit confusing, therefore I'm adding an example. Here are the pointers for the data chain:

36 10 00, 44 30 00, ac 62 00, 03 b3 00, 17 04 01

Using the mapping from above, we get

M = 0036 0044 02ac 0303 0417
N = 0001 0003 0006 000b 0010

Sectors
0:0036 2:0044 4:02ac 7:0303 12:0417
1:0037 3:0045 5:02ad 8:0304 13:0418
6:02ae 9:0305 14:0419
10:0306 15:041a
11:0307 16:041b

This means: The file occupies the sectors >0036 (sector 0), >0037 (sector 1), >0044 (sector 2), ... >041b (sector 16). Note that N does not provide the length of the current chain element but the total number of read sectors after reading this chain element. Counting from 0, and together with the directory entry, we have

:''The number of sectors which a file occupies on the disk is N<sub>last</sub>+1''

Or you may want calculate the intervals as follows:

: ''intv(i).start = M<sub>i</sub>''
: ''intv(i).end = M<sub>i</sub> + N<sub>i</sub> - (N<sub>i-1</sub> + 1)''

with ''N<sub>-1</sub>=-1''.

Important comment to '''sector/AU usage''': For disks with capacities up to 720 KiB (2880 sectors), the M-value refers to a sector. For disks with higher capacities (1.44 or 2.88 MiB, i.e. 5760 or 11520 sectors), M-values are AUs. The N-values are always sector counts, even when the M-value points to an AU.

=== Allocation Bit Map ===

This map shows which sectors are occupied by files on this file system. The map is located starting at byte 0x38 and reaching to the end of this sector, so its size is 200 bytes. This means that for file systems with more than 1600 sectors, clusters must be formed which serve as ''allocation units'' (AU).

Bits are organized in little-endian order. That is, a value of 0x01 declares the AU with the smallest number of a block of 8 to be allocated. On floppy disks with less than 1600 sectors, the allocation map is usually preset with 0x03, reserving sector 0 and sector 1.

{| class="filesys"
|-
| AU 7
| AU 6
| AU 5
| AU 4
| AU 3
| AU 2
| AU 1
| AU 0
|-
|}

Disks with a capacity of at most 400 KiB have an AU size of 1 sector (all SSSD, SSDD, DSSD, DSDD, with 40 tracks, at most 1440 sectors). Disks with at most 800 KiB space have 2 sectors per AU (720 KiB, 2880 sectors), with 1.4 MiB we have 4 sectors per AU, and the disks with ultra capacity (2.8 MiB) have 8 sectors per AU.

== Hard Disk File System ==

The file system is defined by

* the Volume Information Block
* the Directory Descriptor Records
* the File Descriptor Index Records
* the File Descriptor Records, and
* the Allocation Bit Map

=== Volume Information Block (HFDC) ===

The Volume information block (VIB) contains information about the complete file system on this volume. It is located in the first sector of the volume. The VIB takes the role both of the volume specifier and of the root directory specifier. Therefore, we find directory information as well as volume information in this block.

{| class="filesys" style="width:50%"
|-
! 00
| colspan="4" rowspan="5" | Volume name
|-
! 02
|-
! 04
|-
! 06
|-
! 08
|-
! 0A
| colspan="4" | Total number of allocation units
|-
! 0C
| colspan="2" | Sectors/Track
| colspan="2" | Reserved AUs / W
|-
! 0E
| colspan="2" | Step speed / I
| colspan="2" | Red. write current / N
|-
! 10
| Sect/AU -1
| Heads -1
| BS
| Write precomp
|-
! 12
| colspan="4" rowspan="2"| Date and time of creation
|-
! 14
|-
! 16
| colspan="2" | # of files
| colspan="2" | # of subdirectories
|-
! 18
| colspan="4" | AU number of file descriptor index record
|-
! 1A
| colspan="4" | AU number of DSK1 emulation file
|-
! 1C
| colspan="4" rowspan="5" | AU numbers of subdirectories (DDR)
|-
! 1E
|-
! 20
|-
! ...
|-
! FE
|-
|}

The W,I,N values may be present after initial formatting. Usually they are replaced by the given settings.

'''Reserved AUs''' (0-255): Value is divided by 64 (0x40) and declares the start AU for file contents (0-16320). For instance, with a value of 0x15, file contents are stored at AUs 0x0540 and higher.

There are 114 slots for pointers to subdirectories (from 0x1c to 0xff, 2 bytes each), so this is the maximum number of subdirectories in a directory.

==== Special MFM parameters ====

'''Step speed''' (0-255): Controllers like the HDC9234 on the HFDC card use the value for step timing. The number is controller-specific.

'''Reduced write current''' (0-255): Value is divided by 8 and indicates the cylinder number (0-2040) starting from which the write current in the write head is reduced.

'''BS''' = Buffered head stepping (one bit, 0 or 1): Some drives allow for fast stepping by increasing a step counter and then performing a fast, single seek.

'''Write precompensation''' (0-127): Value is divided by 16 and indicates the cylinder number (0-2032) starting from which the timing of the flux writing is changed.

=== Volume Information Block (SCSI) ===

The Volume information block (VIB) contains information about the complete file system on this volume. It is located in the first sector of the volume. The VIB takes the role both of the volume specifier and of the root directory specifier. Therefore, we find directory information as well as volume information in this block.

{| class="filesys" style="width:50%"
|-
! 00
| colspan="2" rowspan="5" | Volume name
|-
! 02
|-
! 04
|-
! 06
|-
! 08
|-
! 0A
| colspan="2" | Total number of AUs
|-
! 0C
| Reserved
| Reserved AUs / W
|-
! 0E
| Unused / I
| Unused / N
|-
! 10
| Sectors per AU
| Unused
|-
! 12
| colspan="2" rowspan="2" | Date and time of creation
|-
! 14
|-
! 16
| # of files
| # of subdirectories
|-
! 18
| colspan="2" | AU number of file descriptor index record
|-
! 1A
| colspan="2" style="border: 1px solid black; padding:0.5ex" | Reserved
|-
! 1C
| colspan="2" rowspan="5" | AU numbers of subdirectories (DDR)
|-
! 1E
|-
! 20
|-
! ...
|-
! FE
|-
|}

Byte >10 is the same as in the HFDC VIB (first 4 bits, adding 1). Thus, a value of >F0 means 16 sectors per AU and is the maximum number. The other four bits are not used. See above for the meaning of '''Reserved AUs'''.

=== Directory Descriptor Records ===
Each directory is defined by a directory descriptor record (DDR). It is structured similarly to a VIB.

{| class="filesys" style="width:50%"
|-
! 00
| colspan="2" rowspan="5" style="border: 1px solid black; padding:0.5ex" | Directory name
|-
! 02
|-
! 04
|-
! 06
|-
! 08
|-
! 0A
| colspan="2" style="border: 1px solid black; padding:0.5ex" | HFDC: Total number of AUs / SCSI: unused
|-
! 0C
| style="border: 1px solid black; padding:0.5ex; width:50%" | unused
| style="border: 1px solid black; padding:0.5ex; width:50%" | "D"
|-
! 0E
| style="border: 1px solid black; padding:0.5ex; width:50%" | "I"
| style="border: 1px solid black; padding:0.5ex; width:50%" | "R"
|-
! 10
| colspan="2" style="border: 1px solid black; padding:0.5ex" | unused
|-
! 12
| colspan="2" rowspan="2" style="border: 1px solid black; padding:0.5ex" | Date and time of creation
|-
! 14
|-
! 16
| style="border: 1px solid black; padding:0.5ex" | # of files
| style="border: 1px solid black; padding:0.5ex" | # of subdirectories
|-
! 18
| colspan="2" style="border: 1px solid black; padding:0.5ex" | Pointer to file descriptor index record (FDIR)
|-
! 1A
| colspan="2" style="border: 1px solid black; padding:0.5ex" | Pointer to the parent directory AU
|-
! 1C
| colspan="2" rowspan="5" style="border: 1px solid black; padding:0.5ex" | AU numbers of subdirectories (DDR)
|-
! 1E
|-
! 20
|-
! ...
|-
! FE
|-
|}

=== File Descriptor Index Records ===

As space in a DDR is limited, the files are referenced outside the DDR, using a File Decriptor Index Record (FDIR). There is one FDIR per directory. The FDIR is also responsible for the ordering of file names in the directory. That is, new files are inserted into the list, preserving alphabetical order.

The end of the list is marked by the first null pointer. Note that the FDIR for hard disks contain pointers to '''allocation units''', not to sectors.

The last entry of the list (position >FE) points back to the containing directory AU. With a sector size of 256 bytes we can have 127 files per directory at most.

{| class="filesys"
|-
! 00
| AU number of first file descriptor record
|-
! 02
| AU number of second file descriptor record
|-
! 04
| AU number of third file descriptor record
|-
! 06
| AU number of fourth file descriptor record
|-
! ...
|-
! FC
| AU number of 127th file descriptor record
|-
! FE
| AU number of directory descriptor record of this FDIR
|-
|}

=== File Descriptor Records ===
Each file is defined by a file descriptor record.

{| class="filesys" style="width:50%"
|-
! 00
| colspan="2" rowspan="5" style="border: 1px solid black; padding:0.5ex" | File name
|-
! 02
|-
! 04
|-
! 06
|-
! 08
|-
! 0A
| colspan="2" style="border: 1px solid black; padding:0.5ex" | Extended record length
|-
! 0C
| style="border: 1px solid black; padding:0.5ex; width:50%" | File status flags
| style="border: 1px solid black; padding:0.5ex; width:50%" | Number of records/sec
|-
! 0E
| colspan="2" style="border: 1px solid black; padding:0.5ex" | Number of sectors currently allocated (also see extended information)
|-
! 10
| style="border: 1px solid black; padding:0.5ex" | End-of-file offset
| style="border: 1px solid black; padding:0.5ex" | Logical record length
|-
! 12
| colspan="2" style="border: 1px solid black; padding:0.5ex" | Number of level 3 records allocated (also see extended information)
|-
! 14
| colspan="2" rowspan="2" style="border: 1px solid black; padding:0.5ex" | Date and time of creation
|-
! 16
|-
! 18
| colspan="2" rowspan="2" style="border: 1px solid black; padding:0.5ex" | Date and time of last update
|-
! 1A
|-
! 1C
| style="border: 1px solid black; padding:0.5ex" | "F"
| style="border: 1px solid black; padding:0.5ex" | "I"
|-
! 1E
| colspan="2" style="border: 1px solid black; padding:0.5ex" | Pointer to previous FDR (AU)
|-
! 20
| colspan="2" style="border: 1px solid black; padding:0.5ex" | Pointer to next FDR (AU)
|-
! 22
| colspan="2" style="border: 1px solid black; padding:0.5ex" | Number of AUs allocated by this FDR for the file content
|-
! 24
| colspan="2" style="border: 1px solid black; padding:0.5ex" | Pointer to file descriptor index record (AU)
|-
! 26
| colspan="2" style="border: 1px solid black; padding:0.5ex" | Extended information (see below)
|-
! 28
| rowspan="4" colspan="2" style="border: 1px solid black; padding:0.5ex" | Data chain pointer blocks (AU)
|-
! 2A
|-
! ...
|-
! FE
|-
|}

For hard drives, the data chain pointer blocks are structured differently. We have four bytes per chain element, two for the start AU, and two for the end AU.

The extended information is a 16-bit word ABCD, built up as follows:

{| class="plain" style="width:60%"
! A
! B
! C
! D
|-
| Number of allocated sectors / 65536
| Number of sectors of a VARIABLE file / 65536
| Sector number in AU pointing to previous FDR
| Sector number of AU pointing to next FDR
|-
|}

The file system allows for multiple chained FIBs in case the cluster list does not fit into one FIB. Unlike the original FIB, the next FIBs may obviously be located in other sectors within an AU, not in the first one: It is possible to define which sector in the given AU actually contains the next FIB. However, this only makes sense if the first sector in the AU is from the same file; otherwise, when deleting a file, it would be impossible to decide whether an AU can be freed or not without checking each other file on the medium.

Anyway, it should be a pretty rare case; I've never seen a file that was so heavily fragmented to require more than one FIB.

=== Allocation Bit Map ===

The allocation bitmap is located in sectors 1 to 31 where each bit represents one allocation unit. That is, we have
31 sector * 256 byte/sector * 8 bit/byte * 1 AU/bit = 63488 AUs = >F800 AUs.

'''Caution''': The bit order in the bytes of the allocation map is '''big-endian''', different to the situation with floppy disks.

{| class="filesys"
|-
| AU 0
| AU 1
| AU 2
| AU 3
| AU 4
| AU 5
| AU 6
| AU 7
|-
|}

The allocation bitmap limits the maximum size of a hard drive in terms of allocation units. The maximum number of sectors in an allocation unit is determined by byte >10 in the VIB which leaves only 4 bits for this number (adding 1), so the maximum is 16.

That is, we ultimately have a maximum usable space of
16 sector/AU * 63488 AU * 256 byte/sector = 260046848 byte

that is 248 MiB. Any bigger drive will stay unused beyond this point.

== References ==

[1] Myarc, Inc.: ''Hard and Floppy Disk Controller / Users manual''

[2] Western Horizon Technologies: ''Small Computer Systems Interface Host Adapter Card / Software Interface Specification'', 1993

[[Category:Programming]]

User talk:Mizapf

2023-08-31T20:30:20Z

Mizapf: /* Notes for further editing */

=== Notes for further editing ===

* Using the TI console as an external keyboard
* BASIC file formats

== Spammer ==

[[Special:Contributions/Epergrem]] -- blocked by me, Aug 31, 2023

User talk:Mizapf

2023-08-31T20:29:54Z

Mizapf: /* Spammer */

=== Notes for further editing ===

* Running MESS on Raspi
* Using the TI console as an external keyboard
* BASIC file formats

== Spammer ==

[[Special:Contributions/Epergrem]] -- blocked by me, Aug 31, 2023

MESS Troubleshooting

2023-02-24T20:24:31Z

Mizapf:

== On startup ==

=== Error message concerning shared object file (Linux) ===
'''Q: When trying to start mess I'm getting an error message "error while loading shared libraries: libSDL_ttf-2.0.so.0: cannot open shared object file: No such file or directory".'''

A: You must install SDL support, in this case the TTF library is missing. Check your software installation and add the required libraries.

=== Screen is black ===
'''Q: The system does not start. The screen remains black.'''

A1 '''(GRAMKracker)''': You have activated the GRAMKracker support, you have set the GK DIP switches to point to GRAM 0 (instead of OpSys), and you have not inserted the GRAMKracker cartridge, or the cartridge is empty. Please read the GK manual.

A2 '''(HSGPL)''': You switched on the [[HSGPL]] without previously uploading an operating system to the HSGPL. As the HSGPL is always active for the SGCPU, you will encounter the same problem there.

The HSGPL is a buffered memory card which replaces the console's ROM and GROM content. When you turn it on, MESS automatically unplugs all memory in the console until you turn off the card again. When you buy an HSGPL card you get a preloaded system. To achieve this in MESS, you have to set the HSGPL configuration switch to "Flash". This allows access to the card but prevents it from taking control. Now you can use a tool like DSRLDR to flash the (emulated) ROMs on the card using a ROM package. When done, you must copy the desired operating system version from the backup positions in the card to the location expected by the system (ROM and GROM). I have written a simple tool to perform this step. Finally, put the switch to the "on" position and reset the emulator.

The HSGPL was sold by the System 99'er User Group ([[SNUG]]), so you should ask them to provide you with a suitable ROM package.

=== Error loading multicart: no pcb found ===
'''Q: I'm getting this message on startup.'''

A: You seem to have attempted to mount a cartridge using the (long obsoleted) "bin" format. Please use only [[MESS multicart system | RPK packages]] as cartridges. You can find almost all known cartridges on the FTP server of whtech.

== During runtime ==

=== RS232/PIO output hangs ===
'''Q: When I try to output a file through RS232 or PIO, the computer seems to hang.'''

A: You have probably forgotten to "insert" an image into the RS232 or PIO device. Check the file manager and define an output file (similar to inserting a disk image into a drive). When printing to PIO or RS232, the contents are appended to the image file.

[[Category:MESS]]

MAME

2023-02-24T20:22:51Z

Mizapf: /* Using */

[[Image:mess_logo_n.png|150px|right]]
MESS (Multiple Emulator Super System) is a multi-system emulator which emulates more than 400 computer systems, many of them from the good old days of the Home Computers. Among them are also a number of TI platforms:

* TI-99/2 (24K and 32K ROM version)
* TI-99/4, 50 Hz and 60 Hz
* TI-99/4A, 50 Hz and 60 Hz
* TI-99/4QI, 50 Hz and 60 Hz
* TI-99/8
* Geneve 9640

A number of peripherals are also emulated, ranging from various disk controllers (up to HFDC), to serial interfaces, USB interface, IDE interface, HSGPL, and also SGCPU.

The emulator is freely downloadable from [http://www.mamedev.org/release.html mamedev.org] as a pre-built binary for Windows systems, and as a source zip archive for all platforms.

You can download and work on the MAME source codes, since all MAME components have been relicenced under an open-source licence (BSD or GPL). If you want to contribute, you should get in contact with the maintainers, though. A good location for that is the [http://forums.bannister.org/ubbthreads.php?ubb=postlist&Board=1&page=1 MESS message board].

I would be happy to see more people from the TI community helping to improve the TI emulation in MESS.

<div style="clear:both; margin-top:2em"></div>
<div style="float:left; padding:1em; height: 35em; width:45%; background-color:#ddddee">

==Installing and setup==

* [https://www.mizapf.de/en/ti99/mame/buildmame Building MAME] from source
* [https://www.mizapf.de/ti99/mame/winstmame Installing on Windows systems]
* [https://www.mizapf.de/en/ti99/mame/ Getting the ROMs]
* [[Setting up the HSGPL for MAME]]
* [[Setting up the Horizon Ramdisk]]

</div>

<div style="margin-left:50%; padding:1em; height: 35em;width:45%; background-color:#ddeedd">

==Using==

* [https://www.ninermame.org/info/scope Features of the TI and Geneve emulation in MAME]
* [[MAME TI emulation usage|Working with the TI/Geneve emulation]]
* [[MESS and TI cartridges|Cartridges]]
* [[MESS media handling|Media handling]]
** [[MESS media handling#Using_your_TI_and_Geneve_hard_drive_in_MESS|Using your TI/Geneve hard drive in MESS]]
** [[MESS media handling#Formatting_disks|Formatting disks]]
** [[MESS media handling#Setting_up_a_blank_hard_disk|Setting up a blank hard disk]]
** [[MESS media handling#Upgrading_to_new_CHD_format|Upgrading CHD version]]
** [[MESS media handling#IDE disk handling|Using the IDE HD controller]]
* [[MESS debugger|Built-in debugger]]
* [https://www.mizapf.de/ti99/timt TIImageTool] - a GUI-based image manager
</div>

<div style="clear:both; height:1em"></div>

<div style="float:left; padding:1em; height: 30em;width:45%; background-color:#eedddd">

==Questions and Troubleshooting==

* Some help for [[MESS Troubleshooting]].
* [[MESSFAQ | Frequently Asked Questions]] related to the TI/Geneve emulation in MESS.
* [https://www.ninermame.org/using/keyboard/uimodekey Change MESS menu mode key] from Scroll Lock to another key
* Hassle with the [[MESS keyboard modes]]
</div>

<div style="padding:1em; margin-left:50%; height: 30em;width:45%; background-color:#ddeeee">

==Details==

* Basics: [[Emulation and Simulation]]
* [[Guided tour through MESS|Get a look under the hood of MESS]]
* The [[MESS cartridge handling|cartridge system]] of MESS
* Programmer's Guide to MESS
* [https://www.mizapf.de/ti99/mame/changes MAME version history] with features, fixes, and regressions list
* [https://www.ninermame.org/details/serialconn RS232 emulation]
* [[MAME Internals]]
* [[MAME Floppy sound emulation | Floppy sound emulation]]
</div>

<div style="clear:both; margin-bottom:2em"></div>

__NOTOC__

[[Category:Emulation]]
[[Category:MAME]]

MAME

2023-02-24T20:21:52Z

Mizapf: /* Questions and Troubleshooting */

[[Image:mess_logo_n.png|150px|right]]
MESS (Multiple Emulator Super System) is a multi-system emulator which emulates more than 400 computer systems, many of them from the good old days of the Home Computers. Among them are also a number of TI platforms:

* TI-99/2 (24K and 32K ROM version)
* TI-99/4, 50 Hz and 60 Hz
* TI-99/4A, 50 Hz and 60 Hz
* TI-99/4QI, 50 Hz and 60 Hz
* TI-99/8
* Geneve 9640

A number of peripherals are also emulated, ranging from various disk controllers (up to HFDC), to serial interfaces, USB interface, IDE interface, HSGPL, and also SGCPU.

The emulator is freely downloadable from [http://www.mamedev.org/release.html mamedev.org] as a pre-built binary for Windows systems, and as a source zip archive for all platforms.

You can download and work on the MAME source codes, since all MAME components have been relicenced under an open-source licence (BSD or GPL). If you want to contribute, you should get in contact with the maintainers, though. A good location for that is the [http://forums.bannister.org/ubbthreads.php?ubb=postlist&Board=1&page=1 MESS message board].

I would be happy to see more people from the TI community helping to improve the TI emulation in MESS.

<div style="clear:both; margin-top:2em"></div>
<div style="float:left; padding:1em; height: 35em; width:45%; background-color:#ddddee">

==Installing and setup==

* [https://www.mizapf.de/en/ti99/mame/buildmame Building MAME] from source
* [https://www.mizapf.de/ti99/mame/winstmame Installing on Windows systems]
* [https://www.mizapf.de/en/ti99/mame/ Getting the ROMs]
* [[Setting up the HSGPL for MAME]]
* [[Setting up the Horizon Ramdisk]]

</div>

<div style="margin-left:50%; padding:1em; height: 35em;width:45%; background-color:#ddeedd">

==Using==

* [https://www.ninermame.org/info/scope Features of the TI and Geneve emulation in MAME]
* [[MAME TI emulation usage|Working with the TI/Geneve emulation]]
* [[Tools for MESS|Tools]]
* [[MESS and TI cartridges|Cartridges]]
* [[MESS media handling|Media handling]]
** [[MESS media handling#Using_your_TI_and_Geneve_hard_drive_in_MESS|Using your TI/Geneve hard drive in MESS]]
** [[MESS media handling#Formatting_disks|Formatting disks]]
** [[MESS media handling#Setting_up_a_blank_hard_disk|Setting up a blank hard disk]]
** [[MESS media handling#Upgrading_to_new_CHD_format|Upgrading CHD version]]
** [[MESS media handling#IDE disk handling|Using the IDE HD controller]]
* [[MESS debugger|Built-in debugger]]
* [https://www.mizapf.de/ti99/timt TIImageTool] - a GUI-based image manager
</div>

<div style="clear:both; height:1em"></div>

<div style="float:left; padding:1em; height: 30em;width:45%; background-color:#eedddd">

==Questions and Troubleshooting==

* Some help for [[MESS Troubleshooting]].
* [[MESSFAQ | Frequently Asked Questions]] related to the TI/Geneve emulation in MESS.
* [https://www.ninermame.org/using/keyboard/uimodekey Change MESS menu mode key] from Scroll Lock to another key
* Hassle with the [[MESS keyboard modes]]
</div>

<div style="padding:1em; margin-left:50%; height: 30em;width:45%; background-color:#ddeeee">

==Details==

* Basics: [[Emulation and Simulation]]
* [[Guided tour through MESS|Get a look under the hood of MESS]]
* The [[MESS cartridge handling|cartridge system]] of MESS
* Programmer's Guide to MESS
* [https://www.mizapf.de/ti99/mame/changes MAME version history] with features, fixes, and regressions list
* [https://www.ninermame.org/details/serialconn RS232 emulation]
* [[MAME Internals]]
* [[MAME Floppy sound emulation | Floppy sound emulation]]
</div>

<div style="clear:both; margin-bottom:2em"></div>

__NOTOC__

[[Category:Emulation]]
[[Category:MAME]]

MAME

2023-02-24T20:20:22Z

Mizapf: /* Details */

[[Image:mess_logo_n.png|150px|right]]
MESS (Multiple Emulator Super System) is a multi-system emulator which emulates more than 400 computer systems, many of them from the good old days of the Home Computers. Among them are also a number of TI platforms:

* TI-99/2 (24K and 32K ROM version)
* TI-99/4, 50 Hz and 60 Hz
* TI-99/4A, 50 Hz and 60 Hz
* TI-99/4QI, 50 Hz and 60 Hz
* TI-99/8
* Geneve 9640

A number of peripherals are also emulated, ranging from various disk controllers (up to HFDC), to serial interfaces, USB interface, IDE interface, HSGPL, and also SGCPU.

The emulator is freely downloadable from [http://www.mamedev.org/release.html mamedev.org] as a pre-built binary for Windows systems, and as a source zip archive for all platforms.

You can download and work on the MAME source codes, since all MAME components have been relicenced under an open-source licence (BSD or GPL). If you want to contribute, you should get in contact with the maintainers, though. A good location for that is the [http://forums.bannister.org/ubbthreads.php?ubb=postlist&Board=1&page=1 MESS message board].

I would be happy to see more people from the TI community helping to improve the TI emulation in MESS.

<div style="clear:both; margin-top:2em"></div>
<div style="float:left; padding:1em; height: 35em; width:45%; background-color:#ddddee">

==Installing and setup==

* [https://www.mizapf.de/en/ti99/mame/buildmame Building MAME] from source
* [https://www.mizapf.de/ti99/mame/winstmame Installing on Windows systems]
* [https://www.mizapf.de/en/ti99/mame/ Getting the ROMs]
* [[Setting up the HSGPL for MAME]]
* [[Setting up the Horizon Ramdisk]]

</div>

<div style="margin-left:50%; padding:1em; height: 35em;width:45%; background-color:#ddeedd">

==Using==

* [https://www.ninermame.org/info/scope Features of the TI and Geneve emulation in MAME]
* [[MAME TI emulation usage|Working with the TI/Geneve emulation]]
* [[Tools for MESS|Tools]]
* [[MESS and TI cartridges|Cartridges]]
* [[MESS media handling|Media handling]]
** [[MESS media handling#Using_your_TI_and_Geneve_hard_drive_in_MESS|Using your TI/Geneve hard drive in MESS]]
** [[MESS media handling#Formatting_disks|Formatting disks]]
** [[MESS media handling#Setting_up_a_blank_hard_disk|Setting up a blank hard disk]]
** [[MESS media handling#Upgrading_to_new_CHD_format|Upgrading CHD version]]
** [[MESS media handling#IDE disk handling|Using the IDE HD controller]]
* [[MESS debugger|Built-in debugger]]
* [https://www.mizapf.de/ti99/timt TIImageTool] - a GUI-based image manager
</div>

<div style="clear:both; height:1em"></div>

<div style="float:left; padding:1em; height: 30em;width:45%; background-color:#eedddd">

==Questions and Troubleshooting==

* Some help for [[MESS Troubleshooting]].
* [[MESSFAQ | Frequently Asked Questions]] related to the TI/Geneve emulation in MESS.
* [https://www.mizapf.de/en/ti99/mame Change MESS menu mode key] from Scroll Lock to another key
* Hassle with the [[MESS keyboard modes]]
</div>

<div style="padding:1em; margin-left:50%; height: 30em;width:45%; background-color:#ddeeee">

==Details==

* Basics: [[Emulation and Simulation]]
* [[Guided tour through MESS|Get a look under the hood of MESS]]
* The [[MESS cartridge handling|cartridge system]] of MESS
* Programmer's Guide to MESS
* [https://www.mizapf.de/ti99/mame/changes MAME version history] with features, fixes, and regressions list
* [https://www.ninermame.org/details/serialconn RS232 emulation]
* [[MAME Internals]]
* [[MAME Floppy sound emulation | Floppy sound emulation]]
</div>

<div style="clear:both; margin-bottom:2em"></div>

__NOTOC__

[[Category:Emulation]]
[[Category:MAME]]

MAME

2023-02-24T20:19:50Z

Mizapf: /* Details */

[[Image:mess_logo_n.png|150px|right]]
MESS (Multiple Emulator Super System) is a multi-system emulator which emulates more than 400 computer systems, many of them from the good old days of the Home Computers. Among them are also a number of TI platforms:

* TI-99/2 (24K and 32K ROM version)
* TI-99/4, 50 Hz and 60 Hz
* TI-99/4A, 50 Hz and 60 Hz
* TI-99/4QI, 50 Hz and 60 Hz
* TI-99/8
* Geneve 9640

A number of peripherals are also emulated, ranging from various disk controllers (up to HFDC), to serial interfaces, USB interface, IDE interface, HSGPL, and also SGCPU.

The emulator is freely downloadable from [http://www.mamedev.org/release.html mamedev.org] as a pre-built binary for Windows systems, and as a source zip archive for all platforms.

You can download and work on the MAME source codes, since all MAME components have been relicenced under an open-source licence (BSD or GPL). If you want to contribute, you should get in contact with the maintainers, though. A good location for that is the [http://forums.bannister.org/ubbthreads.php?ubb=postlist&Board=1&page=1 MESS message board].

I would be happy to see more people from the TI community helping to improve the TI emulation in MESS.

<div style="clear:both; margin-top:2em"></div>
<div style="float:left; padding:1em; height: 35em; width:45%; background-color:#ddddee">

==Installing and setup==

* [https://www.mizapf.de/en/ti99/mame/buildmame Building MAME] from source
* [https://www.mizapf.de/ti99/mame/winstmame Installing on Windows systems]
* [https://www.mizapf.de/en/ti99/mame/ Getting the ROMs]
* [[Setting up the HSGPL for MAME]]
* [[Setting up the Horizon Ramdisk]]

</div>

<div style="margin-left:50%; padding:1em; height: 35em;width:45%; background-color:#ddeedd">

==Using==

* [https://www.ninermame.org/info/scope Features of the TI and Geneve emulation in MAME]
* [[MAME TI emulation usage|Working with the TI/Geneve emulation]]
* [[Tools for MESS|Tools]]
* [[MESS and TI cartridges|Cartridges]]
* [[MESS media handling|Media handling]]
** [[MESS media handling#Using_your_TI_and_Geneve_hard_drive_in_MESS|Using your TI/Geneve hard drive in MESS]]
** [[MESS media handling#Formatting_disks|Formatting disks]]
** [[MESS media handling#Setting_up_a_blank_hard_disk|Setting up a blank hard disk]]
** [[MESS media handling#Upgrading_to_new_CHD_format|Upgrading CHD version]]
** [[MESS media handling#IDE disk handling|Using the IDE HD controller]]
* [[MESS debugger|Built-in debugger]]
* [https://www.mizapf.de/ti99/timt TIImageTool] - a GUI-based image manager
</div>

<div style="clear:both; height:1em"></div>

<div style="float:left; padding:1em; height: 30em;width:45%; background-color:#eedddd">

==Questions and Troubleshooting==

* Some help for [[MESS Troubleshooting]].
* [[MESSFAQ | Frequently Asked Questions]] related to the TI/Geneve emulation in MESS.
* [https://www.mizapf.de/en/ti99/mame Change MESS menu mode key] from Scroll Lock to another key
* Hassle with the [[MESS keyboard modes]]
</div>

<div style="padding:1em; margin-left:50%; height: 30em;width:45%; background-color:#ddeeee">

==Details==

* Basics: [[Emulation and Simulation]]
* [[Guided tour through MESS|Get a look under the hood of MESS]]
* The [[MESS cartridge handling|cartridge system]] of MESS
* Programmer's Guide to MESS
* [https://www.mizapf.de/ti99/mame/changes MAME version history] with features, fixes, and regressions list
* [[MESS issues and non-issues | MESS issues]]
* [https://www.ninermame.org/details/serialconn RS232 emulation]
* [[MAME Internals]]
* [[MAME Floppy sound emulation | Floppy sound emulation]]
</div>

<div style="clear:both; margin-bottom:2em"></div>

__NOTOC__

[[Category:Emulation]]
[[Category:MAME]]

MAME

2023-02-24T20:19:01Z

Mizapf: /* Using */

[[Image:mess_logo_n.png|150px|right]]
MESS (Multiple Emulator Super System) is a multi-system emulator which emulates more than 400 computer systems, many of them from the good old days of the Home Computers. Among them are also a number of TI platforms:

* TI-99/2 (24K and 32K ROM version)
* TI-99/4, 50 Hz and 60 Hz
* TI-99/4A, 50 Hz and 60 Hz
* TI-99/4QI, 50 Hz and 60 Hz
* TI-99/8
* Geneve 9640

A number of peripherals are also emulated, ranging from various disk controllers (up to HFDC), to serial interfaces, USB interface, IDE interface, HSGPL, and also SGCPU.

The emulator is freely downloadable from [http://www.mamedev.org/release.html mamedev.org] as a pre-built binary for Windows systems, and as a source zip archive for all platforms.

You can download and work on the MAME source codes, since all MAME components have been relicenced under an open-source licence (BSD or GPL). If you want to contribute, you should get in contact with the maintainers, though. A good location for that is the [http://forums.bannister.org/ubbthreads.php?ubb=postlist&Board=1&page=1 MESS message board].

I would be happy to see more people from the TI community helping to improve the TI emulation in MESS.

<div style="clear:both; margin-top:2em"></div>
<div style="float:left; padding:1em; height: 35em; width:45%; background-color:#ddddee">

==Installing and setup==

* [https://www.mizapf.de/en/ti99/mame/buildmame Building MAME] from source
* [https://www.mizapf.de/ti99/mame/winstmame Installing on Windows systems]
* [https://www.mizapf.de/en/ti99/mame/ Getting the ROMs]
* [[Setting up the HSGPL for MAME]]
* [[Setting up the Horizon Ramdisk]]

</div>

<div style="margin-left:50%; padding:1em; height: 35em;width:45%; background-color:#ddeedd">

==Using==

* [https://www.ninermame.org/info/scope Features of the TI and Geneve emulation in MAME]
* [[MAME TI emulation usage|Working with the TI/Geneve emulation]]
* [[Tools for MESS|Tools]]
* [[MESS and TI cartridges|Cartridges]]
* [[MESS media handling|Media handling]]
** [[MESS media handling#Using_your_TI_and_Geneve_hard_drive_in_MESS|Using your TI/Geneve hard drive in MESS]]
** [[MESS media handling#Formatting_disks|Formatting disks]]
** [[MESS media handling#Setting_up_a_blank_hard_disk|Setting up a blank hard disk]]
** [[MESS media handling#Upgrading_to_new_CHD_format|Upgrading CHD version]]
** [[MESS media handling#IDE disk handling|Using the IDE HD controller]]
* [[MESS debugger|Built-in debugger]]
* [https://www.mizapf.de/ti99/timt TIImageTool] - a GUI-based image manager
</div>

<div style="clear:both; height:1em"></div>

<div style="float:left; padding:1em; height: 30em;width:45%; background-color:#eedddd">

==Questions and Troubleshooting==

* Some help for [[MESS Troubleshooting]].
* [[MESSFAQ | Frequently Asked Questions]] related to the TI/Geneve emulation in MESS.
* [https://www.mizapf.de/en/ti99/mame Change MESS menu mode key] from Scroll Lock to another key
* Hassle with the [[MESS keyboard modes]]
</div>

<div style="padding:1em; margin-left:50%; height: 30em;width:45%; background-color:#ddeeee">

==Details==

* Basics: [[Emulation and Simulation]]
* [[Guided tour through MESS|Get a look under the hood of MESS]] <span style="font-weight:bold; color:red">NEW</span>
* The [[MESS cartridge handling|cartridge system]] of MESS
* Programmer's Guide to MESS
* [https://www.mizapf.de/ti99/mame/changes MAME version history] with features, fixes, and regressions list
* [[MESS issues and non-issues | MESS issues]]
* [https://www.ninermame.org/details/serialconn RS232 emulation]
* [[MAME Internals]]
* [[MAME Floppy sound emulation | Floppy sound emulation]]
</div>

<div style="clear:both; margin-bottom:2em"></div>

__NOTOC__

[[Category:Emulation]]
[[Category:MAME]]

MAME

2023-02-24T20:17:35Z

Mizapf: /* Installing and setup */

[[Image:mess_logo_n.png|150px|right]]
MESS (Multiple Emulator Super System) is a multi-system emulator which emulates more than 400 computer systems, many of them from the good old days of the Home Computers. Among them are also a number of TI platforms:

* TI-99/2 (24K and 32K ROM version)
* TI-99/4, 50 Hz and 60 Hz
* TI-99/4A, 50 Hz and 60 Hz
* TI-99/4QI, 50 Hz and 60 Hz
* TI-99/8
* Geneve 9640

A number of peripherals are also emulated, ranging from various disk controllers (up to HFDC), to serial interfaces, USB interface, IDE interface, HSGPL, and also SGCPU.

The emulator is freely downloadable from [http://www.mamedev.org/release.html mamedev.org] as a pre-built binary for Windows systems, and as a source zip archive for all platforms.

You can download and work on the MAME source codes, since all MAME components have been relicenced under an open-source licence (BSD or GPL). If you want to contribute, you should get in contact with the maintainers, though. A good location for that is the [http://forums.bannister.org/ubbthreads.php?ubb=postlist&Board=1&page=1 MESS message board].

I would be happy to see more people from the TI community helping to improve the TI emulation in MESS.

<div style="clear:both; margin-top:2em"></div>
<div style="float:left; padding:1em; height: 35em; width:45%; background-color:#ddddee">

==Installing and setup==

* [https://www.mizapf.de/en/ti99/mame/buildmame Building MAME] from source
* [https://www.mizapf.de/ti99/mame/winstmame Installing on Windows systems]
* [https://www.mizapf.de/en/ti99/mame/ Getting the ROMs]
* [[Setting up the HSGPL for MAME]]
* [[Setting up the Horizon Ramdisk]]

</div>

<div style="margin-left:50%; padding:1em; height: 35em;width:45%; background-color:#ddeedd">

==Using==

* [http://mess.redump.net/mess:howto The Official MESS User's Manual]
* [[General MESS features]]
* [[Features of the TI and Geneve emulation in MESS]]
* [[MAME TI emulation usage|Working with the TI/Geneve emulation]]
* [[Tools for MESS|Tools]]
* [[MESS and TI cartridges|Cartridges]]
* [[MESS media handling|Media handling]]
** [[MESS media handling#Using_your_TI_and_Geneve_hard_drive_in_MESS|Using your TI/Geneve hard drive in MESS]]
** [[MESS media handling#Formatting_disks|Formatting disks]]
** [[MESS media handling#Setting_up_a_blank_hard_disk|Setting up a blank hard disk]]
** [[MESS media handling#Upgrading_to_new_CHD_format|Upgrading CHD version]]
** [[MESS media handling#IDE disk handling|Using the IDE HD controller]]
* [[MESS debugger|Built-in debugger]]
* [https://www.mizapf.de/ti99/timt TIImageTool] - a GUI-based image manager
</div>

<div style="clear:both; height:1em"></div>

<div style="float:left; padding:1em; height: 30em;width:45%; background-color:#eedddd">

==Questions and Troubleshooting==

* Some help for [[MESS Troubleshooting]].
* [[MESSFAQ | Frequently Asked Questions]] related to the TI/Geneve emulation in MESS.
* [https://www.mizapf.de/en/ti99/mame Change MESS menu mode key] from Scroll Lock to another key
* Hassle with the [[MESS keyboard modes]]
</div>

<div style="padding:1em; margin-left:50%; height: 30em;width:45%; background-color:#ddeeee">

==Details==

* Basics: [[Emulation and Simulation]]
* [[Guided tour through MESS|Get a look under the hood of MESS]] <span style="font-weight:bold; color:red">NEW</span>
* The [[MESS cartridge handling|cartridge system]] of MESS
* Programmer's Guide to MESS
* [https://www.mizapf.de/ti99/mame/changes MAME version history] with features, fixes, and regressions list
* [[MESS issues and non-issues | MESS issues]]
* [https://www.ninermame.org/details/serialconn RS232 emulation]
* [[MAME Internals]]
* [[MAME Floppy sound emulation | Floppy sound emulation]]
</div>

<div style="clear:both; margin-bottom:2em"></div>

__NOTOC__

[[Category:Emulation]]
[[Category:MAME]]

Technical details

2023-02-24T20:10:36Z

Mizapf:

On this page I collect some findings that I have not yet put into specific categories (but which should be available nevertheless).

== Communication with devices ==

* Here is a commented log when [[SSSD Format Log|formatting a SSSD floppy disk]] with the TI disk controller. Actually, this dump was achieved using MESS and putting in some printf lines.

* [[Hard disk track layout]] when created with the HFDC

== Details about the chipset ==

* [[Programmable Systems Interface TMS 9901]]

== Determine rate register values for TMS9902 ==

The TMS9902 UART (serial interface) is used on various RS232 controller cards. The baud rate is not set by providing some integer number but by configuring a clock divider and multiplier. The baud rate cannot therefore be set precisely but only approximately.

The following illustration shows these approximations, the setting of the clock divider of and the multiplier, and the rate register values below the lines. The favorite values are printed in bold, and the corresponding hexadecimal rate register value is shown in blue below.

[[File:baudrates.png|600px]]

== TI-99/4A chipset and components ==

=== TMS9900 processor ===

Input/output operations are performed by the [[Communications Register Unit]].

'''TODO: Continue'''

=== Scratch Pad RAM ===
"Where is scratch pad RAM? - Scratch pad RAM is the ONLY area of RAM addressed with a 16 bit data line. It is FAST.

It can be found from >8300 to >83FE, and parts of it are used by the operating system. (Note: The symbol > means the number following is in hexadecimal format).

Different bits are used depending on how you are using the console! In case you thought EASY BUG was part of the Mini Memory module- yes, it is in the module, but it does not RUN from there- for greater speed it is transferred to the scratch pad area, where it resides from >8370 to >83FF

>8300 to >8348 IS USED BY BASIC (XB) and so seems to be a reasonable place to put a pure machine code utility.

>834A to >83FE seems to be fully utilised for most environments.

== Setting up RXTX for Java ==

RXTX is a serial and parallel port API implementation which is available for Windows, MacOS, and Unix systems, as binary and source code files. The complete documentation and the download location is at http://rxtx.qbang.org/wiki/index.php/Main_Page. You should build the binaries for 64 bit systems from the sources.

=== Instructions for Windows ===

Download the RXTX binaries package from http://rxtx.qbang.org/wiki/index.php/Download. Version 2.1-7 is OK. You now have to copy two files manually into the correct folders.

* Locate RXTXComm.jar in the ZIP file.
* Copy this file into your Java installation folder. This should be at '''C:\Program Files(x86)\Java\jre6''' (or a similar name; can't tell what version you have installed). Copy the file into the subfolder '''lib\ext'''. You may find some other JAR files there; in that case you are at the right location.
* Locate rxtxSerial.dll in the ZIP file.
* Copy this file into the subfolder '''bin''' of the Java installation folder as located above. You should find a lot of dll files there.

You should now be able to use RXTX with your Java applications.

=== Instructions for Linux ===

* Unzip the file
* Enter the source directory
* Do a
./configure
* Install missing libraries if errors are reported.
* Create and install
make
make install

The file ''RXTXcomm.jar'' should now be found in the ''lib/ext'' folder of your Java installation. The native libraries ''librxtxSerial.so'', ''librxtxParallel.so'' and more have been copied into the ''lib/i386'' or ''lib/amd64'' folders (32 bit or 64 bit build; Intel 64 bit also uses the amd64 folder).

At first you will likely get an error message during Java execution:
check_group_uucp(): error testing lock file creation Error details:Permission deniedcheck_lock_status:
No permission to create lock file.
please see: How can I use Lock Files with rxtx? in INSTALL

This message appears because you still have no permission to access the ports and to create a lock file. To fix this you must be member of the following groups:

* uucp
* lock (to be allowed to create lock files in /var/lock; you may have to change permissions for this directory as well!)
* dialout (to be allowed to use the serial interface)

Check /etc/group and add your user name behind all lines, or use your favorite system management tool. You must log out and log in again to make these changes effective. After this change, no such error message should be reported on the command line anymore.

=== Known Issues ===

''' 'UTS_RELEASE' undeclared (first use in this function)''': Using the version rxtx-2.1-7r2 with a recent openSUSE issues this message on configure, and building also fails. Obviously this symbol has been thrown out of the kernel sources, which is still present in the 2.1 rxtx release. I could solve this by [http://rxtx.qbang.org/wiki/index.php/Retrieving_Source_Code using the CVS version].

'''make install''': There is a bug in the configure script, resulting in trouble when using a Java 1.6 JDK or higher. You may get an error message
libtool: install: `x86_64-unknown-linux-gnu/librxtxRS485.la' is not a directory
In that case you need to manually add a version string into the configure script. Look for a sequence
1.1*|1.2*|1.3*|1.4*|1.5*
and add a |1.6* behind. This appears multiple times in the configure script; make sure you change it at least for your operating system.

'''Bug in rxtx-2.1-7r2 on 64 bit systems''': If your application immediately exits with a SIGSEGV, and you can see in the dump file that it happened while calling read(), and if your system is 64 bit (x86_64), you may have run into a (known) bug in RXTX (see [http://bugzilla.qbang.org/show_bug.cgi?id=171 Bugzilla, bug 171]). Please apply the patch mentioned in the comment on the linked page.

== Error codes from the disk controller card ==

These are the error codes from the PHP1240 Disk Controller Card (the original TI disk controller).

(moved, see [[Troubleshooting#Disk-related_issues]])

== Hardware discussions ==

=== Using ILA and SENILA ===
Todo

Super Sketch

2023-02-24T20:06:36Z

Mizapf: Mizapf moved page Super sketch to Super Sketch without leaving a redirect: No lowercase in title

SUPER SKETCH drawing tablet.

Super Sketch Sketch-Master Model G2400 from Personal Peripherals Inc 1984.

Medium: Cartridge plus tablet. Required: Console only. The tablet plugs into the module port and has all necessary software in the module.

When graphics tablets can easily cost over GBP 300, you don't expect too much for GBP 65... in fact SUPERSKETCH is a remarkable product at the price.

[[Image:SKETCH.JPG|250px|right]]

The most significant drawback is a feature of the VDP in our console- when in bit map mode (hi res graphics), each character on screen is divided into 8 rows of 8 pixels. For each row of 8 pixels, only two colours are permitted. When using SuperSketch, this can cause "bleeding" problems when you try to place three colours in a row. With great care you can reduce the visual effects of this but it is a significant drawback.

SUPERSKETCH uses a movable arm which can be used to trace a drawing, or merely used 'freeform'. A full palette of colours is available, and a good choice of 'brushes'. As drawing straight lines can be difficult, special facilities are provided to assist you. There is a "fill" command also, but if there is even a one pixel gap in the shape, the ink will run out and fill the screen!

Once created, pictures can be saved to cassette ONLY, not to disk, not to printer, although owners with 32k ram may be able to patch in a screen dump program of their own via an interrupt switch (console mod required).

Essentially a toy, Supersketch is a very interesting peripheral for the 99/4A, and seems strongly enough built to be used by the younger members of the family, who could find it to be a very expressive medium. A colour tv should be considered essential for this item! although it can be used with black and white.

[[Category:Expansion]]
[[Category:Module]]

MAME TI emulation usage

2023-02-24T20:02:20Z

Mizapf: /* Printing in MESS */

The following description addresses the usage of MAME starting from version 0.186.

== Slot devices ==

The TI emulation makes use of "slot devices". These are devices that offer a ''slot'' into which another component can be plugged.

=== Peripheral Box ===

The [[Peripheral Expansion Box]] is modelled as a collection of expansion card slots. It plugs into the "ioport" of the console, so unless you explicitly plug it in, you do not see any of its slots.

Check

mame64 ti99_4a -listslots

and

mame64 ti99_4a -ioport peb -listslots

Slot names must be specified on the command like with a leading "-". As you can see, the slots of the PEB are named "ioport:peb:slot2" to "ioport:peb:slot8".

Any device plugged into the PEB must be specified using the slot name. An example could look like this:

mame64 ti99_4a -cart editass -ioport peb -ioport:peb:slot2 32kmem -ioport:peb:slot3 speech -ioport:peb:slot6 tirs232 -ioport:peb:slot8 hfdc -flop1 mydisk.dsk

This may look pretty long, but you can hide this in a script (batch) file. Also, the frontends like QMC2 allow for a set of options to be defined for each start.

The slots are all equivalent, concerning the cards that may be plugged into them, but if you want to keep with the real box, you should plug the disk controller into slot 8, because there is a gap in the chassis to connect the drives in the compartment to the controller.

The [[Peripheral_Expansion_Box#Peripheral_Box_Slot_Concept|Flex Cable Interface]] traditionally goes into slot 1, even though each slot is connected in parallel with all lines. Accordingly, we leave that option away as well.

{| class="plainc"
! Slot parameter
! Value
! Device
|-
| rowspan="14" | -ioport:peb:slot2 ... -ioport:peb:slot8
| 32kmem
| TI-99 32KiB memory expansion card
|-
| myarcmem
| Myarc Memory expansion card MEXP-1
|-
| samsmem
| SuperAMS memory expansion card
|-
| horizon
| Horizon 4000 Ramdisk
|-
| pcode
| TI-99 P-Code Card
|-
| hsgpl
| SNUG High-speed GPL card
|-
| speech
| TI-99 Speech synthesizer (on adapter card)
|-
| tirs232
| TI-99 RS232/PIO interface
|-
| ide
| Nouspikel IDE interface card
|-
| usbsm
| Nouspikel USB/Smartmedia card
|-
| tirs232
| TI-99 RS232/PIO interface
|-
| bwg
| SNUG BwG Floppy Controller
|-
| tifdc
| TI-99 Standard DSSD Floppy Controller
|-
| hfdc
| Myarc Hard and Floppy Disk Controller
|-
|}

=== Joystick port ===

The joystick port is also realized as a slot device. This has the benefit that special logic can be put into the devices instead of being somewhat incorporated in the console. In particular, the handling of the Mechatronics Mouse, the joysticks, and the TI-99/4 handsets required some case processing.

Now the device can be specified as plugged into the "joyport":

mame64 ti99_4a -joyport twinjoy
mame64 ti99_4a -joyport mecmouse
mame64 ti99_4 -joyport handset

The "twinjoy" is the default setting, so you need not specify it explicitly.

=== Cartridge port ===

The cartridge port (also known as ''GROM port'') allows for plugging in three different devices:

* The single cartridge slot. This is not a real device; it just configures the cartridge slot to host a single cartridge. It is the default setting. The only cartridge option is "-cart".
* The multi-cartridge expander. It allows for up to four cartridges to be plugged in by using "-cart1" to "-cart4". When several cartridges are plugged in, the TI console offers a software selection using "REVIEW MODULE LIBRARY".
* The GRAM Kracker. It is a device from [[Miller's Graphics]] that is plugged into the cartridge port and offers another slot for a guest cartridge. You can then copy the cartridge contents into the GRAM Kracker with offers NVRAM to store them, and also to allow you to modify these contents.

The cartridge slots work with both RPK and ZIP cartridges.

So when using the TI-99/4, /4a, and /8 you can specify how the cartridge port looks like:

mame64 ti99_4a -gromport single -cart invaders
mame64 ti99_4a -gromport multi -cart1 exbasic -cart2 editor_assembler.rpk
mame64 ti99_4a -gromport gkracker -cart hunt_the_wumpus.rpk

In order to use the GRAM Kracker, you must have the ROM contents of the GRAM Kracker in a file called gkracker.bin, and this must be found in a ZIP file ti99_gkracker.zip located in the rompath.

You can create this zip file quite easily:

== Using serial connections ==

MAME does not offer a direct access to the PC serial interface (the UART). Instead, we can use a socket pipe which connects MESS with another application that provides the access. Details are explained on the [https://www.ninermame.org/details/serialconn serial emulation description].

One application that provides the necessary connection is [https://www.mizapf.de/ti99/timt TIImageTool], in particular its ''serial bridge'' feature.

Supposed that you have started TIImageTool and started the serial bridge on socket 10000 on the same computer where MAME is running, the connection is set up like this:

mame64 ti99_4a -ioport peb -ioport:peb:slot6 tirs232 -serl1 socket.localhost:10000

Using the parameter ''serl2'' you can connect to the emulated RS2332/2. Also, you can set the CRU address to 1500 which turns the ports into RS232/3 and 4. The CRU address can be set in the [[MAME DIP switch settings|DIP switch settings]].

== Printing in MESS ==

You can output plain text content to a "virtual" printer. In our case it is a text file that is written to, and you can then use your PC printing facilities to print that file on a real printer.

mame64 ti99_4a -ioport peb -ioport:peb:slot6 tirs232 -parl outfile.txt

Within TI BASIC, you can simply do a

LIST "PIO"

which sends the program lines in memory to the file named "outfile.txt" on your PC file system. Of course, any other TI application may also write to PIO in the same way. You can also try to output graphic content, but this will end up in a lot of uninterpreted binary values, specific for the printer you chose in the application. You will need to write a tool to convert these binary values to an appropriate image.

For the parallel output you '''do not need''' the [https://www.ninermame.org/details/serialconn serial bridge].

[[Category:MAME]]

MAME TI emulation usage

2023-02-24T20:01:27Z

Mizapf: /* Using serial connections */

The following description addresses the usage of MAME starting from version 0.186.

== Slot devices ==

The TI emulation makes use of "slot devices". These are devices that offer a ''slot'' into which another component can be plugged.

=== Peripheral Box ===

The [[Peripheral Expansion Box]] is modelled as a collection of expansion card slots. It plugs into the "ioport" of the console, so unless you explicitly plug it in, you do not see any of its slots.

Check

mame64 ti99_4a -listslots

and

mame64 ti99_4a -ioport peb -listslots

Slot names must be specified on the command like with a leading "-". As you can see, the slots of the PEB are named "ioport:peb:slot2" to "ioport:peb:slot8".

Any device plugged into the PEB must be specified using the slot name. An example could look like this:

mame64 ti99_4a -cart editass -ioport peb -ioport:peb:slot2 32kmem -ioport:peb:slot3 speech -ioport:peb:slot6 tirs232 -ioport:peb:slot8 hfdc -flop1 mydisk.dsk

This may look pretty long, but you can hide this in a script (batch) file. Also, the frontends like QMC2 allow for a set of options to be defined for each start.

The slots are all equivalent, concerning the cards that may be plugged into them, but if you want to keep with the real box, you should plug the disk controller into slot 8, because there is a gap in the chassis to connect the drives in the compartment to the controller.

The [[Peripheral_Expansion_Box#Peripheral_Box_Slot_Concept|Flex Cable Interface]] traditionally goes into slot 1, even though each slot is connected in parallel with all lines. Accordingly, we leave that option away as well.

{| class="plainc"
! Slot parameter
! Value
! Device
|-
| rowspan="14" | -ioport:peb:slot2 ... -ioport:peb:slot8
| 32kmem
| TI-99 32KiB memory expansion card
|-
| myarcmem
| Myarc Memory expansion card MEXP-1
|-
| samsmem
| SuperAMS memory expansion card
|-
| horizon
| Horizon 4000 Ramdisk
|-
| pcode
| TI-99 P-Code Card
|-
| hsgpl
| SNUG High-speed GPL card
|-
| speech
| TI-99 Speech synthesizer (on adapter card)
|-
| tirs232
| TI-99 RS232/PIO interface
|-
| ide
| Nouspikel IDE interface card
|-
| usbsm
| Nouspikel USB/Smartmedia card
|-
| tirs232
| TI-99 RS232/PIO interface
|-
| bwg
| SNUG BwG Floppy Controller
|-
| tifdc
| TI-99 Standard DSSD Floppy Controller
|-
| hfdc
| Myarc Hard and Floppy Disk Controller
|-
|}

=== Joystick port ===

The joystick port is also realized as a slot device. This has the benefit that special logic can be put into the devices instead of being somewhat incorporated in the console. In particular, the handling of the Mechatronics Mouse, the joysticks, and the TI-99/4 handsets required some case processing.

Now the device can be specified as plugged into the "joyport":

mame64 ti99_4a -joyport twinjoy
mame64 ti99_4a -joyport mecmouse
mame64 ti99_4 -joyport handset

The "twinjoy" is the default setting, so you need not specify it explicitly.

=== Cartridge port ===

The cartridge port (also known as ''GROM port'') allows for plugging in three different devices:

* The single cartridge slot. This is not a real device; it just configures the cartridge slot to host a single cartridge. It is the default setting. The only cartridge option is "-cart".
* The multi-cartridge expander. It allows for up to four cartridges to be plugged in by using "-cart1" to "-cart4". When several cartridges are plugged in, the TI console offers a software selection using "REVIEW MODULE LIBRARY".
* The GRAM Kracker. It is a device from [[Miller's Graphics]] that is plugged into the cartridge port and offers another slot for a guest cartridge. You can then copy the cartridge contents into the GRAM Kracker with offers NVRAM to store them, and also to allow you to modify these contents.

The cartridge slots work with both RPK and ZIP cartridges.

So when using the TI-99/4, /4a, and /8 you can specify how the cartridge port looks like:

mame64 ti99_4a -gromport single -cart invaders
mame64 ti99_4a -gromport multi -cart1 exbasic -cart2 editor_assembler.rpk
mame64 ti99_4a -gromport gkracker -cart hunt_the_wumpus.rpk

In order to use the GRAM Kracker, you must have the ROM contents of the GRAM Kracker in a file called gkracker.bin, and this must be found in a ZIP file ti99_gkracker.zip located in the rompath.

You can create this zip file quite easily:

== Using serial connections ==

MAME does not offer a direct access to the PC serial interface (the UART). Instead, we can use a socket pipe which connects MESS with another application that provides the access. Details are explained on the [https://www.ninermame.org/details/serialconn serial emulation description].

One application that provides the necessary connection is [https://www.mizapf.de/ti99/timt TIImageTool], in particular its ''serial bridge'' feature.

Supposed that you have started TIImageTool and started the serial bridge on socket 10000 on the same computer where MAME is running, the connection is set up like this:

mame64 ti99_4a -ioport peb -ioport:peb:slot6 tirs232 -serl1 socket.localhost:10000

Using the parameter ''serl2'' you can connect to the emulated RS2332/2. Also, you can set the CRU address to 1500 which turns the ports into RS232/3 and 4. The CRU address can be set in the [[MAME DIP switch settings|DIP switch settings]].

== Printing in MESS ==

You can output plain text content to a "virtual" printer. In our case it is a text file that is written to, and you can then use your PC printing facilities to print that file on a real printer.

mame64 ti99_4a -ioport peb -ioport:peb:slot6 tirs232 -parl outfile.txt

Within TI BASIC, you can simply do a

LIST "PIO"

which sends the program lines in memory to the file named "outfile.txt" on your PC file system. Of course, any other TI application may also write to PIO in the same way. You can also try to output graphic content, but this will end up in a lot of uninterpreted binary values, specific for the printer you chose in the application. You will need to write a tool to convert these binary values to an appropriate image.

For the parallel output you '''do not need''' the [[MESS Serial connection|serial bridge]].

[[Category:MAME]]

MAME

2023-02-24T19:59:39Z

Mizapf: /* Details */

[[Image:mess_logo_n.png|150px|right]]
MESS (Multiple Emulator Super System) is a multi-system emulator which emulates more than 400 computer systems, many of them from the good old days of the Home Computers. Among them are also a number of TI platforms:

* TI-99/2 (24K and 32K ROM version)
* TI-99/4, 50 Hz and 60 Hz
* TI-99/4A, 50 Hz and 60 Hz
* TI-99/4QI, 50 Hz and 60 Hz
* TI-99/8
* Geneve 9640

A number of peripherals are also emulated, ranging from various disk controllers (up to HFDC), to serial interfaces, USB interface, IDE interface, HSGPL, and also SGCPU.

The emulator is freely downloadable from [http://www.mamedev.org/release.html mamedev.org] as a pre-built binary for Windows systems, and as a source zip archive for all platforms.

You can download and work on the MAME source codes, since all MAME components have been relicenced under an open-source licence (BSD or GPL). If you want to contribute, you should get in contact with the maintainers, though. A good location for that is the [http://forums.bannister.org/ubbthreads.php?ubb=postlist&Board=1&page=1 MESS message board].

I would be happy to see more people from the TI community helping to improve the TI emulation in MESS.

<div style="clear:both; margin-top:2em"></div>
<div style="float:left; padding:1em; height: 35em; width:45%; background-color:#ddddee">

==Installing and setup==

* [https://www.mizapf.de/en/ti99/mame/buildmame Building MAME] from source
* [https://www.mizapf.de/ti99/mame/winstmame Installing on Windows systems]
* [[Installing MAME on Linux|Installing on Linux systems]]
* [https://www.mizapf.de/en/ti99/mame/ Getting the ROMs]
* [[Setting up the HSGPL for MAME]]
* [[Setting up the Horizon Ramdisk]]

</div>

<div style="margin-left:50%; padding:1em; height: 35em;width:45%; background-color:#ddeedd">

==Using==

* [http://mess.redump.net/mess:howto The Official MESS User's Manual]
* [[General MESS features]]
* [[Features of the TI and Geneve emulation in MESS]]
* [[MAME TI emulation usage|Working with the TI/Geneve emulation]]
* [[Tools for MESS|Tools]]
* [[MESS and TI cartridges|Cartridges]]
* [[MESS media handling|Media handling]]
** [[MESS media handling#Using_your_TI_and_Geneve_hard_drive_in_MESS|Using your TI/Geneve hard drive in MESS]]
** [[MESS media handling#Formatting_disks|Formatting disks]]
** [[MESS media handling#Setting_up_a_blank_hard_disk|Setting up a blank hard disk]]
** [[MESS media handling#Upgrading_to_new_CHD_format|Upgrading CHD version]]
** [[MESS media handling#IDE disk handling|Using the IDE HD controller]]
* [[MESS debugger|Built-in debugger]]
* [https://www.mizapf.de/ti99/timt TIImageTool] - a GUI-based image manager
</div>

<div style="clear:both; height:1em"></div>

<div style="float:left; padding:1em; height: 30em;width:45%; background-color:#eedddd">

==Questions and Troubleshooting==

* Some help for [[MESS Troubleshooting]].
* [[MESSFAQ | Frequently Asked Questions]] related to the TI/Geneve emulation in MESS.
* [https://www.mizapf.de/en/ti99/mame Change MESS menu mode key] from Scroll Lock to another key
* Hassle with the [[MESS keyboard modes]]
</div>

<div style="padding:1em; margin-left:50%; height: 30em;width:45%; background-color:#ddeeee">

==Details==

* Basics: [[Emulation and Simulation]]
* [[Guided tour through MESS|Get a look under the hood of MESS]] <span style="font-weight:bold; color:red">NEW</span>
* The [[MESS cartridge handling|cartridge system]] of MESS
* Programmer's Guide to MESS
* [https://www.mizapf.de/ti99/mame/changes MAME version history] with features, fixes, and regressions list
* [[MESS issues and non-issues | MESS issues]]
* [https://www.ninermame.org/details/serialconn RS232 emulation]
* [[MAME Internals]]
* [[MAME Floppy sound emulation | Floppy sound emulation]]
</div>

<div style="clear:both; margin-bottom:2em"></div>

__NOTOC__

[[Category:Emulation]]
[[Category:MAME]]

MAME

2023-02-24T19:58:34Z

Mizapf:

[[Image:mess_logo_n.png|150px|right]]
MESS (Multiple Emulator Super System) is a multi-system emulator which emulates more than 400 computer systems, many of them from the good old days of the Home Computers. Among them are also a number of TI platforms:

* TI-99/2 (24K and 32K ROM version)
* TI-99/4, 50 Hz and 60 Hz
* TI-99/4A, 50 Hz and 60 Hz
* TI-99/4QI, 50 Hz and 60 Hz
* TI-99/8
* Geneve 9640

A number of peripherals are also emulated, ranging from various disk controllers (up to HFDC), to serial interfaces, USB interface, IDE interface, HSGPL, and also SGCPU.

The emulator is freely downloadable from [http://www.mamedev.org/release.html mamedev.org] as a pre-built binary for Windows systems, and as a source zip archive for all platforms.

You can download and work on the MAME source codes, since all MAME components have been relicenced under an open-source licence (BSD or GPL). If you want to contribute, you should get in contact with the maintainers, though. A good location for that is the [http://forums.bannister.org/ubbthreads.php?ubb=postlist&Board=1&page=1 MESS message board].

I would be happy to see more people from the TI community helping to improve the TI emulation in MESS.

<div style="clear:both; margin-top:2em"></div>
<div style="float:left; padding:1em; height: 35em; width:45%; background-color:#ddddee">

==Installing and setup==

* [https://www.mizapf.de/en/ti99/mame/buildmame Building MAME] from source
* [https://www.mizapf.de/ti99/mame/winstmame Installing on Windows systems]
* [[Installing MAME on Linux|Installing on Linux systems]]
* [https://www.mizapf.de/en/ti99/mame/ Getting the ROMs]
* [[Setting up the HSGPL for MAME]]
* [[Setting up the Horizon Ramdisk]]

</div>

<div style="margin-left:50%; padding:1em; height: 35em;width:45%; background-color:#ddeedd">

==Using==

* [http://mess.redump.net/mess:howto The Official MESS User's Manual]
* [[General MESS features]]
* [[Features of the TI and Geneve emulation in MESS]]
* [[MAME TI emulation usage|Working with the TI/Geneve emulation]]
* [[Tools for MESS|Tools]]
* [[MESS and TI cartridges|Cartridges]]
* [[MESS media handling|Media handling]]
** [[MESS media handling#Using_your_TI_and_Geneve_hard_drive_in_MESS|Using your TI/Geneve hard drive in MESS]]
** [[MESS media handling#Formatting_disks|Formatting disks]]
** [[MESS media handling#Setting_up_a_blank_hard_disk|Setting up a blank hard disk]]
** [[MESS media handling#Upgrading_to_new_CHD_format|Upgrading CHD version]]
** [[MESS media handling#IDE disk handling|Using the IDE HD controller]]
* [[MESS debugger|Built-in debugger]]
* [https://www.mizapf.de/ti99/timt TIImageTool] - a GUI-based image manager
</div>

<div style="clear:both; height:1em"></div>

<div style="float:left; padding:1em; height: 30em;width:45%; background-color:#eedddd">

==Questions and Troubleshooting==

* Some help for [[MESS Troubleshooting]].
* [[MESSFAQ | Frequently Asked Questions]] related to the TI/Geneve emulation in MESS.
* [https://www.mizapf.de/en/ti99/mame Change MESS menu mode key] from Scroll Lock to another key
* Hassle with the [[MESS keyboard modes]]
</div>

<div style="padding:1em; margin-left:50%; height: 30em;width:45%; background-color:#ddeeee">

==Details==

* Basics: [[Emulation and Simulation]]
* [[Guided tour through MESS|Get a look under the hood of MESS]] <span style="font-weight:bold; color:red">NEW</span>
* The [[MESS cartridge handling|cartridge system]] of MESS
* Programmer's Guide to MESS
* [https://www.mizapf.de/ti99/mame/changes MAME version history] with features, fixes, and regressions list
* [[MESS issues and non-issues | MESS issues]]
* [https://www.ninermame.org/details/serialconn RS232 emulation]
* [[MESS Work in progress]]
* [[MAME Internals]]
* [[MAME Floppy sound emulation | Floppy sound emulation]]
</div>

<div style="clear:both; margin-bottom:2em"></div>

__NOTOC__

[[Category:Emulation]]
[[Category:MAME]]

Main Page

2022-09-18T19:01:32Z

Mizapf:

<div style="font-size:1.5em;">Welcome to Ninerpedia!</div>

The Wiki for [[TI-99/4A]], [[TI-99/8]], [[Geneve 9640]], and all related hardware and software

[[File:Ti994a_console.jpg|250px|link=TI-99/4A]]<span style="margin-left:2em"> </span>
[[File:99 8 Console.JPG|200px|link=TI-99/8]]<span style="margin-left:3em"> </span>
[[File:Geneve_expansion_card.jpg|200px|link=Geneve 9640]]

On these pages, we try to collect valuable information for one of the greatest home computers and its extensions. You will find information on

<div style="display:inline-block; margin-right: 10em">
* [[Community]] Links
* [[Protocols]] and [[Formats]] Specifications
* [[Interfacing with the outside world]]
* [[File systems]]
* [[Specifications]]
* [[Hardware]]
* [[Troubleshooting]]
* [[Media]]
* [[Software]]
* [[Technical details|Technical bits and pieces]]
</div>
<div style="display:inline-block">
* [[Terminology]] (Glossary)
* [[Frequently Asked Questions]] (FAQ)
* [[Development resources]]
* [[Programming]]
* [[Using the system]]
* [[Recent developments]]
* [[Hardware projects]]
* [[Emulators]]
* [[News]]
* '''New:''' [[Challenges]]
</div>

<div style="clear:both; padding:1em; margin:3em 1em 1em 1em; background-color:#ccecff">The '''[[MAME | MAME TI-99 emulation]] pages''' give you a lot of information, tips, and hints for running the current version of the [http://mamedev.org/ MAME emulator]. The MAME pages are currently moved to a new site; you will find an overview on [https://www.mizapf.de/ti99/mame/changes TI-related changes] there. There is also some more information on the utility program [https://www.mizapf.de/ti99/timt TIImageTool].</div>

Find more TI-related information on [http://www.99er.net/ 99er.net].

[[Category:Main]]

GeneveOS XOP Definitions

2022-04-30T16:27:50Z

Mizapf:

GeneveOS makes frequent use of XOPs and offers them for user programs. An XOP (extended operation) is a special command of the TMS processor family which causes a [[Terminology#C|context switch]], transferring control to a location that is specified in a table.

Compared to common architecture concepts, the XOP is TI's way of implementing a '''system call'''.

The XOP instruction takes two arguments; the first delivers data for the call, the second is a number from 0 to 15 and indicates the '''XOP number'''. In GeneveOS, all system calls are XOP 0 with specific arguments:

ARGUM DATA <number>
...
XOP @ARGUM,0
...

=== Overview ===

{| class="plainc"
! XOP argument
! Category
|-
| 5 || [[Geneve keyboard control | Keyboard ]]
|-
| 6 || [[GeneveOS Video Interface | Video display ]]
|-
| 7 || [[GeneveOS Memory Management Functions | Memory Management ]]
|-
| 8 || [[GeneveOS Device Operation | Devices (Files) ]]
|-
| 9 || [[GeneveOS Utility Functions | Utility functions]]
|-
| 10 || Mathematical functions
|}

=== Used workspaces ===

The XOPs use workspaces F0C0 and F0A0.

[[Category:MDOS]]
[[Category:Geneve]]
[[Category:Programming]]

GeneveOS Device Operation

2022-04-24T19:43:05Z

Mizapf: /* BWRITE */

Accessing devices (floppy disk, hard disk, serial connector, printer) is possible in GeneveOS via XOP calls.

== User-task XOPs ==

User-task XOPs are available for use in application programs. Here is a typical example:

PABADD EQU >F180
FILE DATA 8
...
LI R0,PABADD
XOP @FILE,0
MOVB @PABADD+2,R0
JNE ERROR
...

Similar as with the TI-99/4A device service routine concept (DSR), a Peripheral Access Block (PAB) must be set up prior to invoking the XOP.

=== Device Service Routine Call ===

{| class="xoparg"
|-
|
! Input !! Output
|-
| R0
| Pointer to PAB || -
|-
|}

The actual operation is contained in the Peripheral Access Block (PAB).

=== Peripheral Access Block ===

While the TI-99/4A DSRs expect the PAB to be stored in VDP RAM, the Geneve OS DSRs use CPU RAM for the PAB, which means the PAB need not be copied to the video RAM before use. Also, you can choose to have the I/O buffers in VDP or CPU RAM.

The general layout of the PAB is as follows:

{| class="plainc" style="margin-left:1%"
|-
! width="5%" | 00
! width="5%" | 01
! width="5%" | 02
! width="5%" | 03
! width="5%" | 04
! width="5%" | 05
! width="5%" | 06
! width="5%" | 07
! width="5%" | 08
! width="5%" | 09
! width="5%" | 0A
! width="5%" | 0B
! width="5%" | 0C
! width="5%" | 0D
! width="5%" | 0E
! width="5%" | 0F
! width="5%" | 10 ...
|-
| Opcode
| Mode
| Error code
| colspan="3" | Buffer address
| colspan="2" | Record number
| colspan="2" | Record length
| Memory type
| colspan="3" | Character count
| Status byte
| Name length
| Name
|-
|}

Note that the buffer addresses are 21-bit wide, represented by the [[MDOS Memory Management Functions#Local_.28virtual.29_pages | virtual address]] within the calling task. The address for this buffer should be derived from [[MDOS Memory Management Functions | memory allocation]] operations that were invoked earlier.

After the operation, the PAB contains information about the results of the operation.

=== Mode ===

The mode bits are used to determine the operation direction (in/out/update/append), the encoding (display/internal), the structure (fixed/variable) and the access (sequential/relative).

{| class="plainbits" style="width:64%"
! 0
! 1
! 2
! 3
! 4
! 5
! 6
! 7
|-
| style="width:24%" rowspan="4" colspan="3" | Unused (000)
| style="width:8%" rowspan="2" | Fixed=0
| style="width:8%" rowspan="2" | Display=0
| style="width:16%" colspan="2" | Update=00
| style="width:8%" rowspan="2" | Sequential=0
|-
| colspan="2" | Output=01
|-
| rowspan="2" | Variable=1
| rowspan="2" | Internal=1
| colspan="2" | Input=10
| rowspan="2" | Relative=1
|-
| colspan="2" | Append=11
|}

=== Error code ===

The error code is an eight bit word with the following structure:

{| class="plainbits" style="float:left"
! 0
! 1
! 2
! 3
! 4
! 5
! 6
! 7
|-
| colspan="3" | Number
| colspan="5" | Detail code for error 7
|}

{| class="plainc" style="float:left"
! Number
! Meaning
|-
| 0
| No such device
|-
| 1
| Write-protected
|-
| 2
| Illegal open attribute
|-
| 3
| Illegal operation
|-
| 4
| Out of buffer space
|-
| 5
| Read beyond EOF
|-
| 6
| Device error
|-
| 7
| File error
|}

<div style="clear:both"></div>

== Operations ==

=== OPEN ===

Open a record-oriented file. A file must be opened before it can be read from or written to. This operation is not required for flat memory image files.

The PAB must be set up prior to invoking the operation:

'''IN'''

{| class="plainc" style="margin-left:1%"
|-
! width="4%" | 00
! width="4%" | 01
! width="4%" | 02
! width="4%" | 03
! width="4%" | 04
! width="4%" | 05
! width="4%" | 06
! width="4%" | 07
! width="4%" | 08
! width="4%" | 09
! width="4%" | 0A
! width="4%" | 0B
! width="4%" | 0C
! width="4%" | 0D
! width="4%" | 0E
! width="4%" | 0F
! width="4%" | 10 ...
|-
| '''00'''
| Mode
| -
| colspan="3" | -
| colspan="2" | Records to reserve
| colspan="2" | Record length
| -
| colspan="3" | -
| -
| Name length
| Name
|-
|}

'''Open new file''': The '''Record Length''' must be set to a value greater than 0. This will become the length of the records of the new file.

'''Open existing file''': The '''Record Length''' must match the length of the records. If the length is unknown, 0 may be passed.

After the OPEN operation has completed, the PAB delivers information about the result:

'''OUT'''

{| class="plainc" style="margin-left:1%"
|-
! width="4%" | 00
! width="4%" | 01
! width="4%" | 02
! width="4%" | 03
! width="4%" | 04
! width="4%" | 05
! width="4%" | 06
! width="4%" | 07
! width="4%" | 08
! width="4%" | 09
! width="4%" | 0A
! width="4%" | 0B
! width="4%" | 0C
! width="4%" | 0D
! width="4%" | 0E
! width="4%" | 0F
! width="4%" | 10 ...
|-
| -
| -
| Error code
| colspan="3" | -
| colspan="2" | -
| colspan="2" | Actual Record Length
| -
| 0
| colspan="2" | True Record Length
| -
| Name length
| Name
|-
|}

The '''Actual Record Length''' is the length of the records of the existing file. When 0 was passed on the call, this delivers the record length of the file; otherwise this is the value that was passed for the call. The '''True Record Length''' is the record length of the file when it already exists.

<div style="margin-bottom:6em"></div>

=== CLOSE ===

Closes a record-oriented file. A file must be closed after being used. After closing, no further read or write operations may be invoked on the file. This operation is not required for flat memory image files.

The PAB must be set up prior to invoking the operation:

'''IN'''

{| class="plainc" style="margin-left:1%"
|-
! width="4%" | 00
! width="4%" | 01
! width="4%" | 02
! width="4%" | 03
! width="4%" | 04
! width="4%" | 05
! width="4%" | 06
! width="4%" | 07
! width="4%" | 08
! width="4%" | 09
! width="4%" | 0A
! width="4%" | 0B
! width="4%" | 0C
! width="4%" | 0D
! width="4%" | 0E
! width="4%" | 0F
! width="4%" | 10 ...
|-
| '''01'''
| Mode
| -
| colspan="3" | -
| colspan="2" | -
| colspan="2" | -
| -
| colspan="3" | -
| -
| Name length
| Name
|-
|}

After the CLOSE operation has completed, the PAB delivers information about the result:

'''OUT'''

{| class="plainc" style="margin-left:1%"
|-
! width="4%" | 00
! width="4%" | 01
! width="4%" | 02
! width="4%" | 03
! width="4%" | 04
! width="4%" | 05
! width="4%" | 06
! width="4%" | 07
! width="4%" | 08
! width="4%" | 09
! width="4%" | 0A
! width="4%" | 0B
! width="4%" | 0C
! width="4%" | 0D
! width="4%" | 0E
! width="4%" | 0F
! width="4%" | 10 ...
|-
| -
| -
| Error code
| colspan="3" | -
| colspan="2" | -
| colspan="2" | -
| -
| colspan="3" | -
| -
| Name length
| Name
|-
|}

<div style="margin-bottom:6em"></div>

=== READ ===

Reads a record from a record-oriented file. For flat memory image files, [[#LOAD | LOAD]] must be used.

'''IN'''

{| class="plainc" style="margin-left:1%"
|-
! width="4%" | 00
! width="4%" | 01
! width="4%" | 02
! width="4%" | 03
! width="4%" | 04
! width="4%" | 05
! width="4%" | 06
! width="4%" | 07
! width="4%" | 08
! width="4%" | 09
! width="4%" | 0A
! width="4%" | 0B
! width="4%" | 0C
! width="4%" | 0D
! width="4%" | 0E
! width="4%" | 0F
! width="4%" | 10 ...
|-
| '''02'''
| Mode
| -
| colspan="3" | Buffer address
| colspan="2" | Record number
| colspan="2" | Record length
| Memory
| colspan="3" | -
| -
| Name length
| Name
|-
|}

Use the '''Record number''' field to specify the desired record in '''fixed record length''' files. This is not available for variable length record files.

The '''Record Length''' must match the length of the records as specified by [[#OPEN | OPEN]].

The '''Memory''' flag determines whether the data are read into CPU (0) or VDP (not 0) memory.

After the READ operation has completed, the PAB delivers information about the result:

'''OUT'''

{| class="plainc" style="margin-left:1%"
|-
! width="4%" | 00
! width="4%" | 01
! width="4%" | 02
! width="4%" | 03
! width="4%" | 04
! width="4%" | 05
! width="4%" | 06
! width="4%" | 07
! width="4%" | 08
! width="4%" | 09
! width="4%" | 0A
! width="4%" | 0B
! width="4%" | 0C
! width="4%" | 0D
! width="4%" | 0E
! width="4%" | 0F
! width="4%" | 10 ...
|-
| -
| -
| Error code
| colspan="3" | -
| colspan="2" | Next record number
| colspan="2" | -
| -
| colspan="3" | Number of read bytes
| -
| Name length
| Name
|}

'''Next record number''' applies for fixed record length files only.

<div style="margin-bottom:6em"></div>

=== WRITE ===

Writes a record to a record-oriented file. For flat memory image files, [[#SAVE | SAVE]] must be used.

'''IN'''

{| class="plainc" style="margin-left:1%"
|-
! width="4%" | 00
! width="4%" | 01
! width="4%" | 02
! width="4%" | 03
! width="4%" | 04
! width="4%" | 05
! width="4%" | 06
! width="4%" | 07
! width="4%" | 08
! width="4%" | 09
! width="4%" | 0A
! width="4%" | 0B
! width="4%" | 0C
! width="4%" | 0D
! width="4%" | 0E
! width="4%" | 0F
! width="4%" | 10 ...
|-
| '''03'''
| Mode
| -
| colspan="3" | Buffer address
| colspan="2" | Record number
| colspan="2" | Record length
| Memory
| colspan="3" | Number of bytes to write
| -
| Name length
| Name
|-
|}

Use the '''Record number''' field to specify the desired record in '''fixed record length''' files. This is not available for variable length record files.

The '''Record Length''' must match the length of the records as specified by [[#OPEN | OPEN]].

The '''Memory''' flag determines whether the data written from CPU (0) or VDP (not 0) memory.

After the WRITE operation has completed, the PAB delivers information about the result:

'''OUT'''

{| class="plainc" style="margin-left:1%"
|-
! width="4%" | 00
! width="4%" | 01
! width="4%" | 02
! width="4%" | 03
! width="4%" | 04
! width="4%" | 05
! width="4%" | 06
! width="4%" | 07
! width="4%" | 08
! width="4%" | 09
! width="4%" | 0A
! width="4%" | 0B
! width="4%" | 0C
! width="4%" | 0D
! width="4%" | 0E
! width="4%" | 0F
! width="4%" | 10 ...
|-
| -
| -
| Error code
| colspan="3" | -
| colspan="2" | Next record number
| colspan="2" | -
| -
| colspan="3" | Number of read bytes
| -
| Name length
| Name
|}

'''Next record number''' applies for fixed record length files only.

<div style="margin-bottom:6em"></div>

=== RESTORE ===

<div style="margin-bottom:6em"></div>

=== LOAD ===

<div style="margin-bottom:6em"></div>

=== SAVE ===

<div style="margin-bottom:6em"></div>

=== DELETE ===

<div style="margin-bottom:6em"></div>

=== SCRATCH ===

<div style="margin-bottom:6em"></div>

=== STATUS ===

<div style="margin-bottom:6em"></div>

=== BREAD ===

Reads a sector from a file or from a device. This is a level-2 operation, that is, it accesses the device based on sector addressing (or sectors of a file). BREAD allows for two operations:

* Read sectors from a file.
* Read sectors from a device.

'''IN'''

{| class="plainc" style="margin-left:1%"
|-
! width="4%" | 00
! width="4%" | 01
! width="4%" | 02
! width="4%" | 03
! width="4%" | 04
! width="4%" | 05
! width="4%" | 06
! width="4%" | 07
! width="4%" | 08
! width="4%" | 09
! width="4%" | 0A
! width="4%" | 0B
! width="4%" | 0C
! width="4%" | 0D
! width="4%" | 0E
! width="4%" | 0F
! width="4%" | 10 ...
|-
| '''0A'''
| -
| -
| colspan="3" | Buffer address
| colspan="2" | Sector offset LSW
| colspan="2" | -
| CPU / VDP
| -
| colspan="2" | Number of sectors
| Sector offset MSB
| Name length
| Name
|-
|}

The sector offset is defined by byte 0E as the most significant byte (value*65536) plus the word in bytes 06 and 07.

Byte 0A specifies whether the buffer address belongs to the CPU (0) or the VDP (non-zero) address space.

* CPU buffer address: ...p pppp.pppx xxxx.xxxx xxxx. The first three bits are ignored; the next 8 bits specify the page number in the user task, and the remaining 13 bits provide the offset in the page.
* VDP buffer address: .... ...x.xxxx xxxx.xxxx xxxx. The last 17 bits indicate the 128K video address.

'''Read from file''': When a file is addressed, the operation reads a sequence of sectors from the file. The '''Sector offset''' is the number of the first sector of the file, counting from 0. The physical locations of the sectors are subject to the sector allocation on the device.

'''Read from device''': When a device is addressed, the operation reads a sequence of sectors from the device. The '''Sector offset''' is the physical sector number.

After the BREAD operation has completed, the PAB delivers information about the result:

'''OUT'''

{| class="plainc" style="margin-left:1%"
|-
! width="4%" | 00
! width="4%" | 01
! width="4%" | 02
! width="4%" | 03
! width="4%" | 04
! width="4%" | 05
! width="4%" | 06
! width="4%" | 07
! width="4%" | 08
! width="4%" | 09
! width="4%" | 0A
! width="4%" | 0B
! width="4%" | 0C
! width="4%" | 0D
! width="4%" | 0E
! width="4%" | 0F
! width="4%" | 10 ...
|-
| -
| -
| Error code
| colspan="3" | Updated buffer address
| colspan="2" | Updated sector offset LSW
| colspan="2" | -
| -
| -
| colspan="2" | Remaining sectors
| Updated sector offset MSB
| -
| -
|-
|}

'''Error codes'''

* '''60''': Bad operation; happens when the device is not a block device.
* '''A0''': Read beyond end of file or device.
* '''C0''': Media error. The system was unable to read the sector although it should be readable.
* '''E0''': General error; happens when the device does not contain the specified file.

The '''Updated buffer address''' points to the memory address after the sectors were read (e.g. when 4 sectors are read, the pointer is increased by 4*256 = 1024).

The '''Updated sector offset''' is the first sector that has not been read due to an error condition.

The '''Remaining sectors''' is the number of unread sectors due to an error condition.

=== BWRITE ===

Writes a sector to a file or to a device. This is a level-2 operation, that is, it accesses the device based on sector addressing (or sectors of a file). BWRITE allows for three operations:

* Create a new, empty file.
* Write sectors to a file.
* Write sectors to a device.

'''IN'''

{| class="plainc" style="margin-left:1%"
|-
! width="4%" | 00
! width="4%" | 01
! width="4%" | 02
! width="4%" | 03
! width="4%" | 04
! width="4%" | 05
! width="4%" | 06
! width="4%" | 07
! width="4%" | 08
! width="4%" | 09
! width="4%" | 0A
! width="4%" | 0B
! width="4%" | 0C
! width="4%" | 0D
! width="4%" | 0E
! width="4%" | 0F
! width="4%" | 10 ...
|-
| '''0B'''
| -
| -
| colspan="3" | Buffer address
| colspan="2" | Sector offset LSW
| colspan="2" | -
| CPU / VDP
| -
| colspan="2" | Number of sectors
| Sector offset MSB
| Name length
| Name
|-
|}

'''Create a file''': When a file is addressed, and the number of sectors is 0, a new file is created. The contents of the file should be written by BWRITE on the same file with a sector count greater than 0.

'''Write to file''': When a file is addressed, the operation writes a sequence of sectors to the file. The '''Sector offset''' is the number of the first sector of the file, counting from 0. The physical locations of the sectors are subject to the sector allocation on the device; in particular, when fragmentation is required, the sectors are written to the new fragment.

'''Writing to device''': When a device is addressed, the operation writes a sequence of sectors to the device. The '''Sector offset''' is the physical sector number.

After the BWRITE operation has completed, the PAB delivers information about the result:

'''OUT'''

{| class="plainc" style="margin-left:1%"
|-
! width="4%" | 00
! width="4%" | 01
! width="4%" | 02
! width="4%" | 03
! width="4%" | 04
! width="4%" | 05
! width="4%" | 06
! width="4%" | 07
! width="4%" | 08
! width="4%" | 09
! width="4%" | 0A
! width="4%" | 0B
! width="4%" | 0C
! width="4%" | 0D
! width="4%" | 0E
! width="4%" | 0F
! width="4%" | 10 ...
|-
| -
| -
| Error code
| colspan="3" | Updated buffer address
| colspan="2" | Updated sector offset LSW
| colspan="2" | -
| -
| -
| colspan="2" | Remaining sectors
| Updated sector offset MSB
| -
| -
|-
|}

The '''Updated buffer address''' points to the memory address after the sectors were written (e.g. when 4 sectors are written, the pointer is increased by 4*256 = 1024).

The '''Updates sector offset''' is the first sector that has not been written due to an error condition.

The '''Remaining sectors''' is the number of unwritten sectors due to an error condition.

<div class="warn">Unless you want to write directly to the device, make sure that the PAB contains a file name that points to a file, not to a device. For example, when the file name has been created by the program, and for some reason the file name is empty (like "HDS1."), the following write operation will overwrite the volume information block and the allocation tables and '''destroy the target device filesystem'''.</div>

Tick here: [ ] Yes, I fully understood the danger of this operation.

(The author lost a complete hard disk by this incident, and was lucky to have a backup.)

<div style="margin-bottom:6em"></div>

=== PROTECT ===

<div style="margin-bottom:6em"></div>

=== RENAME ===

<div style="margin-bottom:6em"></div>

=== FORMAT ===

GeneveOS Device Operation

2022-04-24T18:42:10Z

Mizapf: /* BREAD */

Accessing devices (floppy disk, hard disk, serial connector, printer) is possible in GeneveOS via XOP calls.

== User-task XOPs ==

User-task XOPs are available for use in application programs. Here is a typical example:

PABADD EQU >F180
FILE DATA 8
...
LI R0,PABADD
XOP @FILE,0
MOVB @PABADD+2,R0
JNE ERROR
...

Similar as with the TI-99/4A device service routine concept (DSR), a Peripheral Access Block (PAB) must be set up prior to invoking the XOP.

=== Device Service Routine Call ===

{| class="xoparg"
|-
|
! Input !! Output
|-
| R0
| Pointer to PAB || -
|-
|}

The actual operation is contained in the Peripheral Access Block (PAB).

=== Peripheral Access Block ===

While the TI-99/4A DSRs expect the PAB to be stored in VDP RAM, the Geneve OS DSRs use CPU RAM for the PAB, which means the PAB need not be copied to the video RAM before use. Also, you can choose to have the I/O buffers in VDP or CPU RAM.

The general layout of the PAB is as follows:

{| class="plainc" style="margin-left:1%"
|-
! width="5%" | 00
! width="5%" | 01
! width="5%" | 02
! width="5%" | 03
! width="5%" | 04
! width="5%" | 05
! width="5%" | 06
! width="5%" | 07
! width="5%" | 08
! width="5%" | 09
! width="5%" | 0A
! width="5%" | 0B
! width="5%" | 0C
! width="5%" | 0D
! width="5%" | 0E
! width="5%" | 0F
! width="5%" | 10 ...
|-
| Opcode
| Mode
| Error code
| colspan="3" | Buffer address
| colspan="2" | Record number
| colspan="2" | Record length
| Memory type
| colspan="3" | Character count
| Status byte
| Name length
| Name
|-
|}

Note that the buffer addresses are 21-bit wide, represented by the [[MDOS Memory Management Functions#Local_.28virtual.29_pages | virtual address]] within the calling task. The address for this buffer should be derived from [[MDOS Memory Management Functions | memory allocation]] operations that were invoked earlier.

After the operation, the PAB contains information about the results of the operation.

=== Mode ===

The mode bits are used to determine the operation direction (in/out/update/append), the encoding (display/internal), the structure (fixed/variable) and the access (sequential/relative).

{| class="plainbits" style="width:64%"
! 0
! 1
! 2
! 3
! 4
! 5
! 6
! 7
|-
| style="width:24%" rowspan="4" colspan="3" | Unused (000)
| style="width:8%" rowspan="2" | Fixed=0
| style="width:8%" rowspan="2" | Display=0
| style="width:16%" colspan="2" | Update=00
| style="width:8%" rowspan="2" | Sequential=0
|-
| colspan="2" | Output=01
|-
| rowspan="2" | Variable=1
| rowspan="2" | Internal=1
| colspan="2" | Input=10
| rowspan="2" | Relative=1
|-
| colspan="2" | Append=11
|}

=== Error code ===

The error code is an eight bit word with the following structure:

{| class="plainbits" style="float:left"
! 0
! 1
! 2
! 3
! 4
! 5
! 6
! 7
|-
| colspan="3" | Number
| colspan="5" | Detail code for error 7
|}

{| class="plainc" style="float:left"
! Number
! Meaning
|-
| 0
| No such device
|-
| 1
| Write-protected
|-
| 2
| Illegal open attribute
|-
| 3
| Illegal operation
|-
| 4
| Out of buffer space
|-
| 5
| Read beyond EOF
|-
| 6
| Device error
|-
| 7
| File error
|}

<div style="clear:both"></div>

== Operations ==

=== OPEN ===

Open a record-oriented file. A file must be opened before it can be read from or written to. This operation is not required for flat memory image files.

The PAB must be set up prior to invoking the operation:

'''IN'''

{| class="plainc" style="margin-left:1%"
|-
! width="4%" | 00
! width="4%" | 01
! width="4%" | 02
! width="4%" | 03
! width="4%" | 04
! width="4%" | 05
! width="4%" | 06
! width="4%" | 07
! width="4%" | 08
! width="4%" | 09
! width="4%" | 0A
! width="4%" | 0B
! width="4%" | 0C
! width="4%" | 0D
! width="4%" | 0E
! width="4%" | 0F
! width="4%" | 10 ...
|-
| '''00'''
| Mode
| -
| colspan="3" | -
| colspan="2" | Records to reserve
| colspan="2" | Record length
| -
| colspan="3" | -
| -
| Name length
| Name
|-
|}

'''Open new file''': The '''Record Length''' must be set to a value greater than 0. This will become the length of the records of the new file.

'''Open existing file''': The '''Record Length''' must match the length of the records. If the length is unknown, 0 may be passed.

After the OPEN operation has completed, the PAB delivers information about the result:

'''OUT'''

{| class="plainc" style="margin-left:1%"
|-
! width="4%" | 00
! width="4%" | 01
! width="4%" | 02
! width="4%" | 03
! width="4%" | 04
! width="4%" | 05
! width="4%" | 06
! width="4%" | 07
! width="4%" | 08
! width="4%" | 09
! width="4%" | 0A
! width="4%" | 0B
! width="4%" | 0C
! width="4%" | 0D
! width="4%" | 0E
! width="4%" | 0F
! width="4%" | 10 ...
|-
| -
| -
| Error code
| colspan="3" | -
| colspan="2" | -
| colspan="2" | Actual Record Length
| -
| 0
| colspan="2" | True Record Length
| -
| Name length
| Name
|-
|}

The '''Actual Record Length''' is the length of the records of the existing file. When 0 was passed on the call, this delivers the record length of the file; otherwise this is the value that was passed for the call. The '''True Record Length''' is the record length of the file when it already exists.

<div style="margin-bottom:6em"></div>

=== CLOSE ===

Closes a record-oriented file. A file must be closed after being used. After closing, no further read or write operations may be invoked on the file. This operation is not required for flat memory image files.

The PAB must be set up prior to invoking the operation:

'''IN'''

{| class="plainc" style="margin-left:1%"
|-
! width="4%" | 00
! width="4%" | 01
! width="4%" | 02
! width="4%" | 03
! width="4%" | 04
! width="4%" | 05
! width="4%" | 06
! width="4%" | 07
! width="4%" | 08
! width="4%" | 09
! width="4%" | 0A
! width="4%" | 0B
! width="4%" | 0C
! width="4%" | 0D
! width="4%" | 0E
! width="4%" | 0F
! width="4%" | 10 ...
|-
| '''01'''
| Mode
| -
| colspan="3" | -
| colspan="2" | -
| colspan="2" | -
| -
| colspan="3" | -
| -
| Name length
| Name
|-
|}

After the CLOSE operation has completed, the PAB delivers information about the result:

'''OUT'''

{| class="plainc" style="margin-left:1%"
|-
! width="4%" | 00
! width="4%" | 01
! width="4%" | 02
! width="4%" | 03
! width="4%" | 04
! width="4%" | 05
! width="4%" | 06
! width="4%" | 07
! width="4%" | 08
! width="4%" | 09
! width="4%" | 0A
! width="4%" | 0B
! width="4%" | 0C
! width="4%" | 0D
! width="4%" | 0E
! width="4%" | 0F
! width="4%" | 10 ...
|-
| -
| -
| Error code
| colspan="3" | -
| colspan="2" | -
| colspan="2" | -
| -
| colspan="3" | -
| -
| Name length
| Name
|-
|}

<div style="margin-bottom:6em"></div>

=== READ ===

Reads a record from a record-oriented file. For flat memory image files, [[#LOAD | LOAD]] must be used.

'''IN'''

{| class="plainc" style="margin-left:1%"
|-
! width="4%" | 00
! width="4%" | 01
! width="4%" | 02
! width="4%" | 03
! width="4%" | 04
! width="4%" | 05
! width="4%" | 06
! width="4%" | 07
! width="4%" | 08
! width="4%" | 09
! width="4%" | 0A
! width="4%" | 0B
! width="4%" | 0C
! width="4%" | 0D
! width="4%" | 0E
! width="4%" | 0F
! width="4%" | 10 ...
|-
| '''02'''
| Mode
| -
| colspan="3" | Buffer address
| colspan="2" | Record number
| colspan="2" | Record length
| Memory
| colspan="3" | -
| -
| Name length
| Name
|-
|}

Use the '''Record number''' field to specify the desired record in '''fixed record length''' files. This is not available for variable length record files.

The '''Record Length''' must match the length of the records as specified by [[#OPEN | OPEN]].

The '''Memory''' flag determines whether the data are read into CPU (0) or VDP (not 0) memory.

After the READ operation has completed, the PAB delivers information about the result:

'''OUT'''

{| class="plainc" style="margin-left:1%"
|-
! width="4%" | 00
! width="4%" | 01
! width="4%" | 02
! width="4%" | 03
! width="4%" | 04
! width="4%" | 05
! width="4%" | 06
! width="4%" | 07
! width="4%" | 08
! width="4%" | 09
! width="4%" | 0A
! width="4%" | 0B
! width="4%" | 0C
! width="4%" | 0D
! width="4%" | 0E
! width="4%" | 0F
! width="4%" | 10 ...
|-
| -
| -
| Error code
| colspan="3" | -
| colspan="2" | Next record number
| colspan="2" | -
| -
| colspan="3" | Number of read bytes
| -
| Name length
| Name
|}

'''Next record number''' applies for fixed record length files only.

<div style="margin-bottom:6em"></div>

=== WRITE ===

Writes a record to a record-oriented file. For flat memory image files, [[#SAVE | SAVE]] must be used.

'''IN'''

{| class="plainc" style="margin-left:1%"
|-
! width="4%" | 00
! width="4%" | 01
! width="4%" | 02
! width="4%" | 03
! width="4%" | 04
! width="4%" | 05
! width="4%" | 06
! width="4%" | 07
! width="4%" | 08
! width="4%" | 09
! width="4%" | 0A
! width="4%" | 0B
! width="4%" | 0C
! width="4%" | 0D
! width="4%" | 0E
! width="4%" | 0F
! width="4%" | 10 ...
|-
| '''03'''
| Mode
| -
| colspan="3" | Buffer address
| colspan="2" | Record number
| colspan="2" | Record length
| Memory
| colspan="3" | Number of bytes to write
| -
| Name length
| Name
|-
|}

Use the '''Record number''' field to specify the desired record in '''fixed record length''' files. This is not available for variable length record files.

The '''Record Length''' must match the length of the records as specified by [[#OPEN | OPEN]].

The '''Memory''' flag determines whether the data written from CPU (0) or VDP (not 0) memory.

After the WRITE operation has completed, the PAB delivers information about the result:

'''OUT'''

{| class="plainc" style="margin-left:1%"
|-
! width="4%" | 00
! width="4%" | 01
! width="4%" | 02
! width="4%" | 03
! width="4%" | 04
! width="4%" | 05
! width="4%" | 06
! width="4%" | 07
! width="4%" | 08
! width="4%" | 09
! width="4%" | 0A
! width="4%" | 0B
! width="4%" | 0C
! width="4%" | 0D
! width="4%" | 0E
! width="4%" | 0F
! width="4%" | 10 ...
|-
| -
| -
| Error code
| colspan="3" | -
| colspan="2" | Next record number
| colspan="2" | -
| -
| colspan="3" | Number of read bytes
| -
| Name length
| Name
|}

'''Next record number''' applies for fixed record length files only.

<div style="margin-bottom:6em"></div>

=== RESTORE ===

<div style="margin-bottom:6em"></div>

=== LOAD ===

<div style="margin-bottom:6em"></div>

=== SAVE ===

<div style="margin-bottom:6em"></div>

=== DELETE ===

<div style="margin-bottom:6em"></div>

=== SCRATCH ===

<div style="margin-bottom:6em"></div>

=== STATUS ===

<div style="margin-bottom:6em"></div>

=== BREAD ===

Reads a sector from a file or from a device. This is a level-2 operation, that is, it accesses the device based on sector addressing (or sectors of a file). BREAD allows for two operations:

* Read sectors from a file.
* Read sectors from a device.

'''IN'''

{| class="plainc" style="margin-left:1%"
|-
! width="4%" | 00
! width="4%" | 01
! width="4%" | 02
! width="4%" | 03
! width="4%" | 04
! width="4%" | 05
! width="4%" | 06
! width="4%" | 07
! width="4%" | 08
! width="4%" | 09
! width="4%" | 0A
! width="4%" | 0B
! width="4%" | 0C
! width="4%" | 0D
! width="4%" | 0E
! width="4%" | 0F
! width="4%" | 10 ...
|-
| '''0A'''
| -
| -
| colspan="3" | Buffer address
| colspan="2" | Sector offset LSW
| colspan="2" | -
| CPU / VDP
| -
| colspan="2" | Number of sectors
| Sector offset MSB
| Name length
| Name
|-
|}

The sector offset is defined by byte 0E as the most significant byte (value*65536) plus the word in bytes 06 and 07.

Byte 0A specifies whether the buffer address belongs to the CPU (0) or the VDP (non-zero) address space.

* CPU buffer address: ...p pppp.pppx xxxx.xxxx xxxx. The first three bits are ignored; the next 8 bits specify the page number in the user task, and the remaining 13 bits provide the offset in the page.
* VDP buffer address: .... ...x.xxxx xxxx.xxxx xxxx. The last 17 bits indicate the 128K video address.

'''Read from file''': When a file is addressed, the operation reads a sequence of sectors from the file. The '''Sector offset''' is the number of the first sector of the file, counting from 0. The physical locations of the sectors are subject to the sector allocation on the device.

'''Read from device''': When a device is addressed, the operation reads a sequence of sectors from the device. The '''Sector offset''' is the physical sector number.

After the BREAD operation has completed, the PAB delivers information about the result:

'''OUT'''

{| class="plainc" style="margin-left:1%"
|-
! width="4%" | 00
! width="4%" | 01
! width="4%" | 02
! width="4%" | 03
! width="4%" | 04
! width="4%" | 05
! width="4%" | 06
! width="4%" | 07
! width="4%" | 08
! width="4%" | 09
! width="4%" | 0A
! width="4%" | 0B
! width="4%" | 0C
! width="4%" | 0D
! width="4%" | 0E
! width="4%" | 0F
! width="4%" | 10 ...
|-
| -
| -
| Error code
| colspan="3" | Updated buffer address
| colspan="2" | Updated sector offset LSW
| colspan="2" | -
| -
| -
| colspan="2" | Remaining sectors
| Updated sector offset MSB
| -
| -
|-
|}

'''Error codes'''

* '''60''': Bad operation; happens when the device is not a block device.
* '''A0''': Read beyond end of file or device.
* '''C0''': Media error. The system was unable to read the sector although it should be readable.
* '''E0''': General error; happens when the device does not contain the specified file.

The '''Updated buffer address''' points to the memory address after the sectors were read (e.g. when 4 sectors are read, the pointer is increased by 4*256 = 1024).

The '''Updated sector offset''' is the first sector that has not been read due to an error condition.

The '''Remaining sectors''' is the number of unread sectors due to an error condition.

=== BWRITE ===

Writes a sector to a file or to a device. This is a level-2 operation, that is, it accesses the device based on sector addressing (or sectors of a file). BWRITE allows for three operations:

* Create a new, empty file.
* Write sectors to a file.
* Write sectors to a device.

'''IN'''

{| class="plainc" style="margin-left:1%"
|-
! width="4%" | 00
! width="4%" | 01
! width="4%" | 02
! width="4%" | 03
! width="4%" | 04
! width="4%" | 05
! width="4%" | 06
! width="4%" | 07
! width="4%" | 08
! width="4%" | 09
! width="4%" | 0A
! width="4%" | 0B
! width="4%" | 0C
! width="4%" | 0D
! width="4%" | 0E
! width="4%" | 0F
! width="4%" | 10 ...
|-
| '''0B'''
| -
| -
| colspan="3" | Buffer address
| colspan="2" | Sector offset
| colspan="2" | -
| -
| colspan="3" | Number of sectors
| -
| Name length
| Name
|-
|}

'''Create a file''': When a file is addressed, and the number of sectors is 0, a new file is created. The contents of the file should be written by BWRITE on the same file with a sector count greater than 0.

'''Write to file''': When a file is addressed, the operation writes a sequence of sectors to the file. The '''Sector offset''' is the number of the first sector of the file, counting from 0. The physical locations of the sectors are subject to the sector allocation on the device; in particular, when fragmentation is required, the sectors are written to the new fragment.

'''Writing to device''': When a device is addressed, the operation writes a sequence of sectors to the device. The '''Sector offset''' is the physical sector number.

After the BWRITE operation has completed, the PAB delivers information about the result:

'''OUT'''

{| class="plainc" style="margin-left:1%"
|-
! width="4%" | 00
! width="4%" | 01
! width="4%" | 02
! width="4%" | 03
! width="4%" | 04
! width="4%" | 05
! width="4%" | 06
! width="4%" | 07
! width="4%" | 08
! width="4%" | 09
! width="4%" | 0A
! width="4%" | 0B
! width="4%" | 0C
! width="4%" | 0D
! width="4%" | 0E
! width="4%" | 0F
! width="4%" | 10 ...
|-
| -
| -
| Error code
| colspan="3" | Updated buffer address
| colspan="2" | Next unwritten sector
| colspan="2" | -
| -
| 0
| colspan="2" | Number of unwritten sectors
| -
| Name length
| Name
|-
|}

The '''Updated buffer address''' points to the memory address after the sectors were written (e.g. when 4 sectors are written, the pointer is increased by 4*256 = 1024).

The '''Next unwritten sector''' is the first sector that has not been written due to an error condition.

The '''Number of unwritten sectors''' is the number of unwritten sectors due to an error condition.

<div class="warn">Unless you want to write directly to the device, make sure that the PAB contains a file name that points to a file, not to a device. For example, when the file name has been created by the program, and for some reason the file name is empty (like "HDS1."), the following write operation will overwrite the volume information block and the allocation tables and '''destroy the target device filesystem'''.</div>

Tick here: [ ] Yes, I fully understood the danger of this operation.

(The author lost a complete hard disk by this incident, and was lucky to have a backup.)

<div style="margin-bottom:6em"></div>

=== PROTECT ===

<div style="margin-bottom:6em"></div>

=== RENAME ===

<div style="margin-bottom:6em"></div>

=== FORMAT ===

GeneveOS Device Operation

2022-04-24T18:30:57Z

Mizapf: /* BREAD */

Accessing devices (floppy disk, hard disk, serial connector, printer) is possible in GeneveOS via XOP calls.

== User-task XOPs ==

User-task XOPs are available for use in application programs. Here is a typical example:

PABADD EQU >F180
FILE DATA 8
...
LI R0,PABADD
XOP @FILE,0
MOVB @PABADD+2,R0
JNE ERROR
...

Similar as with the TI-99/4A device service routine concept (DSR), a Peripheral Access Block (PAB) must be set up prior to invoking the XOP.

=== Device Service Routine Call ===

{| class="xoparg"
|-
|
! Input !! Output
|-
| R0
| Pointer to PAB || -
|-
|}

The actual operation is contained in the Peripheral Access Block (PAB).

=== Peripheral Access Block ===

While the TI-99/4A DSRs expect the PAB to be stored in VDP RAM, the Geneve OS DSRs use CPU RAM for the PAB, which means the PAB need not be copied to the video RAM before use. Also, you can choose to have the I/O buffers in VDP or CPU RAM.

The general layout of the PAB is as follows:

{| class="plainc" style="margin-left:1%"
|-
! width="5%" | 00
! width="5%" | 01
! width="5%" | 02
! width="5%" | 03
! width="5%" | 04
! width="5%" | 05
! width="5%" | 06
! width="5%" | 07
! width="5%" | 08
! width="5%" | 09
! width="5%" | 0A
! width="5%" | 0B
! width="5%" | 0C
! width="5%" | 0D
! width="5%" | 0E
! width="5%" | 0F
! width="5%" | 10 ...
|-
| Opcode
| Mode
| Error code
| colspan="3" | Buffer address
| colspan="2" | Record number
| colspan="2" | Record length
| Memory type
| colspan="3" | Character count
| Status byte
| Name length
| Name
|-
|}

Note that the buffer addresses are 21-bit wide, represented by the [[MDOS Memory Management Functions#Local_.28virtual.29_pages | virtual address]] within the calling task. The address for this buffer should be derived from [[MDOS Memory Management Functions | memory allocation]] operations that were invoked earlier.

After the operation, the PAB contains information about the results of the operation.

=== Mode ===

The mode bits are used to determine the operation direction (in/out/update/append), the encoding (display/internal), the structure (fixed/variable) and the access (sequential/relative).

{| class="plainbits" style="width:64%"
! 0
! 1
! 2
! 3
! 4
! 5
! 6
! 7
|-
| style="width:24%" rowspan="4" colspan="3" | Unused (000)
| style="width:8%" rowspan="2" | Fixed=0
| style="width:8%" rowspan="2" | Display=0
| style="width:16%" colspan="2" | Update=00
| style="width:8%" rowspan="2" | Sequential=0
|-
| colspan="2" | Output=01
|-
| rowspan="2" | Variable=1
| rowspan="2" | Internal=1
| colspan="2" | Input=10
| rowspan="2" | Relative=1
|-
| colspan="2" | Append=11
|}

=== Error code ===

The error code is an eight bit word with the following structure:

{| class="plainbits" style="float:left"
! 0
! 1
! 2
! 3
! 4
! 5
! 6
! 7
|-
| colspan="3" | Number
| colspan="5" | Detail code for error 7
|}

{| class="plainc" style="float:left"
! Number
! Meaning
|-
| 0
| No such device
|-
| 1
| Write-protected
|-
| 2
| Illegal open attribute
|-
| 3
| Illegal operation
|-
| 4
| Out of buffer space
|-
| 5
| Read beyond EOF
|-
| 6
| Device error
|-
| 7
| File error
|}

<div style="clear:both"></div>

== Operations ==

=== OPEN ===

Open a record-oriented file. A file must be opened before it can be read from or written to. This operation is not required for flat memory image files.

The PAB must be set up prior to invoking the operation:

'''IN'''

{| class="plainc" style="margin-left:1%"
|-
! width="4%" | 00
! width="4%" | 01
! width="4%" | 02
! width="4%" | 03
! width="4%" | 04
! width="4%" | 05
! width="4%" | 06
! width="4%" | 07
! width="4%" | 08
! width="4%" | 09
! width="4%" | 0A
! width="4%" | 0B
! width="4%" | 0C
! width="4%" | 0D
! width="4%" | 0E
! width="4%" | 0F
! width="4%" | 10 ...
|-
| '''00'''
| Mode
| -
| colspan="3" | -
| colspan="2" | Records to reserve
| colspan="2" | Record length
| -
| colspan="3" | -
| -
| Name length
| Name
|-
|}

'''Open new file''': The '''Record Length''' must be set to a value greater than 0. This will become the length of the records of the new file.

'''Open existing file''': The '''Record Length''' must match the length of the records. If the length is unknown, 0 may be passed.

After the OPEN operation has completed, the PAB delivers information about the result:

'''OUT'''

{| class="plainc" style="margin-left:1%"
|-
! width="4%" | 00
! width="4%" | 01
! width="4%" | 02
! width="4%" | 03
! width="4%" | 04
! width="4%" | 05
! width="4%" | 06
! width="4%" | 07
! width="4%" | 08
! width="4%" | 09
! width="4%" | 0A
! width="4%" | 0B
! width="4%" | 0C
! width="4%" | 0D
! width="4%" | 0E
! width="4%" | 0F
! width="4%" | 10 ...
|-
| -
| -
| Error code
| colspan="3" | -
| colspan="2" | -
| colspan="2" | Actual Record Length
| -
| 0
| colspan="2" | True Record Length
| -
| Name length
| Name
|-
|}

The '''Actual Record Length''' is the length of the records of the existing file. When 0 was passed on the call, this delivers the record length of the file; otherwise this is the value that was passed for the call. The '''True Record Length''' is the record length of the file when it already exists.

<div style="margin-bottom:6em"></div>

=== CLOSE ===

Closes a record-oriented file. A file must be closed after being used. After closing, no further read or write operations may be invoked on the file. This operation is not required for flat memory image files.

The PAB must be set up prior to invoking the operation:

'''IN'''

{| class="plainc" style="margin-left:1%"
|-
! width="4%" | 00
! width="4%" | 01
! width="4%" | 02
! width="4%" | 03
! width="4%" | 04
! width="4%" | 05
! width="4%" | 06
! width="4%" | 07
! width="4%" | 08
! width="4%" | 09
! width="4%" | 0A
! width="4%" | 0B
! width="4%" | 0C
! width="4%" | 0D
! width="4%" | 0E
! width="4%" | 0F
! width="4%" | 10 ...
|-
| '''01'''
| Mode
| -
| colspan="3" | -
| colspan="2" | -
| colspan="2" | -
| -
| colspan="3" | -
| -
| Name length
| Name
|-
|}

After the CLOSE operation has completed, the PAB delivers information about the result:

'''OUT'''

{| class="plainc" style="margin-left:1%"
|-
! width="4%" | 00
! width="4%" | 01
! width="4%" | 02
! width="4%" | 03
! width="4%" | 04
! width="4%" | 05
! width="4%" | 06
! width="4%" | 07
! width="4%" | 08
! width="4%" | 09
! width="4%" | 0A
! width="4%" | 0B
! width="4%" | 0C
! width="4%" | 0D
! width="4%" | 0E
! width="4%" | 0F
! width="4%" | 10 ...
|-
| -
| -
| Error code
| colspan="3" | -
| colspan="2" | -
| colspan="2" | -
| -
| colspan="3" | -
| -
| Name length
| Name
|-
|}

<div style="margin-bottom:6em"></div>

=== READ ===

Reads a record from a record-oriented file. For flat memory image files, [[#LOAD | LOAD]] must be used.

'''IN'''

{| class="plainc" style="margin-left:1%"
|-
! width="4%" | 00
! width="4%" | 01
! width="4%" | 02
! width="4%" | 03
! width="4%" | 04
! width="4%" | 05
! width="4%" | 06
! width="4%" | 07
! width="4%" | 08
! width="4%" | 09
! width="4%" | 0A
! width="4%" | 0B
! width="4%" | 0C
! width="4%" | 0D
! width="4%" | 0E
! width="4%" | 0F
! width="4%" | 10 ...
|-
| '''02'''
| Mode
| -
| colspan="3" | Buffer address
| colspan="2" | Record number
| colspan="2" | Record length
| Memory
| colspan="3" | -
| -
| Name length
| Name
|-
|}

Use the '''Record number''' field to specify the desired record in '''fixed record length''' files. This is not available for variable length record files.

The '''Record Length''' must match the length of the records as specified by [[#OPEN | OPEN]].

The '''Memory''' flag determines whether the data are read into CPU (0) or VDP (not 0) memory.

After the READ operation has completed, the PAB delivers information about the result:

'''OUT'''

{| class="plainc" style="margin-left:1%"
|-
! width="4%" | 00
! width="4%" | 01
! width="4%" | 02
! width="4%" | 03
! width="4%" | 04
! width="4%" | 05
! width="4%" | 06
! width="4%" | 07
! width="4%" | 08
! width="4%" | 09
! width="4%" | 0A
! width="4%" | 0B
! width="4%" | 0C
! width="4%" | 0D
! width="4%" | 0E
! width="4%" | 0F
! width="4%" | 10 ...
|-
| -
| -
| Error code
| colspan="3" | -
| colspan="2" | Next record number
| colspan="2" | -
| -
| colspan="3" | Number of read bytes
| -
| Name length
| Name
|}

'''Next record number''' applies for fixed record length files only.

<div style="margin-bottom:6em"></div>

=== WRITE ===

Writes a record to a record-oriented file. For flat memory image files, [[#SAVE | SAVE]] must be used.

'''IN'''

{| class="plainc" style="margin-left:1%"
|-
! width="4%" | 00
! width="4%" | 01
! width="4%" | 02
! width="4%" | 03
! width="4%" | 04
! width="4%" | 05
! width="4%" | 06
! width="4%" | 07
! width="4%" | 08
! width="4%" | 09
! width="4%" | 0A
! width="4%" | 0B
! width="4%" | 0C
! width="4%" | 0D
! width="4%" | 0E
! width="4%" | 0F
! width="4%" | 10 ...
|-
| '''03'''
| Mode
| -
| colspan="3" | Buffer address
| colspan="2" | Record number
| colspan="2" | Record length
| Memory
| colspan="3" | Number of bytes to write
| -
| Name length
| Name
|-
|}

Use the '''Record number''' field to specify the desired record in '''fixed record length''' files. This is not available for variable length record files.

The '''Record Length''' must match the length of the records as specified by [[#OPEN | OPEN]].

The '''Memory''' flag determines whether the data written from CPU (0) or VDP (not 0) memory.

After the WRITE operation has completed, the PAB delivers information about the result:

'''OUT'''

{| class="plainc" style="margin-left:1%"
|-
! width="4%" | 00
! width="4%" | 01
! width="4%" | 02
! width="4%" | 03
! width="4%" | 04
! width="4%" | 05
! width="4%" | 06
! width="4%" | 07
! width="4%" | 08
! width="4%" | 09
! width="4%" | 0A
! width="4%" | 0B
! width="4%" | 0C
! width="4%" | 0D
! width="4%" | 0E
! width="4%" | 0F
! width="4%" | 10 ...
|-
| -
| -
| Error code
| colspan="3" | -
| colspan="2" | Next record number
| colspan="2" | -
| -
| colspan="3" | Number of read bytes
| -
| Name length
| Name
|}

'''Next record number''' applies for fixed record length files only.

<div style="margin-bottom:6em"></div>

=== RESTORE ===

<div style="margin-bottom:6em"></div>

=== LOAD ===

<div style="margin-bottom:6em"></div>

=== SAVE ===

<div style="margin-bottom:6em"></div>

=== DELETE ===

<div style="margin-bottom:6em"></div>

=== SCRATCH ===

<div style="margin-bottom:6em"></div>

=== STATUS ===

<div style="margin-bottom:6em"></div>

=== BREAD ===

Reads a sector from a file or from a device. This is a level-2 operation, that is, it accesses the device based on sector addressing (or sectors of a file). BREAD allows for two operations:

* Read sectors from a file.
* Read sectors from a device.

'''IN'''

{| class="plainc" style="margin-left:1%"
|-
! width="4%" | 00
! width="4%" | 01
! width="4%" | 02
! width="4%" | 03
! width="4%" | 04
! width="4%" | 05
! width="4%" | 06
! width="4%" | 07
! width="4%" | 08
! width="4%" | 09
! width="4%" | 0A
! width="4%" | 0B
! width="4%" | 0C
! width="4%" | 0D
! width="4%" | 0E
! width="4%" | 0F
! width="4%" | 10 ...
|-
| '''0A'''
| -
| -
| colspan="3" | Buffer address
| colspan="2" | Sector offset LSW
| colspan="2" | -
| CPU / VDP
| -
| colspan="2" | Number of sectors
| Sector offset MSB
| Name length
| Name
|-
|}

The sector offset is defined by byte 0E as the most significant byte (value*65536) plus the word in bytes 06 and 07.

Byte 0A specifies whether the buffer address belongs to the CPU (0) or the VDP (non-zero) address space.

'''Read from file''': When a file is addressed, the operation reads a sequence of sectors from the file. The '''Sector offset''' is the number of the first sector of the file, counting from 0. The physical locations of the sectors are subject to the sector allocation on the device.

'''Read from device''': When a device is addressed, the operation reads a sequence of sectors from the device. The '''Sector offset''' is the physical sector number.

After the BREAD operation has completed, the PAB delivers information about the result:

'''OUT'''

{| class="plainc" style="margin-left:1%"
|-
! width="4%" | 00
! width="4%" | 01
! width="4%" | 02
! width="4%" | 03
! width="4%" | 04
! width="4%" | 05
! width="4%" | 06
! width="4%" | 07
! width="4%" | 08
! width="4%" | 09
! width="4%" | 0A
! width="4%" | 0B
! width="4%" | 0C
! width="4%" | 0D
! width="4%" | 0E
! width="4%" | 0F
! width="4%" | 10 ...
|-
| -
| -
| Error code
| colspan="3" | Updated buffer address
| colspan="2" | Updated sector offset LSW
| colspan="2" | -
| -
| -
| colspan="2" | Remaining sectors
| Updated sector offset MSB
| -
| -
|-
|}

'''Error codes'''

* '''60''': Bad operation; happens when the device is not a block device.
* '''A0''': Read beyond end of file or device.
* '''C0''': Media error. The system was unable to read the sector although it should be readable.
* '''E0''': General error; happens when the device does not contain the specified file.

The '''Updated buffer address''' points to the memory address after the sectors were read (e.g. when 4 sectors are read, the pointer is increased by 4*256 = 1024).

The '''Updated sector offset''' is the first sector that has not been read due to an error condition.

The '''Remaining sectors''' is the number of unread sectors due to an error condition.

=== BWRITE ===

Writes a sector to a file or to a device. This is a level-2 operation, that is, it accesses the device based on sector addressing (or sectors of a file). BWRITE allows for three operations:

* Create a new, empty file.
* Write sectors to a file.
* Write sectors to a device.

'''IN'''

{| class="plainc" style="margin-left:1%"
|-
! width="4%" | 00
! width="4%" | 01
! width="4%" | 02
! width="4%" | 03
! width="4%" | 04
! width="4%" | 05
! width="4%" | 06
! width="4%" | 07
! width="4%" | 08
! width="4%" | 09
! width="4%" | 0A
! width="4%" | 0B
! width="4%" | 0C
! width="4%" | 0D
! width="4%" | 0E
! width="4%" | 0F
! width="4%" | 10 ...
|-
| '''0B'''
| -
| -
| colspan="3" | Buffer address
| colspan="2" | Sector offset
| colspan="2" | -
| -
| colspan="3" | Number of sectors
| -
| Name length
| Name
|-
|}

'''Create a file''': When a file is addressed, and the number of sectors is 0, a new file is created. The contents of the file should be written by BWRITE on the same file with a sector count greater than 0.

'''Write to file''': When a file is addressed, the operation writes a sequence of sectors to the file. The '''Sector offset''' is the number of the first sector of the file, counting from 0. The physical locations of the sectors are subject to the sector allocation on the device; in particular, when fragmentation is required, the sectors are written to the new fragment.

'''Writing to device''': When a device is addressed, the operation writes a sequence of sectors to the device. The '''Sector offset''' is the physical sector number.

After the BWRITE operation has completed, the PAB delivers information about the result:

'''OUT'''

{| class="plainc" style="margin-left:1%"
|-
! width="4%" | 00
! width="4%" | 01
! width="4%" | 02
! width="4%" | 03
! width="4%" | 04
! width="4%" | 05
! width="4%" | 06
! width="4%" | 07
! width="4%" | 08
! width="4%" | 09
! width="4%" | 0A
! width="4%" | 0B
! width="4%" | 0C
! width="4%" | 0D
! width="4%" | 0E
! width="4%" | 0F
! width="4%" | 10 ...
|-
| -
| -
| Error code
| colspan="3" | Updated buffer address
| colspan="2" | Next unwritten sector
| colspan="2" | -
| -
| 0
| colspan="2" | Number of unwritten sectors
| -
| Name length
| Name
|-
|}

The '''Updated buffer address''' points to the memory address after the sectors were written (e.g. when 4 sectors are written, the pointer is increased by 4*256 = 1024).

The '''Next unwritten sector''' is the first sector that has not been written due to an error condition.

The '''Number of unwritten sectors''' is the number of unwritten sectors due to an error condition.

<div class="warn">Unless you want to write directly to the device, make sure that the PAB contains a file name that points to a file, not to a device. For example, when the file name has been created by the program, and for some reason the file name is empty (like "HDS1."), the following write operation will overwrite the volume information block and the allocation tables and '''destroy the target device filesystem'''.</div>

Tick here: [ ] Yes, I fully understood the danger of this operation.

(The author lost a complete hard disk by this incident, and was lucky to have a backup.)

<div style="margin-bottom:6em"></div>

=== PROTECT ===

<div style="margin-bottom:6em"></div>

=== RENAME ===

<div style="margin-bottom:6em"></div>

=== FORMAT ===

GeneveOS Device Operation

2022-04-24T18:25:00Z

Mizapf: /* BREAD */

Accessing devices (floppy disk, hard disk, serial connector, printer) is possible in GeneveOS via XOP calls.

== User-task XOPs ==

User-task XOPs are available for use in application programs. Here is a typical example:

PABADD EQU >F180
FILE DATA 8
...
LI R0,PABADD
XOP @FILE,0
MOVB @PABADD+2,R0
JNE ERROR
...

Similar as with the TI-99/4A device service routine concept (DSR), a Peripheral Access Block (PAB) must be set up prior to invoking the XOP.

=== Device Service Routine Call ===

{| class="xoparg"
|-
|
! Input !! Output
|-
| R0
| Pointer to PAB || -
|-
|}

The actual operation is contained in the Peripheral Access Block (PAB).

=== Peripheral Access Block ===

While the TI-99/4A DSRs expect the PAB to be stored in VDP RAM, the Geneve OS DSRs use CPU RAM for the PAB, which means the PAB need not be copied to the video RAM before use. Also, you can choose to have the I/O buffers in VDP or CPU RAM.

The general layout of the PAB is as follows:

{| class="plainc" style="margin-left:1%"
|-
! width="5%" | 00
! width="5%" | 01
! width="5%" | 02
! width="5%" | 03
! width="5%" | 04
! width="5%" | 05
! width="5%" | 06
! width="5%" | 07
! width="5%" | 08
! width="5%" | 09
! width="5%" | 0A
! width="5%" | 0B
! width="5%" | 0C
! width="5%" | 0D
! width="5%" | 0E
! width="5%" | 0F
! width="5%" | 10 ...
|-
| Opcode
| Mode
| Error code
| colspan="3" | Buffer address
| colspan="2" | Record number
| colspan="2" | Record length
| Memory type
| colspan="3" | Character count
| Status byte
| Name length
| Name
|-
|}

Note that the buffer addresses are 21-bit wide, represented by the [[MDOS Memory Management Functions#Local_.28virtual.29_pages | virtual address]] within the calling task. The address for this buffer should be derived from [[MDOS Memory Management Functions | memory allocation]] operations that were invoked earlier.

After the operation, the PAB contains information about the results of the operation.

=== Mode ===

The mode bits are used to determine the operation direction (in/out/update/append), the encoding (display/internal), the structure (fixed/variable) and the access (sequential/relative).

{| class="plainbits" style="width:64%"
! 0
! 1
! 2
! 3
! 4
! 5
! 6
! 7
|-
| style="width:24%" rowspan="4" colspan="3" | Unused (000)
| style="width:8%" rowspan="2" | Fixed=0
| style="width:8%" rowspan="2" | Display=0
| style="width:16%" colspan="2" | Update=00
| style="width:8%" rowspan="2" | Sequential=0
|-
| colspan="2" | Output=01
|-
| rowspan="2" | Variable=1
| rowspan="2" | Internal=1
| colspan="2" | Input=10
| rowspan="2" | Relative=1
|-
| colspan="2" | Append=11
|}

=== Error code ===

The error code is an eight bit word with the following structure:

{| class="plainbits" style="float:left"
! 0
! 1
! 2
! 3
! 4
! 5
! 6
! 7
|-
| colspan="3" | Number
| colspan="5" | Detail code for error 7
|}

{| class="plainc" style="float:left"
! Number
! Meaning
|-
| 0
| No such device
|-
| 1
| Write-protected
|-
| 2
| Illegal open attribute
|-
| 3
| Illegal operation
|-
| 4
| Out of buffer space
|-
| 5
| Read beyond EOF
|-
| 6
| Device error
|-
| 7
| File error
|}

<div style="clear:both"></div>

== Operations ==

=== OPEN ===

Open a record-oriented file. A file must be opened before it can be read from or written to. This operation is not required for flat memory image files.

The PAB must be set up prior to invoking the operation:

'''IN'''

{| class="plainc" style="margin-left:1%"
|-
! width="4%" | 00
! width="4%" | 01
! width="4%" | 02
! width="4%" | 03
! width="4%" | 04
! width="4%" | 05
! width="4%" | 06
! width="4%" | 07
! width="4%" | 08
! width="4%" | 09
! width="4%" | 0A
! width="4%" | 0B
! width="4%" | 0C
! width="4%" | 0D
! width="4%" | 0E
! width="4%" | 0F
! width="4%" | 10 ...
|-
| '''00'''
| Mode
| -
| colspan="3" | -
| colspan="2" | Records to reserve
| colspan="2" | Record length
| -
| colspan="3" | -
| -
| Name length
| Name
|-
|}

'''Open new file''': The '''Record Length''' must be set to a value greater than 0. This will become the length of the records of the new file.

'''Open existing file''': The '''Record Length''' must match the length of the records. If the length is unknown, 0 may be passed.

After the OPEN operation has completed, the PAB delivers information about the result:

'''OUT'''

{| class="plainc" style="margin-left:1%"
|-
! width="4%" | 00
! width="4%" | 01
! width="4%" | 02
! width="4%" | 03
! width="4%" | 04
! width="4%" | 05
! width="4%" | 06
! width="4%" | 07
! width="4%" | 08
! width="4%" | 09
! width="4%" | 0A
! width="4%" | 0B
! width="4%" | 0C
! width="4%" | 0D
! width="4%" | 0E
! width="4%" | 0F
! width="4%" | 10 ...
|-
| -
| -
| Error code
| colspan="3" | -
| colspan="2" | -
| colspan="2" | Actual Record Length
| -
| 0
| colspan="2" | True Record Length
| -
| Name length
| Name
|-
|}

The '''Actual Record Length''' is the length of the records of the existing file. When 0 was passed on the call, this delivers the record length of the file; otherwise this is the value that was passed for the call. The '''True Record Length''' is the record length of the file when it already exists.

<div style="margin-bottom:6em"></div>

=== CLOSE ===

Closes a record-oriented file. A file must be closed after being used. After closing, no further read or write operations may be invoked on the file. This operation is not required for flat memory image files.

The PAB must be set up prior to invoking the operation:

'''IN'''

{| class="plainc" style="margin-left:1%"
|-
! width="4%" | 00
! width="4%" | 01
! width="4%" | 02
! width="4%" | 03
! width="4%" | 04
! width="4%" | 05
! width="4%" | 06
! width="4%" | 07
! width="4%" | 08
! width="4%" | 09
! width="4%" | 0A
! width="4%" | 0B
! width="4%" | 0C
! width="4%" | 0D
! width="4%" | 0E
! width="4%" | 0F
! width="4%" | 10 ...
|-
| '''01'''
| Mode
| -
| colspan="3" | -
| colspan="2" | -
| colspan="2" | -
| -
| colspan="3" | -
| -
| Name length
| Name
|-
|}

After the CLOSE operation has completed, the PAB delivers information about the result:

'''OUT'''

{| class="plainc" style="margin-left:1%"
|-
! width="4%" | 00
! width="4%" | 01
! width="4%" | 02
! width="4%" | 03
! width="4%" | 04
! width="4%" | 05
! width="4%" | 06
! width="4%" | 07
! width="4%" | 08
! width="4%" | 09
! width="4%" | 0A
! width="4%" | 0B
! width="4%" | 0C
! width="4%" | 0D
! width="4%" | 0E
! width="4%" | 0F
! width="4%" | 10 ...
|-
| -
| -
| Error code
| colspan="3" | -
| colspan="2" | -
| colspan="2" | -
| -
| colspan="3" | -
| -
| Name length
| Name
|-
|}

<div style="margin-bottom:6em"></div>

=== READ ===

Reads a record from a record-oriented file. For flat memory image files, [[#LOAD | LOAD]] must be used.

'''IN'''

{| class="plainc" style="margin-left:1%"
|-
! width="4%" | 00
! width="4%" | 01
! width="4%" | 02
! width="4%" | 03
! width="4%" | 04
! width="4%" | 05
! width="4%" | 06
! width="4%" | 07
! width="4%" | 08
! width="4%" | 09
! width="4%" | 0A
! width="4%" | 0B
! width="4%" | 0C
! width="4%" | 0D
! width="4%" | 0E
! width="4%" | 0F
! width="4%" | 10 ...
|-
| '''02'''
| Mode
| -
| colspan="3" | Buffer address
| colspan="2" | Record number
| colspan="2" | Record length
| Memory
| colspan="3" | -
| -
| Name length
| Name
|-
|}

Use the '''Record number''' field to specify the desired record in '''fixed record length''' files. This is not available for variable length record files.

The '''Record Length''' must match the length of the records as specified by [[#OPEN | OPEN]].

The '''Memory''' flag determines whether the data are read into CPU (0) or VDP (not 0) memory.

After the READ operation has completed, the PAB delivers information about the result:

'''OUT'''

{| class="plainc" style="margin-left:1%"
|-
! width="4%" | 00
! width="4%" | 01
! width="4%" | 02
! width="4%" | 03
! width="4%" | 04
! width="4%" | 05
! width="4%" | 06
! width="4%" | 07
! width="4%" | 08
! width="4%" | 09
! width="4%" | 0A
! width="4%" | 0B
! width="4%" | 0C
! width="4%" | 0D
! width="4%" | 0E
! width="4%" | 0F
! width="4%" | 10 ...
|-
| -
| -
| Error code
| colspan="3" | -
| colspan="2" | Next record number
| colspan="2" | -
| -
| colspan="3" | Number of read bytes
| -
| Name length
| Name
|}

'''Next record number''' applies for fixed record length files only.

<div style="margin-bottom:6em"></div>

=== WRITE ===

Writes a record to a record-oriented file. For flat memory image files, [[#SAVE | SAVE]] must be used.

'''IN'''

{| class="plainc" style="margin-left:1%"
|-
! width="4%" | 00
! width="4%" | 01
! width="4%" | 02
! width="4%" | 03
! width="4%" | 04
! width="4%" | 05
! width="4%" | 06
! width="4%" | 07
! width="4%" | 08
! width="4%" | 09
! width="4%" | 0A
! width="4%" | 0B
! width="4%" | 0C
! width="4%" | 0D
! width="4%" | 0E
! width="4%" | 0F
! width="4%" | 10 ...
|-
| '''03'''
| Mode
| -
| colspan="3" | Buffer address
| colspan="2" | Record number
| colspan="2" | Record length
| Memory
| colspan="3" | Number of bytes to write
| -
| Name length
| Name
|-
|}

Use the '''Record number''' field to specify the desired record in '''fixed record length''' files. This is not available for variable length record files.

The '''Record Length''' must match the length of the records as specified by [[#OPEN | OPEN]].

The '''Memory''' flag determines whether the data written from CPU (0) or VDP (not 0) memory.

After the WRITE operation has completed, the PAB delivers information about the result:

'''OUT'''

{| class="plainc" style="margin-left:1%"
|-
! width="4%" | 00
! width="4%" | 01
! width="4%" | 02
! width="4%" | 03
! width="4%" | 04
! width="4%" | 05
! width="4%" | 06
! width="4%" | 07
! width="4%" | 08
! width="4%" | 09
! width="4%" | 0A
! width="4%" | 0B
! width="4%" | 0C
! width="4%" | 0D
! width="4%" | 0E
! width="4%" | 0F
! width="4%" | 10 ...
|-
| -
| -
| Error code
| colspan="3" | -
| colspan="2" | Next record number
| colspan="2" | -
| -
| colspan="3" | Number of read bytes
| -
| Name length
| Name
|}

'''Next record number''' applies for fixed record length files only.

<div style="margin-bottom:6em"></div>

=== RESTORE ===

<div style="margin-bottom:6em"></div>

=== LOAD ===

<div style="margin-bottom:6em"></div>

=== SAVE ===

<div style="margin-bottom:6em"></div>

=== DELETE ===

<div style="margin-bottom:6em"></div>

=== SCRATCH ===

<div style="margin-bottom:6em"></div>

=== STATUS ===

<div style="margin-bottom:6em"></div>

=== BREAD ===

Reads a sector from a file or from a device. This is a level-2 operation, that is, it accesses the device based on sector addressing (or sectors of a file). BREAD allows for two operations:

* Read sectors from a file.
* Read sectors from a device.

'''IN'''

{| class="plainc" style="margin-left:1%"
|-
! width="4%" | 00
! width="4%" | 01
! width="4%" | 02
! width="4%" | 03
! width="4%" | 04
! width="4%" | 05
! width="4%" | 06
! width="4%" | 07
! width="4%" | 08
! width="4%" | 09
! width="4%" | 0A
! width="4%" | 0B
! width="4%" | 0C
! width="4%" | 0D
! width="4%" | 0E
! width="4%" | 0F
! width="4%" | 10 ...
|-
| '''0A'''
| -
| -
| colspan="3" | Buffer address
| colspan="2" | Sector offset LSW
| colspan="2" | -
| CPU / VDP
| -
| colspan="2" | Number of sectors
| Sector offset MSB
| Name length
| Name
|-
|}

The sector offset is defined by byte 0E as the most significant byte (value*65536) plus the word in bytes 06 and 07.

Byte 0A specifies whether the buffer address belongs to the CPU (0) or the VDP (non-zero) address space.

'''Read from file''': When a file is addressed, the operation reads a sequence of sectors from the file. The '''Sector offset''' is the number of the first sector of the file, counting from 0. The physical locations of the sectors are subject to the sector allocation on the device.

'''Read from device''': When a device is addressed, the operation reads a sequence of sectors from the device. The '''Sector offset''' is the physical sector number.

After the BREAD operation has completed, the PAB delivers information about the result:

'''OUT'''

{| class="plainc" style="margin-left:1%"
|-
! width="4%" | 00
! width="4%" | 01
! width="4%" | 02
! width="4%" | 03
! width="4%" | 04
! width="4%" | 05
! width="4%" | 06
! width="4%" | 07
! width="4%" | 08
! width="4%" | 09
! width="4%" | 0A
! width="4%" | 0B
! width="4%" | 0C
! width="4%" | 0D
! width="4%" | 0E
! width="4%" | 0F
! width="4%" | 10 ...
|-
| -
| -
| Error code
| colspan="3" | Updated buffer address
| colspan="2" | Updated sector offset LSW
| colspan="2" | -
| -
| -
| colspan="2" | Remaining sectors
| Updated sector offset MSB
| -
| -
|-
|}

The '''Updated buffer address''' points to the memory address after the sectors were read (e.g. when 4 sectors are read, the pointer is increased by 4*256 = 1024).

The '''Updated sector offset''' is the first sector that has not been read due to an error condition.

The '''Remaining sectors''' is the number of unread sectors due to an error condition.

=== BWRITE ===

Writes a sector to a file or to a device. This is a level-2 operation, that is, it accesses the device based on sector addressing (or sectors of a file). BWRITE allows for three operations:

* Create a new, empty file.
* Write sectors to a file.
* Write sectors to a device.

'''IN'''

{| class="plainc" style="margin-left:1%"
|-
! width="4%" | 00
! width="4%" | 01
! width="4%" | 02
! width="4%" | 03
! width="4%" | 04
! width="4%" | 05
! width="4%" | 06
! width="4%" | 07
! width="4%" | 08
! width="4%" | 09
! width="4%" | 0A
! width="4%" | 0B
! width="4%" | 0C
! width="4%" | 0D
! width="4%" | 0E
! width="4%" | 0F
! width="4%" | 10 ...
|-
| '''0B'''
| -
| -
| colspan="3" | Buffer address
| colspan="2" | Sector offset
| colspan="2" | -
| -
| colspan="3" | Number of sectors
| -
| Name length
| Name
|-
|}

'''Create a file''': When a file is addressed, and the number of sectors is 0, a new file is created. The contents of the file should be written by BWRITE on the same file with a sector count greater than 0.

'''Write to file''': When a file is addressed, the operation writes a sequence of sectors to the file. The '''Sector offset''' is the number of the first sector of the file, counting from 0. The physical locations of the sectors are subject to the sector allocation on the device; in particular, when fragmentation is required, the sectors are written to the new fragment.

'''Writing to device''': When a device is addressed, the operation writes a sequence of sectors to the device. The '''Sector offset''' is the physical sector number.

After the BWRITE operation has completed, the PAB delivers information about the result:

'''OUT'''

{| class="plainc" style="margin-left:1%"
|-
! width="4%" | 00
! width="4%" | 01
! width="4%" | 02
! width="4%" | 03
! width="4%" | 04
! width="4%" | 05
! width="4%" | 06
! width="4%" | 07
! width="4%" | 08
! width="4%" | 09
! width="4%" | 0A
! width="4%" | 0B
! width="4%" | 0C
! width="4%" | 0D
! width="4%" | 0E
! width="4%" | 0F
! width="4%" | 10 ...
|-
| -
| -
| Error code
| colspan="3" | Updated buffer address
| colspan="2" | Next unwritten sector
| colspan="2" | -
| -
| 0
| colspan="2" | Number of unwritten sectors
| -
| Name length
| Name
|-
|}

The '''Updated buffer address''' points to the memory address after the sectors were written (e.g. when 4 sectors are written, the pointer is increased by 4*256 = 1024).

The '''Next unwritten sector''' is the first sector that has not been written due to an error condition.

The '''Number of unwritten sectors''' is the number of unwritten sectors due to an error condition.

<div class="warn">Unless you want to write directly to the device, make sure that the PAB contains a file name that points to a file, not to a device. For example, when the file name has been created by the program, and for some reason the file name is empty (like "HDS1."), the following write operation will overwrite the volume information block and the allocation tables and '''destroy the target device filesystem'''.</div>

Tick here: [ ] Yes, I fully understood the danger of this operation.

(The author lost a complete hard disk by this incident, and was lucky to have a backup.)

<div style="margin-bottom:6em"></div>

=== PROTECT ===

<div style="margin-bottom:6em"></div>

=== RENAME ===

<div style="margin-bottom:6em"></div>

=== FORMAT ===

GeneveOS Device Operation

2022-04-24T18:01:59Z

Mizapf: /* BREAD */

Accessing devices (floppy disk, hard disk, serial connector, printer) is possible in GeneveOS via XOP calls.

== User-task XOPs ==

User-task XOPs are available for use in application programs. Here is a typical example:

PABADD EQU >F180
FILE DATA 8
...
LI R0,PABADD
XOP @FILE,0
MOVB @PABADD+2,R0
JNE ERROR
...

Similar as with the TI-99/4A device service routine concept (DSR), a Peripheral Access Block (PAB) must be set up prior to invoking the XOP.

=== Device Service Routine Call ===

{| class="xoparg"
|-
|
! Input !! Output
|-
| R0
| Pointer to PAB || -
|-
|}

The actual operation is contained in the Peripheral Access Block (PAB).

=== Peripheral Access Block ===

While the TI-99/4A DSRs expect the PAB to be stored in VDP RAM, the Geneve OS DSRs use CPU RAM for the PAB, which means the PAB need not be copied to the video RAM before use. Also, you can choose to have the I/O buffers in VDP or CPU RAM.

The general layout of the PAB is as follows:

{| class="plainc" style="margin-left:1%"
|-
! width="5%" | 00
! width="5%" | 01
! width="5%" | 02
! width="5%" | 03
! width="5%" | 04
! width="5%" | 05
! width="5%" | 06
! width="5%" | 07
! width="5%" | 08
! width="5%" | 09
! width="5%" | 0A
! width="5%" | 0B
! width="5%" | 0C
! width="5%" | 0D
! width="5%" | 0E
! width="5%" | 0F
! width="5%" | 10 ...
|-
| Opcode
| Mode
| Error code
| colspan="3" | Buffer address
| colspan="2" | Record number
| colspan="2" | Record length
| Memory type
| colspan="3" | Character count
| Status byte
| Name length
| Name
|-
|}

Note that the buffer addresses are 21-bit wide, represented by the [[MDOS Memory Management Functions#Local_.28virtual.29_pages | virtual address]] within the calling task. The address for this buffer should be derived from [[MDOS Memory Management Functions | memory allocation]] operations that were invoked earlier.

After the operation, the PAB contains information about the results of the operation.

=== Mode ===

The mode bits are used to determine the operation direction (in/out/update/append), the encoding (display/internal), the structure (fixed/variable) and the access (sequential/relative).

{| class="plainbits" style="width:64%"
! 0
! 1
! 2
! 3
! 4
! 5
! 6
! 7
|-
| style="width:24%" rowspan="4" colspan="3" | Unused (000)
| style="width:8%" rowspan="2" | Fixed=0
| style="width:8%" rowspan="2" | Display=0
| style="width:16%" colspan="2" | Update=00
| style="width:8%" rowspan="2" | Sequential=0
|-
| colspan="2" | Output=01
|-
| rowspan="2" | Variable=1
| rowspan="2" | Internal=1
| colspan="2" | Input=10
| rowspan="2" | Relative=1
|-
| colspan="2" | Append=11
|}

=== Error code ===

The error code is an eight bit word with the following structure:

{| class="plainbits" style="float:left"
! 0
! 1
! 2
! 3
! 4
! 5
! 6
! 7
|-
| colspan="3" | Number
| colspan="5" | Detail code for error 7
|}

{| class="plainc" style="float:left"
! Number
! Meaning
|-
| 0
| No such device
|-
| 1
| Write-protected
|-
| 2
| Illegal open attribute
|-
| 3
| Illegal operation
|-
| 4
| Out of buffer space
|-
| 5
| Read beyond EOF
|-
| 6
| Device error
|-
| 7
| File error
|}

<div style="clear:both"></div>

== Operations ==

=== OPEN ===

Open a record-oriented file. A file must be opened before it can be read from or written to. This operation is not required for flat memory image files.

The PAB must be set up prior to invoking the operation:

'''IN'''

{| class="plainc" style="margin-left:1%"
|-
! width="4%" | 00
! width="4%" | 01
! width="4%" | 02
! width="4%" | 03
! width="4%" | 04
! width="4%" | 05
! width="4%" | 06
! width="4%" | 07
! width="4%" | 08
! width="4%" | 09
! width="4%" | 0A
! width="4%" | 0B
! width="4%" | 0C
! width="4%" | 0D
! width="4%" | 0E
! width="4%" | 0F
! width="4%" | 10 ...
|-
| '''00'''
| Mode
| -
| colspan="3" | -
| colspan="2" | Records to reserve
| colspan="2" | Record length
| -
| colspan="3" | -
| -
| Name length
| Name
|-
|}

'''Open new file''': The '''Record Length''' must be set to a value greater than 0. This will become the length of the records of the new file.

'''Open existing file''': The '''Record Length''' must match the length of the records. If the length is unknown, 0 may be passed.

After the OPEN operation has completed, the PAB delivers information about the result:

'''OUT'''

{| class="plainc" style="margin-left:1%"
|-
! width="4%" | 00
! width="4%" | 01
! width="4%" | 02
! width="4%" | 03
! width="4%" | 04
! width="4%" | 05
! width="4%" | 06
! width="4%" | 07
! width="4%" | 08
! width="4%" | 09
! width="4%" | 0A
! width="4%" | 0B
! width="4%" | 0C
! width="4%" | 0D
! width="4%" | 0E
! width="4%" | 0F
! width="4%" | 10 ...
|-
| -
| -
| Error code
| colspan="3" | -
| colspan="2" | -
| colspan="2" | Actual Record Length
| -
| 0
| colspan="2" | True Record Length
| -
| Name length
| Name
|-
|}

The '''Actual Record Length''' is the length of the records of the existing file. When 0 was passed on the call, this delivers the record length of the file; otherwise this is the value that was passed for the call. The '''True Record Length''' is the record length of the file when it already exists.

<div style="margin-bottom:6em"></div>

=== CLOSE ===

Closes a record-oriented file. A file must be closed after being used. After closing, no further read or write operations may be invoked on the file. This operation is not required for flat memory image files.

The PAB must be set up prior to invoking the operation:

'''IN'''

{| class="plainc" style="margin-left:1%"
|-
! width="4%" | 00
! width="4%" | 01
! width="4%" | 02
! width="4%" | 03
! width="4%" | 04
! width="4%" | 05
! width="4%" | 06
! width="4%" | 07
! width="4%" | 08
! width="4%" | 09
! width="4%" | 0A
! width="4%" | 0B
! width="4%" | 0C
! width="4%" | 0D
! width="4%" | 0E
! width="4%" | 0F
! width="4%" | 10 ...
|-
| '''01'''
| Mode
| -
| colspan="3" | -
| colspan="2" | -
| colspan="2" | -
| -
| colspan="3" | -
| -
| Name length
| Name
|-
|}

After the CLOSE operation has completed, the PAB delivers information about the result:

'''OUT'''

{| class="plainc" style="margin-left:1%"
|-
! width="4%" | 00
! width="4%" | 01
! width="4%" | 02
! width="4%" | 03
! width="4%" | 04
! width="4%" | 05
! width="4%" | 06
! width="4%" | 07
! width="4%" | 08
! width="4%" | 09
! width="4%" | 0A
! width="4%" | 0B
! width="4%" | 0C
! width="4%" | 0D
! width="4%" | 0E
! width="4%" | 0F
! width="4%" | 10 ...
|-
| -
| -
| Error code
| colspan="3" | -
| colspan="2" | -
| colspan="2" | -
| -
| colspan="3" | -
| -
| Name length
| Name
|-
|}

<div style="margin-bottom:6em"></div>

=== READ ===

Reads a record from a record-oriented file. For flat memory image files, [[#LOAD | LOAD]] must be used.

'''IN'''

{| class="plainc" style="margin-left:1%"
|-
! width="4%" | 00
! width="4%" | 01
! width="4%" | 02
! width="4%" | 03
! width="4%" | 04
! width="4%" | 05
! width="4%" | 06
! width="4%" | 07
! width="4%" | 08
! width="4%" | 09
! width="4%" | 0A
! width="4%" | 0B
! width="4%" | 0C
! width="4%" | 0D
! width="4%" | 0E
! width="4%" | 0F
! width="4%" | 10 ...
|-
| '''02'''
| Mode
| -
| colspan="3" | Buffer address
| colspan="2" | Record number
| colspan="2" | Record length
| Memory
| colspan="3" | -
| -
| Name length
| Name
|-
|}

Use the '''Record number''' field to specify the desired record in '''fixed record length''' files. This is not available for variable length record files.

The '''Record Length''' must match the length of the records as specified by [[#OPEN | OPEN]].

The '''Memory''' flag determines whether the data are read into CPU (0) or VDP (not 0) memory.

After the READ operation has completed, the PAB delivers information about the result:

'''OUT'''

{| class="plainc" style="margin-left:1%"
|-
! width="4%" | 00
! width="4%" | 01
! width="4%" | 02
! width="4%" | 03
! width="4%" | 04
! width="4%" | 05
! width="4%" | 06
! width="4%" | 07
! width="4%" | 08
! width="4%" | 09
! width="4%" | 0A
! width="4%" | 0B
! width="4%" | 0C
! width="4%" | 0D
! width="4%" | 0E
! width="4%" | 0F
! width="4%" | 10 ...
|-
| -
| -
| Error code
| colspan="3" | -
| colspan="2" | Next record number
| colspan="2" | -
| -
| colspan="3" | Number of read bytes
| -
| Name length
| Name
|}

'''Next record number''' applies for fixed record length files only.

<div style="margin-bottom:6em"></div>

=== WRITE ===

Writes a record to a record-oriented file. For flat memory image files, [[#SAVE | SAVE]] must be used.

'''IN'''

{| class="plainc" style="margin-left:1%"
|-
! width="4%" | 00
! width="4%" | 01
! width="4%" | 02
! width="4%" | 03
! width="4%" | 04
! width="4%" | 05
! width="4%" | 06
! width="4%" | 07
! width="4%" | 08
! width="4%" | 09
! width="4%" | 0A
! width="4%" | 0B
! width="4%" | 0C
! width="4%" | 0D
! width="4%" | 0E
! width="4%" | 0F
! width="4%" | 10 ...
|-
| '''03'''
| Mode
| -
| colspan="3" | Buffer address
| colspan="2" | Record number
| colspan="2" | Record length
| Memory
| colspan="3" | Number of bytes to write
| -
| Name length
| Name
|-
|}

Use the '''Record number''' field to specify the desired record in '''fixed record length''' files. This is not available for variable length record files.

The '''Record Length''' must match the length of the records as specified by [[#OPEN | OPEN]].

The '''Memory''' flag determines whether the data written from CPU (0) or VDP (not 0) memory.

After the WRITE operation has completed, the PAB delivers information about the result:

'''OUT'''

{| class="plainc" style="margin-left:1%"
|-
! width="4%" | 00
! width="4%" | 01
! width="4%" | 02
! width="4%" | 03
! width="4%" | 04
! width="4%" | 05
! width="4%" | 06
! width="4%" | 07
! width="4%" | 08
! width="4%" | 09
! width="4%" | 0A
! width="4%" | 0B
! width="4%" | 0C
! width="4%" | 0D
! width="4%" | 0E
! width="4%" | 0F
! width="4%" | 10 ...
|-
| -
| -
| Error code
| colspan="3" | -
| colspan="2" | Next record number
| colspan="2" | -
| -
| colspan="3" | Number of read bytes
| -
| Name length
| Name
|}

'''Next record number''' applies for fixed record length files only.

<div style="margin-bottom:6em"></div>

=== RESTORE ===

<div style="margin-bottom:6em"></div>

=== LOAD ===

<div style="margin-bottom:6em"></div>

=== SAVE ===

<div style="margin-bottom:6em"></div>

=== DELETE ===

<div style="margin-bottom:6em"></div>

=== SCRATCH ===

<div style="margin-bottom:6em"></div>

=== STATUS ===

<div style="margin-bottom:6em"></div>

=== BREAD ===

Reads a sector from a file or from a device. This is a level-2 operation, that is, it accesses the device based on sector addressing (or sectors of a file). BREAD allows for two operations:

* Read sectors from a file.
* Read sectors from a device.

'''IN'''

{| class="plainc" style="margin-left:1%"
|-
! width="4%" | 00
! width="4%" | 01
! width="4%" | 02
! width="4%" | 03
! width="4%" | 04
! width="4%" | 05
! width="4%" | 06
! width="4%" | 07
! width="4%" | 08
! width="4%" | 09
! width="4%" | 0A
! width="4%" | 0B
! width="4%" | 0C
! width="4%" | 0D
! width="4%" | 0E
! width="4%" | 0F
! width="4%" | 10 ...
|-
| '''0A'''
| -
| -
| colspan="3" | Buffer address
| colspan="2" | Sector offset LSW
| colspan="2" | -
| CPU/VDP
| -
| colspan="2" | Number of sectors
| Sector offset MSB
| Name length
| Name
|-
|}

The sector offset is defined by byte 0E as the most significant byte (value*65536) plus the word in bytes 06 and 07.

Byte 0A specifies whether the buffer address belongs to the CPU (0) or the VDP (non-zero) address space.

'''Read from file''': When a file is addressed, the operation reads a sequence of sectors from the file. The '''Sector offset''' is the number of the first sector of the file, counting from 0. The physical locations of the sectors are subject to the sector allocation on the device.

'''Read from device''': When a device is addressed, the operation reads a sequence of sectors from the device. The '''Sector offset''' is the physical sector number.

After the BREAD operation has completed, the PAB delivers information about the result:

'''OUT'''

{| class="plainc" style="margin-left:1%"
|-
! width="4%" | 00
! width="4%" | 01
! width="4%" | 02
! width="4%" | 03
! width="4%" | 04
! width="4%" | 05
! width="4%" | 06
! width="4%" | 07
! width="4%" | 08
! width="4%" | 09
! width="4%" | 0A
! width="4%" | 0B
! width="4%" | 0C
! width="4%" | 0D
! width="4%" | 0E
! width="4%" | 0F
! width="4%" | 10 ...
|-
| -
| -
| Error code
| colspan="3" | Updated buffer address
| colspan="2" | Updated sector offset LSW
| colspan="2" | -
| -
| -
| colspan="2" | Remaining sectors
| Updated sector offset MSB
| -
| -
|-
|}

The '''Updated buffer address''' points to the memory address after the sectors were written (e.g. when 4 sectors are written, the pointer is increased by 4*256 = 1024).

The '''Next unwritten sector''' is the first sector that has not been written due to an error condition.

The '''Number of unwritten sectors''' is the number of unwritten sectors due to an error condition.

=== BWRITE ===

Writes a sector to a file or to a device. This is a level-2 operation, that is, it accesses the device based on sector addressing (or sectors of a file). BWRITE allows for three operations:

* Create a new, empty file.
* Write sectors to a file.
* Write sectors to a device.

'''IN'''

{| class="plainc" style="margin-left:1%"
|-
! width="4%" | 00
! width="4%" | 01
! width="4%" | 02
! width="4%" | 03
! width="4%" | 04
! width="4%" | 05
! width="4%" | 06
! width="4%" | 07
! width="4%" | 08
! width="4%" | 09
! width="4%" | 0A
! width="4%" | 0B
! width="4%" | 0C
! width="4%" | 0D
! width="4%" | 0E
! width="4%" | 0F
! width="4%" | 10 ...
|-
| '''0B'''
| -
| -
| colspan="3" | Buffer address
| colspan="2" | Sector offset
| colspan="2" | -
| -
| colspan="3" | Number of sectors
| -
| Name length
| Name
|-
|}

'''Create a file''': When a file is addressed, and the number of sectors is 0, a new file is created. The contents of the file should be written by BWRITE on the same file with a sector count greater than 0.

'''Write to file''': When a file is addressed, the operation writes a sequence of sectors to the file. The '''Sector offset''' is the number of the first sector of the file, counting from 0. The physical locations of the sectors are subject to the sector allocation on the device; in particular, when fragmentation is required, the sectors are written to the new fragment.

'''Writing to device''': When a device is addressed, the operation writes a sequence of sectors to the device. The '''Sector offset''' is the physical sector number.

After the BWRITE operation has completed, the PAB delivers information about the result:

'''OUT'''

{| class="plainc" style="margin-left:1%"
|-
! width="4%" | 00
! width="4%" | 01
! width="4%" | 02
! width="4%" | 03
! width="4%" | 04
! width="4%" | 05
! width="4%" | 06
! width="4%" | 07
! width="4%" | 08
! width="4%" | 09
! width="4%" | 0A
! width="4%" | 0B
! width="4%" | 0C
! width="4%" | 0D
! width="4%" | 0E
! width="4%" | 0F
! width="4%" | 10 ...
|-
| -
| -
| Error code
| colspan="3" | Updated buffer address
| colspan="2" | Next unwritten sector
| colspan="2" | -
| -
| 0
| colspan="2" | Number of unwritten sectors
| -
| Name length
| Name
|-
|}

The '''Updated buffer address''' points to the memory address after the sectors were written (e.g. when 4 sectors are written, the pointer is increased by 4*256 = 1024).

The '''Next unwritten sector''' is the first sector that has not been written due to an error condition.

The '''Number of unwritten sectors''' is the number of unwritten sectors due to an error condition.

<div class="warn">Unless you want to write directly to the device, make sure that the PAB contains a file name that points to a file, not to a device. For example, when the file name has been created by the program, and for some reason the file name is empty (like "HDS1."), the following write operation will overwrite the volume information block and the allocation tables and '''destroy the target device filesystem'''.</div>

Tick here: [ ] Yes, I fully understood the danger of this operation.

(The author lost a complete hard disk by this incident, and was lucky to have a backup.)

<div style="margin-bottom:6em"></div>

=== PROTECT ===

<div style="margin-bottom:6em"></div>

=== RENAME ===

<div style="margin-bottom:6em"></div>

=== FORMAT ===

GeneveOS Device Operation

2022-04-24T17:42:08Z

Mizapf: /* BREAD */

Accessing devices (floppy disk, hard disk, serial connector, printer) is possible in GeneveOS via XOP calls.

== User-task XOPs ==

User-task XOPs are available for use in application programs. Here is a typical example:

PABADD EQU >F180
FILE DATA 8
...
LI R0,PABADD
XOP @FILE,0
MOVB @PABADD+2,R0
JNE ERROR
...

Similar as with the TI-99/4A device service routine concept (DSR), a Peripheral Access Block (PAB) must be set up prior to invoking the XOP.

=== Device Service Routine Call ===

{| class="xoparg"
|-
|
! Input !! Output
|-
| R0
| Pointer to PAB || -
|-
|}

The actual operation is contained in the Peripheral Access Block (PAB).

=== Peripheral Access Block ===

While the TI-99/4A DSRs expect the PAB to be stored in VDP RAM, the Geneve OS DSRs use CPU RAM for the PAB, which means the PAB need not be copied to the video RAM before use. Also, you can choose to have the I/O buffers in VDP or CPU RAM.

The general layout of the PAB is as follows:

{| class="plainc" style="margin-left:1%"
|-
! width="5%" | 00
! width="5%" | 01
! width="5%" | 02
! width="5%" | 03
! width="5%" | 04
! width="5%" | 05
! width="5%" | 06
! width="5%" | 07
! width="5%" | 08
! width="5%" | 09
! width="5%" | 0A
! width="5%" | 0B
! width="5%" | 0C
! width="5%" | 0D
! width="5%" | 0E
! width="5%" | 0F
! width="5%" | 10 ...
|-
| Opcode
| Mode
| Error code
| colspan="3" | Buffer address
| colspan="2" | Record number
| colspan="2" | Record length
| Memory type
| colspan="3" | Character count
| Status byte
| Name length
| Name
|-
|}

Note that the buffer addresses are 21-bit wide, represented by the [[MDOS Memory Management Functions#Local_.28virtual.29_pages | virtual address]] within the calling task. The address for this buffer should be derived from [[MDOS Memory Management Functions | memory allocation]] operations that were invoked earlier.

After the operation, the PAB contains information about the results of the operation.

=== Mode ===

The mode bits are used to determine the operation direction (in/out/update/append), the encoding (display/internal), the structure (fixed/variable) and the access (sequential/relative).

{| class="plainbits" style="width:64%"
! 0
! 1
! 2
! 3
! 4
! 5
! 6
! 7
|-
| style="width:24%" rowspan="4" colspan="3" | Unused (000)
| style="width:8%" rowspan="2" | Fixed=0
| style="width:8%" rowspan="2" | Display=0
| style="width:16%" colspan="2" | Update=00
| style="width:8%" rowspan="2" | Sequential=0
|-
| colspan="2" | Output=01
|-
| rowspan="2" | Variable=1
| rowspan="2" | Internal=1
| colspan="2" | Input=10
| rowspan="2" | Relative=1
|-
| colspan="2" | Append=11
|}

=== Error code ===

The error code is an eight bit word with the following structure:

{| class="plainbits" style="float:left"
! 0
! 1
! 2
! 3
! 4
! 5
! 6
! 7
|-
| colspan="3" | Number
| colspan="5" | Detail code for error 7
|}

{| class="plainc" style="float:left"
! Number
! Meaning
|-
| 0
| No such device
|-
| 1
| Write-protected
|-
| 2
| Illegal open attribute
|-
| 3
| Illegal operation
|-
| 4
| Out of buffer space
|-
| 5
| Read beyond EOF
|-
| 6
| Device error
|-
| 7
| File error
|}

<div style="clear:both"></div>

== Operations ==

=== OPEN ===

Open a record-oriented file. A file must be opened before it can be read from or written to. This operation is not required for flat memory image files.

The PAB must be set up prior to invoking the operation:

'''IN'''

{| class="plainc" style="margin-left:1%"
|-
! width="4%" | 00
! width="4%" | 01
! width="4%" | 02
! width="4%" | 03
! width="4%" | 04
! width="4%" | 05
! width="4%" | 06
! width="4%" | 07
! width="4%" | 08
! width="4%" | 09
! width="4%" | 0A
! width="4%" | 0B
! width="4%" | 0C
! width="4%" | 0D
! width="4%" | 0E
! width="4%" | 0F
! width="4%" | 10 ...
|-
| '''00'''
| Mode
| -
| colspan="3" | -
| colspan="2" | Records to reserve
| colspan="2" | Record length
| -
| colspan="3" | -
| -
| Name length
| Name
|-
|}

'''Open new file''': The '''Record Length''' must be set to a value greater than 0. This will become the length of the records of the new file.

'''Open existing file''': The '''Record Length''' must match the length of the records. If the length is unknown, 0 may be passed.

After the OPEN operation has completed, the PAB delivers information about the result:

'''OUT'''

{| class="plainc" style="margin-left:1%"
|-
! width="4%" | 00
! width="4%" | 01
! width="4%" | 02
! width="4%" | 03
! width="4%" | 04
! width="4%" | 05
! width="4%" | 06
! width="4%" | 07
! width="4%" | 08
! width="4%" | 09
! width="4%" | 0A
! width="4%" | 0B
! width="4%" | 0C
! width="4%" | 0D
! width="4%" | 0E
! width="4%" | 0F
! width="4%" | 10 ...
|-
| -
| -
| Error code
| colspan="3" | -
| colspan="2" | -
| colspan="2" | Actual Record Length
| -
| 0
| colspan="2" | True Record Length
| -
| Name length
| Name
|-
|}

The '''Actual Record Length''' is the length of the records of the existing file. When 0 was passed on the call, this delivers the record length of the file; otherwise this is the value that was passed for the call. The '''True Record Length''' is the record length of the file when it already exists.

<div style="margin-bottom:6em"></div>

=== CLOSE ===

Closes a record-oriented file. A file must be closed after being used. After closing, no further read or write operations may be invoked on the file. This operation is not required for flat memory image files.

The PAB must be set up prior to invoking the operation:

'''IN'''

{| class="plainc" style="margin-left:1%"
|-
! width="4%" | 00
! width="4%" | 01
! width="4%" | 02
! width="4%" | 03
! width="4%" | 04
! width="4%" | 05
! width="4%" | 06
! width="4%" | 07
! width="4%" | 08
! width="4%" | 09
! width="4%" | 0A
! width="4%" | 0B
! width="4%" | 0C
! width="4%" | 0D
! width="4%" | 0E
! width="4%" | 0F
! width="4%" | 10 ...
|-
| '''01'''
| Mode
| -
| colspan="3" | -
| colspan="2" | -
| colspan="2" | -
| -
| colspan="3" | -
| -
| Name length
| Name
|-
|}

After the CLOSE operation has completed, the PAB delivers information about the result:

'''OUT'''

{| class="plainc" style="margin-left:1%"
|-
! width="4%" | 00
! width="4%" | 01
! width="4%" | 02
! width="4%" | 03
! width="4%" | 04
! width="4%" | 05
! width="4%" | 06
! width="4%" | 07
! width="4%" | 08
! width="4%" | 09
! width="4%" | 0A
! width="4%" | 0B
! width="4%" | 0C
! width="4%" | 0D
! width="4%" | 0E
! width="4%" | 0F
! width="4%" | 10 ...
|-
| -
| -
| Error code
| colspan="3" | -
| colspan="2" | -
| colspan="2" | -
| -
| colspan="3" | -
| -
| Name length
| Name
|-
|}

<div style="margin-bottom:6em"></div>

=== READ ===

Reads a record from a record-oriented file. For flat memory image files, [[#LOAD | LOAD]] must be used.

'''IN'''

{| class="plainc" style="margin-left:1%"
|-
! width="4%" | 00
! width="4%" | 01
! width="4%" | 02
! width="4%" | 03
! width="4%" | 04
! width="4%" | 05
! width="4%" | 06
! width="4%" | 07
! width="4%" | 08
! width="4%" | 09
! width="4%" | 0A
! width="4%" | 0B
! width="4%" | 0C
! width="4%" | 0D
! width="4%" | 0E
! width="4%" | 0F
! width="4%" | 10 ...
|-
| '''02'''
| Mode
| -
| colspan="3" | Buffer address
| colspan="2" | Record number
| colspan="2" | Record length
| Memory
| colspan="3" | -
| -
| Name length
| Name
|-
|}

Use the '''Record number''' field to specify the desired record in '''fixed record length''' files. This is not available for variable length record files.

The '''Record Length''' must match the length of the records as specified by [[#OPEN | OPEN]].

The '''Memory''' flag determines whether the data are read into CPU (0) or VDP (not 0) memory.

After the READ operation has completed, the PAB delivers information about the result:

'''OUT'''

{| class="plainc" style="margin-left:1%"
|-
! width="4%" | 00
! width="4%" | 01
! width="4%" | 02
! width="4%" | 03
! width="4%" | 04
! width="4%" | 05
! width="4%" | 06
! width="4%" | 07
! width="4%" | 08
! width="4%" | 09
! width="4%" | 0A
! width="4%" | 0B
! width="4%" | 0C
! width="4%" | 0D
! width="4%" | 0E
! width="4%" | 0F
! width="4%" | 10 ...
|-
| -
| -
| Error code
| colspan="3" | -
| colspan="2" | Next record number
| colspan="2" | -
| -
| colspan="3" | Number of read bytes
| -
| Name length
| Name
|}

'''Next record number''' applies for fixed record length files only.

<div style="margin-bottom:6em"></div>

=== WRITE ===

Writes a record to a record-oriented file. For flat memory image files, [[#SAVE | SAVE]] must be used.

'''IN'''

{| class="plainc" style="margin-left:1%"
|-
! width="4%" | 00
! width="4%" | 01
! width="4%" | 02
! width="4%" | 03
! width="4%" | 04
! width="4%" | 05
! width="4%" | 06
! width="4%" | 07
! width="4%" | 08
! width="4%" | 09
! width="4%" | 0A
! width="4%" | 0B
! width="4%" | 0C
! width="4%" | 0D
! width="4%" | 0E
! width="4%" | 0F
! width="4%" | 10 ...
|-
| '''03'''
| Mode
| -
| colspan="3" | Buffer address
| colspan="2" | Record number
| colspan="2" | Record length
| Memory
| colspan="3" | Number of bytes to write
| -
| Name length
| Name
|-
|}

Use the '''Record number''' field to specify the desired record in '''fixed record length''' files. This is not available for variable length record files.

The '''Record Length''' must match the length of the records as specified by [[#OPEN | OPEN]].

The '''Memory''' flag determines whether the data written from CPU (0) or VDP (not 0) memory.

After the WRITE operation has completed, the PAB delivers information about the result:

'''OUT'''

{| class="plainc" style="margin-left:1%"
|-
! width="4%" | 00
! width="4%" | 01
! width="4%" | 02
! width="4%" | 03
! width="4%" | 04
! width="4%" | 05
! width="4%" | 06
! width="4%" | 07
! width="4%" | 08
! width="4%" | 09
! width="4%" | 0A
! width="4%" | 0B
! width="4%" | 0C
! width="4%" | 0D
! width="4%" | 0E
! width="4%" | 0F
! width="4%" | 10 ...
|-
| -
| -
| Error code
| colspan="3" | -
| colspan="2" | Next record number
| colspan="2" | -
| -
| colspan="3" | Number of read bytes
| -
| Name length
| Name
|}

'''Next record number''' applies for fixed record length files only.

<div style="margin-bottom:6em"></div>

=== RESTORE ===

<div style="margin-bottom:6em"></div>

=== LOAD ===

<div style="margin-bottom:6em"></div>

=== SAVE ===

<div style="margin-bottom:6em"></div>

=== DELETE ===

<div style="margin-bottom:6em"></div>

=== SCRATCH ===

<div style="margin-bottom:6em"></div>

=== STATUS ===

<div style="margin-bottom:6em"></div>

=== BREAD ===

Reads a sector from a file or from a device. This is a level-2 operation, that is, it accesses the device based on sector addressing (or sectors of a file). BREAD allows for two operations:

* Read sectors from a file.
* Read sectors from a device.

'''IN'''

{| class="plainc" style="margin-left:1%"
|-
! width="4%" | 00
! width="4%" | 01
! width="4%" | 02
! width="4%" | 03
! width="4%" | 04
! width="4%" | 05
! width="4%" | 06
! width="4%" | 07
! width="4%" | 08
! width="4%" | 09
! width="4%" | 0A
! width="4%" | 0B
! width="4%" | 0C
! width="4%" | 0D
! width="4%" | 0E
! width="4%" | 0F
! width="4%" | 10 ...
|-
| '''0A'''
| -
| -
| colspan="3" | Buffer address
| colspan="2" | Sector offset
| colspan="2" | -
| -
| colspan="3" | Number of sectors
| -
| Name length
| Name
|-
|}

'''Read from file''': When a file is addressed, the operation reads a sequence of sectors from the file. The '''Sector offset''' is the number of the first sector of the file, counting from 0. The physical locations of the sectors are subject to the sector allocation on the device.

'''Read from device''': When a device is addressed, the operation reads a sequence of sectors from the device. The '''Sector offset''' is the physical sector number.

After the BREAD operation has completed, the PAB delivers information about the result:

'''OUT'''

{| class="plainc" style="margin-left:1%"
|-
! width="4%" | 00
! width="4%" | 01
! width="4%" | 02
! width="4%" | 03
! width="4%" | 04
! width="4%" | 05
! width="4%" | 06
! width="4%" | 07
! width="4%" | 08
! width="4%" | 09
! width="4%" | 0A
! width="4%" | 0B
! width="4%" | 0C
! width="4%" | 0D
! width="4%" | 0E
! width="4%" | 0F
! width="4%" | 10 ...
|-
| -
| -
| Error code
| colspan="3" | Updated buffer address
| colspan="2" | Next unwritten sector
| colspan="2" | -
| -
| 0
| colspan="2" | Number of unwritten sectors
| -
| Name length
| Name
|-
|}

The '''Updated buffer address''' points to the memory address after the sectors were written (e.g. when 4 sectors are written, the pointer is increased by 4*256 = 1024).

The '''Next unwritten sector''' is the first sector that has not been written due to an error condition.

The '''Number of unwritten sectors''' is the number of unwritten sectors due to an error condition.

=== BWRITE ===

Writes a sector to a file or to a device. This is a level-2 operation, that is, it accesses the device based on sector addressing (or sectors of a file). BWRITE allows for three operations:

* Create a new, empty file.
* Write sectors to a file.
* Write sectors to a device.

'''IN'''

{| class="plainc" style="margin-left:1%"
|-
! width="4%" | 00
! width="4%" | 01
! width="4%" | 02
! width="4%" | 03
! width="4%" | 04
! width="4%" | 05
! width="4%" | 06
! width="4%" | 07
! width="4%" | 08
! width="4%" | 09
! width="4%" | 0A
! width="4%" | 0B
! width="4%" | 0C
! width="4%" | 0D
! width="4%" | 0E
! width="4%" | 0F
! width="4%" | 10 ...
|-
| '''0B'''
| -
| -
| colspan="3" | Buffer address
| colspan="2" | Sector offset
| colspan="2" | -
| -
| colspan="3" | Number of sectors
| -
| Name length
| Name
|-
|}

'''Create a file''': When a file is addressed, and the number of sectors is 0, a new file is created. The contents of the file should be written by BWRITE on the same file with a sector count greater than 0.

'''Write to file''': When a file is addressed, the operation writes a sequence of sectors to the file. The '''Sector offset''' is the number of the first sector of the file, counting from 0. The physical locations of the sectors are subject to the sector allocation on the device; in particular, when fragmentation is required, the sectors are written to the new fragment.

'''Writing to device''': When a device is addressed, the operation writes a sequence of sectors to the device. The '''Sector offset''' is the physical sector number.

After the BWRITE operation has completed, the PAB delivers information about the result:

'''OUT'''

{| class="plainc" style="margin-left:1%"
|-
! width="4%" | 00
! width="4%" | 01
! width="4%" | 02
! width="4%" | 03
! width="4%" | 04
! width="4%" | 05
! width="4%" | 06
! width="4%" | 07
! width="4%" | 08
! width="4%" | 09
! width="4%" | 0A
! width="4%" | 0B
! width="4%" | 0C
! width="4%" | 0D
! width="4%" | 0E
! width="4%" | 0F
! width="4%" | 10 ...
|-
| -
| -
| Error code
| colspan="3" | Updated buffer address
| colspan="2" | Next unwritten sector
| colspan="2" | -
| -
| 0
| colspan="2" | Number of unwritten sectors
| -
| Name length
| Name
|-
|}

The '''Updated buffer address''' points to the memory address after the sectors were written (e.g. when 4 sectors are written, the pointer is increased by 4*256 = 1024).

The '''Next unwritten sector''' is the first sector that has not been written due to an error condition.

The '''Number of unwritten sectors''' is the number of unwritten sectors due to an error condition.

<div class="warn">Unless you want to write directly to the device, make sure that the PAB contains a file name that points to a file, not to a device. For example, when the file name has been created by the program, and for some reason the file name is empty (like "HDS1."), the following write operation will overwrite the volume information block and the allocation tables and '''destroy the target device filesystem'''.</div>

Tick here: [ ] Yes, I fully understood the danger of this operation.

(The author lost a complete hard disk by this incident, and was lucky to have a backup.)

<div style="margin-bottom:6em"></div>

=== PROTECT ===

<div style="margin-bottom:6em"></div>

=== RENAME ===

<div style="margin-bottom:6em"></div>

=== FORMAT ===

GeneveOS Device Operation

2022-04-24T17:40:35Z

Mizapf: /* BREAD */

Accessing devices (floppy disk, hard disk, serial connector, printer) is possible in GeneveOS via XOP calls.

== User-task XOPs ==

User-task XOPs are available for use in application programs. Here is a typical example:

PABADD EQU >F180
FILE DATA 8
...
LI R0,PABADD
XOP @FILE,0
MOVB @PABADD+2,R0
JNE ERROR
...

Similar as with the TI-99/4A device service routine concept (DSR), a Peripheral Access Block (PAB) must be set up prior to invoking the XOP.

=== Device Service Routine Call ===

{| class="xoparg"
|-
|
! Input !! Output
|-
| R0
| Pointer to PAB || -
|-
|}

The actual operation is contained in the Peripheral Access Block (PAB).

=== Peripheral Access Block ===

While the TI-99/4A DSRs expect the PAB to be stored in VDP RAM, the Geneve OS DSRs use CPU RAM for the PAB, which means the PAB need not be copied to the video RAM before use. Also, you can choose to have the I/O buffers in VDP or CPU RAM.

The general layout of the PAB is as follows:

{| class="plainc" style="margin-left:1%"
|-
! width="5%" | 00
! width="5%" | 01
! width="5%" | 02
! width="5%" | 03
! width="5%" | 04
! width="5%" | 05
! width="5%" | 06
! width="5%" | 07
! width="5%" | 08
! width="5%" | 09
! width="5%" | 0A
! width="5%" | 0B
! width="5%" | 0C
! width="5%" | 0D
! width="5%" | 0E
! width="5%" | 0F
! width="5%" | 10 ...
|-
| Opcode
| Mode
| Error code
| colspan="3" | Buffer address
| colspan="2" | Record number
| colspan="2" | Record length
| Memory type
| colspan="3" | Character count
| Status byte
| Name length
| Name
|-
|}

Note that the buffer addresses are 21-bit wide, represented by the [[MDOS Memory Management Functions#Local_.28virtual.29_pages | virtual address]] within the calling task. The address for this buffer should be derived from [[MDOS Memory Management Functions | memory allocation]] operations that were invoked earlier.

After the operation, the PAB contains information about the results of the operation.

=== Mode ===

The mode bits are used to determine the operation direction (in/out/update/append), the encoding (display/internal), the structure (fixed/variable) and the access (sequential/relative).

{| class="plainbits" style="width:64%"
! 0
! 1
! 2
! 3
! 4
! 5
! 6
! 7
|-
| style="width:24%" rowspan="4" colspan="3" | Unused (000)
| style="width:8%" rowspan="2" | Fixed=0
| style="width:8%" rowspan="2" | Display=0
| style="width:16%" colspan="2" | Update=00
| style="width:8%" rowspan="2" | Sequential=0
|-
| colspan="2" | Output=01
|-
| rowspan="2" | Variable=1
| rowspan="2" | Internal=1
| colspan="2" | Input=10
| rowspan="2" | Relative=1
|-
| colspan="2" | Append=11
|}

=== Error code ===

The error code is an eight bit word with the following structure:

{| class="plainbits" style="float:left"
! 0
! 1
! 2
! 3
! 4
! 5
! 6
! 7
|-
| colspan="3" | Number
| colspan="5" | Detail code for error 7
|}

{| class="plainc" style="float:left"
! Number
! Meaning
|-
| 0
| No such device
|-
| 1
| Write-protected
|-
| 2
| Illegal open attribute
|-
| 3
| Illegal operation
|-
| 4
| Out of buffer space
|-
| 5
| Read beyond EOF
|-
| 6
| Device error
|-
| 7
| File error
|}

<div style="clear:both"></div>

== Operations ==

=== OPEN ===

Open a record-oriented file. A file must be opened before it can be read from or written to. This operation is not required for flat memory image files.

The PAB must be set up prior to invoking the operation:

'''IN'''

{| class="plainc" style="margin-left:1%"
|-
! width="4%" | 00
! width="4%" | 01
! width="4%" | 02
! width="4%" | 03
! width="4%" | 04
! width="4%" | 05
! width="4%" | 06
! width="4%" | 07
! width="4%" | 08
! width="4%" | 09
! width="4%" | 0A
! width="4%" | 0B
! width="4%" | 0C
! width="4%" | 0D
! width="4%" | 0E
! width="4%" | 0F
! width="4%" | 10 ...
|-
| '''00'''
| Mode
| -
| colspan="3" | -
| colspan="2" | Records to reserve
| colspan="2" | Record length
| -
| colspan="3" | -
| -
| Name length
| Name
|-
|}

'''Open new file''': The '''Record Length''' must be set to a value greater than 0. This will become the length of the records of the new file.

'''Open existing file''': The '''Record Length''' must match the length of the records. If the length is unknown, 0 may be passed.

After the OPEN operation has completed, the PAB delivers information about the result:

'''OUT'''

{| class="plainc" style="margin-left:1%"
|-
! width="4%" | 00
! width="4%" | 01
! width="4%" | 02
! width="4%" | 03
! width="4%" | 04
! width="4%" | 05
! width="4%" | 06
! width="4%" | 07
! width="4%" | 08
! width="4%" | 09
! width="4%" | 0A
! width="4%" | 0B
! width="4%" | 0C
! width="4%" | 0D
! width="4%" | 0E
! width="4%" | 0F
! width="4%" | 10 ...
|-
| -
| -
| Error code
| colspan="3" | -
| colspan="2" | -
| colspan="2" | Actual Record Length
| -
| 0
| colspan="2" | True Record Length
| -
| Name length
| Name
|-
|}

The '''Actual Record Length''' is the length of the records of the existing file. When 0 was passed on the call, this delivers the record length of the file; otherwise this is the value that was passed for the call. The '''True Record Length''' is the record length of the file when it already exists.

<div style="margin-bottom:6em"></div>

=== CLOSE ===

Closes a record-oriented file. A file must be closed after being used. After closing, no further read or write operations may be invoked on the file. This operation is not required for flat memory image files.

The PAB must be set up prior to invoking the operation:

'''IN'''

{| class="plainc" style="margin-left:1%"
|-
! width="4%" | 00
! width="4%" | 01
! width="4%" | 02
! width="4%" | 03
! width="4%" | 04
! width="4%" | 05
! width="4%" | 06
! width="4%" | 07
! width="4%" | 08
! width="4%" | 09
! width="4%" | 0A
! width="4%" | 0B
! width="4%" | 0C
! width="4%" | 0D
! width="4%" | 0E
! width="4%" | 0F
! width="4%" | 10 ...
|-
| '''01'''
| Mode
| -
| colspan="3" | -
| colspan="2" | -
| colspan="2" | -
| -
| colspan="3" | -
| -
| Name length
| Name
|-
|}

After the CLOSE operation has completed, the PAB delivers information about the result:

'''OUT'''

{| class="plainc" style="margin-left:1%"
|-
! width="4%" | 00
! width="4%" | 01
! width="4%" | 02
! width="4%" | 03
! width="4%" | 04
! width="4%" | 05
! width="4%" | 06
! width="4%" | 07
! width="4%" | 08
! width="4%" | 09
! width="4%" | 0A
! width="4%" | 0B
! width="4%" | 0C
! width="4%" | 0D
! width="4%" | 0E
! width="4%" | 0F
! width="4%" | 10 ...
|-
| -
| -
| Error code
| colspan="3" | -
| colspan="2" | -
| colspan="2" | -
| -
| colspan="3" | -
| -
| Name length
| Name
|-
|}

<div style="margin-bottom:6em"></div>

=== READ ===

Reads a record from a record-oriented file. For flat memory image files, [[#LOAD | LOAD]] must be used.

'''IN'''

{| class="plainc" style="margin-left:1%"
|-
! width="4%" | 00
! width="4%" | 01
! width="4%" | 02
! width="4%" | 03
! width="4%" | 04
! width="4%" | 05
! width="4%" | 06
! width="4%" | 07
! width="4%" | 08
! width="4%" | 09
! width="4%" | 0A
! width="4%" | 0B
! width="4%" | 0C
! width="4%" | 0D
! width="4%" | 0E
! width="4%" | 0F
! width="4%" | 10 ...
|-
| '''02'''
| Mode
| -
| colspan="3" | Buffer address
| colspan="2" | Record number
| colspan="2" | Record length
| Memory
| colspan="3" | -
| -
| Name length
| Name
|-
|}

Use the '''Record number''' field to specify the desired record in '''fixed record length''' files. This is not available for variable length record files.

The '''Record Length''' must match the length of the records as specified by [[#OPEN | OPEN]].

The '''Memory''' flag determines whether the data are read into CPU (0) or VDP (not 0) memory.

After the READ operation has completed, the PAB delivers information about the result:

'''OUT'''

{| class="plainc" style="margin-left:1%"
|-
! width="4%" | 00
! width="4%" | 01
! width="4%" | 02
! width="4%" | 03
! width="4%" | 04
! width="4%" | 05
! width="4%" | 06
! width="4%" | 07
! width="4%" | 08
! width="4%" | 09
! width="4%" | 0A
! width="4%" | 0B
! width="4%" | 0C
! width="4%" | 0D
! width="4%" | 0E
! width="4%" | 0F
! width="4%" | 10 ...
|-
| -
| -
| Error code
| colspan="3" | -
| colspan="2" | Next record number
| colspan="2" | -
| -
| colspan="3" | Number of read bytes
| -
| Name length
| Name
|}

'''Next record number''' applies for fixed record length files only.

<div style="margin-bottom:6em"></div>

=== WRITE ===

Writes a record to a record-oriented file. For flat memory image files, [[#SAVE | SAVE]] must be used.

'''IN'''

{| class="plainc" style="margin-left:1%"
|-
! width="4%" | 00
! width="4%" | 01
! width="4%" | 02
! width="4%" | 03
! width="4%" | 04
! width="4%" | 05
! width="4%" | 06
! width="4%" | 07
! width="4%" | 08
! width="4%" | 09
! width="4%" | 0A
! width="4%" | 0B
! width="4%" | 0C
! width="4%" | 0D
! width="4%" | 0E
! width="4%" | 0F
! width="4%" | 10 ...
|-
| '''03'''
| Mode
| -
| colspan="3" | Buffer address
| colspan="2" | Record number
| colspan="2" | Record length
| Memory
| colspan="3" | Number of bytes to write
| -
| Name length
| Name
|-
|}

Use the '''Record number''' field to specify the desired record in '''fixed record length''' files. This is not available for variable length record files.

The '''Record Length''' must match the length of the records as specified by [[#OPEN | OPEN]].

The '''Memory''' flag determines whether the data written from CPU (0) or VDP (not 0) memory.

After the WRITE operation has completed, the PAB delivers information about the result:

'''OUT'''

{| class="plainc" style="margin-left:1%"
|-
! width="4%" | 00
! width="4%" | 01
! width="4%" | 02
! width="4%" | 03
! width="4%" | 04
! width="4%" | 05
! width="4%" | 06
! width="4%" | 07
! width="4%" | 08
! width="4%" | 09
! width="4%" | 0A
! width="4%" | 0B
! width="4%" | 0C
! width="4%" | 0D
! width="4%" | 0E
! width="4%" | 0F
! width="4%" | 10 ...
|-
| -
| -
| Error code
| colspan="3" | -
| colspan="2" | Next record number
| colspan="2" | -
| -
| colspan="3" | Number of read bytes
| -
| Name length
| Name
|}

'''Next record number''' applies for fixed record length files only.

<div style="margin-bottom:6em"></div>

=== RESTORE ===

<div style="margin-bottom:6em"></div>

=== LOAD ===

<div style="margin-bottom:6em"></div>

=== SAVE ===

<div style="margin-bottom:6em"></div>

=== DELETE ===

<div style="margin-bottom:6em"></div>

=== SCRATCH ===

<div style="margin-bottom:6em"></div>

=== STATUS ===

<div style="margin-bottom:6em"></div>

=== BREAD ===

Reads a sector from a file or from a device. This is a level-2 operation, that is, it accesses the device based on sector addressing (or sectors of a file). BREAD allows for two operations:

* Read sectors from a file.
* Read sectors from a device.

'''IN'''

{| class="plainc" style="margin-left:1%"
|-
! width="4%" | 00
! width="4%" | 01
! width="4%" | 02
! width="4%" | 03
! width="4%" | 04
! width="4%" | 05
! width="4%" | 06
! width="4%" | 07
! width="4%" | 08
! width="4%" | 09
! width="4%" | 0A
! width="4%" | 0B
! width="4%" | 0C
! width="4%" | 0D
! width="4%" | 0E
! width="4%" | 0F
! width="4%" | 10 ...
|-
| '''0B'''
| -
| -
| colspan="3" | Buffer address
| colspan="2" | Sector offset
| colspan="2" | -
| -
| colspan="3" | Number of sectors
| -
| Name length
| Name
|-
|}

'''Read from file''': When a file is addressed, the operation reads a sequence of sectors from the file. The '''Sector offset''' is the number of the first sector of the file, counting from 0. The physical locations of the sectors are subject to the sector allocation on the device.

'''Read from device''': When a device is addressed, the operation reads a sequence of sectors from the device. The '''Sector offset''' is the physical sector number.

After the BREAD operation has completed, the PAB delivers information about the result:

'''OUT'''

{| class="plainc" style="margin-left:1%"
|-
! width="4%" | 00
! width="4%" | 01
! width="4%" | 02
! width="4%" | 03
! width="4%" | 04
! width="4%" | 05
! width="4%" | 06
! width="4%" | 07
! width="4%" | 08
! width="4%" | 09
! width="4%" | 0A
! width="4%" | 0B
! width="4%" | 0C
! width="4%" | 0D
! width="4%" | 0E
! width="4%" | 0F
! width="4%" | 10 ...
|-
| -
| -
| Error code
| colspan="3" | Updated buffer address
| colspan="2" | Next unwritten sector
| colspan="2" | -
| -
| 0
| colspan="2" | Number of unwritten sectors
| -
| Name length
| Name
|-
|}

The '''Updated buffer address''' points to the memory address after the sectors were written (e.g. when 4 sectors are written, the pointer is increased by 4*256 = 1024).

The '''Next unwritten sector''' is the first sector that has not been written due to an error condition.

The '''Number of unwritten sectors''' is the number of unwritten sectors due to an error condition.

<div class="warn">Unless you want to write directly to the device, make sure that the PAB contains a file name that points to a file, not to a device. For example, when the file name has been created by the program, and for some reason the file name is empty (like "HDS1."), the following write operation will overwrite the volume information block and the allocation tables and '''destroy the target device filesystem'''.</div>

Tick here: [ ] Yes, I fully understood the danger of this operation.

(The author lost a complete hard disk by this incident, and was lucky to have a backup.)

<div style="margin-bottom:6em"></div>

=== BWRITE ===

Writes a sector to a file or to a device. This is a level-2 operation, that is, it accesses the device based on sector addressing (or sectors of a file). BWRITE allows for three operations:

* Create a new, empty file.
* Write sectors to a file.
* Write sectors to a device.

'''IN'''

{| class="plainc" style="margin-left:1%"
|-
! width="4%" | 00
! width="4%" | 01
! width="4%" | 02
! width="4%" | 03
! width="4%" | 04
! width="4%" | 05
! width="4%" | 06
! width="4%" | 07
! width="4%" | 08
! width="4%" | 09
! width="4%" | 0A
! width="4%" | 0B
! width="4%" | 0C
! width="4%" | 0D
! width="4%" | 0E
! width="4%" | 0F
! width="4%" | 10 ...
|-
| '''0B'''
| -
| -
| colspan="3" | Buffer address
| colspan="2" | Sector offset
| colspan="2" | -
| -
| colspan="3" | Number of sectors
| -
| Name length
| Name
|-
|}

'''Create a file''': When a file is addressed, and the number of sectors is 0, a new file is created. The contents of the file should be written by BWRITE on the same file with a sector count greater than 0.

'''Write to file''': When a file is addressed, the operation writes a sequence of sectors to the file. The '''Sector offset''' is the number of the first sector of the file, counting from 0. The physical locations of the sectors are subject to the sector allocation on the device; in particular, when fragmentation is required, the sectors are written to the new fragment.

'''Writing to device''': When a device is addressed, the operation writes a sequence of sectors to the device. The '''Sector offset''' is the physical sector number.

After the BWRITE operation has completed, the PAB delivers information about the result:

'''OUT'''

{| class="plainc" style="margin-left:1%"
|-
! width="4%" | 00
! width="4%" | 01
! width="4%" | 02
! width="4%" | 03
! width="4%" | 04
! width="4%" | 05
! width="4%" | 06
! width="4%" | 07
! width="4%" | 08
! width="4%" | 09
! width="4%" | 0A
! width="4%" | 0B
! width="4%" | 0C
! width="4%" | 0D
! width="4%" | 0E
! width="4%" | 0F
! width="4%" | 10 ...
|-
| -
| -
| Error code
| colspan="3" | Updated buffer address
| colspan="2" | Next unwritten sector
| colspan="2" | -
| -
| 0
| colspan="2" | Number of unwritten sectors
| -
| Name length
| Name
|-
|}

The '''Updated buffer address''' points to the memory address after the sectors were written (e.g. when 4 sectors are written, the pointer is increased by 4*256 = 1024).

The '''Next unwritten sector''' is the first sector that has not been written due to an error condition.

The '''Number of unwritten sectors''' is the number of unwritten sectors due to an error condition.

<div class="warn">Unless you want to write directly to the device, make sure that the PAB contains a file name that points to a file, not to a device. For example, when the file name has been created by the program, and for some reason the file name is empty (like "HDS1."), the following write operation will overwrite the volume information block and the allocation tables and '''destroy the target device filesystem'''.</div>

Tick here: [ ] Yes, I fully understood the danger of this operation.

(The author lost a complete hard disk by this incident, and was lucky to have a backup.)

<div style="margin-bottom:6em"></div>

=== PROTECT ===

<div style="margin-bottom:6em"></div>

=== RENAME ===

<div style="margin-bottom:6em"></div>

=== FORMAT ===

GeneveOS XOP Definitions

2022-04-24T17:28:53Z

Mizapf:

GeneveOS makes frequent use of XOPs and offers them for user programs. An XOP (extended operation) is a special command of the TMS processor family which causes a [[Terminology#C|context switch]], transferring control to a location that is specified in a table.

Compared to common architecture concepts, the XOP is TI's way of implementing a '''system call'''.

The XOP instruction takes two arguments; the first delivers data for the call, the second is a number from 0 to 15 and indicates the '''XOP number'''. In GeneveOS, all system calls are XOP 0 with specific arguments:

ARGUM DATA <number>
...
XOP @ARGUM,0
...

{| class="plainc"
! XOP argument
! Category
|-
| 5 || [[Geneve keyboard control | Keyboard ]]
|-
| 6 || [[GeneveOS Video Interface | Video display ]]
|-
| 7 || [[GeneveOS Memory Management Functions | Memory Management ]]
|-
| 8 || [[GeneveOS Device Operation | Devices (Files) ]]
|-
| 9 || [[GeneveOS Utility Functions | Utility functions]]
|-
| 10 || Mathematical functions
|}

[[Category:MDOS]]
[[Category:Geneve]]
[[Category:Programming]]

Geneve Memory Management Functions

2022-04-24T17:27:15Z

Mizapf: Mizapf moved page Geneve Memory Management Functions to GeneveOS Memory Management Functions

#REDIRECT [[GeneveOS Memory Management Functions]]

GeneveOS Memory Management Functions

2022-04-24T17:27:14Z

Mizapf: Mizapf moved page Geneve Memory Management Functions to GeneveOS Memory Management Functions

Memory management in MDOS is available via XOP 7. In the MDOS sources the relevant files are ''manage2s'' and ''manage2t''.

'''Fast RAM''' is all memory with 0 wait states (SRAM), while '''Slow RAM''' is 1 wait state RAM, offered by the DRAM chips. The on-chip RAM is not considered here as it is not manageable by MDOS. The 256 bytes of on-chip RAM are always visible in the logical address area F000-F0FB and FFFC-FFFF. Any page that is mapped to the E000-FFFF area will be overwritten by operations in that area; this must be considered when using the E000-FFFF area.

Two classes of memory management functions are available: XOPs for user tasks, and XOPs exclusively used by the operating system.

== Introduction and terminology ==

As it was common with TI application programming, buffers were usually placed statically in the program, that is, a portion of memory (like 256 bytes) was reserved in the program code to be used for storing data. Assembly language offers the [https://en.wikipedia.org/wiki/.bss BSS and BES] directives for this purpose. This is not recommended when the buffer is very big, like 12 KiB, since that space will bloat the program code that must be loaded on application start. It is impossible for even larger buffer spaces like 100 KiB. In that cases, dynamic allocation is the typical solution also known from other systems.

The Geneve offers 512 KiB of slow RAM and another 32 KiB of fast RAM. Starting from MDOS 2.5, the fast RAM must be [[Geneve_9640#Memory_Expansion | expanded]] to 64 KiB. Obviously, this memory can only be effectively used with the help of memory management functions.

=== Logical address space and execution pages ===

The logical address space are the addresses as seen from the CPU. The Geneve uses a 16-bit address bus which means that the logical address space is 64 KiB large. The CPU itself is not capable of addressing more memory, which is a limitation for application design. It essentially means that a ''transparent'' access to more than 64 KiB is impossible. The CPU is not capable of representing addresses outside this area.

The connection between execution pages and the logical addresses can be seen here:

[[file:executionpage.png|650px]]

Execution pages are associated to logical addresses in a fixed way; the logical address allows to easily calculate the execution page: The first three bits determine the execution page. The remaining 13 bits are the 8 KiB memory space within this execution page.

=== Physical address space and physical pages ===

The physical address space comprises the complete memory area of the Geneve from the hardware viewpoint. There is no consideration of allocation to tasks. The physical address space consists of 256 '''pages''' of 8 KiB each, together 2 MiB.

[[File:physicalpages.png]]

The first 64 pages are the DRAM area (the slow RAM); from page number E8 to EF we find 8 pages of fast SRAM. The original configuration of the Geneve only included 32 KiB of SRAM, but in most cases this was expanded to 64 KiB. From page F0 to FF we find the Boot ROM; there is room for 128 KiB, but only 16 KiB are actually used, since the page address is not completely decoded in this area: All even pages are the same page, and all odd pages are the same page as well.

Physical addresses can be represented as shown here:

[[File:physicaladd.png]]

Accordingly, physical addresses range from '''000000''' to '''1FFFFF'''. The TMS 9995, however, cannot use physical addresses since they do not match the 16 bit width of the address bus. The Geneve architecture includes a [[Geneve paged memory organization | memory mapper]] which is used to map the logical address space of the CPU to the physical address space. So when the CPU accesses the logical address A080 the mapper determines which physical address this corresponds with. For instance, if the mapper contains the value 2C for execution page 5, the logical address A080 maps to physical address 058080.

=== Local (virtual) pages ===

MDOS allows for multitasking. In principle, multitasking is possible whenever we have means of passing control between independent applications. This can be done explicitly (by ''yielding'') or timer-controlled. Apart from that, when several tasks are running in the system we have to take care that each task gets a part of the global memory area exclusively for itself. But how can we know which application uses which part of the physical memory?

Consequently, access to memory must be "virtualized"; we do not allow a direct access to the physical memory but map "local" or "virtual" addresses to a physical addresses. This indirection has an important advantage in multitasking systems: Every task may run as if it were the only one in the system. Although several tasks may access memory at the same local address, the actual physical memory is different.

[[file:virtualpages.png]]

The illustration shows how the "local pages" of the task are mapped to physical pages. We see that a task may use up to 256 local pages, covering the complete physical space. This is an untypical, extreme case, though. A task should only make use of those pages it really needs. This means that many, in fact most of the local pages are unassigned.

In this example, another task has been loaded in the system, but although some of the local pages it uses are also used by the other task, they access different physical pages. Each task gets an own collection of pages from the '''pool''' of free physical pages.

When a task is done the allocated memory should be returned to the system; otherwise the pool of pages dries up, and no more tasks can be loaded and run (a so-called ''memory hole'').

Now how do virtual addresses look like? - Just like physical addresses:

[[file:virtualadd.png]]

In fact the local page number just needs to be mapped to the physical page number if that local page has got such an associated physical page.

As said above, the CPU can only work with logical addresses, not with physical addresses. This is also true for virtual addresses. We can, however, write programs that need to care for the proper paging, like the XOPs presented here.

As you noticed we are using the terms '''local''' address/page and '''virtual''' address/page synonymously, but we would recommend to avoid the term virtual addressing and instead speak about local addresses. The reason is that virtual memory management has a distinctly different meaning in common computer architectures.

=== Virtual address spaces in other architectures ===

''Virtual memory'' and its management in PC architectures refers to the mechanism by which a part of the logical address is interpreted as an index in a page table (or a cascaded page table). The page table contains pointers to physical memory and also to space on a mass storage, allowing for swapping pages in and out. The Geneve memory organization is similar to this concept as a pointer into a table is translated to a prefix into the physical address space.

However, and this is a notable difference, there is no support for virtual addresses in the TMS 9995. We may, of course, write applications that take care of memory mapping, but this is a pure software solution. The XOPs as shown below, and also other XOPs like those for file access, provide such a software implementation of virtual addressing.

PC architectures with the Intel 8086 had an address bus of 20 bits (1 MiB address space), the Intel 80286 had an address bus width of 24 bit which already allowed for 16 MiB address space. Modern PCs have at least a 32-bit wide address. A process may thus make use of a maximum of 2<sup>32</sup> bytes or 4 GiB. Here the address space is (or better was) ''larger'' than the amount of memory in the system. (Now you know why you might want to change to a 64-bit architecture.)

With our Geneve, however, the address space is ''smaller'' than the amount of available memory, and we neither have any kind of segment registers as in the 8086. This means that we will never have a similarly simple, expandable memory model as known from the PC world. Any kind of memory paging must be handled on the software level.

The concept as presented here as some similarities with the [http://en.wikipedia.org/wiki/Expanded_memory EMS technology] on PCs which was dropped with the availability of the 80386 and newer processors featuring the protected mode that allowed programs to make use of the virtual memory management.

=== Shared memory ===

Memory pages can be shared among tasks. This is simply done by deliberately assigning the same physical page to different tasks. Since shared pages can be used by many tasks they cannot be allocated and freed in the same way as the usual "private" pages. Also, we want to be able to share more than a single page and still retain some relation between them. Therefore, '''shared page groups''' are introduced.

[[file:Sharedpages.png]]

The illustration shows some important properties of the concept of shared pages:

* Shared pages can only be shared as a complete group. If you take one, you take all. This is reasonable since the task that offers pages to be shared should assume that all pages to be shared are actually used in the other tasks.
* Shared groups are always contiguous, they have no holes. Assumed that in the example, task 1 wants to share the pages 6-8 and A-D, it must declare two distinct groups 1 and 2.
* Groups are identified by a '''type'''. Unlike in the illustration, a type is not a color but a number from 1 to 254 (not 0 and not 255). Types may be freely defined, but it may be reasonable to find a convention on the numbers so that, for instance, tasks know by the number whether the shared group contains code or data.
* The creation of a group is done by one of the tasks declaring some of its private pages as shared, assigning a type. The other tasks may then import these pages.
* The importing task must have a gap in its local page allocation which is large enough to contain the group.
* A type may be reused when all tasks have released the shared group of this type.
* Local page 0 may never be member of a shared group since it contains essential information for the task.

== User-task XOPs ==

User-task XOPs are available for use in application programs. Here is a typical example:

SEVEN DATA 7
...
GETMEM LI R0,1 // Allocate
LI R1,5 // 5 pages (=40 KiB)
LI R2,10 // Starting at local page 10
CLR R3 // Slow mem is OK
XOP @SEVEN,0 // Invoke XOP
...

=== Available memory pages ===

'''Opcode: 0'''

{| class="xoparg"
|-
|
! Input !! Output
|-
| R0
| Opcode (0000) || Error code (always 0)
|-
| R1
| || Number of free pages
|-
| R2
| || Number of fast free pages
|-
| R3
| || Total number of pages in system
|-
|}

This function is used to query the free space in the system. No changes are applied. The total number of pages are the maximum number of allocatable pages.

=== Allocate pages ===

'''Opcode: 1'''

{| class="xoparg"
|-
|
! Input !! Output
|-
| R0
| Opcode (0001) || Error code (0, 1, 7, 8)
|-
| R1
| Number of pages || Number of pages actually fetched to complete map as required
|-
| R2
| Local page number || Number of fast pages fetched
|-
| R3
| Speed flag ||
|-
|}

Using this function a task can allocate pages from the pool of free pages. It must specify at which local page number the requested sequence of physical pages shall be installed.

Using the speed flag the task can control the preference for the memory type. If set (not 0), the system tries to first allocate fast memory, and when nothing is left, continues with slow memory. The opposite happens when the flag is 0.

Local pages are only once associated with physical pages until they are explicitly freed. If another allocation request overlaps with an earlier one, only new pages are allocated.

[[file:allocate.png]]

As shown here, first the pages 3-5 were allocated, returning 3 as the number of actually fetched pages. Then the pages 2-7 were allocated, but pages 3-5 are skipped, so again we get only 3 pages reported as allocated.

<div style="clear:both"></div>

=== Free pages ===

'''Opcode: 2'''

{| class="xoparg"
|-
|
! Input !! Output
|-
| R0
| Opcode (0002) || Error code (0, 2)
|-
| R1
| Number of pages ||
|-
| R2
| Local page address ||
|-
|}

Returns allocated pages to the pool of free pages. When the application terminates, all assigned pages are returned automatically, so this function is mainly used when the application explicitly wants to return memory during its runtime. Shared pages cannot be freed by this function.

Error code 2 is returned when the local page address (R2) is 0; page 0 cannot be freed in this way.

=== Map local page at execution page ===

'''Opcode: 3'''

{| class="xoparg"
|-
|
! Input !! Output
|-
| R0
| Opcode (0003) || Error code (-, 2, 3)
|-
| R1
| Local page number ||
|-
| R2
| Execution page number ||
|-
|}

By this function, a local page is mapped into an execution page. While pure data operations (as done in some XOP functions) may be done using local (virtual) addresses, execution of '''code''' in these areas '''requires''' that the page be mapped into an execution page, which means it gets logical addresses. Logical addressing in the code usually requires that a particular execution page be used. For instance, if the code contains a subroutine that is expected at a certain address, it will fail to work when located elsewhere.

Error code 2 is returned when the local page number or the execution page number is 0.

Error code 3 is returned when the execution page number is higher than 7 or the local page is unassigned.

=== Get address map ===

'''Opcode: 4'''

{| class="xoparg"
|-
|
! Input !! Output
|-
| R0
| Opcode (0004) || Error code (-, 8)
|-
| R1
| Pointer to buffer || Count of pages reported
|-
| R2
| Buffer size ||
|-
|}

Gets the map table. On return of the call, the memory locations pointed to by R1 contain a sequence of physical page numbers that have been allocated. R1 contains the length of this sequence. The value at the pointer position is the physical page number associated with local page 0; next is the physical page number associated with local page 1 and so on. The table is trimmed, which means it stops with the last assigned page. Unassigned pages in between are indicated by a FF value.

Error code 8 is returned when the buffer is too small to hold the list of numbers of allocated pages.

=== Declare shared pages ===

'''Opcode: 5'''

{| class="xoparg"
|-
|
! Input !! Output
|-
| R0
| Opcode (0005) || Error code
|-
| R1
| Number of pages to declare as shared ||
|-
| R2
| Local page number ||
|-
| R3
| Type to be assigned to shared pages ||
|-
|}

Following the above description of [[#Shared memory|shared memory]], this function must be used to initially define a shared pages group. In the example, task 1 previously executed this function with R1=3, R2=6, R3=1 and once more with R1=4, R2=>0A, R3=2.

=== Release shared pages ===

'''Opcode: 6'''

{| class="xoparg"
|-
|
! Input !! Output
|-
| R0
| Opcode (0006) || Error code (0, 6, 8)
|-
| R1
| Type ||
|-
|}

When a task does not need the shared memory anymore or wants to free its local pages, it calls this function to release the shared memory on its side. As we cannot release single pages, the group identifier (type) must be passed.

Error code 6 occurs when the given type is unknown (not declared before).

=== Import shared pages ===

'''Opcode: 7'''

{| class="xoparg"
|-
|
! Input !! Output
|-
| R0
| Opcode (0007) || Error code (0, 2, 6, 7, 8)
|-
| R1
| Type ||
|-
| R2
| Local page number for start of shared area ||
|-
|}

Imports a group of shared pages. In the [[#Shared memory|example]] above, task 2 has executed this function with R1=1, R2=3 and a second time with R1=2, R2=9.

The error codes indicate that all worked well (0), that the task attempted to overlay local page 0, which is not allowed (2), that the group identifier is invalid or unknown (6), or that the task attempted to overlay an already assigned private page. Task 2 in the example would have run into this problem if it had tried to import group 2 starting at local page 0A, and local page 0D was already associated with physical page EF.

=== Return size of shared page group ===

'''Opcode: 8'''

{| class="xoparg"
|-
|
! Input !! Output
|-
| R0
| Opcode (0008) || Error code (0, 6)
|-
| R1
| Type || Number of pages in shared group
|-
|}

By this function the task can deterine the size of the indicated shared group. This is important to know so that we can successfully import the group at a gap that is large enough.

== Privileged XOPs (only available for operating system) ==

The following XOPs are used within MDOS itself to implement the memory management. They cannot be used from user tasks since they have good potential to spoil the entire management, requiring a system reboot. They may be of interest for people attempting to continue MDOS developnment.

=== Release task ===

'''Opcode: 9'''

{| class="xoparg"
|-
|
! Input !! Output
|-
| R0
| Opcode (0009) || Error code (0, -1)
|-
| R1
| First node ||
|}

Undoes all memory allocations for this task. This function is called by the system when a task terminates. The first node is the pointer in MEMLST. An error code of -1 (FFFF) is returned when this function is called by a user task.

=== Get memory page ===

'''Opcode: 10'''

{| class="xoparg"
|-
|
! Input !! Output
|-
| R0
| Opcode (000A) || Error code (0, 1, -1)
|-
| R1
| Physical page number || Pointer to node
|-
| R2
| Speed flag || (Page number from node)
|-
|}

Gets the pointer to the node of a physical page. The node is used in the linked list of the page management. If R1 is from 0-FF, the result is the pointer to the node of the first free physical page. The speed flag is used to determine whether to find slow (0) or fast (not 0) memory. If R1 is logically higher than FF (usually with the high byte set to FF), the function will allocate a new page, depending on the speed flag.

R0 contains 0 if no error occured (note that the page is still not assigned to a task); 1 means that the page is not available or there are no free pages. -1 is returned when the caller is a user task.

=== Free memory page ===

'''Opcode: 11'''

{| class="xoparg"
|-
|
! Input !! Output
|-
| R0
| Opcode (000B) || Error code (0, 8, -1)
|-
| R1
| Physical page number || Pointer to node
|-
|}

The physical page is added to the list of free pages. Returns error code 8 if the page node could nbot be inserted in the list.

=== Free memory node ===

'''Opcode: 12'''

{| class="xoparg"
|-
|
! Input !! Output
|-
| R0
| Opcode (000C) || Error code (0, -1)
|-
| R1
| Pointer to node ||
|-
|}

Management function. The node is added to the list of free nodes.

=== Link memory node ===

'''Opcode: 13'''

{| class="xoparg"
|-
|
! Input !! Output
|-
| R0
| Opcode (000D) || Error code (0, -1)
|-
| R1
| Pointer to node ||
|-
| R2
| Pointer to node to link to ||
|-
|}

Management function. Links memory nodes together to produce the linked list.

=== Get address map (system) ===

'''Opcode: 14'''

{| class="xoparg"
|-
|
! Input !! Output
|-
| R0
| Opcode (000E) || -1 or count of valid pages
|-
|}

Used by [[Terminology#D|DSRs]]. Returns the mapping of local pages into location >1F00. R0 returns the length of the list which is also stored at 1FFE.

== Error codes ==

{| class="plain"
! Code
! Meaning
|-
| 00
| No error
|-
| 01
| Not enough free pages
|-
| 02
| Can't remap execution page zero
|-
| 03
| No page at local address
|-
| 04
| User area not large enough for list
|-
| 05
| Shared type already defined
|-
| 06
| Shared type doesn't exist
|-
| 07
| Can't overlay shared and private memory
|-
| 08
| Out of table space
|-
|}

[[Category:Geneve]]
[[Category:MDOS]]
[[Category:Programming]]

GeneveOS XOP Definitions

2022-04-24T17:26:04Z

Mizapf:

GeneveOS makes frequent use of XOPs and offers them for user programs. An XOP (extended operation) is a special command of the TMS processor family which causes a [[Terminology#C|context switch]], transferring control to a location that is specified in a table.

Compared to common architecture concepts, the XOP is TI's way of implementing a '''system call'''.

The XOP instruction takes two arguments; the first delivers data for the call, the second is a number from 0 to 15 and indicates the '''XOP number'''. In GeneveOS, all system calls are XOP 0 with specific arguments:

ARGUM DATA <number>
...
XOP @ARGUM,0
...

{| class="plainc"
! XOP argument
! Category
|-
| 5 || [[Geneve keyboard control | Keyboard ]]
|-
| 6 || [[GeneveOS Video Interface | Video display ]]
|-
| 7 || [[MDOS Memory Management Functions | Memory Management ]]
|-
| 8 || [[GeneveOS Device Operation | Device Operation ]]
|-
| 9 || [[GeneveOS Utility Functions | Utility functions]]
|-
| 10 || Mathematical functions
|}

[[Category:MDOS]]
[[Category:Geneve]]
[[Category:Programming]]

MDOS XOP Definitions

2022-04-24T17:24:09Z

Mizapf: Mizapf moved page MDOS XOP Definitions to GeneveOS XOP Definitions

#REDIRECT [[GeneveOS XOP Definitions]]

GeneveOS XOP Definitions

2022-04-24T17:24:09Z

Mizapf: Mizapf moved page MDOS XOP Definitions to GeneveOS XOP Definitions

MDOS makes frequent use of XOPs and offers them for user programs. An XOP (extended operation) is a special command of the TMS processor family which causes a [[Terminology#C|context switch]], transferring control to a location that is specified in a table.

Compared to common architecture concepts, the XOP is TI's way of implementing a '''system call'''. All system calls are XOP 0 with specific arguments:

ARGUM DATA <number>
...
XOP @ARGUM,0
...

{| class="plainc"
! XOP argument
! Category
|-
| 5 || [[Geneve keyboard control | Keyboard ]]
|-
| 6 || [[GeneveOS Video Interface | Video display ]]
|-
| 7 || [[MDOS Memory Management Functions | Memory Management ]]
|-
| 8 || [[GeneveOS Device Operation | Device Operation ]]
|-
| 9 || [[GeneveOS Utility Functions | Utility functions]]
|-
| 10 || Mathematical functions
|}

[[Category:MDOS]]
[[Category:Geneve]]
[[Category:Programming]]

Programmable Systems Interface TMS 9901

2022-04-24T12:04:51Z

Mizapf:

The Programmable System Interface (PSI) is a circuit that is used on the TI-99/4A main board, on some expansion cards, and on the Geneve.

The designation of the PSI is '''TMS9901''', and this is the name that most users should be more familiar with.

== Features ==

The TMS 9901 Programmable Systems Interface is a multi-purpose circuit that is used in the TI-99/4A and the Geneve computer, and also on some peripheral cards like the Corcomp Floppy Disk Controller.

The 9901 has three main usage modes:

* Input/Output ports
* Interrupt prioritizing
* Timer

The I/O ports are mainly used for scanning the keyboard and joysticks, while the timer is used for cassette data encoding and decoding. The interrupt prioritizer is only used for the video interrupt which is routed from the VDP to the CPU through the 9901.

== Package ==

This is the pin assignment according to the 9901 specification.

[[File:Pack9901.png|300px|left]]

You can see pins of related functions marked by the same background color.

Orange: Interrupt inputs

Red: CRU bit selection (00000 - 11111, i.e. 0-31 decimal)

Blue: CRU interface

Violet: I/O ports

Yellow: Outgoing interrupt and level

Note that some pins have a double function, or in other words, two functions share the same pin. I will discuss this in the following sections.

<div style="clear:both"></div>

== Input/Output port operation ==

The simplest way of working with the 9901 is input/output operation with the ports. The 9901 has 16 configurable ports that can be individually used as inputs or outputs: P0 to P15.

=== Px port as input ===

[[File:Port9901in.png|250px]]

The power-on preset for every port is input. If you want to probe the P2 status (bit 18), use

CLR R12
TB 18
JEQ P2ACT

TB copies the bit at the given CRU address into the Equal bit of the status register. JEQ will jump to the location when this input has a high level. The maximum input current is 100 µA. You should protect the input with a resistor; [[#Safety_precautions | see below]] for a more detailed discussion.

If you want to read all 16 ports, use the STCR instruction:

LI R12,32
STCR R1,0

Note that the CRU base address in R12 advances in steps of 2, so bit 16 is on address 32. Also, for reading 16 bits, you must specify a count of 0.

Besides the 16 ports, the interrupt inputs of the 9901 can be used as input ports as well. More about that can be found in the section about the [[#Interrupt_mode| interrupt mode]].

=== Px port as output ===

[[File:Port9901out.png|250px]]

Once you write a value to the CRU address of a 9901 port, this port switches to output mode. The value written to the port is the value that is shown on its pin. If we want to output a 1 on P6, we have to use

CLR R12
SBO 22

If we wanted to output a 0, SBZ would have to be used. In order to set several ports in one go, use LDCR.

We can also read the output port just by using TB as usual (or STCR for several ports at once).

CLR R12
SBO 22
TB 22
JEQ EXPECT

The TB operation should return the 1 which the previous SBO has set.

You '''cannot''' switch back to input mode. This is only possible by resetting the 9901, either using the /RST1 input line, or by setting the /RST2 bit (bit 15) to 0 in clock mode.

== Interrupt mode ==

In interrupt mode, bits 1 to 15 are used to set the interrupt mask (write), or to query the interrupt inputs (read). That is, the meaning of reading and writing the bits is indeed different.

This schema shows how the interrupt inputs are used.

[[File:Int9901.png|600px]]

This illustration is slightly simplified; there is a latch between each interrupt input and the mask AND gate. This is not relevant for our programming, though. For more details see the ''TMS 9901 Programmable Systems Interface Data Manual'' [[#ref2|[1]]].

=== Checking the interrupt inputs ===

In general, every interrupt input can be read via CRU access:

CLR R12
TB 15
JEQ NOINT15

TB copies the bit at the specified CRU address to the Equal status bit. This means that JEQ jumps to the location when the bit is 1. Since all interrupt inputs are negative logic, reading a 1 means that there is no interrupt at this input (so I called it NOINT15).

If we want to read several interrupt inputs by a single instruction, we have to use STCR.

LI R12,16
STCR R1,8

This reads the states of the /INT8, /INT9, ..., /INT15 inputs and puts them in the most significant byte of R1. (See the specification of STCR and LDCR for transfers of up to 8 bits.)

=== Interrupt levels ===

Each interrupt input (/INT1 to /INT15) may be used to trigger an interrupt at another circuit, typically the CPU. For this purpose, the 9901 offers an /INTREQ outgoing line. In the TI console, it is routed to the /INTREQ input of the TMS9900 CPU.

In addition there is a priority encoder, which is not shown here. This encoder outputs a 4-bit number which reflects the smallest number of the interrupt inputs where an interrupt has been sensed.

That is, if /INT4 and /INT7 are currently set to 0 (active), the priority encoder outputs (0100), which means 4.

The TMS9900 CPU can differentiate between these interrupt levels, and by using its LIMI command, we can set a threshold where interrupts are ignored. So when we use a LIMI 3, the interrupts of level 4, 5, 6 and higher will be ignored.

The bad news is that Texas Instruments did not use these priority lines in the TI console. In fact, these outputs (IC0 .. IC3) are not connected, and the respective interrupt level inputs at the CPU are hardwired to (0001), which means that every interrupt that occurs in the TI console is automatically set to level 1. So in order to block all interrupts from the 9901

LIMI 0

must be executed. To allow all,

LIMI 1

is sufficient. For some unclear reason, TI used LIMI 2 in all occasions.

=== Arming and disarming interrupts ===

As said above, every interrupt input can be read at any time in interrupt mode. In that sense, we don't really treat these inputs as interrupts inputs, but simply as input ports.

If we want a port to trigger an interrupt, we must arm this interrupt input. This is done by setting the respective bit to 1.

CLR R12
SBO 2

This enables interrupt input /INT2 to cause an /INTREQ when its input changes to 0. In the TI console, /INT2 is connected to the interrupt output of the VDP (video processor). If you want to block interrupts on that input, use SBZ.

It is a common misunderstanding that interrupts can be cleared by using a SBZ on an input. I also found this in the popular ''TI Intern'' book. Instead, SBZ n simply blocks interrupt input /INTn. In the case of the video processor, it is up to the VDP to clear its interrupt, and this is done by reading its status register.

Consequently, you '''cannot''' read the current mask setting of the 9901. What you get from reading are the input levels of the pins. So if you plan to change the mask bits temporarily, be aware that you cannot ask the 9901 to give you the current setting which you want to restore later. You will have to find out by another way.

== Clock mode ==

Besides the I/O capabilities, the 9901 offers a "real-time" clock. This should not be understood as a precise timer with seconds, hundreds of seconds or other but as a countdown timer that is decremented every 64 CPU clock cycles.

This schematic is taken from the Osborne book [[#ref1 |[2]]], redrawn by me in LibreOffice (and with added Load Buffer).

[[File:Clock9901.png|550px]]

=== Using the timer ===

There are basically two ways of using the countdown timer:

* Interval timer: Set the counter to a value; wait until the counter reaches zero. The 9901 can be set up to raise an interrupt at that instant.
* Event timer: Set the counter to a value; do something and then read the counter value.

The counter has 14 bits; that is, its maximum value is 0x3FFF (16383). The counter is decremented every 64 clock cycles, and for the TI-99/4A and the Geneve with a clock cycle time of 333ns, this means that the counter resolution is 21.333 µs. The whole 16384 steps take 0.3495 seconds (349.5 ms).

When the counter reaches 0, it is reloaded from the load buffer, and counting continues.

It is essential to understand that the counter '''always''' counts down, independent of the mode. The specification says that the clock is enabled when a non-zero value is loaded into the load buffer, but tests on a real Geneve show that the clock decrements even when the load buffer is filled with 0.

=== Setting the timer ===

In order to set the load buffer and so to define the maximum counter value, we must switch to clock mode. This is done by setting bit 0 of the 9901 to 1. In the TI/Geneve systems, the 9901 is mapped to CRU base address 0, so we can do this

CLR R12
SBO 0

to enter '''clock mode'''. Using SBZ 0 returns to '''interrupt mode'''.

The effect of switching to clock mode is that the load buffer becomes accessible by the CRU addresses 1 to 14. Supposed that we want to load the buffer with the value 0x00FF, we may use these lines:

CLR R12
SBO 0
LI R1,>00FF
INCT R12
LDCR R1,14

As we see, we must change the CRU base. The LDCR operation always starts at the address defined in R12; if this is not 0, we have to set it here. Note, however, that the CRU address is always half of the R12 value, since the rightmost bit, A15, is not part of the address. If we want to start at bit 1, we must increase R12 by 2. This is, by the way, done wrong in several places in the literature where R12 is only set to 1.

We can combine the SBO and the LDCR to one operation if we define the rightmost bit of R1 as the bit 0 and the following bits as the timer value.

CLR R12
LI R1,>01FF (0000 0001 1111 1111)
LDCR R1,15

Do '''not''' write all 16 bits. The last bit will change bit 15 of the 9901, which is the /RST2 bit. When we are in clock mode, writing a 0 to the /RST2 bit resets all I/O ports. This means that all pins are set to inputs, and devices that rely on them as outputs may be turned off unintentionally.

=== Reading the timer ===

We are interested for the current value of the timer at some occasions. However, since the counter is constantly changing (every 64 clock cycles), reading from the active counter may deliver a wrong result. Think, for instance, about a value 0x2000, which is decremented after we read the first bits, we may end up with 0x2FFF (2 from 0x2000, FFF from 0x1FFF).

For this reason, the timer value is copied to a '''read buffer'''. This happens at every 64th clock cycle, when the counter is also decremented, but only when we are '''not''' in clock mode.

To read the buffer, we must set the 9901 to clock mode first, which freezes the counter value in the read buffer. Then we can read the counter using STCR.

CLR R12
SBO 0
STCR R1,15
SRL R1,1
SBZ 0

As we see, register 1 will contain bit 0 in its rightmost bit, so we shift R1 by one position to move it out.

Do not forget to return to interrupt mode, or the buffer will not receive further updates.

As mentioned, bit 15 is the /RST2 bit when we write to it. For reading, bit 15 reflects the /INTREQ output.

=== The weird S0 input ===

There is one peculiarity with the 9901. When the input line S0 is set to 1, the clock mode is '''left temporarily''' - until S0 is 0 again, and bit 0 is 1. If bit 0 is 0, this has no effect, as the clock mode is never entered.

What is the reason for this?

TI obviously considered use cases where the 9901 remains in clock mode for longer times, while the I/O ports must still be operated. The I/O ports are available on bits 16-31, which means that the S0 input is 1 for these addresses. So when we do a SBO 16, this is not related to the timer value, and thus should control the first I/O port. To allow this, the chip returns to interrupt/port mode for this operation, and when S0 is reset, returns to clock mode.

In the TI console, the S0-S4 inputs are directly connected with the address bus lines A10-A14. This has a strange side effect: Whenever address bus line A10 changes to 1, the clock mode is left temporarily, and this also happens for ordinary memory accesses.

Suppose that we are in clock mode (SBO 0). In this mode, the read buffer should not be updated, so when we read it, we should get the same value every time, although the real counter value is different. But this is difficult to achieve: If our program uses a memory address where A10 is 1 for some instruction, loading this instruction into the CPU will set A10 to 1, and thus leave clock mode, which updates the counter.

Therefore, you may have the impression that the read register continues to be updated even though you set bit 0 to 1. But this is only happening because your program extends over a location where A10 is 1. So if you want to prove that in clock mode the read register remains fixed, your program must avoid all memory locations where A10 is 1.

== Shared pins ==

Some pins have a double meaning; for example, pin 34 is labeled /INT7 / P15. How do we select the functions?

The shared pins are those for the interrupt inputs /INT7 to /INT15; they may also be used for P7 to P15 (in the opposite order).

If the Pn port is set to '''input''', the situation looks like this:

[[File:Shared9901in.png|250px]]

This means that both port and interrupt input have the same values; each one is a mirror of the other's state. We notice it by reading the bits of the associated CRU addresses, getting the same results. There is a difference, though: The interrupt input can be armed to trigger an outgoing interrupt, while the I/O port cannot.

In the other case, the Pn port is an '''output'''.

[[File:Shared9901out.png|250px]]

Is that possible? - Sure. The interrupt input will reflect the output of the port. When we set the port to 1, the interrupt input will get that 1 (same for 0). If we arm the interrupt input, setting the output port to 0 will trigger an interrupt via this input. The 9901 specification document recommends to disarm the interrupt trigger for the shared ports because of this possibly unwanted effect.

== Safety precautions ==

The TMS9901 PSI is an interrupt encoder and an I/O circuit. You may have heard that improper use of I/O circuits may damage the circuit so that it must be replaced. Is this possible with the 9901 as well? Is there a way to kill the 9901?

Short answer: Yes.

Longer answer: Yes, but it depends on the way how the ports are used.

If the port is used as an input, nothing bad will happen, since the ports have high input impedance. You can put 0V or 5V directly to the input; of course, you should not use excessive voltage.

=== How to damage the 9901 ports ===

The problem is when the port is configured as an output port. In that case it may output 0V (0) or 5V (1). When you connect the output to the opposite voltage, you will cause a short circuit which quickly exceeds the chip's maximum power dissipation of 750 mW. This means you will fry the chip.

Consider the following setup (but don't try it!).

[[File:Badport9901.png|300px]]

Obviously, port P4 is assumed to be an input. When the switch is open, port P4 will sense a 1 on its input. When the switch is closed, it will sense a 0.

Now what happens when you execute this code?

CLR R12
SBO 20

This will program port P4 to be an output, and to show a 1 (5V) at the output. SBZ will, in contrast, make this port output a 0. So how do you make it an input port? - This is done by resetting the chip. As long as you don't use a SBZ/SBO (or a LDCR) on the ports, the ports are inputs.

Nothing has happened up to now. But now imagine that you press the switch. This will put the 1 output to ground, causing the short circuit, and your 9901 is toast.

=== What about the TI console? ===

So can we damage the 9901 in the TI console by a suitable CRU operation? - Luckily not.

The reason is the way TI used the ports on the mainboard. Most of the ports are configured as outputs. Nothing happens when you reset them to inputs.

* The pure interrupt inputs (/INT1 to /INT6) are safe, as they cannot output anything. They have no output driver that could be fried.
* P0 and P1 are not connected.
* P2, P3, and P4 are designed as outputs, so they cannot be turned from an input to an output.
* P5 is the selector of the Alpha Lock key, so output as well.
* P6 and P7 (/INT15) are the cassette motor control outputs.
* P8 (/INT14) is the audio gate output.
* P9 (/INT13) is the cassette output.
* P10 (/INT12) is pulled up to 5V via a 10 kOhm resistor. If you put a 0 on this port (5V), the maximum current is 500 µA, which results in a power dissipation of 2.5 mW (far below the maximum 750 mW).
* P11 (/INT11) is the cassette input. However, there is a resistor of 2.2 kOhm (R413) which effectively guards the port of high currents.
* P12, P13, P14, P15 (/INT10 ... /INT7) are the keyboard input lines. Again, we have pull-ups of 10 kOhm against +5V, but also 470 Ohm on the line, which means a maximum of 8.5 mA or 42.5 mW. This is still well below the maximum value.

So we see that resistors are the best way to protect the ports. And we may calm down; we cannot burn the 9901 in the TI console by a bug in our program.

== Literature ==

<span id="ref1">[1]</span> Texas Instruments: ''TMS 9901 Programmable Systems Interface Data Manual'', July 1977

<span id="ref2">[2]</span> Adam Osborne, Gerry Kane: ''Osborne 16-Bit Microprocessor Handbook / Includes 2900 Chip Slice Family''. Published by OSBORNE/McGraw-Hill 1975, 1981. ISBN 0-931988-43-8.

Programmable Systems Interface TMS 9901

2022-04-23T14:02:17Z

Mizapf: /* Package */

The Programmable System Interface (PSI) is a circuit that is used on the TI-99/4A main board, on some expansion cards, and on the Geneve.

The designation of the PSI is '''TMS9901''', and this is the name that most users should be more familiar with.

== Features ==

The TMS 9901 Programmable Systems Interface is a multi-purpose circuit that is used in the TI-99/4A and the Geneve computer, and also on some peripheral cards like the Corcomp Floppy Disk Controller.

The 9901 has three main usage modes:

* Input/Output ports
* Interrupt prioritizing
* Timer

The I/O ports are mainly used for scanning the keyboard and joysticks, while the timer is used for cassette data encoding and decoding. The interrupt prioritizer is only used for the video interrupt which is routed from the VDP to the CPU through the 9901.

== Package ==

This is the pin assignment according to the 9901 specification.

[[File:Pack9901.png|300px|left]]

You can see pins of related functions marked by the same background color.

Orange: Interrupt inputs

Red: CRU bit selection (00000 - 11111, i.e. 0-31 decimal)

Blue: CRU interface

Violet: I/O ports

Yellow: Outgoing interrupt and level

Note that some pins have a double function, or in other words, two functions share the same pin. I will discuss this in the following sections.

<div style="clear:both"></div>

== Input/Output port operation ==

The simplest way of working with the 9901 is input/output operation with the ports. The 9901 has 16 configurable ports that can be individually used as inputs or outputs: P0 to P15.

=== Px port as input ===

[[File:Port9901in.png|250px]]

The power-on preset for every port is input. If you want to probe the P2 status (bit 18), use

CLR R12
TB 18
JEQ P2ACT

TB copies the bit at the given CRU address into the Equal bit of the status register. JEQ will jump to the location when this input has a high level. The maximum input current is 100 µA. You should protect the input with a resistor; [[#Safety_precautions | see below]] for a more detailed discussion.

If you want to read all 16 ports, use the STCR instruction:

LI R12,32
STCR R1,0

Note that the CRU base address in R12 advances in steps of 2, so bit 16 is on address 32. Also, for reading 16 bits, you must specify a count of 0.

The 9901 offers some more inputs than the 16 ports; we can use the interrupt inputs as well. More about that can be found in the section about the [[#Interrupt_mode| interrupt mode]].

=== Px port as output ===

[[File:Port9901out.png|250px]]

Once you write a value to the CRU address of a 9901 port, this port switches to output mode. The value written to the port is the value that is shown on its pin. If we want to output a 1 on P6, we have to use

CLR R12
SBO 22

If we wanted to output a 0, SBZ would have to be used. In order to set several ports in one go, use LDCR.

We can also read the output port just by using TB as usual (or STCR for several ports at once).

CLR R12
SBO 22
TB 22
JEQ EXPECT

The TB operation should return the 1 which the previous SBO has set.

You '''cannot''' switch back to input mode. This is only possible by resetting the 9901, either using the /RST1 input line, or by setting the /RST2 bit (bit 15) to 0 in clock mode.

== Interrupt mode ==

In interrupt mode, bits 1 to 15 are used to set the interrupt mask (write), or to query the interrupt inputs (read). That is, the meaning of reading and writing the bits is indeed different.

This schema shows how the interrupt inputs are used.

[[File:Int9901.png|600px]]

This illustration is slightly simplified; there is a latch between each interrupt input and the mask AND gate. This is not relevant for our programming, though. For more details see the [[#ref2 | TMS 9901 Programmable Systems Interface Data Manual]].

=== Checking the interrupt inputs ===

In general, every interrupt input can be read via CRU access:

CLR R12
TB 15
JEQ NOINT15

TB copies the bit at the specified CRU address to the Equal status bit. This means that JEQ jumps to the location when the bit is 1. Since all interrupt inputs are negative logic, reading a 1 means that there is no interrupt at this input (so I called it NOINT15).

If we want to read several interrupt inputs by a single instruction, we have to use STCR.

LI R12,16
STCR R1,8

This reads the states of the /INT8, /INT9, ..., /INT15 inputs and puts them in the most significant byte of R1. (See the specification of STCR and LDCR for transfers of up to 8 bits.)

=== Interrupt levels ===

Each interrupt input (/INT1 to /INT15) may be used to trigger an interrupt at another circuit, typically the CPU. For this purpose, the PSI offers an /INTREQ outgoing line. In the TI console, it is routed to the /INTREQ input of the TMS9900 CPU.

In addition there is a priority encoder, which is not shown here. This encoder outputs a 4-bit number which reflects the smallest number of the interrupt inputs where an interrupt has been sensed.

That is, if /INT4 and /INT7 are currently set to 0 (active), the priority encoder outputs (0100), which means 4.

The TMS9900 CPU can differentiate between these interrupt levels, and by using its LIMI command, we can set a threshold where interrupts are ignored. So when we use a LIMI 3, the interrupts of level 4, 5, 6 and higher will be ignored.

The bad news is that Texas Instruments did not use these priority lines in the TI console. In fact, these outputs (IC0 .. IC3) are not connected, and the respective interrupt level inputs at the CPU are hardwired to (0001), which means that every interrupt that occurs in the TI console is automatically set to level 1. So in order to block all interrupts from the 9901

LIMI 0

must be executed. To allow all,

LIMI 1

is sufficient. For some unclear reason, TI used LIMI 2 in all occasions.

=== Arming and disarming interrupts ===

As said above, every interrupt input can be read at any time in interrupt mode. In that sense, we don't really treat these inputs as interrupts inputs, but simply as input ports.

If we want a port to trigger an interrupt, we must arm this interrupt input. This is done by setting the respective bit to 1.

CLR R12
SBO 2

This enables interrupt input /INT2 to cause an /INTREQ when its input changes to 0. In the TI console, /INT2 is connected to the interrupt output of the VDP (video processor). If you want to block interrupts on that input, use SBZ.

It is a common misunderstanding that interrupts can be cleared by using a SBZ on an input. I also found this in the popular ''TI Intern'' book. Instead, SBZ n simply blocks interrupt input /INTn. In the case of the video processor, it is up to the VDP to clear its interrupt, and this is done by reading its status register.

Consequently, you '''cannot''' read the current mask setting of the 9901. What you get from reading are the input levels of the pins. So if you plan to change the mask bits temporarily, be aware that you cannot ask the 9901 to give you the current setting which you want to restore later. You will have to find out by another way.

== Counter mode ==

Besides the I/O capabilities, the PSI offers a "real-time" clock. This should not be understood as a precise timer with seconds, hundreds of seconds or other but as a countdown timer that is decremented every 64 CPU clock cycles.

This schematic is taken from the [[#ref1 |Osborne book]], redrawn by me in LibreOffice (and with added Load Buffer).

[[File:Clock9901.png|550px]]

=== Using the timer ===

There are basically two ways of using the countdown timer:

* Interval timer: Set the counter to a value; wait until the counter reaches zero. The PSI can be set up to raise an interrupt at that instant.
* Event timer: Set the counter to a value; do something and then read the counter value.

The counter has 14 bits; that is, its maximum value is 0x3FFF (16383). The counter is decremented every 64 clock cycles, and for the TI-99/4A and the Geneve with a clock cycle time of 333ns, this means that the counter resolution is 21.333 µs. The whole 16384 steps take 0.3495 seconds (349.5 ms).

When the counter reaches 0, it is reloaded from the load buffer, and counting continues.

It is essential to understand that the counter '''always''' counts down, independent of the mode. The specification says that the clock is enabled when a non-zero value is loaded into the load buffer, but tests on a real Geneve show that the clock decrements even when the load buffer is filled with 0.

=== Setting the timer ===

In order to set the load buffer and so to define the maximum counter value, we must switch to clock mode. This is achieved by setting bit 0 of the PSI to 1. In the TI/Geneve systems, the PSI is mapped to CRU base address 0, so we can do this

CLR R12
SBO 0

to enter '''clock mode'''. Using SBZ 0 returns to '''interrupt mode'''.

The effect of switching to clock mode is that the load buffer becomes accessible by the CRU addresses 1 to 14. Supposed that we want to load the buffer with the value 0x00FF, we may use these lines:

CLR R12
SBO 0
LI R1,>00FF
INCT R12
LDCR R1,14

As we see, we must change the CRU base. The LDCR operation always starts at the address defined in R12; if this is not 0, we have to set it here. Note, however, that the CRU address is always half of the R12 value, since the rightmost bit, A15, is not part of the address. If we want to start at bit 1, we must increase R12 by 2. This is, by the way, done wrong in several places in the literature where R12 is only set to 1.

We can combine the SBO and the LDCR to one operation if we define the rightmost bit of R1 as the bit 0 and the following bits as the timer value.

CLR R12
LI R1,>01FF (0000 0001 1111 1111)
LDCR R1,15

Do '''not''' write all 16 bits. The last bit will change bit 15 of the PSI, which is the /RST2 bit. When we are in clock mode, writing a 0 to the /RST2 bit resets all I/O ports. This means that all pins are set to inputs, and devices that rely on them as outputs may be turned off unintentionally.

=== Reading the timer ===

We are interested for the current value of the timer at some occasions. However, since the counter is constantly changing (every 64 clock cycles), reading from the active counter may deliver a wrong result. Think, for instance, about a value 0x2000, which is decremented after we read the first bits, we may end up with 0x2FFF (2 from 0x2000, FFF from 0x1FFF).

For this reason, the timer value is copied to a '''read buffer'''. This happens at every 64th clock cycle, when the counter is also decremented, but only when we are '''not''' in clock mode.

To read the buffer, we must set the PSI to clock mode first, which freezes the counter value in the read buffer. Then we can read the counter using STCR.

CLR R12
SBO 0
STCR R1,15
SRL R1,1
SBZ 0

As we see, register 1 will contain bit 0 in its rightmost bit, so we shift R1 by one position to move it out.

Do not forget to return to interrupt mode, or the buffer will not receive further updates.

As mentioned, bit 15 is the /RST2 bit when we write to it. For reading, bit 15 reflects the /INTREQ output.

=== The weird S0 input ===

There is one peculiarity with the PSI. When the input line S0 is set to 1, the clock mode is '''left temporarily''' - until S0 is 0 again, and bit 0 is 1. If bit 0 is 0, this has no effect, as the clock mode is never entered.

What is the reason for this?

TI obviously considered use cases where the PSI remains in clock mode for longer times, while the I/O ports must still be operated. The I/O ports are available on bits 16-31, which means that the S0 input is 1 for these addresses. So when we do a SBO 16, this is not related to the timer value, and thus should control the first I/O port. To allow this, the chip returns to interrupt/port mode for this operation, and when S0 is reset, returns to clock mode.

In the TI console, the S0-S4 inputs are directly connected with the address bus lines A10-A14. This has a strange side effect: Whenever address bus line A10 changes to 1, the clock mode is left temporarily, and this also happens for ordinary memory accesses.

Suppose that we are in clock mode (SBO 0). In this mode, the read buffer should not be updated, so when we read it, we should get the same value every time, although the real counter value is different. But this is difficult to achieve: If our program uses a memory address where A10 is 1 for some instruction, loading this instruction into the CPU will set A10 to 1, and thus leave clock mode, which updates the counter.

Therefore, you may have the impression that the read register continues to be updated even though you set bit 0 to 1. But this is only happening because your program extends over a location where A10 is 1. So if you want to prove that in clock mode the read register remains fixed, your program must avoid all memory locations where A10 is 1.

== Shared pins ==

Some pins have a double meaning; for example, pin 34 is labeled /INT7 / P15. How do we select the functions?

The shared pins are those for the interrupt inputs /INT7 to /INT15; they may also be used for P7 to P15 (in the opposite order).

If the Pn port is set to '''input''', the situation looks like this:

[[File:Shared9901in.png|250px]]

This means that both port and interrupt input have the same values; each one is a mirror of the other's state. We notice it by reading the bits of the associated CRU addresses, getting the same results. There is a difference, though: The interrupt input can be armed to trigger an outgoing interrupt, while the I/O port cannot.

In the other case, the Pn port is an '''output'''.

[[File:Shared9901out.png|250px]]

Is that possible? - Sure. The interrupt input will reflect the output of the port. When we set the port to 1, the interrupt input will get that 1 (same for 0). If we arm the interrupt input, setting the output port to 0 will trigger an interrupt via this input. The 9901 specification document recommends to disarm the interrupt trigger for the shared ports because of this possibly unwanted effect.

== Safety precautions ==

The TMS9901 PSI is an interrupt encoder and an I/O circuit. You may have heard that improper use of I/O circuits may damage the circuit so that it must be replaced. Is this possible with the 9901 as well? Is there a way to kill the 9901?

Short answer: Yes.

Longer answer: Yes, but it depends on the way how the ports are used.

If the port is used as an input, nothing bad will happen, since the ports have high input impedance. You can put 0V or 5V directly to the input; of course, you should not use excessive voltage.

=== How to damage the 9901 ports ===

The problem is when the port is configured as an output port. In that case it may output 0V (0) or 5V (1). When you connect the output to the opposite voltage, you will cause a short circuit which quickly exceeds the chip's maximum power dissipation of 750 mW. This means you will fry the chip.

Consider the following setup (but don't try it!).

[[File:Badport9901.png|300px]]

Obviously, port P4 is assumed to be an input. When the switch is open, port P4 will sense a 1 on its input. When the switch is closed, it will sense a 0.

Now what happens when you execute this code?

CLR R12
SBO 20

This will program port P4 to be an output, and to show a 1 (5V) at the output. SBZ will, in contrast, make this port output a 0. So how do you make it an input port? - This is done by resetting the chip. As long as you don't use a SBZ/SBO (or a LDCR) on the ports, the ports are inputs.

Nothing has happened up to now. But now imagine that you press the switch. This will put the 1 output to ground, causing the short circuit, and your 9901 is toast.

=== What about the TI console? ===

So can we damage the 9901 in the TI console by a suitable CRU operation? - Luckily not.

The reason is the way how TI used the ports on the mainboard. Most of the ports are configured as outputs. Nothing happens when you reset them to inputs.

* The pure interrupt inputs (/INT1 to /INT6) are safe, as they cannot output anything. They have no output driver that could be fried.
* P0 and P1 are not connected.
* P2, P3, and P4 are designed as outputs, so they cannot be turned from an input to an output.
* P5 is the selector of the Alpha Lock key, so output as well.
* P6 and P7 (/INT15) are the cassette motor control outputs.
* P8 (/INT14) is the audio gate output.
* P9 (/INT13) is the cassette output.
* P10 (/INT12) is pulled up to 5V via a 10 kOhm resistor. If you put a 0 on this port (5V), the maximum current is 500 µA, which results in a power dissipation of 2.5 mW (far below the maximum 750 mW).
* P11 (/INT11) is the cassette input. However, there is a resistor of 2.2 kOhm (R413) which effectively guards the port of high currents.
* P12, P13, P14, P15 (/INT10 ... /INT7) are the keyboard input lines. Again, we have pull-ups of 10 kOhm against +5V, but also 470 Ohm on the line, which means a maximum of 8.5 mA or 42.5 mW. This is still well below the maximum value.

So we see that resistors are the best way to protect the ports. And we may calm down; we cannot burn the 9901 in the TI console by a bug in our program.

== Literature ==

<span id="ref1">[1]</span> Texas Instruments: ''TMS 9901 Programmable Systems Interface Data Manual'', July 1977

<span id="ref2">[2]</span> Adam Osborne, Gerry Kane: ''Osborne 16-Bit Microprocessor Handbook / Includes 2900 Chip Slice Family''. Published by OSBORNE/McGraw-Hill 1975, 1981. ISBN 0-931988-43-8.

File:Pack9901.png

2022-04-23T13:57:54Z

Mizapf: Mizapf uploaded a new version of File:Pack9901.png

Programmable Systems Interface TMS 9901

2022-04-23T13:55:22Z

Mizapf: /* Counter mode */

The Programmable System Interface (PSI) is a circuit that is used on the TI-99/4A main board, on some expansion cards, and on the Geneve.

The designation of the PSI is '''TMS9901''', and this is the name that most users should be more familiar with.

== Features ==

The TMS 9901 Programmable Systems Interface is a multi-purpose circuit that is used in the TI-99/4A and the Geneve computer, and also on some peripheral cards like the Corcomp Floppy Disk Controller.

The 9901 has three main usage modes:

* Input/Output ports
* Interrupt prioritizing
* Timer

The I/O ports are mainly used for scanning the keyboard and joysticks, while the timer is used for cassette data encoding and decoding. The interrupt prioritizer is only used for the video interrupt which is routed from the VDP to the CPU through the 9901.

== Package ==

This is the pin assignment according to the 9901 specification.

[[File:Pack9901.png|300px|left]]

You can see pins of related functions marked by the same background color.

* Orange: Interrupt inputs
* Red: CRU bit selection (00000 - 11111, i.e. 0-31 decimal)
* Blue: CRU interface
* Violet: I/O ports
* Yellow: Outgoing interrupt and level

Note that some pins have a double function, or in other words, two functions share the same pin. I will discuss this in the following sections.

<div style="clear:both"></div>

== Input/Output port operation ==

The simplest way of working with the 9901 is input/output operation with the ports. The 9901 has 16 configurable ports that can be individually used as inputs or outputs: P0 to P15.

=== Px port as input ===

[[File:Port9901in.png|250px]]

The power-on preset for every port is input. If you want to probe the P2 status (bit 18), use

CLR R12
TB 18
JEQ P2ACT

TB copies the bit at the given CRU address into the Equal bit of the status register. JEQ will jump to the location when this input has a high level. The maximum input current is 100 µA. You should protect the input with a resistor; [[#Safety_precautions | see below]] for a more detailed discussion.

If you want to read all 16 ports, use the STCR instruction:

LI R12,32
STCR R1,0

Note that the CRU base address in R12 advances in steps of 2, so bit 16 is on address 32. Also, for reading 16 bits, you must specify a count of 0.

The 9901 offers some more inputs than the 16 ports; we can use the interrupt inputs as well. More about that can be found in the section about the [[#Interrupt_mode| interrupt mode]].

=== Px port as output ===

[[File:Port9901out.png|250px]]

Once you write a value to the CRU address of a 9901 port, this port switches to output mode. The value written to the port is the value that is shown on its pin. If we want to output a 1 on P6, we have to use

CLR R12
SBO 22

If we wanted to output a 0, SBZ would have to be used. In order to set several ports in one go, use LDCR.

We can also read the output port just by using TB as usual (or STCR for several ports at once).

CLR R12
SBO 22
TB 22
JEQ EXPECT

The TB operation should return the 1 which the previous SBO has set.

You '''cannot''' switch back to input mode. This is only possible by resetting the 9901, either using the /RST1 input line, or by setting the /RST2 bit (bit 15) to 0 in clock mode.

== Interrupt mode ==

In interrupt mode, bits 1 to 15 are used to set the interrupt mask (write), or to query the interrupt inputs (read). That is, the meaning of reading and writing the bits is indeed different.

This schema shows how the interrupt inputs are used.

[[File:Int9901.png|600px]]

This illustration is slightly simplified; there is a latch between each interrupt input and the mask AND gate. This is not relevant for our programming, though. For more details see the [[#ref2 | TMS 9901 Programmable Systems Interface Data Manual]].

=== Checking the interrupt inputs ===

In general, every interrupt input can be read via CRU access:

CLR R12
TB 15
JEQ NOINT15

TB copies the bit at the specified CRU address to the Equal status bit. This means that JEQ jumps to the location when the bit is 1. Since all interrupt inputs are negative logic, reading a 1 means that there is no interrupt at this input (so I called it NOINT15).

If we want to read several interrupt inputs by a single instruction, we have to use STCR.

LI R12,16
STCR R1,8

This reads the states of the /INT8, /INT9, ..., /INT15 inputs and puts them in the most significant byte of R1. (See the specification of STCR and LDCR for transfers of up to 8 bits.)

=== Interrupt levels ===

Each interrupt input (/INT1 to /INT15) may be used to trigger an interrupt at another circuit, typically the CPU. For this purpose, the PSI offers an /INTREQ outgoing line. In the TI console, it is routed to the /INTREQ input of the TMS9900 CPU.

In addition there is a priority encoder, which is not shown here. This encoder outputs a 4-bit number which reflects the smallest number of the interrupt inputs where an interrupt has been sensed.

That is, if /INT4 and /INT7 are currently set to 0 (active), the priority encoder outputs (0100), which means 4.

The TMS9900 CPU can differentiate between these interrupt levels, and by using its LIMI command, we can set a threshold where interrupts are ignored. So when we use a LIMI 3, the interrupts of level 4, 5, 6 and higher will be ignored.

The bad news is that Texas Instruments did not use these priority lines in the TI console. In fact, these outputs (IC0 .. IC3) are not connected, and the respective interrupt level inputs at the CPU are hardwired to (0001), which means that every interrupt that occurs in the TI console is automatically set to level 1. So in order to block all interrupts from the 9901

LIMI 0

must be executed. To allow all,

LIMI 1

is sufficient. For some unclear reason, TI used LIMI 2 in all occasions.

=== Arming and disarming interrupts ===

As said above, every interrupt input can be read at any time in interrupt mode. In that sense, we don't really treat these inputs as interrupts inputs, but simply as input ports.

If we want a port to trigger an interrupt, we must arm this interrupt input. This is done by setting the respective bit to 1.

CLR R12
SBO 2

This enables interrupt input /INT2 to cause an /INTREQ when its input changes to 0. In the TI console, /INT2 is connected to the interrupt output of the VDP (video processor). If you want to block interrupts on that input, use SBZ.

It is a common misunderstanding that interrupts can be cleared by using a SBZ on an input. I also found this in the popular ''TI Intern'' book. Instead, SBZ n simply blocks interrupt input /INTn. In the case of the video processor, it is up to the VDP to clear its interrupt, and this is done by reading its status register.

Consequently, you '''cannot''' read the current mask setting of the 9901. What you get from reading are the input levels of the pins. So if you plan to change the mask bits temporarily, be aware that you cannot ask the 9901 to give you the current setting which you want to restore later. You will have to find out by another way.

== Counter mode ==

Besides the I/O capabilities, the PSI offers a "real-time" clock. This should not be understood as a precise timer with seconds, hundreds of seconds or other but as a countdown timer that is decremented every 64 CPU clock cycles.

This schematic is taken from the [[#ref1 |Osborne book]], redrawn by me in LibreOffice (and with added Load Buffer).

[[File:Clock9901.png|550px]]

=== Using the timer ===

There are basically two ways of using the countdown timer:

* Interval timer: Set the counter to a value; wait until the counter reaches zero. The PSI can be set up to raise an interrupt at that instant.
* Event timer: Set the counter to a value; do something and then read the counter value.

The counter has 14 bits; that is, its maximum value is 0x3FFF (16383). The counter is decremented every 64 clock cycles, and for the TI-99/4A and the Geneve with a clock cycle time of 333ns, this means that the counter resolution is 21.333 µs. The whole 16384 steps take 0.3495 seconds (349.5 ms).

When the counter reaches 0, it is reloaded from the load buffer, and counting continues.

It is essential to understand that the counter '''always''' counts down, independent of the mode. The specification says that the clock is enabled when a non-zero value is loaded into the load buffer, but tests on a real Geneve show that the clock decrements even when the load buffer is filled with 0.

=== Setting the timer ===

In order to set the load buffer and so to define the maximum counter value, we must switch to clock mode. This is achieved by setting bit 0 of the PSI to 1. In the TI/Geneve systems, the PSI is mapped to CRU base address 0, so we can do this

CLR R12
SBO 0

to enter '''clock mode'''. Using SBZ 0 returns to '''interrupt mode'''.

The effect of switching to clock mode is that the load buffer becomes accessible by the CRU addresses 1 to 14. Supposed that we want to load the buffer with the value 0x00FF, we may use these lines:

CLR R12
SBO 0
LI R1,>00FF
INCT R12
LDCR R1,14

As we see, we must change the CRU base. The LDCR operation always starts at the address defined in R12; if this is not 0, we have to set it here. Note, however, that the CRU address is always half of the R12 value, since the rightmost bit, A15, is not part of the address. If we want to start at bit 1, we must increase R12 by 2. This is, by the way, done wrong in several places in the literature where R12 is only set to 1.

We can combine the SBO and the LDCR to one operation if we define the rightmost bit of R1 as the bit 0 and the following bits as the timer value.

CLR R12
LI R1,>01FF (0000 0001 1111 1111)
LDCR R1,15

Do '''not''' write all 16 bits. The last bit will change bit 15 of the PSI, which is the /RST2 bit. When we are in clock mode, writing a 0 to the /RST2 bit resets all I/O ports. This means that all pins are set to inputs, and devices that rely on them as outputs may be turned off unintentionally.

=== Reading the timer ===

We are interested for the current value of the timer at some occasions. However, since the counter is constantly changing (every 64 clock cycles), reading from the active counter may deliver a wrong result. Think, for instance, about a value 0x2000, which is decremented after we read the first bits, we may end up with 0x2FFF (2 from 0x2000, FFF from 0x1FFF).

For this reason, the timer value is copied to a '''read buffer'''. This happens at every 64th clock cycle, when the counter is also decremented, but only when we are '''not''' in clock mode.

To read the buffer, we must set the PSI to clock mode first, which freezes the counter value in the read buffer. Then we can read the counter using STCR.

CLR R12
SBO 0
STCR R1,15
SRL R1,1
SBZ 0

As we see, register 1 will contain bit 0 in its rightmost bit, so we shift R1 by one position to move it out.

Do not forget to return to interrupt mode, or the buffer will not receive further updates.

As mentioned, bit 15 is the /RST2 bit when we write to it. For reading, bit 15 reflects the /INTREQ output.

=== The weird S0 input ===

There is one peculiarity with the PSI. When the input line S0 is set to 1, the clock mode is '''left temporarily''' - until S0 is 0 again, and bit 0 is 1. If bit 0 is 0, this has no effect, as the clock mode is never entered.

What is the reason for this?

TI obviously considered use cases where the PSI remains in clock mode for longer times, while the I/O ports must still be operated. The I/O ports are available on bits 16-31, which means that the S0 input is 1 for these addresses. So when we do a SBO 16, this is not related to the timer value, and thus should control the first I/O port. To allow this, the chip returns to interrupt/port mode for this operation, and when S0 is reset, returns to clock mode.

In the TI console, the S0-S4 inputs are directly connected with the address bus lines A10-A14. This has a strange side effect: Whenever address bus line A10 changes to 1, the clock mode is left temporarily, and this also happens for ordinary memory accesses.

Suppose that we are in clock mode (SBO 0). In this mode, the read buffer should not be updated, so when we read it, we should get the same value every time, although the real counter value is different. But this is difficult to achieve: If our program uses a memory address where A10 is 1 for some instruction, loading this instruction into the CPU will set A10 to 1, and thus leave clock mode, which updates the counter.

Therefore, you may have the impression that the read register continues to be updated even though you set bit 0 to 1. But this is only happening because your program extends over a location where A10 is 1. So if you want to prove that in clock mode the read register remains fixed, your program must avoid all memory locations where A10 is 1.

== Shared pins ==

Some pins have a double meaning; for example, pin 34 is labeled /INT7 / P15. How do we select the functions?

The shared pins are those for the interrupt inputs /INT7 to /INT15; they may also be used for P7 to P15 (in the opposite order).

If the Pn port is set to '''input''', the situation looks like this:

[[File:Shared9901in.png|250px]]

This means that both port and interrupt input have the same values; each one is a mirror of the other's state. We notice it by reading the bits of the associated CRU addresses, getting the same results. There is a difference, though: The interrupt input can be armed to trigger an outgoing interrupt, while the I/O port cannot.

In the other case, the Pn port is an '''output'''.

[[File:Shared9901out.png|250px]]

Is that possible? - Sure. The interrupt input will reflect the output of the port. When we set the port to 1, the interrupt input will get that 1 (same for 0). If we arm the interrupt input, setting the output port to 0 will trigger an interrupt via this input. The 9901 specification document recommends to disarm the interrupt trigger for the shared ports because of this possibly unwanted effect.

== Safety precautions ==

The TMS9901 PSI is an interrupt encoder and an I/O circuit. You may have heard that improper use of I/O circuits may damage the circuit so that it must be replaced. Is this possible with the 9901 as well? Is there a way to kill the 9901?

Short answer: Yes.

Longer answer: Yes, but it depends on the way how the ports are used.

If the port is used as an input, nothing bad will happen, since the ports have high input impedance. You can put 0V or 5V directly to the input; of course, you should not use excessive voltage.

=== How to damage the 9901 ports ===

The problem is when the port is configured as an output port. In that case it may output 0V (0) or 5V (1). When you connect the output to the opposite voltage, you will cause a short circuit which quickly exceeds the chip's maximum power dissipation of 750 mW. This means you will fry the chip.

Consider the following setup (but don't try it!).

[[File:Badport9901.png|300px]]

Obviously, port P4 is assumed to be an input. When the switch is open, port P4 will sense a 1 on its input. When the switch is closed, it will sense a 0.

Now what happens when you execute this code?

CLR R12
SBO 20

This will program port P4 to be an output, and to show a 1 (5V) at the output. SBZ will, in contrast, make this port output a 0. So how do you make it an input port? - This is done by resetting the chip. As long as you don't use a SBZ/SBO (or a LDCR) on the ports, the ports are inputs.

Nothing has happened up to now. But now imagine that you press the switch. This will put the 1 output to ground, causing the short circuit, and your 9901 is toast.

=== What about the TI console? ===

So can we damage the 9901 in the TI console by a suitable CRU operation? - Luckily not.

The reason is the way how TI used the ports on the mainboard. Most of the ports are configured as outputs. Nothing happens when you reset them to inputs.

* The pure interrupt inputs (/INT1 to /INT6) are safe, as they cannot output anything. They have no output driver that could be fried.
* P0 and P1 are not connected.
* P2, P3, and P4 are designed as outputs, so they cannot be turned from an input to an output.
* P5 is the selector of the Alpha Lock key, so output as well.
* P6 and P7 (/INT15) are the cassette motor control outputs.
* P8 (/INT14) is the audio gate output.
* P9 (/INT13) is the cassette output.
* P10 (/INT12) is pulled up to 5V via a 10 kOhm resistor. If you put a 0 on this port (5V), the maximum current is 500 µA, which results in a power dissipation of 2.5 mW (far below the maximum 750 mW).
* P11 (/INT11) is the cassette input. However, there is a resistor of 2.2 kOhm (R413) which effectively guards the port of high currents.
* P12, P13, P14, P15 (/INT10 ... /INT7) are the keyboard input lines. Again, we have pull-ups of 10 kOhm against +5V, but also 470 Ohm on the line, which means a maximum of 8.5 mA or 42.5 mW. This is still well below the maximum value.

So we see that resistors are the best way to protect the ports. And we may calm down; we cannot burn the 9901 in the TI console by a bug in our program.

== Literature ==

<span id="ref1">[1]</span> Texas Instruments: ''TMS 9901 Programmable Systems Interface Data Manual'', July 1977

<span id="ref2">[2]</span> Adam Osborne, Gerry Kane: ''Osborne 16-Bit Microprocessor Handbook / Includes 2900 Chip Slice Family''. Published by OSBORNE/McGraw-Hill 1975, 1981. ISBN 0-931988-43-8.

Programmable Systems Interface TMS 9901

2022-04-23T13:54:48Z

Mizapf: /* Interrupt mode */

The Programmable System Interface (PSI) is a circuit that is used on the TI-99/4A main board, on some expansion cards, and on the Geneve.

The designation of the PSI is '''TMS9901''', and this is the name that most users should be more familiar with.

== Features ==

The TMS 9901 Programmable Systems Interface is a multi-purpose circuit that is used in the TI-99/4A and the Geneve computer, and also on some peripheral cards like the Corcomp Floppy Disk Controller.

The 9901 has three main usage modes:

* Input/Output ports
* Interrupt prioritizing
* Timer

The I/O ports are mainly used for scanning the keyboard and joysticks, while the timer is used for cassette data encoding and decoding. The interrupt prioritizer is only used for the video interrupt which is routed from the VDP to the CPU through the 9901.

== Package ==

This is the pin assignment according to the 9901 specification.

[[File:Pack9901.png|300px|left]]

You can see pins of related functions marked by the same background color.

* Orange: Interrupt inputs
* Red: CRU bit selection (00000 - 11111, i.e. 0-31 decimal)
* Blue: CRU interface
* Violet: I/O ports
* Yellow: Outgoing interrupt and level

Note that some pins have a double function, or in other words, two functions share the same pin. I will discuss this in the following sections.

<div style="clear:both"></div>

== Input/Output port operation ==

The simplest way of working with the 9901 is input/output operation with the ports. The 9901 has 16 configurable ports that can be individually used as inputs or outputs: P0 to P15.

=== Px port as input ===

[[File:Port9901in.png|250px]]

The power-on preset for every port is input. If you want to probe the P2 status (bit 18), use

CLR R12
TB 18
JEQ P2ACT

TB copies the bit at the given CRU address into the Equal bit of the status register. JEQ will jump to the location when this input has a high level. The maximum input current is 100 µA. You should protect the input with a resistor; [[#Safety_precautions | see below]] for a more detailed discussion.

If you want to read all 16 ports, use the STCR instruction:

LI R12,32
STCR R1,0

Note that the CRU base address in R12 advances in steps of 2, so bit 16 is on address 32. Also, for reading 16 bits, you must specify a count of 0.

The 9901 offers some more inputs than the 16 ports; we can use the interrupt inputs as well. More about that can be found in the section about the [[#Interrupt_mode| interrupt mode]].

=== Px port as output ===

[[File:Port9901out.png|250px]]

Once you write a value to the CRU address of a 9901 port, this port switches to output mode. The value written to the port is the value that is shown on its pin. If we want to output a 1 on P6, we have to use

CLR R12
SBO 22

If we wanted to output a 0, SBZ would have to be used. In order to set several ports in one go, use LDCR.

We can also read the output port just by using TB as usual (or STCR for several ports at once).

CLR R12
SBO 22
TB 22
JEQ EXPECT

The TB operation should return the 1 which the previous SBO has set.

You '''cannot''' switch back to input mode. This is only possible by resetting the 9901, either using the /RST1 input line, or by setting the /RST2 bit (bit 15) to 0 in clock mode.

== Interrupt mode ==

In interrupt mode, bits 1 to 15 are used to set the interrupt mask (write), or to query the interrupt inputs (read). That is, the meaning of reading and writing the bits is indeed different.

This schema shows how the interrupt inputs are used.

[[File:Int9901.png|600px]]

This illustration is slightly simplified; there is a latch between each interrupt input and the mask AND gate. This is not relevant for our programming, though. For more details see the [[#ref2 | TMS 9901 Programmable Systems Interface Data Manual]].

=== Checking the interrupt inputs ===

In general, every interrupt input can be read via CRU access:

CLR R12
TB 15
JEQ NOINT15

TB copies the bit at the specified CRU address to the Equal status bit. This means that JEQ jumps to the location when the bit is 1. Since all interrupt inputs are negative logic, reading a 1 means that there is no interrupt at this input (so I called it NOINT15).

If we want to read several interrupt inputs by a single instruction, we have to use STCR.

LI R12,16
STCR R1,8

This reads the states of the /INT8, /INT9, ..., /INT15 inputs and puts them in the most significant byte of R1. (See the specification of STCR and LDCR for transfers of up to 8 bits.)

=== Interrupt levels ===

Each interrupt input (/INT1 to /INT15) may be used to trigger an interrupt at another circuit, typically the CPU. For this purpose, the PSI offers an /INTREQ outgoing line. In the TI console, it is routed to the /INTREQ input of the TMS9900 CPU.

In addition there is a priority encoder, which is not shown here. This encoder outputs a 4-bit number which reflects the smallest number of the interrupt inputs where an interrupt has been sensed.

That is, if /INT4 and /INT7 are currently set to 0 (active), the priority encoder outputs (0100), which means 4.

The TMS9900 CPU can differentiate between these interrupt levels, and by using its LIMI command, we can set a threshold where interrupts are ignored. So when we use a LIMI 3, the interrupts of level 4, 5, 6 and higher will be ignored.

The bad news is that Texas Instruments did not use these priority lines in the TI console. In fact, these outputs (IC0 .. IC3) are not connected, and the respective interrupt level inputs at the CPU are hardwired to (0001), which means that every interrupt that occurs in the TI console is automatically set to level 1. So in order to block all interrupts from the 9901

LIMI 0

must be executed. To allow all,

LIMI 1

is sufficient. For some unclear reason, TI used LIMI 2 in all occasions.

=== Arming and disarming interrupts ===

As said above, every interrupt input can be read at any time in interrupt mode. In that sense, we don't really treat these inputs as interrupts inputs, but simply as input ports.

If we want a port to trigger an interrupt, we must arm this interrupt input. This is done by setting the respective bit to 1.

CLR R12
SBO 2

This enables interrupt input /INT2 to cause an /INTREQ when its input changes to 0. In the TI console, /INT2 is connected to the interrupt output of the VDP (video processor). If you want to block interrupts on that input, use SBZ.

It is a common misunderstanding that interrupts can be cleared by using a SBZ on an input. I also found this in the popular ''TI Intern'' book. Instead, SBZ n simply blocks interrupt input /INTn. In the case of the video processor, it is up to the VDP to clear its interrupt, and this is done by reading its status register.

Consequently, you '''cannot''' read the current mask setting of the 9901. What you get from reading are the input levels of the pins. So if you plan to change the mask bits temporarily, be aware that you cannot ask the 9901 to give you the current setting which you want to restore later. You will have to find out by another way.

== Counter mode ==

Besides the I/O capabilities, the PSI offers a "real-time" clock. This should not be understood as a precise timer with seconds, hundreds of seconds or other but as a countdown timer that is decremented every 64 CPU clock cycles.

This schematic is taken from the Osborne book, redrawn by me in LibreOffice (and with added Load Buffer).

[[File:Clock9901.png|550px]]

=== Using the timer ===

There are basically two ways of using the countdown timer:

* Interval timer: Set the counter to a value; wait until the counter reaches zero. The PSI can be set up to raise an interrupt at that instant.
* Event timer: Set the counter to a value; do something and then read the counter value.

The counter has 14 bits; that is, its maximum value is 0x3FFF (16383). The counter is decremented every 64 clock cycles, and for the TI-99/4A and the Geneve with a clock cycle time of 333ns, this means that the counter resolution is 21.333 µs. The whole 16384 steps take 0.3495 seconds (349.5 ms).

When the counter reaches 0, it is reloaded from the load buffer, and counting continues.

It is essential to understand that the counter '''always''' counts down, independent of the mode. The specification says that the clock is enabled when a non-zero value is loaded into the load buffer, but tests on a real Geneve show that the clock decrements even when the load buffer is filled with 0.

=== Setting the timer ===

In order to set the load buffer and so to define the maximum counter value, we must switch to clock mode. This is achieved by setting bit 0 of the PSI to 1. In the TI/Geneve systems, the PSI is mapped to CRU base address 0, so we can do this

CLR R12
SBO 0

to enter '''clock mode'''. Using SBZ 0 returns to '''interrupt mode'''.

The effect of switching to clock mode is that the load buffer becomes accessible by the CRU addresses 1 to 14. Supposed that we want to load the buffer with the value 0x00FF, we may use these lines:

CLR R12
SBO 0
LI R1,>00FF
INCT R12
LDCR R1,14

As we see, we must change the CRU base. The LDCR operation always starts at the address defined in R12; if this is not 0, we have to set it here. Note, however, that the CRU address is always half of the R12 value, since the rightmost bit, A15, is not part of the address. If we want to start at bit 1, we must increase R12 by 2. This is, by the way, done wrong in several places in the literature where R12 is only set to 1.

We can combine the SBO and the LDCR to one operation if we define the rightmost bit of R1 as the bit 0 and the following bits as the timer value.

CLR R12
LI R1,>01FF (0000 0001 1111 1111)
LDCR R1,15

Do '''not''' write all 16 bits. The last bit will change bit 15 of the PSI, which is the /RST2 bit. When we are in clock mode, writing a 0 to the /RST2 bit resets all I/O ports. This means that all pins are set to inputs, and devices that rely on them as outputs may be turned off unintentionally.

=== Reading the timer ===

We are interested for the current value of the timer at some occasions. However, since the counter is constantly changing (every 64 clock cycles), reading from the active counter may deliver a wrong result. Think, for instance, about a value 0x2000, which is decremented after we read the first bits, we may end up with 0x2FFF (2 from 0x2000, FFF from 0x1FFF).

For this reason, the timer value is copied to a '''read buffer'''. This happens at every 64th clock cycle, when the counter is also decremented, but only when we are '''not''' in clock mode.

To read the buffer, we must set the PSI to clock mode first, which freezes the counter value in the read buffer. Then we can read the counter using STCR.

CLR R12
SBO 0
STCR R1,15
SRL R1,1
SBZ 0

As we see, register 1 will contain bit 0 in its rightmost bit, so we shift R1 by one position to move it out.

Do not forget to return to interrupt mode, or the buffer will not receive further updates.

As mentioned, bit 15 is the /RST2 bit when we write to it. For reading, bit 15 reflects the /INTREQ output.

=== The weird S0 input ===

There is one peculiarity with the PSI. When the input line S0 is set to 1, the clock mode is '''left temporarily''' - until S0 is 0 again, and bit 0 is 1. If bit 0 is 0, this has no effect, as the clock mode is never entered.

What is the reason for this?

TI obviously considered use cases where the PSI remains in clock mode for longer times, while the I/O ports must still be operated. The I/O ports are available on bits 16-31, which means that the S0 input is 1 for these addresses. So when we do a SBO 16, this is not related to the timer value, and thus should control the first I/O port. To allow this, the chip returns to interrupt/port mode for this operation, and when S0 is reset, returns to clock mode.

In the TI console, the S0-S4 inputs are directly connected with the address bus lines A10-A14. This has a strange side effect: Whenever address bus line A10 changes to 1, the clock mode is left temporarily, and this also happens for ordinary memory accesses.

Suppose that we are in clock mode (SBO 0). In this mode, the read buffer should not be updated, so when we read it, we should get the same value every time, although the real counter value is different. But this is difficult to achieve: If our program uses a memory address where A10 is 1 for some instruction, loading this instruction into the CPU will set A10 to 1, and thus leave clock mode, which updates the counter.

Therefore, you may have the impression that the read register continues to be updated even though you set bit 0 to 1. But this is only happening because your program extends over a location where A10 is 1. So if you want to prove that in clock mode the read register remains fixed, your program must avoid all memory locations where A10 is 1.

== Shared pins ==

Some pins have a double meaning; for example, pin 34 is labeled /INT7 / P15. How do we select the functions?

The shared pins are those for the interrupt inputs /INT7 to /INT15; they may also be used for P7 to P15 (in the opposite order).

If the Pn port is set to '''input''', the situation looks like this:

[[File:Shared9901in.png|250px]]

This means that both port and interrupt input have the same values; each one is a mirror of the other's state. We notice it by reading the bits of the associated CRU addresses, getting the same results. There is a difference, though: The interrupt input can be armed to trigger an outgoing interrupt, while the I/O port cannot.

In the other case, the Pn port is an '''output'''.

[[File:Shared9901out.png|250px]]

Is that possible? - Sure. The interrupt input will reflect the output of the port. When we set the port to 1, the interrupt input will get that 1 (same for 0). If we arm the interrupt input, setting the output port to 0 will trigger an interrupt via this input. The 9901 specification document recommends to disarm the interrupt trigger for the shared ports because of this possibly unwanted effect.

== Safety precautions ==

The TMS9901 PSI is an interrupt encoder and an I/O circuit. You may have heard that improper use of I/O circuits may damage the circuit so that it must be replaced. Is this possible with the 9901 as well? Is there a way to kill the 9901?

Short answer: Yes.

Longer answer: Yes, but it depends on the way how the ports are used.

If the port is used as an input, nothing bad will happen, since the ports have high input impedance. You can put 0V or 5V directly to the input; of course, you should not use excessive voltage.

=== How to damage the 9901 ports ===

The problem is when the port is configured as an output port. In that case it may output 0V (0) or 5V (1). When you connect the output to the opposite voltage, you will cause a short circuit which quickly exceeds the chip's maximum power dissipation of 750 mW. This means you will fry the chip.

Consider the following setup (but don't try it!).

[[File:Badport9901.png|300px]]

Obviously, port P4 is assumed to be an input. When the switch is open, port P4 will sense a 1 on its input. When the switch is closed, it will sense a 0.

Now what happens when you execute this code?

CLR R12
SBO 20

This will program port P4 to be an output, and to show a 1 (5V) at the output. SBZ will, in contrast, make this port output a 0. So how do you make it an input port? - This is done by resetting the chip. As long as you don't use a SBZ/SBO (or a LDCR) on the ports, the ports are inputs.

Nothing has happened up to now. But now imagine that you press the switch. This will put the 1 output to ground, causing the short circuit, and your 9901 is toast.

=== What about the TI console? ===

So can we damage the 9901 in the TI console by a suitable CRU operation? - Luckily not.

The reason is the way how TI used the ports on the mainboard. Most of the ports are configured as outputs. Nothing happens when you reset them to inputs.

* The pure interrupt inputs (/INT1 to /INT6) are safe, as they cannot output anything. They have no output driver that could be fried.
* P0 and P1 are not connected.
* P2, P3, and P4 are designed as outputs, so they cannot be turned from an input to an output.
* P5 is the selector of the Alpha Lock key, so output as well.
* P6 and P7 (/INT15) are the cassette motor control outputs.
* P8 (/INT14) is the audio gate output.
* P9 (/INT13) is the cassette output.
* P10 (/INT12) is pulled up to 5V via a 10 kOhm resistor. If you put a 0 on this port (5V), the maximum current is 500 µA, which results in a power dissipation of 2.5 mW (far below the maximum 750 mW).
* P11 (/INT11) is the cassette input. However, there is a resistor of 2.2 kOhm (R413) which effectively guards the port of high currents.
* P12, P13, P14, P15 (/INT10 ... /INT7) are the keyboard input lines. Again, we have pull-ups of 10 kOhm against +5V, but also 470 Ohm on the line, which means a maximum of 8.5 mA or 42.5 mW. This is still well below the maximum value.

So we see that resistors are the best way to protect the ports. And we may calm down; we cannot burn the 9901 in the TI console by a bug in our program.

== Literature ==

<span id="ref1">[1]</span> Texas Instruments: ''TMS 9901 Programmable Systems Interface Data Manual'', July 1977

<span id="ref2">[2]</span> Adam Osborne, Gerry Kane: ''Osborne 16-Bit Microprocessor Handbook / Includes 2900 Chip Slice Family''. Published by OSBORNE/McGraw-Hill 1975, 1981. ISBN 0-931988-43-8.

Programmable Systems Interface TMS 9901

2022-04-23T13:53:57Z

Mizapf: /* Literature */

The Programmable System Interface (PSI) is a circuit that is used on the TI-99/4A main board, on some expansion cards, and on the Geneve.

The designation of the PSI is '''TMS9901''', and this is the name that most users should be more familiar with.

== Features ==

The TMS 9901 Programmable Systems Interface is a multi-purpose circuit that is used in the TI-99/4A and the Geneve computer, and also on some peripheral cards like the Corcomp Floppy Disk Controller.

The 9901 has three main usage modes:

* Input/Output ports
* Interrupt prioritizing
* Timer

The I/O ports are mainly used for scanning the keyboard and joysticks, while the timer is used for cassette data encoding and decoding. The interrupt prioritizer is only used for the video interrupt which is routed from the VDP to the CPU through the 9901.

== Package ==

This is the pin assignment according to the 9901 specification.

[[File:Pack9901.png|300px|left]]

You can see pins of related functions marked by the same background color.

* Orange: Interrupt inputs
* Red: CRU bit selection (00000 - 11111, i.e. 0-31 decimal)
* Blue: CRU interface
* Violet: I/O ports
* Yellow: Outgoing interrupt and level

Note that some pins have a double function, or in other words, two functions share the same pin. I will discuss this in the following sections.

<div style="clear:both"></div>

== Input/Output port operation ==

The simplest way of working with the 9901 is input/output operation with the ports. The 9901 has 16 configurable ports that can be individually used as inputs or outputs: P0 to P15.

=== Px port as input ===

[[File:Port9901in.png|250px]]

The power-on preset for every port is input. If you want to probe the P2 status (bit 18), use

CLR R12
TB 18
JEQ P2ACT

TB copies the bit at the given CRU address into the Equal bit of the status register. JEQ will jump to the location when this input has a high level. The maximum input current is 100 µA. You should protect the input with a resistor; [[#Safety_precautions | see below]] for a more detailed discussion.

If you want to read all 16 ports, use the STCR instruction:

LI R12,32
STCR R1,0

Note that the CRU base address in R12 advances in steps of 2, so bit 16 is on address 32. Also, for reading 16 bits, you must specify a count of 0.

The 9901 offers some more inputs than the 16 ports; we can use the interrupt inputs as well. More about that can be found in the section about the [[#Interrupt_mode| interrupt mode]].

=== Px port as output ===

[[File:Port9901out.png|250px]]

Once you write a value to the CRU address of a 9901 port, this port switches to output mode. The value written to the port is the value that is shown on its pin. If we want to output a 1 on P6, we have to use

CLR R12
SBO 22

If we wanted to output a 0, SBZ would have to be used. In order to set several ports in one go, use LDCR.

We can also read the output port just by using TB as usual (or STCR for several ports at once).

CLR R12
SBO 22
TB 22
JEQ EXPECT

The TB operation should return the 1 which the previous SBO has set.

You '''cannot''' switch back to input mode. This is only possible by resetting the 9901, either using the /RST1 input line, or by setting the /RST2 bit (bit 15) to 0 in clock mode.

== Interrupt mode ==

In interrupt mode, bits 1 to 15 are used to set the interrupt mask (write), or to query the interrupt inputs (read). That is, the meaning of reading and writing the bits is indeed different.

This schema shows how the interrupt inputs are used.

[[File:Int9901.png|600px]]

This illustration is slightly simplified; there is a latch between each interrupt input and the mask AND gate. This is not relevant for our programming, though. For more details see the ''TMS 9901 Programmable Systems Interface Data Manual''.

=== Checking the interrupt inputs ===

In general, every interrupt input can be read via CRU access:

CLR R12
TB 15
JEQ NOINT15

TB copies the bit at the specified CRU address to the Equal status bit. This means that JEQ jumps to the location when the bit is 1. Since all interrupt inputs are negative logic, reading a 1 means that there is no interrupt at this input (so I called it NOINT15).

If we want to read several interrupt inputs by a single instruction, we have to use STCR.

LI R12,16
STCR R1,8

This reads the states of the /INT8, /INT9, ..., /INT15 inputs and puts them in the most significant byte of R1. (See the specification of STCR and LDCR for transfers of up to 8 bits.)

=== Interrupt levels ===

Each interrupt input (/INT1 to /INT15) may be used to trigger an interrupt at another circuit, typically the CPU. For this purpose, the PSI offers an /INTREQ outgoing line. In the TI console, it is routed to the /INTREQ input of the TMS9900 CPU.

In addition there is a priority encoder, which is not shown here. This encoder outputs a 4-bit number which reflects the smallest number of the interrupt inputs where an interrupt has been sensed.

That is, if /INT4 and /INT7 are currently set to 0 (active), the priority encoder outputs (0100), which means 4.

The TMS9900 CPU can differentiate between these interrupt levels, and by using its LIMI command, we can set a threshold where interrupts are ignored. So when we use a LIMI 3, the interrupts of level 4, 5, 6 and higher will be ignored.

The bad news is that Texas Instruments did not use these priority lines in the TI console. In fact, these outputs (IC0 .. IC3) are not connected, and the respective interrupt level inputs at the CPU are hardwired to (0001), which means that every interrupt that occurs in the TI console is automatically set to level 1. So in order to block all interrupts from the 9901

LIMI 0

must be executed. To allow all,

LIMI 1

is sufficient. For some unclear reason, TI used LIMI 2 in all occasions.

=== Arming and disarming interrupts ===

As said above, every interrupt input can be read at any time in interrupt mode. In that sense, we don't really treat these inputs as interrupts inputs, but simply as input ports.

If we want a port to trigger an interrupt, we must arm this interrupt input. This is done by setting the respective bit to 1.

CLR R12
SBO 2

This enables interrupt input /INT2 to cause an /INTREQ when its input changes to 0. In the TI console, /INT2 is connected to the interrupt output of the VDP (video processor). If you want to block interrupts on that input, use SBZ.

It is a common misunderstanding that interrupts can be cleared by using a SBZ on an input. I also found this in the popular ''TI Intern'' book. Instead, SBZ n simply blocks interrupt input /INTn. In the case of the video processor, it is up to the VDP to clear its interrupt, and this is done by reading its status register.

Consequently, you '''cannot''' read the current mask setting of the 9901. What you get from reading are the input levels of the pins. So if you plan to change the mask bits temporarily, be aware that you cannot ask the 9901 to give you the current setting which you want to restore later. You will have to find out by another way.

== Counter mode ==

Besides the I/O capabilities, the PSI offers a "real-time" clock. This should not be understood as a precise timer with seconds, hundreds of seconds or other but as a countdown timer that is decremented every 64 CPU clock cycles.

This schematic is taken from the Osborne book, redrawn by me in LibreOffice (and with added Load Buffer).

[[File:Clock9901.png|550px]]

=== Using the timer ===

There are basically two ways of using the countdown timer:

* Interval timer: Set the counter to a value; wait until the counter reaches zero. The PSI can be set up to raise an interrupt at that instant.
* Event timer: Set the counter to a value; do something and then read the counter value.

The counter has 14 bits; that is, its maximum value is 0x3FFF (16383). The counter is decremented every 64 clock cycles, and for the TI-99/4A and the Geneve with a clock cycle time of 333ns, this means that the counter resolution is 21.333 µs. The whole 16384 steps take 0.3495 seconds (349.5 ms).

When the counter reaches 0, it is reloaded from the load buffer, and counting continues.

It is essential to understand that the counter '''always''' counts down, independent of the mode. The specification says that the clock is enabled when a non-zero value is loaded into the load buffer, but tests on a real Geneve show that the clock decrements even when the load buffer is filled with 0.

=== Setting the timer ===

In order to set the load buffer and so to define the maximum counter value, we must switch to clock mode. This is achieved by setting bit 0 of the PSI to 1. In the TI/Geneve systems, the PSI is mapped to CRU base address 0, so we can do this

CLR R12
SBO 0

to enter '''clock mode'''. Using SBZ 0 returns to '''interrupt mode'''.

The effect of switching to clock mode is that the load buffer becomes accessible by the CRU addresses 1 to 14. Supposed that we want to load the buffer with the value 0x00FF, we may use these lines:

CLR R12
SBO 0
LI R1,>00FF
INCT R12
LDCR R1,14

As we see, we must change the CRU base. The LDCR operation always starts at the address defined in R12; if this is not 0, we have to set it here. Note, however, that the CRU address is always half of the R12 value, since the rightmost bit, A15, is not part of the address. If we want to start at bit 1, we must increase R12 by 2. This is, by the way, done wrong in several places in the literature where R12 is only set to 1.

We can combine the SBO and the LDCR to one operation if we define the rightmost bit of R1 as the bit 0 and the following bits as the timer value.

CLR R12
LI R1,>01FF (0000 0001 1111 1111)
LDCR R1,15

Do '''not''' write all 16 bits. The last bit will change bit 15 of the PSI, which is the /RST2 bit. When we are in clock mode, writing a 0 to the /RST2 bit resets all I/O ports. This means that all pins are set to inputs, and devices that rely on them as outputs may be turned off unintentionally.

=== Reading the timer ===

We are interested for the current value of the timer at some occasions. However, since the counter is constantly changing (every 64 clock cycles), reading from the active counter may deliver a wrong result. Think, for instance, about a value 0x2000, which is decremented after we read the first bits, we may end up with 0x2FFF (2 from 0x2000, FFF from 0x1FFF).

For this reason, the timer value is copied to a '''read buffer'''. This happens at every 64th clock cycle, when the counter is also decremented, but only when we are '''not''' in clock mode.

To read the buffer, we must set the PSI to clock mode first, which freezes the counter value in the read buffer. Then we can read the counter using STCR.

CLR R12
SBO 0
STCR R1,15
SRL R1,1
SBZ 0

As we see, register 1 will contain bit 0 in its rightmost bit, so we shift R1 by one position to move it out.

Do not forget to return to interrupt mode, or the buffer will not receive further updates.

As mentioned, bit 15 is the /RST2 bit when we write to it. For reading, bit 15 reflects the /INTREQ output.

=== The weird S0 input ===

There is one peculiarity with the PSI. When the input line S0 is set to 1, the clock mode is '''left temporarily''' - until S0 is 0 again, and bit 0 is 1. If bit 0 is 0, this has no effect, as the clock mode is never entered.

What is the reason for this?

TI obviously considered use cases where the PSI remains in clock mode for longer times, while the I/O ports must still be operated. The I/O ports are available on bits 16-31, which means that the S0 input is 1 for these addresses. So when we do a SBO 16, this is not related to the timer value, and thus should control the first I/O port. To allow this, the chip returns to interrupt/port mode for this operation, and when S0 is reset, returns to clock mode.

In the TI console, the S0-S4 inputs are directly connected with the address bus lines A10-A14. This has a strange side effect: Whenever address bus line A10 changes to 1, the clock mode is left temporarily, and this also happens for ordinary memory accesses.

Suppose that we are in clock mode (SBO 0). In this mode, the read buffer should not be updated, so when we read it, we should get the same value every time, although the real counter value is different. But this is difficult to achieve: If our program uses a memory address where A10 is 1 for some instruction, loading this instruction into the CPU will set A10 to 1, and thus leave clock mode, which updates the counter.

Therefore, you may have the impression that the read register continues to be updated even though you set bit 0 to 1. But this is only happening because your program extends over a location where A10 is 1. So if you want to prove that in clock mode the read register remains fixed, your program must avoid all memory locations where A10 is 1.

== Shared pins ==

Some pins have a double meaning; for example, pin 34 is labeled /INT7 / P15. How do we select the functions?

The shared pins are those for the interrupt inputs /INT7 to /INT15; they may also be used for P7 to P15 (in the opposite order).

If the Pn port is set to '''input''', the situation looks like this:

[[File:Shared9901in.png|250px]]

This means that both port and interrupt input have the same values; each one is a mirror of the other's state. We notice it by reading the bits of the associated CRU addresses, getting the same results. There is a difference, though: The interrupt input can be armed to trigger an outgoing interrupt, while the I/O port cannot.

In the other case, the Pn port is an '''output'''.

[[File:Shared9901out.png|250px]]

Is that possible? - Sure. The interrupt input will reflect the output of the port. When we set the port to 1, the interrupt input will get that 1 (same for 0). If we arm the interrupt input, setting the output port to 0 will trigger an interrupt via this input. The 9901 specification document recommends to disarm the interrupt trigger for the shared ports because of this possibly unwanted effect.

== Safety precautions ==

The TMS9901 PSI is an interrupt encoder and an I/O circuit. You may have heard that improper use of I/O circuits may damage the circuit so that it must be replaced. Is this possible with the 9901 as well? Is there a way to kill the 9901?

Short answer: Yes.

Longer answer: Yes, but it depends on the way how the ports are used.

If the port is used as an input, nothing bad will happen, since the ports have high input impedance. You can put 0V or 5V directly to the input; of course, you should not use excessive voltage.

=== How to damage the 9901 ports ===

The problem is when the port is configured as an output port. In that case it may output 0V (0) or 5V (1). When you connect the output to the opposite voltage, you will cause a short circuit which quickly exceeds the chip's maximum power dissipation of 750 mW. This means you will fry the chip.

Consider the following setup (but don't try it!).

[[File:Badport9901.png|300px]]

Obviously, port P4 is assumed to be an input. When the switch is open, port P4 will sense a 1 on its input. When the switch is closed, it will sense a 0.

Now what happens when you execute this code?

CLR R12
SBO 20

This will program port P4 to be an output, and to show a 1 (5V) at the output. SBZ will, in contrast, make this port output a 0. So how do you make it an input port? - This is done by resetting the chip. As long as you don't use a SBZ/SBO (or a LDCR) on the ports, the ports are inputs.

Nothing has happened up to now. But now imagine that you press the switch. This will put the 1 output to ground, causing the short circuit, and your 9901 is toast.

=== What about the TI console? ===

So can we damage the 9901 in the TI console by a suitable CRU operation? - Luckily not.

The reason is the way how TI used the ports on the mainboard. Most of the ports are configured as outputs. Nothing happens when you reset them to inputs.

* The pure interrupt inputs (/INT1 to /INT6) are safe, as they cannot output anything. They have no output driver that could be fried.
* P0 and P1 are not connected.
* P2, P3, and P4 are designed as outputs, so they cannot be turned from an input to an output.
* P5 is the selector of the Alpha Lock key, so output as well.
* P6 and P7 (/INT15) are the cassette motor control outputs.
* P8 (/INT14) is the audio gate output.
* P9 (/INT13) is the cassette output.
* P10 (/INT12) is pulled up to 5V via a 10 kOhm resistor. If you put a 0 on this port (5V), the maximum current is 500 µA, which results in a power dissipation of 2.5 mW (far below the maximum 750 mW).
* P11 (/INT11) is the cassette input. However, there is a resistor of 2.2 kOhm (R413) which effectively guards the port of high currents.
* P12, P13, P14, P15 (/INT10 ... /INT7) are the keyboard input lines. Again, we have pull-ups of 10 kOhm against +5V, but also 470 Ohm on the line, which means a maximum of 8.5 mA or 42.5 mW. This is still well below the maximum value.

So we see that resistors are the best way to protect the ports. And we may calm down; we cannot burn the 9901 in the TI console by a bug in our program.

== Literature ==

<span id="ref1">[1]</span> Texas Instruments: ''TMS 9901 Programmable Systems Interface Data Manual'', July 1977

<span id="ref2">[2]</span> Adam Osborne, Gerry Kane: ''Osborne 16-Bit Microprocessor Handbook / Includes 2900 Chip Slice Family''. Published by OSBORNE/McGraw-Hill 1975, 1981. ISBN 0-931988-43-8.

Programmable Systems Interface TMS 9901

2022-04-23T13:53:41Z

Mizapf: /* Literature */

The Programmable System Interface (PSI) is a circuit that is used on the TI-99/4A main board, on some expansion cards, and on the Geneve.

The designation of the PSI is '''TMS9901''', and this is the name that most users should be more familiar with.

== Features ==

The TMS 9901 Programmable Systems Interface is a multi-purpose circuit that is used in the TI-99/4A and the Geneve computer, and also on some peripheral cards like the Corcomp Floppy Disk Controller.

The 9901 has three main usage modes:

* Input/Output ports
* Interrupt prioritizing
* Timer

The I/O ports are mainly used for scanning the keyboard and joysticks, while the timer is used for cassette data encoding and decoding. The interrupt prioritizer is only used for the video interrupt which is routed from the VDP to the CPU through the 9901.

== Package ==

This is the pin assignment according to the 9901 specification.

[[File:Pack9901.png|300px|left]]

You can see pins of related functions marked by the same background color.

* Orange: Interrupt inputs
* Red: CRU bit selection (00000 - 11111, i.e. 0-31 decimal)
* Blue: CRU interface
* Violet: I/O ports
* Yellow: Outgoing interrupt and level

Note that some pins have a double function, or in other words, two functions share the same pin. I will discuss this in the following sections.

<div style="clear:both"></div>

== Input/Output port operation ==

The simplest way of working with the 9901 is input/output operation with the ports. The 9901 has 16 configurable ports that can be individually used as inputs or outputs: P0 to P15.

=== Px port as input ===

[[File:Port9901in.png|250px]]

The power-on preset for every port is input. If you want to probe the P2 status (bit 18), use

CLR R12
TB 18
JEQ P2ACT

TB copies the bit at the given CRU address into the Equal bit of the status register. JEQ will jump to the location when this input has a high level. The maximum input current is 100 µA. You should protect the input with a resistor; [[#Safety_precautions | see below]] for a more detailed discussion.

If you want to read all 16 ports, use the STCR instruction:

LI R12,32
STCR R1,0

Note that the CRU base address in R12 advances in steps of 2, so bit 16 is on address 32. Also, for reading 16 bits, you must specify a count of 0.

The 9901 offers some more inputs than the 16 ports; we can use the interrupt inputs as well. More about that can be found in the section about the [[#Interrupt_mode| interrupt mode]].

=== Px port as output ===

[[File:Port9901out.png|250px]]

Once you write a value to the CRU address of a 9901 port, this port switches to output mode. The value written to the port is the value that is shown on its pin. If we want to output a 1 on P6, we have to use

CLR R12
SBO 22

If we wanted to output a 0, SBZ would have to be used. In order to set several ports in one go, use LDCR.

We can also read the output port just by using TB as usual (or STCR for several ports at once).

CLR R12
SBO 22
TB 22
JEQ EXPECT

The TB operation should return the 1 which the previous SBO has set.

You '''cannot''' switch back to input mode. This is only possible by resetting the 9901, either using the /RST1 input line, or by setting the /RST2 bit (bit 15) to 0 in clock mode.

== Interrupt mode ==

In interrupt mode, bits 1 to 15 are used to set the interrupt mask (write), or to query the interrupt inputs (read). That is, the meaning of reading and writing the bits is indeed different.

This schema shows how the interrupt inputs are used.

[[File:Int9901.png|600px]]

This illustration is slightly simplified; there is a latch between each interrupt input and the mask AND gate. This is not relevant for our programming, though. For more details see the ''TMS 9901 Programmable Systems Interface Data Manual''.

=== Checking the interrupt inputs ===

In general, every interrupt input can be read via CRU access:

CLR R12
TB 15
JEQ NOINT15

TB copies the bit at the specified CRU address to the Equal status bit. This means that JEQ jumps to the location when the bit is 1. Since all interrupt inputs are negative logic, reading a 1 means that there is no interrupt at this input (so I called it NOINT15).

If we want to read several interrupt inputs by a single instruction, we have to use STCR.

LI R12,16
STCR R1,8

This reads the states of the /INT8, /INT9, ..., /INT15 inputs and puts them in the most significant byte of R1. (See the specification of STCR and LDCR for transfers of up to 8 bits.)

=== Interrupt levels ===

Each interrupt input (/INT1 to /INT15) may be used to trigger an interrupt at another circuit, typically the CPU. For this purpose, the PSI offers an /INTREQ outgoing line. In the TI console, it is routed to the /INTREQ input of the TMS9900 CPU.

In addition there is a priority encoder, which is not shown here. This encoder outputs a 4-bit number which reflects the smallest number of the interrupt inputs where an interrupt has been sensed.

That is, if /INT4 and /INT7 are currently set to 0 (active), the priority encoder outputs (0100), which means 4.

The TMS9900 CPU can differentiate between these interrupt levels, and by using its LIMI command, we can set a threshold where interrupts are ignored. So when we use a LIMI 3, the interrupts of level 4, 5, 6 and higher will be ignored.

The bad news is that Texas Instruments did not use these priority lines in the TI console. In fact, these outputs (IC0 .. IC3) are not connected, and the respective interrupt level inputs at the CPU are hardwired to (0001), which means that every interrupt that occurs in the TI console is automatically set to level 1. So in order to block all interrupts from the 9901

LIMI 0

must be executed. To allow all,

LIMI 1

is sufficient. For some unclear reason, TI used LIMI 2 in all occasions.

=== Arming and disarming interrupts ===

As said above, every interrupt input can be read at any time in interrupt mode. In that sense, we don't really treat these inputs as interrupts inputs, but simply as input ports.

If we want a port to trigger an interrupt, we must arm this interrupt input. This is done by setting the respective bit to 1.

CLR R12
SBO 2

This enables interrupt input /INT2 to cause an /INTREQ when its input changes to 0. In the TI console, /INT2 is connected to the interrupt output of the VDP (video processor). If you want to block interrupts on that input, use SBZ.

It is a common misunderstanding that interrupts can be cleared by using a SBZ on an input. I also found this in the popular ''TI Intern'' book. Instead, SBZ n simply blocks interrupt input /INTn. In the case of the video processor, it is up to the VDP to clear its interrupt, and this is done by reading its status register.

Consequently, you '''cannot''' read the current mask setting of the 9901. What you get from reading are the input levels of the pins. So if you plan to change the mask bits temporarily, be aware that you cannot ask the 9901 to give you the current setting which you want to restore later. You will have to find out by another way.

== Counter mode ==

Besides the I/O capabilities, the PSI offers a "real-time" clock. This should not be understood as a precise timer with seconds, hundreds of seconds or other but as a countdown timer that is decremented every 64 CPU clock cycles.

This schematic is taken from the Osborne book, redrawn by me in LibreOffice (and with added Load Buffer).

[[File:Clock9901.png|550px]]

=== Using the timer ===

There are basically two ways of using the countdown timer:

* Interval timer: Set the counter to a value; wait until the counter reaches zero. The PSI can be set up to raise an interrupt at that instant.
* Event timer: Set the counter to a value; do something and then read the counter value.

The counter has 14 bits; that is, its maximum value is 0x3FFF (16383). The counter is decremented every 64 clock cycles, and for the TI-99/4A and the Geneve with a clock cycle time of 333ns, this means that the counter resolution is 21.333 µs. The whole 16384 steps take 0.3495 seconds (349.5 ms).

When the counter reaches 0, it is reloaded from the load buffer, and counting continues.

It is essential to understand that the counter '''always''' counts down, independent of the mode. The specification says that the clock is enabled when a non-zero value is loaded into the load buffer, but tests on a real Geneve show that the clock decrements even when the load buffer is filled with 0.

=== Setting the timer ===

In order to set the load buffer and so to define the maximum counter value, we must switch to clock mode. This is achieved by setting bit 0 of the PSI to 1. In the TI/Geneve systems, the PSI is mapped to CRU base address 0, so we can do this

CLR R12
SBO 0

to enter '''clock mode'''. Using SBZ 0 returns to '''interrupt mode'''.

The effect of switching to clock mode is that the load buffer becomes accessible by the CRU addresses 1 to 14. Supposed that we want to load the buffer with the value 0x00FF, we may use these lines:

CLR R12
SBO 0
LI R1,>00FF
INCT R12
LDCR R1,14

As we see, we must change the CRU base. The LDCR operation always starts at the address defined in R12; if this is not 0, we have to set it here. Note, however, that the CRU address is always half of the R12 value, since the rightmost bit, A15, is not part of the address. If we want to start at bit 1, we must increase R12 by 2. This is, by the way, done wrong in several places in the literature where R12 is only set to 1.

We can combine the SBO and the LDCR to one operation if we define the rightmost bit of R1 as the bit 0 and the following bits as the timer value.

CLR R12
LI R1,>01FF (0000 0001 1111 1111)
LDCR R1,15

Do '''not''' write all 16 bits. The last bit will change bit 15 of the PSI, which is the /RST2 bit. When we are in clock mode, writing a 0 to the /RST2 bit resets all I/O ports. This means that all pins are set to inputs, and devices that rely on them as outputs may be turned off unintentionally.

=== Reading the timer ===

We are interested for the current value of the timer at some occasions. However, since the counter is constantly changing (every 64 clock cycles), reading from the active counter may deliver a wrong result. Think, for instance, about a value 0x2000, which is decremented after we read the first bits, we may end up with 0x2FFF (2 from 0x2000, FFF from 0x1FFF).

For this reason, the timer value is copied to a '''read buffer'''. This happens at every 64th clock cycle, when the counter is also decremented, but only when we are '''not''' in clock mode.

To read the buffer, we must set the PSI to clock mode first, which freezes the counter value in the read buffer. Then we can read the counter using STCR.

CLR R12
SBO 0
STCR R1,15
SRL R1,1
SBZ 0

As we see, register 1 will contain bit 0 in its rightmost bit, so we shift R1 by one position to move it out.

Do not forget to return to interrupt mode, or the buffer will not receive further updates.

As mentioned, bit 15 is the /RST2 bit when we write to it. For reading, bit 15 reflects the /INTREQ output.

=== The weird S0 input ===

There is one peculiarity with the PSI. When the input line S0 is set to 1, the clock mode is '''left temporarily''' - until S0 is 0 again, and bit 0 is 1. If bit 0 is 0, this has no effect, as the clock mode is never entered.

What is the reason for this?

TI obviously considered use cases where the PSI remains in clock mode for longer times, while the I/O ports must still be operated. The I/O ports are available on bits 16-31, which means that the S0 input is 1 for these addresses. So when we do a SBO 16, this is not related to the timer value, and thus should control the first I/O port. To allow this, the chip returns to interrupt/port mode for this operation, and when S0 is reset, returns to clock mode.

In the TI console, the S0-S4 inputs are directly connected with the address bus lines A10-A14. This has a strange side effect: Whenever address bus line A10 changes to 1, the clock mode is left temporarily, and this also happens for ordinary memory accesses.

Suppose that we are in clock mode (SBO 0). In this mode, the read buffer should not be updated, so when we read it, we should get the same value every time, although the real counter value is different. But this is difficult to achieve: If our program uses a memory address where A10 is 1 for some instruction, loading this instruction into the CPU will set A10 to 1, and thus leave clock mode, which updates the counter.

Therefore, you may have the impression that the read register continues to be updated even though you set bit 0 to 1. But this is only happening because your program extends over a location where A10 is 1. So if you want to prove that in clock mode the read register remains fixed, your program must avoid all memory locations where A10 is 1.

== Shared pins ==

Some pins have a double meaning; for example, pin 34 is labeled /INT7 / P15. How do we select the functions?

The shared pins are those for the interrupt inputs /INT7 to /INT15; they may also be used for P7 to P15 (in the opposite order).

If the Pn port is set to '''input''', the situation looks like this:

[[File:Shared9901in.png|250px]]

This means that both port and interrupt input have the same values; each one is a mirror of the other's state. We notice it by reading the bits of the associated CRU addresses, getting the same results. There is a difference, though: The interrupt input can be armed to trigger an outgoing interrupt, while the I/O port cannot.

In the other case, the Pn port is an '''output'''.

[[File:Shared9901out.png|250px]]

Is that possible? - Sure. The interrupt input will reflect the output of the port. When we set the port to 1, the interrupt input will get that 1 (same for 0). If we arm the interrupt input, setting the output port to 0 will trigger an interrupt via this input. The 9901 specification document recommends to disarm the interrupt trigger for the shared ports because of this possibly unwanted effect.

== Safety precautions ==

The TMS9901 PSI is an interrupt encoder and an I/O circuit. You may have heard that improper use of I/O circuits may damage the circuit so that it must be replaced. Is this possible with the 9901 as well? Is there a way to kill the 9901?

Short answer: Yes.

Longer answer: Yes, but it depends on the way how the ports are used.

If the port is used as an input, nothing bad will happen, since the ports have high input impedance. You can put 0V or 5V directly to the input; of course, you should not use excessive voltage.

=== How to damage the 9901 ports ===

The problem is when the port is configured as an output port. In that case it may output 0V (0) or 5V (1). When you connect the output to the opposite voltage, you will cause a short circuit which quickly exceeds the chip's maximum power dissipation of 750 mW. This means you will fry the chip.

Consider the following setup (but don't try it!).

[[File:Badport9901.png|300px]]

Obviously, port P4 is assumed to be an input. When the switch is open, port P4 will sense a 1 on its input. When the switch is closed, it will sense a 0.

Now what happens when you execute this code?

CLR R12
SBO 20

This will program port P4 to be an output, and to show a 1 (5V) at the output. SBZ will, in contrast, make this port output a 0. So how do you make it an input port? - This is done by resetting the chip. As long as you don't use a SBZ/SBO (or a LDCR) on the ports, the ports are inputs.

Nothing has happened up to now. But now imagine that you press the switch. This will put the 1 output to ground, causing the short circuit, and your 9901 is toast.

=== What about the TI console? ===

So can we damage the 9901 in the TI console by a suitable CRU operation? - Luckily not.

The reason is the way how TI used the ports on the mainboard. Most of the ports are configured as outputs. Nothing happens when you reset them to inputs.

* The pure interrupt inputs (/INT1 to /INT6) are safe, as they cannot output anything. They have no output driver that could be fried.
* P0 and P1 are not connected.
* P2, P3, and P4 are designed as outputs, so they cannot be turned from an input to an output.
* P5 is the selector of the Alpha Lock key, so output as well.
* P6 and P7 (/INT15) are the cassette motor control outputs.
* P8 (/INT14) is the audio gate output.
* P9 (/INT13) is the cassette output.
* P10 (/INT12) is pulled up to 5V via a 10 kOhm resistor. If you put a 0 on this port (5V), the maximum current is 500 µA, which results in a power dissipation of 2.5 mW (far below the maximum 750 mW).
* P11 (/INT11) is the cassette input. However, there is a resistor of 2.2 kOhm (R413) which effectively guards the port of high currents.
* P12, P13, P14, P15 (/INT10 ... /INT7) are the keyboard input lines. Again, we have pull-ups of 10 kOhm against +5V, but also 470 Ohm on the line, which means a maximum of 8.5 mA or 42.5 mW. This is still well below the maximum value.

So we see that resistors are the best way to protect the ports. And we may calm down; we cannot burn the 9901 in the TI console by a bug in our program.

== Literature ==

<span id="ref1">[1]</span> Texas Instruments: ''TMS 9901 Programmable Systems Interface Data Manual'', July 1977
<span id="ref2">[2]</span> Adam Osborne, Gerry Kane: ''Osborne 16-Bit Microprocessor Handbook / Includes 2900 Chip Slice Family''. Published by OSBORNE/McGraw-Hill 1975, 1981. ISBN 0-931988-43-8.

Programmable Systems Interface TMS 9901

2022-04-23T13:51:39Z

Mizapf:

The Programmable System Interface (PSI) is a circuit that is used on the TI-99/4A main board, on some expansion cards, and on the Geneve.

The designation of the PSI is '''TMS9901''', and this is the name that most users should be more familiar with.

== Features ==

The TMS 9901 Programmable Systems Interface is a multi-purpose circuit that is used in the TI-99/4A and the Geneve computer, and also on some peripheral cards like the Corcomp Floppy Disk Controller.

The 9901 has three main usage modes:

* Input/Output ports
* Interrupt prioritizing
* Timer

The I/O ports are mainly used for scanning the keyboard and joysticks, while the timer is used for cassette data encoding and decoding. The interrupt prioritizer is only used for the video interrupt which is routed from the VDP to the CPU through the 9901.

== Package ==

This is the pin assignment according to the 9901 specification.

[[File:Pack9901.png|300px|left]]

You can see pins of related functions marked by the same background color.

* Orange: Interrupt inputs
* Red: CRU bit selection (00000 - 11111, i.e. 0-31 decimal)
* Blue: CRU interface
* Violet: I/O ports
* Yellow: Outgoing interrupt and level

Note that some pins have a double function, or in other words, two functions share the same pin. I will discuss this in the following sections.

<div style="clear:both"></div>

== Input/Output port operation ==

The simplest way of working with the 9901 is input/output operation with the ports. The 9901 has 16 configurable ports that can be individually used as inputs or outputs: P0 to P15.

=== Px port as input ===

[[File:Port9901in.png|250px]]

The power-on preset for every port is input. If you want to probe the P2 status (bit 18), use

CLR R12
TB 18
JEQ P2ACT

TB copies the bit at the given CRU address into the Equal bit of the status register. JEQ will jump to the location when this input has a high level. The maximum input current is 100 µA. You should protect the input with a resistor; [[#Safety_precautions | see below]] for a more detailed discussion.

If you want to read all 16 ports, use the STCR instruction:

LI R12,32
STCR R1,0

Note that the CRU base address in R12 advances in steps of 2, so bit 16 is on address 32. Also, for reading 16 bits, you must specify a count of 0.

The 9901 offers some more inputs than the 16 ports; we can use the interrupt inputs as well. More about that can be found in the section about the [[#Interrupt_mode| interrupt mode]].

=== Px port as output ===

[[File:Port9901out.png|250px]]

Once you write a value to the CRU address of a 9901 port, this port switches to output mode. The value written to the port is the value that is shown on its pin. If we want to output a 1 on P6, we have to use

CLR R12
SBO 22

If we wanted to output a 0, SBZ would have to be used. In order to set several ports in one go, use LDCR.

We can also read the output port just by using TB as usual (or STCR for several ports at once).

CLR R12
SBO 22
TB 22
JEQ EXPECT

The TB operation should return the 1 which the previous SBO has set.

You '''cannot''' switch back to input mode. This is only possible by resetting the 9901, either using the /RST1 input line, or by setting the /RST2 bit (bit 15) to 0 in clock mode.

== Interrupt mode ==

In interrupt mode, bits 1 to 15 are used to set the interrupt mask (write), or to query the interrupt inputs (read). That is, the meaning of reading and writing the bits is indeed different.

This schema shows how the interrupt inputs are used.

[[File:Int9901.png|600px]]

This illustration is slightly simplified; there is a latch between each interrupt input and the mask AND gate. This is not relevant for our programming, though. For more details see the ''TMS 9901 Programmable Systems Interface Data Manual''.

=== Checking the interrupt inputs ===

In general, every interrupt input can be read via CRU access:

CLR R12
TB 15
JEQ NOINT15

TB copies the bit at the specified CRU address to the Equal status bit. This means that JEQ jumps to the location when the bit is 1. Since all interrupt inputs are negative logic, reading a 1 means that there is no interrupt at this input (so I called it NOINT15).

If we want to read several interrupt inputs by a single instruction, we have to use STCR.

LI R12,16
STCR R1,8

This reads the states of the /INT8, /INT9, ..., /INT15 inputs and puts them in the most significant byte of R1. (See the specification of STCR and LDCR for transfers of up to 8 bits.)

=== Interrupt levels ===

Each interrupt input (/INT1 to /INT15) may be used to trigger an interrupt at another circuit, typically the CPU. For this purpose, the PSI offers an /INTREQ outgoing line. In the TI console, it is routed to the /INTREQ input of the TMS9900 CPU.

In addition there is a priority encoder, which is not shown here. This encoder outputs a 4-bit number which reflects the smallest number of the interrupt inputs where an interrupt has been sensed.

That is, if /INT4 and /INT7 are currently set to 0 (active), the priority encoder outputs (0100), which means 4.

The TMS9900 CPU can differentiate between these interrupt levels, and by using its LIMI command, we can set a threshold where interrupts are ignored. So when we use a LIMI 3, the interrupts of level 4, 5, 6 and higher will be ignored.

The bad news is that Texas Instruments did not use these priority lines in the TI console. In fact, these outputs (IC0 .. IC3) are not connected, and the respective interrupt level inputs at the CPU are hardwired to (0001), which means that every interrupt that occurs in the TI console is automatically set to level 1. So in order to block all interrupts from the 9901

LIMI 0

must be executed. To allow all,

LIMI 1

is sufficient. For some unclear reason, TI used LIMI 2 in all occasions.

=== Arming and disarming interrupts ===

As said above, every interrupt input can be read at any time in interrupt mode. In that sense, we don't really treat these inputs as interrupts inputs, but simply as input ports.

If we want a port to trigger an interrupt, we must arm this interrupt input. This is done by setting the respective bit to 1.

CLR R12
SBO 2

This enables interrupt input /INT2 to cause an /INTREQ when its input changes to 0. In the TI console, /INT2 is connected to the interrupt output of the VDP (video processor). If you want to block interrupts on that input, use SBZ.

It is a common misunderstanding that interrupts can be cleared by using a SBZ on an input. I also found this in the popular ''TI Intern'' book. Instead, SBZ n simply blocks interrupt input /INTn. In the case of the video processor, it is up to the VDP to clear its interrupt, and this is done by reading its status register.

Consequently, you '''cannot''' read the current mask setting of the 9901. What you get from reading are the input levels of the pins. So if you plan to change the mask bits temporarily, be aware that you cannot ask the 9901 to give you the current setting which you want to restore later. You will have to find out by another way.

== Counter mode ==

Besides the I/O capabilities, the PSI offers a "real-time" clock. This should not be understood as a precise timer with seconds, hundreds of seconds or other but as a countdown timer that is decremented every 64 CPU clock cycles.

This schematic is taken from the Osborne book, redrawn by me in LibreOffice (and with added Load Buffer).

[[File:Clock9901.png|550px]]

=== Using the timer ===

There are basically two ways of using the countdown timer:

* Interval timer: Set the counter to a value; wait until the counter reaches zero. The PSI can be set up to raise an interrupt at that instant.
* Event timer: Set the counter to a value; do something and then read the counter value.

The counter has 14 bits; that is, its maximum value is 0x3FFF (16383). The counter is decremented every 64 clock cycles, and for the TI-99/4A and the Geneve with a clock cycle time of 333ns, this means that the counter resolution is 21.333 µs. The whole 16384 steps take 0.3495 seconds (349.5 ms).

When the counter reaches 0, it is reloaded from the load buffer, and counting continues.

It is essential to understand that the counter '''always''' counts down, independent of the mode. The specification says that the clock is enabled when a non-zero value is loaded into the load buffer, but tests on a real Geneve show that the clock decrements even when the load buffer is filled with 0.

=== Setting the timer ===

In order to set the load buffer and so to define the maximum counter value, we must switch to clock mode. This is achieved by setting bit 0 of the PSI to 1. In the TI/Geneve systems, the PSI is mapped to CRU base address 0, so we can do this

CLR R12
SBO 0

to enter '''clock mode'''. Using SBZ 0 returns to '''interrupt mode'''.

The effect of switching to clock mode is that the load buffer becomes accessible by the CRU addresses 1 to 14. Supposed that we want to load the buffer with the value 0x00FF, we may use these lines:

CLR R12
SBO 0
LI R1,>00FF
INCT R12
LDCR R1,14

As we see, we must change the CRU base. The LDCR operation always starts at the address defined in R12; if this is not 0, we have to set it here. Note, however, that the CRU address is always half of the R12 value, since the rightmost bit, A15, is not part of the address. If we want to start at bit 1, we must increase R12 by 2. This is, by the way, done wrong in several places in the literature where R12 is only set to 1.

We can combine the SBO and the LDCR to one operation if we define the rightmost bit of R1 as the bit 0 and the following bits as the timer value.

CLR R12
LI R1,>01FF (0000 0001 1111 1111)
LDCR R1,15

Do '''not''' write all 16 bits. The last bit will change bit 15 of the PSI, which is the /RST2 bit. When we are in clock mode, writing a 0 to the /RST2 bit resets all I/O ports. This means that all pins are set to inputs, and devices that rely on them as outputs may be turned off unintentionally.

=== Reading the timer ===

We are interested for the current value of the timer at some occasions. However, since the counter is constantly changing (every 64 clock cycles), reading from the active counter may deliver a wrong result. Think, for instance, about a value 0x2000, which is decremented after we read the first bits, we may end up with 0x2FFF (2 from 0x2000, FFF from 0x1FFF).

For this reason, the timer value is copied to a '''read buffer'''. This happens at every 64th clock cycle, when the counter is also decremented, but only when we are '''not''' in clock mode.

To read the buffer, we must set the PSI to clock mode first, which freezes the counter value in the read buffer. Then we can read the counter using STCR.

CLR R12
SBO 0
STCR R1,15
SRL R1,1
SBZ 0

As we see, register 1 will contain bit 0 in its rightmost bit, so we shift R1 by one position to move it out.

Do not forget to return to interrupt mode, or the buffer will not receive further updates.

As mentioned, bit 15 is the /RST2 bit when we write to it. For reading, bit 15 reflects the /INTREQ output.

=== The weird S0 input ===

There is one peculiarity with the PSI. When the input line S0 is set to 1, the clock mode is '''left temporarily''' - until S0 is 0 again, and bit 0 is 1. If bit 0 is 0, this has no effect, as the clock mode is never entered.

What is the reason for this?

TI obviously considered use cases where the PSI remains in clock mode for longer times, while the I/O ports must still be operated. The I/O ports are available on bits 16-31, which means that the S0 input is 1 for these addresses. So when we do a SBO 16, this is not related to the timer value, and thus should control the first I/O port. To allow this, the chip returns to interrupt/port mode for this operation, and when S0 is reset, returns to clock mode.

In the TI console, the S0-S4 inputs are directly connected with the address bus lines A10-A14. This has a strange side effect: Whenever address bus line A10 changes to 1, the clock mode is left temporarily, and this also happens for ordinary memory accesses.

Suppose that we are in clock mode (SBO 0). In this mode, the read buffer should not be updated, so when we read it, we should get the same value every time, although the real counter value is different. But this is difficult to achieve: If our program uses a memory address where A10 is 1 for some instruction, loading this instruction into the CPU will set A10 to 1, and thus leave clock mode, which updates the counter.

Therefore, you may have the impression that the read register continues to be updated even though you set bit 0 to 1. But this is only happening because your program extends over a location where A10 is 1. So if you want to prove that in clock mode the read register remains fixed, your program must avoid all memory locations where A10 is 1.

== Shared pins ==

Some pins have a double meaning; for example, pin 34 is labeled /INT7 / P15. How do we select the functions?

The shared pins are those for the interrupt inputs /INT7 to /INT15; they may also be used for P7 to P15 (in the opposite order).

If the Pn port is set to '''input''', the situation looks like this:

[[File:Shared9901in.png|250px]]

This means that both port and interrupt input have the same values; each one is a mirror of the other's state. We notice it by reading the bits of the associated CRU addresses, getting the same results. There is a difference, though: The interrupt input can be armed to trigger an outgoing interrupt, while the I/O port cannot.

In the other case, the Pn port is an '''output'''.

[[File:Shared9901out.png|250px]]

Is that possible? - Sure. The interrupt input will reflect the output of the port. When we set the port to 1, the interrupt input will get that 1 (same for 0). If we arm the interrupt input, setting the output port to 0 will trigger an interrupt via this input. The 9901 specification document recommends to disarm the interrupt trigger for the shared ports because of this possibly unwanted effect.

== Safety precautions ==

The TMS9901 PSI is an interrupt encoder and an I/O circuit. You may have heard that improper use of I/O circuits may damage the circuit so that it must be replaced. Is this possible with the 9901 as well? Is there a way to kill the 9901?

Short answer: Yes.

Longer answer: Yes, but it depends on the way how the ports are used.

If the port is used as an input, nothing bad will happen, since the ports have high input impedance. You can put 0V or 5V directly to the input; of course, you should not use excessive voltage.

=== How to damage the 9901 ports ===

The problem is when the port is configured as an output port. In that case it may output 0V (0) or 5V (1). When you connect the output to the opposite voltage, you will cause a short circuit which quickly exceeds the chip's maximum power dissipation of 750 mW. This means you will fry the chip.

Consider the following setup (but don't try it!).

[[File:Badport9901.png|300px]]

Obviously, port P4 is assumed to be an input. When the switch is open, port P4 will sense a 1 on its input. When the switch is closed, it will sense a 0.

Now what happens when you execute this code?

CLR R12
SBO 20

This will program port P4 to be an output, and to show a 1 (5V) at the output. SBZ will, in contrast, make this port output a 0. So how do you make it an input port? - This is done by resetting the chip. As long as you don't use a SBZ/SBO (or a LDCR) on the ports, the ports are inputs.

Nothing has happened up to now. But now imagine that you press the switch. This will put the 1 output to ground, causing the short circuit, and your 9901 is toast.

=== What about the TI console? ===

So can we damage the 9901 in the TI console by a suitable CRU operation? - Luckily not.

The reason is the way how TI used the ports on the mainboard. Most of the ports are configured as outputs. Nothing happens when you reset them to inputs.

* The pure interrupt inputs (/INT1 to /INT6) are safe, as they cannot output anything. They have no output driver that could be fried.
* P0 and P1 are not connected.
* P2, P3, and P4 are designed as outputs, so they cannot be turned from an input to an output.
* P5 is the selector of the Alpha Lock key, so output as well.
* P6 and P7 (/INT15) are the cassette motor control outputs.
* P8 (/INT14) is the audio gate output.
* P9 (/INT13) is the cassette output.
* P10 (/INT12) is pulled up to 5V via a 10 kOhm resistor. If you put a 0 on this port (5V), the maximum current is 500 µA, which results in a power dissipation of 2.5 mW (far below the maximum 750 mW).
* P11 (/INT11) is the cassette input. However, there is a resistor of 2.2 kOhm (R413) which effectively guards the port of high currents.
* P12, P13, P14, P15 (/INT10 ... /INT7) are the keyboard input lines. Again, we have pull-ups of 10 kOhm against +5V, but also 470 Ohm on the line, which means a maximum of 8.5 mA or 42.5 mW. This is still well below the maximum value.

So we see that resistors are the best way to protect the ports. And we may calm down; we cannot burn the 9901 in the TI console by a bug in our program.

== Literature ==

<span id="ref1">[1]</span> Adam Osborne, Gerry Kane: ''Osborne 16-Bit Microprocessor Handbook / Includes 2900 Chip Slice Family''. Published by OSBORNE/McGraw-Hill 1975, 1981. ISBN 0-931988-43-8.

Programmable Systems Interface TMS 9901

2022-04-23T13:45:36Z

Mizapf: /* Arming and disarming interrupts */

The Programmable System Interface (PSI) is a circuit that is used on the TI-99/4A main board, on some expansion cards, and on the Geneve.

The designation of the PSI is '''TMS9901''', and this is the name that most users should be more familiar with.

== Features ==

The TMS 9901 Programmable Systems Interface is a multi-purpose circuit that is used in the TI-99/4A and the Geneve computer, and also on some peripheral cards like the Corcomp Floppy Disk Controller.

The 9901 has three main usage modes:

* Input/Output ports
* Interrupt prioritizing
* Timer

The I/O ports are mainly used for scanning the keyboard and joysticks, while the timer is used for cassette data encoding and decoding. The interrupt prioritizer is only used for the video interrupt which is routed from the VDP to the CPU through the 9901.

== Package ==

This is the pin assignment according to the 9901 specification.

[[File:Pack9901.png|300px|left]]

You can see pins of related functions marked by the same background color.

* Orange: Interrupt inputs
* Red: CRU bit selection (00000 - 11111, i.e. 0-31 decimal)
* Blue: CRU interface
* Violet: I/O ports
* Yellow: Outgoing interrupt and level

Note that some pins have a double function, or in other words, two functions share the same pin. I will discuss this in the following sections.

<div style="clear:both"></div>

== Input/Output port operation ==

The simplest way of working with the 9901 is input/output operation with the ports. The 9901 has 16 configurable ports that can be individually used as inputs or outputs: P0 to P15.

=== Px port as input ===

[[File:Port9901in.png|250px]]

The power-on preset for every port is input. If you want to probe the P2 status (bit 18), use

CLR R12
TB 18
JEQ P2ACT

TB copies the bit at the given CRU address into the Equal bit of the status register. JEQ will jump to the location when this input has a high level. The maximum input current is 100 µA. You should protect the input with a resistor; [[#Safety_precautions | see below]] for a more detailed discussion.

If you want to read all 16 ports, use the STCR instruction:

LI R12,32
STCR R1,0

Note that the CRU base address in R12 advances in steps of 2, so bit 16 is on address 32. Also, for reading 16 bits, you must specify a count of 0.

The 9901 offers some more inputs than the 16 ports; we can use the interrupt inputs as well. More about that can be found in the section about the [[#Interrupt_mode| interrupt mode]].

=== Px port as output ===

[[File:Port9901out.png|250px]]

Once you write a value to the CRU address of a 9901 port, this port switches to output mode. The value written to the port is the value that is shown on its pin. If we want to output a 1 on P6, we have to use

CLR R12
SBO 22

If we wanted to output a 0, SBZ would have to be used. In order to set several ports in one go, use LDCR.

We can also read the output port just by using TB as usual (or STCR for several ports at once).

CLR R12
SBO 22
TB 22
JEQ EXPECT

The TB operation should return the 1 which the previous SBO has set.

You '''cannot''' switch back to input mode. This is only possible by resetting the 9901, either using the /RST1 input line, or by setting the /RST2 bit (bit 15) to 0 in clock mode.

== Interrupt mode ==

In interrupt mode, bits 1 to 15 are used to set the interrupt mask (write), or to query the interrupt inputs (read). That is, the meaning of reading and writing the bits is indeed different.

This schema shows how the interrupt inputs are used.

[[File:Int9901.png|600px]]

This illustration is slightly simplified; there is a latch between each interrupt input and the mask AND gate. This is not relevant for our programming, though. For more details see the ''TMS 9901 Programmable Systems Interface Data Manual''.

=== Checking the interrupt inputs ===

In general, every interrupt input can be read via CRU access:

CLR R12
TB 15
JEQ NOINT15

TB copies the bit at the specified CRU address to the Equal status bit. This means that JEQ jumps to the location when the bit is 1. Since all interrupt inputs are negative logic, reading a 1 means that there is no interrupt at this input (so I called it NOINT15).

If we want to read several interrupt inputs by a single instruction, we have to use STCR.

LI R12,16
STCR R1,8

This reads the states of the /INT8, /INT9, ..., /INT15 inputs and puts them in the most significant byte of R1. (See the specification of STCR and LDCR for transfers of up to 8 bits.)

=== Interrupt levels ===

Each interrupt input (/INT1 to /INT15) may be used to trigger an interrupt at another circuit, typically the CPU. For this purpose, the PSI offers an /INTREQ outgoing line. In the TI console, it is routed to the /INTREQ input of the TMS9900 CPU.

In addition there is a priority encoder, which is not shown here. This encoder outputs a 4-bit number which reflects the smallest number of the interrupt inputs where an interrupt has been sensed.

That is, if /INT4 and /INT7 are currently set to 0 (active), the priority encoder outputs (0100), which means 4.

The TMS9900 CPU can differentiate between these interrupt levels, and by using its LIMI command, we can set a threshold where interrupts are ignored. So when we use a LIMI 3, the interrupts of level 4, 5, 6 and higher will be ignored.

The bad news is that Texas Instruments did not use these priority lines in the TI console. In fact, these outputs (IC0 .. IC3) are not connected, and the respective interrupt level inputs at the CPU are hardwired to (0001), which means that every interrupt that occurs in the TI console is automatically set to level 1. So in order to block all interrupts from the 9901

LIMI 0

must be executed. To allow all,

LIMI 1

is sufficient. For some unclear reason, TI used LIMI 2 in all occasions.

=== Arming and disarming interrupts ===

As said above, every interrupt input can be read at any time in interrupt mode. In that sense, we don't really treat these inputs as interrupts inputs, but simply as input ports.

If we want a port to trigger an interrupt, we must arm this interrupt input. This is done by setting the respective bit to 1.

CLR R12
SBO 2

This enables interrupt input /INT2 to cause an /INTREQ when its input changes to 0. In the TI console, /INT2 is connected to the interrupt output of the VDP (video processor). If you want to block interrupts on that input, use SBZ.

It is a common misunderstanding that interrupts can be cleared by using a SBZ on an input. I also found this in the popular ''TI Intern'' book. Instead, SBZ n simply blocks interrupt input /INTn. In the case of the video processor, it is up to the VDP to clear its interrupt, and this is done by reading its status register.

Consequently, you '''cannot''' read the current mask setting of the 9901. What you get from reading are the input levels of the pins. So if you plan to change the mask bits temporarily, be aware that you cannot ask the 9901 to give you the current setting which you want to restore later. You will have to find out by another way.

== Counter mode ==

Besides the I/O capabilities, the PSI offers a "real-time" clock. This should not be understood as a precise timer with seconds, hundreds of seconds or other but as a countdown timer that is decremented every 64 CPU clock cycles.

This schematic is taken from the Osborne book, redrawn by me in LibreOffice (and with added Load Buffer).

[[File:Clock9901.png|550px]]

=== Using the timer ===

There are basically two ways of using the countdown timer:

* Interval timer: Set the counter to a value; wait until the counter reaches zero. The PSI can be set up to raise an interrupt at that instant.
* Event timer: Set the counter to a value; do something and then read the counter value.

The counter has 14 bits; that is, its maximum value is 0x3FFF (16383). The counter is decremented every 64 clock cycles, and for the TI-99/4A and the Geneve with a clock cycle time of 333ns, this means that the counter resolution is 21.333 µs. The whole 16384 steps take 0.3495 seconds (349.5 ms).

When the counter reaches 0, it is reloaded from the load buffer, and counting continues.

It is essential to understand that the counter '''always''' counts down, independent of the mode. The specification says that the clock is enabled when a non-zero value is loaded into the load buffer, but tests on a real Geneve show that the clock decrements even when the load buffer is filled with 0.

=== Setting the timer ===

In order to set the load buffer and so to define the maximum counter value, we must switch to clock mode. This is achieved by setting bit 0 of the PSI to 1. In the TI/Geneve systems, the PSI is mapped to CRU base address 0, so we can do this

CLR R12
SBO 0

to enter '''clock mode'''. Using SBZ 0 returns to '''interrupt mode'''.

The effect of switching to clock mode is that the load buffer becomes accessible by the CRU addresses 1 to 14. Supposed that we want to load the buffer with the value 0x00FF, we may use these lines:

CLR R12
SBO 0
LI R1,>00FF
INCT R12
LDCR R1,14

As we see, we must change the CRU base. The LDCR operation always starts at the address defined in R12; if this is not 0, we have to set it here. Note, however, that the CRU address is always half of the R12 value, since the rightmost bit, A15, is not part of the address. If we want to start at bit 1, we must increase R12 by 2. This is, by the way, done wrong in several places in the literature where R12 is only set to 1.

We can combine the SBO and the LDCR to one operation if we define the rightmost bit of R1 as the bit 0 and the following bits as the timer value.

CLR R12
LI R1,>01FF (0000 0001 1111 1111)
LDCR R1,15

Do '''not''' write all 16 bits. The last bit will change bit 15 of the PSI, which is the /RST2 bit. When we are in clock mode, writing a 0 to the /RST2 bit resets all I/O ports. This means that all pins are set to inputs, and devices that rely on them as outputs may be turned off unintentionally.

=== Reading the timer ===

We are interested for the current value of the timer at some occasions. However, since the counter is constantly changing (every 64 clock cycles), reading from the active counter may deliver a wrong result. Think, for instance, about a value 0x2000, which is decremented after we read the first bits, we may end up with 0x2FFF (2 from 0x2000, FFF from 0x1FFF).

For this reason, the timer value is copied to a '''read buffer'''. This happens at every 64th clock cycle, when the counter is also decremented, but only when we are '''not''' in clock mode.

To read the buffer, we must set the PSI to clock mode first, which freezes the counter value in the read buffer. Then we can read the counter using STCR.

CLR R12
SBO 0
STCR R1,15
SRL R1,1
SBZ 0

As we see, register 1 will contain bit 0 in its rightmost bit, so we shift R1 by one position to move it out.

Do not forget to return to interrupt mode, or the buffer will not receive further updates.

As mentioned, bit 15 is the /RST2 bit when we write to it. For reading, bit 15 reflects the /INTREQ output.

=== The weird S0 input ===

There is one peculiarity with the PSI. When the input line S0 is set to 1, the clock mode is '''left temporarily''' - until S0 is 0 again, and bit 0 is 1. If bit 0 is 0, this has no effect, as the clock mode is never entered.

What is the reason for this?

TI obviously considered use cases where the PSI remains in clock mode for longer times, while the I/O ports must still be operated. The I/O ports are available on bits 16-31, which means that the S0 input is 1 for these addresses. So when we do a SBO 16, this is not related to the timer value, and thus should control the first I/O port. To allow this, the chip returns to interrupt/port mode for this operation, and when S0 is reset, returns to clock mode.

In the TI console, the S0-S4 inputs are directly connected with the address bus lines A10-A14. This has a strange side effect: Whenever address bus line A10 changes to 1, the clock mode is left temporarily, and this also happens for ordinary memory accesses.

Suppose that we are in clock mode (SBO 0). In this mode, the read buffer should not be updated, so when we read it, we should get the same value every time, although the real counter value is different. But this is difficult to achieve: If our program uses a memory address where A10 is 1 for some instruction, loading this instruction into the CPU will set A10 to 1, and thus leave clock mode, which updates the counter.

Therefore, you may have the impression that the read register continues to be updated even though you set bit 0 to 1. But this is only happening because your program extends over a location where A10 is 1. So if you want to prove that in clock mode the read register remains fixed, your program must avoid all memory locations where A10 is 1.

== Shared pins ==

Some pins have a double meaning; for example, pin 34 is labeled /INT7 / P15. How do we select the functions?

The shared pins are those for the interrupt inputs /INT7 to /INT15; they may also be used for P7 to P15 (in the opposite order).

If the Pn port is set to '''input''', the situation looks like this:

[[File:Shared9901in.png|250px]]

This means that both port and interrupt input have the same values; each one is a mirror of the other's state. We notice it by reading the bits of the associated CRU addresses, getting the same results. There is a difference, though: The interrupt input can be armed to trigger an outgoing interrupt, while the I/O port cannot.

In the other case, the Pn port is an '''output'''.

[[File:Shared9901out.png|250px]]

Is that possible? - Sure. The interrupt input will reflect the output of the port. When we set the port to 1, the interrupt input will get that 1 (same for 0). If we arm the interrupt input, setting the output port to 0 will trigger an interrupt via this input. The 9901 specification document recommends to disarm the interrupt trigger for the shared ports because of this possibly unwanted effect.

== Safety precautions ==

The TMS9901 PSI is an interrupt encoder and an I/O circuit. You may have heard that improper use of I/O circuits may damage the circuit so that it must be replaced. Is this possible with the 9901 as well? Is there a way to kill the 9901?

Short answer: Yes.

Longer answer: Yes, but it depends on the way how the ports are used.

If the port is used as an input, nothing bad will happen, since the ports have high input impedance. You can put 0V or 5V directly to the input; of course, you should not use excessive voltage.

=== How to damage the 9901 ports ===

The problem is when the port is configured as an output port. In that case it may output 0V (0) or 5V (1). When you connect the output to the opposite voltage, you will cause a short circuit which quickly exceeds the chip's maximum power dissipation of 750 mW. This means you will fry the chip.

Consider the following setup (but don't try it!).

[[File:Badport9901.png|300px]]

Obviously, port P4 is assumed to be an input. When the switch is open, port P4 will sense a 1 on its input. When the switch is closed, it will sense a 0.

Now what happens when you execute this code?

CLR R12
SBO 20

This will program port P4 to be an output, and to show a 1 (5V) at the output. SBZ will, in contrast, make this port output a 0. So how do you make it an input port? - This is done by resetting the chip. As long as you don't use a SBZ/SBO (or a LDCR) on the ports, the ports are inputs.

Nothing has happened up to now. But now imagine that you press the switch. This will put the 1 output to ground, causing the short circuit, and your 9901 is toast.

=== What about the TI console? ===

So can we damage the 9901 in the TI console by a suitable CRU operation? - Luckily not.

The reason is the way how TI used the ports on the mainboard. Most of the ports are configured as outputs. Nothing happens when you reset them to inputs.

* The pure interrupt inputs (/INT1 to /INT6) are safe, as they cannot output anything. They have no output driver that could be fried.
* P0 and P1 are not connected.
* P2, P3, and P4 are designed as outputs, so they cannot be turned from an input to an output.
* P5 is the selector of the Alpha Lock key, so output as well.
* P6 and P7 (/INT15) are the cassette motor control outputs.
* P8 (/INT14) is the audio gate output.
* P9 (/INT13) is the cassette output.
* P10 (/INT12) is pulled up to 5V via a 10 kOhm resistor. If you put a 0 on this port (5V), the maximum current is 500 µA, which results in a power dissipation of 2.5 mW (far below the maximum 750 mW).
* P11 (/INT11) is the cassette input. However, there is a resistor of 2.2 kOhm (R413) which effectively guards the port of high currents.
* P12, P13, P14, P15 (/INT10 ... /INT7) are the keyboard input lines. Again, we have pull-ups of 10 kOhm against +5V, but also 470 Ohm on the line, which means a maximum of 8.5 mA or 42.5 mW. This is still well below the maximum value.

So we see that resistors are the best way to protect the ports. And we may calm down; we cannot burn the 9901 in the TI console by a bug in our program.

Programmable Systems Interface TMS 9901

2022-04-23T13:40:37Z

Mizapf: /* Input/Output port operation */

The Programmable System Interface (PSI) is a circuit that is used on the TI-99/4A main board, on some expansion cards, and on the Geneve.

The designation of the PSI is '''TMS9901''', and this is the name that most users should be more familiar with.

== Features ==

The TMS 9901 Programmable Systems Interface is a multi-purpose circuit that is used in the TI-99/4A and the Geneve computer, and also on some peripheral cards like the Corcomp Floppy Disk Controller.

The 9901 has three main usage modes:

* Input/Output ports
* Interrupt prioritizing
* Timer

The I/O ports are mainly used for scanning the keyboard and joysticks, while the timer is used for cassette data encoding and decoding. The interrupt prioritizer is only used for the video interrupt which is routed from the VDP to the CPU through the 9901.

== Package ==

This is the pin assignment according to the 9901 specification.

[[File:Pack9901.png|300px|left]]

You can see pins of related functions marked by the same background color.

* Orange: Interrupt inputs
* Red: CRU bit selection (00000 - 11111, i.e. 0-31 decimal)
* Blue: CRU interface
* Violet: I/O ports
* Yellow: Outgoing interrupt and level

Note that some pins have a double function, or in other words, two functions share the same pin. I will discuss this in the following sections.

<div style="clear:both"></div>

== Input/Output port operation ==

The simplest way of working with the 9901 is input/output operation with the ports. The 9901 has 16 configurable ports that can be individually used as inputs or outputs: P0 to P15.

=== Px port as input ===

[[File:Port9901in.png|250px]]

The power-on preset for every port is input. If you want to probe the P2 status (bit 18), use

CLR R12
TB 18
JEQ P2ACT

TB copies the bit at the given CRU address into the Equal bit of the status register. JEQ will jump to the location when this input has a high level. The maximum input current is 100 µA. You should protect the input with a resistor; [[#Safety_precautions | see below]] for a more detailed discussion.

If you want to read all 16 ports, use the STCR instruction:

LI R12,32
STCR R1,0

Note that the CRU base address in R12 advances in steps of 2, so bit 16 is on address 32. Also, for reading 16 bits, you must specify a count of 0.

The 9901 offers some more inputs than the 16 ports; we can use the interrupt inputs as well. More about that can be found in the section about the [[#Interrupt_mode| interrupt mode]].

=== Px port as output ===

[[File:Port9901out.png|250px]]

Once you write a value to the CRU address of a 9901 port, this port switches to output mode. The value written to the port is the value that is shown on its pin. If we want to output a 1 on P6, we have to use

CLR R12
SBO 22

If we wanted to output a 0, SBZ would have to be used. In order to set several ports in one go, use LDCR.

We can also read the output port just by using TB as usual (or STCR for several ports at once).

CLR R12
SBO 22
TB 22
JEQ EXPECT

The TB operation should return the 1 which the previous SBO has set.

You '''cannot''' switch back to input mode. This is only possible by resetting the 9901, either using the /RST1 input line, or by setting the /RST2 bit (bit 15) to 0 in clock mode.

== Interrupt mode ==

In interrupt mode, bits 1 to 15 are used to set the interrupt mask (write), or to query the interrupt inputs (read). That is, the meaning of reading and writing the bits is indeed different.

This schema shows how the interrupt inputs are used.

[[File:Int9901.png|600px]]

This illustration is slightly simplified; there is a latch between each interrupt input and the mask AND gate. This is not relevant for our programming, though. For more details see the ''TMS 9901 Programmable Systems Interface Data Manual''.

=== Checking the interrupt inputs ===

In general, every interrupt input can be read via CRU access:

CLR R12
TB 15
JEQ NOINT15

TB copies the bit at the specified CRU address to the Equal status bit. This means that JEQ jumps to the location when the bit is 1. Since all interrupt inputs are negative logic, reading a 1 means that there is no interrupt at this input (so I called it NOINT15).

If we want to read several interrupt inputs by a single instruction, we have to use STCR.

LI R12,16
STCR R1,8

This reads the states of the /INT8, /INT9, ..., /INT15 inputs and puts them in the most significant byte of R1. (See the specification of STCR and LDCR for transfers of up to 8 bits.)

=== Interrupt levels ===

Each interrupt input (/INT1 to /INT15) may be used to trigger an interrupt at another circuit, typically the CPU. For this purpose, the PSI offers an /INTREQ outgoing line. In the TI console, it is routed to the /INTREQ input of the TMS9900 CPU.

In addition there is a priority encoder, which is not shown here. This encoder outputs a 4-bit number which reflects the smallest number of the interrupt inputs where an interrupt has been sensed.

That is, if /INT4 and /INT7 are currently set to 0 (active), the priority encoder outputs (0100), which means 4.

The TMS9900 CPU can differentiate between these interrupt levels, and by using its LIMI command, we can set a threshold where interrupts are ignored. So when we use a LIMI 3, the interrupts of level 4, 5, 6 and higher will be ignored.

The bad news is that Texas Instruments did not use these priority lines in the TI console. In fact, these outputs (IC0 .. IC3) are not connected, and the respective interrupt level inputs at the CPU are hardwired to (0001), which means that every interrupt that occurs in the TI console is automatically set to level 1. So in order to block all interrupts from the 9901

LIMI 0

must be executed. To allow all,

LIMI 1

is sufficient. For some unclear reason, TI used LIMI 2 in all occasions.

=== Arming and disarming interrupts ===

As said above, every interrupt input can be read at any time in interrupt mode. In that sense, we don't really treat these inputs as interrupts inputs, but simply as input ports.

If we want a port to trigger an interrupt, we must arm this interrupt input. This is done by setting the respective bit to 1.

CLR R12
SBO 2

This enables interrupt input /INT2 to cause an /INTREQ when its input changes to 0. In the TI console, /INT2 is connected to the interrupt output of the VDP (video processor). If you want to block interrupts on that input, use SBZ.

It is a common misunderstanding that interrupts can be cleared by using a SBZ on an input. This can, for example, be seen in the popular TI Intern book. Instead, SBZ n simply blocks interrupt input /INTn. In the case of the video processor, it is up to the VDP to clear its interrupt, and this is done by reading its status register.

== Counter mode ==

Besides the I/O capabilities, the PSI offers a "real-time" clock. This should not be understood as a precise timer with seconds, hundreds of seconds or other but as a countdown timer that is decremented every 64 CPU clock cycles.

This schematic is taken from the Osborne book, redrawn by me in LibreOffice (and with added Load Buffer).

[[File:Clock9901.png|550px]]

=== Using the timer ===

There are basically two ways of using the countdown timer:

* Interval timer: Set the counter to a value; wait until the counter reaches zero. The PSI can be set up to raise an interrupt at that instant.
* Event timer: Set the counter to a value; do something and then read the counter value.

The counter has 14 bits; that is, its maximum value is 0x3FFF (16383). The counter is decremented every 64 clock cycles, and for the TI-99/4A and the Geneve with a clock cycle time of 333ns, this means that the counter resolution is 21.333 µs. The whole 16384 steps take 0.3495 seconds (349.5 ms).

When the counter reaches 0, it is reloaded from the load buffer, and counting continues.

It is essential to understand that the counter '''always''' counts down, independent of the mode. The specification says that the clock is enabled when a non-zero value is loaded into the load buffer, but tests on a real Geneve show that the clock decrements even when the load buffer is filled with 0.

=== Setting the timer ===

In order to set the load buffer and so to define the maximum counter value, we must switch to clock mode. This is achieved by setting bit 0 of the PSI to 1. In the TI/Geneve systems, the PSI is mapped to CRU base address 0, so we can do this

CLR R12
SBO 0

to enter '''clock mode'''. Using SBZ 0 returns to '''interrupt mode'''.

The effect of switching to clock mode is that the load buffer becomes accessible by the CRU addresses 1 to 14. Supposed that we want to load the buffer with the value 0x00FF, we may use these lines:

CLR R12
SBO 0
LI R1,>00FF
INCT R12
LDCR R1,14

As we see, we must change the CRU base. The LDCR operation always starts at the address defined in R12; if this is not 0, we have to set it here. Note, however, that the CRU address is always half of the R12 value, since the rightmost bit, A15, is not part of the address. If we want to start at bit 1, we must increase R12 by 2. This is, by the way, done wrong in several places in the literature where R12 is only set to 1.

We can combine the SBO and the LDCR to one operation if we define the rightmost bit of R1 as the bit 0 and the following bits as the timer value.

CLR R12
LI R1,>01FF (0000 0001 1111 1111)
LDCR R1,15

Do '''not''' write all 16 bits. The last bit will change bit 15 of the PSI, which is the /RST2 bit. When we are in clock mode, writing a 0 to the /RST2 bit resets all I/O ports. This means that all pins are set to inputs, and devices that rely on them as outputs may be turned off unintentionally.

=== Reading the timer ===

We are interested for the current value of the timer at some occasions. However, since the counter is constantly changing (every 64 clock cycles), reading from the active counter may deliver a wrong result. Think, for instance, about a value 0x2000, which is decremented after we read the first bits, we may end up with 0x2FFF (2 from 0x2000, FFF from 0x1FFF).

For this reason, the timer value is copied to a '''read buffer'''. This happens at every 64th clock cycle, when the counter is also decremented, but only when we are '''not''' in clock mode.

To read the buffer, we must set the PSI to clock mode first, which freezes the counter value in the read buffer. Then we can read the counter using STCR.

CLR R12
SBO 0
STCR R1,15
SRL R1,1
SBZ 0

As we see, register 1 will contain bit 0 in its rightmost bit, so we shift R1 by one position to move it out.

Do not forget to return to interrupt mode, or the buffer will not receive further updates.

As mentioned, bit 15 is the /RST2 bit when we write to it. For reading, bit 15 reflects the /INTREQ output.

=== The weird S0 input ===

There is one peculiarity with the PSI. When the input line S0 is set to 1, the clock mode is '''left temporarily''' - until S0 is 0 again, and bit 0 is 1. If bit 0 is 0, this has no effect, as the clock mode is never entered.

What is the reason for this?

TI obviously considered use cases where the PSI remains in clock mode for longer times, while the I/O ports must still be operated. The I/O ports are available on bits 16-31, which means that the S0 input is 1 for these addresses. So when we do a SBO 16, this is not related to the timer value, and thus should control the first I/O port. To allow this, the chip returns to interrupt/port mode for this operation, and when S0 is reset, returns to clock mode.

In the TI console, the S0-S4 inputs are directly connected with the address bus lines A10-A14. This has a strange side effect: Whenever address bus line A10 changes to 1, the clock mode is left temporarily, and this also happens for ordinary memory accesses.

Suppose that we are in clock mode (SBO 0). In this mode, the read buffer should not be updated, so when we read it, we should get the same value every time, although the real counter value is different. But this is difficult to achieve: If our program uses a memory address where A10 is 1 for some instruction, loading this instruction into the CPU will set A10 to 1, and thus leave clock mode, which updates the counter.

Therefore, you may have the impression that the read register continues to be updated even though you set bit 0 to 1. But this is only happening because your program extends over a location where A10 is 1. So if you want to prove that in clock mode the read register remains fixed, your program must avoid all memory locations where A10 is 1.

== Shared pins ==

Some pins have a double meaning; for example, pin 34 is labeled /INT7 / P15. How do we select the functions?

The shared pins are those for the interrupt inputs /INT7 to /INT15; they may also be used for P7 to P15 (in the opposite order).

If the Pn port is set to '''input''', the situation looks like this:

[[File:Shared9901in.png|250px]]

This means that both port and interrupt input have the same values; each one is a mirror of the other's state. We notice it by reading the bits of the associated CRU addresses, getting the same results. There is a difference, though: The interrupt input can be armed to trigger an outgoing interrupt, while the I/O port cannot.

In the other case, the Pn port is an '''output'''.

[[File:Shared9901out.png|250px]]

Is that possible? - Sure. The interrupt input will reflect the output of the port. When we set the port to 1, the interrupt input will get that 1 (same for 0). If we arm the interrupt input, setting the output port to 0 will trigger an interrupt via this input. The 9901 specification document recommends to disarm the interrupt trigger for the shared ports because of this possibly unwanted effect.

== Safety precautions ==

The TMS9901 PSI is an interrupt encoder and an I/O circuit. You may have heard that improper use of I/O circuits may damage the circuit so that it must be replaced. Is this possible with the 9901 as well? Is there a way to kill the 9901?

Short answer: Yes.

Longer answer: Yes, but it depends on the way how the ports are used.

If the port is used as an input, nothing bad will happen, since the ports have high input impedance. You can put 0V or 5V directly to the input; of course, you should not use excessive voltage.

=== How to damage the 9901 ports ===

The problem is when the port is configured as an output port. In that case it may output 0V (0) or 5V (1). When you connect the output to the opposite voltage, you will cause a short circuit which quickly exceeds the chip's maximum power dissipation of 750 mW. This means you will fry the chip.

Consider the following setup (but don't try it!).

[[File:Badport9901.png|300px]]

Obviously, port P4 is assumed to be an input. When the switch is open, port P4 will sense a 1 on its input. When the switch is closed, it will sense a 0.

Now what happens when you execute this code?

CLR R12
SBO 20

This will program port P4 to be an output, and to show a 1 (5V) at the output. SBZ will, in contrast, make this port output a 0. So how do you make it an input port? - This is done by resetting the chip. As long as you don't use a SBZ/SBO (or a LDCR) on the ports, the ports are inputs.

Nothing has happened up to now. But now imagine that you press the switch. This will put the 1 output to ground, causing the short circuit, and your 9901 is toast.

=== What about the TI console? ===

So can we damage the 9901 in the TI console by a suitable CRU operation? - Luckily not.

The reason is the way how TI used the ports on the mainboard. Most of the ports are configured as outputs. Nothing happens when you reset them to inputs.

* The pure interrupt inputs (/INT1 to /INT6) are safe, as they cannot output anything. They have no output driver that could be fried.
* P0 and P1 are not connected.
* P2, P3, and P4 are designed as outputs, so they cannot be turned from an input to an output.
* P5 is the selector of the Alpha Lock key, so output as well.
* P6 and P7 (/INT15) are the cassette motor control outputs.
* P8 (/INT14) is the audio gate output.
* P9 (/INT13) is the cassette output.
* P10 (/INT12) is pulled up to 5V via a 10 kOhm resistor. If you put a 0 on this port (5V), the maximum current is 500 µA, which results in a power dissipation of 2.5 mW (far below the maximum 750 mW).
* P11 (/INT11) is the cassette input. However, there is a resistor of 2.2 kOhm (R413) which effectively guards the port of high currents.
* P12, P13, P14, P15 (/INT10 ... /INT7) are the keyboard input lines. Again, we have pull-ups of 10 kOhm against +5V, but also 470 Ohm on the line, which means a maximum of 8.5 mA or 42.5 mW. This is still well below the maximum value.

So we see that resistors are the best way to protect the ports. And we may calm down; we cannot burn the 9901 in the TI console by a bug in our program.

Programmable Systems Interface TMS 9901

2022-04-23T13:39:53Z

Mizapf: /* Input/Output port operation */

The Programmable System Interface (PSI) is a circuit that is used on the TI-99/4A main board, on some expansion cards, and on the Geneve.

The designation of the PSI is '''TMS9901''', and this is the name that most users should be more familiar with.

== Features ==

The TMS 9901 Programmable Systems Interface is a multi-purpose circuit that is used in the TI-99/4A and the Geneve computer, and also on some peripheral cards like the Corcomp Floppy Disk Controller.

The 9901 has three main usage modes:

* Input/Output ports
* Interrupt prioritizing
* Timer

The I/O ports are mainly used for scanning the keyboard and joysticks, while the timer is used for cassette data encoding and decoding. The interrupt prioritizer is only used for the video interrupt which is routed from the VDP to the CPU through the 9901.

== Package ==

This is the pin assignment according to the 9901 specification.

[[File:Pack9901.png|300px|left]]

You can see pins of related functions marked by the same background color.

* Orange: Interrupt inputs
* Red: CRU bit selection (00000 - 11111, i.e. 0-31 decimal)
* Blue: CRU interface
* Violet: I/O ports
* Yellow: Outgoing interrupt and level

Note that some pins have a double function, or in other words, two functions share the same pin. I will discuss this in the following sections.

<div style="clear:both"></div>

== Input/Output port operation ==

The simplest way of working with the 9901 is input/output operation with the ports. The 9901 has 16 configurable ports that can be individually used as inputs or outputs: P0 to P15.

=== Px port as input ===

[[File:Port9901in.png|250px]]

The power-on preset for every port is input. If you want to probe the P2 status (bit 18), use

CLR R12
TB 18
JEQ P2ACT

TB copies the bit at the given CRU address into the Equal bit of the status register. JEQ will jump to the location when this input has a high level. The maximum input current is 100 µA. You should protect the input with a resistor; see below for a more detailed discussion.

If you want to read all 16 ports, use the STCR instruction:

LI R12,32
STCR R1,0

Note that the CRU base address in R12 advances in steps of 2, so bit 16 is on address 32. Also, for reading 16 bits, you must specify a count of 0.

The 9901 offers some more inputs than the 16 ports; we can use the interrupt inputs as well. More about that can be found in the section about the [[#Interrupt_mode| interrupt mode]].

=== Px port as output ===

[[File:Port9901out.png|250px]]

Once you write a value to the CRU address of a 9901 port, this port switches to output mode. The value written to the port is the value that is shown on its pin. If we want to output a 1 on P6, we have to use

CLR R12
SBO 22

If we wanted to output a 0, SBZ would have to be used. In order to set several ports in one go, use LDCR.

We can also read the output port just by using TB as usual (or STCR for several ports at once).

CLR R12
SBO 22
TB 22
JEQ EXPECT

The TB operation should return the 1 which the previous SBO has set.

You '''cannot''' switch back to input mode. This is only possible by resetting the 9901, either using the /RST1 input line, or by setting the /RST2 bit (bit 15) to 0 in clock mode.

== Interrupt mode ==

In interrupt mode, bits 1 to 15 are used to set the interrupt mask (write), or to query the interrupt inputs (read). That is, the meaning of reading and writing the bits is indeed different.

This schema shows how the interrupt inputs are used.

[[File:Int9901.png|600px]]

This illustration is slightly simplified; there is a latch between each interrupt input and the mask AND gate. This is not relevant for our programming, though. For more details see the ''TMS 9901 Programmable Systems Interface Data Manual''.

=== Checking the interrupt inputs ===

In general, every interrupt input can be read via CRU access:

CLR R12
TB 15
JEQ NOINT15

TB copies the bit at the specified CRU address to the Equal status bit. This means that JEQ jumps to the location when the bit is 1. Since all interrupt inputs are negative logic, reading a 1 means that there is no interrupt at this input (so I called it NOINT15).

If we want to read several interrupt inputs by a single instruction, we have to use STCR.

LI R12,16
STCR R1,8

This reads the states of the /INT8, /INT9, ..., /INT15 inputs and puts them in the most significant byte of R1. (See the specification of STCR and LDCR for transfers of up to 8 bits.)

=== Interrupt levels ===

Each interrupt input (/INT1 to /INT15) may be used to trigger an interrupt at another circuit, typically the CPU. For this purpose, the PSI offers an /INTREQ outgoing line. In the TI console, it is routed to the /INTREQ input of the TMS9900 CPU.

In addition there is a priority encoder, which is not shown here. This encoder outputs a 4-bit number which reflects the smallest number of the interrupt inputs where an interrupt has been sensed.

That is, if /INT4 and /INT7 are currently set to 0 (active), the priority encoder outputs (0100), which means 4.

The TMS9900 CPU can differentiate between these interrupt levels, and by using its LIMI command, we can set a threshold where interrupts are ignored. So when we use a LIMI 3, the interrupts of level 4, 5, 6 and higher will be ignored.

The bad news is that Texas Instruments did not use these priority lines in the TI console. In fact, these outputs (IC0 .. IC3) are not connected, and the respective interrupt level inputs at the CPU are hardwired to (0001), which means that every interrupt that occurs in the TI console is automatically set to level 1. So in order to block all interrupts from the 9901

LIMI 0

must be executed. To allow all,

LIMI 1

is sufficient. For some unclear reason, TI used LIMI 2 in all occasions.

=== Arming and disarming interrupts ===

As said above, every interrupt input can be read at any time in interrupt mode. In that sense, we don't really treat these inputs as interrupts inputs, but simply as input ports.

If we want a port to trigger an interrupt, we must arm this interrupt input. This is done by setting the respective bit to 1.

CLR R12
SBO 2

This enables interrupt input /INT2 to cause an /INTREQ when its input changes to 0. In the TI console, /INT2 is connected to the interrupt output of the VDP (video processor). If you want to block interrupts on that input, use SBZ.

It is a common misunderstanding that interrupts can be cleared by using a SBZ on an input. This can, for example, be seen in the popular TI Intern book. Instead, SBZ n simply blocks interrupt input /INTn. In the case of the video processor, it is up to the VDP to clear its interrupt, and this is done by reading its status register.

== Counter mode ==

Besides the I/O capabilities, the PSI offers a "real-time" clock. This should not be understood as a precise timer with seconds, hundreds of seconds or other but as a countdown timer that is decremented every 64 CPU clock cycles.

This schematic is taken from the Osborne book, redrawn by me in LibreOffice (and with added Load Buffer).

[[File:Clock9901.png|550px]]

=== Using the timer ===

There are basically two ways of using the countdown timer:

* Interval timer: Set the counter to a value; wait until the counter reaches zero. The PSI can be set up to raise an interrupt at that instant.
* Event timer: Set the counter to a value; do something and then read the counter value.

The counter has 14 bits; that is, its maximum value is 0x3FFF (16383). The counter is decremented every 64 clock cycles, and for the TI-99/4A and the Geneve with a clock cycle time of 333ns, this means that the counter resolution is 21.333 µs. The whole 16384 steps take 0.3495 seconds (349.5 ms).

When the counter reaches 0, it is reloaded from the load buffer, and counting continues.

It is essential to understand that the counter '''always''' counts down, independent of the mode. The specification says that the clock is enabled when a non-zero value is loaded into the load buffer, but tests on a real Geneve show that the clock decrements even when the load buffer is filled with 0.

=== Setting the timer ===

In order to set the load buffer and so to define the maximum counter value, we must switch to clock mode. This is achieved by setting bit 0 of the PSI to 1. In the TI/Geneve systems, the PSI is mapped to CRU base address 0, so we can do this

CLR R12
SBO 0

to enter '''clock mode'''. Using SBZ 0 returns to '''interrupt mode'''.

The effect of switching to clock mode is that the load buffer becomes accessible by the CRU addresses 1 to 14. Supposed that we want to load the buffer with the value 0x00FF, we may use these lines:

CLR R12
SBO 0
LI R1,>00FF
INCT R12
LDCR R1,14

As we see, we must change the CRU base. The LDCR operation always starts at the address defined in R12; if this is not 0, we have to set it here. Note, however, that the CRU address is always half of the R12 value, since the rightmost bit, A15, is not part of the address. If we want to start at bit 1, we must increase R12 by 2. This is, by the way, done wrong in several places in the literature where R12 is only set to 1.

We can combine the SBO and the LDCR to one operation if we define the rightmost bit of R1 as the bit 0 and the following bits as the timer value.

CLR R12
LI R1,>01FF (0000 0001 1111 1111)
LDCR R1,15

Do '''not''' write all 16 bits. The last bit will change bit 15 of the PSI, which is the /RST2 bit. When we are in clock mode, writing a 0 to the /RST2 bit resets all I/O ports. This means that all pins are set to inputs, and devices that rely on them as outputs may be turned off unintentionally.

=== Reading the timer ===

We are interested for the current value of the timer at some occasions. However, since the counter is constantly changing (every 64 clock cycles), reading from the active counter may deliver a wrong result. Think, for instance, about a value 0x2000, which is decremented after we read the first bits, we may end up with 0x2FFF (2 from 0x2000, FFF from 0x1FFF).

For this reason, the timer value is copied to a '''read buffer'''. This happens at every 64th clock cycle, when the counter is also decremented, but only when we are '''not''' in clock mode.

To read the buffer, we must set the PSI to clock mode first, which freezes the counter value in the read buffer. Then we can read the counter using STCR.

CLR R12
SBO 0
STCR R1,15
SRL R1,1
SBZ 0

As we see, register 1 will contain bit 0 in its rightmost bit, so we shift R1 by one position to move it out.

Do not forget to return to interrupt mode, or the buffer will not receive further updates.

As mentioned, bit 15 is the /RST2 bit when we write to it. For reading, bit 15 reflects the /INTREQ output.

=== The weird S0 input ===

There is one peculiarity with the PSI. When the input line S0 is set to 1, the clock mode is '''left temporarily''' - until S0 is 0 again, and bit 0 is 1. If bit 0 is 0, this has no effect, as the clock mode is never entered.

What is the reason for this?

TI obviously considered use cases where the PSI remains in clock mode for longer times, while the I/O ports must still be operated. The I/O ports are available on bits 16-31, which means that the S0 input is 1 for these addresses. So when we do a SBO 16, this is not related to the timer value, and thus should control the first I/O port. To allow this, the chip returns to interrupt/port mode for this operation, and when S0 is reset, returns to clock mode.

In the TI console, the S0-S4 inputs are directly connected with the address bus lines A10-A14. This has a strange side effect: Whenever address bus line A10 changes to 1, the clock mode is left temporarily, and this also happens for ordinary memory accesses.

Suppose that we are in clock mode (SBO 0). In this mode, the read buffer should not be updated, so when we read it, we should get the same value every time, although the real counter value is different. But this is difficult to achieve: If our program uses a memory address where A10 is 1 for some instruction, loading this instruction into the CPU will set A10 to 1, and thus leave clock mode, which updates the counter.

Therefore, you may have the impression that the read register continues to be updated even though you set bit 0 to 1. But this is only happening because your program extends over a location where A10 is 1. So if you want to prove that in clock mode the read register remains fixed, your program must avoid all memory locations where A10 is 1.

== Shared pins ==

Some pins have a double meaning; for example, pin 34 is labeled /INT7 / P15. How do we select the functions?

The shared pins are those for the interrupt inputs /INT7 to /INT15; they may also be used for P7 to P15 (in the opposite order).

If the Pn port is set to '''input''', the situation looks like this:

[[File:Shared9901in.png|250px]]

This means that both port and interrupt input have the same values; each one is a mirror of the other's state. We notice it by reading the bits of the associated CRU addresses, getting the same results. There is a difference, though: The interrupt input can be armed to trigger an outgoing interrupt, while the I/O port cannot.

In the other case, the Pn port is an '''output'''.

[[File:Shared9901out.png|250px]]

Is that possible? - Sure. The interrupt input will reflect the output of the port. When we set the port to 1, the interrupt input will get that 1 (same for 0). If we arm the interrupt input, setting the output port to 0 will trigger an interrupt via this input. The 9901 specification document recommends to disarm the interrupt trigger for the shared ports because of this possibly unwanted effect.

== Safety precautions ==

The TMS9901 PSI is an interrupt encoder and an I/O circuit. You may have heard that improper use of I/O circuits may damage the circuit so that it must be replaced. Is this possible with the 9901 as well? Is there a way to kill the 9901?

Short answer: Yes.

Longer answer: Yes, but it depends on the way how the ports are used.

If the port is used as an input, nothing bad will happen, since the ports have high input impedance. You can put 0V or 5V directly to the input; of course, you should not use excessive voltage.

=== How to damage the 9901 ports ===

The problem is when the port is configured as an output port. In that case it may output 0V (0) or 5V (1). When you connect the output to the opposite voltage, you will cause a short circuit which quickly exceeds the chip's maximum power dissipation of 750 mW. This means you will fry the chip.

Consider the following setup (but don't try it!).

[[File:Badport9901.png|300px]]

Obviously, port P4 is assumed to be an input. When the switch is open, port P4 will sense a 1 on its input. When the switch is closed, it will sense a 0.

Now what happens when you execute this code?

CLR R12
SBO 20

This will program port P4 to be an output, and to show a 1 (5V) at the output. SBZ will, in contrast, make this port output a 0. So how do you make it an input port? - This is done by resetting the chip. As long as you don't use a SBZ/SBO (or a LDCR) on the ports, the ports are inputs.

Nothing has happened up to now. But now imagine that you press the switch. This will put the 1 output to ground, causing the short circuit, and your 9901 is toast.

=== What about the TI console? ===

So can we damage the 9901 in the TI console by a suitable CRU operation? - Luckily not.

The reason is the way how TI used the ports on the mainboard. Most of the ports are configured as outputs. Nothing happens when you reset them to inputs.

* The pure interrupt inputs (/INT1 to /INT6) are safe, as they cannot output anything. They have no output driver that could be fried.
* P0 and P1 are not connected.
* P2, P3, and P4 are designed as outputs, so they cannot be turned from an input to an output.
* P5 is the selector of the Alpha Lock key, so output as well.
* P6 and P7 (/INT15) are the cassette motor control outputs.
* P8 (/INT14) is the audio gate output.
* P9 (/INT13) is the cassette output.
* P10 (/INT12) is pulled up to 5V via a 10 kOhm resistor. If you put a 0 on this port (5V), the maximum current is 500 µA, which results in a power dissipation of 2.5 mW (far below the maximum 750 mW).
* P11 (/INT11) is the cassette input. However, there is a resistor of 2.2 kOhm (R413) which effectively guards the port of high currents.
* P12, P13, P14, P15 (/INT10 ... /INT7) are the keyboard input lines. Again, we have pull-ups of 10 kOhm against +5V, but also 470 Ohm on the line, which means a maximum of 8.5 mA or 42.5 mW. This is still well below the maximum value.

So we see that resistors are the best way to protect the ports. And we may calm down; we cannot burn the 9901 in the TI console by a bug in our program.

Programmable Systems Interface TMS 9901

2022-04-23T13:39:05Z

Mizapf: /* Input/Output port operation */

The Programmable System Interface (PSI) is a circuit that is used on the TI-99/4A main board, on some expansion cards, and on the Geneve.

The designation of the PSI is '''TMS9901''', and this is the name that most users should be more familiar with.

== Features ==

The TMS 9901 Programmable Systems Interface is a multi-purpose circuit that is used in the TI-99/4A and the Geneve computer, and also on some peripheral cards like the Corcomp Floppy Disk Controller.

The 9901 has three main usage modes:

* Input/Output ports
* Interrupt prioritizing
* Timer

The I/O ports are mainly used for scanning the keyboard and joysticks, while the timer is used for cassette data encoding and decoding. The interrupt prioritizer is only used for the video interrupt which is routed from the VDP to the CPU through the 9901.

== Package ==

This is the pin assignment according to the 9901 specification.

[[File:Pack9901.png|300px|left]]

You can see pins of related functions marked by the same background color.

* Orange: Interrupt inputs
* Red: CRU bit selection (00000 - 11111, i.e. 0-31 decimal)
* Blue: CRU interface
* Violet: I/O ports
* Yellow: Outgoing interrupt and level

Note that some pins have a double function, or in other words, two functions share the same pin. I will discuss this in the following sections.

<div style="clear:both"></div>

== Input/Output port operation ==

The simplest way of working with the 9901 is input/output operation with the ports. The 9901 has 16 configurable ports that can be individually used as inputs or outputs: P0 to P15.

=== Px port as input ===

[[File:Port9901in.png|250px]]

The power-on preset for every port is input. If you want to probe the P2 status (bit 18), use

CLR R12
TB 18
JEQ P2ACT

TB copies the bit at the given CRU address into the Equal bit of the status register. JEQ will jump to the location when this input has a high level. The maximum input current is 100 µA. You should protect the input with a resistor; see below for a more detailed discussion.

If you want to read all 16 ports, use the STCR instruction:

LI R12,32
STCR R1,0

Note that the CRU base address in R12 advances in steps of 2, so bit 16 is on address 32. Also, for reading 16 bits, you must specify a count of 0.

The 9901 offers some more inputs than the 16 ports; we can use the interrupt inputs as well. More about that can be found in the section about the [[#interrupt_mode| interrupt mode]].

=== Px port as output ===

[[File:Port9901out.png|250px]]

Once you write a value to the CRU address of a 9901 port, this port switches to output mode. The value written to the port is the value that is shown on its pin. If we want to output a 1 on P6, we have to use

CLR R12
SBO 22

If we wanted to output a 0, SBZ would have to be used. In order to set several ports in one go, use LDCR.

We can also read the output port just by using TB as usual (or STCR for several ports at once).

CLR R12
SBO 22
TB 22
JEQ EXPECT

The TB operation should return the 1 which the previous SBO has set.

You '''cannot''' switch back to input mode. This is only possible by resetting the 9901, either using the /RST1 input line, or by setting the /RST2 bit (bit 15) to 0 in clock mode.

== Interrupt mode ==

In interrupt mode, bits 1 to 15 are used to set the interrupt mask (write), or to query the interrupt inputs (read). That is, the meaning of reading and writing the bits is indeed different.

This schema shows how the interrupt inputs are used.

[[File:Int9901.png|600px]]

This illustration is slightly simplified; there is a latch between each interrupt input and the mask AND gate. This is not relevant for our programming, though. For more details see the ''TMS 9901 Programmable Systems Interface Data Manual''.

=== Checking the interrupt inputs ===

In general, every interrupt input can be read via CRU access:

CLR R12
TB 15
JEQ NOINT15

TB copies the bit at the specified CRU address to the Equal status bit. This means that JEQ jumps to the location when the bit is 1. Since all interrupt inputs are negative logic, reading a 1 means that there is no interrupt at this input (so I called it NOINT15).

If we want to read several interrupt inputs by a single instruction, we have to use STCR.

LI R12,16
STCR R1,8

This reads the states of the /INT8, /INT9, ..., /INT15 inputs and puts them in the most significant byte of R1. (See the specification of STCR and LDCR for transfers of up to 8 bits.)

=== Interrupt levels ===

Each interrupt input (/INT1 to /INT15) may be used to trigger an interrupt at another circuit, typically the CPU. For this purpose, the PSI offers an /INTREQ outgoing line. In the TI console, it is routed to the /INTREQ input of the TMS9900 CPU.

In addition there is a priority encoder, which is not shown here. This encoder outputs a 4-bit number which reflects the smallest number of the interrupt inputs where an interrupt has been sensed.

That is, if /INT4 and /INT7 are currently set to 0 (active), the priority encoder outputs (0100), which means 4.

The TMS9900 CPU can differentiate between these interrupt levels, and by using its LIMI command, we can set a threshold where interrupts are ignored. So when we use a LIMI 3, the interrupts of level 4, 5, 6 and higher will be ignored.

The bad news is that Texas Instruments did not use these priority lines in the TI console. In fact, these outputs (IC0 .. IC3) are not connected, and the respective interrupt level inputs at the CPU are hardwired to (0001), which means that every interrupt that occurs in the TI console is automatically set to level 1. So in order to block all interrupts from the 9901

LIMI 0

must be executed. To allow all,

LIMI 1

is sufficient. For some unclear reason, TI used LIMI 2 in all occasions.

=== Arming and disarming interrupts ===

As said above, every interrupt input can be read at any time in interrupt mode. In that sense, we don't really treat these inputs as interrupts inputs, but simply as input ports.

If we want a port to trigger an interrupt, we must arm this interrupt input. This is done by setting the respective bit to 1.

CLR R12
SBO 2

This enables interrupt input /INT2 to cause an /INTREQ when its input changes to 0. In the TI console, /INT2 is connected to the interrupt output of the VDP (video processor). If you want to block interrupts on that input, use SBZ.

It is a common misunderstanding that interrupts can be cleared by using a SBZ on an input. This can, for example, be seen in the popular TI Intern book. Instead, SBZ n simply blocks interrupt input /INTn. In the case of the video processor, it is up to the VDP to clear its interrupt, and this is done by reading its status register.

== Counter mode ==

Besides the I/O capabilities, the PSI offers a "real-time" clock. This should not be understood as a precise timer with seconds, hundreds of seconds or other but as a countdown timer that is decremented every 64 CPU clock cycles.

This schematic is taken from the Osborne book, redrawn by me in LibreOffice (and with added Load Buffer).

[[File:Clock9901.png|550px]]

=== Using the timer ===

There are basically two ways of using the countdown timer:

* Interval timer: Set the counter to a value; wait until the counter reaches zero. The PSI can be set up to raise an interrupt at that instant.
* Event timer: Set the counter to a value; do something and then read the counter value.

The counter has 14 bits; that is, its maximum value is 0x3FFF (16383). The counter is decremented every 64 clock cycles, and for the TI-99/4A and the Geneve with a clock cycle time of 333ns, this means that the counter resolution is 21.333 µs. The whole 16384 steps take 0.3495 seconds (349.5 ms).

When the counter reaches 0, it is reloaded from the load buffer, and counting continues.

It is essential to understand that the counter '''always''' counts down, independent of the mode. The specification says that the clock is enabled when a non-zero value is loaded into the load buffer, but tests on a real Geneve show that the clock decrements even when the load buffer is filled with 0.

=== Setting the timer ===

In order to set the load buffer and so to define the maximum counter value, we must switch to clock mode. This is achieved by setting bit 0 of the PSI to 1. In the TI/Geneve systems, the PSI is mapped to CRU base address 0, so we can do this

CLR R12
SBO 0

to enter '''clock mode'''. Using SBZ 0 returns to '''interrupt mode'''.

The effect of switching to clock mode is that the load buffer becomes accessible by the CRU addresses 1 to 14. Supposed that we want to load the buffer with the value 0x00FF, we may use these lines:

CLR R12
SBO 0
LI R1,>00FF
INCT R12
LDCR R1,14

As we see, we must change the CRU base. The LDCR operation always starts at the address defined in R12; if this is not 0, we have to set it here. Note, however, that the CRU address is always half of the R12 value, since the rightmost bit, A15, is not part of the address. If we want to start at bit 1, we must increase R12 by 2. This is, by the way, done wrong in several places in the literature where R12 is only set to 1.

We can combine the SBO and the LDCR to one operation if we define the rightmost bit of R1 as the bit 0 and the following bits as the timer value.

CLR R12
LI R1,>01FF (0000 0001 1111 1111)
LDCR R1,15

Do '''not''' write all 16 bits. The last bit will change bit 15 of the PSI, which is the /RST2 bit. When we are in clock mode, writing a 0 to the /RST2 bit resets all I/O ports. This means that all pins are set to inputs, and devices that rely on them as outputs may be turned off unintentionally.

=== Reading the timer ===

We are interested for the current value of the timer at some occasions. However, since the counter is constantly changing (every 64 clock cycles), reading from the active counter may deliver a wrong result. Think, for instance, about a value 0x2000, which is decremented after we read the first bits, we may end up with 0x2FFF (2 from 0x2000, FFF from 0x1FFF).

For this reason, the timer value is copied to a '''read buffer'''. This happens at every 64th clock cycle, when the counter is also decremented, but only when we are '''not''' in clock mode.

To read the buffer, we must set the PSI to clock mode first, which freezes the counter value in the read buffer. Then we can read the counter using STCR.

CLR R12
SBO 0
STCR R1,15
SRL R1,1
SBZ 0

As we see, register 1 will contain bit 0 in its rightmost bit, so we shift R1 by one position to move it out.

Do not forget to return to interrupt mode, or the buffer will not receive further updates.

As mentioned, bit 15 is the /RST2 bit when we write to it. For reading, bit 15 reflects the /INTREQ output.

=== The weird S0 input ===

There is one peculiarity with the PSI. When the input line S0 is set to 1, the clock mode is '''left temporarily''' - until S0 is 0 again, and bit 0 is 1. If bit 0 is 0, this has no effect, as the clock mode is never entered.

What is the reason for this?

TI obviously considered use cases where the PSI remains in clock mode for longer times, while the I/O ports must still be operated. The I/O ports are available on bits 16-31, which means that the S0 input is 1 for these addresses. So when we do a SBO 16, this is not related to the timer value, and thus should control the first I/O port. To allow this, the chip returns to interrupt/port mode for this operation, and when S0 is reset, returns to clock mode.

In the TI console, the S0-S4 inputs are directly connected with the address bus lines A10-A14. This has a strange side effect: Whenever address bus line A10 changes to 1, the clock mode is left temporarily, and this also happens for ordinary memory accesses.

Suppose that we are in clock mode (SBO 0). In this mode, the read buffer should not be updated, so when we read it, we should get the same value every time, although the real counter value is different. But this is difficult to achieve: If our program uses a memory address where A10 is 1 for some instruction, loading this instruction into the CPU will set A10 to 1, and thus leave clock mode, which updates the counter.

Therefore, you may have the impression that the read register continues to be updated even though you set bit 0 to 1. But this is only happening because your program extends over a location where A10 is 1. So if you want to prove that in clock mode the read register remains fixed, your program must avoid all memory locations where A10 is 1.

== Shared pins ==

Some pins have a double meaning; for example, pin 34 is labeled /INT7 / P15. How do we select the functions?

The shared pins are those for the interrupt inputs /INT7 to /INT15; they may also be used for P7 to P15 (in the opposite order).

If the Pn port is set to '''input''', the situation looks like this:

[[File:Shared9901in.png|250px]]

This means that both port and interrupt input have the same values; each one is a mirror of the other's state. We notice it by reading the bits of the associated CRU addresses, getting the same results. There is a difference, though: The interrupt input can be armed to trigger an outgoing interrupt, while the I/O port cannot.

In the other case, the Pn port is an '''output'''.

[[File:Shared9901out.png|250px]]

Is that possible? - Sure. The interrupt input will reflect the output of the port. When we set the port to 1, the interrupt input will get that 1 (same for 0). If we arm the interrupt input, setting the output port to 0 will trigger an interrupt via this input. The 9901 specification document recommends to disarm the interrupt trigger for the shared ports because of this possibly unwanted effect.

== Safety precautions ==

The TMS9901 PSI is an interrupt encoder and an I/O circuit. You may have heard that improper use of I/O circuits may damage the circuit so that it must be replaced. Is this possible with the 9901 as well? Is there a way to kill the 9901?

Short answer: Yes.

Longer answer: Yes, but it depends on the way how the ports are used.

If the port is used as an input, nothing bad will happen, since the ports have high input impedance. You can put 0V or 5V directly to the input; of course, you should not use excessive voltage.

=== How to damage the 9901 ports ===

The problem is when the port is configured as an output port. In that case it may output 0V (0) or 5V (1). When you connect the output to the opposite voltage, you will cause a short circuit which quickly exceeds the chip's maximum power dissipation of 750 mW. This means you will fry the chip.

Consider the following setup (but don't try it!).

[[File:Badport9901.png|300px]]

Obviously, port P4 is assumed to be an input. When the switch is open, port P4 will sense a 1 on its input. When the switch is closed, it will sense a 0.

Now what happens when you execute this code?

CLR R12
SBO 20

This will program port P4 to be an output, and to show a 1 (5V) at the output. SBZ will, in contrast, make this port output a 0. So how do you make it an input port? - This is done by resetting the chip. As long as you don't use a SBZ/SBO (or a LDCR) on the ports, the ports are inputs.

Nothing has happened up to now. But now imagine that you press the switch. This will put the 1 output to ground, causing the short circuit, and your 9901 is toast.

=== What about the TI console? ===

So can we damage the 9901 in the TI console by a suitable CRU operation? - Luckily not.

The reason is the way how TI used the ports on the mainboard. Most of the ports are configured as outputs. Nothing happens when you reset them to inputs.

* The pure interrupt inputs (/INT1 to /INT6) are safe, as they cannot output anything. They have no output driver that could be fried.
* P0 and P1 are not connected.
* P2, P3, and P4 are designed as outputs, so they cannot be turned from an input to an output.
* P5 is the selector of the Alpha Lock key, so output as well.
* P6 and P7 (/INT15) are the cassette motor control outputs.
* P8 (/INT14) is the audio gate output.
* P9 (/INT13) is the cassette output.
* P10 (/INT12) is pulled up to 5V via a 10 kOhm resistor. If you put a 0 on this port (5V), the maximum current is 500 µA, which results in a power dissipation of 2.5 mW (far below the maximum 750 mW).
* P11 (/INT11) is the cassette input. However, there is a resistor of 2.2 kOhm (R413) which effectively guards the port of high currents.
* P12, P13, P14, P15 (/INT10 ... /INT7) are the keyboard input lines. Again, we have pull-ups of 10 kOhm against +5V, but also 470 Ohm on the line, which means a maximum of 8.5 mA or 42.5 mW. This is still well below the maximum value.

So we see that resistors are the best way to protect the ports. And we may calm down; we cannot burn the 9901 in the TI console by a bug in our program.

Programmable Systems Interface TMS 9901

2022-04-23T13:30:24Z

Mizapf:

The Programmable System Interface (PSI) is a circuit that is used on the TI-99/4A main board, on some expansion cards, and on the Geneve.

The designation of the PSI is '''TMS9901''', and this is the name that most users should be more familiar with.

== Features ==

The TMS 9901 Programmable Systems Interface is a multi-purpose circuit that is used in the TI-99/4A and the Geneve computer, and also on some peripheral cards like the Corcomp Floppy Disk Controller.

The 9901 has three main usage modes:

* Input/Output ports
* Interrupt prioritizing
* Timer

The I/O ports are mainly used for scanning the keyboard and joysticks, while the timer is used for cassette data encoding and decoding. The interrupt prioritizer is only used for the video interrupt which is routed from the VDP to the CPU through the 9901.

== Package ==

This is the pin assignment according to the 9901 specification.

[[File:Pack9901.png|300px|left]]

You can see pins of related functions marked by the same background color.

* Orange: Interrupt inputs
* Red: CRU bit selection (00000 - 11111, i.e. 0-31 decimal)
* Blue: CRU interface
* Violet: I/O ports
* Yellow: Outgoing interrupt and level

Note that some pins have a double function, or in other words, two functions share the same pin. I will discuss this in the following sections.

<div style="clear:both"></div>

== Input/Output port operation ==

The simplest way of working with the 9901 is input/output operation with the ports. The 9901 has 16 configurable ports that can be individually used as inputs or outputs: P0 to P15.

=== Px port as input ===

[[File:Port9901in.png|250px]]

The power-on preset for every port is input. If you want to probe the P2 status (bit 18), use

CLR R12
TB 18
JEQ P2ACT

TB copies the bit at the given CRU address into the Equal bit of the status register. JEQ will jump to the location when this input has a high level. The maximum input current is 100 µA. You should protect the input with a resistor; see below for a more detailed discussion.

If you want to read all 16 ports, use the STCR instruction:

LI R12,32
STCR R1,0

Note that the CRU base address in R12 advances in steps of 2, so bit 16 is on address 32. Also, for reading 16 bits, you must specify a count of 0.

The 9901 offers some more inputs than the 16 ports; we can use the interrupt inputs as well. See below for a discussion of the interrupt mode.

=== Px port as output ===

[[File:Port9901out.png|250px]]

Once you write a value to the CRU address of a 9901 port, this port switches to output mode. The value written to the port is the value that is shown on its pin. If we want to output a 1 on P6, we have to use

CLR R12
SBO 22

If we wanted to output a 0, SBZ would have to be used. In order to set several ports in one go, use LDCR.

We can also read the output port just by using TB as usual (or STCR for several ports at once).

CLR R12
SBO 22
TB 22
JEQ EXPECT

The TB operation should return the 1 which the previous SBO has set.

You '''cannot''' switch back to input mode. This is only possible by resetting the 9901, either using the /RST1 input line, or by setting the /RST2 bit (bit 15) to 0 in clock mode.

== Interrupt mode ==

In interrupt mode, bits 1 to 15 are used to set the interrupt mask (write), or to query the interrupt inputs (read). That is, the meaning of reading and writing the bits is indeed different.

This schema shows how the interrupt inputs are used.

[[File:Int9901.png|600px]]

This illustration is slightly simplified; there is a latch between each interrupt input and the mask AND gate. This is not relevant for our programming, though. For more details see the ''TMS 9901 Programmable Systems Interface Data Manual''.

=== Checking the interrupt inputs ===

In general, every interrupt input can be read via CRU access:

CLR R12
TB 15
JEQ NOINT15

TB copies the bit at the specified CRU address to the Equal status bit. This means that JEQ jumps to the location when the bit is 1. Since all interrupt inputs are negative logic, reading a 1 means that there is no interrupt at this input (so I called it NOINT15).

If we want to read several interrupt inputs by a single instruction, we have to use STCR.

LI R12,16
STCR R1,8

This reads the states of the /INT8, /INT9, ..., /INT15 inputs and puts them in the most significant byte of R1. (See the specification of STCR and LDCR for transfers of up to 8 bits.)

=== Interrupt levels ===

Each interrupt input (/INT1 to /INT15) may be used to trigger an interrupt at another circuit, typically the CPU. For this purpose, the PSI offers an /INTREQ outgoing line. In the TI console, it is routed to the /INTREQ input of the TMS9900 CPU.

In addition there is a priority encoder, which is not shown here. This encoder outputs a 4-bit number which reflects the smallest number of the interrupt inputs where an interrupt has been sensed.

That is, if /INT4 and /INT7 are currently set to 0 (active), the priority encoder outputs (0100), which means 4.

The TMS9900 CPU can differentiate between these interrupt levels, and by using its LIMI command, we can set a threshold where interrupts are ignored. So when we use a LIMI 3, the interrupts of level 4, 5, 6 and higher will be ignored.

The bad news is that Texas Instruments did not use these priority lines in the TI console. In fact, these outputs (IC0 .. IC3) are not connected, and the respective interrupt level inputs at the CPU are hardwired to (0001), which means that every interrupt that occurs in the TI console is automatically set to level 1. So in order to block all interrupts from the 9901

LIMI 0

must be executed. To allow all,

LIMI 1

is sufficient. For some unclear reason, TI used LIMI 2 in all occasions.

=== Arming and disarming interrupts ===

As said above, every interrupt input can be read at any time in interrupt mode. In that sense, we don't really treat these inputs as interrupts inputs, but simply as input ports.

If we want a port to trigger an interrupt, we must arm this interrupt input. This is done by setting the respective bit to 1.

CLR R12
SBO 2

This enables interrupt input /INT2 to cause an /INTREQ when its input changes to 0. In the TI console, /INT2 is connected to the interrupt output of the VDP (video processor). If you want to block interrupts on that input, use SBZ.

It is a common misunderstanding that interrupts can be cleared by using a SBZ on an input. This can, for example, be seen in the popular TI Intern book. Instead, SBZ n simply blocks interrupt input /INTn. In the case of the video processor, it is up to the VDP to clear its interrupt, and this is done by reading its status register.

== Counter mode ==

Besides the I/O capabilities, the PSI offers a "real-time" clock. This should not be understood as a precise timer with seconds, hundreds of seconds or other but as a countdown timer that is decremented every 64 CPU clock cycles.

This schematic is taken from the Osborne book, redrawn by me in LibreOffice (and with added Load Buffer).

[[File:Clock9901.png|550px]]

=== Using the timer ===

There are basically two ways of using the countdown timer:

* Interval timer: Set the counter to a value; wait until the counter reaches zero. The PSI can be set up to raise an interrupt at that instant.
* Event timer: Set the counter to a value; do something and then read the counter value.

The counter has 14 bits; that is, its maximum value is 0x3FFF (16383). The counter is decremented every 64 clock cycles, and for the TI-99/4A and the Geneve with a clock cycle time of 333ns, this means that the counter resolution is 21.333 µs. The whole 16384 steps take 0.3495 seconds (349.5 ms).

When the counter reaches 0, it is reloaded from the load buffer, and counting continues.

It is essential to understand that the counter '''always''' counts down, independent of the mode. The specification says that the clock is enabled when a non-zero value is loaded into the load buffer, but tests on a real Geneve show that the clock decrements even when the load buffer is filled with 0.

=== Setting the timer ===

In order to set the load buffer and so to define the maximum counter value, we must switch to clock mode. This is achieved by setting bit 0 of the PSI to 1. In the TI/Geneve systems, the PSI is mapped to CRU base address 0, so we can do this

CLR R12
SBO 0

to enter '''clock mode'''. Using SBZ 0 returns to '''interrupt mode'''.

The effect of switching to clock mode is that the load buffer becomes accessible by the CRU addresses 1 to 14. Supposed that we want to load the buffer with the value 0x00FF, we may use these lines:

CLR R12
SBO 0
LI R1,>00FF
INCT R12
LDCR R1,14

As we see, we must change the CRU base. The LDCR operation always starts at the address defined in R12; if this is not 0, we have to set it here. Note, however, that the CRU address is always half of the R12 value, since the rightmost bit, A15, is not part of the address. If we want to start at bit 1, we must increase R12 by 2. This is, by the way, done wrong in several places in the literature where R12 is only set to 1.

We can combine the SBO and the LDCR to one operation if we define the rightmost bit of R1 as the bit 0 and the following bits as the timer value.

CLR R12
LI R1,>01FF (0000 0001 1111 1111)
LDCR R1,15

Do '''not''' write all 16 bits. The last bit will change bit 15 of the PSI, which is the /RST2 bit. When we are in clock mode, writing a 0 to the /RST2 bit resets all I/O ports. This means that all pins are set to inputs, and devices that rely on them as outputs may be turned off unintentionally.

=== Reading the timer ===

We are interested for the current value of the timer at some occasions. However, since the counter is constantly changing (every 64 clock cycles), reading from the active counter may deliver a wrong result. Think, for instance, about a value 0x2000, which is decremented after we read the first bits, we may end up with 0x2FFF (2 from 0x2000, FFF from 0x1FFF).

For this reason, the timer value is copied to a '''read buffer'''. This happens at every 64th clock cycle, when the counter is also decremented, but only when we are '''not''' in clock mode.

To read the buffer, we must set the PSI to clock mode first, which freezes the counter value in the read buffer. Then we can read the counter using STCR.

CLR R12
SBO 0
STCR R1,15
SRL R1,1
SBZ 0

As we see, register 1 will contain bit 0 in its rightmost bit, so we shift R1 by one position to move it out.

Do not forget to return to interrupt mode, or the buffer will not receive further updates.

As mentioned, bit 15 is the /RST2 bit when we write to it. For reading, bit 15 reflects the /INTREQ output.

=== The weird S0 input ===

There is one peculiarity with the PSI. When the input line S0 is set to 1, the clock mode is '''left temporarily''' - until S0 is 0 again, and bit 0 is 1. If bit 0 is 0, this has no effect, as the clock mode is never entered.

What is the reason for this?

TI obviously considered use cases where the PSI remains in clock mode for longer times, while the I/O ports must still be operated. The I/O ports are available on bits 16-31, which means that the S0 input is 1 for these addresses. So when we do a SBO 16, this is not related to the timer value, and thus should control the first I/O port. To allow this, the chip returns to interrupt/port mode for this operation, and when S0 is reset, returns to clock mode.

In the TI console, the S0-S4 inputs are directly connected with the address bus lines A10-A14. This has a strange side effect: Whenever address bus line A10 changes to 1, the clock mode is left temporarily, and this also happens for ordinary memory accesses.

Suppose that we are in clock mode (SBO 0). In this mode, the read buffer should not be updated, so when we read it, we should get the same value every time, although the real counter value is different. But this is difficult to achieve: If our program uses a memory address where A10 is 1 for some instruction, loading this instruction into the CPU will set A10 to 1, and thus leave clock mode, which updates the counter.

Therefore, you may have the impression that the read register continues to be updated even though you set bit 0 to 1. But this is only happening because your program extends over a location where A10 is 1. So if you want to prove that in clock mode the read register remains fixed, your program must avoid all memory locations where A10 is 1.

== Shared pins ==

Some pins have a double meaning; for example, pin 34 is labeled /INT7 / P15. How do we select the functions?

The shared pins are those for the interrupt inputs /INT7 to /INT15; they may also be used for P7 to P15 (in the opposite order).

If the Pn port is set to '''input''', the situation looks like this:

[[File:Shared9901in.png|250px]]

This means that both port and interrupt input have the same values; each one is a mirror of the other's state. We notice it by reading the bits of the associated CRU addresses, getting the same results. There is a difference, though: The interrupt input can be armed to trigger an outgoing interrupt, while the I/O port cannot.

In the other case, the Pn port is an '''output'''.

[[File:Shared9901out.png|250px]]

Is that possible? - Sure. The interrupt input will reflect the output of the port. When we set the port to 1, the interrupt input will get that 1 (same for 0). If we arm the interrupt input, setting the output port to 0 will trigger an interrupt via this input. The 9901 specification document recommends to disarm the interrupt trigger for the shared ports because of this possibly unwanted effect.

== Safety precautions ==

The TMS9901 PSI is an interrupt encoder and an I/O circuit. You may have heard that improper use of I/O circuits may damage the circuit so that it must be replaced. Is this possible with the 9901 as well? Is there a way to kill the 9901?

Short answer: Yes.

Longer answer: Yes, but it depends on the way how the ports are used.

If the port is used as an input, nothing bad will happen, since the ports have high input impedance. You can put 0V or 5V directly to the input; of course, you should not use excessive voltage.

=== How to damage the 9901 ports ===

The problem is when the port is configured as an output port. In that case it may output 0V (0) or 5V (1). When you connect the output to the opposite voltage, you will cause a short circuit which quickly exceeds the chip's maximum power dissipation of 750 mW. This means you will fry the chip.

Consider the following setup (but don't try it!).

[[File:Badport9901.png|300px]]

Obviously, port P4 is assumed to be an input. When the switch is open, port P4 will sense a 1 on its input. When the switch is closed, it will sense a 0.

Now what happens when you execute this code?

CLR R12
SBO 20

This will program port P4 to be an output, and to show a 1 (5V) at the output. SBZ will, in contrast, make this port output a 0. So how do you make it an input port? - This is done by resetting the chip. As long as you don't use a SBZ/SBO (or a LDCR) on the ports, the ports are inputs.

Nothing has happened up to now. But now imagine that you press the switch. This will put the 1 output to ground, causing the short circuit, and your 9901 is toast.

=== What about the TI console? ===

So can we damage the 9901 in the TI console by a suitable CRU operation? - Luckily not.

The reason is the way how TI used the ports on the mainboard. Most of the ports are configured as outputs. Nothing happens when you reset them to inputs.

* The pure interrupt inputs (/INT1 to /INT6) are safe, as they cannot output anything. They have no output driver that could be fried.
* P0 and P1 are not connected.
* P2, P3, and P4 are designed as outputs, so they cannot be turned from an input to an output.
* P5 is the selector of the Alpha Lock key, so output as well.
* P6 and P7 (/INT15) are the cassette motor control outputs.
* P8 (/INT14) is the audio gate output.
* P9 (/INT13) is the cassette output.
* P10 (/INT12) is pulled up to 5V via a 10 kOhm resistor. If you put a 0 on this port (5V), the maximum current is 500 µA, which results in a power dissipation of 2.5 mW (far below the maximum 750 mW).
* P11 (/INT11) is the cassette input. However, there is a resistor of 2.2 kOhm (R413) which effectively guards the port of high currents.
* P12, P13, P14, P15 (/INT10 ... /INT7) are the keyboard input lines. Again, we have pull-ups of 10 kOhm against +5V, but also 470 Ohm on the line, which means a maximum of 8.5 mA or 42.5 mW. This is still well below the maximum value.

So we see that resistors are the best way to protect the ports. And we may calm down; we cannot burn the 9901 in the TI console by a bug in our program.

Programmable Systems Interface TMS 9901

2022-04-23T12:37:52Z

Mizapf: /* Input/Output port operation */

The Programmable System Interface (PSI) is a circuit that is used on the TI-99/4A main board, on some expansion cards, and on the Geneve.

The designation of the PSI is '''TMS9901''', and this is the name that most users will be more familiar with.

== Features ==

The TMS 9901 Programmable Systems Interface is a multi-purpose circuit that is used in the TI-99/4A and the Geneve computer, and also on some peripheral cards like the Corcomp Floppy Disk Controller.

The 9901 has three main usage modes:

* Input/Output ports
* Interrupt prioritizing
* Timer

The I/O ports are mainly used for scanning the keyboard and joysticks, while the timer is used for cassette data encoding and decoding. The interrupt prioritizer is only used for the video interrupt which is routed from the VDP to the CPU through the 9901.

== Package ==

This is the pin assignment according to the 9901 specification.

[[File:Pack9901.png|300px|left]]

You can see pins of related functions marked by the same background color.

* Orange: Interrupt inputs
* Red: CRU bit selection (00000 - 11111, i.e. 0-31 decimal)
* Blue: CRU interface
* Violet: I/O ports
* Yellow: Outgoing interrupt and level

Note that some pins have a double function, or in other words, two functions share the same pin. I will discuss this in the following sections.

<div style="clear:both"></div>

== Input/Output port operation ==

The simplest way of working with the 9901 is input/output operation with the ports. The 9901 has 16 configurable ports that can be individually used as inputs or outputs: P0 to P15.

=== Px port as input ===

[[File:Port9901in.png|250px]]

The power-on preset for every port is input. If you want to probe the P2 status (bit 18), use

CLR R12
TB 18
JEQ P2ACT

TB copies the bit at the given CRU address into the Equal bit of the status register. JEQ will jump to the location when this input has a high level. The maximum input current is 100 µA. You should protect the input with a resistor; see below for a more detailed discussion.

If you want to read all 16 ports, use the STCR instruction:

LI R12,32
STCR R1,0

Note that the CRU base address in R12 advances in steps of 2, so bit 16 is on address 32. Also, for reading 16 bits, you must specify a count of 0.

The 9901 offers some more inputs than the 16 ports; we can use the interrupt inputs as well. See below for a discussion of the interrupt mode.

=== Px port as output ===

[[File:Port9901out.png|250px]]

Once you write a value to the CRU address of a 9901 port, this port switches to output mode. The value written to the port is the value that is shown on its pin. If we want to output a 1 on P6, we have to use

CLR R12
SBO 22

If we wanted to output a 0, SBZ would have to be used. In order to set several ports in one go, use LDCR.

We can also read the output port just by using TB as usual (or STCR for several ports at once).

CLR R12
SBO 22
TB 22
JEQ EXPECT

The TB operation should return the 1 which the previous SBO has set.

You '''cannot''' switch back to input mode. This is only possible by resetting the 9901, either using the /RST1 input line, or by setting the /RST2 bit (bit 15) to 0 in clock mode.

== Interrupt mode ==

In interrupt mode, bits 1 to 15 are used to set the interrupt mask (write), or to query the interrupt inputs (read). That is, the meaning of reading and writing the bits is indeed different.

This schema shows how the interrupt inputs are used.

[[File:Int9901.png|600px]]

This illustration is slightly simplified; there is a latch between each interrupt input and the mask AND gate. This is not relevant for our programming, though. For more details see the ''TMS 9901 Programmable Systems Interface Data Manual''.

=== Checking the interrupt inputs ===

In general, every interrupt input can be read via CRU access:

CLR R12
TB 15
JEQ NOINT15

TB copies the bit at the specified CRU address to the Equal status bit. This means that JEQ jumps to the location when the bit is 1. Since all interrupt inputs are negative logic, reading a 1 means that there is no interrupt at this input (so I called it NOINT15).

If we want to read several interrupt inputs by a single instruction, we have to use STCR.

LI R12,16
STCR R1,8

This reads the states of the /INT8, /INT9, ..., /INT15 inputs and puts them in the most significant byte of R1. (See the specification of STCR and LDCR for transfers of up to 8 bits.)

=== Interrupt levels ===

Each interrupt input (/INT1 to /INT15) may be used to trigger an interrupt at another circuit, typically the CPU. For this purpose, the PSI offers an /INTREQ outgoing line. In the TI console, it is routed to the /INTREQ input of the TMS9900 CPU.

In addition there is a priority encoder, which is not shown here. This encoder outputs a 4-bit number which reflects the smallest number of the interrupt inputs where an interrupt has been sensed.

That is, if /INT4 and /INT7 are currently set to 0 (active), the priority encoder outputs (0100), which means 4.

The TMS9900 CPU can differentiate between these interrupt levels, and by using its LIMI command, we can set a threshold where interrupts are ignored. So when we use a LIMI 3, the interrupts of level 4, 5, 6 and higher will be ignored.

The bad news is that Texas Instruments did not use these priority lines in the TI console. In fact, these outputs (IC0 .. IC3) are not connected, and the respective interrupt level inputs at the CPU are hardwired to (0001), which means that every interrupt that occurs in the TI console is automatically set to level 1. So in order to block all interrupts from the 9901

LIMI 0

must be executed. To allow all,

LIMI 1

is sufficient. For some unclear reason, TI used LIMI 2 in all occasions.

=== Arming and disarming interrupts ===

As said above, every interrupt input can be read at any time in interrupt mode. In that sense, we don't really treat these inputs as interrupts inputs, but simply as input ports.

If we want a port to trigger an interrupt, we must arm this interrupt input. This is done by setting the respective bit to 1.

CLR R12
SBO 2

This enables interrupt input /INT2 to cause an /INTREQ when its input changes to 0. In the TI console, /INT2 is connected to the interrupt output of the VDP (video processor). If you want to block interrupts on that input, use SBZ.

It is a common misunderstanding that interrupts can be cleared by using a SBZ on an input. This can, for example, be seen in the popular TI Intern book. Instead, SBZ n simply blocks interrupt input /INTn. In the case of the video processor, it is up to the VDP to clear its interrupt, and this is done by reading its status register.

== Counter mode ==

Besides the I/O capabilities, the PSI offers a "real-time" clock. This should not be understood as a precise timer with seconds, hundreds of seconds or other but as a countdown timer that is decremented every 64 CPU clock cycles.

This schematic is taken from the Osborne book, redrawn by me in LibreOffice (and with added Load Buffer).

[[File:Clock9901.png|550px]]

=== Using the timer ===

There are basically two ways of using the countdown timer:

* Interval timer: Set the counter to a value; wait until the counter reaches zero. The PSI can be set up to raise an interrupt at that instant.
* Event timer: Set the counter to a value; do something and then read the counter value.

The counter has 14 bits; that is, its maximum value is 0x3FFF (16383). The counter is decremented every 64 clock cycles, and for the TI-99/4A and the Geneve with a clock cycle time of 333ns, this means that the counter resolution is 21.333 µs. The whole 16384 steps take 0.3495 seconds (349.5 ms).

When the counter reaches 0, it is reloaded from the load buffer, and counting continues.

It is essential to understand that the counter '''always''' counts down, independent of the mode. The specification says that the clock is enabled when a non-zero value is loaded into the load buffer, but tests on a real Geneve show that the clock decrements even when the load buffer is filled with 0.

=== Setting the timer ===

In order to set the load buffer and so to define the maximum counter value, we must switch to clock mode. This is achieved by setting bit 0 of the PSI to 1. In the TI/Geneve systems, the PSI is mapped to CRU base address 0, so we can do this

CLR R12
SBO 0

to enter '''clock mode'''. Using SBZ 0 returns to '''interrupt mode'''.

The effect of switching to clock mode is that the load buffer becomes accessible by the CRU addresses 1 to 14. Supposed that we want to load the buffer with the value 0x00FF, we may use these lines:

CLR R12
SBO 0
LI R1,>00FF
INCT R12
LDCR R1,14

As we see, we must change the CRU base. The LDCR operation always starts at the address defined in R12; if this is not 0, we have to set it here. Note, however, that the CRU address is always half of the R12 value, since the rightmost bit, A15, is not part of the address. If we want to start at bit 1, we must increase R12 by 2. This is, by the way, done wrong in several places in the literature where R12 is only set to 1.

We can combine the SBO and the LDCR to one operation if we define the rightmost bit of R1 as the bit 0 and the following bits as the timer value.

CLR R12
LI R1,>01FF (0000 0001 1111 1111)
LDCR R1,15

Do '''not''' write all 16 bits. The last bit will change bit 15 of the PSI, which is the /RST2 bit. When we are in clock mode, writing a 0 to the /RST2 bit resets all I/O ports. This means that all pins are set to inputs, and devices that rely on them as outputs may be turned off unintentionally.

=== Reading the timer ===

We are interested for the current value of the timer at some occasions. However, since the counter is constantly changing (every 64 clock cycles), reading from the active counter may deliver a wrong result. Think, for instance, about a value 0x2000, which is decremented after we read the first bits, we may end up with 0x2FFF (2 from 0x2000, FFF from 0x1FFF).

For this reason, the timer value is copied to a '''read buffer'''. This happens at every 64th clock cycle, when the counter is also decremented, but only when we are '''not''' in clock mode.

To read the buffer, we must set the PSI to clock mode first, which freezes the counter value in the read buffer. Then we can read the counter using STCR.

CLR R12
SBO 0
STCR R1,15
SRL R1,1
SBZ 0

As we see, register 1 will contain bit 0 in its rightmost bit, so we shift R1 by one position to move it out.

Do not forget to return to interrupt mode, or the buffer will not receive further updates.

As mentioned, bit 15 is the /RST2 bit when we write to it. For reading, bit 15 reflects the /INTREQ output.

=== The weird S0 input ===

There is one peculiarity with the PSI. When the input line S0 is set to 1, the clock mode is '''left temporarily''' - until S0 is 0 again, and bit 0 is 1. If bit 0 is 0, this has no effect, as the clock mode is never entered.

What is the reason for this?

TI obviously considered use cases where the PSI remains in clock mode for longer times, while the I/O ports must still be operated. The I/O ports are available on bits 16-31, which means that the S0 input is 1 for these addresses. So when we do a SBO 16, this is not related to the timer value, and thus should control the first I/O port. To allow this, the chip returns to interrupt/port mode for this operation, and when S0 is reset, returns to clock mode.

In the TI console, the S0-S4 inputs are directly connected with the address bus lines A10-A14. This has a strange side effect: Whenever address bus line A10 changes to 1, the clock mode is left temporarily, and this also happens for ordinary memory accesses.

Suppose that we are in clock mode (SBO 0). In this mode, the read buffer should not be updated, so when we read it, we should get the same value every time, although the real counter value is different. But this is difficult to achieve: If our program uses a memory address where A10 is 1 for some instruction, loading this instruction into the CPU will set A10 to 1, and thus leave clock mode, which updates the counter.

Therefore, you may have the impression that the read register continues to be updated even though you set bit 0 to 1. But this is only happening because your program extends over a location where A10 is 1. So if you want to prove that in clock mode the read register remains fixed, your program must avoid all memory locations where A10 is 1.

== Shared pins ==

Some pins have a double meaning; for example, pin 34 is labeled /INT7 / P15. How do we select the functions?

The shared pins are those for the interrupt inputs /INT7 to /INT15; they may also be used for P7 to P15 (in the opposite order).

If the Pn port is set to '''input''', the situation looks like this:

[[File:Shared9901in.png|250px]]

This means that both port and interrupt input have the same values; each one is a mirror of the other's state. We notice it by reading the bits of the associated CRU addresses, getting the same results. There is a difference, though: The interrupt input can be armed to trigger an outgoing interrupt, while the I/O port cannot.

In the other case, the Pn port is an '''output'''.

[[File:Shared9901out.png|250px]]

Is that possible? - Sure. The interrupt input will reflect the output of the port. When we set the port to 1, the interrupt input will get that 1 (same for 0). If we arm the interrupt input, setting the output port to 0 will trigger an interrupt via this input. The 9901 specification document recommends to disarm the interrupt trigger for the shared ports because of this possibly unwanted effect.

== Safety precautions ==

The TMS9901 PSI is an interrupt encoder and an I/O circuit. You may have heard that improper use of I/O circuits may damage the circuit so that it must be replaced. Is this possible with the 9901 as well? Is there a way to kill the 9901?

Short answer: Yes.

Longer answer: Yes, but it depends on the way how the ports are used.

If the port is used as an input, nothing bad will happen, since the ports have high input impedance. You can put 0V or 5V directly to the input; of course, you should not use excessive voltage.

=== How to damage the 9901 ports ===

The problem is when the port is configured as an output port. In that case it may output 0V (0) or 5V (1). When you connect the output to the opposite voltage, you will cause a short circuit which quickly exceeds the chip's maximum power dissipation of 750 mW. This means you will fry the chip.

Consider the following setup (but don't try it!).

[[File:Badport9901.png|300px]]

Obviously, port P4 is assumed to be an input. When the switch is open, port P4 will sense a 1 on its input. When the switch is closed, it will sense a 0.

Now what happens when you execute this code?

CLR R12
SBO 20

This will program port P4 to be an output, and to show a 1 (5V) at the output. SBZ will, in contrast, make this port output a 0. So how do you make it an input port? - This is done by resetting the chip. As long as you don't use a SBZ/SBO (or a LDCR) on the ports, the ports are inputs.

Nothing has happened up to now. But now imagine that you press the switch. This will put the 1 output to ground, causing the short circuit, and your 9901 is toast.

=== What about the TI console? ===

So can we damage the 9901 in the TI console by a suitable CRU operation? - Luckily not.

The reason is the way how TI used the ports on the mainboard. Most of the ports are configured as outputs. Nothing happens when you reset them to inputs.

* The pure interrupt inputs (/INT1 to /INT6) are safe, as they cannot output anything. They have no output driver that could be fried.
* P0 and P1 are not connected.
* P2, P3, and P4 are designed as outputs, so they cannot be turned from an input to an output.
* P5 is the selector of the Alpha Lock key, so output as well.
* P6 and P7 (/INT15) are the cassette motor control outputs.
* P8 (/INT14) is the audio gate output.
* P9 (/INT13) is the cassette output.
* P10 (/INT12) is pulled up to 5V via a 10 kOhm resistor. If you put a 0 on this port (5V), the maximum current is 500 µA, which results in a power dissipation of 2.5 mW (far below the maximum 750 mW).
* P11 (/INT11) is the cassette input. However, there is a resistor of 2.2 kOhm (R413) which effectively guards the port of high currents.
* P12, P13, P14, P15 (/INT10 ... /INT7) are the keyboard input lines. Again, we have pull-ups of 10 kOhm against +5V, but also 470 Ohm on the line, which means a maximum of 8.5 mA or 42.5 mW. This is still well below the maximum value.

So we see that resistors are the best way to protect the ports. And we may calm down; we cannot burn the 9901 in the TI console by a bug in our program.

Programmable Systems Interface TMS 9901

2022-04-23T12:36:47Z

Mizapf: /* Input/Output port operation */

The Programmable System Interface (PSI) is a circuit that is used on the TI-99/4A main board, on some expansion cards, and on the Geneve.

The designation of the PSI is '''TMS9901''', and this is the name that most users will be more familiar with.

== Features ==

The TMS 9901 Programmable Systems Interface is a multi-purpose circuit that is used in the TI-99/4A and the Geneve computer, and also on some peripheral cards like the Corcomp Floppy Disk Controller.

The 9901 has three main usage modes:

* Input/Output ports
* Interrupt prioritizing
* Timer

The I/O ports are mainly used for scanning the keyboard and joysticks, while the timer is used for cassette data encoding and decoding. The interrupt prioritizer is only used for the video interrupt which is routed from the VDP to the CPU through the 9901.

== Package ==

This is the pin assignment according to the 9901 specification.

[[File:Pack9901.png|300px|left]]

You can see pins of related functions marked by the same background color.

* Orange: Interrupt inputs
* Red: CRU bit selection (00000 - 11111, i.e. 0-31 decimal)
* Blue: CRU interface
* Violet: I/O ports
* Yellow: Outgoing interrupt and level

Note that some pins have a double function, or in other words, two functions share the same pin. I will discuss this in the following sections.

<div style="clear:both"></div>

== Input/Output port operation ==

The simplest way of working with the 9901 is input/output operation with the ports. The 9901 has 16 configurable ports that can be individually used as inputs or outputs: P0 to P15.

=== Px port as input ===

[[File:Port9901in.png|250px]]

The power-on preset for every port is input. If you want to probe the P2 status (bit 18), use

CLR R12
TB 18
JEQ P2ACT

TB copies the bit at the given CRU address into the Equal bit of the status register. JEQ will jump to the location when this input has a high level. The maximum input current is 100 µA. You should protect the input with a resistor; see below for a more detailed discussion.

If you want to read all 16 ports, use the STCR instruction:

LI R12,32
STCR R1,0

Note that the CRU base address in R12 advances in steps of 2, so bit 16 is on address 32. Also, for reading 16 bits, you must specify a count of 0.

The 9901 offers some more inputs than the 16 ports; we can use the interrupt inputs as well. See below for a discussion of the interrupt mode.

=== Px port as output ===

[[File:Port9901out.png|250px]]

Once you write a value to the CRU address of a 9901 port, this port switches to output mode. The value written to the port is the value that is shown on its pin. If we want to output a 1 on P6, we have to use

CLR R12
SBO 22

If we wanted to output a 0, SBZ would have to be used. In order to set several ports in one go, use LDCR.

Note that you cannot switch back to input mode. This is only possible by resetting the 9901, either using the /RST1 input line, or by setting the /RST2 bit (bit 15) to 0 in clock mode.

We can also read the output port just by using TB as usual (or STCR for several ports at once).

CLR R12
SBO 22
TB 22
JEQ EXPECT

The TB operation should return the 1 which the previous SBO has set.

== Interrupt mode ==

In interrupt mode, bits 1 to 15 are used to set the interrupt mask (write), or to query the interrupt inputs (read). That is, the meaning of reading and writing the bits is indeed different.

This schema shows how the interrupt inputs are used.

[[File:Int9901.png|600px]]

This illustration is slightly simplified; there is a latch between each interrupt input and the mask AND gate. This is not relevant for our programming, though. For more details see the ''TMS 9901 Programmable Systems Interface Data Manual''.

=== Checking the interrupt inputs ===

In general, every interrupt input can be read via CRU access:

CLR R12
TB 15
JEQ NOINT15

TB copies the bit at the specified CRU address to the Equal status bit. This means that JEQ jumps to the location when the bit is 1. Since all interrupt inputs are negative logic, reading a 1 means that there is no interrupt at this input (so I called it NOINT15).

If we want to read several interrupt inputs by a single instruction, we have to use STCR.

LI R12,16
STCR R1,8

This reads the states of the /INT8, /INT9, ..., /INT15 inputs and puts them in the most significant byte of R1. (See the specification of STCR and LDCR for transfers of up to 8 bits.)

=== Interrupt levels ===

Each interrupt input (/INT1 to /INT15) may be used to trigger an interrupt at another circuit, typically the CPU. For this purpose, the PSI offers an /INTREQ outgoing line. In the TI console, it is routed to the /INTREQ input of the TMS9900 CPU.

In addition there is a priority encoder, which is not shown here. This encoder outputs a 4-bit number which reflects the smallest number of the interrupt inputs where an interrupt has been sensed.

That is, if /INT4 and /INT7 are currently set to 0 (active), the priority encoder outputs (0100), which means 4.

The TMS9900 CPU can differentiate between these interrupt levels, and by using its LIMI command, we can set a threshold where interrupts are ignored. So when we use a LIMI 3, the interrupts of level 4, 5, 6 and higher will be ignored.

The bad news is that Texas Instruments did not use these priority lines in the TI console. In fact, these outputs (IC0 .. IC3) are not connected, and the respective interrupt level inputs at the CPU are hardwired to (0001), which means that every interrupt that occurs in the TI console is automatically set to level 1. So in order to block all interrupts from the 9901

LIMI 0

must be executed. To allow all,

LIMI 1

is sufficient. For some unclear reason, TI used LIMI 2 in all occasions.

=== Arming and disarming interrupts ===

As said above, every interrupt input can be read at any time in interrupt mode. In that sense, we don't really treat these inputs as interrupts inputs, but simply as input ports.

If we want a port to trigger an interrupt, we must arm this interrupt input. This is done by setting the respective bit to 1.

CLR R12
SBO 2

This enables interrupt input /INT2 to cause an /INTREQ when its input changes to 0. In the TI console, /INT2 is connected to the interrupt output of the VDP (video processor). If you want to block interrupts on that input, use SBZ.

It is a common misunderstanding that interrupts can be cleared by using a SBZ on an input. This can, for example, be seen in the popular TI Intern book. Instead, SBZ n simply blocks interrupt input /INTn. In the case of the video processor, it is up to the VDP to clear its interrupt, and this is done by reading its status register.

== Counter mode ==

Besides the I/O capabilities, the PSI offers a "real-time" clock. This should not be understood as a precise timer with seconds, hundreds of seconds or other but as a countdown timer that is decremented every 64 CPU clock cycles.

This schematic is taken from the Osborne book, redrawn by me in LibreOffice (and with added Load Buffer).

[[File:Clock9901.png|550px]]

=== Using the timer ===

There are basically two ways of using the countdown timer:

* Interval timer: Set the counter to a value; wait until the counter reaches zero. The PSI can be set up to raise an interrupt at that instant.
* Event timer: Set the counter to a value; do something and then read the counter value.

The counter has 14 bits; that is, its maximum value is 0x3FFF (16383). The counter is decremented every 64 clock cycles, and for the TI-99/4A and the Geneve with a clock cycle time of 333ns, this means that the counter resolution is 21.333 µs. The whole 16384 steps take 0.3495 seconds (349.5 ms).

When the counter reaches 0, it is reloaded from the load buffer, and counting continues.

It is essential to understand that the counter '''always''' counts down, independent of the mode. The specification says that the clock is enabled when a non-zero value is loaded into the load buffer, but tests on a real Geneve show that the clock decrements even when the load buffer is filled with 0.

=== Setting the timer ===

In order to set the load buffer and so to define the maximum counter value, we must switch to clock mode. This is achieved by setting bit 0 of the PSI to 1. In the TI/Geneve systems, the PSI is mapped to CRU base address 0, so we can do this

CLR R12
SBO 0

to enter '''clock mode'''. Using SBZ 0 returns to '''interrupt mode'''.

The effect of switching to clock mode is that the load buffer becomes accessible by the CRU addresses 1 to 14. Supposed that we want to load the buffer with the value 0x00FF, we may use these lines:

CLR R12
SBO 0
LI R1,>00FF
INCT R12
LDCR R1,14

As we see, we must change the CRU base. The LDCR operation always starts at the address defined in R12; if this is not 0, we have to set it here. Note, however, that the CRU address is always half of the R12 value, since the rightmost bit, A15, is not part of the address. If we want to start at bit 1, we must increase R12 by 2. This is, by the way, done wrong in several places in the literature where R12 is only set to 1.

We can combine the SBO and the LDCR to one operation if we define the rightmost bit of R1 as the bit 0 and the following bits as the timer value.

CLR R12
LI R1,>01FF (0000 0001 1111 1111)
LDCR R1,15

Do '''not''' write all 16 bits. The last bit will change bit 15 of the PSI, which is the /RST2 bit. When we are in clock mode, writing a 0 to the /RST2 bit resets all I/O ports. This means that all pins are set to inputs, and devices that rely on them as outputs may be turned off unintentionally.

=== Reading the timer ===

We are interested for the current value of the timer at some occasions. However, since the counter is constantly changing (every 64 clock cycles), reading from the active counter may deliver a wrong result. Think, for instance, about a value 0x2000, which is decremented after we read the first bits, we may end up with 0x2FFF (2 from 0x2000, FFF from 0x1FFF).

For this reason, the timer value is copied to a '''read buffer'''. This happens at every 64th clock cycle, when the counter is also decremented, but only when we are '''not''' in clock mode.

To read the buffer, we must set the PSI to clock mode first, which freezes the counter value in the read buffer. Then we can read the counter using STCR.

CLR R12
SBO 0
STCR R1,15
SRL R1,1
SBZ 0

As we see, register 1 will contain bit 0 in its rightmost bit, so we shift R1 by one position to move it out.

Do not forget to return to interrupt mode, or the buffer will not receive further updates.

As mentioned, bit 15 is the /RST2 bit when we write to it. For reading, bit 15 reflects the /INTREQ output.

=== The weird S0 input ===

There is one peculiarity with the PSI. When the input line S0 is set to 1, the clock mode is '''left temporarily''' - until S0 is 0 again, and bit 0 is 1. If bit 0 is 0, this has no effect, as the clock mode is never entered.

What is the reason for this?

TI obviously considered use cases where the PSI remains in clock mode for longer times, while the I/O ports must still be operated. The I/O ports are available on bits 16-31, which means that the S0 input is 1 for these addresses. So when we do a SBO 16, this is not related to the timer value, and thus should control the first I/O port. To allow this, the chip returns to interrupt/port mode for this operation, and when S0 is reset, returns to clock mode.

In the TI console, the S0-S4 inputs are directly connected with the address bus lines A10-A14. This has a strange side effect: Whenever address bus line A10 changes to 1, the clock mode is left temporarily, and this also happens for ordinary memory accesses.

Suppose that we are in clock mode (SBO 0). In this mode, the read buffer should not be updated, so when we read it, we should get the same value every time, although the real counter value is different. But this is difficult to achieve: If our program uses a memory address where A10 is 1 for some instruction, loading this instruction into the CPU will set A10 to 1, and thus leave clock mode, which updates the counter.

Therefore, you may have the impression that the read register continues to be updated even though you set bit 0 to 1. But this is only happening because your program extends over a location where A10 is 1. So if you want to prove that in clock mode the read register remains fixed, your program must avoid all memory locations where A10 is 1.

== Shared pins ==

Some pins have a double meaning; for example, pin 34 is labeled /INT7 / P15. How do we select the functions?

The shared pins are those for the interrupt inputs /INT7 to /INT15; they may also be used for P7 to P15 (in the opposite order).

If the Pn port is set to '''input''', the situation looks like this:

[[File:Shared9901in.png|250px]]

This means that both port and interrupt input have the same values; each one is a mirror of the other's state. We notice it by reading the bits of the associated CRU addresses, getting the same results. There is a difference, though: The interrupt input can be armed to trigger an outgoing interrupt, while the I/O port cannot.

In the other case, the Pn port is an '''output'''.

[[File:Shared9901out.png|250px]]

Is that possible? - Sure. The interrupt input will reflect the output of the port. When we set the port to 1, the interrupt input will get that 1 (same for 0). If we arm the interrupt input, setting the output port to 0 will trigger an interrupt via this input. The 9901 specification document recommends to disarm the interrupt trigger for the shared ports because of this possibly unwanted effect.

== Safety precautions ==

The TMS9901 PSI is an interrupt encoder and an I/O circuit. You may have heard that improper use of I/O circuits may damage the circuit so that it must be replaced. Is this possible with the 9901 as well? Is there a way to kill the 9901?

Short answer: Yes.

Longer answer: Yes, but it depends on the way how the ports are used.

If the port is used as an input, nothing bad will happen, since the ports have high input impedance. You can put 0V or 5V directly to the input; of course, you should not use excessive voltage.

=== How to damage the 9901 ports ===

The problem is when the port is configured as an output port. In that case it may output 0V (0) or 5V (1). When you connect the output to the opposite voltage, you will cause a short circuit which quickly exceeds the chip's maximum power dissipation of 750 mW. This means you will fry the chip.

Consider the following setup (but don't try it!).

[[File:Badport9901.png|300px]]

Obviously, port P4 is assumed to be an input. When the switch is open, port P4 will sense a 1 on its input. When the switch is closed, it will sense a 0.

Now what happens when you execute this code?

CLR R12
SBO 20

This will program port P4 to be an output, and to show a 1 (5V) at the output. SBZ will, in contrast, make this port output a 0. So how do you make it an input port? - This is done by resetting the chip. As long as you don't use a SBZ/SBO (or a LDCR) on the ports, the ports are inputs.

Nothing has happened up to now. But now imagine that you press the switch. This will put the 1 output to ground, causing the short circuit, and your 9901 is toast.

=== What about the TI console? ===

So can we damage the 9901 in the TI console by a suitable CRU operation? - Luckily not.

The reason is the way how TI used the ports on the mainboard. Most of the ports are configured as outputs. Nothing happens when you reset them to inputs.

* The pure interrupt inputs (/INT1 to /INT6) are safe, as they cannot output anything. They have no output driver that could be fried.
* P0 and P1 are not connected.
* P2, P3, and P4 are designed as outputs, so they cannot be turned from an input to an output.
* P5 is the selector of the Alpha Lock key, so output as well.
* P6 and P7 (/INT15) are the cassette motor control outputs.
* P8 (/INT14) is the audio gate output.
* P9 (/INT13) is the cassette output.
* P10 (/INT12) is pulled up to 5V via a 10 kOhm resistor. If you put a 0 on this port (5V), the maximum current is 500 µA, which results in a power dissipation of 2.5 mW (far below the maximum 750 mW).
* P11 (/INT11) is the cassette input. However, there is a resistor of 2.2 kOhm (R413) which effectively guards the port of high currents.
* P12, P13, P14, P15 (/INT10 ... /INT7) are the keyboard input lines. Again, we have pull-ups of 10 kOhm against +5V, but also 470 Ohm on the line, which means a maximum of 8.5 mA or 42.5 mW. This is still well below the maximum value.

So we see that resistors are the best way to protect the ports. And we may calm down; we cannot burn the 9901 in the TI console by a bug in our program.

Programmable Systems Interface TMS 9901

2022-04-22T23:28:22Z

Mizapf: /* Using the timer */

The Programmable System Interface (PSI) is a circuit that is used on the TI-99/4A main board, on some expansion cards, and on the Geneve.

The designation of the PSI is '''TMS9901''', and this is the name that most users will be more familiar with.

== Features ==

The TMS 9901 Programmable Systems Interface is a multi-purpose circuit that is used in the TI-99/4A and the Geneve computer, and also on some peripheral cards like the Corcomp Floppy Disk Controller.

The 9901 has three main usage modes:

* Input/Output ports
* Interrupt prioritizing
* Timer

The I/O ports are mainly used for scanning the keyboard and joysticks, while the timer is used for cassette data encoding and decoding. The interrupt prioritizer is only used for the video interrupt which is routed from the VDP to the CPU through the 9901.

== Package ==

This is the pin assignment according to the 9901 specification.

[[File:Pack9901.png|300px|left]]

You can see pins of related functions marked by the same background color.

* Orange: Interrupt inputs
* Red: CRU bit selection (00000 - 11111, i.e. 0-31 decimal)
* Blue: CRU interface
* Violet: I/O ports
* Yellow: Outgoing interrupt and level

Note that some pins have a double function, or in other words, two functions share the same pin. I will discuss this in the following sections.

<div style="clear:both"></div>

== Input/Output port operation ==

The simplest way of working with the 9901 is input/output operation with the ports. The 9901 has 16 configurable ports that can be individually used as inputs or outputs: P0 to P15.

=== Px port as input ===

[[File:Port9901in.png|250px]]

The power-on preset for every port is input. If you want to probe the P2 status (bit 18), use

CLR R12
TB 18
JEQ P2ACT

TB copies the bit at the given CRU address into the Equal bit of the status register. JEQ will jump to the location when this input has a high level. The maximum input current is 100 µA. You should protect the input with a resistor; see below for a more detailed discussion.

If you want to read all 16 ports, use the STCR instruction:

LI R12,32
STCR R1,0

Note that the CRU base address in R12 advances in steps of 2, so bit 16 is on address 32. Also, for reading 16 bits, you must specify a count of 0.

The 9901 offers some more inputs than the 16 ports; we can use the interrupt inputs as well. See below for a discussion of the interrupt mode.

=== Px port as output ===

[[File:Port9901out.png|250px]]

Once you write a value to the CRU address of a 9901 port, this port switches to output mode. The value written to the port is the value that is shown on its pin. If we want to output a 1 on P6, we have to use

CLR R12
SBO 22

If we wanted to output a 0, SBZ would have to be used. In order to set several ports in one go, use LDCR.

Note that you cannot switch back to input mode. This is only possible by resetting the 9901, either using the /RST1 input line, or by setting the /RST2 bit (bit 15) to 0 in clock mode.

== Interrupt mode ==

In interrupt mode, bits 1 to 15 are used to set the interrupt mask (write), or to query the interrupt inputs (read). That is, the meaning of reading and writing the bits is indeed different.

This schema shows how the interrupt inputs are used.

[[File:Int9901.png|600px]]

This illustration is slightly simplified; there is a latch between each interrupt input and the mask AND gate. This is not relevant for our programming, though. For more details see the ''TMS 9901 Programmable Systems Interface Data Manual''.

=== Checking the interrupt inputs ===

In general, every interrupt input can be read via CRU access:

CLR R12
TB 15
JEQ NOINT15

TB copies the bit at the specified CRU address to the Equal status bit. This means that JEQ jumps to the location when the bit is 1. Since all interrupt inputs are negative logic, reading a 1 means that there is no interrupt at this input (so I called it NOINT15).

If we want to read several interrupt inputs by a single instruction, we have to use STCR.

LI R12,16
STCR R1,8

This reads the states of the /INT8, /INT9, ..., /INT15 inputs and puts them in the most significant byte of R1. (See the specification of STCR and LDCR for transfers of up to 8 bits.)

=== Interrupt levels ===

Each interrupt input (/INT1 to /INT15) may be used to trigger an interrupt at another circuit, typically the CPU. For this purpose, the PSI offers an /INTREQ outgoing line. In the TI console, it is routed to the /INTREQ input of the TMS9900 CPU.

In addition there is a priority encoder, which is not shown here. This encoder outputs a 4-bit number which reflects the smallest number of the interrupt inputs where an interrupt has been sensed.

That is, if /INT4 and /INT7 are currently set to 0 (active), the priority encoder outputs (0100), which means 4.

The TMS9900 CPU can differentiate between these interrupt levels, and by using its LIMI command, we can set a threshold where interrupts are ignored. So when we use a LIMI 3, the interrupts of level 4, 5, 6 and higher will be ignored.

The bad news is that Texas Instruments did not use these priority lines in the TI console. In fact, these outputs (IC0 .. IC3) are not connected, and the respective interrupt level inputs at the CPU are hardwired to (0001), which means that every interrupt that occurs in the TI console is automatically set to level 1. So in order to block all interrupts from the 9901

LIMI 0

must be executed. To allow all,

LIMI 1

is sufficient. For some unclear reason, TI used LIMI 2 in all occasions.

=== Arming and disarming interrupts ===

As said above, every interrupt input can be read at any time in interrupt mode. In that sense, we don't really treat these inputs as interrupts inputs, but simply as input ports.

If we want a port to trigger an interrupt, we must arm this interrupt input. This is done by setting the respective bit to 1.

CLR R12
SBO 2

This enables interrupt input /INT2 to cause an /INTREQ when its input changes to 0. In the TI console, /INT2 is connected to the interrupt output of the VDP (video processor). If you want to block interrupts on that input, use SBZ.

It is a common misunderstanding that interrupts can be cleared by using a SBZ on an input. This can, for example, be seen in the popular TI Intern book. Instead, SBZ n simply blocks interrupt input /INTn. In the case of the video processor, it is up to the VDP to clear its interrupt, and this is done by reading its status register.

== Counter mode ==

Besides the I/O capabilities, the PSI offers a "real-time" clock. This should not be understood as a precise timer with seconds, hundreds of seconds or other but as a countdown timer that is decremented every 64 CPU clock cycles.

This schematic is taken from the Osborne book, redrawn by me in LibreOffice (and with added Load Buffer).

[[File:Clock9901.png|550px]]

=== Using the timer ===

There are basically two ways of using the countdown timer:

* Interval timer: Set the counter to a value; wait until the counter reaches zero. The PSI can be set up to raise an interrupt at that instant.
* Event timer: Set the counter to a value; do something and then read the counter value.

The counter has 14 bits; that is, its maximum value is 0x3FFF (16383). The counter is decremented every 64 clock cycles, and for the TI-99/4A and the Geneve with a clock cycle time of 333ns, this means that the counter resolution is 21.333 µs. The whole 16384 steps take 0.3495 seconds (349.5 ms).

When the counter reaches 0, it is reloaded from the load buffer, and counting continues.

It is essential to understand that the counter '''always''' counts down, independent of the mode. The specification says that the clock is enabled when a non-zero value is loaded into the load buffer, but tests on a real Geneve show that the clock decrements even when the load buffer is filled with 0.

=== Setting the timer ===

In order to set the load buffer and so to define the maximum counter value, we must switch to clock mode. This is achieved by setting bit 0 of the PSI to 1. In the TI/Geneve systems, the PSI is mapped to CRU base address 0, so we can do this

CLR R12
SBO 0

to enter '''clock mode'''. Using SBZ 0 returns to '''interrupt mode'''.

The effect of switching to clock mode is that the load buffer becomes accessible by the CRU addresses 1 to 14. Supposed that we want to load the buffer with the value 0x00FF, we may use these lines:

CLR R12
SBO 0
LI R1,>00FF
INCT R12
LDCR R1,14

As we see, we must change the CRU base. The LDCR operation always starts at the address defined in R12; if this is not 0, we have to set it here. Note, however, that the CRU address is always half of the R12 value, since the rightmost bit, A15, is not part of the address. If we want to start at bit 1, we must increase R12 by 2. This is, by the way, done wrong in several places in the literature where R12 is only set to 1.

We can combine the SBO and the LDCR to one operation if we define the rightmost bit of R1 as the bit 0 and the following bits as the timer value.

CLR R12
LI R1,>01FF (0000 0001 1111 1111)
LDCR R1,15

Do '''not''' write all 16 bits. The last bit will change bit 15 of the PSI, which is the /RST2 bit. When we are in clock mode, writing a 0 to the /RST2 bit resets all I/O ports. This means that all pins are set to inputs, and devices that rely on them as outputs may be turned off unintentionally.

=== Reading the timer ===

We are interested for the current value of the timer at some occasions. However, since the counter is constantly changing (every 64 clock cycles), reading from the active counter may deliver a wrong result. Think, for instance, about a value 0x2000, which is decremented after we read the first bits, we may end up with 0x2FFF (2 from 0x2000, FFF from 0x1FFF).

For this reason, the timer value is copied to a '''read buffer'''. This happens at every 64th clock cycle, when the counter is also decremented, but only when we are '''not''' in clock mode.

To read the buffer, we must set the PSI to clock mode first, which freezes the counter value in the read buffer. Then we can read the counter using STCR.

CLR R12
SBO 0
STCR R1,15
SRL R1,1
SBZ 0

As we see, register 1 will contain bit 0 in its rightmost bit, so we shift R1 by one position to move it out.

Do not forget to return to interrupt mode, or the buffer will not receive further updates.

As mentioned, bit 15 is the /RST2 bit when we write to it. For reading, bit 15 reflects the /INTREQ output.

=== The weird S0 input ===

There is one peculiarity with the PSI. When the input line S0 is set to 1, the clock mode is '''left temporarily''' - until S0 is 0 again, and bit 0 is 1. If bit 0 is 0, this has no effect, as the clock mode is never entered.

What is the reason for this?

TI obviously considered use cases where the PSI remains in clock mode for longer times, while the I/O ports must still be operated. The I/O ports are available on bits 16-31, which means that the S0 input is 1 for these addresses. So when we do a SBO 16, this is not related to the timer value, and thus should control the first I/O port. To allow this, the chip returns to interrupt/port mode for this operation, and when S0 is reset, returns to clock mode.

In the TI console, the S0-S4 inputs are directly connected with the address bus lines A10-A14. This has a strange side effect: Whenever address bus line A10 changes to 1, the clock mode is left temporarily, and this also happens for ordinary memory accesses.

Suppose that we are in clock mode (SBO 0). In this mode, the read buffer should not be updated, so when we read it, we should get the same value every time, although the real counter value is different. But this is difficult to achieve: If our program uses a memory address where A10 is 1 for some instruction, loading this instruction into the CPU will set A10 to 1, and thus leave clock mode, which updates the counter.

Therefore, you may have the impression that the read register continues to be updated even though you set bit 0 to 1. But this is only happening because your program extends over a location where A10 is 1. So if you want to prove that in clock mode the read register remains fixed, your program must avoid all memory locations where A10 is 1.

== Shared pins ==

Some pins have a double meaning; for example, pin 34 is labeled /INT7 / P15. How do we select the functions?

The shared pins are those for the interrupt inputs /INT7 to /INT15; they may also be used for P7 to P15 (in the opposite order).

If the Pn port is set to '''input''', the situation looks like this:

[[File:Shared9901in.png|250px]]

This means that both port and interrupt input have the same values; each one is a mirror of the other's state. We notice it by reading the bits of the associated CRU addresses, getting the same results. There is a difference, though: The interrupt input can be armed to trigger an outgoing interrupt, while the I/O port cannot.

In the other case, the Pn port is an '''output'''.

[[File:Shared9901out.png|250px]]

Is that possible? - Sure. The interrupt input will reflect the output of the port. When we set the port to 1, the interrupt input will get that 1 (same for 0). If we arm the interrupt input, setting the output port to 0 will trigger an interrupt via this input. The 9901 specification document recommends to disarm the interrupt trigger for the shared ports because of this possibly unwanted effect.

== Safety precautions ==

The TMS9901 PSI is an interrupt encoder and an I/O circuit. You may have heard that improper use of I/O circuits may damage the circuit so that it must be replaced. Is this possible with the 9901 as well? Is there a way to kill the 9901?

Short answer: Yes.

Longer answer: Yes, but it depends on the way how the ports are used.

If the port is used as an input, nothing bad will happen, since the ports have high input impedance. You can put 0V or 5V directly to the input; of course, you should not use excessive voltage.

=== How to damage the 9901 ports ===

The problem is when the port is configured as an output port. In that case it may output 0V (0) or 5V (1). When you connect the output to the opposite voltage, you will cause a short circuit which quickly exceeds the chip's maximum power dissipation of 750 mW. This means you will fry the chip.

Consider the following setup (but don't try it!).

[[File:Badport9901.png|300px]]

Obviously, port P4 is assumed to be an input. When the switch is open, port P4 will sense a 1 on its input. When the switch is closed, it will sense a 0.

Now what happens when you execute this code?

CLR R12
SBO 20

This will program port P4 to be an output, and to show a 1 (5V) at the output. SBZ will, in contrast, make this port output a 0. So how do you make it an input port? - This is done by resetting the chip. As long as you don't use a SBZ/SBO (or a LDCR) on the ports, the ports are inputs.

Nothing has happened up to now. But now imagine that you press the switch. This will put the 1 output to ground, causing the short circuit, and your 9901 is toast.

=== What about the TI console? ===

So can we damage the 9901 in the TI console by a suitable CRU operation? - Luckily not.

The reason is the way how TI used the ports on the mainboard. Most of the ports are configured as outputs. Nothing happens when you reset them to inputs.

* The pure interrupt inputs (/INT1 to /INT6) are safe, as they cannot output anything. They have no output driver that could be fried.
* P0 and P1 are not connected.
* P2, P3, and P4 are designed as outputs, so they cannot be turned from an input to an output.
* P5 is the selector of the Alpha Lock key, so output as well.
* P6 and P7 (/INT15) are the cassette motor control outputs.
* P8 (/INT14) is the audio gate output.
* P9 (/INT13) is the cassette output.
* P10 (/INT12) is pulled up to 5V via a 10 kOhm resistor. If you put a 0 on this port (5V), the maximum current is 500 µA, which results in a power dissipation of 2.5 mW (far below the maximum 750 mW).
* P11 (/INT11) is the cassette input. However, there is a resistor of 2.2 kOhm (R413) which effectively guards the port of high currents.
* P12, P13, P14, P15 (/INT10 ... /INT7) are the keyboard input lines. Again, we have pull-ups of 10 kOhm against +5V, but also 470 Ohm on the line, which means a maximum of 8.5 mA or 42.5 mW. This is still well below the maximum value.

So we see that resistors are the best way to protect the ports. And we may calm down; we cannot burn the 9901 in the TI console by a bug in our program.