OS Assembly Language

Sat, 21 Mar 2015 | Microcomputer 0606

Earl W. Bollinger

It is sometimes useful to be able to develop specific device driver software for the OS9 environment. But it can be difficult to write a device driver without some place to start from. The purpose of this article is to provide some software tools that will allow you to be able to develop Sequential Character File (SCF) device driver software more easily. Your OS9 Technical Reference manual provides more detailed information about these drivers in Chapter Six.

A SCFman device driver is primarily designed to perform the actual character by character data transfers for OS9. It handles all the actual details of input/output to or from a specific hardware device or controller. The SCF drivers are usually designed so as to be re-entrant. Thus one copy of the driver can handle all identical devices resulting in the minimum use of available memory.

Program Example 1 demonstrates the typical structure of a basic SCF device driver module. This particular program listing is actually a template or boilerplate used to start the development of custom SCF driver modules.

The SCF driver must have a header, body and cyclic redundancy checksum (CRC) value in order to be a valid OS9 module. Otherwise, OS9 will simply refuse to load the module into memory or execute it. You must use the OS9 assembler definition files, located in the /DO/DEFS directory, in order to interface to the OS9 system properly. The dispatch jump table provides the six major functions that have to be provided by the driver for OS9.

INIT has to provide for two basic functions. First, INIT has to initialize the device or program it for later use. Second, if required, INIT must install an interrupt service routine into OS9 for that specific device. READ simply gets or reads the next character from the device or input buffer. WRITE outputs a character via the device or output buffer. GETSTAT and SETSTAT provide a means whereby the device's status can be obtained or changed. TERM is used to de-allocate or terminate the device from the system when it is no longer needed. TERM must also remove the interrupt routine from the OS9 system if it was installed earlier.

Program Example 2 demonstrates the typical structure of a SCF based NULL device driver. Program Example 3 is the SCF device path descriptor module for the NULL device driver.

A null device is a very useful tool for multitasking types of operations. Any data redirected to a null device will simply be thrown away or ignored. This is useful for background tasks that would otherwise clutter up the console screen with extraneous junk or data. For example:

OS9:ASM /D2/PROGRAM L 0 = /D2/ PROG.OBJ & (ENTER)

causes OS9 to assemble the program as a concurrent background task. But the output listing would also be to the screen. This would cause problems if you wanted to use the text editor or some other program at the same time. But if you used a null device like this:

OS9:ASM /D2/PROGRAM L 0 = /D2/ PROG.OBJ >/NL & CENTER;

then the output listing would simply disappear, and only error messages would get displayed on your screen.

To use the device driver as a null device is relatively simple. First a null device does not require any initialization and it should always be ready to ignore anything sent to it. Thus you only need to have INIT, WRITE, GETSTAT, PUTSTAT, and TERM return to OS9 the fact that the null device is always ready. If OS9 requests a READ from the null device you can have it always return an End of File (EOF) condition.

In order to use the null device driver, you must set up an appropriate device path descriptor. In this case you will call the path descriptor "NL". To then use the null device, you simply redirect all output to it with a ">/NL" redirection command. Of course, before you can use the driver and path descriptor you must have them loaded into memory using the LOAD command.

The /DO/DEFS/OS9defs and /DO/DEFS/SCFdefs system definition files require a large amount of memory to be needed by the OS9 assembler. When you assemble the programs, you should allocate about 15k bytes of memory for the assembler to utilize. For example:

OS9:ASM /D1/NULLDRIVER.SRC L 0 = /D0/CMDS/ NULLDRIVER #15k (ENTER)

would cause the assembler to assemble the program and install the object module in the execution directory, also allocating 15k bytes of memory for the assembler's symbol table storage area.

The Color Computer does offer some interesting possibilities for those of you who want to address these items. If you have a Radio Shack Multi-Pak Interface (26-3024) and a Deluxe RS-232 Program Pak™ (26-2226) you can design your own custom SCF serial port driver to use with OS9. The Multi-Pak Interface is designed for switching Program Paks via software.

Pin 8 on the Color Computer's Program Pak connector provides for an interrupt line that can be used to advantage. This line goes to pin 18 of the U4 PIA chip. U4 is a MC6821 PIA device and pin 18 allows for a Fast Interrupt Request

Program Example 1

(FIRQ) to be sent to the MC6809 microprocessor. Thus if your own device driver's interrupt routine is installed into OS9, you then can get to your serial port via software switching of the Multi-Pak Interface.

You could have more than one Deluxe RS-232 Program Pak™ in the interface also. By using the path descriptor serial port address location (offset OEhex) as a Program Pak slot select value, you could use the same device driver for more than one port. The path descriptor DVINIT byte can be used to program each port as required for each application.

