Serial I/O

The Serial I/O package is an arbitrary collection of processes that use the serial ports on the H8. The collection includes:

• print output — offering H8 access to the Macintosh printer via a special LP: driver;
• ASCII file transfer — allowing the H8 and Macintosh to exchange ASCII text files via a special AT: driver;
• modem access — allowing the H8 to use the Macintosh modem.

By all rights, the Tape I/O functions should be in here as well. But they were already completed when this package was conceived and I decided to let sleeping dogs lie.

All H8 I/O must flow through the I/O package, which maintains 8250 UART emulation. These routines provide the "glue" between the I/O package and the Macintosh disk system and serial driver; this is all Macintosh code with nothing of the H8 system emulated here.

Print Page Layout

Print page specifications:

• The page defaults to a 1/2 inch margin, all the way around (this is configurable on the Emulator Preferences panel).

• The emulator uses, by default, the Courier font at a size of 10-points. This should allow about 90 characters wide by 60 lines on 8 1/2 x 11 paper, portrait format, or around 120 characters wide by 45 lines on 8 1/2 x 11 paper, landscape format.

  These figures were obtained using an Apple Personal LaserWriter/300 printer with QuickDraw printing; your mileage may vary. Experimentation is required to determine what you will get on your printer.

• Both the Style and Job dialogs are used, so the user can select the page orientation, paper size, number of copies, from- and to-pages, etc.

The emulator supports CR and LF. The emulator supports TAB, assuming a stop every 8 characters. The emulator supports a series of escape sequences, beginning with the ESC character, detailed in the following table.

The emulator supports Form Feed to move to the next page. In the absence of a form feed character, the emulator will skip to the next page on receipt of the first printable character for the print line following the last one that fits on the page. This will allow a full page of text followed by Form Feed without generating an extra blank page. Certain characters in the non-printable character set (0x00 through 0x1f) are used to signal between the LP: driver and the print package; these are described below. All other non-printable characters are filtered.

Note on Numbers: Several of the escape sequences take a numeric operand. These must be expressed in printable ASCII digits. The number can be expressed in either decimal or octal representation, and spaces are ignored, easing the use of calculated values when programming in Basic. The use of Octal is signaled by the presence of at least one leading zero; decimal numbers must not have a leading zero. Thus, "27" is a decimal representation and "033" is an octal representation of the number 27 (e.g., the ESCape character).

Here's a page of scanned demo print produced on the author's laser printer.

The printer doesn't provide a word-wrap feature, nor does it provide text-run measurement services. Your program is responsible for making sure that the print line fits in the available page width.

go to top

Print Handler Design

My original intent was to print from the emulated H8 directly into a Print Manager page. But attempting to keep a page open that long and run the emulator during the print process proved to be very unreliable.

Instead, we use a temporary, private "spool" file that receives all H8 print output. That is, the spool file contains ASCII text and formatting characters.

When the H8 printer closes, we go into a classic Print Manager loop. The emulator is suspended while we're in the loop, which goes as follows:

1. Allocate a TPrint record. Open the printer and set default values in the TPrint record. Rewind the spool file.

2. Offer the user a style dialog ("Page Setup..."). If the user cancels, the loop ends and nothing prints.

3. Start a print job. Load fonts and determine the page bounds.

4. Offer the user a print job dialog. If the user cancels, the loop ends and nothing prints.

5. Print the entire document. The print manager takes care of clipping at the margins, and printing only the pages selected in the job dialog.

6. Close the print job and the printer. Release the TPrint record. Rewind the spool file.

The temporary spool file is opened once when the emulator is started, and deleted when the emulator quits. It's reused for all H8 print jobs. The file is created in the temporary items folder with a creator of 'h8h8' and a type of 'TRSH', using the current time expressed as an eight-character hex string as the file name. (If the emulator crashes, you'll see these in the rescued items folder on the next Mac restart.)

A special LP: driver is required on the H8 to signal the start and end of a print job, as well as to transfer the print data to the emulator. The print driver sends the following characters to control the print process:

Control Character	Function
0x02	Open a print file — rewind the spool file, enable the "close print job" menu item, and prepare to receive print output.
0x03	Close an open print file — if the spooler had been open and has collected data, print that data. Then close the spooler and disable the "close print job" menu item.

The user will see the Style and Job dialogs after the LP: driver sends the close code.

Since it's possible for an HDOS application to .CLEAR the print file rather than use .CLOSE, and since the LP: driver does not see .CLEAR SCALLs, there will be a menu item that will allow a print job to be manually closed, initiating the print process. This item will be active only while a print job is active, as shown above. Using this menu starts the same process as when the driver sends the close code.

