Details of configuring the SIO port mappings

[donfroula]

I've been trying to figure out how the multiple layers of mapping of character mode devices to the four (4) virtual SIO serial ports actually works on the IMSAI8080esp.

At the CP/M level, there are four logical devices that are mapped to "physical" devices - CON, RDR, PUN, and LST.

CON: is the system console device, used for communication with the operator.
RDR: is the paper tape reader device.
PUN: is the paper tape punch device.
LST: is the output list device (printer).

The CP/M "physical" devices to which these logical devices may be mapped (by default IOBYTE values or modified with the STAT command) are:

TTY:	Teletype device (slow speed console)
CRT:	Cathode ray tube device (high speed console)
BAT:	Batch processing (console is current RDR:, output goes to current LST: device)
UC1:	User-defined console
PTR:	Paper tape reader (high speed reader)
UR1:	User-defined reader #1
UR2:	User-defined reader #2
PTP:	Paper tape punch (high speed punch)
UP1:	User-defined punch #1
UP2:	User-defined punch #2
LPT:	Line printer
UL1:	User-defined list device #1

Not all CP/M physical devices may be attached to the logical devices, as only two bits per logical device or four possibilities are present in the IOBYTE for each logical device . What is possible, defined in CP/M BIOS, may be displayed by the "STAT VAL:" command. For example:

Iobyte Assign:
CON: = TTY: CRT: BAT: UC1:
RDR: = TTY: PTR: UR1: UR2:
PUN: = TTY: PTP: UP1: UP2:
LST: = TTY: CRT: LPT: UL1:

The actual devices attached to the IMSAI8080esp are driven by port definitions and subroutines in the BIOS portion of CP/M. Thus, the logical RDR: device, for example, could actually be a high speed reader, teletype reader, or cassette tape. The BIOS defines the mapping of the CP/M physical device names to specific SIO Z80 ports. An example of SIO emulated processor port definitions from the BIOS source code is here:

                ;       IMSAI 8080 I/O PORTS
                ;
 0002 =         TTY     EQU     02H             ;TTY DATA PORT
 0003 =         TTYS    EQU     03H             ;TTY STATUS PORT
                
 0004 =         KBD     EQU     04H             ;KEYBOARD DATA PORT
 0005 =         KBDS    EQU     05H             ;KEYBOARD STATUS PORT
                
 0008 =         SIO1C   EQU     08H             ;CONTROL PORT FOR FIRST SIO BOARD
                
 0022 =         AUX     EQU     22H             ;AUX DATA PORT
 0023 =         AUXS    EQU     23H             ;AUX STATUS PORT
                
 0024 =         USR     EQU     24H             ;USER DATA PORT
 0025 =         USRS    EQU     25H             ;USER STATUS PORT
                
 0028 =         SIO2C   EQU     28H             ;CONTROL PORT FOR SECOND SIO BOARD

However, since we are dealing with an emulated Z80/8080 and SIO boards, there are lines in boot.conf and system.conf that define how the HAL or Hardware Abstraction Layer operates. These lines define how the emulated SIO board ports map to real ESP UARTS and other emulated devices, like the modem:

### SIO-2 default port mappings (HAL)
SIO1.portA.device=WEBTTY,UART0
SIO1.portB.device=VIOKBD
SIO2.portA.device=WEBPTR,UART1
SIO2.portB.device=MODEM

These mappings require modification if the S132 is installed. For example, my system (with S132 enabled) uses:

### SIO-2 default port mappings (HAL)
SIO1.portA.device=S132TTY+,WEBTTY,UART0
SIO1.portB.device=S132VIO+,VIOKBD
SIO2.portA.device=WEBPTR,UART1
SIO2.portB.device=MODEM

What I am unclear about (and seems not to be documented) is how these boot.conf lines work.

• Why are multiple HAL mappings allowed per SIO port? Is there a significance to the order?
• What does the "+" character mean after the HAL device?
• How do the HAL UART0 and UART1 device map to the real ESP32 UARTs and MODEM HAL device?
• Is there a comprehensive list of HAL devices and which may be mapped to each SIO port?