00002

00003

00004

00005

00006

00007

00008

00009

00010 00011 00012

00013

00014

00017

00018

00019

00020 00021 00022

00023

00024

00025

00026

00027

00028

00029

00030

00031

00032

00033

00034

00035

00036

00037

00038

NAM SCFDRIVER

TTL TEMPLATE ***************************************

* SCF DEVICE DRIVER TEMPLATE ***************************************

* USE /D0/DEFS/OS9DEFS AND USE /D0/DEFS/SCFDEFS ARE

* PUT BETWEEN THE IFP1 AND ENDC COMMANDS

IFP1 ENDC

00E1 0081 0000 000 D 000E 0015

D 001 D

87CD002B 03

53434644

TYPE REVS

DRVNAM

SET DRIVR+OBJCT

SET REENT+1

MOD DRVEND,DRVNAM,TYPE,REVS,DRSTRT,SIZE

FCB UPDAT.

FCS /SCFDRVR/

FCB 1 EDITION NUMBER

ORG V.SCF

ALLOW ROOM FOR SCF VARIABLES

0016

IF DESIRED, ADD ADDITIONAL VARIABLE TEMPORARY STORAGE HERE.

SIZE

SCFDRIVER ENTRY POINT HERE DRSTRT

DISPATCH TABLE FOR DEVICE DRIVER
W 0016	16000F	LBRA	IN IT	INITIALIZE DEVICE
W 0019	16000C	LBRA	READ	GET A CHARACTER FROM
W 001C	160009	LBRA	WRITE	PUT A CHARACTER TO
W 001F	160006	LBRA	GETSTAT	GET DEVICE STATUS
W 0022	160003	LBRA	PUTSTAT	SET DEVICE STATUS
W 0025	160000	LBRA	TERM	TERMINATE THE DEVICE

INSERT APPROPRIATE ROUTINES FOR EACH SECTION AS REQUIRED

00045

00046

00047

INSERT APPROPRIATE ROUTINES FOR EACH SECTION AS REQUIRED

00048	*
00049	0028	IN IT
00050	0028	READ
00051	0028	WRITE
00052	0028	GETSTAT
00053	0028	PUTSTAT
00054	0028	TERM
00055	0028 F8E1EA		EMOD
00056	002 B	DRVEND	EQU
00057			END

00000 error(s) 00006 warning(s)

$002B 00043 program bytes generated $0000 00000 data bytes allocated $2050 08272 bytes used for symbols

Program Example 2
00001
00002				NAM	NULLDRIVER
00003				TTL	FROM TEMPLATE
00004			***************************************
00005			*
00006			* SCF NULL DEVICE DRIVER
00007			*
00008			***************************************
00009			*
00010			*
00011			* USE /D0/DEFS/OS9DEFS AND USE /D0/DEFS/SCFDEFS ARE
00012			* PUT BETWEEN THE	IFP1 AND ENDC COMMANDS
00013			*
00014				IFPl
00017				ENDC
00018			*
00019		00E1	TYPE	SET	DRIVR+OBJCT
00020		0081	REVS	SET	REENT+1
00021		0000	87CD0034	MOD	DRVEND, DRVNAM, TYPE, REVS, DRSTRT
00022		000D 03		FCB	UPDAT.
00023		000E	4E554C4C DRVNAM	FCS	/NULLDRVR/
00024		0016	01	FCB	1 EDITION NUMBER
00025			*
00026			*
00027	D	001 D		ORG	V.SCF ALLOW ROOM FOR SCF 1
00028			*
00029			* IF DESIRED, ADD	ADDITIONAL VARIABLE
00030			* TEMPORARY STORAGE HERE.
00031			*
00032		0017	SIZE	EQU
00033			*
00034			* SCFDRIVER ENTRY	POINT HERE
00035		0017	DRSTRT
00036	W	0017	16000F	LBRA	IN IT
00037	W	001A	16000E	LBRA	READ
00038	W	001D 160009		LBRA	WRITE
00039	w	0020	160006	LBRA	GETSTAT
00040	w	0023	160003	LBRA	PUTSTAT
00041	w	0026	160000	LBRA	TERM

00042

00043

* INSERT

APPROPRIATE ROUTINES FOR

EACH

00044

* SECTION

AS REQUIRED

00045

★

00046

0029

IN IT

00047

0029

WRITE

00048

0029

GETSTAT

00049

0029

PUTSTAT

00050

0029

TERM

00051

00052

0029

CLRB

RETURN A ZERO CODE

00053

002A

RTS

DON'T DO ANYTHING

00054

★

00055

★

00056

002 B

READ

00057

002B 4F

CLRA

00058

002C

1A01

ORCC

#$01

SET CARRY FLAG