Formatting information is stored in a print segment table, and includes such things as font number and size, font color, "face" information (e.g., bold, etc.), and the height of the segment.

There can be up to 75 segments per 150-character print line; if they are used up, the last segment on the line will be printed with the last set of formatting information received by the printer emulator.

go to top

File Transfer Design

The emulator supports the bi-directional transfer of ASCII text files between the H8 and the Macintosh file system. A specially-written AT: device driver is supplied with the emulator which can communicate open, close, and EOF conditions, allowing files to be moved with a minimum of user interaction.

The AT: driver uses a series of codes to signal the emulator:

Control Character	Direction	Function
0x02	outbound	Open an input file. The StandardGetFile dialog is displayed. If the user cancels, a Cancel code (0x07) is returned. Otherwise, the file is opened and ready for input.
0x03	outbound	Close the input file.
0x04	inbound	End of file. This is send by the emulator following the last character of the file.
0x05	outbound	Open an output file. The StandardPutFile dialog is displayed. If the user cancels, a Cancel code (0x07) is returned. Otherwise, the file is opened and ready for output.
0x06	outbound	Close the output file. This is sent by the AT: driver when the output file is closed.
0x07	inbound	Cancel. Sent by the emulator to signal that the user clicked Cancel on the StandardGetFile or StandardPutFile dialog, or some other error prevented the file from opening. The driver returns EC.RF or EC.WF to PIP, which prints a "Read (Write) Failure on the Device" message on the console.

(In the table, a direction of "outbound" refers to the H8-to-emulator direction, and "inbound" refers to the emulator-to-H8 direction.)

Because the opening and closing of Mac files is controlled by the AT: driver, the user need not fiddle with emulator menus or do anything else out of the ordinary to transfer a file; the act of copying the file to/from the AT: driver causes the dialog box to appear and after it is dispatched the rest of the process is automatic.

To maintain flow control in the emulator-to-H8 direction, characters are not presented to the H8 until the AT: driver reads the 8250 status port. The process goes as follows:

1. The AT: driver reads the status port. The I/O Process decodes the IN and calls the file transfer status routine, atStatus (ref: I/O package).

2. If there is an output file open, atStatus sets the txTempty bit in a status byte. If there is an input file open, atStatus sets the rxDataAvailable bit in the same status byte, and then puts the next input byte onto the serial port with a call to ioPutSerialData.

3. The AT: driver sees the rxDataAvailable bit and INs the data port.

4. The I/O process decodes the IN, resets the state of the 8250 UART based on the fact of the read, and returns the data byte to the AT: driver.

This process ensures that the data flows at the maximum rate supported by the AT: driver, with minimum overhead since it is driven completely by AT: driver events. The process does not allow for the use of receiver interrupts on this port, but since this port is dedicated to this file transfer function and HDOS does not support the user of interrupts by character drivers, this should not be a problem.

End-of-line character conversion is done at the file I/O routines:

• output carriage return characters are dropped;
• output line feed characters are converted to carriage return;
• input carriage return characters are converted to newline (line feed).

If for some reason a Macintosh text file does not end in a carriage return character, the emulator ensures that a newline character is sent to the H8 before the end-of-file signal.

go to top

Modem Design

Since there's only one modem port on the Macintosh, this is a single-use resource that we can't just grab and use. A menu item is used to open or close the modem; the modem must be opened before being used, and should be closed after use so that other Macintosh applications can use it.

When opened, the modem is initialized for 9600 bps, 8 data bits, no parity, 1 stop bit.

200-character buffers are available at both incoming interfaces. The emulator issues Xoff when they pass the 160-character point, and Xon when they shrink below 40 characters.

Xon/Xoff are supported in all four directions.

If break is set on the 8250 UART, the emulator holds a break condition on the modem for 300ms. The UART's break condition does not need to be held for any length of time.

The routine mdProcessing moves characters from the output buffer to the modem and from the modem to the input buffer. This is called by the scheduling loop every 10ms, but doesn't do anything unless the modem has been allocated for use. As many characters as possible are moved on each call.

Characters are sent from the input buffer to the H8 at a rate of 500 cps. This is managed by the mdClock routine, which gets control from the scheduling loop every millisecond. Output from the H8 is simply placed into the output buffer, if the modem has been allocated. If not, it's trashed.

The configuration of the modem is quite lame. It occurred to me during development that nobody is really ever going to use this feature, given all the great Mac-native communications software out there. No to mention that there's no way you'll ever get a web browser on an H8! So I went with a fixed configuration. If there's any interest in actually using this feature, I'll consider making the feature configurable.

go to top