The configuration guides on Dave's web site for the IMSAI8080esp and S132 has some guidance, but details are lacking. Dave mentions "details of configuring the SIO port mappings will be published later". I'd be very interested in those details.

Regards,

Don

[dmcnaugh]

A really nice summary how how CP/M 2.2 does logical to "physical" device mapping.

I will write up the details of configuring the SIO port mappings with the HAL and post it here and add it to the website ensuring I answer the questions you've asked.

Should be able to do that this weekend.

[dmcnaugh]

As noted above: there are only 4 (four) ports for the CP/M logical devices to be mapped via the CP/M "physical" level and these are the 4 serial ports of the emulated SIO communications cards each with 2 ports, designated:

• SIO1.portA (IO ports 02H & 03H)
• SIO1.portB (IO ports 04H &05H)
• SIO2.portA (IO ports 22H & 23H)
• SIO2.portB (IO ports 24H & 25H)

The HAL then lets us map these 4 (four) ports to one or more of 8 (eight) actual end points for the emulation as follows:

• UART0 - Physical UART0 on the ESP32 (Tx/Rx Patch pins & USB) and typically RS232-1 DE-9
• UART1 - Physical UART1 on the ESP32 (IO22/IO5 Patch pins) and typically RS232-2 DE-9
• WEBTTY - Web Socket endpoint for the TTY: window on the Desktop UI (Web)
• VIOKBD - Web Socket endpoint for the CRT: window (keyboard only) on the Desktop UI (Web)
  • this device should have been named WEBVIO, but won't change now
• MODEM - the WiFi based emulated 'AT' Modem
• WEBPTR - Web Socket endpoint for the PTR: window on the Desktop UI (Web)

This much is summarised in the Configuration guide

• in the table at https://thehighnibble.com/imsai8080/configure/#serial-communications-rs232-usb
• and https://thehighnibble.com/imsai8080/configure/#sio-2-port-mappings

The remaining 2 (two) actual end points for the emulation are specific to the S-132 add-on:

• S132TTY - endpoint for the VT100 (TTY:) screen on the S-132 (<ctrl><alt><F1>)
• S132VIO - endpoint for the IMSAI VIO (CRT:) screen (keyboard only) on the S-132 (<ctrl><alt><F4>)

Now that we understand the full list of endpoints, it is time to understand the operation of the HAL:

• the HAL will search the list of mapped endpoints until it finds the first "connected" endpoint and normally communicate with only that device
• UART0, UART1 & MODEM are always "connected"
• WEBTTY, VIOKBD, WEBPTR are only connected when their corresponding Web Socket is connected (plug glyph is green not red)
• S132TTY, S132VIO are only connected when the S-132 is detected
• for example: if the HAL is configured with SIO1.portA.device=WEBTTY,UART0 this this port will:
  • send/receive to/from the TTY: window on the Desktop UI if the Web Socket is connected (green)
  • skip the TTY: window on the Desktop UI if the Web Socket is not connected (red) and send/receive with/from UART0
  • ie. input & output will only ever be to one of these two endpoints depending on the state of the TTY: window Web Socket