00059

002E

C6D3

LDB

#E$EOF

SEND BACK EOF

00060

0030

RTS

00061

00062

★

00063

0031

7120A6

EMOD

00064

0034

DRVEND

EQU

★

00065

END

00000

error(s)

$0034 00052 program bytes generated $0000 00000 data bytes allocated $2050 08272 bytes used for symbols

00006 warning(s)

$0034 00052 program bytes generated $0000 00000 data bytes allocated $2050 08272 bytes used for symbols

Program Example 3
00001			NAM	NL
00002			TTL	NULL DEVICE		PATH DESCRIPTOR
00003		*********************************
00004		*			*
00005		* SERIAL PORT DEVICE DESCRIPTOR			★
00006		★			*
00007		★ USED WITH NULL	DEVICE	DRIVER	*
00008		*			*
00009		*********************************
00010		*
00011	0003	UPDATE	SET	03
00012	00 F0	DEVICE	SET	$F0
00013	0001	OBJECT	SET	$01
00014	0080	REENT	SET	$80
00015		*
00016		* MODULE HEADER INFORMATION
00017		*
00018	00 Fl	TYPE	SET	DEVICE+OBJECT
00019	0000	87CD003D	MOD	DVEND,	DVNAM,	TYPE,REENT+1,SCFNAM,DRVNAM
00020	000D 03		FCB	UPDATE
00021	000E	000000	FCB	$00, $00,$00		ADDRESS OF SERIAL PORT
00022	0011	IB	FCB	OPTSIZ		•
00023	0012	OPTBGN	EQU	★
00024		*

00025		* PATH DESCRIPTOR		OPTION	LIST
00026		★	*
00027	0012	00	CLASS	FCB	00	SCF TYPE DESIGNATION
00028	0013	00	UPC	FCB	00	UPPER/LOWER CASE
00029	0014	01	BSE	FCB	01	BACKSPACE ECHO BS,SP,BS
00030	0015	00	DCLRL	FCB	00	DELETE OR CLR LINE
00031	0016	01	ECHO	FCB	01	ECHO CHARS
00032	0017	00	AUTOLF	FCB	00	AUTO LINE FEED
00033	0018	00	NULL	FCB	00	NO END OF LINE NULLS
00034	0019	00	PAUSE	FCB	00	END OF LINE PAUSE OFF
00035	001Â	10	PAGE	FCB	16	LINES PER PAGE
00036	001 B	08	BKS PC	FCB	08	BACKSPACE CHAR
00037	001C	18	DELETE	FCB	24	DELETE LINE CHAR
00038	001 D	0D	EOFREC	FCB	13	END OF RECORD (LINE)
00039	001E	IB	ENDFIL	FCB	27	END OF FILE CHAR
00040	001 F	04	RPRLL	FCB	04	REPRINT LAST LINE
00041	0020	01	DUPE	FCB	01	DUPLICATE LAST LINE
00042	0021	17	PSCHAR	FCB	23	PAUSE CHAR
00043	0022	03	INTRUP	FCB	03	KEYBOARD INTERRUPT CHAR
00044	0023	15	ABORT	FCB	$15	KEYBOARD ABORT CHAR
00045	0024	08	BKSPE	FCB	08	BACKSOACE ECHO CHAR
00046	0025	07	OVRFLW	FCB	07	BELL-LINE OVERFLOW CHAR
00047	0026	00	DVINIT	FCB	00	DEVICE INITIALIZATION VALUE
00048	0027	02	BAUD	FCB	02	BAUD RATE VALUE
00049	0028	002 D	DV2	FDB	DVNAM	OFFSET TO ATTACHED DEVICE NAME
00050	002A	0000	STATUS	FDB	00	OFFSET TO DEVICE STATUS ROUTIN
00051	002C	00	ERROR	FCB	00	I/O ERROR CODE STATUS
00052	001 B		OPTSIZ	EQU	*-OPTBGN
00053		*
00054
00055	002 D	4ECC	DVNAM	FCS	/NL/	DEVICE PATH NAME
00056	002F	5343C6	SCFNAM	FCS	/SCF/	DEVICE MANAGER NAME
00057	0032	4E554C4C	DRVNAM	FCS	/NULLDRVR/	SERIAL PORT DRIVER NAME
00058	003A	645CBB		EMOD		MODULE CRC VALUE
00059	00 3D		DVEND	EQU	★
00060				END
00000	error(s )					$003D 00061 program bytes generated $0000 00000 data bytes allocated $0250 00592 bytes used for symbols H 00000 warning(s) $003D 00061 program bytes generated $0000 00000 data bytes allocated $0250 00592 bytes used for symbols H

Microcomputing Magazine

» Microcomputer 0606