• HOWEVER the use of the + sign after an endpoint name will call the HAL to follow on (sometimes I've called this "fall through") to the next endpoint on the list
• for example: if the HAL is configured with SIO1.portA.device=WEBTTY+,UART0 this this port will:
  • send/receive to/from the TTY: window on the Desktop UI if the Web Socket is connected (green)
  • but always continue on and also send/receive to/from UART0
  • ie. output will be to both of these endpoints and input from either endpoint if the TTY: window Web Socket is connected

[donfroula]

This is great, Dave. Thanks for documenting.

Each SIO port is associated with two Z80/8080 IO ports. One is for read/write data transfer, the other for device status. The two processor ports are documented in the system.conf comments:

# SIO 1 Channel A, Ports 2/3
# SIO 1 Channel B, Ports 4/5
# SIO 2 Channel A, Ports 34/35
# SIO 2 Channel B, ports 36/37

BTW, I can access and send/receive data from those ports directly by writing/reading to them in BASIC, as in my Echo speech synth demo video, elsewhere here, regardless of CP/M device assignment. Data goes to whatever HAL device is connected to the SIO/Channel per your description.

Could you elaborate regarding which of the HAL devices are bidirectional and which support the status port on the SIO channels?

Do the HAL WEBTTY and S132TTY HAL devices connect to both the TTY and CRT devices in the browser GUI and S132, depending which is active? There is no separate WEBCRT or S132CRT device. Same question for the VIOKBD and S132VIO.

I think you meant, "...if the Web Socket is NOT connected (red) and send/receive..."

[dmcnaugh]

As you've noted: all the SIO channels are bidirectional, ie. can be both read and written, always.

All the HAL devices are also bidirectional and implement the status port because they are endpoints for the SIO channels.

The sole exception is the IMSAI VIO device (VIOKBD and S132VIO) as only the keyboard input is serially attached to an SIO channel.
The IMSAI VIO is a memory mapped character based display, for details and the manual see: https://s100computers.com/Hardware%20Folder/IMSAI/VIO%20Board/VIO%20Board.htm

So as noted, there is NO WEBCRT or S132CRT device to be serially attached to an SIO channel for output. It hurts my eyes and my brain to even see these these two ideas in text and would prefer to erase them from this post :-)

The IMSAI VIO includes and onboard BIOS of its own that more or less (more less than more) emulates an ADM-33 terminal. The CP/M BIOS maps output to the CRT: "physical" device by making direct calls to the VIO BIOS, no serial comms via an SIO is involved. The CP/M BIOS maps input from the CRT: "physical" device to the SIO 1 Channel B, Ports 4/5 so then via the HAL to whatever input device you've assigned, typically VIOKBD or S132VIO or both.

[donfroula]

Perfectly clear, Dave. Thanks for the great detail.

I am going to study the CP/M 2.2B01 BIOS source code and try to diagram out the connection paths.

[dmcnaugh]

Actually, there is still something missing from this story to complete the picture. But the answer is buried in the CP/M BDOS code and I've never fully understood it. It would be great if someone could conclusively complete the picture.

The un-resolved link is how CP/M maps the 12 (twelve) CP/M "physical" devices to entry points in the CP/M BIOS.

For me: TTY:, CRT:, LPT: are mostly clear. However BAT:, UC1:, PTR:, PTP:, UR1:, UR2:, UP1:, UP2: and UL1: frequently confuse me as there appear to be overlaps and uni-directional devices. I'd love to see a neat table that lays it all out clearly.

[donfroula]

I spotted this old article the delves into using the IOBYTE in adapting the 2.2 BIOS to a new machine. If I have time today, I’ll see how well it maps to the BIOS assembly source, thoughtfully provided on the disk image.

https://www.mark-ogden.uk/mirrors/www.cirsovius.de/CPM/Projekte/Artikel/Grundlagen/IOByte/IOByte-de.html

[donfroula]

I'm pretty sure this is how the BIOS works with IOBYTE in the emulated v2.2 CP/M, after tracing the flow through the BIOS code.

Looking through the CP/M 2.2 BIOS source, the two SIO boards' data and status ports and labels are defined at the top of the file:

                ;
                ;       IMSAI 8080 I/O PORTS
                ;
 0002 =         TTY     EQU     02H             ;TTY DATA PORT
 0003 =         TTYS    EQU     03H             ;TTY STATUS PORT                
 0004 =         KBD     EQU     04H             ;KEYBOARD DATA PORT
 0005 =         KBDS    EQU     05H             ;KEYBOARD STATUS PORT            
 0008 =         SIO1C   EQU     08H             ;CONTROL PORT FOR FIRST SIO BOARD
                
 0022 =         AUX     EQU     22H             ;AUX DATA PORT
 0023 =         AUXS    EQU     23H             ;AUX STATUS PORT                
 0024 =         USR     EQU     24H             ;USER DATA PORT
 0025 =         USRS    EQU     25H             ;USER STATUS PORT          
 0028 =         SIO2C   EQU     28H             ;CONTROL PORT FOR SECOND SIO BOARD

CP/M places the character to be output in register C and then calls the JMP table location that vectors to the SIO routine for one of the four logical devices (edited here to include only the four SIO-compatible devices). The device must be output-capable, so no vector is supplied for READER, the paper tape reader, normally. There are only three valid logical devices for output:

                ;
                ;       JUMP VECTOR FOR INDIVIDUAL SUBROUTINES
                ;

 D206 C3D8D3            JMP     CONST           ;CONSOLE STATUS
 D209 C3E4D3            JMP     CONIN           ;CONSOLE CHARACTER IN
 D20C C3F0D3            JMP     CONOUT          ;CONSOLE CHARACTER OUT
 D20F C308D4            JMP     LIST            ;LIST CHARACTER OUT
 D212 C314D4            JMP     PUNCH           ;PUNCH CHARACTER OUT
 D215 C320D4            JMP     READER          ;READER CHARACTER IN

Looking at the console output routine referenced in the JMP table as an example (CONOUT), the code vectors to this routine, which examines the two bits in IOBYTE to determine which subroutine to call to do the physical output.

                ;
                ;       CONSOLE OUTPUT CHARACTER FROM REGISTER C
                ;
 D3F0 CDC3D3    CONOUT: CALL    DISPATCH        ;GO TO ONE OF THE PHYSICAL DEVICE ROUTINES
 D3F3 01                DB      1               ;USE BITS 1-0 OF IOBYTE
 D3F4 49D4              DW      TTYOUT          ;00 - TTY:
 D3F6 A0D4              DW      CRTOUT          ;01 - CRT:
 D3F8 CBD4              DW      LPTOUT          ;10 - BAT:

                ;       DW      AUXOUT          ;11 - UC1:
 D3FA 81D4              DW      USROUT          ;11 - UC1:

Note the AUXOUT routine is commented out here or UC1 would map to a different Z80 port (Port 22H and 23H or SIO2.portA.device).

Continuing with USROUT:

                ;
                ;       USER OUTPUT
                ;
 D481 DB25      USROUT: IN      USRS            ;GET STATUS
 D483 0F                RRC                     ;TEST BIT 0
 D484 D281D4            JNC     USROUT          ;WAIT UNTIL TRANSMITTER READY
 D487 79                MOV     A,C             ;GET CHAR TO ACCUMULATOR
 D488 D324              OUT     USR             ;SEND TO USR
 D48A C9                RET

The USRS status bit is checked (Z80 Port 25H). When the mapped HAL device is ready, Register C, with the character to transmit, is sent to USR (Z80 Port 24H) and the BIOS returns from the IO call.

Any HAL device connected to Z80 Port 24H (SIO2.portB in the emulated SIOs) will get the character. In the case of the default HAL configuration, that would be the MODEM (SIO2.portB.device=MODEM).

What puzzles me is how the STAT VAL: command determines which physical devices are valid for each logical device.

[donfroula]

A nice practical aspect of all of this for me is that I can freely associate either or both of the IMSAI8080esp physical DB9 serial ports with any any of the four available SIO channels,

For example, I have found with this configuration, in combination with Udo Munk's CPM/2.2B03 disk image, I can route the LST printer device to UL1,

stat LST:=UL1: (not possible with the supplied CP/M 2.2b01 disk image on the SDCARD)

UL1 is mapped in the b03 CP/M version's BIOS to SIO2.portA. With this configuration in boot.conf:

SIO1.portA.device=S132TTY+,WEBTTY
SIO1.portB.device=S132VIO+,VIOKBD
SIO2.portA.device=WEBPTR,UART0+,UART1
SIO2.portB.device=MODEM

...printer output will go to both physical DB9 connectors simultaneously. I have my serial printer connected to one port and my Echo speech synthesizer to the other. I simply switch on the device I need. The physical HAL ports can even be set to different baud rates. However, a reboot will always direct boot messages to UART0, regardless of configuration.

[udo-munk]

What puzzles me is how the STAT VAL: command determines which physical devices are valid for each logical device.

This simply is hardcoded in the STAT program, it has no informations about physical ports in a machine. The program sets two bits in the IOByte for a logical device, up to the BIOS to make something meaningful from the bits. The latest BIOS version B03 makes best use of this.

[donfroula]

Thanks. Simple answer!

I traced through the improvements in b03 and like the way the SIO mappings are configured much better than b01.