Digital PDFs

AA-FQ15C-TK

June 1987

563 pages

Original

20MB

Document:	MicroPower Pascal IO Services Manual 198706
Order Number:	AA-FQ15C-TK
Revision:	0
Pages:	563
Original Filename:	AA-FQ15C-TK_MicroPower_Pascal_IO_Services_Manual_198706.pdf

OCR Text

MicroPower/Pascal 1/0
Services Manual
Order No. AA- FQ15C- TK

MicroPower/Pascal 1/0
Services Manual
Order No. AA-FQ15C-TK

June 1987
This manual contains the 1/0 services information required for designing and developing
MicroPower/Pascal microcomputer application programs. 1/0 services· include file
system services, task-to-task communication, and device 1/0. A guide to writing device
drivers is provided for designing and developing nonstandard device drivers.

Operating System and Version: Micro/RSX Version 3.0
RSX- 11 M Version 4.2
RSX-11 M-PLUS version 3.0
RT-11 Version 5.2
VAX/VMS Version 4.0
Software Version:

MicroPower/Pascal-Micro/RSX Version 2.4
MicroPower /Pascal-RSX Version 2.4
MicroPower/Pascal-RT Version 2.4
MicroPower/Pascal-VMS Version 2.4

Digital Equipment Corporation

Maynard, Massachusetts

First Printing, June 1985
Updated, April 1986
Revised, October 1986
Revised, June 1987
The information in this document is subject to change without notice and should not be
construed as a commitment by Digital Equipment Corporation. Digital Equipment Corporation
assumes no responsibility for any errors that may appear in this document.
The software described in this document is furnished under a license and may be used or copied
only in accordance with the terms of such license.
No responsibility is assumed for the use or reliability of software on equipment that is not
supplied by Digital Equipment Corporation or its affiliated companies.
Copyright ©1985, 1986, 1987 by Digital Equipment Corporation
All Rights Reserved.
The READER'S COMMENTS form on the last page of this document requests the user's critical
evaluation to assist in preparing future documentation.
The following are trademarks of Digital Equipment Corporation:
DEC
DECmate
DECUS
DECwriter
DIBOL
MASS BUS
MicroPower/Pascal

PDP
P/OS
Professional
Rainbow
RSTS
RSX
RT

UNIBUS
VAX
VMS
VT
Work Processor

~urnuo~u

This document was prepared using an in-house documentation production system. All page
composition and make-up was performed by TEX, the typesetting system developed by Donald
E. Knuth at Stanford University. TEX is a trademark of the American Mathematical Society.

Contents
Preface

xix

Chapter 1 Introduction to MicroPower/Pascal Input/Output
1.1
1.2
1.3

I/O System Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .... 1-3
Performing 1/0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-7
Request/Reply Packet Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-8
1.3.1
Request Queue Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-9
1.3.2
I/O Request and Reply Packets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-11

Chapter 2 Ancillary Control Process
2.1
2.2
2.3
2.4

2.5
2.6
2.7
2.8

ACP Features and Capabilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-1
Accessing the ACP for File I/O . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2
Pascal File System Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-3
Request/Reply Packet Interface . . . . . . . . . . . . . . . . . . . . . . . . . .· . . . . . . . . . . . . 2-4
2.4.1
Physical Read and Write Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-4
2.4.2
Logical Read and Write Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-5
2.4.3
Set Characteristics Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-5
2.4.4
Get Characteristics Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-5
2.4.5
Lookup and Enter Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-6
2.4.6
Rename, Delete, Protect, and Unprotect Functions . . . . . . . . . . . . . . . . . . . . 2-7
2.4.7
Close and Purge Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-7
Status Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-8
ACP Prefix File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-9
Application Note: Device-Name Parsing . . . . . . . . . . . . . . . . . . . . . . . . . . . . -... 2-10
FALACP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-11

iii

Chapter 3 Asynchronous Serial Line (Terminal) Driver
3.1
3.2
3.3
3.4

3.5
3.6
3.7

TT Driver Features and Capabilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-1
Performing Asynchronous Serial I/O . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-2
Pascal I/O Procedure Interface . . . . . . . . . . . . . . · . . . . . . . . . . . . . . . . . . . . . . . . 3-3
Request/Reply Packet Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-5
3.4.1
Read Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-7
3.4.2
Write Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-8
3.4.3
Get and Set Characteristics Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-9
3.4.4
Set Modem Semaphore Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-14
3.4.5
Stop Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-15
Status Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-15
TT Driver Prefix File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-16
Application Note: Hardware Buffering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-20

Chapter 4
4.1
4.2
4.3
4.4

Disk-Class Device Drivers

Disk Driver Features and Capabilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-2
Performing Disk 1/0 . . . . . . . . . . . . . . . . . . ........................... 4-3
Pascal 1/0 Procedure Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-5
Request/Reply Packet Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-7
4.4.1
RLOl/2 (DL) Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-10
4.4.1.1 DL Logical Read and Write . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-10
4.4.1.2 DL Physical Read and Write . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-11
4.4.1.3 DL Get Characteristics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-12
4.4.2
RX02 (DY) Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-13
4.4.2.1 DY Logical Read and Write . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-13
4.4.2.2 DY Physical Read and Write . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-14
4.4.2.3 DY Format Subfunctions of Physical Write . . . . . . . . . . . . . . . . . . . . 4-15
4.4.2.4 DY Get Characteristics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-16
4.4.3
MSCP (DU) Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-17
4.4.3.1 DU Logical Read and Write . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-17
4.4.3.2 DU Get Characteristics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-18
4.4.4
Extended Disk (XD) Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-18
4.4.4.1 XD Logical Read and Write . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-18
4.4.4.2 XD Get Characteristics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-19
4.4.5
TU58 (DD) Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-20
4.4.5.1 DD Logical Read and Write . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-20
4.4.5.2 . DD Physical Read and Write . . . . . . . . .' . . . . . . . . . . . . . . . . . . . . 4-21
4.4.5.3 DD Get Characteristics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-22

4.4.6

4.5
4.6
4.7
4.8

Virtual Memory (VM) Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-23
4.4.6.1 VM Logical Read and Write . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-23
4.4.6.2 VM Get Characteristics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-23
Status Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-24
Extended Error Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-26
Disk Driver Prefix Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-26
Extended Disk Driver Source Excerpt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-30

Chapter 5
5 .1
5.2
5.3

5.4
5.5

5.6
5. 7

MU Driver Features and Capabilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-1
Performing TMSCP Tape I/O . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-2
Pascal Support Routine Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-4
5.3.1
READ_TAPE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-5
5.3.2
WRITE_TAPE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-5
5.3.3
REPOSITION_TAPE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-6
5.3.4
WRITE_TAPE_MARK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-7
5.3.5
REWIND_TAPE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-7
Pascal I/O Procedure Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-8
Request/Reply Packet Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-9
5.5.1
Read and Write Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-11
5.5.2
Get Characteristics Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-12
5.5.3
Reposition Tape Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-12
5.5.4
Write Tape Mark Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-13
5.5.5
Rewind Tape Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-13
Status Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-14
MU Driver Prefix File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-15

Chapter 6
6.1
6.2
6.3
6.4

TMSCP Tape Driver

Parallel Line Drivers

Parallel Line Driver Features and Capabilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-2
Performing Parallel I/O . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-3
Pascal I/O Procedure Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-5
Pascal Support Routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-7
6.4.1
SBC-11/21 PIO Support Routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-8
6.4.1.1 SET_pIQ_MQDE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-8
6.4.1.2 WRITE_pIQ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-8
6.4.1.3 READ_pIQ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-9

6.4.2

6.5

6.6
6.7
6.8

KXTl 1-CA/KXJll-CA PIO and Counter/Timer Support Routines . . . . . . . . . 6-9
6.4.2.1 YK_PORT_READ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-10
6.4.2.2 YK_pORT_WRITE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-11
6.4.2.3 YK_SET_PATTERN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-12
6.4.2.4 KXTll-CA/KXJll-CA PIO DMA Process . . . . . . . ; . . . . . . . . . . . . . 6-15
6.4.2.5 YK_SET_TIMER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-19
6.4.2.6 YK__READ_TIMER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-20
6.4.2.7 YK_CLEAR_TIMER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-21
6.4.2.8 Using Timer/Counters to Count External Pulses . . . . . . . . . . . . . . . . . 6-21
6.4.2.9 Linking Two Timer/Counters as 32-Bit Counter . . . . . . . . . . . . . . . . . 6-24
Request/Reply Packet Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-25
6.5.1
DRVl 1-J (XA) Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-2~
6.5.1.1 XA Read and Write . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-29
6.5.1.2 XA Get Characteristics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-30
6.5.1.3 XA Enable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-30
6.5.1.4 XA Disable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-31
6.5.2
DRVll (YA) Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-31
6.5.2.1 YA Read and Write . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-31
6.5.2.2 YA Get Characteristics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-32
6.5.3
DRVll-B (YB) Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-33
6.5.3.1 YB Read and Write . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-33
6.5.3.2 YB Set Characteristics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-35
6.5.3.3 YB Get Characteristics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-36
6.5.4
SBC-11/21 PIO (YF) Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-36
6.5.4.1 YF Read and Write . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-36
6.5.4.2 YF Get Characteristics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-37
6.5.5
KXTl 1-CA/KXJll-CA PIO (YK) Functions . . . . . . . . . . . . . . . . . . . . . . . 6-38
6.5.5.1 YK Read . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-38
6.5.5.2 YK Write . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-38
6.5.5.3 YK Get Characteristics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-39
6.5.5.4 YK Set Pattern . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-40
6.5.5.5 YK DMA Read, Write, and Complete . . . . . . . . . . . . . . . . . . . . . . . . 6-41
6.5.5.6 YK Set Timer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-42
6.5.5.7 YK Clear Timer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-43
6.5.5.8 YK Read Timer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-43
Status Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-43
Extended Error Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-44
Parallel Line Driver Prefix Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-45
6.8.1
XA Prefix File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .... 6-45
6.8.2
YA Prefix File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .· .. 6-46

6.8.3
6.8.4
6.8.5

YB Prefix File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-47
YF Prefix File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-48
YK Prefix File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-50

Chapter 7 Analog-to-Digital Converter Driver
7.1
7.2
7.3
7.4

7.5

7.6
7.7

Driver Features and Capabilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-1
Performing Analog-to-Digital Conversions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-2
Pascal I/O Procedure Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-3
Pascal Support Routine Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-4
7.4.1
SET_ANALOG_MODE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-5
7.4.2
READ_ANALOG_SIGNAL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-7
7.4.3
WRITE_ANALOG_WAIT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-8
Request/Reply Packet Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-8
7.5.1
Set Characteristics (Configure Device) Function . . . . . . . . . . . . . . . . . . . . . 7-11
7.5.2
Read Logical (Read Converted Data) Function . . . . . . . . . . . . . . . . . . . . . 7-13
7.5.3
Get Characteristics Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-14
Status Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-15
AD Driver Prefix File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-15

Chapter 8
8.1
8.2
8.3

8.4

8.5
8.6

Real-Time Clock Driver

KW Driver Features and Capabilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-1
Performing Real-Time Clock I/O . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-2
Pascal Support Routine Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-3
8.3.1
READ_COUNTS_WAIT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-3
8.3.2
READ_COUNTS_SIGNAL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-6
8.3.3
START__RTCLOCK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-8
8.3.4
STOP__RTCLOCK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-10
Request/Reply Packet Interface . . . . . . . . . . , . . . . . . . . . . . . . . . . . . . . . . . . . . 8-10
8.4.1
Read Physical Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-13
8.4.2
Enable Clock Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-15
8.4.3
Disable Clock Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ... 8-17
8.4.4
Get Characteristics Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ... 8-17
Status Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-18
KW Driver Prefix File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-18

vii

Chapter 9
9.1
9.2
9 .3

9.4

9.5
9.6

QD Driver Features and Capabilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-1
Performing KXTll-CA/KXJll-CA DMA 1/0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-2
Pascal Support Routine Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-3
9.3.1
$DMA_TRANSFER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-4
9.3.2
$DMA_SEARCH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-6
9.3.3
$DMA_SEARCH_TRANSFER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-7
9.3.4
KXTl 1-CA/KXJll-CA PIO with DMA . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-8
9.3.5
KXTl 1-CA/KXJll-CA 1/0 Using SLU2A or SLU2B with DMA . . . . . . . . . . . 9-8
9.3.6
$DMA_GET_STATUS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-9
9.3.7
$DMA_ALLOCATE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-11
9.3.8
$DMA_DEALLOCATE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-11
9.3.9
KXTll-CA/KXJll-CA DMA Sample Program . . . . . . . . . . . . . . . . . . . . . 9-11
Request/Reply Packet Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ,· . . . . . . . 9-14
9.4.1
Read and Write Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-16
9.4.2
KXTll-CA/KXJll-CA PIO DMA Process . . . . . . . . . . . . . . . . . . . . . . . . 9-21
9.4.3
KXTl 1-CA/KXJl 1-CA IjO Using SLU2A or SLU2B with DMA . . . . . . . . . . 9-22
9.4.4
Get Characteristics Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-22
9.4.5
Channel Allocation and Deallocation . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-24
Status Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-25
QD Driver Prefix File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-26

Chapter 10
10.1
10.2
10.3
10.4

Peripheral Processor OMA Driver

Instrument Bus Driver

Instrument Bus Features and Capabilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-1
Driver Features and Capabilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-3
Performing Instrument Bus 1/0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-4
Pascal Support Routine Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-5
10.4.1
READ_IEQ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-6
10.4.2 WRITE_JEQ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-7
10.4.3
SET_STATE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-8
10.4.4 WRITE_EOI_IEQ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-9
10.4.5 JEQ_COMMAND . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-10
10.4.6 IEQ _SERIAL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-11
10.4.7 JEQ_PARALLEL_POLL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-12
10.4.8 JEQ_pARALLEL_LOAD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-13
10.4.9 IEQ _PARALLEL _CONFIG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-13
10.4.10 IEQ_AUX_COMMAND . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-14
10.4.11 IEQ-1{EQ_SERVICE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-15
10.4.12 JEQ_CONTROL_GTS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-16
10.4.13 JEQ _PASS-CONTROL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-17

viii

10.5

10.6
10.7
10.8

10.4.14 SET_INT_MASK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-17
10.4.15 REC_IEQ_EVENT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-18
Request/Reply Packet Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-20
10 .5 .1
Read Logical Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-23
10.5.2 Write and Write with EOI Termination Functions . . . . . . . . . . . . . . . . . . 10-24
10.5.3 Get Characteristics (Sense State) Function . . . . . . . . . . . . . . . . . . . . . . . 10-25
10.5.4 Set Characteristics (Set State) Function . . . . . . . . . . . . . . . . . . . . . . . . . 10-25
10.5.5 Write IEEE Remote Messages Function . . . . . . . . . . . . . . . . . . . . . . . . . 10-27
10.5.6 Serial Poll Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-28
10.5.7 Parallel Poll Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-29
10.5.8 Load Parallel Poll Register Function . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-29
10.5.9 Parallel Poll Configure Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-30
10.5.10 Auxilary Command Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-31
10.5.11 Request Service Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-32
10.5.12 Get Control Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-32
10.5.13 Go to Standby Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-33
10.5.14 Pass Control Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-33
10.5.15 Set Event Mask Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-34
10.5.16 Wait for Event and Recognize Event Functions . . . . . . . . . . . . . . . . . . . . 10-35
Status Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ; . . . . . . . . . . . . . . . . . 10-37
Extended Error Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-38
XE Driver Prefix File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-38

Chapter 1 1 Network Service Process
11.1
11.2
11.3
11.4

11.5
11.6
11.7

NSP Features and Capabilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-1
Accessing the NSP for Task-to-Task Communication . . . . . . . . . . . . . . . . . . . . . . . 11-2
Pascal File System Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-4
NSP Set and Get Characteristics Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-4
11.4.1
Set Characteristics to $SECTL Queue Semaphore . . . . . . . . . . . . . . . . . . . 11-4
11.4.2 Get Characteristics to $SECTL Queue Semaphore . . . . . . . . . . . . . . . . . . . 11-5
11.4.3 Get Characteristics to File Variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-6
Status Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-6
NSP Prefix File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-8
Sample Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-11
11.7.1
Transferring Data Between Two MicroPower/Pascal Nodes . . . . . . . . . . . . 11-11
11.7.2 Transferring Data Between MicroPower/Pascaf and VAX/VMS Nodes . . . . . 11-13
11.7.3 Determining and Setting the Local Node Number . . . . . . . . . . . . . . . . . . 11-15

Chapter 12
12.1
12.2
12.3
12.4

12.5
12.6

CS Driver Features and Capabilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-2
Performing Asynchronous DDCMP I/O . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-3
Pascal 'I/O Procedure Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-6
Request/Reply Packet Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-8
12.4.1
Enable Protocol and Disable Protocol Functions . . . . . . . . . . . . . . . . . . . 12-11
12.4.2 Read and Write Functions . . . . . . . . . . . . . . . . .' . . . . . . . . . . . . . . . . 12-11
12.4.3 Get Characteristics Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-12
Status Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-13
CS Driver Prefix File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-13

Chapter 13
13.1

13.2
13.3
13.4

13.5
13.6

Asynchronous DDCMP Driver

Communication Drivers

Communication Driver Features and Capabilities . . . . . . . . . . . . . . . . . . . . . . . . . . 13-2
13.1.1
Ethernet Communication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-3
13.1.2 Synchronous Point-to-Point Communication . . . . . . . . . . . . . . . . . . . . . . . 13-4
13.1.3 Peripheral Processor Two-Port RAM Communication . . . . . . . . . . . . . . . . . 13-5
Performing Communication Device I/O . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-6
Pascal I/O Procedure Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-10
Request/Reply Packet Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-11
13.4.1
DEQNA (QN) Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-15
_13.4.1.1 QN Enable Portal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-15
13.4.1.2 QN Read and Write . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-16
13.4.1.3 QN Get Characteristics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-18
13.4.1.4 QN Disable Portal . . . . . . . . . . . . . . . . . , . . . . . . . . . . . . . . . . . 13-18
13.4.2 DPVll and KXTll-CA/KXJll-CA Synchronous Communication (XP and XS)
Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-19
13.4.2.1 XP or XS Enable and Disable . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-19
13.4.2.2 XP or XS Read and Write . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-19
13.4.2.3 XP or XS Get Characteristics . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-20
13.4.2.4 XP or XS Stop . . . . . . . . . . . . . . . . . . . . . . . . . . . .· . . . . . . . . . 13-2i
13.4.2.5 XP or XS Set Modem Semaphore . . . . . . . . . . . . . . . . . . . . . . . . . 13-21
13.4.3 KXTll-CA/KXJll-CA Two-Port RAM (KX and KK) Functions . . . . . . . . . . 13-22
13.4.3.1 KX or KK Read and Write . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-22
13.4.3.2 KX or KK Get Characteristics . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-23
13.4.3.3 KX or KK Enable and Disable . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-24
Status Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-24
Communication Driver Prefix Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-25
13.6.1
QN Prefix File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-25
13.6.2 XP and XS Prefix Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-26
13.6.3 KX and KK Prefix Files . . . . . . . . . -. . . . . . . . . . . . . . . . . . . . . . . . . . 13-28

13.7

Peripheral Processor Communication Support Routines . . . . . . . . . . . . . . . . . . . . . 13-32
13.7.1
KX_READ_DATA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-33
13.7.2 KX_WRITE_DATA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-34
13.7.3 KK_READ_DATA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-35
13.7.4 KK_WRITE_DATA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-35

Chapter 14 Guide to Writing a Device Driver
14.1
14.2

14.3
14.4

Device Driver Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-1
Device Driver Prefix Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-3
14.2.1
Priority Assignments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-3
14.2.2 DRVCF$ Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-4
14.2.3 CTRCF$ Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-5
14.2.4 Sample Driver Prefix Module (DYPFX.MAC) . . . . . . . . . . . . . . . . . . . . . . 14-8
Device Driver Impure-Area Definition Macro (xxISZ$) . . . . . . . . . . . . . -. . . . . . . . . 14-9
Device Driver Proper . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-10
14.4.1
Copyright Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-11
14.4.2 Module Header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-11
14.4.3 Functional Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-11
14.4.4 Declarations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-12
14.4.4.1 Local Macro Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-12
14.4.4.2 Externally Defined Symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-12
14.4.4.3 Process Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-12
14.4.4.4 Impure-Area Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-14
14.4.4.5 Pure-Area Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-14
14.4.5 Initialization Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-14
14.4.6 Controller Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-15
14.4.7 Interrupt Service Routine (ISR) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-16
14.4.8 Fork Routine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-17
14.4.9 Reply Subroutine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-17
14.4.10 Termination Procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-18
14.4.11 Error-Processing Routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-18
14.4.11.llnvalid Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-18
14.4.11.2Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-18
14.4.11.3 Drive or Controller Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-19
14 .4 .11.4 Resource Famine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-19

Chapter 15
15.1

15.2

Driver Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-1
15.1.1
ADPAR$ (Return PAR Address) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-3
15.1.2 DRMAP$ (Remap Virtual Address) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-4
15.1.3 DRPAR$ (Read Contents of PAR or PDR Register) . . . . . . . . . . . . . . . . . . 15-6
15.1.4 DRVDF$ (Define Driver Packet Symbols) . . . . . . . . . . . . . . . . . . . . . . . . . 15-7
15.1.5
DSCXW$ (Disable MMU Context Switch) . . . . . . . . . . . . . . . . . . . . . . . . 15-8
15.1.6 DWPAR$ (Write to PAR or PDR Register) . . . . . . . . . . . . . . . . . . . . . . . 15-10
15.1.7 ENCXW$ (Enable MMU Context Switch) . . . . . . . . . . . . . . . . . . . . . . . . 15-11
15.1.8
IBADR$ (Increment Byte Address and Check for PAR Tick Overflow) . . . . . 15-13
15.1.9
IWADR$ (Increment Word Address and Check for PAR Tick Overflow) .... 15-14
15.1.10 MVBYT$ (Move Byte from/to Virtual Addresses) . . . . . . . . . . . . . . . . . . . 15-15
15.1.11 MVBYU$ (Move Byte from/to Virtual Addresses from User-Mode) . . . . . . . 15-16
15.1.12 MVMAP$ (Move Word from/to Virtual Addresses in Mapped Case Only) .. 15-17
15.1.13 MVVAD$ (Move Address and PAR) . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-18
15.1.14 MVWRD$ (Move Word from/to Virtual Addresses) . . . . . . . . . . . . . . . . . 15-19
15.1.15 MVWRU$ (Move Word from/to Virtual Addresses from User-Mode) . . . . . . 15-20
15.1.16 SPL$ (Set Priority Level) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-21
15.1.17 XTAD$ (Compute Bus Extended Address) . . . . . . . . . . . . . . . . . . . . . . . 15-22
Driver Subroutines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-24
15.2.1
$BLXIO (Block Move) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-25
15.2.2
$DDEXC (Report Exception for Device Driver) . . . . . . . . . . . . . . . . . . . . 15-26
15.2.3
$DDINI (Device Driver Initialization) . . . . . . . . . . . . . . . . . . . . . . . . . . 15-27
15.2.4
$DRALR (Allocate Memory) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-28
15.2.5
$DRDSP (Deallocate Dynamic Memory) . . . . . . . . . . . . . . . . . . . . . . . . 15-29
15.2.6
$DRHIN (Initialize Heap) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-30
15.2.7 $DRNEW (Allocate Dynamic Memory) . . . . . . . . . . . . . . . . . . . . . . . . . 15-31
15.2.8
$DRPLY (Send Device Driver Reply) . . . . . . . . . . . . . . . . . . . . . . . . . . 15-32
15.2.9
$SV02, $SV03, and $SV05 (Save/Restore Registers) . . . . . . . . . . . . . . . . . 15-33

Appendix A
A.1

A.2

Device Driver Macros and Subroutines

Directory Structure and File Storage

Structure of a Random-Access Device . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-1
A.1.1
Home Block . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-2
A.1.2
Directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-4
A.1.2.1 Directory Segment Header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-5
A.1.2.2 Directory Entry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-6
A.1.2.3 Extended Directory Entry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-8
A.1.2.4 End-of-Segment Marker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-8
Directory Use . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-9
A.2.1
Sample Directory Segment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-9

xii

A.2.2
A.2.3
A.2.4
A.2.5

Splitting a Directory Segment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-12
File Storage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-16
Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-16
Size and Number of Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-18

Appendix B KXTl 1-CA and KXJl 1-CA Peripheral Processors
B.1

B.2

B.3

KXTll-CA/KXJll-CA Hardware and Applications . . . . . . . . . . . . . . . . . . . . . . . . . B-1
B.1.1
KXTll-CA Hardware Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-3
B.1.2
KXJll-CA Hardware Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-4
B.1.3
Using the KXTl 1-CA or KXJl l-CA as a Peripheral Processor . . . . . . . . . . . . B-6
B.1.3.1 Peripheral Processor Hardware Configuration . . . . . . . . . . . . . . . . . . . B-8
B.1.3.2 Peripheral Processor Application Software Configuration . . . . . . . . . . . . B-8
Developing KXTll-CA and KXJll-CA Applications . . . . . . . . . . . . . . . . . . . . . . . . . B-9
B.2.1
Partitioning the Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-9
B.2.2
Designing the Peripheral Processor Application System . . . . . . . . . . . . . . . . . B-9
B.2.3
Software and Hardware Configuration Guidelines . . . . . . . . . . . . . . . . . . . B-10
B.2.3.1 Configuring Memory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-10
B.2.3.2 Memory Configuration Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-11
B.2.3.3 Memory Selection Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-12
B.2.4
Configuring the KXTll-CA or KXJll-CA System Environment . . . . . . . . . . B-13
B.2.4.1 Selecting Stand-Alone or Peripheral Processor Operation . . . . . . . . . . . B-13
B.2.4.2 Selecting KXTll-CA or KXJll-CA Initialization and Self-Test Options .. B-14
KX/KK Device Driver Communication Protocol . . . . . . . . . . . . . . . . . . . . . . . . ... B-19
B.3.1
Communication Mechanisms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-19
B.3.2
KX/KK Protocol Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-22
B.3.2.1 KX and KK Driver Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . B-23
B.3.2.2 Message Communication Between the KX and KK Drivers . . . . . . . . . . B-25
B.3.2.3 Synchronizing KX and KK Device Driver Operations . . . . . . . . . . . . . . B-26
B.3.3
Command Register Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-27
B.3.3.1 Command Field (KC.COM) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-27
B3.3.2 Interrupt-When-Data-Available Bit (KC.IDA) . . . . . . . . . . . . . . . . . . . B-29
B.3.3.3 Interrupt-When-Data-Requested Bit (KC.IDR) . . . . . . . . . . . . . . . . . . . B-30
B.3.3.4 Data Length Field (KC.LEN) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-30
B.3.3.5 End-of-Message Bit (KC.EOM) . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-30
B.3.3.6 Vector Number Field (KC.VEC) . . . . . . . . . . . . . . . . . . . . . . . . . . . B-30
B.3.4
Status Register Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-30
B.3.4.1 Error Code Field (KS.ERC) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-31
B.3.4.2 Data-Requested Bit (KS.DR) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-31
B.3.4.3 End-of-Message Bit (KS.EOM) . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-31
B.3.4.4 Data-Available Bit (KS.DA) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-32
B.3.4.5 Actual Length Field (KS.ALN) . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-32

xiii

B.4
B.5
B.6
B. 7
B.8

B.9
B.10

B.3.4.6 Interrupt-Enabled Bit (KS.IEN) . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-32
B.3.4.7 Interface-Ready Bit (KS.ON) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-32
B.3.4.8 Cumulative-Error Bit (KS.ERR) . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-32
B.3.5
Interface Initialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-32
KXTl 1-CA and KXJl 1-CA CSR and Vector Assignments . . . . . . . . . . . . . . . . . . . . B-33
System ID Switch Positions, Two-Port RAM CSR and Vector Assignments . . . . . . . . . B-35
Sample MicroPower/Pascal Configuration File . . . . . . . . . . . . . . . . . . . . . . . . . . . B-37
Sample Configuration Files for the KXJll-CA . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-40
Shared Memory on a KXJ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-52
B.8.1
KXJ_ENABLE_SHARED . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-53
B.8.2
KXJ_DISABLE_SHARED . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-54
B.8.3
Arbiter and KXJ Configuration Files and Applications . . . . . . . . . . . . . . . . . B-54
Calculating Checksums for PROMS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-65
Load Application onto KXTll-CA/KXJll-CA Procedure . . . . . . . . . . . . . . . . . . . . . B-66
B.10.1
.MIM File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-66
B.10.2 User's Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-66
B.10.3 Program Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . -. ..... B-67

Appendix C
C.1

C.2

XL Serial Line Driver

PDP-11 XL Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-1
C.1.1
Functions Provided . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-3
C.1.1.1 Read Function. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-3
C.1.1.2 Write Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-3
C.1.1.3 Connect Receive Ring Buffer Function . . . . . . . . . . . . . . . . . . . . . . . C-4
C.1.1.4 Disconnect Receive Ring Buffer Function . . . . . . . . . . . . . . . . . . . . . C-4
C.1.1.5 Connect Transmit Ring Buffer Function . . . . . . . . . . . . . . . . . . . . . . C-4
C.1.1.6 Disconnect Transmit Ring Buffer Function. . . . . . . . . . . . . . . . . . . . . C-4
C.1.1.7 Report Data-Set Status Change Function. . . . . . . . . . . . . . . . . . . . . . C-4
C.1.1.8 Set Status Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-5
C.1.1.9 Get Status Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-5
C.1.1.10 Device-Independent Function Modifiers . . . . . . . . . . . . . . . . . . . . . . C-5
C.1.2
Function-Dependent Request Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . C-5
C.1.2.1 Block-Mode Read or Write Functions . . . . . . . . . . . . . . . . . . . . . . . . C-6
C.1.2.2 Connect Receive or Transmit Ring Buffer Functions . . . . . . . . . . . . . . . C-6
C.1.2.3 Disconnect Receive or Transmit Ring Buffer Functions . . . . . . . . . . . . . C-7
C.1.2.4 Set Status Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-7
C.1.2.5 Get Status Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-10
C.1.2.6 Report Data-Set Status Change Function . . . . . . . . . . . . . . . . . . . . . . C-11
C.1.3
Status Codes . . . . . . . . . . . . . . . . . . . . . . . . ._. . . . . . . . . . . . . . . . . . C-12
C.1.4
PDP-11 XL Prefix File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-12
Peripheral Processor XL Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-17

xiv

C.2.1

Functions Provided . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-18
C.2.1.1 Read Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-19
C.2.1.2 Write Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-19
C.2.1.3 Connect Receive Ring Buffer Function . . . . . . . . . . . . . . . . . . . . . . . C-19
C.2.1.4 Disconnect Receive Ring Buffer Function . . . . . . . . . . . . . . . . . . . . . C-19
C.2.1.5 Connect Transmit Ring Buffer Function . . . . . . . . . . . . . . . . . . . . . . C-19
C.2.1.6 Disconnect Transmit Ring Buffer Function . . . . . . . . . . . . . . . . . . . . . C-20
C.2.1.7 Set Status Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-20
C.2.1.8 Get Status Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-20
C.2.1.9 Report data-set status change function . . . . . . . . . . . . . . . . . . . . . . . C-20
C.2.1.10 Device-Independent Function Modifiers . . . . . . . . . . . . . . . . . . . . . . C-20
C.2.2
Function-Dependent Request Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . C-20
C.2.2.1 Block-Mode Read or Write Functions . . . . . . . . . . . . . . . . . . . . . . . . C-21
C.2.2.2 Connect Receive or Transmit Ring Buffer Functions . . . . . . . . . . . . . . . C-21
C.2.2.3 Disconnect Receive or Transmit Ring Buffer Functions . . . . . . . . . . . . . C-22
C.2.2.4 Set Status Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-22
C.2.2.5 Get Status Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-25
C.2.2.6 Report Data-Set Status Change Function . . . . . . . . . . . . . . . . . . . . . . C-28
C.2.3
Status Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-28
C.2.4
KXTl 1-CA XL Prefix File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-28

Appendix D Sample MACRO- 11 Device Driver
Index
Figures
1-1
2-1
3-1
4-1
4-2
4-3
4-4
4-5
4-6
5-1
6-1
6-2
6-3
6-4

General I/O Packet Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-12
ACP Prefix File (ACPPFX.MAC) Excerpt . . . . . . . . . . . . . . . . . . . . . . . . . . 2-10
TT Driver Prefix File (TTPFX.MAC) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-18
RL01/RL02 Driver Prefix File (DLPFX.MAC) . . . . . . . . . . . . . . . . . . . . . . . 4-27
RX02 Driver Prefix File (DYPFX.MAC) . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-28
MSCP Disk-Class Driver Prefix File (DUPFX.MAC) . . . . . . . . . . . . . . . . . . . 4-28
TU58 Driver Prefix File (DDPFX.MAC) . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-29
Virtual Memory Driver Prefix File (VMPFX.MAC) . . . . . . . . . . . . . . . . . . . . 4-30
Extended Disk Driver Source File (XDDRV.PAS) Excerpt . . . . . . . . . . . . . . . . 4-31
TMSCP Tape Driver Prefix File (MUPFX.MAC) . . . . . . . . . . . . . . . . . . . . . . 5-15
KXTll-CA/KXJll-CA PIO DMA Sample Program . . . . . . . . . . . . . . . . . . . 6-16
YK Prefix File for PIO DMA Sample Program . . . . . . . . . . . . . . . . . . . . . . 6-18
KXTll-CA/KXJll-CA External Pulse Counter Sample Program . . . . . . . . . . . 6-22
YK Prefix File for External Pulse Counter Sample Program . . . . . . . . . . . . . . 6-23

6-5
6-6
6-7
6-8
6-9
6-10
7-1
8-1
9-1
9-2
10-1
11-1
12-1
13-1
13-2
13-3
13-4
13-5
A-1
A-2
A-3
A-4
A-5
A-6
A-7
A-8
A-9
A-10
A-11
A-12
A-13
A-14
A-15
A-16
A-17
B-1
B-2
B-3
B-4
B-5
B-6
B-7

KXTll-CA 32-Bit Counter Sample Program . . . . . . . . . . . . . . . . . . . . . . . . 6-24
DRVl 1-J Driver Prefix File (XAPFX.MAC) . . . . . . . . . . . . . . . . . . . . . . . . . 6-46
DRVll Driver Prefix File (YAPFX.PAS) . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-47
DRVll-B Driver Prefix File (YBPFX.MAC) Excerpt . . . . . . . . . . . . . . . . . . . 6-49
SBC-11/21 PIO Driver Prefix File (YFPFX.MAC) . . . . . . . . . . . . . . . . . . . . . 6-50
KXTl 1-CA/KXJll-CA PIO Driver Prefix File (YKPFX.MAC) . . . . . . . . . . . . . 6-59
AD Driver Prefix File (ADPFX.MAC) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-16
KW Driver Prefix File (KWPFX.MAC) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-19
KXTll-CA/KXJll-CA DMA Sample Program . . . . . . . . . . . . . . . . . . . . . . 9-12
KXTl 1-CA/KXJll-CA DTC Driver Prefix File (QDPFX.MAC) . . . . . . . . . . . . 9-26
Instrument Bus Driver Prefix File (XEPFX.MAC) . . . . . . . . . . . . . . . . . . . . 10-39
NSP Prefix File (NSPPFX.MAC) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-10
CS Driver Prefix File (CSPFX.MAC) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-15
DEQNA Driver Prefix File (QNPFX.MAC) . . . . . . . . . . . . . . . . . . . . . . . . 13-26
DPVl 1 Driver Prefix File (XPPFX.MAC) . . . . . . . . . . . . . . . . . . . . . . . . . 13-27
KXTl 1-CA/KXJll-CA Synchronous Serial Driver Prefix File (XSPFX.MAC) .. 13-28
KXTll-CA/KXJl 1-CA Two-Port RAM Driver Prefix File (KXPFX.MAC) ..... 13-31
KXTl 1-CA/KXJll-CA Two-Port RAM Driver Prefix File (KKPFX.MAC) ..... 13-32
Format of Random-Access Device . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-2
Format of Home Block . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-3
Format of Directory Segment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-4
Format of Directory Entry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-6
Format of Status Word . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-6
Format of Date Word . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-8
Directory Listing . ' . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-9
Directory Segment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-10
Storing a New File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-12
Full Directory. Segment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-13
Directory Before Splitting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-14
Directory After Splitting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-15
Directory Links . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-16
Random-Access Device with Two Permanent Files . . . . . . . . . . . . . . . . . . . A-17
Random-Access Device with One Tentative File . . . . . . . . . . . . . . . . . . . . . A-17
Random-Access Device with Two Tentative Files . . . . . . . . . . . . . . . . . . . . A-17
Random-Access Device with Four Permanent Files . . . . . . . . . . . . . . . . . . . A-18
KXTl 1-CA Hardware Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-3
KXJl 1-CA Hardware Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-5
Adding Peripheral Processors to Traditional LSI-11 Systems . . . . . . . . . . . . . . B-7
Peripheral Processor Application Software Configuration . . . . . . . . . . . . . . . . B-8
KXTl 1-CA Memory Map Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . B-11
KX/KK Device Driver Communication Linkage . . . . . . . . . . . . . . . . . . . . . • B-20
TPR Register Layout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-21

xvi

C-1
C-2

XL Driver Prefix File (XLPFX.MAC) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-16
KXTll-CA XL Driver Prefix File (XLPFXK.MAC) . . . . . . . . . . . . . . . . . . . . . C-30

Tables
1-1
12-1
13-1
13-2
13-3
A-1
B-1
B-2
B-3

Request Queue Names, Units, and Unit Numbering . . . . . . . . . . . . . . . . . . . 1-9
Asynchronous DDCMP I/O Paths and Interfaces . . . . . . . . . . . . . . . . . . . . 12-6
Communication I/O Paths and Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . 13-9
Two-Port RAM Data Channel Addresses . . . . . . . . . . . . . . . . . . . . . . . . 13-29
KX Prefix File Defaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-29
Contents of Home Block . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-3
MicroPower/Pascal Usage of KXTll-CA Memory Maps . . . . . . . . . . . . . . . B-12
Initialization/Self-Test Options for the KXTl 1-CA . . . . . . . . . . . . . . . . . . . B-15
Initialization/Self-Test Options for the KXJll-CA . . . . . . . . . . . . . . . . . . . B-16

xvii

Preface

Intended Audience
This manual describes the MicroPower/Pascal 1/0 system and the run-time 1/0 services it
provides for user programs. The content of this manual is based on the assumption that
you are familiar with either Pascal or MACR0-11. All MicroPower/Pascal microcomputer
software development is done with one or both of those development languages. Additional
reference information for performing run-time 1/0 in Pascal is contained in Chapter 9 of the

MicroPower /Pascal Language Guide.

Structure of This Document
Fifteen chapters and four appendixes make up this manual:
•

Chapter 1 presents an overview of the MicroPower/Pascal 1/0 services. The chapter lists
supported devices and protocols, summarizes the 1/0 system components, mechanisms, and
interfaces, and describes the request/reply packet interface to the DIGITAL-supplied device
drivers.

•

Chapters 2 through 13 describe the DIGITAL-supplied system processes that provide 1/0
services ("1/0 servers"). Chapters 2, 11, and 12 describe the ancillary control process (ACP),
the network service process (NSP), and the asynchronous DDCMP protocol driver-that is,
the 1/0 system components that are layered above the device drivers. Chapter 3 describes
the asynchronous serial line (terminal) driver, Chapters 4 and 5 the mass-storage device
drivers (disk and tape), Chapters 6 through 10 the real-time device drivers (PIO, A/D,
DMA, instrument bus), and Chapter 13 the communication device drivers.
Chapters 2 through 13 describe features and capabilities, application building considerations,
user interfaces, completion-status codes, and prefix files for each DIGITAL-supplied 1/0
server.

•

Chapter 14 presents guidelines for writing a MicroPower/Pascal device driver for nonstandard hardware devices-devices not supported by the drivers in the MicroPower /Pascal
distribution kit. The chapter describes the necessary components of a device driver and
the driver's interface to the application program and refers to sample drivers written in
MACR0-11 (DY driver) and Pascal (YA driver).

xix

•

Chapter 15 describes macros and subroutines that can be used by device drivers written in
MACR0-11.

•

Appendix A describes the RT-11-compatible directory structure optionally supported by the
MicroPower/Pascal ACP and discusses file storage.

•

Appendix B presents information on developing applications for the KXTl 1-CA or KXJl 1-CA
peripheral processor.

•

Appendix C describes the XL serial line driver, which is included on the MicroPower/Pascal
distribution kit for existing applications that require it.

•

Appendix D lists the source code for a sample MACR0-11 device driver-the RX02 (DY)
driver.

Associated Documents
The following software documentation is required for complete reference purposes:
•

MicroPower/Pascal document set

•

Standard documentation for your host operating system

You will also need the following hardware reference documents to correctly configure your
target (application) hardware, to use the standard device drivers, or to write device drivers that
are hardware- and software-compatible with other system components:
•

Microcomputer handbooks, including Microcomputers and Memories (Order No. EB-2091220) and Microcomputer Interfaces Handbook (Order No. EB-23144-18)

•

SBC-11/21 Single-Board Computer User's Guide (Order No. EK-SBCOl-UG-001), required
when developing SBC-11/21 applications

•

KXT11-CA Single-Board Computer User's Guide (Order No. EK-KXTCA-UG-001), required
when developing KXTl 1-CA applications

•

KX/11-CA Single-Board Computer User's Guide (Order No. EK-KXJCA-UG), required when
developing KXJl 1-CA applications

•

LSI-11 Analog System User's Guide (Order No. EK-AXVll-46-002), required when
developing applications using the ADVll-C, AAVll-C, AXVll-C, or KWVll-C 1/0 boards

•

IEU11-A/IEQ11-A User's Guide (Order No. EK-IEUQl-UG-001), required when developing
applications using IEQl 1-A instrument bus hardware

•

DPVl 1 Serial Synchronous Interface Technical Manual (Order No. EK-DPVl 1-TM), required
when developing applications using DPVl 1 communication hardware

•

Peripheral Processor Tool Kit-RT Reference Manual (Order No. AA-AU63C-TC), Peripheral
Processor Software Tool Kit-RSX Reference Manual (Order No. AA-AU64C-TC), or Peripheral
Processor Tool Kit-Micro VMS Reference Manual (Order No. AA-HX84A-TE) required when
using the KUI utility program to load peripheral processor applications from RT-11, RSX-11,
or MicroVMS arbiters

•

VAX/VMS DECprom User's Guide (Order No. AA-W754A-TK), required when using the
VMS DECprom program to calculate and program ROM checksums for KXTl 1-CA or
KXJl 1-CA applications

•

Additional hardware documentation for microcomputer hardware presently not covered in
the microcomputer handbooks

Conventions Used in This Document
1.

Pascal-reserved words that must not be abbreviated are shown in uppercase characters
in syntax examples. Within those examples, lowercase characters are used for variable
parameters (or other syntax elements) that you may choose for your application.

In some MACR0-11 syntax diagrams, optional parameters and syntax are shown within
brackets ([ ]).

Some MACR0-11 syntax examples are shown with long macro invocations continued on
a second line-for example, the CRPC$ and DFSPC$ macro calls. However, when writing
source code in MACR0-11, you must keep each macro invocation on a single line.

This manual uses "MPBUILD" as a generic term for the VMS, RSX, and RT versions of the
MicroPower/Pascal automated build procedure. Note that the name of the RT-host version
of the procedure is "MPBLD," not "MPBUILD."

Symbols

The numeric values given in this manual for symbols for data structure sizes, offsets, and so
forth, are subject to change. Therefore, use symbol names rather than numeric values for
components of packets and other system data structures.

xxi

Chapter 1
Introduction to MicroPower/Pascal Input/Output
This chapter provides an overview of MicroPower/Pascal input/output (1/0) services. The
1/0 services include device 1/0, task-to-task communication, and Pascal file system operations,
including optional RT-11 directory support for disk-class devices. Those services are provided
at run time by the MicroPower/Pascal 1/0 system, consisting of DIGITAL-supplied system
processes (called "1/0 service processes" or "1/0 servers") and the Pascal Object Time System
(OTS). The 1/0 services allow a MicroPower/Pascal program to input data from and output data
to devices or tasks that are external to the target processor, using normal Pascal IjO statements
or DIGITAL-supplied Pascal support routines.

Note
The MicroPower /Pascal Run-Time Services Manual describes run-time services
that are provided by the MicroPower/Pascal kernel. Those services include
the kernel facilities for interprocess communication (send/receive) and setup of
interrupt vectoring (connect-to-interrupt) that are basic to MicroPower /Pascal
IjO.
The MicroPower/Pascal 1/0 service processes support IfO on mass-storage devices, real-time
devices, and communication devices.

Introduction to MicroPower /Pascal Input/Output 1-1

The supported mass-storage devices and protocols, listed by server, are:

Server

Devices /Protocols

DL driver

RLVll controller, RLOl disk (16/18-bit addressing)
RLV12 controller, RL01/RL02 disks (16/18/22-bit addressing)
RLV21 controller, RL01/RL02 disks (16/18-bit addressing)

DY driver

RXV21 controller, RX02 flexible diskettes (single/ double density, 18-bit
addressing)

DU driver

Mass Storage Control Protocol (MSCP) controllers and disks, including
RQDXl, RQDX2, and RQDX3 controllers and RX50, RD51, RD52, RD53,
and RC25 disks (22-bit Q-bus environment)

XD driver

Extended (> 65536 blocks) physical disks, partitioned for Pascal 1/0

DD driver

TU58 DECtape II connected to DLV or either KXTl 1-CA or KXJl 1-CA
serial line interface unit

VM driver

Virtual memory (mapped systems only, requires MMU)

MU driver

TMSCP tapes, including TK50 streaming cartridge tape

The supported real-time devices and protocols, listed by server, are:

Server

Devices /Protocols

XA driver

DRVl 1-J 64-bit parallel interface (four 16-bit ports)

YA driver

DRVl 1 16-bit parallel interface

YB driver

DRVl 1-B DMA interface

YF driver

SBC-11/21 8255 PIO interface

YK driver

KXTl 1-CA or KXJl 1-CA
8-bit parallel ports (16-bit if linked)
4-bit special-purpose 1/0 port
16-bit counter/timers

AD driver

ADVl 1-C and AXVl 1-C A/D converter boards

KW driver

KWVl 1-C programmable real-time clock

QD driver

KXTl 1-CA or KXJl 1-CA 2-channel direct transfer controller (DTC)

XE driver

IEQl 1-A instrument bus interface

1-2 Introduction to MicroPower /Pascal Input/Output

The supported communication devices and protocols, listed by server, are:

Server

Devices /Protocols

TT driver

Asynchronous serial (terminal) lines, including DLVll-type (DLVll,
DLVll-E, DLVll-F, DLVll-J), DLART-type (KXTll-CA or KXJll-CA
console, SBC-11/21, CMR21, MXVll-A, MXVll-B), DZVll, DHVll,
KXTl 1-CA or KXJll-CA multiprotocol chip

CS driver

DDCMP over asynchronous serial lines (usable as base for DECnet)

QN driver

DEQNA Ethernet interface, Ethernet data link protocol (usable as base
for DECnet)

XP driver

DPVl 1 synchronous serial line interface, bit-synchronous mode (usable
as base for bit-oriented protocol, such as HDLC or LAPB)

XS driver

KXTl 1-CA or KXJll-CA synchronous serial line interface (usable as base
for bit-oriented protocol)

KK driver

KXTl 1-CA or KXJl 1-CA two-port RAM, peripheral processor side of
two-port RAM protocol

KX driver

KXTl 1-CA or KXJl 1-CA two-port RAM, arbiter side of two-port RAM
protocol

The servers that are not specific to a single device or protocol-the ACP and the NSP-do
not appear above. However, the ACP supports all the OPENable devices and protocols among
those listed, and the NSP supports all listed communication devices and protocols (including,
indirectly, TT).

1. l 1/0 System Architecture
The MicroPower/Pascal 1/0 system has the following components:
•

Pascal/file system OTS

•

Ancillary control process (ACP)

•

Network service process (NSP)

•

Protocol/ device drivers
Note
The required participants in a standard (driver-based) 1/0 transfer are a calling
user process, a device driver, and an appropriately set-up hardware device.
For task-to-task communication, a partner task on a remote processor is also
required. The other components-OTS, ACP, NSP, protocol driver-are layered
on the device driver (and each other) and function as intermediaries in an 1/0
transfer.

The Pascal OTS is composed of the Pascal kernel and 1/0 system interface routines. The 1/0
system interface routines reside in a separate file and are called the file system OTS. The OTS
routines are built into a user process on an as-needed basis-automatically if you build with
MPBUILD. (If building without MPBUILD, you must include the appropriate OTS libraries on
the MERGE utility command line.)

Introduction to MicroPower /Pascal Input/Output 1-3

In contrast to the OTS routines, which can be viewed as part of the user process that requests
an 1/0 service, the ACP, the NSP, and the protocolfdevice drivers are system processes,
termed 1/0 service processes or 1/0 servers. You build the required system processes into your
application by editing and assembling a system-process prefix module. That module includes
a global symbol reference that causes the appropriate system process to be merged into the
application.
The user process, the ACP, the NSP, and the drivers communicate with each other via the
kernel mechanisms for interprocess communication-the high-level (send/receive) or low-level
(signal-queue/wait-queue) queue semaphore kernel primitives.
The ACP supports file-opening operations for 1/0 devices and protocols plus standard Pascal
1/0 on disk devices. (Optionally, the ACP supports RT-11 file structure on disk devices
or opening of task-to-task links.) The ACP is called when an application program opens a
file. The open operation associates a file variable with an I/O server (a driver, the ACP for
disk operations or the NSP for task-to-task operations), making it possible to perform normal
device-independent Pascal I/O via the server. Subsequent I/0 requests go directly to the server.
The NSP supports task-to-task communication between a MicroPower/Pascal application and
an application on a remote processor. The NSP is called (by the ACP) when an application
program opens a logical link, over a physical communication link, with a remote task. The
open operation associates a file variable with an NSP logical-link server, making it possible to
perform device-independent Pascal task-to-task IjO. Subsequent I/O requests go directly to the
server.
The protocol/device drivers support I/O on a protocol or a hardware device. (The current
version of MicroPower/Pascal has only one protocol driver-for asynchronous DDCMP.) The
driver is called by the user process (that is, the OTS or alternative routines), the ACP (for
OPEN or disk I/O), or the NSP (task-to-task I/O) as necessary to complete a user-requested
IjO operation.
The device drivers normally communicate with and control the hardware by manipulating
device registers or other I/O page locations. In addition, the drivers establish hardwareinterrupt vectoring via the connect-to-interrupt kernel primitive. When a hardware device issues
an interrupt to signal completion of a transfer or to request further transfer-related processing
from the driver, control is passed to an interrupt service routine (ISR) in the driver. The
ISR performs critical processing in kernel mapping context at a high priority, then issues a
FORK$ call for less-critical processing or kernel-primitive invocation (possibly signaling' a driver
semaphore), then exits, allowing interrupted or lower-priority processing to continue.
The MicroPower/Pascal I/O system provides three basic user interfaces to I/O:
•

Pascal file system I/O (normal Pascal I/O statements)

•

Pascal support routines (independent of file system)

•

Request/reply packet I/O (send/receive)

The request/reply packet interface uses the kernel send/receive primitives to issue requests
directly to the request queue semaphore of the ACP, the NSP, or a driver. The request/reply
packet interface is the central mechanism for MicroPower/Pascal I/O and provides the basis
for the higher-level file system and support routine interfaces.

1-4 Introduction to MicroPower /Pascal Input/Output

The rest of this section summarizes the possible 1/0 request paths (user process -> device
driver)' through the 1/0 system.
Note
The following abbreviations are used in this section:
U
= User process
FSOTS

= File system OTS routines

ACP

=Ancillary control process

NSP

=Network service process

=Protocol driver (CS)

= Device driver

Each arrow represents a kernel send or signal-queue operation.
The possible 1/0 request paths for Pascal OPEN operations are shown below:

+-------+

+-------+:---------------->:+-------+
+-------+
p
:
I F
:l +-------+
: D I:---> D
A
: s
I
N
I---> I
u : 0 :--->: c :--->: s :
+-------+
p
D
I T
:
:
p
: ---------------->
: s
: +-------+
+-------+ +-------+:-----------------------------> ·-------·
I
I

I
I

I
I
I

I
I
I
I
I
I

ML0-830-87

The paths shown above correspond to the following OPEN operations (x denotes a participant
in the operation):

FSOTS

ACP

NSP

Operation

OPEN of NSP /CS /TT link

OPEN of NSP /DD link

OPEN of CS /TT file

OPEN of openable DD file

The 1/0 request path for a Pascal 1/0 operation on an opened disk file is shown below:

+-------+
u

I
I
I
I
I
I
I
I
I
I
I
I
I
I

+-------+

s
0

--->

+-------+

+-------+
I
I
I
I
I
I

--->:
I

I
I
I

D
D

+-------+

+-------+
VIL0-980-87

Introduction to MicroPower /Pascal Input/Output 1-5

The possible I/O request paths for Pascal IJO operations on opened nondisk files or logical
links are shown below:

+-------+
+-------+ +-------+
:
---------------->: p :
:
i F
+-------+
i
i ---> l
l S
i
N
i ---> l
D
I
I
D
u : 0 --->:
s
:
+-------+
:
i T
i
P
:----------------> l D
: s
+-------+
:
: ----------------------------->:
+-------+
+-------+
ML0-831-87
The paths shown above correspond to the following operations (x denotes a participant in the
operation):

FSOTS

ACP

NSP

Operation

Pascal I/O on NSP /CS/TT link

Pascal I/O on NSP /DD link

Pascal 1/0 on CS/TT file

Pascal I/O on nondisk DD file

To perform nonfile I/O from a MACR0-11 program-or a Pascal program from which you
wish to exclude the FSOTS, the ACP, the NSP, and any Pascal support routines-you must
issue send requests to a driver request queue semaphore. The following operations can be
performed:

u
x

FSOTS

ACP

NSP

Operation

CS /TT function

DD function

To perform file IJO from a MACR0-11 program-or a Pascal program from which you wish
to exclude the FSOTS-you must issue a send request to the ACP to open the file or logical
link. (If you wish to exclude the ACP for a logical link open, it is still considered a file system
operation, so you must issue an ACP-formatted send request to the NSP.) Subsequent send
requests-for read, write, and so forth-must be issued to the ACP or driver queue semaphore
identified in the reply to the open request.

1-6 Introduction to MicroPower /Pascal Input/Output

The following operations can be performed (x in parentheses denotes an optional participant in
the operation):

FSOTS

ACP

NSP

Operation

(x)

OPEN of NSP /CS/TT link

(x)

OPEN of NSP /DD link

OPEN of CS /TT file

OPEN of DD file or disk file I/O

I/O on opened NSP /CS /TT link

IjO on opened NSP /DD link

I/O on opened CS/TT file

I/O on opened nondisk DD file

x
x

Note
With regard to the ACP and NSP entries above, note that the current version
of this manual does not provide detailed descriptions of the ACP and NSP
send/receive interfaces.

1.2 Performing 1/0
For most MicroPower/Pascal applications, you perform I/O in one of two ways. You can
invoke Pascal I/O statements that open files for data and then input or output the data, in
accordance with the rules for Pascal I/O. The Pascal 1/0 procedures-OPEN, GET, WRITE,
and so forth-are described in Chapter 9 of the MicroPower /Pascal Language Guide.
For drivers that do not permit file sys~em access-for example, QD, or XE-or for which file
access is of limited usefulness-for example, MU, YK, or KW-you perform I/O by calling
DIGITAL-supplied support routines that are independent of the file system. Those routines
provide high-level nonfile access to an I/O resource. The routines typically issue Pascal SEND
requests to the request queue semaphore of a device driver. The support routines are described
in detail in Sections 5.3 (MU), 6.4 (YF /YK), 7.4 (AD), 8.3 (KW), 9.3 (QD), 10.4 (XE), and 13.7
(KX/KK).
In addition to invoking the Pascal I/O statements or support routines, you must:
1.

[For each device driver:] Edit the DEVICES macro in the system configuration file to reflect
the device interrupt vector addresses

Edit the prefix file for each required system process, as described in the prefix file sections
of Chapters 2 through 13

Build into your application the required If O system components:
•

Driver process(es)

•

[For file OPEN:] ACP

•

[For logical link OPEN:] NSP

Introduction to MicroPower /Pascal Input/Output 1-7

•

Pascal OTS routines for file service-built in automatically by MPBUILD for programs
that invoke Pascal 1/0 procedures-or nonfile-oriented support routines, plus any other
1/0 routines you opt to include (see kit files GETSET.P AS and GSINC.P AS)

For more information on setting up your application software for 1/0, see Chapter 4 of the

MicroPower /Pascal Run-Time Services Manual, the prefix file sections of Chapters 2 through 13,
and the material on building system processes in the MicroPower/Pascal system user's guide
for your host system.
The 1/0 system file system and support routine interfaces conceal from the Pascal user the basic
mechanisms of Micro Power/Pascal 1/0-the sending of request packets to 1/0 server queue
semaphores, the dispatching of interrupts, and the signaling of reply semaphores.
Note
It is possible to bypass the file system, the ACP, and any available support
routines in order to access a device driver directly. This can be accomplished
via send/receive operations to a driver's request queue semaphore.
It is also possible, given detailed knowledge of the ACP and NSP request/reply

packet interfaces, either to bypass the file system OTS in order to access the
ACP directly, or to bypass the file system OTS and the ACP to access the NSP
directly.~, However, the current version of this manual does not provide detailed
descriptions of the ACP and NSP send/receive interfaces.

1.3 Request/Reply Packet Interface
1/0 servers are system processes that accept requests for 1/0 operations from user or system
processes. DIGITAL-supplied 1/0 servers include device drivers and layered processes, such
as the protocol (DDCMP) driver, the network service process (NSP), and the ancillary control
process (ACP). The mechanism for interprocess communication is the kernel send/receive (or
lower-level signal/wait) queue semaphore facility. 1/0 requests for a device or service are
passed to the server in the form of a request message (queue packet). Each server maintains a
request queue semaphore, through which 1/0 requests are passed. The request packet supplies
all the information the server needs to perform the desired operation, including the function
code, type of reply desired, and where applicable, the unit number, device address, and databuffer location. After receiving a request, a device-level server (device driver) will perform
all process-level, interrupt-level, and fork-level processing for the requesting process; a layered
server (ACP, NSP, or protocol driver) will perform processing and give requests to other layers
as necessary to complete the operation.
When the 1/0 operation has been completed, if a full reply was requested, the server signals the
requesting process and returns a reply message packet (often a modified version of the request
packet). The reply message packet indicates completion status and other information, such as
number of bytes successfully transferred, as applicable.
This section describes the general features of the send/receive 1/0 packet interface as those
features pertain to DIGITAL-supplied drivers (see note). The device- or function-dependent
aspects of the 1/0 packet interface are covered in the individual driver descriptions in Chapters
3 through 10 and Chapters 12 and 13.

1-8

Introduction to MicroPower /Pascal Input/Output

Note
The device driver request and reply packets are described later in this section
and throughout the driver chapters. The symbols used to describe the packets
and the information they contain are MACR0-11 symbols defined by the kernel
macro DRVDF$ from the COMU /COMM kernel macro libraries. The Pascal
equivalents of those symbols are defined in IOPKTS.P AS, an include file that is
recommended for use with Pascal I/O requests.
The ACP and NSP packet-level interfaces are not documented in detail in the
current version of this manual.

1.3.1 Request Queue Names
The driver request queue semaphores have standardized, 4-character names that identify the
driver associated with the semaphore and the controller serviced by the driver. The names are
of the form $ddc:

Designator

Meaning

A driver identifier (for example, DY for RX02 or TT for terminal line)

A controller identifier (for example, A, B, C, ... -as specified in a driver
prefix file-or simply A where multiple controllers do not apply)

Thus, $DYA and $DYB would name the request queues for the first and second RX02 controllers
configured on a system, and $ TTA would name the queue for any asynchronous serial line
interface.
The request queue name must be specified in uppercase letters. Also, since device drivers
specify 6-character names, including two space characters, you should space-fill the last two
character positions in the request queue nam~ when creating the request queue.
Table 1-1 lists standard request queue names, supported hardware units, and unit numbering
for standard device drivers.
Table 1-1:

Request Queue Names, Units, and Unit Numbering

Request
Queue Name

Number
of Units

Numbering

Asynchronous
serial

$TTA

1-n (1-4 for DZVll, 18 for DHVl l, 1 for most
others)

0 through (n-1) in prefix file order, crossing controller boundaries

RLOl/2

$DLc

1-4 (any combination of
RLOls and RL02s)

In prefix file

RX02

$DYc

1-2

0 for left drive and 1 for right in
dual-drive

MSCP

$DUc

1-n

In prefix file

Driver

Introduction to MicroPower/Pascal Input/Output. 1-9

Table 1-1 (Cont.):

Request Queue Names, Units, and Unit Numbering

Driver

Request
Queue Name

Number
of Units

Extended disk

$XDc

1-n (partitions), as determined by disk size and
user-defined partition size

0 through (n-1)

TU58

$DDc

1-2

0 for left drive and 1 for right in
dual-drive

Virtual memory

$VMc

TM SCP

$MUc

DRVll-J

$XAc

[For read/write:] 1-4
[For Enable/Disable:]
1-12

0 through 3 for ports A through
D
4 through 15 for port A lines 0
through 11

DRVll

$YAA

DRVll-B

$YBc

SBC-11/21 PIO

$YFA

1-2

0 and 1 for ports A and B

KXTll-CA or
KXJl l-CA PIO

$YKA

1-6

0 through 5 for ports A through
C and timers 1 through 3

A/D converter

$ADc

Real-time clock

$KWc

0 (normally)

KXTll-CA or
KXJll-CA OMA

$QDc

1-2

0 and 1 for channels A and B

Instrument bus

$XEc

1 (per controller)

Sequentially upward from 0 in
prefix file order, crossing controller and board boundaries

DDCMP

$CSA

1-n

0 through (n-1) in prefix file
order, independently of TT unit
numbers

DEQNA

$QNc

1-4 (portals)

In prefix file

DPVll

$XPc

KXTll-CA or
$XSc
KXJl 1-CA synchronous
serial

KXTll-CA
two-port RAM

$KXc

1-2

0 and 1 in prefix file order

KXTll-CA
two-port RAM

$KKA

1-2

0 for channel 0 and 1 for channel
1

1-10 Introduction to MicroPower /Pascal Input/Output

Numbering

1.3.2 1/0 Request and Reply Packets
Figure 1-1 shows the general form of an 1/0 request packet as received by the driver and an
1/0 reply packet as received by the caller. The diagram includes the standard 6-byte header that
prefixes all packets and that is transparent to users of the send/receive-level mechanisms. (That
header is provided by the SEND$ primitive, based on kernel information and user-provided
macro arguments, when it builds the packet; it should not be included in the send or reply
buffers that are specified in the send/receive calls.)
Note that the request data consists of an 18-byte portion that is function-independent-fields
DP.FUN to DP.SEM-and a 16-byte portion that varies in content, depending on the kind of
function requested-fields DP.DAD to DP.LEN.

Note
The field names shown do not represent offsets into the send or reply buffers;
rather, they correspond to offset symbols used by the drivers to reference
packets; for example, DP.FUN is a 6-byte offset from the packet header.

Introduction to MicroPower /Pascal Input/Output 1-11

Figure 1-1:

General 1/0 Packet Formats

I/O

REQUEST
PACKET

+-----------------+
Standard

+-----------------+
Standard
I
--1
packet
I

I
I
I

packet

I
I
I

header

I/O
REPLY
PACKET

--1

header

-----------------1
Function

DP.FUN -

Function
I
I
I
I
I

DP.UNI -

Unit

DP.SEQ -

Sequence number

- DP.FUN

Unit

- DP.UNI

I
I
I
I

Sequence number

- DP.SEQ

Funcinde p
value
data

Status code

- DP.STS

Actual length

- DP.ALN

Error info

- DP.ERR

Reserved for

- DP .XTR

Requesting.

DP.PDB -

·-1

I
I
1-1
I
I

process
identifier

1----------------Reply
DP.SEM - :
I

driver

semaphore
identifier

-----------------1

I
I
I

DP.DAD -

--1
I
I

--1

Request data

:
I

--1

1--

Ref
data
info

1-----------------1
DP.LEN - I Buffer length :
+-----------------+
I

Funcdep
value
data

I
I
I

--1

address

- DP.FDD

I
I
I
I

-----------------1
Buffer
:
DP.BUF - I
I

usage

I
I

I
I
I

--1

DP.PAR - I

Reply data

Reserved

+-----------------+
ML0-832-87

1-12 Introduction to MicroPower/Pascal Input/Output

The request packet fields shown in Figure 1-1 have the following significance:

Field

Significance

DP.FUN

The 6-bit function code and the function-modifier bits that together specify the
operation to be performed. The function word is divided into three subfields,
as follows:
• Function code value in bits 0 to 5:
IF$RDP =Read Physical
IF$RDL = Read Logical
IF$WTP =Write Physical
IF$WTL = Write Logical
IF$SET =Set Characteristics
IF$GET = Get Characteristics
Other codes denote device-specific functions-for example, IF$SMD, as used
in the TT driver. See individual device-driver descriptions for device-specific
functions.
The following function codes are reserved (see Sections 2.4.5 through 2.4.7):
IF$LOK =Lookup (open)
IF$ENT =Enter (open)
IF$REN = Rename
IF$DEL = Delete
IF$CLS =Close
IF$PRG = Purge
IF$PRO =Protect
IF$UNP = Unprotect
•

Device-dependent function-modifier bits 6 to 12 (their meaning is described
separately for each driver).

• Device-independent function-modifier bit settings, for bits 13 to 15:
FM$BSM (bit 13) Set = Reply semaphore (DP.SEM) is a binary or a counting
semaphore
FM$DCK (bit 14) Set = Data check
FM$INH (bit 15) Set= Inhibit retry of soft device errors
DP.UNI

The unit number of the desired device, where applicable. (The high-order byte
of DP.UNI is reserved.) See Table 1-1 for unit-numbering information.

DP.SEQ

An optional, user-defined value, for example, a sequence number for identifying
a given request. This field is provided for the user's purposes only; it is not
used by the driver but is returned in the reply packet.

DP.PDB

The Pascal STRUCTURE_ID-type variable that identifies the requesting process
(first three words of the process descriptor block; see Section 3.1.6 of the
MicroPower /Pascal Run-Time Services Manual). This field is used for the QD
driver Allocate Channel (IF$ALL) function; see Chapter 9.

Introduction to MicroPower/Pascal Input/Output 1-13

Field

Significance

DP.SEM

The Pascal STRUCTURE-1D-type variable that identifies the user's completionreply semaphore (first three words of the structure descriptor block; see Section
3.1.5 of the MicroPower /Pascal Run-Time Services Manual). If modifier bit
FM$BSM of word DP.FUN is not set, implying a full reply, this field must
identify a queue semaphore through which a reply packet is to be sent. If
modifier bit FM$BSM is set, this field can identify either a binary or a counting
semaphore, which is signaled on request completion (whether successful or not).
If the first word of this field is zeroed, the driver takes no completion-reply
action.

DP.DAD

Interpreted according to the type of device handled and the function requested
and is unused in some cases. For logical IjO on a disk, the first two words are
interpreted as a double-word logical block number, with the least-significant part
in the first word. Other drivers either ignore this field or interpret it differently
(see the TT driver Get Characteristics request packet in Chapter 3, for example).

DP.BUF

The virtual address of the start of the user's data buffer. This word is filled in
automatically by SEND or SEND$, based on the reference-buffer parameter you
supply in the call.

DP.PAR

The page address register value that maps the user's data buffer. This value
is supplied and filled in automatically by SEND or SEND$ and is meaningful
only in a mapped environment.

DP.LEN

The amount of data to be transferred, in bytes. This word is filled in
automatically by SEND or SEND$, based on the reference-length parameter
you supply in the call.

Note
If not used for reference data information, fields DP.BUF through DP.LEN can
be used for additional value data.
Note that all drivers notify the requesting process of a request completion, if a reply semaphore
is specified in the request (DP.SEM is nonzero), by either a full reply or a done signal, as
determined by function-modifier bit FM$BSM of the function word (DP.FUN). If bit FM$BSM is
not set, a full reply (also shown above) is sent via the queue semaphore identified in DP.SEM.
If bit FM$BSM is set, the binary or the counting semaphore identified in DP.SEM is signaled on

request completion. In this case, the requesting process cannot determine whether the operation
completed successfully. If the requesting process does not desire any notification of completion,
the first word of DP.SEM must contain 0, in which case the setting of DP.FUN bit 13 is not
significant.

1-14

Introduction to MicroPower /Pascal Input/Output

The function-dependent portion of a request is described in detail for each driver in the individual
driver descriptions.
The reply message is a modified form of the request message, with the DP .FUN and DP .SEQ
fields unchanged and the following fields filled in as appropriate:
•

DP.STS (DP.PDB), in which completion-status information has been inserted

•

Possibly DP.ALN and DP.ERR (DP.PDB+2 and DP.PDB+4), in which the actual length of a
transfer and error information may have been placed

•

Possibly DP .XTR (DP .SEM)

•

Possibly some portion of the function-dependent value data field, DP.FDD

The meanings of the modified fields in the reply message shown in Figure 1-1 are as follows:

Field

Significance

DP.STS

Code for completion status, indicating type of error; the exception codes
returned are listed in Chapter 6 of the MicroPower /Pascal Run-Time
Services Manual and in the individual driver chapters; ES$NOR (0)
indicates success

DP.ALN

The length of the data actually transferred, in bytes, for transfer functions

DP.ERR

Device-dependent hardware- or software-error information if DP.STS is
nonzero

DP.FDD

To be interpreted according to the type of device handled and the function
requested-unused in most cases

Individual driver descriptions in later chapters provide more specific information about the
status, length, and error word values and function-dependent information in the DP.FDD field.

Introduction to MicroPower /Pascal Input/Output 1-15

Chapter 2
Ancillary Control Process
This chapter describes the MicroPower/Pascal ancillary control process (ACP), which in
cooperation with the network service process (NSP), the standard 1/0 drivers, and the Pascal
file system OTS (or equivalent user routines), provides the capability for device-independent file
1/0. (The ACP, the NSP, and the drivers are collectively referred to as "l/O service processes"
or "l/O servers.") Also, the ACP optionally provides RT-11 directory services, which allow you
to set up RT-11-compatible file directory structures on disk devices.

2. 1 ACP Features and Capabilities
The ACP supports file-opening operations for all MicroPower/Pascal-supported 1/0 devices
and protocols plus normal Pascal 1/0 on disk devices. It is called from a MicroPower/Pascal
application program in order to associate a file variable with an 1/0 service process, making
it possible to perform device-independent 1/0 via normal Pascal 1/0 statements. Requests for
file-opening or disk-transfer operations are passed by the file system OTS to the ACP.
The functions of the ACP include:
•

Parsing user device/ file specifications

•

Determining device characteristics

•

Supporting RT-11 file structure on disk-class devices (optionally enabled in prefix file)

•

Checking file limits when accessing disk-class devices

•

Supporting parsing for task-to-task links in cooperation with the NSP-a DECnet Session
Control layer function (optionally enabled in prefix file)

Ancillary Control Process 2-1

2.2 Accessing the ACP for File 1/0
For most MicroPower/Pascal applications, you access the ACP implicitly by opening a file with
the Pascal OPEN statement. If the file in question is a named file on a directory-structured disk,
other Pascal I/O statements you issue implicitly access the ACP-BREAK, DELETEJILE, and
so forth. See Section 2.3 for more information on the Pascal file system interface to the ACP;
see Chapter 9 of the MicroPower /Pascal Language Guide for descriptions of OPEN and the other
Pascal IfO statements.
In addition to issuing the OPEN and subsequent Pascal 1/0 procedure calls, you must:
1.

Edit the ACP prefix file to indicate:

•

ACP initialization and request-handling process priorities

•
•
•
•

Directory operation priority
Whether RT-11 directory support is required
Whether network open support is required
The ACP dynamic pool size

Build into your application the following I/O system components:

•

ACP process

•

I/O service processes (device drivers and NSP, as appropriate) to be accessed via file
system (OPEN)

•

Pascal OTS routines for file service-built in automatically by MPBUILD for programs
that invoke Pascal I/O procedures-plus any support routines you opt to include (see
kit files FSPAS.PAS, INTDIR.PAS, GETSET.PAS, and GSINC.PAS)

For more information on setting up your application software for file system IjO, see Section
2.6, the NSP and driver chapters of this manual, and the material on building system processes
in the MicroPower/Pascal system user's guide for your host system.

Note
It is possible to bypass both the file system and the ACP in order to access a
device driver directly. This can be accomplished via send/receive operations
to a driver's request queue semaphore or, in some cases, via DIGITAL-supplied
support routines that talk to a particular driver. Such access is referred to
throughout this manual as "nonfile access."

As noted in other chapters, it is also possible, given detailed knowledge of the
ACP and NSP request/reply packet interfaces, to either bypass the file system
OTS in order to access the ACP directly or bypass the file system OTS and the
ACP to access the NSP directly. Such access is referred to as "low-level file
system access." However, the current version of this manual does not provide
detailed descriptions of the ACP and NSP send/receive interfaces.
The following sections describe the Pascal file system interface to the ACP, the lower-level
request/reply packet interface (in general terms-see the preceding note), the status codes that
can be returned to users of either interface, and the ACP prefix file. An application note on
device-name parsing concludes the chapter.

2-2

Ancillary Control Process

2.3 Pascal File System Interface
The following Pascal I/O statement implicitly accesses ACP services:
OPEN
When you open a non-directory-structured file-that is, a file that does not have a directory,
such as a terminal line, a communications port, a network link, or an A/D converter-the
file system OTS sends an open request to the ACP, and the ACP sends the request to the
associated I/O server (device driver or NSP) for any device-dependent open processing. When
the device/ server completes open processing, it replies to the ACP. Provided no error occurred,
the ACP returns the unit number and the structure descriptor block (SDB) of the I/O server
to the file system OTS. All subsequent operations to that file are sent by the file system OTS
directly to the I/O service process, with no further ACP involvement.
However, when you open a disk file, whether directory-structured or not, the ACP associates a
channel with your file variable and returns the channel number and the ACP' s SDB to the file
system OTS. All subsequent operations to that disk file are processed by the ACP. This allows
the ACP to perform file-limit checks for disk files. If you build RT-11 directory support into
your application-by specifying RTSUP = 1 in the ACP prefix file-RT-11 directory operations
can be performed.
The current OTS and ACP interaction does not allow for Pascal I/O with disks having greater
than 65,536 blocks. I/O transfer computations are performed with 16 bits, with no allowances
made for media having block counts that exceed 16 bits. If multiblock GET transfers are being
performed to a disk opened as 'DUAO:' or 'XDAl:', for example, the ACP may not detect when
the 16-bit block count overflows and wraps around (beginning again at zero). Thus, EOF is
never returned, and the operation loops.
The following Pascal I/O statements implicitly access the ACP for disk-class devices only:
DELETEJILE
BREAK
INIT_DIRECTORY

PROTECT-FILE

EMPTY_BUFFER

RENAMEJILE

GET, READ

SQUE!EZE_DIRECTORY

PUT, WRITE

UNPROTECTJILE

PURGE

GET, READ, PUT, and WRITE statements may or may not trigger ACP requests, depending on
the current state of the OTS buffers. The appropriate request packets are sent to the ACP only
when necessary to complete a user-requested operation. For example, a READ or GET operation
that requires more data than what remains in the buffers from previous input operations causes
the OTS to issue one or more Read Logical (IF$RDL) requests to the ACP. Other Pascal
statements unconditionally cause the OTS to issue send requests; examples are BREAK, which
· generates a Write Logical (IF$WTL), and CLOSE, which generates a Close (IF$CLS) request
(normally preceded by a Write Logical, unless BREAK immediately precedes CLOSE).
Pascal Get Characteristics functions that report the characteristics of disks are provided in
the file GETSET .PAS in the MicroPower /Pascal distribution kit. Those functions issue Get
Characteristics (IF$GET) request packets to the driver.

Ancillary Control Process 2-3

2.4 Request/Reply Packet Interface
The packet-level functions provided by the ACP are listed below by symbolic and decimal
function code:
Code

Function

IF$RDP (0)
IF$RDL (1)

Read Physical
Read Logical

IF$WTP (3)
IF$WTL (4)

Write Physical
Write Logical

IF$SET (6)
IF$GET (7)

Set Characteristics
Get Characteristics

IF$LOK (16)
IF$ENT (17)

Lookup
Enter

IF$REN (18)
IF$DEL (19)
IF$CLS (20)
IF$PRG (21)
IF$PRO (22)
IF$UNP (23)

Rename
Delete
Close
Purge
Protect
Un protect

Many of the functions are not processed directly by the ACP but rather are passed to the I/O
service process connected to the channel.
Note
When a disk-class device is opened, a channel is allocated in the ACP, and
subsequent requests for that device come to the ACP. When a nondisk device
is opened, the ACP is called only for the open. Subsequent requests for that
device go directly to the ·device driver or service process with no further ACP
involvement.
The ACP consists of an initialization process, which lowers its priority to become the main
request server. The main request server handles all I/O requests for open disk files and
passes all open or RT-11 directory requests to the RT-11 directory process. The RT-11 process
performs device-specification parsing, determination of device characteristics, and all RT-11
directory operations.

2.4. l Physical Read and Write Functions
Physical read and write requests are valid only on an open channel. The request is sent to the
device driver with no limit or boundary checks.

2-4 Ancillary Control Process

2.4.2 Logical Read and Write Functions
Logical read/write requests are checked for validity (within bounds of the file for a file-structured
device, channel open verification) and the request is passed on to the appropriate driver. The
driver will reply directly to the user upon completion of the request. On write operations, the
ACP will update the current high mark in the file if the file was entered. The request packet
for read/write requests is the same as for device drivers, except that the unit (DP.UNI) field
contains a channel number.
Each read or write request specifies the beginning block number for the operation.
If the read or write operation causes the limits of a file on a file-structured device to be
exceeded, the ACP truncates the transfer length to the maximum available in the file. If no data

is available, status ES$EOF is returned.

2.4.3 Set Characteristics Function
Set Characteristics requests are valid only on an open channel. The request is sent to the device
driver with no checks.

2.4.4 Get Characteristics Function
The Get Characteristics function returns a block of device-dependent information about a
specified channel in the function-dependent portion of the reply message. The information
consists of the codes for device class, type, starting block number of the file, highest block in
use, the file size, the device driver unit number, and the device driver structure descriptor block.
If no channel is specified (packet offset DP. UNI) or if the specified channel is not open, the

ACP returns only a class and type code indicating that the response has come from the ACP.
The function-independent portions of the Get Characteristics request and reply packets are the
same as for device drivers, except that, as noted above, the unit (DP.UNI) field contains a
channel number. The function-dependent portions of the packets are as follows:
I
I
I

1----------------DP.DAD 1

I
I

Type

Not
used

Funcdep
value
data

Start block fl

File size

I
I
I

1--

DP.LEN -

- DP.FDD

High block fl

Dev ice unit fl
Device

DP.BUF DP.PAR -

I Class

I
I

1
I

+-----------------+

Ref
data
info
v

driver
SDB

--·
I
I
I
--1

I
I

+-----------------+

ML0-834-87

Ancillary Control Process 2-5

In the reply information:
•

Class is DC$SSV, for system service class.

•

Type is SS$DFL for file (directory) structured access, SS$DSK for nonfile (nondirectory)
structured access, or SS$ACP if no channel or an invalid channel was specified.

If the type is SS$DFL or SS$DSK the following information is returned:

•

The starting block number of the file on the disk

•

The highest logical block number used within the file (normally meaningful only when
creating a file-that is, HISTORY := NEW)

•

The size of the file in blocks

•

The unit number of the device on which the file resides

•

The device driver structure descriptor for the device on which the file resides

Note
The MACR0-11 field names do not represent offsets into the user's send or reply
buffers; they are offset symbols used by MACR0-11 IjO servers to reference
packets. For example, DP.FDD is a 24-byte (decimal) offset from the packet
header. The symbols are defined by the DRVDF$ macro, which resides in the
COMU and COMM kernel macro libraries. The equivalent Pascal symbols are
defined in the IOPKTS.PAS include file.

2.4.5 Lookup and Enter Functions
Lookup and Enter are the OPEN functions. For directory-structured I/O, Lookup is used to find
an existing file, and Enter is used to create a new file. For network IjO, Lookup designates
the active task, and Enter establishes a passive task. For all other I/O, Lookup and Enter are
equivalent.
Lookup and Enter parse the user's file specification. If the device specification is a ring buffer,
the SDB of the ring buffer is returned to the file system OTS. The file system then operates
directly on the ring buffer. Otherwise, the ACP sends a Get Characteristics request (IF$GET) to
the 1/0 server request semaphore in order to determine the device characteristics.
If the Get Characteristics succeeds, the ACP passes the Lookup or Enter request to the I/O server
to allow it to perform any device-specific open processing. I/O servers must reserve Lookup and
Enter function codes even if they do not implement those functions. IjO servers may ignore the
requests if they have no device-specific processing to perform for them. I/O servers that ignore
the requests should return them with ES$NOR (normal completion) or ES$IFN (invalid function)
status. The ACP interprets ES$IFN as indicating that no special processing was required and
continues processing the request as if ES$NOR were returned. (This allows compatibility with
Version 1 MicroPower/Pascal drivers.) Alternatively, an I/O server may support Lookup or
Enter, performing appropriate device-specific open processing. However, if an I/O server does
not wish to be accessed by the ACP, it should return ES$UFN (unsupported function) or any
other error code (other than ES$IFN), informing the ACP that an error occurred during open
processing.

2-6 Ancillary Control Process

If no error occurs in device-dependent open processing, the ACP returns the following

information to the file system OTS:
•

For nondisk devices, the unit number and the device-driver SOB

•

For disk devices, a channel number and the ACP SDB

The file system OTS sends all subsequent requests for the specified device to the 1/0 server
indicated in the ACP reply. Thus, disk requests are sent to the ACP, while nondisk requests
are sent to a device driver with no further ACP involvement.

2.4.6 Rename, Delete, Protect, and Unprotect Functions
Rename, Delete, Protect, and Unprotect are valid only on permanent files. A permanent file
is one with the PERM bit set in the directory entry; see Appendix A for more information on
RT-11 directory structure.
The ACP searches the directory for the specified file and, if the file is found, changes the
directory entry. (Note that Delete changes the status of the file from permanent to empty.)
No checks are made to determine if the file is currently open for another user; the ACP does
not perform any contention checks on files.

2.4.7 Close and Purge Functions
Close and Purge are valid only for a channel that has been defined by a previous Lookup or
Enter request to the ACP.
Close makes a tentative file permanent if the file was Entered. If the file was opened with a
Lookup, Close is functionally equivalent to Purge (deallocates channel).
Purge makes a tentative file empty if the file was Entered. If the file was opened with a Lookup,
Purge deallocates the channel in the ACP.
Any further requests on the channel after Close or Purge are invalid, since the channel is no
longer defined.
The file system OTS passes Close/Purge requests on to the 1/0 server when the Pascal
CLOSE/PURGE procedures are executed. 1/0 servers must reserve Close and Purge function
codes even if they do not wish to implement the functions. 1/0 servers may completely ignore
these requests if they have no device-specific processing to perform for any of them. 1/0 servers
that ignore the requests should return them with an ES$NOR (normal completion) or ES$1FN
(invalid function) status. ES$1FN indicates to the file system OTS that no special processing was
required. (This allows compatibility with Version 1 MicroPower/Pascal drivers.) Alternatively,
an IjO server can support Close or Purge, performing appropriate device-specific Close/Purge
processing.

Ancillary Control Process 2-7

2.5 Status Codes
The ACP returns the exception codes shown below in the status-code field of the reply message.
If you perform I/O with Pascal I/O statements-that is, not with send/receive statements or
Pascal support routine calls-the Pascal OTS will report the corresponding exception (unless the
operation was an OPEN, DELETEJILE, RENAMEJILE, PROTECTJILE, UNPROTECTJILE,
INIT_DIRECTORY, or SQUEEZE_DIRECTORY for which a STATUS return was specified). The
error codes shown are those generated by the ACP directly-not those generated by other I/O
system components involved in file I/O.
If no error is detected during the I/O operation, the ACP returns a value of ES$NOR (0) in the
status-code field.

The following codes are returned by all configurations of the ACP:

Code

Type

Description

ES$ABT

HARD_IO

I/O request canceled or aborted

ES$NXU

HARD_IO

Nonexistent unit or channel

ES$DVF

SOFT_IQ

Attempt to signal device driver failed

ES$EOF

SOFT_IO

End of file encountered

ES$IDS

SOFT_IQ

Illegal device specification

ES$IFN

SOFT_IQ

Illegal function

ES$IFS

SOFT_IO

Illegal file specification

ES$IRS

SOFT-10

Illegal rename specification

ES$NFS

SOFT_IO

Device not file structured

ES$NRF

SOFT-10

No reference data present

ES$WEF

SOFT-10

Attempted write past EOF

ES$NMC

RESOURCE

Insufficient space for operation in ACP pool

The following codes are returned only if RT-11 directory support is selected (RTSUP = 1) in the
prefix file:

Code

Type

Description

ES$DCF

SOFT-10

Device full

ES$DIO

SOFT-10

Directory I/ 0 error

ES$DRF

SOFT_IQ

Directory full

ES$FNF

SOFT-10

File not found

ES$IDR

·soFT_IO

Invalid directory format

ES$PRO

SOFT-10

File protection error

2-8 Ancillary Control Process

The following codes are returned only if NSP support is selected (NSPSUP = 1) in the prefix
file:

Code

Type

Description

ES$INS

SOFT-10

Invalid network specification

ES$NNS

RESOURCE

No network service process installed

Exception codes are defined in the EXC.P AS include file for Pascal users and by the EXMSK$
macro in the COMU and COMM macro libraries for MACR0-11 users.

2.6 ACP Prefix File
Figure 2-1 shows the user-modifiable portion of the ACP prefix module. The following
paragraphs describe the macro calls and symbol definitions that can be edited to fit your
application.
The ACP prefix file allows you to enable or disable RT-11 file support, enable or disable network
OPEN support, and tune the size of the ACP pool area.
RT-11 file support allows the user to create, maintain, and modify RT-11 file-structured disk
devices. Volumes written with the MicroPower/Pascal ACP may be read by RT-11, VAX/VMS
(using EXCHANGE), and RSX-11 (using FLX).
The network OPEN support allows the ACP to parse and create session control messages,
required when using the NSP. If the NSP is not being used in your application, the code
required to parse and generate these messages is not required.
The ACP pool area is used by the ACP in processing open requests. This area may need to be
adjusted in size, depending on the number of NSP open requests that are currently in progress
(180 bytes required per open) and the number of concurrently open disk files (40 bytes required
per channel).

Ancillary Control Process 2-9

Figure 2-1:

ACP Prefix File (ACPPFX.MAC) Excerpt
.TITLE ACPPFX - Ancillary Control Process prefix file

rhis software is furnished under a license and may be used or copied
only in accordance with the terms of such license.
Copyright (c) 1984, 1986 by Digital Equipment Corporation.
All rights reserved .
. MCALL macdf$
macdf $
RT$IPR == 250.
RT$PPR == 175.
DIR$PR == 175.

initialization priority
processing priority
directory operation priority

NSPSUP = (0 or 1)
0 = No NSP open support
1 = Include NSP open support
NSPSUP = 1 ; include NSP support
;+

RTSUP = (0 or 1)
0 = No RT--11 Directory support
1 = Include RT--11 Directory support
RTSUP

; include RT--11 directory support

; ACP pool size in bytes
$DPLSZ == 1000.

180. per NSP open
40. per channel

; END OF USER PARAMETERS
.end

2. 7 Application Note: Device-Name Parsing
The ACP parser converts device names into SDBs. The device name in a file specification may
be:
•

A ring buffer name.

•

A standard device name in the form ddcu, where dd is the 2-letter device name, c is an
optional controller letter (default is A), and u is an optional unit number (default is 0). A
dollar sign ($) is added to the beginning of the device name and controller letter to form
the structure name (example: DUAO: is converted to '$DUA' unit 0).

•

A logical name. A logical name should translate to one of the other forms described here.

2-10 Ancillary Control Process

Device strings are converted to uppercase before processing, so only uppercase kernel structures
may be accessed via the OPEN statement. Any names less than six characters are padded with
spaces to a 6-character length.
If no device name is specified, the ACP uses the default device name 'DK'. The user is assumed

to have created a logical name for DK, either at build time in the kernel configuration file, or
at run time via a call to the CREATE_LOGICAL_NAME routine.

2.8 FALACP
FALACP .PAS is a small version of the ACP, which you can use only in specific applications.
FALACP performs terminal and ring buffer OPENs for a FALCON or KXTll-CA application
having more than one serial line. This program opens files from 'TTAl:' to 'TTA9:', 'XLOO:' to
'XL09', and 'XLIO:' to 'XLI9:'. For applications that require only terminal or ring-buffer access
on the FALCON or KXTl 1-CA, you can use this program to replace the standard ACP.
Unlike the standard ACP, FALACP performs minimal device checking, making use of the first
device name character to discriminate between terminal driver and ring buffer access. You are
responsible for using the correct terminal line name or ring buffer name.
To use this alternate ACP, build FALACP into your application instead of the standard ACP
driver. You do not need the ACPPFX.MAC prefix file. FALACP.PAS is in MICROPOWER$LIB
for VMS and in LB:[2, 10] for RSX.

Ancillary Control Process 2-11

Chapter 3
Asynchronous Serial Line (Terminal) Driver
This chapter describes the use of the MicroPower/Pascal asynchronous serial line (TT) driver,
sometimes referred to as the terminal driver. The driver supports I/O operations on terminals
and other devices attached to the following serial line interfaces:

•
•
•
•

DLVll-type-DLVll, DLVll-E, DLVll-F, DLVll-J
DLART-type-KXTll-CA or KXJll-CA console, SBC-11/21, CMR21, MXVll-A,
MXVll-B
DZVll
KXTl 1-CA or KXJll-CA multiprotocol chip

The supported devices interface one or more asynchronous serial communication lines to a
MicroPower/Pascal target processor for communication with terminals, modems, and other
processors.

3. 1 TT Driver Features and Capabilities
The TT driver supports read and write operations, the returning or altering of line parameters,
and a stop function for outstanding read requests. AH data transmissions use the same baud
rate for sending and receiving. All lines run in 8-bit mode with one stop bit and no parity.
Read operations on a line are performed in line or block mode, as determined by prefix file
default or a Set Characteristics operation.
In line mode, terminal-oriented line-editing operations, such as line erasure (CTRL/U), previouscharacter deletion (DELETE), and line redisplay (CTRL/R), are performed. Characters are echoed
(if echo is enabled) as they are read. No data is returned to the requesting process until a
carriage return is typed or the edit buffer overflows. The size of the edit buffer is specified in
the TT driver prefix file.
In block mode, all data is passed to the requesting process without interpretation (unless
XON /XOFF flow control is enabled). This allows you to connect the serial lines to devices other
than terminals. For example, you can use the TT driver in conjunction with the asynchronous
DDCMP (CS) driver to communicate with another MicroPower/Pascal target system over a
serial line. See Chapter 12 for details.

Asynchronous Serial Line (Terminal) Driver 3-1

In block mode, minimum/maximum read requests are honored. This allows your programin particular, the OTS routines that carry out Pascal I/O procedure requests-to read a
minimum number of bytes to complete your request plus as many other bytes (up to a
maximum) as are immediately available. This facility is useful for high line-speed applications.
Minimum/maximum read requests are possible, because the TT input ISR has two buffers and
can buffer characters between reads. The size of the ISR input buffers is set in the TT driver
prefix file.
Get and Set Characteristics functions allow the requesting process to inspect and change line
parameters, including baud rate, modem status flags, input/output flow control (XON/XOFF),
line/block mode, character length, even/odd parity, number of stop bits, and echo. Line
parameters are initially set according to default values you specify in the TT driver prefix file.
The stop function allows the requesting process to reclaim resources by aborting an in-progress
read request.
Modem control is supported for the DLVll-E, DHVll, and KXTll-CA or KXJll-CA
multiprotocol channel A interfaces and, in a limited fashion, for the DZVl 1 interface. Modems
allow you to connect remote terminal lines to the serial line interface for access to the target
processor. The modem is controlled by a set of signals it exchanges with the target processor.
(More information on modem control signals is provided in Section 3.4.3.)
Modem control interrupts are supported for DLVll-E, DHVll, and KXTll-CA and KXJll-CA
multiprotocol channel A. The Set Modem Semaphore command allows the requesting process
to specify a binary or counting semaphore to be signaled on each interrupt.

3.2 Performing Asynchronous Serial 1/0
For most MicroPower/Pascal applications, you perform asynchronous serial I/0-particularly
terminal I/0-by invoking Pascal I/O procedures that open files for terminal data and then
input or output the data, in accordance with the rules for Pascal IjO. (INPUT and OUTPUT are
opened implicitly and thus require no explicit OPEN invocation.) The Pascal I/O proceduresOPEN, GET, WRITE, and so forth-are described in Chapter 9 of the MicroPower /Pascal

Language Guide.
Note
The TT driver Set Modem Semaphore operation cannot be performed with Pascal
I/O procedures. See Section 3.3 for more information on such operations.
In addition to invoking the Pascal I/O procedures, you must:
1.

Edit the DEVICES macro in the system configuration file to reflect the serial-line controller
interrupt vector addresses

Edit the TT driver prefix file to reflect:
•

[For each controller:] Controller type, CSR address, interrupt vector address, hardware
interrupt priority, and number of serial lines

•

[For each line:] ISR buffer size, speed, edit buffer size, and where supported by hardware,
the setting or clearing of such parameters as input or output flow control (XON/XOFF),
line editing (with or without echo of characters as they are read), bits/character, parity
bits, number of stop bits, modem status-change interrupts, baud rate programming, Data
Terminal Ready or Request to Send indications, or BREAK assertion

3-2 Asynchronous Serial Line (Terminal) Driver

•
3.

Driver initialization and request-handling process priorities.

Build into your application the following 1/0 system components:
•

TT driver process

•

[For explicit terminal file OPEN:] Ancillary control process (ACP)

•

Pascal OTS routines for file service-built in automatically by MPBUILD for programs
that invoke Pascal 1/0 procedures-plus any terminal 1/0 support routines you opt to
include (see kit files GETSET.PAS, GSINC.PAS, VTlOO.PAS, and VTlINC.PAS)

For more information on setting up your application software for terminal 1/0, see Chapter
4 of the MicroPower /Pascal Run-Time Services Manual, Section 3.6 of this manual, and the
material on building system processes in the MicroPower/Pascal system user's guide for your
host system.
When a module that contains Pascal 1/0 procedure invocations is built into your application,
Pascal OTS routines for file service are linked to the module. The OTS file routines perform all
Pascal operations on files, including file opening, input, and output. In particular, they perform
the necessary low-level processing of high-level operations like OPEN and WRITE. Thus, the
basic mechanisms of MicroPower/Pascal 1/0-the sending of request packets to driver or ACP
queue semaphores, the dispatching of interrupts, and the signaling of reply semaphores-are
concealed from the Pascal user.
Alternatives to using the Pascal 1/0 procedures for terminal 1/0 exist, but require more effort.
You can:
•

Issue your own Pascal or MACR0-11 packet-level requests to the ACP and the driver,
bypassing the OTS file routines (lower-level file system access)

•

Issue your own Pascal or MACR0-11 packet-level requests to the driver, bypassing the
OTS file routines and the ACP (nonfile access)

The following sections describe the Pascal 1/0 procedure interface to the TT driver, the lowerlevel request/reply packet interface, the status codes that can be returned to users of either
interface, and the TT driver prefix file. An application note on hardware buffering concludes
the chapter.

3.3 Pascal 1/0 Procedure Interface
To perform standard Pascal 1/0 to an asynchronous serial line, you must open a file. Opening
the file associates a Pascal file variable with a serial line unit. Invoke the OPEN procedure as
follows:
OPEN (filvar, 'TTAu:', ... )

where:
•

filvar is a Pascal file variable.

•

u is a serial line number (0, 1, ... ).

Asynchronous Serial Line (Terminal) Driver 3-3

For example, 'TTAl:' would specify the second line (1) of the first serial interface controller
listed in the TT driver prefix file.
Note
Any number of serial lines are supported, but the number is limited for each
type of controller-up to four for DZVl l, up to eight for DHVl 1, and one for
most others. The range of valid identifying unit numbers is 0 through (n-1) for
n lines configured in the TT driver prefix file. Lines are numbered sequentially
upward from 0 in the order they appear in the prefix file, crossing controller
boundaries.
The standard Pascal file variables INPUT and OUTPUT are implicitly associated
(by default) with 'TTAO:'. They require no explicit OPEN invocations.
The OPEN statement causes the Pascal OTS to send an open request to the ACP, which returns
a unit number and a TT driver request semaphore ID to the OTS. Subsequent 1/0 requests are
sent directly to the driver by the OTS, with no further ACP involvement.
In carrying out subsequent input, output, CLOSE, or PURGE operations on serial interface units,
the Pascal OTS uses the following packet-level driver functions:
•

Read Logical (IF$RDL)

•

Write Logical (IF$WTL)

•

Close (IF$CLS)

•

Purge (IF$PRG)

The appropriate request packets are sent to the driver only when necessary to complete a
user-requested operation. For example, a READ or GET operation that requires more data than
what remains in the buffers from previous input operations causes the ors to issue one or
more Read Logical .(IF$RDL) requests to the TT driver. Other Pascal statements unconditionally
cause the OTS to issue send requests; examples are BREAK, which generates a Write Logical
(IF$WTL), and CLOSE, which generates a Close (IF$CLS) request (normally preceded by a Write
Logical, unless BREAK immediately precedes CLOSE).
Pascal Get and Set Characteristics functions that report or alter the characteristics or status of
serial lines are provided in the file GETSET .PAS on the MicroPower/Pascal distribution kit.
Those functions issue Get or Set Characteristics (IF$GET or IF$SET) request packets to the
driver.
Neither the Set Modem Semaphore (IF$SMD) nor the Stop 1/0 (IF$STP) packet-level. driver
function can be performed with normal Pascal 1/0 statements or GETSET functions. To
perform the Set Modem Semaphore or the Stop 1/0 function, either use the request/reply
packet interface directly or write Pascal procedures that take a user-specified file variable (or
queue semaphore ID) and send the appropriate request packet to the driver. (The Get/Set
Characteristics procedures in GETSET.PAS demonstrate the latter approach.)
Note
Pascal procedures for manipulating VTlOO video are distributed as source
modules on the MicroPower/Pascal kit. The relevant files are VTlOO.PAS, which
contains the procedures, and the include file VTllNC.P AS, which externally
declares the procedures. Most of the operations WRITE to OUTPUT.

3-4 Asynchronous Serial Line (Terminal) Driver

3.4 Request/Reply Packet Interface
The following packet-level functions provided by the TT driver are listed by symbolic and
decimal function code:

Code

Function

IF$RDP (0)
IF$RDL (1)

Read Physical
Read Logical

IF$WTP (3)
IF$WTL (4)

Write Physical
Write Logical

IF$SET (6)
IF$GET (7)

Set Characteristics
Get Characteristics

IF$STP (10)

Stop 1/0

IF$SMD (11)

Set Modem Semaphore

If a request is received for an Open (IF$LOK or IF$ENT), a Close (IF$CLS), or a Purge
(IF$PRG), the driver returns an illegal function status code (ES$1FN), which the ACP (Open) or
OTS (Close/Purge) interprets as indicating that no device-dependent processing was required
for that operation.

Note
The MACR0-11 symbols used in this section are defined by the DRVDF$ macro,
which resides in the COMU and COMM kernel macro libraries. The equivalent
Pascal symbols are defined in the IOPKTS.P AS include file.
The following function modifiers recognized by the TT driver are shown listed by symbolic code
and bit position:

Code

Function

FM$MIN (bit 7)

Enable minimum/maximum block-mode read

FM$BSM (bit 13)

Signal binary/ counting semaphore

The TT driver is a single (static) process, beginning as an initialization process and then
lowering its priority to the running level specified in the prefix file. The single process handles
all the controllers (serial interface units) and lines specified in the prefix file, unlike other
MicroPower/Pascal drivers that create a separate process for each controller. 1/0 requests for
any controller are sent (using a Pascal SEND or a MACR0-11 SEND$) to the request queue
semaphore waited on by the driver process.

Asynchronous Serial Line (Terminal) Driver 3-5

The request queue name and number of supported units for TT driver requests are shown
below:
Request
Queue Name

Driver

Asynchronous $TTA
serial

Number of Units

Numbering

1-n (1-4 for DZVll,
1-8 for DHVll,
1 for most others)

0 through (n-1) in
prefix file order,
crossing controller
boundaries

The units configured for each controller must be specified in the TT driver prefix file.
The general format of the TT driver request and reply packets follows:
TT

REQUEST
PACKET

DP.FUN -

+-----------------+
Standard

packet

header

Function

REPLY
PACKET

- DP.FUN

I
I

DP.UNI -

Unit

- DP.UNI

DP.SEQ -

Sequence number

- DP.SEQ

DP.PDB -

Requesting

Status code

- DP.STS

Actual length

- DP.ALN

identifier

Error info

- DP.ERR

Reserved for

- DP.XTR

semaphore

driver

process

DP.SEM -

identifier

I
I
I
I
I
I
I

Funcind e p
value
data

usage

- DP.FDD

DP.FDD I

Request
DP.MIN -

data

Funcdep
value
data

Not used

Reply
data

Not used

DP.BUF -

I
I

Buffer

DP.PAR -

address

Ref
data
info

DP.LEN -

Buffer length

+-----------------+

I
I
I

,-----------------,

,-:
,--

I
I

--,
:
--,
I

Reserved

I
I

+-----------------+ ML0-833-87

The function-independent portions of the packets are described in the request/reply packet
interface section of Chapter 1. The valid function and function-modifier codes for the function
(DP.FUN) field and the valid unit numbers for the unit (DP.UNI) field are listed at the beginning
of this section.

3-6 Asynchronous Serial Line (Terminal) Driver

The function-dependent portions of the request and reply packets for each type of TT driver
function are described in the following sections.
Note
The MACR0-11 field names shown do not represent offsets into the user's
send or reply buffers; they are offset symbols used by MACR0-11 drivers to
reference packets. For example, DP.FUN is a 6-byte offset from the packet
header.

3 .4. l Read Functions
When a read (IF$RDP or IF$RDL) request is received, the TT driver validates the request and
queues it on the specified line. If no request is currently active, the operation is begun.
Reads are performed in block mode, unless you enabled line editing for the line in question in
the prefix file or in a Set Characteristics request.
In line mode, line-editing functions are performed with optional echoing of characters as they
are read. No data is returned to the requesting process until a carriage return has been entered,
regardless of the requested read length. Thus, even a single-character request must wait for a
carriage return-unless a portion of a previously entered line remained in the line buffer when
the operation commenced.
In block mode, the request is checked for the minimum/maximum (FM$MIN) function modifier
and a minimum read value (offset DP .MIN in the request packet). If both are present, the
value specified at offset DP .MIN in the request packet is used as the required read size; if
either is absent, the reference buffer length (DP.LEN) is used as the required size. Once the
required amount of data has been received, the request is considered complete. If FM$MIN
was specified, up to (maximum-minimum) additional bytes of data will be returned to the user
if they are currently available in the ISR buffers. The request is then returned to the user with
the actual-length field (offset DP.ALN), reflecting the actual length of the transfer.
If input flow control is enabled for the line (by prefix file default or Set Characteristics request),
the input ISR sends XOFFs to the device attached to the line whenever the input ISR buffer is
75 % full. When the congestion is reduced, an XON is sent to allow further input.

Asynchronous Serial Line (Terminal) Driver 3-7

The function-dependent portions of the read request and reply packets are shown below:
I
I
I

·-----------------,
DP.FDD Not

I
I
I

·--

I
I
I

DP.MIN

I
I
I

used

Min read length
- ·----------------I
I
I

,----------------Not
·-- used
,----------------DP.BUF Buff er
·-DP.PAR address
,----------------DP.LEN Buffer length
+-----------------+

I
I

Funedep
value
data

,----------------- - DP.FDD

!
I
I

,--

1
I

Not used

I
I
I
I
I
I
I
I
I

I
I
I
I
I

----A

Ref
data
info
v
ML0-835-87

Fields DP .BUF through DP .LEN specify the location and length of the user buffer that is to
receive the data. Those fields are put into the packet by the kernel send primitive, based on
the send call arguments.
The DP.MIN field can be used to specify a minimum read length for block-mode reads. If
function-modifier FM$MIN is set, the number of bytes returned by a block-mode read is the
amount specified in DP.MIN plus as many bytes, up to the DP .LEN maximum, as were available
in the input JSR buffers when the minimum length was achieved. If DP.MIN is zero, this has
the effect of a conditional read. DP .MIN is ignored for line-mode reads.
If FM$MIN is not set, DP.LEN is used as the required read length.

In line mode, the length specified at DP.LEN is honored, but regardless of the number of
available bytes, no data is returned until a terminator has been entered.

3.4.2 Write Functions
When a write (IF$WTP or IF$WTL) request is received, the TT driver validates the request and
queues it on the specified line. If no request is currently active, the operation is begun.

Note
Write requests have priority over pending echo for output.
Thus, if a
user application performs continuous writes, pending echo may be delayed
indefinite!y.
If output flow control is enabled for the line (by prefix file default or Set Characteristics request),
XOFFs received from the device attached to the line suspend output, until an XON is received.

Replies to write requests are not sent to the caller until all data has been given to the device.
Generally, this means that all data except the last two bytes has been transmitted. If the
application requires complete output synchronization, it writes one or two null bytes. See the
application note on hardware buffering at the end of this chapter for details.

3-8 Asynchronous Serial Line (Terminal) Driver

The function-dependent portions of the write request and reply packets follow:

- DP.FOO

Not used

ML0-836-87

Fields DP.BUF through DP.LEN specify the location and size of the user buffer from which data
is to be copied. Those fields are put into the packet by the kernel send primitive, based on the
send call arguments.

3.4.3 Get and Set Characteristics Functions
The Get Characteristics (IF$GET) and Set Characteristics (IF$SET) functions allow you to inspect
or change the current parameters of a given line. The parameters include bit settings for:
•

Input/Output flow control (XON /XOFF)

•

Line /Block mode

•

Echo (line mode only; characters are echoed as they are read)

•

Read-only modem controls-Ring, Carrier, Clear to Send, Data Set Ready (for DLVl 1E, DHVll, KXTl 1-CA or KXJll-CA multiprotocol channel A; Ring and Carrier only for
DZVll)
.

•

Read/write modem controls-Data Terminal Ready, Request to Send, Enable Modem
Interrupts (for DLVll-E, DHVll, KXTll-CA or KXJll-CA multiprotocol channel A; DTR
only for DZVll)

•

Assert/Deassert BREAK

•

Programmable baud rate (only for DLVll-E, DLVll-F, DLART, KXTll-CA or KXJll-CA
multiprotocol, DHVl 1, DZVl 1)

•

Setting the line's framing characteristics: bits/character, parity, stop bits

•

Terminal type
Note
No modem control is provided for KXTl 1-CA or KXJll-CA multiprotocol
channel B. Channel A can be configured with full modem control or no modem
control. The list above assumes full modem control for channel A.

Asynchronous Serial Line (Terminal) Driver 3-9

Split line speeds are not supported; a line's transmit and receive speeds must
match.
When a Get Characteristics request is received, the TT driver gets the line status settings from
the transmit and receiver CSRs and from its internal control block for the specified line and
passes those parameters back to the requesting process.
When a Set Characteristics request is received, the TT driver sets or clears bits in the transmitter
and receiver CSRs and in its internal control block for the specified line and then performs
a Get Characteristics operation, which passes the new line parameters back to the requesting
process.
The function-dependent portions of the Get Characteristics request and reply packets follow:

Type

: Class

- DP.FDD

Line parameter 1
Line parameter 2
Line speed
Not used

ML0-837-87

The function-dependent portions of the Set Characteristics request and reply packets are shown
below:

DP.FDD -

Reserved

Type

i Class

- DP .FDI

I
I

Line parameter 1
Line parameter 2

Funcde p
value
data

Line speed

Not

DP.PAR -

used

DP.LEN -

+-----------------+

3-10 Asynchronous Serial Line (Terminal) Driver

Line parameter 2
Line speed

DP.BUF -

Line parameter 1

Not used

Ref
data
info
v
ML0-838-87

Device class and type information is returned at offsets DP.FDD and DP.FDD+l in the Get and
Set Characteristics reply packets. In those fields:
•

Class is DC$TER for asynchronous serial line interface.

•

Type indicates the specific type of interface:
TT$DL for minimum serial line capability (DLVll, DLVll-J, MXVll-A)
TT$DLE for DLVll-E
TT$DLF for DLVl 1-F
TT$DLT for DLART (SBC-11/21, MXVll-B, KXTll-CA console, CMR21)
TT$DLU for DLART (KXJl 1-CA console)
TT$DM for KXTll-CA or KXJll-CA multiprotocol, data line only port
TT$DMM for KXTl 1-CA or KXJl 1-CA multiprotocol with modem control
TT$DH for DHVl 1
TT$DZ for DZVll

The first and second line parameters (at DP.FDD+2 and DP.FDD+4 in the packets just shown)
are identical to the parml and parm2 arguments used in calls to the TTLIN$ prefix file macro.
(See Section 3.6.) The TT line parameters select the characteristics to be set or report the current
line characteristics.
The format of the first line parameter is shown below:
15

+-----------------------------------------------+
+-----------------------------------------------+
I
I

I
I

+- Output flow control
I

+---- Input flow control

+------------------- Line editing
+---------------------- Echo
ML0-839-87
The four bits labeled above correspond to the TTLIN$ C.xxxx options:
•

Bit 0, if set, enables output flow control (XON/XOFF).

•

Bit 1, if set, enables input flow control (XON /XOFF).

•

Bit 6, if set, enables line editing (line mode for read operations).

•

Bit 7, if set, enables echo of characters as they are read, provided the line-editing bit (6) is
also set.

Asynchronous Serial Line (Terminal) Driver 3-11

The format of the second line parameter is shown below:
15

+-----------------------------------------------+
+-----------------------------------------------+
I
I

I
I

Ring

+---- Carrier Detect
:
+------- Clear to Send
: +---------- Data Set Ready
+------------- Data Terminal Ready
+---------------- Request to Send
+------------------- Enable Modem Interrupt
+------------------------- Assert BREAK
+---------------------------- Enable Baud Rate Set
I
I

I
I

ML0-840-87

Bits 0 (Ring) through 3 (Data Set Ready) are read-only. The remaining labeled bits correspond
to the TTLIN$ E.xxx options. Bits 0 (Ring) through 6 (Enable modem status-change interrupts)
are modem control bits. Proceeding from right to left in the format above:

3-12

•

Bit 0, if set, indicates a Ring, informing the target processor that an incoming call signal is
being received by the modem.

•

Bit 1, if set, indicates Carrier Detect, informing the target processor that the data channel
signal is OK, .receiver is ready.

•

Bit 2, if set, indicates Clear to Send, informing the target processor that the modem is ready
to transmit data.

•

Bit 3, if set, indicates Data Set Ready, informing the target processor that the modem is in
data mode and ready to operate.

•

Bit 4, if set, indicates Data Terminal Ready, informing the modem that the target processor
is ready to transmit or receive data; if clear, the modem disconnects itself from the line.

•

Bit 5, if set, indicates Request to Send, telling modem to enter transmission mode; if clear,
the modem leaves transmission mode after data transmission.

•

Bit 6, if set, enables modem status-change interrupts (only for DLVll-E, KXTll-CA, or
KXJll-CA multiprotocol with full modem control, or DHVll).

•
•

Bit 8, if set, asserts a BREAK (must be cleared by software) .
Bit 9, if set, enables software-setting of the baud rate specified in the TT line speed parameter .
(Device must be jumpered to allow programmable baud rate.)

Asynchronous Serial Line (Terminal) Driver

•

Bits 10 and 11, select character length as follows:
Setting

•
•

Length

00
01
10

Bit 12, if set, generates parity bit for each character. If clear, no parity bits are generated.
Bit 13, if set, generates even parity. If clear, odd parity is generated. This bit has no effect
if bit 12 is clear.

•

Bit 14, if set, generates two stop bits rather than one. (If you have selected a character
length of 5 and you select two stop bits, 1.5 stop bits are generated for each character.) If
clear, one stop bit is generated for each character.

•

Bit 15, if set, modifies the line's framing characteristics through use of the values in bits
10-14. If clear, bits 10-14 have no effect on the line's framing characteristics.

With a KXTll-CA/KXJll-CA multiprotocol chip, if you have selected 5-bit mode, the three
high-order bits of each data byte must be 0, or unpredictable errors occur.
The line speed parameter (at offset DP.FDD+6) contains a value that sets the baud rateprovided the device is jumpered to allow software programming of baud rate and bit 9 of the
second line parameter is set. In a TT Get/Set Characteristics reply packet, the speed parameter
gives the current baud rate.
TKe following shows possible decimal line speed values:
Value

Baud

Notes

Invalid for DLART, KXTll-CA/KXJll-CA multiprotocol

Invalid for DLART, KXTl 1-CA/KXJl 1-CA multiprotocol

110

Invalid for DLART

134.5

Invalid for DLART, KXTl 1-CA/KXJl 1-CA multiprotocol

150

Invalid for DLART

200

Valid only for DLVll type

300

600

1200

1800

Invalid for DLART, KXTll-CA/KXJll-CA multiprotocol

2000

Invalid for DLART, KXTl 1-CA/KXJll-CA multiprotocol

2400

3600

Invalid for DLART, KXT /KXJ multiprotocol, DHVl 1

Asynchronous Serial Line (Terminal) Driver 3-13

Value

Baud

Notes

4800

7200

9600

19200

Invalid for DZVll

38400

Invalid for DLVll-E/F, DZVll

76800

Valid only for KXTll-CA/KXJll-CA multiprotocol

Invalid for DLART, KXTl 1-CA/KXJll-CA multiprotocol

Note
For DHVl 1 line-pairs, two sets of possible baud rates (A and B) are listed in
the DHVl 1 hardware guide. When selecting DHVl 1 baud rates, remember that
both members of a line-pair must use baud rates from the same set.

3.4.4 Set Modem Semaphore Function
The Set Modem Semaphore (IF$SMD) function is used to specify the binary or counting
semaphore to be signaled at each modem interrupt. Modem interrupts are generated when a
change in modem status occurs on a specified line. After issuing this command, you would
normally send a Set Characteristics command, enabling modem status interrupts. Modem
interrupts are supported only by DHVl l, KXTl 1-CA or KXJl 1-CA multiprotocol channel A, and
DLVll-E hardware. To disable modem status signaling, you can send a set command disabling
modem interrupts. To change semaphores, you can send another Set Modem Semaphore
command specifying a different semaphore.
The following shows the function-dependent portions of the Set Modem Semaphore request
and reply packets:
I
I
I

1----------------Semaphore

DP.FDD - :

I
1-1
I
I

1-1
I
I

- DP.FDD
I

structure
ID

1-----------------

Funcdep
value
data

Not used
1-1
I
I

DP.BUF -

Not used

DP.PAR DP.LEN -

+-----------------+

1-1
I
I

1-----------------

1
I

Ref
data
info
v
M L0-840A-87

The binary or counting semaphore specified at offset DP.FDD is placed in the TT driver's
internal control block for the line specified at offset DP. UNI (function-independent portion).
The specified semaphore is signaled whenever a modem control interrupt occurs on a DLVll-E,
DHVll, or KXTll-CA or KXJll-CA multiprotocol channel A.

3-14 Asynchronous Serial Line (Terminal) Driver

The calling program is responsible for issuing a Get Characteristics request to determine the
status on each signal and for taking appropriate action (possibly inclu<;iing a Set Characteristics
operation). The file GETSET .PAS on the MicroPower/Pascal distribution kit provides a model
for getting and changing characteristics.

3.4.5 Stop Request
The Stop Request (IF$STP) function lets you stop an in-progress read. DP .ALN of the read
reply packet contains the number of bytes already transferred to your buffer at the time the
terminal driver begins processing the stop request.
For lines in edit mode, your buffer gets filled with the contents of the edit buffer at the time
the stop request is processed. The number of characters transferred are MIN (characters in edit
buffer, DP.LEN). After your buffer has been filled, any additional characters in the EDIT buffer
are flushed.
DP.STS of the read reply packet contains ES$ABO.
The stop request is returned with a status of ES$NOR. It is returned by the driver after the
stopped read request is returned.
If you have an outstanding Pascal read request (as opposed to packet level 1/0) and a stop
1/0 is issued, the OTS raises an ES$ABO exception for the process that issued the read. You
should be prepared to handle the exception that occurs as a result of the stopping of the read.

Characters that arrive on the line while the stop request is being processed are buffered and
are available for the next read request on that line. These characters are placed in an internal
buffer different from the edit buffer. No characters are transferred from the internal buffer to
the edit buffer or to the user buffer while the stop request is being processed.
If you issue a stop request for a line on which no read request is currently in progress, the
driver returns an ES$NIP (no 1/0 in progress) exception.

3.5 Status Codes
If a serial interface device or the TT driver detects an error during an 1/0 operation, the driver
returns an exception code in the status-code (DP.STS) field of the reply message. If you are
performing 1/0 with Pascal 1/0 statements-that is, not with send/receive statements-the
Pascal OTS will raise the corresponding exception (unless the operation was an OPEN for which
a STATUS return was specified). If no error was detected during the 1/0 operation, the driver
returns a value of ES$NOR (0) in the status-code (DP.STS) field of the reply message.

Asynchronous Serial Line (Terminal) Driver

3-15

The TT driver returns the following exception codes:

Code

Type

Description

ES$FRM

HARD_IO

Framing error

ES$IVP

HARD-10

Invalid parameter: software set of baud rate not allowed for this
device, baud rate illegal for this device

ES$NXU

HARD_IO

Nonexistent unit: invalid unit number

ES$0VF

HARD-10

Data (software buffer) overflow

ES$0VR

HARD_IO

Device overrun

ES$PAR

HARD_IO

Parity error

ES$IFN

SOFT_IO

Illegal function code; also used internally to signal ACP or
OTS that no device-dependent processing of an Open, Close, or
Purge was required

ES$NRF

SOFT-10

No reference data present for read or write request

ES$ABO

SOFT_IO

Read request aborted

ES$NIP

SOFT_IO

No I/O in progress for specified line

Exception codes are defined in the EXC.P AS include file for Pascal users and by the EXMSK$
macro in the COMU /COMM macro libraries for MACR0-11 users.
Note
Not listed above are exception codes for OTS-detected I/O errors or for kerneldetected errors that the TT driver raises rather than passing back to the
requesting process. OTS-detected 1/0 errors are listed in Chapter 9 of the

MicroPower /Pascal Language Guide.

3.6 TT Driver Prefix File
The TT driver prefix module is distributed in four versions-TTPFX.MAC, TTPFXC.MAC (CMR21
version), TTPFXF.MAC (SBC-11/21 version), and TTPFXK.MAC (KXTll-CA and KXJll-CA
versions). The versions differ only in their selection of the default (uncommented) macro calls
for a particular board.
Figure 3-1 shows TTPFX.MAC. The following paragraphs describe the macro calls and symbol
definitions that can be edited to fit your application.
The TTCTR$ macro is invoked once for each controller serviced by the driver. Its parameters
are device type, CSR address, interrupt vector, hardware priority, and number of lines.
Note
The interrupt vector supplied in the prefix file is the receive-side vector for a
given controller; the transmit vector is assumed to follow the receive vector
by 4 bytes. For example, vec=300 implies a corresponding transmit vector at
location 304. Both vectors would be specified in the DEVICES macro in the
system configuration file-for example, "DEVICES ... 300, 304."

3-16 Asynchronous Serial Line (Terminal) Driver

The possible device types are:
•

TT$DL for minimum serial line capability (DLVll, DLVll-J, MXVll-A)

•

TT$DLE for DLVll-E

•
•
•
•
•
•
•

TT$DLF for DLVll-F
TT$DLT for DLART (SBC-11/21, MXVll-B, KXTll-CA console, CMR21)
TT$DLU for DLART (KXJl 1-CA console)
TT$DM for KXTl 1-CA or KXJll-CA multiprotocol, data line only port
TT$DMM for KXTll-CA or KXJll-CA multiprotocol with full modem control
TT$DH for DHVll
TT$DZ for DZVl 1

The TTLIN$ macro is invoked once for each configured line. Its parameters are ISR buffer size,
two parameters (parml and parm2) of status bit-settings, line speed, and edit buffer size.
The options for TTLIN$ parameters parml and parm2, described below, correspond to bit
settings in the TT driver Set Characteristics request packet. The Set Characteristics request can
be used to change line characteristics at run time.
For lines that are to be used by the asynchronous DDCMP (CS) driver for DDCMP message
exchange, you must not enable flow control (XON/XOFF) or line editing. See Chapter 12 for
details.

Note
For serial hardware in which each line is associated with its own CSR/vector
pair, the TTCTR$ and TTLIN$ macros are invoked in pairs for each line. For
example, the DLVll-J is considered a single controller in the hardware sense.
However, each DLVll-J line, by virtue of being associated with a unique
CSR/vector pair, is considered a separate controller by the MicroPower /Pascal
software. So the controller and line macros, TTCTR$ and TTLIN$, must be
invoked in pairs for each DLVl 1-J line.
The following TT$IPR and TT$PPR definitions determine the priority at which the TT driver
process initializes and the priority to which it lowers itself for request processing. Note that
no xx$HPR hardware priority symbol appears. The TT driver, unlike most other standard
MicroPower /Pascal drivers, services several different types of controllers under the umbrella of
a single process. Thus, a different hardware priority is specified-in a TTCTR$ call-for each
controller.

Asynchronous Serial Line (Terminal) Driver 3-17

Figure 3-1:

TT Driver Prefix File (TTPFX.MAC)

.NLIST
.ENABL
.LIST
.TITLE

LC
TTPFX - Terminal/Serial Line Driver Prefix file

This software is furnished under a license and may be used or copied
only in accordance with the terms of such license.
Copyright (c) 1984, 1986 by Digital Equipment Corporation.
All rights reserved .
. mcall
macdf $
drvdf $
ttpfx$

macdf$, drvdf$, ttpfx$

: Define globals symbols needed for the TT process
TT$IPR
TT$PPR

250.
175.

;Initialization priority
;Normal process priority

This is where the user defines the asynchronous lines.
TTCTR$ is used to define the device controller, TTLIN$
defines each of the lines associated with the controller.
TTLIN$(s) must follow (immediately) its (their) TTCTR$ definition.
The order of the TTLIN$ defines the unit numbers. Thus
the first TTLIN$ is unit 0, the second unit 1, etc ....
Options for parm1 are:
C.OFLW
enable output flow control (terminal/host XON/XOFF)
C.IFLW
enable input flow control (host/terminal XON/XOFF)
C.LINE
enable line editing
C.ECHO
If C.LINE has been selected, enable echo of characters
as they are read.

Options for parm2 are:
E.DTR
Set Data Terminal ready (DTR)
E.RTS
Set Request to send
E.DIE
Enable modem interrupts (TT$DLE, TT$DMM, TT$DH)
E.BRK
Set Break (must be cleared by software)
E.PBD
Software set selected baud rate. This option
should only be used if the device is jumpered
to allow software programming of the baud rate.
DLV-11 Console SLU
WARNING: Do not define this line for applications with PASDBG support
foo = C.OFLW!C.IFLW!C.LINE!C.ECHO
; Full XON/XOFF, ECHO, LINE
foo1 = 0
; Use jumpered/default baud rate
ttctr$ type=TT$DL, csr=177560, vector=60, hprio=4, nlines=1
ttlin$ ibuf=20, parm1=foo, parm2=foo1, speed=9600, edtbuf=80.

3-18

Asynchronous Serial Line (Terminal) Driver

DLV-11 SLU2
foo = C.OFLW!C.IFLW!C.LINE!C.ECHO
; Full XON/XOFF, ECHO, LINE
f oo1 = 0
; Use jumpered/default baud rate
ttctr$ type=TT$DL, csr=176500, vector=300, hprio=4, nlines=1
ttlin$ ibuf=20, parm1=foo, parm2=foo1, speed=9600, edtbuf=80.
KXT11--CA/FALCON/CMR21 Console DLART
WARNING: Do not define this line for applications with PASDBG support
foo = C.OFLW!C.IFLW!C.LINE!C.ECHO
; Full XON/XOFF, ECHO, LINE
foo1 = E.PBD
; Set programmed baud rate
ttctr$ type=TT$DLT, csr=177560, vector=60, hprio=4, nlines=1
ttlin$ ibuf=20, parm1=foo, parm2=foo1, speed=9600, edtbuf=80.
KXJ11--CA Console DLART
WARNING: Do not define this line for applications with PASDBG support
foo = C.OFLW!C.IFLW!C.LINE!C.ECHO
; Full XON/XOFF, ECHO, LINE
foo1 = E.PBD
; Set programmed baud rate
ttctr$ type=TT$DLU, csr=177560, vector=60, hprio=4, nlines=1
ttlin$ ibuf=20, parm1=foo, parm2=foo1, speed=9600, edtbuf=80.
FALCON SLU2 DLART ( NOTE: hprio=5 for SLU2
foo = C.OFLW!C.IFLW!C.LINE!C.ECHO
; Full XON/XOFF, ECHO, LINE
foo1 = E.PBD
; Set programmed baud rate
ttctr$ type=TT$DLT, csr=176540, vector=120, hprio=5, nlines=1
ttlin$ ibuf=20, parm1=foo, parm2=foo1, speed=9600, edtbuf=80.
KXT11--CA/KXJ11--CA Multiprotocol channel A (SLU2A) with modem control
foo = C.OFLW!C.IFLW!C.LINE!C.ECHO
Full XON/XOFF, ECHO, LINE
foo1 = E.PBD!E.DTR
; Set baud rate & DTR
ttctr$ type=TT$DMM, csr=175700, vector=140, hprio=4, nlines=1
ttlin$ ibuf=20, parm1=foo, parm2=foo1, speed=9600, edtbuf=80.
KXT11--CA/KX~11--CA Multiprotocol channel B (SLU2B) (Note: Channel B has no
modem control)
foo = C.OFLW!C.IFLW!C.LINE!C.ECHO
; Full XON/XOFF, ECHO, LINE
foo1 = E.PBD
; Set programmed baud rate
ttctr$ type=TT$DM, csr=175710, vector=160, hprio=4, nlines=1
ttlin$ ibuf=20, parm1=foo, parm2=foo1, speed=9600, edtbuf=80.

CMR21 Port 3 (Note Hardware priority = 5)
foo
C.OFLW!C.IFLW!C.LINE!C.ECHO
; Full XON/XOFF, ECHO, LINE
foo1 = E.PBD
; Set programmed baud rate
ttctr$ type=TT$DLT, csr=175620, vector=124, hprio=5, nlines=1
ttlin$ ibuf=20, parm1=foo, parm2=foo1, speed=9600, edtbuf=80.
DZV-11
foo = C.OFLW!C.IFLW!C.LINE!C.ECHO
; Full XON/XOFF, ECHO, LINE
foo1 = E.PBD!E.DTR
; Set baud rate & DTR
ttctr$ type=TT$DZ, csr=160100, vector=310, hprio=4, nlines=4
ttlin$ ibuf=20, parm1=foo, parm2=foo1, speed=9600, edtbuf=80.
ttlin$ ibuf=20, parm1=foo, parm2=foo1, speed=9600, edtbuf=80.
ttlin$ ibuf=20, parm1=foo, parm2=foo1, speed=9600, edtbuf=80.
ttlin$ ibuf=20, parm1=foo, parm2=foo1, speed=9600, edtbuf=80.

Asynchronous Serial Line (Terminal) Driver 3-19

DHV11
foo = C.OFLW!C.IFLW!C.LINE!C.ECHO
; Full XON/XOFF, ECHO, LINE
foo1 = E.PBD!E.DTR
; Set baud rate & DTR
ttctr$ type=TT$DH, csr=160020, vector=320, hprio=4, nlines=8.
ttlin$ ibuf=20, parm1=foo, parm2=foo1, speed=9600, edtbuf=80.
ttlin$ ibuf=20, parm1=foo, parm2=foo1, speed=9600, edtbuf=80.
ttlin$ ibuf=20, parm1=foo, parm2=foo1, speed=9600, edtbuf=80.
ttlin$ ibuf=20, parm1=foo, parm2=foo1, speed=9600, edtbuf=80.
ttlin$ ibuf=20, parm1=foo, parm2=foo1, speed=9600, edtbuf=80.
ttlin$ ibuf=20, parm1=foo, parm2=foo1, speed=9600, edtbuf=80.
ttlin$ ibuf=20, parm1=foo, parm2=foo1, speed=9600, edtbuf=80.
ttlin$ ibuf=20, parm1=foo, parm2=foo1, speed=9600, edtbuf=80.
ttfin$
.end

; Finish up after generating the data structures

3.7 Application Note: Hardware Buffering
TT driver packet-level write requests are not replied to the caller until all data has been given to
the device. Generally this means that all the data except the last two bytes has been transmitted.
If the application requires complete output synchronization-a guarantee that all data has left
the particular serial interface board-it writes one or two null bytes.
The relevant hardware buffering information is given below for each type of serial line controller:

Controller

Buffering

DLVll-J

Double-buffered input, double-buffered output; two null bytes
should be written to guarantee all data has left the board.

DLVll,
DLVll-E,
DLVll-F,
DLART

Double-buffered input, single-buffered output; one null byte should
be written to guarantee all data has left the board.

DHVll

256-character input buffer, DMA output; all data has left the
DUART; only one null byte required to guarantee all data has left
the board.

DZVll

64-character input buffer, single-buffer output; one null byte should
be written to guarantee all data has left the board.

KXTll-CA
or KXJll-CA
multiprotocol
chip

Quadruple-buffered input, double-buffered output; two null bytes
should be written to guarantee all data has left the chip.

3-20 Asynchronous Serial Line (Terminal) Driver

Chapter 4
Disk-Class Device Drivers
This chapter describes the use of the MicroPower/Pascal disk-class device drivers, which support
1/0 operations both on disks and on nondisk media that are treated as disks. The disk drivers
support the mass-storage controllers, media, and protocols listed below:

Driver

Supported Controllers, Media, and Protocols

RLVll controller, RLOl disk (16/18-bit addressing)
RLV12 controller, RL01/RL02 disks (16/18/22-bit addressing)
RLV21 controller, RL01/RL02 disks (16/18-bit addressing)

RXV21 controller, RX02 flexible diskettes (single/double density, 18-bit addressing)

Mass Storage Control Protocol (MSCP) controllers and disks, including RQDXl,
RQDX2, and RQDX3 controllers and RXSO, RD51, RD52, RD53, and RC25 disks
(22-bit Q-bus environment)

Extended (> 65536 blocks) physical disks, partitioned for Pascal 1/0

TU58 DECtape II connected to DLV or KXTl 1-CA/KXJl 1-CA serial line
interface unit

Virtual memory (mapped systems only, requires MMU)

The devices listed above provide mass storage for MicroPower /Pascal target applications.
Note
MSCP is a high-level interface to a family of devices and mass-storage controllers
manufactured by DIGITAL.

Disk-Class Device Drivers 4-1

4. l Disk Driver Features and Capabilities
The disk-class drivers support read and write operations and the returning of device
characteristics.
Logical read or write operations transfer data to or from a buffer in the calling process, starting
at a disk address that is specified (at packet-level) in units of numbered, 512-byte logical blocks.
All RLOl/2, RX02, and MSCP read and write operations use direct-memory-access (DMA)
transfers; TU58 read and write operations use byte transfers; virtual memory read and write
operations use word move (MOV) instructions.
Get Characteristics operations report standard device characteristics, including the storage
capacity per disk unit (or XD partition) in terms of logical blocks.
In addition to logical read and write and Get Characteristics functions, most disk drivers support
operations that are specific to the controllers, media, or protocols they support.
The RLOl/2, RX02, and TU58 drivers support physical read and write operations, which specify
the initial disk or tape address in terms of a track, cylinder, and sector (RLOl/2, RX02) or a
128-byte physical record (TU58).
The RLOl/2 driver supports bad-block replacement, using the manufacturer's bad-block
replacement table, which resides in block 1 of the RLOl or RL02 disk. The table starts at
the first word of block 1 and has the following form:

+--------------------+
bad-blk-num
replcmnt-blk-num
bad-blk-num
replcmnt-blk-num

1--------------------1
l
0
:
+--------------------+
I

ML0-841-87

The bad-blk-num value is the logical block number of the bad block. The replcmnt-blk-num
value is the logical block number of the replacement block. Replacement blocks reside on the
disk's last track-second recording surface, last cylinder. The range of logical block numbers on
the last track is 10220 to 10239 for the RLOl and 20460 to 20479 for the RL02. Logical blocks
on the last track are write protected from access by logical block number; you can access the
replacement area only by physical address. No more than 10 bad blocks are allowed per disk.
The RLOl/2 driver also supports dynamic mounting and dismounting of disk packs. The
driver detects when a new pack has been mounted and reads in a new copy of the bad-block
replacement table. (Control of the mounting of the pack by an operator is the responsibility of
the application program.)
The RX02 driver supports initialization (formatting) of a diskette for single- or double-density
operation.

4-2

Disk-Class Device Drivers

The TU58 driver supports read-with-increased-threshold and write-verjfy options. The extended
disk driver supports the partitioning (subdividing) of disks with greater than 65,536 blocks so
that Pascal file operations can be performed on them. The XD driver helps you overcome two
current limitations on IjO to extended disks:
•

The RT-11 file system's 16-bit orientation, which imposes a 65,536 block limit on an RT-11
directory-structured disk

•

The current OTS and ACP interaction, in which 16 bits are used for I/O transfer
computations with no allowances made for media with block counts that cannot be contained
in 16 bits; this limitation imposes a 65,536 block limit on a non-directory-structured disk
(for example, a disk opened as 'DUAO:')

The XD driver allows you to subdivide an extended disk into multiple partitions of up to 65 ,536
blocks each. You can then OPEN a partition or a named directory file in a partition as if the
partition was a disk itself and perform normal Pascal file operations. (Section 4.3 gives the
OPEN syntax for a named directory file or a non-directory-structured disk unit.)
Conceptually, the XD driver resides "between" the ACP and a physical disk driver (DL, DY, DU),
receiving ACP requests for I/O and translating them into physical-disk driver requests. In the
standard MicroPower/Pascal controller/unit terminology, each physical disk partitioned by the
XD driver is considered a single controller and each partition a unit. Thus, an RD53 configured
as DUAO: (for example) in the DU prefix file could be subdivided into three partitions that
could be referenced in Pascal OPEN statements as 'XDAO:', 'XDAl:', and 'XDA2:'. According
to that mapping, an I/O request for XDAl: would access the second partition of DUAO:.

Note
Another approach to extended disk I/O is to issue send requests directly to
the physical disk driver, bypassing the OTS file routines, the ACP, and the XD
driver (nonfile access).

4.2 Performing Disk 1/0
For most MicroPower/Pascal applications, you perform disk IjO by invoking Pascal I/O
procedures that open files for disk data and then input or output the data, in accordance
with the rules for Pascal I/O. If a file is a named file on a directory-structured disk, you can
also invoke Pascal I/O procedures that initialize the directory or rename, protect, or delete
a file. If the disk is an RX02, you can invoke a Pascal I/O procedure that formats the
disk for single- or double-density operation. Pascal I/O procedures-OPEN, GET, WRITE,
INIT_DIRECTORY, DELETE_FILE, FORMAT_RX02, and so forth-are described in Chapter 9
of the MicroPower /Pascal Language Guide.

Note
The disk driver physical read and write operations cannot be performed with
Pascal I/O procedures. See Section 4.3.
In addition to invoking the Pascal I/O procedures, you must:
1.

Edit the DEVICES macro in the system configuration file to reflect the disk controller
interrupt vector addresses (not applicable for the VM driver)

Disk-Class Device Drivers 4-3

Edit the disk driver prefix file to reflect:
•

Number of controllers

•

[For each controller:] Controller identifier (A, B, ... ),number of controller units and their
identifying numbers (0, 1, ... )

•

[For each nonVM controller:] CSR address and interrupt vector address

•

[For each VM controller (region):] Size of the memory region in 512-byte blocks

•

[For each DD controller:] Serial line type and speed

•

Hardware interrupt priority

•

Driver initialization and request-handling process priorities

[For extended disk partitioning:] Perform steps 1 and 2 to configure the physical disk device
driver(s) for the disks to be partitioned; then edit the XD driver source, XDDRV.PAS, to
reflect:
•

Maximum number of disk blocks per partition (up to 65 ,536)

•

Minimum number of disk blocks per partition

•

Number of physical disks to be partitioned

•

[For each physical disk:] Request queue semaphore name and unit number associated
with the physical disk (see Step 2) and XD request queue semaphore name; for each
physical disk after the first, increase DATA_SP ACE attribute by 456

Edit the ACP prefix file to indicate whether RT-11 directory support is required; the default
is inclusion of directory support

Build into your application the following IJO system components:
•

Disk driver process

•

[For extended disk partitioning:] XD driver, as a user static process (NOT as a system
process, as for other drivers); see Appendix B of the system user's guides for build
details

•

[For disk file OPEN:] Ancillary control process (ACP)

•

Pascal OTS routines for file service-built in automatically by MPBUILD for programs
that invoke Pascal 1/0 procedures-plus any disk 1/0 support routines you opt to
include (see kit files FSPAS.PAS, INTDIR.PAS, GETSET.PAS, and GSINC.PAS)

For more information on setting up your application software for disk 1/0, see Chapter 4 of
the MicroPower/Pascal Run-Time Services Manual, Sections 4.7 and 4.8 of this manual, and the
material on building system processes in the MicroPower/Pascal system user's guide for your
host system.
When a module that contains Pascal 1/0 procedure invocations is built into your application,
Pascal OTS routines for file service are linked to the module. The OTS file routines perform all
Pascal operations on files, including file opening, input, and output. In particular, they perform
the necessary low-level processing of high-level operations such as OPEN and WRITE. Thus, the
basic mechanisms of MicroPower/Pascal 1/0-the sending of request packets to driver or ACP

4-4

Disk-Class Device Drivers

queue semaphores, the dispatching of interrupts, and the signaling of reply semaphores-are
concealed from the Pascal user.
Alternatives to using the Pascal 1/0 procedures for disk I/O exist, but require more effort. You
can:

•

Issue your own Pascal or MACR0-11 packet-level requests to the ACP and the driver,
bypassing the OTS file routines (lower-level file system access).

•

Issue your own Pascal or MACR0-11 packet-level requests to the driver, bypassing the
OTS file routines and the ACP (nonfile access).

The following sections describe the Pascal 1/0 procedure interface to the disk drivers, the
lower-level request/reply packet interface, status codes that can be returned to users of either
interface, extended error information that the DL, DY, and DD drivers return to packet-level
users, and disk driver prefix files.

4.3 Pascal 1/0 Procedure Interface
To perform standard Pascal I/O to a disk, you must open a file. Opening the file associates a
Pascal file variable with a named directory file or a non-directory-structured disk unit. For a
named directory file, invoke the OPEN procedure with:
OPEN (filvar, 'ddcu:filnam.typ', ... )

where:

•
•
•
•
•

filvar is a Pascal file variable .
dd is the driver identifier (DL for RLOl/2, DY for RX02, DU for MSCP, DD for TU58, VM
for virtual memory, XD for extended disk).
c is a controller identifier (A, B, ... ; default is A) .
u is a controller unit number (0, 1, ... ; default is 0) .
filnam. typ is the directory file name .

For a non-directory-structured disk file, invoke the OPEN procedure with:
OPEN (filvar, 'ddcu: ', ... )

where filvar, dd, c, and u are the same syntactic elements described above. For example,
'DYAO:' would specify the first unit (0) of the first RX02 controller (A) listed in the DY driver
prefix file.

Disk-Class Device Drivers 4-5

The number of units supported for each disk-class controller follows:

Controller

Number of Units

Numbering

RLOl/2

1-4 (any
combination of
RLOls and RL02s)

In prefix file

RX02

1-2

0 for left drive and 1 for right in dual-drive

MSCP

1-n

In prefix file

Extended
disk

1-n (partitions),
as determined by
physical disk
size and
user-defined
partition size

0 through (n-1)

TU58

1-2

0 for left drive and 1 for right in dual-drive

Virtual
memory

The number of units configured for each controller and their unit numbers must be specified in
a disk driver prefix file. Typically, unit numbering starts at 0.
The OPEN statement causes the Pascal OTS to send an open request to the ACP, which returns
a channel number and an ACP request semaphore ID to the OTS. That information is used in
subsequent Pascal I/O operations on the unit.
In carrying out subsequent input, output, CLOSE, PURGE, rename, delete, protect, and unprotect
operations on disk units and files, the Pascal OTS and the ACP use the following packet-level
driver functions:

•
•

Read Logical (IF$RDL)

•
•
•

Write Logical (IF$WTL)

•

Close (IF$CLS)

•

Purge (IF$PRG)

•

Protect (IF$PRO)-directory files only

•

Unprotect (IF$UNP)-directory files only

Write Physical (IF$RDP)-for RX02 formatting

Rename (IF$REN)-directory files only
Delete (IF$DEL)-directory files only

The appropriate request packets are sent to the ACP only when necessary to comple,te a userrequested operation. For example, a READ or GET operation that requires more data than what
remains in the buffers from previous input operations causes the OTS to issue one or more
Read Logical (IF$RDL) requests to the ACP. Other Pascal statements unconditionally cause the
OTS to issue send requests; examples are BREAK, which generates a Write Logical (IF$WTL),

4-6 Disk-Class Device Drivers

and CLOSE, which generates a Close (IF$CLS) request (normally preceded by a Write Logical,
unless BREAK immediately precedes CLOSE).
Pascal Get Characteristics functions that report the characteristics of disks are provided in
the file GETSET.PAS on the MicroPower/Pascal distribution kit. Those functions issue Get
Characteristics (IF$GET) request packets to the driver.
The following packet-level driver functions cannot be performed with normal Pascal 1/0
statements or GETSET functions:
•

Read Physical (IF$RDP)

•

Write Physical (IF$WTP)-except for RX02 formatting

To perform these functions, either use the request/reply packet interface directly or write
Pascal procedures that take a user-specified file variable (or queue semaphore ID) and send
the appropriate request packets to the driver. (The Get/Set Characteristics procedures in
GETSET.PAS demonstrate the latter approach.)

4.4 Request/Reply Packet Interface
The packet-level functions provided by the disk-class device drivers are listed below by symbolic
and decimal function code:
Code

Function

IF$RDP (0)
IF$RDL (1)

Read Physical (RLOl/2, RX02, TU58)
Read Logical

IF$WTP (3)
IF$WTL (4)

Write Physical (RLOl/2, RX02, TU58)
Write Logical

IF$GET (7)

Get Characteristics

IF$0NY (8)
IF$BYP (9)
IF$INT (10)

Bypass Only (MSCP- for internal use only)
Bypass (MSCP-for internal use only)
Initialize Port (MSCP-for internal use only)

If a request is received for an Open (IF$LOK or IF$ENT), a Close (IF$CLS), or a Purge (IF$PRG),

the driver returns an illegal function (ES$IFN), which the ACP interprets as indicating that no
device-dependent processing was required for that operation.
Note
The MACR0-11 symbols used in this section are defined by the DRVDF$ macro,
which resides in the COMU and COMM kernel macro libraries. The equivalent
Pascal symbols are defined in the IOPKTS.P AS include file.

Disk-Class Device Drivers 4-7

The function modifiers recognized by the disk-class device drivers are shown below by symbolic
code and bit position:

Code

Function

FM$ WFM (bit 6)

Format device (RX02 Write Physical)

FM$WSD (bit 7)

Format single density (RX02 Write Physical)

FM$BSM (bit 13)

Signal binary/counting semaphore

FM$DCK (bit 14)

Data check (TU58)

FM$INH (bit 15)

Inhibit retries on error (RLOl/2, RX02, MSCP, TU58)

Each disk-class device driver consists of an initialization process, which lowers its priority to
become the first controller's request handler process, plus an additional request handler process
for each configured controller. (For the VM driver, "controller" means "memory region," as
specified in the VM driver prefix file.) Multiple processes within a driver process family share
the same instruction and pure-data segments but require separate RAM for impure data. 1/0
requests intended for a particular controller are sent (using a Pascal SEND or a MACR0-11
SEND$) to the request queue semaphore waited on by that controller's request handler process.
The following shows request queue names and number of supported units for disk driver
requests:

Driver

Request Queue Name

Number of Units

Numbering

RLOl/2

$DLc

1-4 (any combination
of RLOls and RL02s)

In prefix file

RX02

$DYc

1-2

0 for left drive and 1
for right in dual-drive

MSCP

$DUc

1-n

In prefix file

Extended
disk

$XDc

1-n (partitions),
as determined by
physical disk size
and user-defined
partition size

0 through (n-1)

TU58

$DDc

1-2

0 for left drive and 1
for right in dual-drive

Virtual
memory

$VMc

The letter c in a queue name represents a controller designation {A, B, ... -as specified in a
driver prefix file). The number of units configured for each controller and their unit numbers
must be specified in a disk driver prefix file. Typically, unit numbering starts at 0.

4-8

Disk-Class Device Drivers

The general format of the disk request and reply packets follows:
DISK
REQUEST
PACKET

+-----------------+
:
Standard
:·-packet
.-:
header

+-----------------+
Standard

Function

packet

DP.FUN -

DISK
REPLY
PACKET

header
- DP.FUN

DP.UNI -

Unit

- DP.UNI

DP.SEQ -

Sequence number

- DP.SEQ

DP.PDE -

Requesting

Status code

- DP.STS

Actual length

- DP.ALN

identifier

Error info

- DP.ERR

Reserved for

- DP.XTR

semaphore

driver

process

DP.SEM -

identifier

Funcind e p
value
data

usage

DP.DAD -

- DP.FDD
I
I

Request

Func-

dep

value
data
data

data
v

DP.BUF -

Buffer

DP.PAR -

address

Ref
data
info

Buffer length

DP.LEN -

+-----------------+

Reserved
+------------~----+

ML0-842-87

Note
The MACR0-11 field names shown above do not represent offsets into the user's
send or reply buffers; they are offset symbols used by MACR0-11 drivers to
reference packets. For example, DP .FUN is a 6-byte offset from the packet
header.

Disk-Class Device Drivers 4-9

4.4. 1 RLO 1/2 (DL) Functions
4.4. 1. l DL Logical Read and Write
An RLOl/2 logical read or write operation transfers data to or from a user buffer, starting at a
disk address that is specified in terms of a logical block number-0 to 10209 for the RLOl, 0 to
20449 for the RL02.
The unit of storage implied by logical IJO operations is the 512-byte logical block, which
consists of two logically contiguous sectors.
The disk driver converts logical block numbers into physical device addresses-tracks, cylinders,
and sectors. Logical blocks span several sectors and may cross cylinders.
Multisector logical transfers read from or write to logically sequential sectors of the disk.
A write operation that does not fill the last or only block involved causes the remainder of the
block to be zero-filled; this remainder can include the entire second sector of the block.
The RLOl disk has 20 logical blocks per track and 510.5 usable tracks, for a total of 10,210
logical blocks. The RL02 disk has 20 logical blocks per track and 1022.5 usable tracks, for a
total of 20,450 logical blocks.
Note
The last track on an RLOl or RL02 disk, containing the replacement blocks
for bad-block replacement, is write-protected by the DL driver. This track is
excluded from the calculation of usable logical blocks.

In addition, for RT-11 compatibility, the last 10 blocks on the next to last track
of each disk are also excluded from the logical block calculation. The RT-11
RLOl and RL02 drivers reserve these 10 blocks for bad-block replacements. The
DL driver does not use or write-protect these blocks but also does not include
them in the device-dependent information it returns to the caller.
The format used for recording logical blocks is RT-11-compatible: twenty 2-sector logical blocks
per track with a 34-sector per track offset.
All RLOl/2 read and write operations transfer an even number of bytes to or from the user's
buffer because of the word orientation of the device.

4-10

Disk-Class Device Drivers

The following are function-dependent portions of the DL logical read or write request and reply
packets:

DP.DAD

Logical block
- ----------------number

-----------------

- DP.FDD
I
I

Funedep
value
data

Not used

----------------DP.BUF Buffer
DP.PAR
DP.LEN

address

Buffer length
- -----------------

+-----------------+

v
Ref
data
info
v
ML0-843-87

The range of the logical-blk-num value is 0 to 10,209 for the RLOl or 0 to 20,449 for the RL02.
The buffer-length value determines the length, in bytes, of the data transfer.

4.4. 1.2 DL Physical Read and Write
An RLOl/2 physical read or write operation transfers data to or from the user's buffer, starting
at a physical device address specified by absolute track, cylinder, and sector number.
The unit of storage implied by physical 1/0 operations is the 128-word sector. Data transfers
can start at any physical sector of the disk.
A write operation that does not fill the last or only sector involved causes the remainder of the
sector to be zero-filled.
All RLOl/2 read and write operations transfer an even number of bytes to or from the user's
buffer because of the word orientation of the device.

Disk-Class Device Drivers 4-11

The following are function-dependent portions of the DL physical read or write request and
reply packets:
I
I
I

DP.DAD -

-----------------,
Track I Sector :
-----------------,
Cylinder
:
-----------------,
I

--,

Funcdep
value
data

I
--1
I
I

I
I
I

Not used

I
I

DP.BUF -

-----------------,
Buffer
I

DP.PAR -

address

--,

DP.LEN -

- DP.FDD

I
I

I
I
I

-----------------,
Buffer length I

-----------------,

I
I

Ref
data
info
v

+---------~-------+

ML0-844-87

The range of the sector value is 1 to 40.
The track value is 0 or 1.
The range of the cylinder value is 0 to 255 for RLOl or 0 to 511 for RL02.
The buffer-length value determines the length, in bytes, of the data transfer.

4.4. 1.3 DL Get Characteristics
The DL Get Characteristics function returns a block of device-dependent information about a
specified RLOl /2 unit in the function-dependent portion of the reply message. The information
consists of the codes for device class and type, the number of logical blocks per unit-10,210 for
the RLOl and 20,450 for the RL02-and the number of tracks (surfaces), sectors, and cylinders
per unit. The unsafe volume (ES$UNS) error is returned if a disk is not properly mounted for
a Get Characteristics request.

4-12

Disk-Class Device Drivers

The following are function-dependent portions of the DL Get Characteristics request and reply
packets:

DP.DAD -

Type

: Class

- DP.FDD

Funcde p
value
data
Not
used

DP.BUF -

I
I
I
1--

DP.PAR -

1
I
I

1--

DP.LEN -

1
I

+-----------------+

I
I
I

Number of
logical blocks
----------------Tracks : Sectors

(Least
sign if.)
(Most
signif.)

Cylinders

Ref
data
info
v
ML0-845-87

In the reply information above:
•

Class is DC$DSK for disk device class.

•

Type is DK$DL for RL01/RL02 device type.

•

The number of logical blocks, tracks, sectors, and cylinders is given per unit-for one disk.
The number of tracks is reported as 2, indicating two recording surfaces.

4.4. 2 RX02 (DY) Functions
4.4.2.1 DY Logical Read and Write
An RX02 logical read or write operation transfers data to or from a user buffer, starting at an
initial disk address that is specified in terms of a logical block number-0 to 493 for single
density, 0 to 987 for double density.
The unit of storage implied by logical 1/0 operations is the 512-byte logical block. In singledensity mode, a logical block consists of four logically contiguous sectors; in double-density
mode, two logically contiguous sectors. (The sectors are physically noncontiguous because of
the 2:1 sector interleaving algorithm used to read and write logical blocks.)
The disk driver converts logical block numbers into physical device addresses-cylinders and
sectors. Logical blocks span several sectors and may cross cylinders.
Multisector logical transfers read from or write to logically sequential sectors of the disk.
A write operation that does not fill the last or only block involved causes the remainder of
the block to be zero-filled; this remainder can include the entire second' sector of the block in
double-density mode or as many as three complete sectors in single-density mode.
In accordance with DIGITAL and industry standards, cylinder 0 is unused in the organization of
logical blocks on an RX02 diskette; logical block 0 begins at cylinder 1, sector 1. A single-density
diskette has 6.5 logical blocks per cylinder and 76 usable cylinders, for a total of 494 logical
blocks. A double-density diskette has 13 blocks per cylinder and 76 usable cylinders, for a

Disk-Class Device Drivers 4-13

total of 988 logical blocks. (The logical block-recording technique used is RT-11-compatible:
2:1 interleaving with a 6-sector per cylinder offset.)
All RX02 read or write operations transfer an even number of bytes to or from the user's buffer
because of the word orientation of the device. If an odd-value buffer length is specified in the
request (field DP.LEN), the driver assumes one byte as the effective transfer length.
All read or write operations are tried at the density of the last request; the first request is always
tried at single density. If a density error occurs and if retries are inhibited, the opposite density
is set, and the ES$IVM status code is returned to the application program. (The user's program
may then retry the previous request at the new density, if desired; in any case, the new density
will be in effect for the next I/O operation performed on the drive unit.) If a density error
occurs and if retries are not inhibited, the opposite density is set, and the request is retried
automatically. If the density error persists after 10 retries, the ES$IVM status code is returned
to the application program.
The function-dependent portions of the DY logical read or write request and reply packets are
shown below:
I
I
I

DP.DAD -

-----------------1
Logical block
--1
number
-----------------

I
I
I

-----------------, - DP.FDD
Funedep
value
data

Not used

----------------DP.BUF Buffer
DP.PAR -

address

----------------DP.LEN Buffer length
+-----------------+

I
I
I
--1

I
I

--1

Not used

I
I
I

--1
I

I
I
--1
I
I
I

-----------------1
I
I

Ref
data
info
v
ML0-846-87

The range of the logical-blk-num value is 0 to 493 for a single-density RX02 or 0 to 987 for a
double-density RX02.
The buffer-length value determines the length, in bytes, of the data transfer.

4.4.2.2 DY Physical Read and Write
An RX02 physical read or write operation transfers data to or from the user's buffer, starting at
a physical device address specified by absolute cylinder and sector number.
The unit of storage implied by physical I/O operations is the 64-word (single-density) or
128-word (double-density) sector. Data transfers can start at any physical sector of the diskette.
A write operation that does not fill the last or only sector involved causes the remainder of the
sector to be zero-filled.
Two special forms of the physical write function format an RX02 diskette for single-density or
double-density operation. (See the section on DY format subfunctions.)

4-14

Disk-Class Device Drivers

The following are function-dependent portions of the DY physical read or write request and
reply packets:

DP.DAD

Track
Sector
- ----------------I
I

----------------Cylinder
-----------------

- DP.FDD
I
I

Funedep
value
data

Not used

DP.BUF -

----------------Buffer

DP.PAR -

address

DP.LEN -

----------------Buff er length

+-----------------+

v
Ref
data
info
v
ML0-847-87

The range of the sector value is 1 to 26.
The track value is 0.
The range of the cylinder value is 0 to 76.
The buffer-length value determines the length, in bytes, of the data transfer.

4.4.2.3 DY Format Subfunctions of Physical Write
If modifier bits FM$WFM and FM$WSD of the function word are both set in an RX02 Write
Physical (IF$WTP) function request, the meaning of the function is "format diskette for singledensity;" if modifier bit FM$WFM is set and modifier bit FM$WSD is not set, the meaning of
the function is "format diskette for double-density."

The single-density format subfunction reformats a double-density or single-density diskette for
single density, clearing the entire volume in the process. The double-density format subfunction
reformats a single-density or double-density diskette for double density, likewise clearing the
entire volume.
Note
A format operation requires approximately 30 seconds to complete.

Disk-Class Device Drivers 4-15

The function-dependent portions of the request and reply packets for the single- and doubledensity formatting subfunctions of Write Physical are shown below:

DP.DAD -

'0'

I
I
I

-----------------1 - DP.FDD
I
I

'F'

Funcdep
value
data

Not used

I
I
I
I

Not used

DP.BUF -

Ref
data
info

DP.PAR DP.LEN -

+-----------------+

ML0-848-87

The DP.DAD field must contain the ASCII character sequence FO in the first (low-order) word.

4.4.2.4 DY Get Characteristics
The DY Get Characteristics function returns a block of device-dependent information about a
specified RX02 unit in the function-dependent portion of the reply message. The information
consists of codes for the device class and type, the number of logical blocks per unit-494
for single density, 988 for double density-and the number of tracks (surfaces), sectors, and
cylinders per unit. The unsafe volume (ES$UNS) error is returned if a disk is not properly
mounted for a Ger Characteristics request.
The following are function-dependent portions of the DY Get Characteristics request and reply
packets:
l

1-----------------1
DP.DAD 1---1
--1
1-1---1
Not
I

I
I
I

I
I
I
--1
I
I
I

used
DP.BUF

I
I
I

DP.PAR DP.LEN

4-16

--1
--1
--1
I
I
I

I
I

+-----------------+

Disk-Class Device Drivers

:----------------Type
Class
- DP.FDD
----------------Number of
(Least
I
I

I
I

Funedep
value
data

logical blocks

----------------Tracks
Sectors
----------------Cylinders
-----------------

signif.)
(Most
signif.)

v
Ref
data
info
v

ML0-849-87

In the preceding reply information:
•

Class is DC$DSK for disk device class.

•

Type is DK$DY2 for RX02 device type.

•

The number of logical blocks, tracks, sectors, and cylinders is given per unit-for one
diskette. The number of tracks is reported as 1, indicating a single recording surface.

4.4.3 MSCP (DU) Functions
4.4.3. 1 DU Logical Read and Write
An MSCP logical read or write operation transfers data to or from the user's buffer, starting at
a 512-byte logical block specified by a logical block number-0 to n-1, where n is the size of
the disk in logical blocks.
The unit of storage implied by logical 1/0 operations is the 512-byte logical block.
A write operation that does not fill the last or only block involved causes the remainder of the
block to be zero-filled.
Read and write operations to an MSCP disk transfer an even number of bytes to or from the
user's buffer because of the word orientation of the devices.
The following are function-dependent portions of the DU logical read or write request and reply
packets:

DP.DAD -

----------------Not used

----------------Buffer
DP.BUF -

I
I

number

DP.PAR

I
I
I

1----------------- - DP.FDD

----------------Logical block

address

----------------DP.LEN Buffer length
+-----------------+

Funedep
value
data
I
I
I
I

I
I

1-1

I
I

1-1
I
I

Not used

1--

I
I
1-1

I
I

1----------------1

Ref
data
info
v
ML0-850-87

The range of the logical-block-number value is 0 to n-1, where n is the size of the device in
logical blocks.
The buffer-length value determines the length, in bytes, of the data transfer.

Disk-Class Device Drivers 4-17

4.4.3.2 DU Get Characteristics
The DU Get Characteristics function returns a block of device-dependent information about a
specified MSCP unit in the function-dependent portion of the reply message. The information
consists of the codes for device class and type and the number of logical blocks per unit. The
only way to distinguish between MSCP disks is by the number of logical blocks per unit.
The unsafe volume (ES$UNS) error is returned if a disk is not properly mounted for a Get
Characteristics request.
The following are function-dependent portions of the DU Get Characteristics request and reply
packets:
I

I
I

DP.DAD -

,----------------Type
: Class
- DP.FDD
1----------------(Least
Number of
:

I
I

Funcde p
value
data

logical blocks

sign if.)
(Most
sign if.)

Not

Not
used

used

DP.BUF Ref
data
info

DP.PAR DP.LEN -

+-----------------+

v
ML0-851-87

In the reply information above:
•

Class is DC$DSK for disk device class.

•

Type is DK$DU for MSCP disk device type.

•

The number of logical blocks is given per unit-for one disk.

4.4.4 Extended Disk (XO) Functions
4.4.4. 1 XD Logical Read and Write
The XD packet-level read/write functions normally are accessed through the file system, not
through explicit send requests from the user process. You can issue send requests for extended
disk 1/0 to the XD driver, although normally it is preferable to issue the requests directly to
the physical disk device driver. (An exception would be if the XD driver is present in your
application and is accessed both by the file system and by sends, by different processes.)
An extended disk logical read or write operation transfers data to or from the user's buffer,
starting at a 512-byte logical block specified by a logical block number-0 to n-1, where n is
the size of the partition in logical blocks.
The unit of storage implied by logical 1/0 operations is the 512-byte logical block.

4-18

Disk-Class Device Drivers

See the descriptions of the MicroPower/Pascal physical disk device drivers for information on
zero filling of blocks, word or byte orientation of devices, and so forth. An XD driver transfer
takes on the characteristics of the physical-disk driver on which XD is layered.
The following are function-dependent portions of the XD logical read or write request and reply
packets:

DP.DAD

----------------Logical block

- DP.FDD
I
I

number

-----------------

Funedep
value
data

Not used

----------------Buffer
DP.BUF DP.PAR
DP.LEN

address

Buffer length
- -----------------

+-----------------+

v
Ref
data
info

v
ML0-852-87

The buffer-length value determines the length, in bytes, of the data transfer.

4.4.4. 2 XD Get Characteristics
The XD Get Characteristics function returns a block of device-dependent information about a
specified XD partition in the function-dependent portion of the reply message. The information
consists of the codes for device class and type and the number of logical blocks in the partition.
The following are function-dependent portions of the XD Get Characteristics request and reply
packets:
I
I
I

-----------------1
Type
I Class
- DP.FDD
Number of
logical blocks
----------------Not

(Least
signif.)
(Most
signif.)

used

ML0-853-87

Disk-Class Device Drivers 4-19

In the reply information above:
•

Class is DC$DSK for disk device class.

•

Type is DK$XD for extended disk device type.

•

The number of logical blocks is given for the requested partition (DP. UNI).

4.4.5 TU58 (DD) Functions
4.4.5. 1 DD Logical Read and Write
A TU58 logical read or write operation transfers data to or from a user buffer, starting at a tape
address that is specified in terms of a logical block number (0 to 511).
The unit of storage implied by logical I/O operations is the 512-byte logical block, which consists
of four logically contiguous 128-byte records. (The records are physically noncontiguous because
of the automatic interleaving performed by the controller in normal tape addressing mode.)
A write operation that does not fill the last or only block involved causes the remainder of the
block to be zero-filled; that remainder can consist of up to 511 bytes.
If modifier bit FM$DCK of DP .FUN is set to 1 in a TU58 read function request, the driver
instructs the drive to read with increased threshold. That type of read operation can be used to
check for fading data on the tape.
If modifier bit FM$DCK of DP.FUN is set to 1 in a TU58 write function request, the driver
instructs the drive to write with read verify. Following the write portion of the request, the
drive attempts to read the data without errors; the drive returns a status code to the driver,
indicating success or failure. That type of write operation can be used to ensure that reliable
data can later be recovered.

The following are function-dependent portions of the DD logical read or write request and reply
packets:

DP.DAD -

----------------Logical block

- DP.FDD
I
I

number

-----------------

Funedep
value
data

Not used

DP.BUF -

----------------Buffer

address
----------------DP.LEN Buffer length
DP.PAR

+-----------------+

v
Ref
data
info
v
ML0-854-87

The range of the logical-blk-num value is 0 to 511.
The buffer-length value determines the length, in bytes, of the data transfer.

4-20 Disk-Class Device Drivers

If retries were required to complete the operation successfully, a value of ES$NOR (0) is
returned in the status-code (DP.STS) field of the reply packet, and a value of 1 is returned in
the error-info (DP .ERR) field of the packet. The status-code and error-info fields are in the
function-independent portion of the packet.

4.4.5.2 DD Physical Read and Write
A TU58 physical read or write operation transfers data to or from the user's buffer, starting
at a device address specified by a physical record number (0 to 2047). (Tape positioning is
performed in special address mode.)
The unit of storage implied by physical If O operations is the 128-byte record. Data transfers
can start at any physical record on the tape.
Multirecord transfers-exceeding 128 bytes-read from or write to physically sequential records
on the tape.
A write operation that does not fill the last or only record involved causes the last record (up
to 127 bytes) to be zero-filled. The standard record interleaving that is performed for logical
1/0 is disabled for physical 1/0.
If modifier bit FM$DCK of DP.FUN is set to 1 in a TU58 read function request, the driver
instructs the drive to read with increased threshold. That type of read operation can be used to
check for fading data on the tape.
If modifier bit FM$DCK of DP .FUN is set to 1 in a TU58 write function request, the driver
instructs the drive to write with read verify. Following the write portion of the request, the
drive attempts to read the data without errors; the drive returns a status code to the driver,
indicating success or failure. That type of write operation can be used to ensure that reliable
data can later be recovered.

The following are function-dependent portions of the DD physical read or write request and
reply packets:

DP.DAD

Physical rec num
- -----------------

----------------Not
used

----------------DP.BUF Buffer
DP.PAR

DP.LEN -

address

----------------Buffer length
+-----------------+

- DP.FDD

I
I

Funedep
value
data

Not used

I
I
I
I

-----------------1

I
I

Ref
data
info
v
ML0-855-87

The range of the physical-rec-num value is 0 to 2047.
The buffer-length value determines the length, in bytes, of the data transfer.

Disk-Class Device Drivers 4-21

If retries were required to complete the operation successfully, a. value of ES$NOR (0) is
returned in the status-code (DP .STS) field of the reply packet, and a value of 1 is returned in
the error-info (DP.ERR) field of the packet. The status-code and error-info fields are in the
function-independent portion of the packet.

4.4.5.3 DD Get Characteristics
The DD Get Characteristics function returns a block of device-dependent information about a
specified TU58 unit in the function-dependent portion of the reply message. The information
consists .of the codes for device class and type and the number of logical blocks per unit.
In addition to returning device characteristics, the Get Characteristics function performs a seek
operation-to the first block of the directory-in order to determine whether a cartridge is in
the drive. If no cartridge is in the drive, the unsafe volume (ES$UNS) status code is returned
in the function-independent portion of the reply message.
The following are function-dependent portions of the DD Get Characteristics request and reply
packets:
I
I

I
I
I

,----------------DP.DAD -

1----------------Type i Class
- DP.FDD

Func-

Number of

dep

value
data

Not

Not
used

logical blocks

(Least
sign if.)
(Most
signif.)

used

DP.BUF Ref
data
info

DP.PAR DP.LEN -

+-----------------+

v
ML0-856-87

In the reply information above:

4-22

•

Class is DC$DSK for disk device class.

•

Type is DK$DD (TU58) for TU58 device type.

•

The number of logical blocks is given per unit-for one DECtape II cartridge (always 512
blocks).

Disk-Class Device Drivers

4.4.6 Virtual Memory (VM) Functions
4.4.6. 1 VM Logical Read and Write
A virtual-memory-disk logical read or write operation transfers data to or from the user's buffer,
starting at a 512-byte logical block specified by a logical bloc:k number-0 to n-1, where n is
the size of the memory region in logical blocks.
You specify the memory region size in the VM driver prefix file. The unit of storage implied by
logical 1/0 operations is the 512-byte logical block, although of course the number of blocks
you specify is converted to 64-byte PAR ticks for the purpose of allocating the region.
When a read or write request is received, the driver maps the "device" and the user buffer to
P ARs 0 and 1 and then uses the driver subroutine $BLXIO to copy the logical block. ($BLXIO
is described in Chapter 15.) An even number of bytes are transferred between the user buffer
and virtual memory using word move (MOV) instructions. A write operation that does not fill
the last or only block involved causes the remainder of the block to be zero-filled.
The following are function-dependent portions of the VM logical read or write request and reply
packets:
I
I
I

1----------------DP.DAD Logical block
I
I

number

-----------------

- DP.FDD
I
I

Funedep
value
data

Not used

DP.BUF -

I
I
I

DP.PAR -

I
I
I

DP.LEN

I
I

----------------Buffer

1--

address

Buff er length
- ,----------------+-----------------+

v
Ref
data
info
v
ML0-857-87

The range of the logical-blk-num value is 0 to n-1, where n is the size of the device in logical
blocks.
The buffer-length value determines the length, in bytes, of the data transfer.

4.4.6.2 VM Get Characteristics
The VM Get Characteristics function returns a block of device-dependent information about a
specified virtual memory "disk" unit in the function-dependent portion of the reply message.
The information consists of the codes for device class and type and the number of logical blocks
in the memory region (as specified in the VM driver prefix file).

Disk-Class Device Drivers 4-23

The function-dependent portions of the VM Get Characteristics request and reply packets are
shown below:
I
I

:----------------DP.DAD -

Type

I
I

1--

Funcd ep
value
data

1
I
I

1-1
I
I

DP.BUF -

1-1
I

DP.PAR -

1-1
I

Not

- DP.FDD

Number of
logical blocks

(Least
sign if.)
(Most
sign if.)

Not

I
I

used

DP.LEN -

l Class

I
I

I
1-1

+-----------------+

used

Ref
data
info
v
ML0-858-87

In the preceding reply information:
•

Class is DC$DSK for disk device class.

•

Type is DK$VM for virtual memory disk device type.

4.5 Status Codes
If an error is detected during an 1/0 operation by a disk-class device or driver, the driver
returns an exception code in the status-code field of the reply message. If you are performing

IjO with Pascal IjO statements-that is, not with send/receive statements or Pascal support
routine calls-the Pascal OTS will raise the corresponding exception (unless the operation was
an OPEN for which a STATUS return was specified). If no error was detected during the 1/0
operation, a value of ES$NOR (0) is returned in the status-code (DP .STS) field of the reply
message.

4-24

Disk-Class Device Drivers

The disk drivers return the following exception codes:

Code

Type

Description

ES$ABT

HARD_IO

Driver process deleted; request not serviced

ES$CTL

HARD-10

Controller error (DY, DU)

ES$DRV

HARD_IO

Drive error (DL, DU); all retries failed, data check
error, seek error (block not found), motor stopped,
or bad operation code (DD)

ES$FOR

HARD_IO

Media format error (DU)

ES$IBN

HARD-10

Invalid block number on read/write request (DU,
DD, XO)

ES$IDA

HARD_IO

Invalid device address on read/write request (DL,
DY, VM)
.

ES$IVD

HARD_IO

Invalid data (DU)

ES$IVM

HARD_IO

Invalid mode-volume formatted for opposite or
unrecognized density (DY)

ES$IVP

HARD_IO

Invalid request packet parameter-odd buffer address or odd number of bytes to transfer (DL, DY,
DU, VM)

ES$NXM

HARD_IO

Attempted transfer to nonexistent memory or write
to ROM (DL, DY)

ES$NXU

HARD_IO

Nonexistent unit-unit number not defined in
prefix file (DL, DU); drive number greater than
1 (DY, DD); unit number greater than 0 (VM); unit
number not defined in XDDRV (XO)

ES$0FL

HARD-IO

Unit off line (DU)

ES$0VF

HARD_IO

Data overflow (DY)

ES$PAR

HARD_ro

Parity error, CRC error (DL); unrecoverable CRC
error or soft error with no retry (DY)

ES$PWR

HARD_IO

Device power failure (DY)

ES$UNS

HARD_ro

Unsafe volume, drive not ready: door open, power
not OK, drive not up to speed, no volume, no
cartridge in drive (DL, DY, DU, DD)

ES$WLK

HARD_IO

Write-locked unit (DL, DU, DD)

ES$IFN

SOFT_IO

Illegal function code

ES$IVL

SOFT_IO

Invalid length specified (XO)

ES$NRF

SOFT_IO

No reference data present (DD)

Exception codes are defined in the EXC.P AS include file for Pascal users and by the EXMSK$
macro in the COMU/COMM macro libraries for MACR0-11 users.

Disk-Class Device Drivers 4-25

Note
Not listed above are exception codes for OTS-detected 1/0 errors or for kerneldetected errors that the disk drivers raise rather than passing back to the
requesting process. OTS-detected 1/0 errors are listed in Chapter 9 of the
MicroPower /Pascal Language Guide.

4.6 Extended Error Information
The RLOl/2 (DL), RX02 (DY), and TU58 (DD) disk-class drivers return extended error
information to packet-level users.
In the event of a hardware error, the DL driver copies the multipurpose register (MPR) into the
DP.ERR field of the reply packet. See the RLV12 Disk Controller User's Guide for a description
of the MPR.
In the event of a hardware error, the DY driver copies one byte of definitive error code-as
returned by the RXV21 in response to the read error code function-into the DP.ERR field of
the reply packet. That status information is described in the RX02 Floppy Disk System User's

Guide.
For all status returns and hardware error returns in particular, the DD driver returns a hardware
success code in the low-order byte of the DP.ERR field of the reply message. (It is the same
hardware success code returned by the TU58 controller for each operation in byte 3 of the end
packet.) In the event of a hardware error, the hardware success code provides more specific
error information. See the TUSB DECtape II User's Guide for a description of the end packet
sent by the tape controller.

4. 7 Disk Driver Prefix Files
Figures 4-1 through 4-5 show the disk driver prefix modules. The following paragraphs describe
the prefix file macro calls and symbol definitions that can be edited to fit your application.

Note
No prefix module exists for the XD driver. Instead, you edit the XD driver
source module, available on the distribution kit, to fit your application. See
Section 4.8 for details.
The DRVCF$ macro contains a field (nctrl) for the number of controllers (or memory regions)
on the target to be supported by the driver. The dname field specifies the first two characters
of the corresponding request-queue semaphore name.
The CTRCF$ macro is invoked once for each controller to be serviced by the driver. It gives
the controller name, number of units, CSR and vector addresses, and unit numbers. You can
edit those fields, if your controller does not conform to the defaults. For the VM driver, the
memory region size-the number of 512-byte blocks-is specified in place of the CSR and vector
addresses. For the DD driver, the serial line type and speed are specified. The five CTRCF$
invocations in the DD driver prefix file specify a DLVll-type SLU; a KXTll-CA, FALCON, or
CMR21 console DLART; a KXJll-CA console DLART; an SBC-11/21 DLART type SLU; and
a KXTl 1-CA or KXJl 1-CA multiprotocol channel B (SLU2B), each with a line speed of 38400.
(See Chapter 3 for valid serial line types and speeds.)

4-26

Disk-Class Device Drivers

Note
The DU prefix file shows two possible CTRCF$ definitions for a single controller
rather than CTRCF$ definitions for multiple controllers (the normal practice).
The units field specifies the unit numbers of the devices attached to the controller. The
designation 0:1 refers to unit 0 and unit 1. For an RX02 or a TU58, 0 and 1 are the only
possible unit numbers, but you can edit that field if you have only one unit <O> . Note that
<0,1 > and <O:l > are equivalent. For a virtual memory region, 0 is the only possible unit
number.
The interrupt vectors specified in those macros must also be specified in the system configuration
file, using the DEVICES macro.
The xx$IPR, xx$PPR, and xx$HPR definitions specify the initialization and request-handling
software priorities for the disk driver processes and the hardware interrupt priority for the disk
controllers. All controllers associated with a given driver have the same priority. Of course, no
hardware interrupt priority is specified for a virtual memory "controller" (region).
Figure 4-1:

RLO l /RL02 Driver Prefix File (DLPFX.MAC)

.TITLE

DLPFX

- RLV11, RLV21 Prefix File

This software is furnished under a license and may be used or copied
only in accordance with the terms of such license.
Copyright (c) 1982, 1986 by Digital Equipment Corporation.
All rights reserved .
. mcall
DL$IPR
DL$PPR
DL$HPR
drvcf $
ctrcf $
ctrcf $

drvcf$, ctrcf$
250.
175.
4

Process initialization priority
; Process priority
; RLV11 hardware priority

dname=DL,nctrl=1
cname=A,nunits=2. ,csrvec=<174400,160>,units=<0:1>
cname=B,nunits=2. ,csrvec=<174410,164>,units=<0,1>

.end

Disk-Class Device Drivers 4-27

Figure 4-2:
.TITLE

RX02 Driver Prefix File (DYPFX.MAC)
DYPFX

- RX02 Prefix File

drvcf$, ctrcf$

DY$IPR
DY$PPR
DY$HPR

250.
175.
5

drvcf $
ctr cf$
ctrcf$

Process initialization priority
; Process priority
; RX02 hardware priority

dname=DY,nctrl=1
cname=A,nunits=2.,csrvec=<177170,264>,units=<0:1>
cname=B,nunits=2. ,csrvec=<177200,270>,units=<0,1>

.end

Figure 4-3:

MSCP Disk-Class Driver Prefix File (DUPFX.MAC)

.TITLE

OUPFX

- MSCP Micro PDP-11 Prefix File

This software is furnished under a license and may be used or copied
only in accordance with the terms of such license.
Copyright (c) 1983, 1986 by Digital Equipment Corporation.
All rights reserved.
.mcall
DU$IPR
DU$PPR
drvcf $
ctrcf $
ctrcf $

drvcf$, ctrcf$
250.
; Process initialization priority
175.
; Process priority
dname=DU,nctrl=1
cname=A,nunits=3. ,csrvec=<172150,154>,units=<0:2>
cname=A,nunits=3. ,csrvec=<174344,154>,units=<0:2>

.end

4-28

Disk-Class Device Drivers

Figure 4-4:
.nlist
.enabl
.list
. TITLE

TU58 Driver Preftx File (DDPFX.MAC)
LC
DDPFX

1
1

TU58 Device Ori ver Pref ix Module

THIS SOFTWARE IS fURNISHED UNDER A LICENSE AND MAY BE USED OR COPIED
ONLY IN ACCORDANCE WITH THE TERMS OF SUCH LICENSE.
COPYRIGHT (c) 19B2, 1986 BY DIGITAL EQUIPMENT CORPORATION. ALL
RIGHTS RESERVED.
.mcall
.mcall
.mcall
drvdf $
DD$PPR
DD$HPR

drvcf $
ctrcf $
drvdf $
175.
4

Process priority
TU58 hardware priority (must be 5 for Falcon
SLU2)
DD$IPR
250.
Process initialization priority
drvcf$
dname=DD,nctrl=1
;DLV11 type SLU
ctrcf$
cname=A,nunits=2. ,csrvec=<176510,310>,units=<0:1>,typrm=<TT$DL,
;38400>
;KXT11--CA/FALCON/CMR21 Console DLART
ctrcf$
cname=A,nunits=2. ,csrvec=<176560,60>,units=<0:1>,typrm=<TT$DLT,
;38400>
;KXJ11--CA Console DLART
ctrcf$
cname=A,nunits=2. ,csrvec=<176560,60>,units=<0:1>,typrm=<TT$DLU,
;38400>
;FALCON SLU2 DLART
; * Remember to change DD$HPR to 5 if Falcon SLU2 DLART is selected *
ctrcf$
cname=A,nunits=2. ,csrvec=<176540,120>,units=<0:1>,typrm=<TT$DLT,
;38400>
;KXT11--CA or KXJ11--CA Multiprotocol channel B (SLU2B)
ctrcf$
cname=A,nunits=2. ,csrvec=<175710,160>,units=<0:1>,typrm=<TT$DM,
;38400>
.end

Disk-Class Device Drivers 4-29

Figure 4-5:
.TITLE

Virtual Memory Driver Prefix File (VMPFX.MAC)
VMPFX

- Virtual Memory Driver Prefix Module

drvcf$, ctrcf$

VM$IPR
VM$PPR

250.
175.

VMSIZ

<128.>

drvcf$
ctrcf$

Process initialization priority
Process priority
size in blocks (each block is 512. bytes)

dname=VM,nctrl=1
cname=A,nunits=1.,csrvec=<VMSIZ>,units=<O>

.end

4.8 Extended Disk Driver Source Excerpt
Figure 4-6 shows the portions of the extended disk (XD) driver source, XDDRV.P AS, that can
be edited to fit your application.
MAX_UNIT_SIZE, the maximum number of disk blocks for each partition, must not exceed
65 ,536. If there is room for multiple partitions on the disk, every partition, except possibly the
last, will be of this size.
MIN _UNIT_SIZE, the minimum number of disk blocks for each partition, gives the minimum
acceptable value for the last (or only) partition on the disk.
To illustrate the use of MAX_UNIT_SIZE and MIN_UNIT_SIZE, an extended disk with 138,000
blocks for which you specify MAX _UNIT_SIZE = 65000 and MIN _UNIT_SIZE = 100 will have
two 65,000 block partitions (XDAO: and XDAl:) and one 8000 block partition (XDA2:).
NO_DEVICES specifies the number of physical disks to be partitioned.
The PARTITION _ONE_pHYSICAL _UNIT procedure must be called NO_DEVICES times.
For each physical disk to be partitioned, PARTITION _ONE_pHYSICAL _UNIT identifies
the request queue semaphore name and unit number associated with the physical disk
(DEVICE_NAME__)( and UNIT_NUMBER__)() and the XD request queue semaphore name
to be associated with that disk unit (XD_NAME__)(), INDEX indexes into the internal array that
holds the control information; by convention, the INDEX value begins at 1 and increments up
to NO_DEVICES.
For each extended disk after the first, increase the DATA_SP ACE attribute by 456.

4-30

Disk-Class Device Drivers

Figure 4-6:

Extended Disk Driver Source File (XDDRV.PAS) Excerpt

[system(micropower), init_priority(250), priority(175),
privileged, data_space(1000)]
program $xddrv;
COPYRIGHT (c) 1986 BY
DIGITAL EQUIPMENT CORPORATION, MAYNARD
MASSACHUSETTS. ALL RIGHTS RESERVED.
*)
{

The XO driver permit~ MicroPower/Pascal to do perform file-structured
I/O to disk devices with
greater than 65536 blocks. It does this by partitioning the
physical disk unit into multiple partitions. Each physical disk
unit is treated as a single controller with one or more logical units.
}

%include 'src:exc'
%include 'src:iopkts'
%include 'src:gsinc'
const
{Define the maximum number of disk blocks per partition.}
{NOTE: Must not exceed 65536.}
max_unit_size = 65536;
{Define the minimum number of disk blocks per partition.}
min_unit_size = 100;
{Define the number of physical disk units which are to be partitioned.}
no_devices = 1;

{Procedure partition_one_physical_unit is invoked no_devices times.}
partition_one_physical_unit(
device_name_x := '$DUA '
unit_number_x := 0,
xd_name_x := '$XDA
index:= 1);
{

Note: For each additional call to partition_one_physical_unit,
increase data_space attribute by 456 (dynamic process
stack and impure area) .
partition_one_physical_unit(
Request queue semaphore name associated with physical disk device.
device_name_x := '$DUA '
Unit number of physical disk device.
unit_number_x := 1,
Request queue semaphore name associated with extended disk.
Should be of the form '$XDc
xd_name_x := '$XDB
Ordinal in range 1,2, ... ,no_devices.
index
2);
}

end. {$xddrv}

Disk-Class Device Drivers 4-31

Chapter 5
TMSCP Tape Driver
This chapter describes the use of the MicroPower/Pascal TMSCP magnetic tape (MU) driver.
The MU driver supports nondirectory-structured 1/0 operations on tape interfaces that use the
Tape Mass Storage Control Protocol (TMSCP)-in particular, the TKSO streaming cartridge tape
interface. The TKSO is used primarily for large-volume data storage or redundant (backup)
storage by MicroPower/Pascal applications.
Note
TMSCP is a high-level interface to a family of tape controllers and devices
manufactured by DIGITAL.

5. l MU Driver Features and Capabilities
The MU driver supports read and write operations and the returning of device characteristics,
plus the tape-specific operations Reposition, Write Tape Mark, and Rewind.
Read and write operations transfer data to or from a buffer in the calling process, starting at
the current tape position.
The Get Characteristics operation reports the TMSCP device class and type.
The Reposition Tape operation repositions the tape to an offset forward or backward from the
current position or forward from the beginning of tape (BOT), as determined by user-specified
modifiers.
The Write Tape Mark operation establishes the end of a logical file.
The Rewind Tape operation repositions to the BOT.

TMSCP Tape Driver

5-1

5.2 Performing TMSCP Tape 1/0
For most MicroPower/Pascal applications and particularly for streaming applications, you
perform TMSCP tape IjO by invoking Pascal support routines-READ-TAPE, REWIND_TAPE,
and so forth. Those routines provide high-level nonfile access to TMSCP tape controllers. The
MU support routines issue Pascal send requests to the request queue semaphore of the MU
driver. The routines are described in Section 5.3.
You can also perform TMSCP tape I/O by invoking Pascal I/O procedures that open files for
tape data and then input or output the data in accordance with the rules for Pascal ljO. The
Pascal I/O procedures-OPEN, GET, WRITE, and so forth-are described in Chapter 9 of the
MicroPower /Pascal Language Guide. However, file-oriented operations are of limited use; one
limitation is that MU tape-specific operations cannot be performed by Pascal I/O procedures.
Optionally, you can modify the Pascal support routines that perform Reposition, Write Tape
Mark, and Rewind operations to accept a file variable. (For a model, see the Get and Set
Characteristics functions in kit file GETSET.PAS.) A more serious limitation is that because of
the nature of Pascal buffering, you must take special care to provide the necessary degree of
input or output synchronization. Pascal ljO is unsuitable for streaming applications.
In addition to invoking the TMSCP support routines or Pascal 1/0 procedures, you must:
1.

Edit the DEVICES macro in the system configuration file to reflect the TMSCP controller
interrupt vector addresses

Edit the MU driver prefix file to reflect:

•
•

Number of controllers
[For each controller:] Controller identifier (A, B, ... ), CSR address, interrupt vector
address, number of controller units (1) and identifying number (0)

•

Hardware interrupt priority

•

Driver initialization and request-handling process priorities

Build into your application the following I/O system components:
•

MU driver process

•

Pascal TMSCP support routines (from kit files MUSUB.P AS and MUINC.P AS)

•

[For MU file OPEN only:] Ancillary control process (ACP)

•

Pascal OTS routines for file service-built in automatically by MPBUILD for programs
that invoke Pascal I/O procedures-plus any other I/O support routines you opt to
include (see kit files GETSET.P AS and GSINC.PAS)

For more information on setting up your application software for TMSCP tape IjO, see Chapter
4 of the MicroPower /Pascal Run-Time Services Manual, Section 5.7 of this manual, and the
material on building system processes in the MicroPower/Pascal system user's guide for your
host system.

5-2

TMSCP Tape Driver

Alternatives to using the TMSCP support routines or the Pascal I/O procedures for TMSCP
tape 1/0 exist, but require more effort. You can:
•

Issue your own Pascal or MACR0-11 packet-level requests to the driver, bypassing the
Pascal support routines for nonfile I/O, as well as the ACP and the OTS file routines
(low-level nonfile access)

•

Issue your own Pascal or MACR0-11 packet-level requests to the ACP and the driver,
bypassing the ors file routines (lower-level file system access)

The following sections describe the Pascal support routine interface to the MU driver, the Pascal
I/O procedure interface, the lower-level request/reply packet interface, the status codes that
can be returned to users of any interface, and the MU driver prefix file.

TMSCP Tape Driver 5-3

5.3 Pascal Support Routine Interface
The following support routines, written in Pascal and independent of the file system, provide a
high-level interface to TMSCP tape controllers:
•

READ_TAPE procedure

•
•
•
•
•

WRITE_TAPE procedure
REPOSITION _'.fAPE procedure
WRITE_TAPE_MARK procedure
REWIND_TAPE procedure
INIT_TAPE_CNTL procedure-for internal use only
Note
The TMSCP support routines use all of the packet-level MU driver functions
except Get Characteristics (IF$GET). To perform that operation, use the
Get Characteristics function (descriptor version) in the distribution kit file
GETSET .PAS.

The following sections describe Pascal support routines for TMSCP tape I/O. Each routine
allocates an I/O packet, fills it in with information based on the procedure parameters, sends it
to the MU driver queue semaphore for the specified port, and returns immediately to the caller.
If the routine has a reply parameter, the driver sends a standard driver reply via the specified
queue semaphore when the operation is complete. (The driver reply packets are described in
Section 5 .5.)
Note
The distributed support routines assume a unit number of 0 for each operation.
The following files on the MicroPower/Pascal distribution kit are required for using the routines:

File

Description

MUSUB.PAS

TMSCP routine source module

MUINC.PAS

TMSCP routine include file

IOPKTS.PAS

Pascal 1/0 include file

To use a source module, you must compile it and then merge it with the program at user-process
build time. The associated include files must be included in the program at compile time.

5-4 TMSCP Tape Driver

5.3. l READ_TAPE
The READ_TAPE procedure requests a read operation, which transfers data to the user's buffer
from the current tape position. The length of the specified buffer determines the length of the
data transfer.
The packet-level equivalent of READ_TAPE is the IF$RDL function.
The syntax for calling the procedure is as follows:
READ_TAPE (buffer, mu_desc, reply);

Parameter

Type

Description

VAR buffer

PACKED ARRAY
[first.last:
INTEGER] of CHAR

Data buffer

VAR mu_desc

STRUCTURE_DESC

Initialized driver queue semaphore descriptor

VAR reply

STRUCTURE_DESC

Optional initialized reply queue semaphore
descriptor; if specified, it is the user's
responsibility to wait for the reply

The count of bytes transferred is returned in the actual-length field of the MU driver reply
packet.

5.3.2 WRITE_TAPE
The WRITE_TAPE procedure requests a write operation, which transfers data from the user's
buffer to the current tape position. The length o[ the specified buffer determines the length of
the data transfer.
The packet-level equivalent of WRITE_TAPE is the IF$WTL function.
The syntax for calling the procedure is as follows:
WRITE_TAPE (buffer, mu_desc, reply);

Parameter

Type

Description

VAR buffer

PACKED ARRAY
[first ..last:
INTEGER] of CHAR

Data buffer

VAR mu_desc

STRUCTURE_DESC

Initialized driver queue semaphore descriptor

VAR reply

STRUCTURE_DESC

Optional initialized reply queue semaphore
descriptor; if specified, it is the user's
responsibility to wait for the reply

The count of bytes transferred is returned in the actual-length field of the MU driver reply
packet.

TMSCP Tape Driver 5-5

5.3.3 REPOSITION_TAPE
The REPOSITION_TAPE procedure requests that the tape be repositioned to a point that is
specified either by use of a generic object count or by use of record and tape-mark counts.
Note
For tape-specific operations, the relevant units are records, tape marks (which
indicate the end of a logical file), and objects (a context-dependent term for
either records or tape marks).
Depending on user-specified modifiers, the tape can be repositioned to an offset forward or
backward from the current position or forward from the BOT.
The packet-level equivalent of REPOSITION _TAPE is the IF$REP function.
The syntax for calling the procedure is as follows:
REPOSITION_TAPE

ocount, mcount, mod_oper, mu_desc, reply);

Parameter

Type

Description

ocount

LONG_INTEGER

Object offset if the Object-Count modifier
is specified; otherwise a record offset-the
number of objects or records to skip

mcount

LONG_INTEGER

Tape-mark offset-the number of tape
marks to skip; not applicable if the ObjectCount modifier is specified

mod_oper

UNSIGNED

Function-modifier values: Rewind value (2)
for repositioning from BOT, Object-Count
value (4) for use of object offsets, or Reverse
value (6) for reverse repositioning

VAR mu_desc

STRUCTURE_DESC

Initialized driver queue semaphore descriptor

VAR reply

STRUCTURE_DESC

Optional initialized reply queue semaphore
descriptor; if specified, it is the user's
responsibility to wait for the reply

When both record and tape-mark offsets are specified, the tape-mark offset is observed first. For
example, with the Rewind modifier set, a record offset of 10 (decimal) and a tape-mark offset
of 2 would reposition the tape to the eleventh record of the third file.
Indication of success or failure is returned in the MU driver reply packet.

5-6 TMSCP Tape Driver

5.3.4 WRITE_TAPE_MARK
The WRITE_TAPE_MARK procedure establishes the end of a logical file by writing a tape
mark at the current position.
The packet-level equivalent of WRITE_TAPE_MARK is the IF$MRK function.
The syntax for calling the procedure is as follows:
WRITE_TAPE_MARK ( mu_desc, reply ) ;

Parameter

Type

Description

VAR mu_desc

STRUCTURE_DESC

Initialized driver queue semaphore descriptor

VAR reply

STRUCTURE_DESC

Optional initialized reply queue semaphore
descriptor; if specified, it is the user's
responsibility to wait for the reply

Indication of success or failure is returned in the MU driver reply packet.

5.3.5 REWIND_TAPE
The REWIND_TAPE procedure requests that the tape be rewound to the BOT. It is logically
equivalent to doing a REPOSITION_TAPE with an offset of 0 and the Rewind modifier set.
The packet-level equivalent of REWIND_TAPE is the IF$RWD function.
The syntax for calling the procedure is as follows:
REWIND_TAPE ( mu_desc, reply);

Parameter

Type

Description

VAR mu_desc

STRUCTURE_DESC

Initialized driver queue semaphore descriptor

VAR reply

STRUCTURE_DESC

Optional initialized reply queue semaphore
descriptor; if specified, it is the user's
responsibility to wait for the reply

Indication of success or failure is returned in the MU driver reply packet.

TMSCP Tape Driver 5-7

5.4 Pascal 1/0 Procedure Interface
To perform standard Pascal I/O to a TMSCP tape controller, you must open a file. Opening
the file associates a Pascal file variable with a tape controller untt. Invoke the OPEN procedure
as follows:
OPEN (filvar, 'MUcO:', ... )
where:
•

filvar is a Pascal file variable.

•

c is a controller identifier (A, B, ... ).

For example, 'MUAO:' would specify unit 0 of the first TMSCP controller (A) listed in the MU
prefix file.
The OPEN statement causes the Pascal OTS to send a packet-level open request to the ACP,
which returns a unit number and a driver request semaphore ID to the OTS. Subsequent 1/0
requests are sent directly to the driver by the OTS with no further ACP involvement.
In carrying out subsequent input, output, CLOSE, or PURGE operations on TMSCP units, the
Pascal OTS uses the following packet-level driver functions:
•

Read Logical (IF$RDL)

•

Write Logical (IF$WTL)

•

Close (IF$CLS)

•

Purge (IF$PRG)

The appropriate request packets are sent to the driver only when necessary for completion of
a user-requested operation. For example, a READ or GET operation that requires more data
than what remains in the buffers from previous input operations causes the OTS to issue one or
more Read Logical (IF$RDL) requests to the MU driver. Other Pascal statements unconditionally
cause the OTS to issue send requests; examples are BREAK, which generates a Write Logical
(IF$WTL), and CLOSE, which generates a Close (IF$CLS) request (normally preceded by a Write
Logical, unless BREAK immediately precedes CLOSE).
Pascal functions that report the characteristics of MU-driver-supported hardware are provided
in the file· GETSET.PAS on the MicroPower/Pascal distribution kit. Those functions issue Get
Characteristics (IF$GET) request packets to the driver.
The following packet-level driver functions cannot be performed with normal Pascal I/O
statements or GETSET functions:
•

Reposition Tape (IF$REP)

•

Write Tape Mark (IF$MRK)

•

Rewind Tape (IF$REW)

To perform these functions, use the Pascal support routines for nonfile 1/0 (see the preceding
section), use the request/reply packet interface directly, or write Pascal procedures that take a
user-specified file· variable and send the appropriate request packets to the driver. (The Get
Characteristics procedures in GETSET.PAS demonstrate the latter approach.)

5-8 TMSCP Tape Driver

5.5 Request/Reply Packet Interface
The packet-level functions provided by the TMSCP driver are listed below by symbolic and
decimal function code:

Code

Function

IF$RDL (1)

Read Logical

IF$WTL (4)

Write Logical

IF$GET (7)

Get Characteristics

IF$0NY (8)
IF$BYP (9)
IF$INT (10)

Bypass Only-for internal use only
Bypass-for internal use only
Initialize Port-for internal use only

IF$REP (11)
IF$MRK (12)
IF$RWD (13)

Reposition Tape
Write Tape Mark
Rewind Tape

If a request is received for an Open (IF$LOK or IF$ENT), a Close (IF$CLS), or a Purge

(IF$PRG), the driver returns an illegal function status code (ES$IFN), which the ACP (Open)
or OTS (Close/Purge) interprets to mean that no device-dependent processing was required for
that operation.
Note
The MACR0-11 symbols used in this section are defined by the DRVDF$ macro,
which resides in the COMU and COMM kernel macro libraries. The equivalent
Pascal symbols are defined in the IOPKTS.P AS include file.

The function modifiers recognized by the MU driver are shown below by symbolic code and
bit position:

Code

Function

FM$BSM (bit 13)

Signal binary/ counting semaphore

FM$INH (bit 15)

Inhibit retries on error

The MU driver consists of an initialization process, which lowers its priority to become the
first controller's request handler process, plus an additional request handler process for each
configured controller. I/O requests for a particular controller are sent (using a Pascal SEND or
a MACR0-11 SEND$) to the request queue semaphore waited on by that controller's request
handler process.

TMSCP Tape Driver 5-9

The request queue name and number of supported units for MU driver requests are shown
below:

Driver

Request
Queue Name

Number
of Units

Numbering

TM SCP

$MUc

The letter c in a quel:le name represents a controller designation {A, B, ... , as specified in an MU
driver prefix file).
The general format of the TMSCP request and reply packets is shown below:
TMSCP
REQUEST
PACKET

+-----------------+
Standard

I
I
I

,-,--

I
I
I

packet

I
I
I

header

,----------------DP.FUN Function
,----------------DP.UNI Unit
,----------------DP.SEQ Sequence number
,----------------DP.PDB Requesting
I
I
I
I
I
I

I
I

I
I
I

,-,-I

I
I

process

I
I
I
I
I
I
I
I
I
I

Funeindep
value
data

identifier

,----------------DP.SEM Reply
I
I
I

,-,-I
I
I

semaphore

I
I
I

identifier

----------------DP.DAD Request

I
I

Funedep
value
data

data

DP.BUF -

----------------Buffer

DP.PAR -

address

----------------Buffer length
DP.LEN +-----------------+

v
Ref
data
info
v

I
I
I

----------------Function
- DP.FUN
----------------Unit
- DP.UNI
----------------Sequence number
- DP.SEQ
----------------Status code
- DP.STS
----------------Actual length
- DP.ALN
----------------Error info
- DP.ERR
----------------Reserved for
- DP.XTR
driver

--,
--,

TM SCP
REPLY
PACKET

usage

I
I
I

--,
I

I
I

-----------------1 - DP.FDD
I
I
I

Reply data

--,

----------------Not
used

----------------Reserved

I
I

--,

I
I
I

--1
+-----------------+ ML0-859-87
I
I

The function-independent portions of the packets shown above are described in Section 1.3,
Request/Reply Packet Interface. The valid function and function-modifier codes for the function
(DP.FUN) field and the valid unit numbers for the unit (DP.UNI) field are listed at the beginning
of this section.

5-10

TMSCP Tape Driver

The function-dependent portions of the request and reply packets are described in the sections
that follow for each type of TMSCP driver function.
Note
The MACR0-11 field names shown above do not represent offsets into the user's
send or reply buffers; they are offset symbols used by MACR0-11 drivers to
reference packets. For example, DP.FUN is a 6-byte offset from the packet
header.

5.5. 1 Read and Write Functions
A TMSCP read or write operation transfers data between the user's buffer and the current tape
position.
The following are function-dependent portions of the MU read or write request and reply
packets:

- DP.FOO

Not used

,----------------I

!
I

ML0-860-87

The buffer-length value determines the length, in bytes, of the data transfer.

TMSCP Tape Driver

5-11

5.5.2 Get Characteristics Function
The MU Get Characteristics function returns the codes for TMSCP device class and type in the
function-dependent portion of the reply message.
The following are function-dependent portions of the MU Get Characteristics request and reply
packets:

DP.DAD -

Type

l Class

- DP.FDD

I
I

Funcdep
value

Not

data

Not
used

used

DP.BUF DP.PAR -

Ref
data

DP.LEN -

info
v

+-----------------+

ML0-861-87

In the reply information above:
•

Class is DC$TAP for tape device class.

•

Type is MT$MU for TMSCP tape device type.

5.5.3 Reposition Tape Function
The Reposition Tape function requests that the tape be repositioned to a point that is specified
either by use of a generic object count or by use of record and tape-mark counts.
Note
For tape-specific operations, the relevant units are records, tape marks (which
indicate the end of a logical file), and objects (a context-dependent term for
either records or tape marks).
Depending on user-specified modifiers, the tape can be repositioned to an offset forward or
backward from the current position .or forward from the BOT.

5-12

TMSCP Tape Driver

The following are function-dependent portions of the MU Reposition request and reply packets:

DP.DAD -

----------------Modifiers
----------------Object
offset

Funedep
value
data

offset

Not used

Ref
data
info
v

----------------Tape-mark

----------------DP.BUF DP.PAR DP.LEN -

- DP.FDD
I
I

+-----------------+

Not used

ML0-862-87

The modifier word can specify the following:
•

Rewind value (2) for repositioning from the BOT

•

Object-Count value (4) for use of object offsets

•

Reverse value (6) for reverse repositioning

If the Object-Count modifier is set, the object-offset field gives the number of objects (records
or tape marks) to skip, and the tape-mark-offset field is ignored. Otherwise, the object-offset
and tape-111ark-offset fields give the numbers of records and tape marks to skip. In the latter
case, the tape-mark offset is observed before the record offset. For example, with the Rewind
modifier set, a record offset of 10 (decimal) and a tape-mark offset of 2 would reposition the
tape to the eleventh record of the third file.

5.5.4 Write Tape Mark Function
The Write Tape Mark function establishes the end of a logical file by writing a tape mark at the
current position.
The function-dependent portions of the Write Tape Mark request and reply packets are not
used.

5.5.5 Rewind Tape Function
The Rewind Tape function requests that the tape be rewound to the BOT. It is logically
equivalent to doing a Reposition with an offset of 0 and the Rewind modifier set.
The function-dependent portions of the MU Rewind request and reply packets are not used.

TMSCP Tape Driver 5-13

5.6 Status Codes
If an error is detected during an I/O operation by a tape device or the MU driver, the driver
returns an exception code in the status-code (DP.STS) field of the reply message. If you

are performing I/O with Pascal I/O statements-that is, not with send/receive statements or
Pascal support routine calls-the Pascal OTS will raise the corresponding exception (unless the
operation was an OPEN for which a STATUS return was specified). If no error is detected
during the I/O operation, a value of ES$NOR (0) is returned in the status-code (DP.STS) field
of the reply message.
The MU driver returns the following exception codes:

Code

Type

Description

ES$ABT

HARD_IO

I/O request canceled or port reinitialized

ES$BOT

HARD_IO

Beginning of tape encountered

ES$CTL

HARD_IO

Controller error, formatter error, or position lost

ES$DRV

HARD-10

Drive error

ES$IBN

HARD_IO

Invalid block number

ES$IVD

HARD_IO

Data error

ES$IVP

HARD_IO

Invalid command, host buffer access error

ES$NXU

HARD-10

Nonexistent unit

ES$0FL

HARD_IO

Device off line

ES$0VF

HARD-10

Data overflow, record data truncated

ES$UNS

HARD_IO

Unsafe volume

ES$WLK

HARD_IO

Write-protected unit

ES$EOF

SOFT_IO

Tape mark encountered

ES$IFN

SOFT_IO

Illegal function

Exception codes are defined in the ESCODE.P AS include file (included by EXC.PAS) for Pascal
users and by the EXMSK$ macro in the COMU/COMM macro libraries for MACR0-11 users.
Note
Not listed above are exception codes for OTS-detected I/O errors or for
kernel-detected errors that the driver raises rather than passing back to the
requesting process. OTS-detected IjO errors are listed in Chapter 9 of the

MicroPower /Pascal Language Guide.

5-14 TMSCP Tape Driver

5. 7 MU Driver Prefix File
Figure 5-1 shows the TMSCP tape driver prefix module. The following paragraphs describe the
prefix file macro calls and symbol definitions that can be edited to fit your application.
The DRVCF$ macro contains a field for the number of controllers on the target to be supported
by the driver. The dname field specifies the first two characters of the corresponding request
queue semaphore name.
The CTRCF$ macro is invoked once for each controller to be serviced by the driver. It gives
the controller name, number of units (1), CSR and vector addresses, and unit number (0). The
interrupt vectors must also be specified in the system configuration file, using the DEVICES
macro.
The MU$IPR, MU$PPR, and MU$HPR definitions specify the initialization and request-handling
software priorities for the driver process and the hardware interrupt priority for the controller(s).
Figure 5-1:
.title

TMSCP Tape Driver Prefix File (MUPFX.MAC)

MUPFX

- TMSCP Micro PDP-11 driver prefix module

THIS SOFTWARE IS FURNISHED UNDER A LICENSE AND MAY BE USED OR COPIED
ONLY IN ACCORDANCE WITH THE TERMS OF SUCH LICENSE.
COPYRIGHT (c) 1983, 1986 BY DIGITAL EQUIPMENT CORPORATION. ALL RIGHTS
RESERVED .
. mcall
.mcall
MU$PPR
MU$HPR
MU$IPR
drvcf$
ctrcf$

drvcf$
ctrcf$
175.
4

250.

Process priority
MSCP hardware priority
Process initialization priority

dname=MU,nctrl=1
cname=A,nunits=1. ,csrvec=<174500,300>,units=<O:O>

.end

TMSCP Tape Driver 5-15

Chapter 6
Parallel Line Drivers
This chapter describes the use of the MicroPower/Pascal parallel line drivers, which support
1/0 operations on devices connected through parallel line interfaces. The parallel line drivers
support the interfaces listed below:
Driver

Supported Interfaces

DRVl 1-J 64-bit parallel interface (four 16-bit ports)

DRVll 16-bit parallel interface

DRVl 1-B DMA interface

SBC-11/21 8255 PIO interface

KXTl 1-CA/KXJl l-CA
8-bit parallel ports (16-bit if linked)
4-bit special-purpose IjO ports
16-bit counter/timers

The supported devices interface parallel lines to a MicroPower /Pascal target processor so that
block data transfers can be performed.
DRVl 1-B block transfers use direct memory access, minimizing processor involvement. It is
also possible to coordinate the YK driver with the KXTl 1-CA and KXJl 1-CA DMA (QD) driver
to effect DMA block transfers through a KXTl 1-CA or KXJll-CA parallel port.

Note
Unlike other MicroPower/Pascal drivers, the DRVl 1 (YA) driver is not included
in the driver object libraries. It is distributed as two source modules-the driver
proper (YADRV.PAS) and the driver prefix file (YAPFX.PAS). It is available for
applications that require it and/or as a base for editing and/or as an example
of a device driver coded in Pascal.
The DRVl 1-J (XA) driver is distributed in both object and source form; source
modules XADRV .MAC and XAPFX.MAC are available as a base for editing.

Parallel Line Drivers 6-1

6. l Parallel Line Driver Features and Capabilities
The parallel line drivers support block-mode read and write operations and returning of device
characteristics.
Read and write operations transfer a specified number of data bytes to or from the caller's buffer.
For the DRVll-J, DRVll, and DRVll-B, data is transferred by word. For the SBC-11/21 PIO
interface, data is transferred by byte. For the KXTl 1-CA and KXJl l-CA PIO interface, data is
transferred by byte or (if two ports are linked) by word. An even number of bytes must be
specified for devices that do word transfers.
KXTll-CA and KXJll-CA parallel port read/write operations have pattern recognition
capabilities, by which a transfer can be made to terminate when a specified pattern is found or
a search limit is reached.
Get Characteristics operations report standard device characteristics, including device class and
type.
In addition to read, write, and Get Characteristics operations, most of the drivers support
operations that are specific to the interfaces they support.
The XA driver supports enabling or disabling of special interrupt functions on DRVl 1-J port
A. In the standard, factory-jumpered DRVll-J configuration, port A provides 12 sense lines
(0 to 11), each capable of generating unique interrupt requests. These lines are particularly
useful for monitoring specific points in your application environment (for example, in process
control applications). The remaining four bits in port A monitor the four user-reply signals
(USER RPLY A to USER RPLY D) on the DRVll-J's two 1/0 connectors. These four bits are
capable of generating interrupt requests in response to events in or requests by your hardware.
In addition to the interrupt functions of port A, all 16 lines can be used for 1/0 operattons as
provided through ports B, C, and D.
The selection of low-active or high-active signals for generating interrupt requests and the
selection of rotating or fixed priority for interrupts within each of two 8-bit interrupt groups are
made in the XA driver prefix file. See Section 6.8.1 for details.
The DRVl 1-B Set Characteristics function establishes internal default CSR settings to be used
for subsequent DMA transfers. Initial default settings of those bits are determined in the YB
driver prefix file. The settable bits include bits that control the initiation of DMA transfers and
three function bits available for user-defined purposes.
The KXTl 1-CA/KXJl 1-CA PIO (YK) driver supports pattern recognition on PIO reads and
writes, DMA transfers, use of a KXTl 1-CA or KXJl 1-CA parallel port (in coordination with the
KXTl 1-CA/KXJl 1-CA DMA driver), and the setting, reading, and clearing of the KXTl 1-CA
and KXJll-CA counter/timers. Many types of 1/0 operations are possible, depending on how
the parallel ports and counter/timers are configured and programmed. See Section 6.8.5 for
information on different configurations. Bidirectional mode is not supported.

6-2

Parallel Line Drivers

6.2 Performing Parallel 1/0
For most MicroPower /Pascal applications-except KXTl 1-CA and KXJl 1-CA target applications-you perform parallel I/O by invoking Pascal I/O procedures that open files for parallel
line data and then input or output the data, in accordance with the rules for Pascal I/O. The
Pascal I/O procedures-OPEN, GET, WRITE, and so forth-are described in Chapter 9 of the

MicroPower /Pascal Language Guide.
File-oriented operations on the KXTl 1-CA or KXJl 1-CA parallel ports are allowed but are of
limited usefulness, because the YK pattern setting, DMA transfer, and counter/timer functions
cannot be performed by Pascal I/O procedures. For most MicroPower/Pascal applications, you
perform KXTll-CA or KXJll-CA PIO by invoking Pascal support routines-YK_pORT_READ,
YK_SET_PATTERN, YK_READ_TIMER, and so forth. Those routines provide high-level
nonfile access to the KXTl 1-CA or KXJll-CA parallel ports and counter/timers. (Optionally,
you can modify the pattern setting and counter/timer routines to accept a file variable.) The YK
support routines issue Pascal send requests to the request queue semaphore of the YK driver.
The routines are described in Section 6.4.2.

Note
The DRVl 1-J (XA) driver sense line Enable and Disable operations also cannot
be performed with Pascal I/O procedures. See Section 6.3 for more information
on such operations.
In addition to invoking the Pascal I/O procedures, or KXTll-CA or KXJll-CA support routines,
you must:
1.

Edit the DEVICES macro in the system configuration file to reflect the parallel-line controller
interrupt vector addresses

Edit the parallel line driver prefix file to reflect:

•

Number of controllers

•

[For each controller:] Controller identifier (A, B, ... ), CSR address, interrupt vector
address, number of controller units and their identifying numbers (0, 1, ... )

•

Hardware interrupt priority

•

Other hardware/interface characteristics, such as DRVll-J sense-line signal and priority
settings, DRVll-B default CSR settings, or KXTll-CA or KXJll-CA parallel port and
timer port attributes

•

Driver initialization and request-handling process priorities

Build into your application the following I/O system components:
•

Parallel line driver process

•

[For non-file-oriented KXTll-CA or KXJll-CA PIO:] Pascal KXTll-CA and KXJll-CA
PIO support routines (from kit files YK.P AS and YKINC.P AS)

•

[For parallel line file OPEN:] Ancillary control process (ACP)

Parallel Line Drivers 6-3

•

Pascal OTS routines for file service-built in automatically by MPBUILD for programs
that invoke Pascal 1/0 procedures-plus any file-oriented support routines you opt to
include (see kit files GETSET.PAS and GSINC.PAS)
Note
In addition to the KXTl 1-CA and KXJl 1-CA PIO support routines
and file-oriented support routines in the kit files mentioned above, the
MicroPower/Pascal distribution kit provides support routines for non-fileoriented, non-interrupt parallel 1/0 on the SBC-11/21 board. Those routines,
discussed below and in Section 6.4, do not require the OTS file-service routines,
the ACP, or the YF driver.

For more information on setting up your application software for parallel 1/0, see Chapter
4 of the MicroPower/Pascal Run-Time Services Manual, Section 6.8 of this manual, and the
material on building system processes in the MicroPower/Pascal system user's guide for your
host system.
When a module that contains Pascal 1/0 procedure invocations is built into your application,
Pascal OTS routines for file service are linked to the module. The OTS file routines perform all
Pascal operations on files, including file opening, input, and output. In particular, they perform
the necessary low-level processing of high-level operations such as OPEN and WRITE. Thus, the
basic mechanisms of MicroPower/Pascal 1/0-the sending of request packets to driver or ACP
queue semaphores, the dispatching of interrupts, and the signaling of reply semaphores-are
concealed from the Pascal user.
Alternatives to using the Pascal 1/0 procedures for parallel 1/0 exist, but require more
effort. (The PIO support routines for KXTl 1-CA, KXJll-CA, and SBC-11/21 applications
were mentioned previously in this section.) You can:
•

Issue your own Pascal or MACR0-11 packet-level requests to the ACP and the driver,
bypassing the OTS file routines (lower-level file system access).

•

[For KXTll-CA, KXJll-CA or SBC-11/21 PIO:] Invoke Pascal routines that support nonfile-oriented parallel 1/0 (high-level nonfile access).

•

Issue your own Pascal or MACR0-11 packet-level requests to the driver, bypassing the OTS
file routines, the ACP, and the Pascal support routines for nonfile 1/0 (low-level nonfile
access).

The following sections describe the Pascal 1/0 procedure interface to the parallel line drivers,
the Pascal support routines, the lower-level request/reply packet interface, the status codes that
can be returned to users of any interface, and the parallel line driver prefix files.

6-4

Parallel Line Drivers

6.3 Pascal 1/0 Procedure Interface
To perform standard Pascal I/O to a parallel line, you must open a file. Opening the file
associates a Pascal file variable with a parallel controller unit. Invoke the OPEN procedure as
follows:
OPEN (filvar, 'ddcu:', ... )

where:
•

filvar is a Pascal file variable.

•

dd is the driver identifier (XA for DRVll-J, YA for DRVll, YB for DRVll-B, YF for SBC11/21 PIO, YK for KXTl 1-CA and KXJll-CA parallel ports-KXTl 1-CA and KXJll-CA
counter/timers not accessible).

•

c is a controller identifier (A, B, ... ).

•

u is a controller unit number (0, l, ... ).

For example, 'XAAl:' would specify the second unit (1) of the first DRVll-J controller (A)
listed in the XA driver prefix file.
Note
The DRVll (YA), SBC-11/21 PIO (YF), and KXTl 1-CA and KXJll-CA PIO
(YK) drivers do not support multiple controllers; specify A for the controller
identifier.
The number of units supported for each parallel line controller is shown below:

Controller

Number of Units

Numbering

DRVll-J

[For read/
write:] 1-4
[For packetlevel Enable/
Disable:] 1-12

0 through 3 for
ports A through D
4 through 15 for port A
lines 0 through 11

DRVll

DRVll-B

SBC-11/21 PIO

1-2

0 and 1 for ports
A and B

KXTll-CA or
KXJl 1-CA PIO

1-6

0 through 2 for ports A through
C and 3 through 5 for timers 1
through 3 (timer units cannot be
accessed by Pascal I/O procedures)

The number of units actually configured for each controller and their unit
numbers must be specified in a parallel line driver prefix file.
The OPEN causes the Pascal OTS to send a packet-level open request to the ACP, which returns
a unit number and a driver request semaphore ID to the OTS. Subsequent I/O requests are
sent directly to the driver by the OTS, with no further ACP involvement.

Parallel Line Drivers 6-5

In carrying out subsequent input, output, CLOSE, or PURGE operations on parallel line controller
units, the Pascal OTS uses the following packet-level driver functions:
•

Read Logical (IF$RDL)

•

Write Logical (IF$WTL)

•

Close (IF$CLS)

•

Purge (IF$PRG)

The appropriate request packets are sent to the driver only when necessary for completion of
a user-requested operation. For example, a READ or GET operation that requires more data
than what remains in the buffers from previous input operations causes the ors to issue one
or more Read Logical (IF$RDL) requests to the parallel line driver. Other Pascal statements
unconditionally cause the OTS to issue send requests; examples are BREAK, which generates
a Write Logical (IF$WTL), and CLOSE, which generates a Close (IF$CLS) request (normally
preceded by a Write Logical, unless BREAK immediately precedes CLOSE).
Pascal Get and Set Characteristics functions that report or alter the characteristics or status of
supported parallel interfaces are provided in the file GETS ET.PAS on the MicroPower /Pascal
distribution kit. Those functions issue Get and Set Characteristics (IF$GET and IF$SET) request
packets to the driver.
The following packet-level driver functions cannot be performed with normal Pascal I/O
statements or GETSET functions:

•

XA Enable (IF$ENA)

•
•
•
•
•
•
•
•

XA Dis.able (IF$DSA)
YK Set Pattern (IF$YKP)
YK DMA Read (IF$YKR)
YK OMA Write (IF$YKW)
YK DMA Complete (IF$YKE)
YK Set Timer (IF$YKS)
YK Clear Timer (IF$YKU)
YK Read Timer (IF$YKT)

To perform those functions, use Pascal support routines (available for KXTl 1-CA or KXJll-CA
PIO only), use the request/reply packet interface directly, or write Pascal procedures that take
a user-specified file variable (or queue semaphore ID) and send the appropriate request packets
to the driver. (The Get/Set Characteristics procedures in GETSET.PAS demonstrate the last
approach.)

6-6

Parallel Line Drivers

6.4 Pascal Support Routines
The following support routines, written in Pascal and independent of the file system, provide
alternative high-level interfaces to the SBC-li/21 and KXTll-CA or KXJll-CA PIO hardware:
•

SET_PIO_MOOE procedure

•

REAO_PIO function

•
•
•
•

WRITE_PIO procedure

•
•

YK_SET_TIMER function

•

YK_CLEAR_TIMER function

YK_pORT_REAO function
YK_PORT_WRITE function
YK_SET_P ATTERN function

YK_REAO_TIMER function

The first three routines support SBC-11/21 8255 PIO in noninterrupt mode and are independent
of the SBC-11/21 PIO driver. They are used to set up and access the PIO ports directly from
a user process, using programmed 1/0.
The remaining routines support KXTll-CA or KXJll-CA PIO via the YK driver. The KXTll-CA
and KXJl 1-CA routines use all the YK packet-level functions, except the following:
•

Get Characteristics (IF$GET)

•

OMA Read (IF$YKR)

•

OMA Write (IF$YKW)

•

OMA Complete (IF$YKE)

Note
A non-file-oriented· Get Characteristics function is provided in the distribution
kit file GETSET .PAS.
See Section 6.4.2.4 for details on the use of a KXTl 1-CA/KXJll-CA parallel
port for OMA transfers.
The following sections describe the Pascal functions for non-file-oriented parallel 1/0 on the
SBC-11/21 and the KXTll-CA or KXJll-CA.

Parallel Line Drivers 6-7

6.4. l SBC-1 l /21 PIO Support Routines
The SBC-11/21 ;PIO routines allow you to set up and access the SBC-11/21 PIO ports directly
from a user process, with no driver involvement. (This differentiates those routines from most
MicroPower/Pascal support routines, which send packet-level requests to drivers.) The routines
support the SBC-11/21 on-board 8255 PIO in mode 0 (noninterrupt mode). In mode 0 there
are two 8-bit data ports (A and B) and a third dual 4-bit port (C). The lower half of port C is
permanently connected as an input. Ports A and B and the upper half of port C can be used
as either input or output, as determined by wire-wrap jumpers on the SBC-11/21 board.
The following files on the MicroPower/Pascal distribution kit are required for using the functions:
Name

Description

YFDRVP.PAS

SBC-11/21 noninterrupt PIO routine source module

YFDRVI.PAS

SBC-11/21 noninterrupt PIO routine include file

To use a source module, you must compile it and then merge it with the program at user-process
build time. The associated include file must be included in the program at compile time.
The following SBC-11/21 data structures, defined in YFDRVI.PAS, are referenced throughout
the rest of this section:
TYPE
port_sel = (port_a, port_b, port_c_low, port_c_high);
mode_sel = (Ainput_Binput_Cinput, Ainput_Binput_Coutput,
Ainput_Boutput_Cinput, Ainput_Boutput_Coutput,
Aoutput_Binput_Cinput, Aoutput_Binput_Coutput,
Aoutput_Boutput_Cinput, Aoutput_Boutput_Coutput);

6.4. 1. 1 SET_PIO_MODE
The SBC-11/21 procedure SET_pJO_MODE sets one of eight modes, each of which represents
a different combination of input/ output settings for the three ports.
The syntax for calling the procedure is as follows:
SET_PIO_MODE (mode);

Parameter

Type

Description

mode

mode_sel

Mode selected-one of the eight possible combinations of
input/output settings for ports A, B, and C (high)

6.4.1.2 WRITE_PIO
The SBC-11/21 procedure WRITE_pIO writes a value to a user-specified port.

6-8 Parallel Line Drivers

The syntax for calling the procedure is as follows:
WRITE_PIO ( port, outdat ) ;

Parameter

Type

Description

port

port_sel

Port selected

outdat

INTEGER

Value to be written-must be in 8-bit or 4-bit value range
as appropriate for the port

6.4. 1.3 READ_PIO
The SBC-11/21 function READ_PIO reads a user-specified port and returns a value of type
INTEGER.
The syntax for calling the function is as follows:
READ_PIO ( port

Parameter

Type

Description

port

port_sel

Port selected

6.4.2 KXTl 1-CA/KXJl 1-CA PIO and Counter/Timer Support Routines
Each KXTll-CA or KXJll-CA PIO routine allocates an I/O packet, fills it with information
based on the function parameters, and sends it to the YK driver.

If a reply semaphore is provided in the call, the function returns immediately after sending the
driver request. When the operation is complete, the driver sends a standard device driver reply
via the specified semaphore. (The driver reply is described in Section 6.5.) The completion
status returned in the reply packet must be processed by a routine that is waiting on the
semaphore. For PIO read/write operations, the routine that waits on the semaphore must also
process the actual-length information in the packet.
If no reply semaphore is provided, the function waits for the driver reply before returning to
the caller.
The KXTl 1-CA and KXJl 1-CA PIO functions allow you to issue multiple requests for a single
KXTl 1-CA or KXJl 1-CA parallel port. Thus, you can set up a double-buffering type of operation,
with a second buffer starting to be filled/sent while a first buffer is returned/acknowledged to
the caller.
In addition, pattern-matching commands can be issued in conjunction with the PIO transfer
commands. For example, consider a case in which a buffer is to be filled until a special
character is received and then a second buffer is to be filled until a different special character
is received. The function calls to accomplish are a YK_SET_PATTERN, a YK_pORT_READ,
a second YK_SET_pATTERN, and a second YK_pORT_READ. All four calls can be issued
without waiting for a reply from any of them. You can continue processing until signaled that
the first portion has been received; then the device driver can continue receiving the second
portion while you are processing the first.

Parallel Line Drivers 6-9

The following files on the MicroPower/Pascal distribution kit are required for using the functions:
Name

Description

YK.PAS

KXTll-CA and KXJll-CA PIO and counter/timer function
source module

YKINC.PAS

KXTll-CA and KXJll-CA PIO, C/T function and driver
packet include file

To use a source module, you must compile it and then merge it with the program at user-process
build time. The associated include files must be included in the program at compile time.
The following data type from YKINC.PAS is referenced throughout this section; it defines the
YK unit numbers for the support routine interface:
TYPE
UNIT_NUMBER =
PORT_A ,
PORT_B ,
PORT_C ,
TIMER_! ,
TIMER_2 ,
TIMER_3 )

{ Port A }
{ Port B }
{ Port C }
{ Timer 1 }
{ Timer 2 }
{ Timer 3 }

6.4.2. 1 YK-PORT_READ
The YK_pORT_READ function transfers data from a parallel port to a KXTl 1-CA or KXJl 1-CA
buffer and returns a completion-status value of type UNSIGNED. See Section 6.6 for a list of
completion-status values.
The syntax for calling the function is as follows:
YK_PORT_READ ( port_num, buffer, byte_count, reply, match_rst, seq_num )

Parameter

Type

Description.

port_num

UNIT-NUMBER

Number of port to be read from.

VAR buffer

UNIVERSAL

Data buffer address; if omitted, a "signal
semaphore only" operation is implied, and the
byte count must be 0.

VAR byte_count UNSIGNED

Number of bytes to be read. If in patternmatch mode, the count specifies an upper limit
instead of an actual count. If the limit is
reached before the pattern is matched, an error
is reported. When the pattern is found, the
read terminates, and BYTE_COUNT is set to
the actual number of bytes read. In patternmatch mode, the last byte in the buffer will be
the one that matched. BYTE_COUNT is not
returned if the reply parameter is provided.

6-10 Parallel Line Drivers

Parameter

Type

Description.

STRUCTURE_DEsc_pTR

Optional pointer to an initialized reply queue
semaphore descriptor; default is NIL.

match_rst

BOOLEAN

Optional parameter that, if TRUE, causes a
previously set pattern mode to be reset at the
end of the read command;, default is FALSE.

seq_num

UNSIGNED

Optional user-defined word value, returned
unmodified in driver reply packet; default is
0 (0 is returned in reply packet).

If no reply parameter is provided, the function sets the parameter BYTE_COUNT to the count
of bytes transferred by the operation. Otherwise, the count of bytes transferred is returned in
the actual-length field of the YK driver reply packet.

6.4.2.2 YK_PORT_WRITE
The KXT11-CA/KXJ11-CA function YK_PORT_WRITE transfers data from a KXT or KXJ buffer
to a parallel port and returns a completion-status value of type UNSIGNED. See Section 6.6 for
a list of completion-status values.
The syntax for calling the function is as follows:
YK_PORT_WRITE ( port_num, buffer, byte_count, reply, match_rst, seq_num)

Parameter

Type

Description

port_num

UNIT_NUMBER

Port number to be written to.

VAR buffer

UNIVERSAL

Data buffer address.

VAR byte.:._count UNSIGNED

Number of bytes to be written. If patternmatch mode is enabled on at least one of the
output lines, the byte count specifies an upper
limit instead of an actual length. If the limit
is reached before the pattern is matched, an
error is reported. When the pattern is found,
the write terminates, and BYTE_COUNT is
set to the actual number of bytes that were
written. BYTE_COUNT is not returned if the
reply parameter was provided.

STRUCTURE_DESC_PTR

Optional pointer to an initialized reply queue
semaphore descriptor; default is NIL.

match_rst

BOOLEAN

Optional parameter that, if TRUE, causes a
previously set pattern mode to be reset at the
end of the write command; default is FALSE.

seq_num

UNSIGNED

Optional user-defined word value, returned
unmodified in driver reply packet; default is
0 (0 is returned in reply packet).

Parallel Line Drivers 6-11

6.4.2.3 YK_SET_PATTERN
The KXTll-CA/KXJll-CA function YK_SET_pATTERN controls the pattern-recognition features of the peripheral processor. Specifically, it sets pattern-match mode on parallel port A or
B. The setting of pattern-match mode affects subsequent operation of the YK_pORT_READ and
YK_PORT_WRITE functions. In pattern-match mode, a read or a write operation terminates
only when a specified pattern is found in the data or when the user-imposed search limit in
the read or write request (BYTE_COUNT) is reached.
The YK_SET_pATTERN function returns a completion-status value of type UNSIGNED. See
Section 6.6 for a list of completion-status values.
To use pattern matching, you must specify "PAT=YES" for port A or B in the prefix file
port-configuration (YKCP$) macro.
The syntax for calling the function is as follows:
YK_SET_PATTERN ( port_num, mode, reply, patp, patt, patm, pt_buf, seq_num)

6-12

Parameter

Type

Description

port_num

UNIT_NUMBER

Port number.

mode

P AT_MOD_ENTRY

Pattern modifier bits; AND-MODE, the default, indicates that all specified pattern bits
must match.
OR_MODE indicates that
only one of the specified pattern bits must
match. WAIT-MATCH sets wait-for-patternmatch mode. PAT-RESET causes the pattern
mode to be reset after a command. Note that
OR-MODE and AND_MODE are the only
modifiers that are mutually exclusive; all other
combinations are valid.

STRUCTURE_DESC_PTR

Optional pointer to an initialized reply queue
semaphore descriptor; default is NIL.

Parallel Line Drivers

Parameter

Type

Description

patp
patt
patm

BYTE_RANGE
BYTE_RANGE
BYTE_RANGE

The PATP, PATT, and PATM parameters collectively define the match pattern for the specified port. Each bit (0-7) in a PATP, PATT,
or P ATM specification corresponds to a bit (07) in the match pattern; that is, bit n of the
match pattern is defined by the nth bits of
PATP, PATT, and PATM. For each match pattern bit, P ATP supplies pattern polarity information; PATT, pattern transition information;
and P ATM, pattern mask information. For details on the significance of P ATP/PATT /P ATM
bit combinations, see the table and the example
below. The default value for each parameter
is 0.

pt-buf

YKBUF_pT

Optional buffer pointer used only in wait_match
mode; default is NIL. If omitted for wait_match
mode operation, one byte of data-two if ports
are linked-will be returned in first word of
function-dependent portion of YK driver reply
packet.
·

seq_num

UNSIGNED

Optional user-defined word value, returned
unmodified in driver reply packet; default is
0 (0 is returned in reply packet).

The PAT_MOD_ENTRY, PATTERN _MODS, and YKBUf_pT data types, from YKINC.PAS, are
shown below:
TYPE
Pattern_mods =
nu_3 .
nu_4 .
pat_reset .
and_mode .
or_mode .
wait_match )

{ Pattern Function Modifiers }
{ - not used }
{ - not used }
{ - reset pattern at end }
{ - AND pattern mode }
{ - OR pattern mode }
{ - Wait until match mode }

Pat_mod_entry = PACKED SET OF Pattern_mods ;
YKBUF_PT = - UNSIGNED ;

{ data buffer pointer }

Parallel Line Drivers 6-13

The pattern specification for each bit of the match pattern is defined as follows:

PATP

PATT

PATM

Event Recognized

Bit masked off-no event recognized

Any transition

Logical 0 state

Logical 1 state

Logical 1 to logical 0 transition

Logical 0 to logical 1 transition

Note
Do not specify more than one bit to detect transitions if you specify
AND_MQDE.
For example, to set a pattern of bits 0 to 3 = 1 AND bits 5 and 6 = 0 AND bit 7 = logical 1 to
logical 0 transition AND bit 4 ignored, you would pass the following bits in the P ATP, PATT,
and P ATM parameters:
Bit

PATP

PATT

PATM

The following function call would set the desired pattern:
YK_SET_PATTERN (port_num := PORT_A,
mode := [ and_mode ] ,
patp := %0'17',
patt := %0'200',
patm := %0'357')

6-14 Parallel Line Drivers

6.4.2.4 KXT 11-CA/KXJ 11-CA PIO OMA Process
If you want to perform DMA transfers via a KXTl 1-CA/KXJl 1-CA parallel port, you must first
set up and send a DMA Read or a DMA Write request packet to the YK driver and wait for
the reply. If the reply indicates normal status, you then send a DMA transfer command to the
DMA (QD) driver; otherwise, you report a software exception. You must wait for each request
to complete, since only one PIO DMA operation can be in progress at a time. After the DMA
transfer completes, you send a DMA Complete request to the YK driver, which unlocks the
queue of requests for that port.

Observe the following guidelines when performing DMA I/O on a KXTl 1-CA or KXJl 1-CA
parallel port:
•

Use KXTll-CA or KXJll-CA DMA channel B (QD unit 1) for the QD requests. Channel
B is linked to the timer/counter (KXTll-CA or KXJll-CA PIO) chip when you install
the jumper to configure the DMA request lines. (See Section 6.3.12 of the SBC-11/21
Single-Board Computer User's Guide for details on installing the jumper or see the KX/11-CA
Single-Board Computer User's Guide.)

•

Specify "DMA=YES" for the KXTl 1-CA or KXJl 1-CA PIO port in the YK prefix file portconfiguration (YKCP$) macro.

•

Use KXTll-CA/KXJll-CA PIO port A (YK unit 0). Line Cl is connected to the DMA
request line and therefore is not available for handshake for port B. (This means that port
B, if used, must be configured as a bit port.) In the prefix file, line Cl must be set up as an
inverted output so that it works correctly with the DMA request line.

•

In the QD transfer request, specify wait-for-request mode and byte mode. Also, specify
the address of the data CSR for YK port A as 177033 (octal), not 177032 (octal). This is
necessary because the DMA chip addresses bytes in memory in a way different from typical
LSI-11 hardware; the chip's high-order byte is LSI-ll's low-order byte, and vice-versa.
Specify that the data CSR for YK port A is in the I/O page (DMA$ IO option). Use an
even address for the other address.

•

After a transfer, the data in the destination buffer has each byte reversed, again because of
the way the DMA chip addresses bytes. For example, "abed" in a source buffer becomes
"bade" in the destination buffer. Therefore, you should reverse the bytes in each word
before transmitting the data or after receiving the data. (A procedure for reversing the bytes
is shown in the following example.)

Figure 6-1 shows a sample program that uses the YK and QD drivers to perform DMA I/Oona
KXTl 1-CA/KXJll-CA parallel port. Data is transferred from the parallel port to local memory
on the KXTll-CA/KXJll-CA. Note that the program calls the local procedure REVERSE_BUF
after data is received to reverse the bytes in the data buffer.
Figure 6-2 shows the appropriately modified YK driver prefix file. (The YK prefix file is described
in Section 6.8.5.)

Parallel Line Drivers 6-15

Figure 6-1:
{Notes:

KXT 11-CA/KXJ 11-CA PIO OMA Sample Program
1. Can only use Parallel Port A for byte I/O when using the
DMA chip, Port B must be a bit port.
2. Can only use DMA unit 1 for I/0 to YK port.}

[ SYSTEM(MICROPOWER), PRIORITY(50),
DATA_SPACE(2100), STACK_SIZE (200)] PROGRAM yktio;
{$NOLIST}
%include 'mutex.pas'
%include 'ykinc.pas'
%include 'qdinc.pas'
%include 'exc.pas'

{ mutex procedures }
{ get the YK data structures and
handler interface }
{ DMA include files }
{ Get exception processing, it picks
up escode.pas }

{$LIST}
CONST
BUFSIZE
30;
{size of buffer}
INITBUF
'ABCDEFGHIJKLMN OPQRSTUVWXYZ123'; {data for input buffer}
VAR
protect_mutex : mutex;
{screen access protection}
inbuf : PACKED ARRAY[1 .. BUFSIZE] OF CHAR; {buffers}
inbuf_size : UNSIGNED;
{size of buffers}
in_reply_descriptor : STRUCTURE_DESC; {queue semaphore
descriptors for replies}
in_reply_packet : YK_REPLY; {reply packet from driver}
in_status : UNSIGNED; {Dummy status for return by Yk_port_read
and yk_port_write functions}
address_1,address_2 : DMA$ADDRESS;
byte_count : DMA$BYTE_COUNT;
yk_req : yk_port_rqst;
k : integer;
[INITIALIZE] PROCEDURE YK_INIT

{Initialize procedure. Runs once at
startup.}

BEGIN
IF NOT CREATE_QUEUE_SEMAPHORE (DESC := in_reply_descriptor) THEN
WRITELN ('Create semaphore failed');
END ;
{Main program}
BEGIN
FOR k := 1 to BUFSIZE DO {clear the input buffer}
inbuf [k] := ' ';
writeln ('Input buffer initialized');
inbuf_size := bufsize;

6-16 Parallel Line Drivers

{set up dma request to OMA port}
with yk_req do
BEGIN
oper := dma_read;
funct_mods := [];
unit_num := port_A;
reply_sem := in_reply_descriptor.id;
END;
send ( name := '$YKA
{set up in OMA read mode}
val_data := yk_req,
val_length
size (yk_port_rqst) ) ;
receive (val_data := in_reply_packet,
{wait for set up to
complete}
val_length :=size (in_reply_packet),
desc := in_reply_descriptor);
IF in_reply_packet.status <> es$nor THEN
writeln ( 'Error setting up OMA read');
address_1 := DMA$NORM_IBUS_ADDRESS;
address_1.high := %o'77';
Optional since already saying on the i/o page }
address_1.low := %0'177033';
address_1.inc := DMA$NOINC;
address_1.bm := DMA$BYTE;
address_1.io := DMA$IO;
{Address is on the local i/o page}
address_1.wfr := dma$wfr;
address_1.adrtyp := dma$physical; {Address is a physical address}

{

address_2 := DMA$NORM_IBUS_ADDRESS;
address_2.low := (ADDRESS(inBUF)): :UNSIGNED;
{It's a read operation since destination is a plain buffer}
BYTE_COUNT := $DMA_TRANSFER (
{transfer ... }
UNIT := 1,
{ on this unit }
SOURCE := address_1,
{ from DMA port }
DEST := address_2,
{ to the other local buffer }
COUNT := inbuf_SIZE );
{this much}
IF BYTE_COUNT = 0
THEN
REPORT(EXC_TYPE:=[RESOURCE] ,EXC_CODE:=ES$RSC)
ELSE
BEGIN
writeln ('Read successful ',BYTE_COUNT,' bytes');
WRITELN (INBUF);
END;
yk_req.oper := dma_complete; {finish DMA transaction}
send ( name := '$YKA '
val_data := yk_req,
val_length
size (yk_port_rqst) );
receive (val_data := in_reply_packet, {wait for operation to
complete}
val_length :=size (in_reply_packet),
desc := in_reply_descriptor);
IF in_reply_packet.status <> es$nor THEN
writeln ( 'Error finishing up OMA read');
end.

Parallel Line Drivers 6-17

Figure 6-2:

YK Prefix File for PIO OMA Sample Program
.TITLE YKPFXS - Parallel I/0 and counter/timer Driver Prefix Module
.ident /V2.0/

;DEFINE PRIORITIES FOR YK HANDLER
YK$HPR
YK$IPR
YK$PPR

== 5
250.
== 180.

Hardware priority
Initialization priority
Process priority

;CALL:

INITIALIZE MACRO
.MCALL
YKCI$

YKCI$

; PORT A
;Configure as an input port in byte mode with interlocked handshake,
;get DMA support
YKCP$

CHAN=A,PTYPE=YK$INP,HSH=YK$INL,DMA=YES

; PORT B
;Port A used with DMA chip, so one Port C bit normally used for Port B
;handshake is unavailable, therefore Port B must be a bit port.
YKCP$

CHAN=B,PTYPE=YK$BIT

; PORT C
; Interlo.cked handshake signals for Port A (bi ts 2 and 3) ,
;bit 1 is for the DMA request line (MUST BE INVERTED)
YKCP$

CHAN=C,OUT=<YK$B1!YK$B3>,INV=YK$B1

; TIMER 1
;Not used
;+

; TIMER 2
;Not used
;+

; TIMER 3
;Not used
;+

; END CONFIGURATION
YKCE$
.END

6-18

Parallel Line Drivers

6.4.2.5 YILSET_TIMER
The KXTll-CA/KXJll-CA function YK_SET_TIMER can set a timer to an initial value, trigger
a timer after setting it, or set a timer to signal a binary or counting semaphore periodically.
This function can be used in conjunction with the YK_READ_TIMER function to time or count
real-time events. It returns a completion-status value of type UNSIGNED. See Section 6.6 for
a list of completion-status values.
Timers are initialized to a value (timer_value, below) and count down to 0. You subtract the
current value from the initial value to calculate the number of ticks.
The timers count down at a rate of 2MHz, or one tick every .5 microseconds. At that rate,
counting down to 0 from the maximum 16-bit timer value (65536) takes approximately 33
milliseconds. For longer intervals, you can have the timer count from 65536 to 0 several times,
or link two timers together to make a 32-bit timer. (To specify the maximum initial value,
you should enter 0 rather than its equivalent 65536.) To link two timers together, specify
"TLNK=YK$112" in the YK prefix file macro YKCT$. (See the example in Section 6.4.2.9.)
The syntax for calling the function is as follows:
YK_SET_TIMER ( timer_num, timer_value, mode, reply, bin_sem )

Parameter

Type

Description

timer_num

UNIT_NUMBER

Timer number.

timer_value

UNSIGNED

Timer constant (TC) value.

mode

TIMER_MOD_ENTRY

Timer mode; INIT_CONSTANT causes the
timer constant (TC) value to be set, TRIGGER
causes the timer to be triggered after setup, and
CONTIN _CYCLE causes the driver to signal
the binary or counting semaphore bin_sem,
if specified, and restart the timer after each
timeout. If CONTIN _CYCLE is not specified,
the timer just counts down once (single cycle),
and the driver then replies to the user. If timer
mode is omitted, the mode set by the prefix file
or the last timer command remains in effect.

STRUCTURE_DESC_PTR

Optional pointer to an initialized reply queue
semaphore descriptor; default is NIL.

bin_sem

STRUCTURE_DESC_PTR

Optional pointer to an initialized binary or
counting semaphore to be signaled on each
timer timeout; default is NIL.

Parallel Line Drivers 6-19

The TIMER_MOD_ENTRY and TIMER_MODS data types, from YKINC.PAS, are shown below:
TYPE
Timer_mods =
nu_5 ,
nu_6 ,
init_constant ,
trigger ,
nu_7 ,
contin_cycle ) ;

{ Timer Function Modifiers }
{ - not used }
{ - not used }
{ - initialize timer constant }
{ - trigger timer when set up }
{ - not used }
{ - continuous cycle mode }

Timer_mod_entry = PACKED SET OF Timer_mods

Note
If port C is being used to supply handshake signals while timer 3 is being used
as a general-purpose timer, the time constant must be set for timer 3 during
initialization and not changed during operation. The reason is that port C is
disabled during the setting of timer 3' s constant, and therefore the handshake
signals also get disabled.

6.4.2.6 YK_READ_TIMER
The KXTll-CA/KXJll-CA function YK_READ_TIMER reads the current count from a
timer/counter and returns a completion-status value of type UNSIGNED. See Section 6.6
for a list of completion-status values.
The syntax for calling the function is as follows:
YK_READ_TIMER ( timer_num, pt_time, reply )

:t_>arameter

Type

Description

timer_num

UNIT-NUMBER

Timer number.

pt_time

YKBUF_pT

Optional pointer to time variable; default is
NIL; if pointer omitted, timer count value will
be returned in first word of function-dependent
portion of YK driver reply packet.

STRUCTURE_DESC_PTR

Optional pointer to an initialized reply queue
semaphore descriptor; default is NIL.

The YKBUf_pT data type, from YKINC.PAS, is shown below:
TYPE
YKBUF_PT =

6-20 Parallel Line Drivers

UNSIGNED ;

{ data buffer pointer }

6.4.2.7 VK_CLEAR_TIMER
The KXTl 1-CA/KXJl 1-CA function YK_CLEAR_TIMER deactivates a timer/ counter that is
operating in the continuous mode and returns a completion-status value of type UNSIGNED.
See Section 6.6 for a list of completion-status values.
The syntax for calling the function is as follows:
YK_CLEAR_TIMER ( timer_num, reply )

Parameter

Type

Description

timer_num

UNIT_NUMBER

Timer number

STRUCTURE_DEsc_pTR

Optional pointer to an initialized reply queue
semaphore descriptor; default is NIL

6.4.2.8 Using Timer/Counters to Count External Pulses
Figure 6-3 shows a sample program that creates an external pulse counter that is unaffected by
timing delays caused by software. The hardware is set up to stop the counting process at the
instant it presents an interrupt request to the processor.
The example uses timer 1 for counting external pulses and timer 3 for timing the counting
interval. Timer 3 causes the software to be signaled and stops timer 1 from counting by
shutting off its gate input. Thus, when the software reads the number of counts from timer 1,
it will be exact. Timer 3 must be set up to have a one-shot input and run in the noncontinuous
mode to accomplish this. To expand timer 1 into a 32-bit counter, you can link timer 2 to it.
(See Section 6.4.2.9.)

Parallel Line Drivers 6-21

Figure 6-3:

KXT 11-CA/KXJ 11-CA External Pulse Counter Sample Program

[SYSTEM(MICROPOWER)] PROGRAM YKSTIM;
{$NOLIST }
%include 'ykinc.pas'
{$LIST }
CONST
interval_init
20000;
count_init = O;

{O corresponds to maximum initial value,

= 65536}

VAR
yk_io_stat
unsigned;
reply_desc
queue_semaphore_desc;
reply_pkt
yk_reply;
count
unsigned;
BEGIN
IF CREATE_QUEUE_SEMAPHORE (DESC := REPLY_DESC) THEN
BEGIN
{Set an initial value in the timer}
{Contin_cycle needed since in one shot mode the driver does
not reply to the reply semaphore set up by the yk_set_timer
procedure until the timer counts down to 0 and interrupts.
Since we are using it as a counter of external pulses, the
counter should never count down to 0. With contin_cycle,
the driver replies to indicate the status of the set timer
request and then signals a binary or counting semaphore if the
counter counts down to 0. No binary or counting semaphore is
needed since the counter shouldn't count down to 0 before the
interval times out.}
yk_io_stat := YK_SET_TIMER
( TIMER_NUM := timer_1,
TIMER_VALUE := count_init,
MODE := [ init_constant, trigger,
contin_cycle]);
{Now start the time interval for counting pulses}
yk_io_stat
YK_SET_TIMER
( TIMER_NUM := timer_3,
TIMER_VALUE := interval_init,
MODE := [ init_constant, trigger].
REPLY:= ADDRESS (reply_desc));
{Wait for the time interval to expire}
RECEIVE ( VAL_DATA := reply_pkt,
VAL_LENGTH :=SIZE (yk_reply),
DESC := reply_desc);
{Read the current count and convert to # of pulses}
yk_io_stat := YK_READ_TIMER ( TIMER_NUM := timer_1,
PT_TIME :=ADDRESS (count));
count := count_init - count;
WRITELN (count,' pulses were counted');
END;
END.

6-22

Parallel Line Drivers

Figure 6-4 shows the appropriately modified YK driver prefix file. (The YK prefix file is described
in Section 6.8.5.)
Figure 6-4:
.TITLE

YK Prefix File for External Pulse Counter Sample Program
YKPFXT - Parallel I/O and counter/timer Driver Prefix Module
.ident /V2.0/

;DEFINE PRIORITIES FOR YK HANDLER
YK$HPR
YK$IPR
YK$PPR

== 5
== 250.
== 180.

Hardware priority
Initialization priority
Process priority

;CALL:

INITIALIZE MACRO
.MCALL
YKCI$

YKCI$

; PORT A not used
;+

PORT B
; Bit port, Timer 1's gate input via bit 7 and count pulse input via bit 5
; (actually all 8 bits set up as inputs)
YKCP$

CHAN=B,PTYPE=YK$BIT

; PORT C
; Bit port, Timer 3's output via bit 0
YKCP$

CHAN=C,PTYPE=YK$BIT,OUT=YK$BO

; TIMER 1
; Enable timer 1's gate input and count input
YKCT$

TNUM=1,TEXrG=YES,TEXTC=YES

; TIMER 2
; Not used
;+

; TIMER 3
; Enable timer 3's output in one-shot mode
YKCT$

TNUM=3,TEXTO=YES,TOUT=YK$T1S

; END CONFIGURATION
YKCE$
.END

Parallel Line Drivers 6-23

6.4.2.9 Linking Two Timer/Counters as 32-Bit Counter
Figure 6-5 shows a sample program, usable with the distributed YK driver prefix file, that links
KXTl 1-CA/KXJl 1-CA timers 1 and 2 together as a 32-bit counter.
With the values supplied-0 (66536) in timer 1 and 200 in timer 2-timer 1 times out every
.033 seconds, and timer 2 times out every 6.6 (200*.033) seconds.
Figure 6-5:

KXT 11-CA 32-Bit Counter Sample Program

[SYSTEM(MICROPOWER), PRIORITY(100),
DATA_SPACE (3000), STACK_SIZE (800)] PROGRAM YKTIM6;
{$NOLIST }
%include 'ykinc.pas'
%include 'escode.pas'
{$LIST }

{ Status codes }

CONST
clear= ''(27)'[2J'(27)'[H';
VAR
yk_io_stat_2,
yk_io_stat_1
sem_2_bin,
sem_Lbin
bin_worked_2,
bin_worked_1

unsigned;
SEMAPHORE_DESC;
BOOLEAN;

[INITIALIZE] procedure foist;
BEGIN
bin_worked_2 := CREATE_BINARY_SEMAPHORE (DESC := sem_2_bin );
bin_worked_1 := CREATE_BINARY_SEMAPHORE (DESC := sem_1_bin ) ;
END;
procedure els;
BEGIN
write(clear);
END;
BEGIN
els;
IF ((bin_worked_1) AND (bin_worked_2)) THEN
BEGIN
{This timer will be decremented by 1 each time Timer 1 times out. Therefore,
it will count to 0 after 200*33 millisec = 6.6 seconds}
yk_io_stat_2 := YK_SET_TIMER ( TIMER_NUM := timer_2, TIMER_VALUE :=200,
MODE := [ init_constant, trigger, contin_cycle ] ,
BIN_SEM := ADDRESS(sem_2_bin));

6-24 Parallel Line Drivers

IF (yk_io_stat_2 <> es$nor) THEN
BEGIN
WRITELN ( 'Error setting timer 2');
END
ELSE
BEGIN
WRITELN ( 'Timer 2 started up');
END;
{Maximum value - s~ it times out every 33 milliseconds}
yk_io_stat_1 := YK_SET_TIMER ( TIMER_NUM := timer_!, TIMER_VALUE := 0,
MODE := [ init_constant, trigger, contin_cycle ],
BIN_SEM := ADDRESS(sem_1_bin));
IF (yk_io_stat_1 <> es$nor) THEN
BEGIN
WRITELN ( 'Error setting timer 1');
END
ELSE
BEGIN
WRITELN ( 'TIMER 1 STARTED UP');
END;
while true do
begin
wait ( desc := sem_2_bin );
writeln ('timer 2 signaled');
end;
END
ELSE
BEGIN
writeln ( 'Semaphores were not created for timers');
END;
END.

6.5 Request/Reply Packet Interface
The packet-level functions provided by the parallel line drivers are listed by symbolic and
decimal function code as follows:

Code

Function

IF$RDP (0)

Read Physical

IF$RDL (1)

Read Logical (equivalent to Read Physical)

IF$WTP (3)

Write Physical

IF$WTL (4)

Write Logical (equivalent to Write Physical)

IF$SET (6)

Set Characteristics (DRVl 1-B)

IF$GET (7)

Get Characteristics

IF$ENA (8)

Enable (DRVll-J)

IF$DSA (9)

Disable (DRVl 1-J)

Parallel Line Drivers 6-25

Code

Function

IF$YKP (8)

Set Pattern (KXTl 1-CA/KXJl 1-CA PIO)

IF$YKR (9)

DMA Read (KXTl 1-CA/KXJl 1-CA PIO)

IF$YKW (10)

DMA Write (KXTl 1-CA/KXJl 1-CA PIO)

IF$YKE (11)

DMA Complete (KXTl 1-CA/KXJl 1-CA PIO)

IF$YKS (12)

Set Timer (KXTl 1-CA/KXJl 1-CA PIO)

IF$YKU (13)

Clear Timer (KXTl 1-CA/KXJl l-CA PIO)

IF$YKT (14)

Read Timer (KXTl 1-CA/KXJl 1-CA PIO)

If a request is received for an Open (IF$LOK or IF$ENT), a Close (IF$CLS), or a Purge
(IF$PRG), the driver returns an illegal function status code (ES$IFN), which the ACP (Open) or
OTS (Close/Purge) interprets as indicating that no device-dependent processing was required
for that operation.

Note
The MACR0-11 symbols used in this,section are defined by the DRVDF$ macro,
which resides in the COMU and COMM kernel macro libraries. The equivalent
Pascal symbols are defined in the IOPKTS.P AS include file.
The function modifiers recognized by the parallel line drivers are listed by symbolic code and
bit position as follows. All but the last are specific to the KXTl 1-CA/KXJl 1-CA PIO driver
and to a single type of operation:
Code

Function

FM$YKA (bit 9)

AND pattern mode-all bits specified in pattern argument must
match (YK Set Pattern)

FM$YKO (bit 10)

OR pattern mode-match with any bit specified in pattern
argument (YK Set Pattern)

FM$YKW (bit 11)

Sets wait-for-pattern-match mode (YK Set Pattern)

FM$YKT (bit 8)

Trigger timer after setup (YK Set Timer)

FM$YKI (bit 9)

Initialize timer constant value (YK Set Timer)

FM$YKC (bit 11)

Continuous cycle-cause timer to signal a binary or counting
semaphore and restart after each timeout (YK Set Timer)

FM$YKR (bit 8)

Reset pattern mode-reset a previously set pattern mode at the
end of a read or a write (YK PIO port A or Bread/write)

FM$BSM (bit 13)

Signal binary/counting semaphore

The DRVl 1-J (XA) and DRVl 1-B (YB) drivers each consist of an initialization process, which
lowers its priority to become the first controller's request handler process, plus an additional
request handler process for each configured controller. 1/0 requests intended for a particular

6-26 Parallel Line Drivers

controller are sent (using a Pascal SEND or a MACR0-11 SEND$) to the request queue
semaphore waited on by that controller's request handler process.
The DRVl 1 (YA) driver consists of one static process and two dynamic processes-a read process
and a write process. After completing its initialization functions at the initialization priority
specified in the prefix file, the static process lowers its priority and functions as a dispatcher
process for I/O requests. The dispatcher process performs request-handling functions for both
dynamic processes.
The SBC-11/21 PIO (YF) and KXTl 1-CA/KXJl 1-CA PIO (YK) drivers each consist of a single
(static) process. After completing its initialization functions at the initialization priority specified
in a prefix file, each static process lowers its priority and functions as a dispatcher process for
I/O requests.
The following list shows the request queue names and number of supported units for parallel
line driver requests:

Driver

Request
Queue Name

DRVll-J

$XAc

Number of Units

Numbering

[For read/write:]
1-4

0 through 3 for ports A through
D

[For Enable/Disable:]
1-12

4 through 15 for port A lines 0

through 11

DRVll

$YAA

DRVll-B

$YBc

SBC-11/21 PIO

$YFA

1-2

0 and 1 for ports A and B

KXTll-CA or
KXJl 1-CA PIO

$YKA

1-6

0 through 2 for ports A through
C and 3 through 5 for timers 1
through 3

The letter c in a queue name represents a controller designation (A, B, ... , as specified in a
parallel line driver prefix file). The number of units actually configured for each controller and
their unit numbers must be specified in a driver prefix file.

Parallel Line Drivers 6-27

The general format of the parallel I/O request and reply packets is shown below:
PIO
REQUEST
PACKET

+-----------------+
l
Standard
1--

'
I
I

1-1
I
I

+-----------------+
Standard
I
--,

packet

PIO

REPLY
PACKET

header

·----------------DP.FUN - I
Function
1----------------DP. UNI - I
I Unit
·----------------DP.SEQ - I Sequence number
·----------------DP.PDE Requesting
I
I

--,

process

I
I

identifier
DP.SEM -

Reply
semaphore
identifier

DP.DAD I
I

·-'
.--

Request

I
I

1
I
I

,--

data

1
I
I

,----------------Buffer

DP.BUF - :

,-I

DP.PAR -

1
I
I

address

,----------------DP.LEN - : Buffer length
+-----------------+
The function-independent portions of the previous packets are described in the request/reply
packet interface section of Chapter 1. The valid function and function-modifier codes for the
function (DP .FUN) field and the valid unit numbers for the unit (DP. UNI) field are listed at the
beginning of this section.
The function-dependent portions of the request and reply packets are described in the sections
that follow for each type of parallel line driver function.

6-28 Parallel Line Drivers

6.5. 1 ORV 11-J (XA) Functions
6.5. 1. 1 XA Read and Write
The XA read and write functions transfer an even number of' bytes to or from a user-specified
buffer. The function-dependent portions of the XA read/write request and reply packets are
shown below:

DP.DAD -

-----------------

I
I
I

I
I

Not used

DP.BUF -

----------------Buffer

DP.PAR -

address

DP.LEN -

-----------------1 - DP.FDD

----------------Buffer length
+-----------------+

Funedep
value
data

Not used

v
Ref
data
info
v
ML0-864-87

The buffer address, which must be on a word boundary, specifies the destination of the data
to be read or the source of the data to be written. The buffer-length value determines the
length, in bytes, of the data transfer. If the length value is an odd number, the last byte is not
transferred.

Parallel Line Drivers 6-29

6.5. 1.2 XA Get Characteristics
The Get Characteristics function returns a block of device-dependent information.
information consists of device class, type, and subtype.

That

The function-dependent portions of the XA Get Characteristics request and reply packets are
shown below:

DP.DAD

- -----------------

I
I

Type

Funedep
value
data
Not

- DP.FOO

:subtype

Not used

used

DP.LEN -

I Class

DP.BUF

DP.PAR

+-----------------+

Ref
data
info
v
ML0-865-87

In the information above:
•

Class is DC$RLT for real-time device class.

•

Type is RT$DRJ for DRVl 1-J device type.

•

Subtype is dependent on the unit number for XA:
RS$SLN = sense-line subtype (units 4 through 15)
RS$PRT =parallel-port subtype (units 0 through 3)

6.5.1.3 XA Enable
The XA Enable function enables interrupts on a specified interrupt line (unit 4 to 15) of port
A, if the line is masked, and associates the user's signal semaphore with that line. The signal

semaphore is a binary or counting semaphore, distinct from the user's reply semaphore. The
semaphore is signaled each time the corresponding interrupt occurs (line goes active-low). If
the specified interrupt line is already enabled when the request is issued, the Enable function
returns a "line already attached" (ES$DAL) error status. (A Disable request must intervene
between two Enable requests for a given line.)

6-30 Parallel Line Drivers

The function-dependent portions of the XA Enable request and reply packets are shown below:

DP.SGL -

----------------Signal

- DP.FDD
I
I

semaphore
ID

-----------------

Funedep
value
data

Not used

I
I
I
I

v
DP.BUF -

Not used

DP.PAR DP.LEN

+-----------------+

Ref
data
info
v
ML0-866-87

Field DP.SGL specifies, by structure ID, the user's semaphore that is to be attached to the
selected interrupt line. This semaphore is signaled each time an interrupt occurs until that
line is detached. The unit number selects the desired bit-interrupt line; the range of valid unit
numbers is 4 to 15 for port A lines 0 to 11, respectively.

6.5. 1.4 XA Disable
The XA Disable function masks interrupts on a specified interrupt line (unit 4 to 15), severing
the association between that line and a signal semaphore, if any. A Disable request for a
masked line-never enabled or previously disabled-has no effect and returns a normal status.
The function-dependent portions of the XA Disable request and reply packets are not used.

6.5.2 ORV 11 (YA) Functions
6.5.2. 1 YA Read and Write
The YA device driver supports simultaneous input and output on a single unit. The driver
assumes that the REQ A signal represents an output interrupt request and that the REQ B signal
represents an input interrupt request; the driver enables the corresponding DRCSR status bits
for those purposes. Read and write requests transfer an even number of bytes to or from a
user-specified buffer.

Parallel Line Drivers 6-31

The function-dependent portions of the YA read/write request and reply packets are shown
below:
I
I
I

DP.DAD -

1-----------------

I
I

:----------------- - DP.FOO

I
I

Not used

1--

Funcdep
value
data

I
I

1-1

I
I

1--

1-1

I
I
I
I

I
I

1-1
I

1--

DP.PAR - I

--1

address

1-----------------1
DP.LEN - : Buffer length I
+-----------------+
I

I
I

1-1
I
I

Not used

1-1

1--

--1

I
I

1----------------DP.BUF - :
Buffer

I
I

I
I
I

I
I

1-----------------1

Ref
data
info
v
ML0-867-87

6.5.2.2 YA Get Characteristics
The Get Characteristics function returns a block of device-dependent information.
information consists of device class, type, and subtype.

That

The function-dependent portions of the YA Get Characteristics request and reply packets are
shown below:
I

I
I
I

-----------------1
--.

I
I
I

DP.DAD -

I
I

1-1

I
I
1--

DP.BUF -

DP.LEN -

6-32

I
I

Funcde p
value
data

I
I

.--

used

I
I

1-1

+-----------------+

Parallel Line Drivers

1
I

1--

Not

1--

DP.PAR -

I
I

1----------------- DP.FOO
: Type : Class
:----------------:
: Subtype
:--

Not used

:----------------'

Ref
data
info
v

ML0-868-87

In the previous information:
•

Class is DC$RLT for real-time device class.

•

Type is RT$DRV for DRVl l device type.

•

Subtype is RS$PRT (parallel-port subtype).

6.5. 3 ORV 11-B (YB) Functions
6.5.3.1 YB Read and Write
The YB driver supports transfers of up to 32K 16-bit words per request in single-cycle or burst
mode, with 18-bit buffer addressing.
The direction of DMA transfer (user device to memory or vice versa) cannot be directly set
under program control. Instead, the transfer direction is set by the CO and Cl TTL input lines
from the user device to the DRVl 1-B, as follows:

Transfer Type

Memory to user device (DATI)

Memory to user device and back (DATIO)

User device to memory (DATO)

User device to memory (DATOB)

The program controls the setting of the CO and Cl lines by manipulating the user device via
the FNCT l, FNCT 2, and FNCT 3 control lines. The user device must interpret the FNCT
control line settings and then set the appropriate CO and Cl combination.
Read or write requests transfer an even number of bytes to or from a user-specified buffer.
Upon receiving a read or write request, the driver validates the request, sets up the Bus Address
Register (BAR) and the Word Count Register (WCR) to initialize the DMA transfer, and sets the
CSR, based on an internally maintained default CSR setting. The default settings must have
been previously set by YB Set Characteristics commands. Setting the CSR initiates a DMA
transfer either immediately (GO and CYCL bits set) or when the device indicates its readiness
by asserting CYCLE REQUEST for at least 1 microsecond (GO bit set and CYCL bit cleared).
When multiple DMA requests are posted to the driver, the requests are validated and queued
internally to minimize the latency in switching from the completion of one request to initiating
the next request.
Under normal circumstances, the maximum length for the user source or destination buffer is
8128 (decimal) bytes. This ensures that the user's buffer can be mapped using a single driver
process PAR. However, larger buffers are supported, provided they occupy contiguous physical
memory. The limit for buffer size is 64K bytes, which is the limit imposed by the DRVl 1-B
hardware.
For buffers larger than 8128 (decimal) bytes, perform the following steps to ensure that DMA
transfers will take place without accidentally corrupting sections of memory that are being used
for other purposes:

Parallel Line Drivers 6-33

1. Reserve a contiguous block of physical memory for the buffer or buffers. (Multiple buffers
may be required if a second or subsequent DMA transfer in the same direction must be
initiated before the first buffer has been saved or reloaded.) The amount of physical memory
required per buffer is the sum of the whole number of 64-byte blocks required to contain
the buffer. The required memory may be reserved for buffer use by NOT specifying it in
the system configuration file during the application build.
2.

To enable DMA transfers of the required length between the user device and LSI-11 bus (Qbus) memory, the user's process must directly write the appropriate value data and referencedata specification-including an unconfigured-memory PAR value-into the request packet,
and set the "reference-data-present" packet header bit (bit 15 of the control/priority word).
To signal the appropriate YB request queue semaphore, PUT_p ACKET or SGLQ$ must be
used instead of SEND or SEND$ (which supplies configured-memory PAR values). The
user-supplied PAR value will be used by the driver process to map to the base of the user
buffer before initiating transfers.

When the DMA transfers are complete, the user process must map directly to the buffer to
recover/reload the buffer contents page by page.

The DRVl 1-B module is capable of performing DMA in single-cycle mode as well as burst
mode. The default is single-cycle mode. Burst mode cannot be requested directly by the user's
program. Instead, the user device must be placed in a mode where it requests a burst mode
cycle from the DRVl 1-B (by holding SINGLE CYCLE low). The user device can be manipulated
under program control to request single-cycle or burst mode transfers as desired, by using the
FNCT 1, FNCT 2, and FNCT 3 control lines. This assumes that the user device has the necessary
intelligence to interpret those control signals.
The function-dependent portions of the YB read or write request and reply packets are shown
below:
I

1----------------DP.DAD .--

·----------------- - DP.FDD
I

1
I
I

1
I

,--

Funcde p
value
data

1
I

Not used

I
I
I

I
I

Not used
I
I
I

--·
-----------------.
I

DP.BUF -

Buffer

DP.PAR -

address

DP.LEN -

I
I

-----------------,
Buffer length I
+-----------------+

Ref
data
info
v
ML0-869-87

6-34 Parallel Line Drivers

6.5.3.2 YB Set Characteristics
The YB Set Characteristics function establishes internal default CSR settings to be used for
subsequent DMA transfers. The settable bits are the FNCT bits, available for user-defined
purposes; the GO bit, which indicates readiness for a DMA transfer; and the CYCL bit, which
determines whether the transfer is initiated by the LSI-11 bus (Q-bus) arbiter or the user device.
Initial default settings of those bits are determined in the YB driver prefix file.
Upon receiving a Set Characteristics request, the DRVll-B driver clears the CSR, resets the
three FNCT bits according to passed bit values, and resets the default settings of the FNCT,
GO, MAINT, and CYCL bits. The new settings remain in effect until they are explicitly reset.
(Note that only the FNCT bit settings are moved immediately into the CSR.)
The function-dependent portions of the YB Set Characteristics request and reply packets are
shown below:

DP.DAD -

FNCT bit values

- DP.FDD
I

GO bit value
CYCL bit value

Funcdep
value
data

Not used

DP.BUF -

Not used
Ref
data
info

DP.PAR DP.LEN -

+-----------------+

v
ML0-870-87

The three CSR value fields shown above correspond to the YB prefix file symbols YB$FNC,
YB$GO, and YB$CYC.
The FNCT values field (offset DP.DAD) supplies the default values for the CSR bits FNCT
1 (bit 1), FNCT 2 (bit 2), and FNCT 3 (bit 3). The allowable values for the field reflect the
bit positions-even decimal values 0 through 14 (binary 1110) inclusive. The FNCT bits are
available to the user device for user-defined purposes.
The GO value field (offset DP.DAD+2) supplies the default value for the CSR bit GO (bit 0). It
may be 0 or 1. Setting the GO bit indicates that the DRVll-B registers have been set up for a
DMA transfer, which can then be initiated by either the user's program or the user device.
The CYCL value field (offset DP.DAD+4) supplies the default value for the CSR bit CYCL (bit
8). It may be 0 or 1. The CYCL bit indicates whether DMA transfers are to be initiated by
the Q-bus arbiter (bit set) or by the user device (bit clear). Setting the CYCL bit with a Set
Characteristics command causes a DMA transfer to be initiated as soon as the next transfer
request is posted to the driver process. Clearing the bit with Set Characteristics means that
the actual DMA transfer must be initiated by the user device after a transfer request has been
posted by the application program. The CYCL bit must be set when the DRVl 1-B is being
used in maintenance mode.

Parallel Line Drivers 6-35

6.5.3.3 YB Get Characteristics
The Get Characteristics function returns a block of device-dependent information. That
information consists of device class and type and the current contents of the device CSR.
The function-dependent portions of the YB Get Characteristics request and reply packets are
shown below:
I

-----------------1

DP.DAD -

Type

I Class

- DP.FDD

I
I

Func-

CSR

de p
value

data
Not

Not used

used

DP.BUF Ref
data

DP.PAR -

info

DP.LEN -

+-----------------+

v
ML0-871-87

In the information above:
•

Class is DC$RL T for real-time device class.

•

Type is RT$DRB for DRVl 1-B device type.

•

CSR is a copy of the current Control and Status register, from which the user can extract
STAT A, STAT B, and STAT C.

6.5.4 SBC-1 1/21 PIO (VF) Functions
6.5.4. 1 VF Read and Write
The YF driver supports unidirectional input and/ or output with 8-bit transfers as selected by
jumpers on the module. The driver supports only mode 1 PIO transfers; modes 0 and 2
are not supported. Mode 1 uses the standard (factory) hardware configuration and permits
interrupt-driven transfers in block mode.
Read and write requests transfer a specified number of bytes to or from a specified buffer.

6-36

Parallel Line Drivers

The function-dependent portions of the YF read or write request and reply packets are shown
below:
I
I

-----------------:

DP.DAD -

I
I
I

--1
I
I

I
--1

Not used

I
I

--·
--.
1-----------------1
DP.BUF - l
Buffer
l
I
1--

DP.PAR - I

Not used

I
I

--1

1-----------------1
Buffer length I
I

Funcdep
value
data
I
I

I
-- I

address

I
I

1----------------- - DP.FDD

1
I

DP.LEN - I

+-----------------+

-----------------,
I

I
I

Ref
data
info
v
ML0-872-87

6.5.4.2 VF Get Characteristics
The Get Characteristics function returns a block of device-dependent information.
information consists of device class, type, and subtype.

That

The function-dependent portions of the YF Get Characteristics request and reply packets are
shown below:

Type

DP.DAD -

:subtype

Funcde p
value
data

Not used

Not
I
I
I

used

1--

DP.BUF -

1-1
I

.-+-----------------+
I

DP.LEN -

1
I

:-----------------

1
I

1
I
I

DP.PAR -

- DP.FDD

: Class

I
I

Ref
data
info
v
ML0-873-87

Parallel Line Drivers 6-37

In the previous information:
•

Class is DC$RLT for real-time device class.

•

Type is RT$FAL for SBC-11/21 PIO type.

•

Subtype is RT$PRT for parallel-port subtype.

6.5.5 KXT 11-CA/KXJ 11-CA PIO (YK) Functions
6.5.5. 1 YK Read
The YK read functions transfer data from a parallel port to a KXTll-CA/KXJll-CA buffer.
YK read operations are affected by the function modifiers specified in Set Pattern operations. In

pattern-match mode, read operations terminate either when a user-specified pattern is found or
when a user-specified search limit (DP.LEN) expires. If no pattern modifiers were specified in
a YK Set Pattern request, the default is FM$YKA (all bits must match).
If pattern-match mode is not set, you specify the length of the transfer.

For bit ports, a read request must be for one byte for a single port or two bytes for linked ports.
The function-dependent portions of the YK read request and reply packets are shown below:
I
I

DP.DAD -

:----------------'

- DP.FOO

I
I

Funcdep
value
data

Not used

DP.BUF -

Buffer

DP.PAR -

address

·-----------------,
Buffer length l
+-----------------+
I

DP.LEN - I

Ref
data
info
v
ML0-874-87

6.5.5.2 YK Write
The YK write functions transfer data from a KXTl 1-CA or KXJl 1-CA buffer to a parallel port.
YK write operations, like read operations, are affected by the function modifiers specified in

Set Pattern operations. In pattern-match mode, write operations terminate either when a userspecified pattern is found or when a user-specified search limit (DP.LEN) expires. If no pattern
modifiers were specified in a YK Set Pattern request, the default is FM$YKA (all bits must
match).
If pattern-match mode is not set, you specify the length of the transfer.

6-38 Parallel Line Drivers

For bit ports, a write request must be one byte for a single port, or two bytes for linked ports.
The function-dependent portions of the YK write request and reply packets are shown below:

DP.DAD

Bufferless data
- -----------------

----------------Not

- DP.FDD
I
I

Funedep
value
data

Not used

used

----------------DP.BUF Buffer
DP.PAR DP.LEN -

address

----------------Buffer length
+-----------------+

v
Ref
data
info
v
ML0-875-87

If you are writing a single byte to a port or two bytes to a linked port, you can omit the buffer

specification and place the data at offset DP.DAD. You must, however, send by value only (and
not by value and by reference).
Note
The support routine YK_PORT_WRITE does not support this technique.

6.5.5.3 YK Get Characteristics
The YK Get Characteristics function returns a block of device-dependent information, which
consists of device class and type.
The function-dependent portions of the YK Get Characteristics request and reply packets are
shown below:

Type

DP.DAD -

: Class

- DP.FDD

I
I

Funcdep
value
data

used

Not
used
DP.BUF -

I
I
I

DP.PAR -

,-I

DP.LEN -

1-1

+-----------------+

Not

Ref
data
info
v
ML0-876-87

Parallel Line Drivers 6-39

In the previous information:
•

Class is DC$RLT for real-time device class.

•

Type is RT$YKP for KXTl 1-CA or KXJll-CA parallel port or RT$YKT for KXTl 1-CA or
KXJl 1-CA timer.

6.5.5.4 YK Set Pattern
The YK Set Pattern function sets pattern-match mode on parallel port A or B. This allows you
to terminate a data transfer when a user-specified pattern is found.
The function modifier bits for this request specify whether all bits specified in the pattern
argument must match (FM$YKA), or just one bit in the pattern argument must match (FM$YKO),
and whether wait-for-pattern-match mode is to be set (FM$YKW). If no modifiers are specified,
the default is FM$YKA.
To use pattern matching, you must specify "PAT=YES" for port A or B in the prefix file
port-configuration (YKCP$) macro.
The function-dependent portions of the YK Set Pattern request and reply packets are shown
below:

x/DP.PMP

lPolarity
- -----------------

x/DP.PMT x/DP.PMM -

--------Trans.
--------Mask
--------Not
I
I

used

----------------Buffer
DP.BUF DP.PAR address
----------------DP.LEN 1 or 2
+-----------------+

- DP.FDD

Match data
I
I

Funedep
value
data
v

Not used

1-----------------1
I

I
I

Ref
data
info
v
ML0-877-87

Fields DP.PMP, DP.PMT, and DP.PMM collectively define the match pattern for the specified
port (unit). Each bit in a DP.PMP, DP.PMT, and DP.PMM field corresponds to a bit (0-7) in
the match pattern; that is, each bit of the match pattern is defined by corresponding bit~ of
DP.PMP, DP.PMT, and DP.PMM. For each match pattern bit, DP.PMP supplies pattern-polarity
information; DP.PMT, pattern-transition information; and DP.PMM, pattern-mask information.

6-40 Parallel Line Drivers

The pattern specification for each bit of the match pattern is defined as follows:
DP.PMP

DP.PMT

DP.PMM

Event Recognized

Bit masked off-no event recognized

Any transition

Logical 0 state

Logical 1 state

Logical 1 to logical 0 transition

Logical 0 to logical 1 transition

Note
Do not specify more than one bit to detect transitions if you specify AND
pattern mode (function modifier FM$YKA).
For example, to set a pattern of bits 0 to 3 = 1 AND bits 5 and 6 = 0 AND bit 7 = logical
1 to logical 0 transition AND bit 4 ignored, you would specify AND pattern mode and pass
the bit pattern 00001111 in DP.PMP, 10000000 in DP.PMT, and 11101111 in DP.PMM. For
wait-for-pattern-match mode, you can use the DP.BUF, DP.PAR, and DP.LEN fields to describe
a variable for receiving the matching data. The length field should be 1 for a single port and 2
for linked ports. Alternatively, if these fields are left clear and the packet is sent by value only,
then the matching data is returned in the first word of the function-dependent portion of the
packet, as shown above.

6.5.5.5 YK DMA Read, Write, and Complete
The YK PIO DMA functions allow you to perform DMA transfers via a KXTl 1-CA or KXJl 1-CA
parallel port. To perform a DMA transfer, you first send a DMA Read or DMA Write request
to the YK driver and wait for a reply. If the reply indicates normal status, you then send a
DMA transfer command to the DMA (QD) driver and wait for the request to complete. After
the DMA transfer completes, you send a DMA Complete request to the YK driver. The DMA
Complete request unlocks the request queue for the port that was used for the transfer.
The function-dependent portions of the YK DMA request and reply packets are not used.
For guidelines to follow when performing DMA I/O on a KXTl 1-CA or KXJll-CA parallel
port-and a sample Pascal program-see Section 6.4.2.4.

Parallel Line Drivers 6-41

6.5.5.6 YK Set Timer
The YK timer functions control the timer/counters on the KXTll-CA and KXJll-CA. Depending
on the function modifier specified, the Set Timer function can initialize a timer constant (FM$YKI),
trigger the timer after setup (FM$YKT), or set up a timer to periodically signal (continuous cycle
mode) a binary or counting semaphore (FM$YKC).
If none of the three YK Set Timer modifiers is specified, the timer mode set by the prefix file or
by the last timer command remains in effect.
If periodic signaling is specified, the driver signals a binary or counting semaphore and restarts
the timer after each timeout. In such a case, the driver replies to the user right after the timer
is set up. If periodic signaling is not specified, the timer just counts down once (single cycle),
and the driver then replies to the user.

Timers are initialized to a value (offset DP.PDA, below) and count down to 0. You subtract the
current value from the initial value to calculate the number of ticks.
The timers count down at a rate of 2MHz, or one tick every .5 microseconds. At that rate,
counting down to 0 from the maximum 16-bit timer value (65536) takes approximately 33
milliseconds. For longer intervals, you can have the timer count from 65536 to 0 several times
or link two timers together to make a 32-bit timer. To link two timers, use "TLNK=YK$112" in
the YK prefix file macro YKCT$.
Section 6.4.2.8 provides a sample program that uses the YK support routines and timers 1 and
3 to count external pulses. Section 6.4.2.9 provides a sample program that uses the YK support
routines to manipulate a 32-bit timer-timers 1 and 2 linked together.
The function-dependent portions of the YK Set Timer request and reply packets are shown
below:
I
I
I

I
I
I

1-----------------1I
1----------------Signal
DP.TSM I

1----------------- - DP.FDD

DP.PDA - I Timer constant
I

1
I

1-1

I
I

1--

Funcdep

semaphore

value
data

Not used

ID
I

v
--1

Not

DP.BUF -

I
I
I

--1

used

DP.PAR DP.LEN -

I
I
I
--1
I
I

+-----------------+

Ref
data
info
v
ML0-878-87

Field DP.PDA specifies a timer constant value to be set. You must provide a signal semaphore
ID in field DP. TSM if you want to establish a continuous-cycle semaphore to be signaled upon
each timer timeout. In addition, you must send the packet by value only.

6-42

Parallel Line Drivers

Note
If port C is being used to supply handshake signals while timer 3 is being used
as a general-purpose timer, the· time constant must be set for timer 3 during
initialization and not changed during operation. The reason is that port C is
disabled during the setting of timer 3's constant, and therefore the handshake
signals also get disabled.

6.5.5. 7 YK Clear Timer
The YK Clear Timer function deactivates a timer that is operating in the continuous mode.
The function-dependent portions of the YK Clear Timer request and reply packets are not used.

6.5.5.8 YK Read Timer
The YK Read Timer function returns the current count value from a timer.
The function-dependent portions of the YK Read Timer request and reply packets are shown
below:

DP.DAD -

Timer count

- DP.FDD

Not used

Funcdep
value
data

Not
used

DP.BUF -

Timer count

DP.PAR -

address

Ref
data
info

DP.LEN -

+-----------------+

ML0-879-87

The DP.BUF, DP.PAR, and DP.LEN fields contain information about the variable that is to
receive the timer-count value. If these fields are left clear, and the packet is sent by value only,
the timer-count value will be returned in the first word of the function-dependent portion of
the reply packet, as shown above.

6.6 Status Codes
If an error is detected during an IJO operation by a parallel interface or driver, the driver returns
an exception code in the status.;code (DP.STS) field of the reply message. If you are performing
I/O with Pascal I/O statements-that is, not with send/receive statements or Pascal support
routine calls-the Pascal OTS will raise the corresponding exception (unless the operation was
an OPEN for which a STATUS return was specified).
If no error was detected during the I/O operation, a value of ES$NOR (0) is returned in the
status-code field of the reply message.

Parallel Line Drivers 6-43

The parallel line drivers return the following exception codes in the status field of the reply
message:

Code

Type

Description

ES$ABT

HARD_IO

1/0 abort, driver process deleted, request not serviced (XA, YB,
YF)

ES$ATN

HARD_IO

Device has indicated error by asserting ATTN bit in the CSR
(YB-see Section 6.7, Extended Error Information)

ES$DAL

HARD_IO

Device allocated (XA); line already attached (XA Enable)

ES$IVM

HARD_IO

Invalid mode: DMA transfers are not allowed on bit type ports,
PIO cannot use OMA when request line output is defined as an
input, pattern match not allowed on PIO port B when linked to
port A, transition recognition cannot be used on PIO port using
a handshake, if OMA transfer is used on one PIO port, then
other port must be bit type (YK)

ES$IVP

HARD_IO

Invalid request packet parameter:
transfer (YB)

ES$NXM

HARD_IO

Nonexistent or read-only memory (YB)

ES$NXU

HARD_IO

Nonexistent unit (XA, YB, YF, YK)

ES$0VF

HARD_IO

Buffer size was exceeded before a PI 0 pattern match was
detected (YK)

ES$PWR

HARD_IO

Power failure (YB)

ES$IFN

SOFT_IO

Invalid function code (XA, YA, YB, YK); attempt to perform a
supported function on a PIO unit not configured to support that
function (YF); also used internally to signal ACP or OTS that no
device-dependent processing of an Open, Close, or Purge was
required

odd number of bytes to

Exception codes are defined in the ESCODE.P AS include file (included by EXC.P AS) for Pascal
users and by the EXMSK$ macro in the COMU/COMM macro libraries for MACR0-11 users.
Note
Not listed above are exception codes for OTS-detected IjO errors or for kerneldetected errors that the parallel drivers raise rather than passing back to the
requesting process. OTS-detected 1/0 errors are listed in Chapter 9 of the

MicroPower /Pascal Language Guide.

6. 7 Extended Error Information
In the event of a DRVl 1-B hardware error (ATTN bit asserted in the CSR), the YB driver copies
the CSR into the DP .ERR field of the driver reply packet. The CSR is described in the DRVl 1-B
hardware guide.

6-44 Parallel Line Drivers

6. 8 Parallel Line Driver Prefix Files
Figures 6-6 through 6-10 show the parallel line driver prefix modules. The following sections
describe the prefix file macro calls and symbol definitions that can be edited to fit your
application.

6.8. 1 XA Prefix File
The XA driver prefix file (Figure 6-6) specifies that low-active signals will be used for
generating interrupt requests. If high-active signals will be used, edit XAPFX.MAC to reflect
that configuration.
The driver prefix file specifies the use of rotating priority for interrupts within each of two 8-bit
groups. When rotating priorities are used, group 1 consists of port A 1/0 bits 0 to 7; group 2
consists of port A 1/0 bits 7 to 11 and USER RPLY A to D (standard hardware configuration),
or port A 1/0 bits 7 to 15 (nonstandard hardware configuration). Rotating priority assigns the
lowest interrupt priority within a group to the line that most recently received interrupt service.
Thus, a maximum of eight interrupt cycles would be required for that group to service each
interrupt request. Group 1 always has higher interrupt priority than group 2.
When fixed priority is used, edit XAPFX.MAC to reflect that hardware configuration. Fixed
priority (nonrotating) within a group causes interrupt priority to be determined by the physical
position of each line on the 1/0 connector. The highest-priority line is port A 1/0 line O;
the lowest-priority line is the USER RPLY D line. However, when USER RPLY interrupts
are disabled through the use of the nonstandard hardware configuration (Wl 1 removed), the
lowest-priority line is port A line 15. When an application requires fixed interrupt priority for
each line within a group, the prefix file can be modified to meet this requirement. Change the
value of the symbol J$RPRI from 1 to 0, as indicated in the source comments, and reassemble
the prefix file before installing it in the system.
The DRVCF$ macro specifies the driver name for the request-queue semaphore and the number
of DRVll-J devices (controllers) on the target to be supported by the driver. You can edit that
field to change the number of controllers; if you do, however, you must add a CTRCF$ macro
for each controller.
The CTRCF$ macro specifies the controller name, number of units-ports and bit-interrupt
lines-the controller supports, CSR and vector addresses, and the unit numbers of supported
units.
Change cname =A to cname = B for the second controller, cname = C for the third, and so on.
The cname field supplies the third character for the corresponding request-queue semaphore
name.
When specifying nunits, be sure to include the decimal point. If the DRVll-J device on your
target supports fewer than 16 units-the maximum is 16-edit that field.
The csrvec field specifies both the initial CSR address (CSRA) and the first of 16 consecutive
vector addresses associated with the device. You can edit that field if your device is not
configured for those starting addresses.
You must use the DEVICES macro to specify all 16 interrupt vectors in the system configuration
file. If the first vector is 400, for example, you must specify 400, 404, 410, 414, 420, 424, 430,
434, 440, 444, 450, 454, 460, 464, 470, and 474.

Parallel Line Drivers 6-45

The units field specifies the unit numbers of the ports and sense lines supported by the controller.
The designation 0:15 specifies units 0 through 15. Each unit number has a fixed significance,
as defined by the XA driver. Unit numbers 0 through 3 refer to parallel ports A, B, C, and D
of the DRVll-J, respectively. Unit numbers 4 through 15 refer to the individual bit-interrupt
(sense) lines 0 through 11 of port A, respectively. The driver uses the values specified in the
units field to validate the unit numbers given at run time in XA-driver function requests. You
can edit that field to restrict the range of valid unit numbers for your device configuration. For
example, the units specification units= < 1,2,4:9 > indicates that only ports B and C (units 1
and 2) can be referred to in parallel-I/O read or write requests and that only the sense lines 0
through 5 of port A (units 4 through 9) can be referred to in bit-interrupt Enable and Disable
requests.
The symbols XA$xPR define various priorities associated with the driver, including the device
interrupt priority.
The J$RPRI definition sets rotating priorities on or off-1 for rotating priorities, 0 for fixed
priorities. J$HIGH sets interrupt polarity to high or low-0 for low-level polarity, 1 for
high-level polarity.
Figure 6-6:

ORV 11-J Driver Prefix File (XAPFX.MAC)

.title

XAPFX

- DRV-11J Device driver prefix module

drvcf$
ctrcf$

175.

Process priority
DRV-11J hardware priority
Process initialization priority

250.

Set for rotating priorities
Clear for low level interrupt polarity

drvcf$
ctrcf$

dname=XA,nctrl=1
cname=A,nunits=16. ,csrvec=<164160,400>,units=<0:15>

.end

6.8.2 YA Prefix File
In Figure 6-7, the YA STD_pRQC_PRIO constant sets the process software priority to the
standard value for the YA driver. The STD-1NT_pRJO constant sets the default DRVl 1 device
interrupt priority.
The CSR address is assigned the default value 167770. That is the factory-configured CSR
address for the device.

6-46 Parallel Line Drivers

The VECTOR_REQA and VECTOR_REQB assignments set the output (REQ A) interrupt vector
address to 340 and the input (REQ B) interrupt vector address to 344, respectively. Those are
the factory-configured vector addresses for the device.
Figure 6-7:

DRVl 1 Driver Preftx File (YAPFX.PAS)

MODULE YAPFX;
{

YAPFX.PAS

- Edit Level 1

This software is furnished under a license and may be used or copied
only in accordance with the terms of such license.
Copyright (c) 1982, 1986 by DIGITAL EQUIPMENT CORPORATION.
All rights reserved.
}

const
std_proc_prio = 175;
std_int_prio = 4;

{ Standard process priority }
{ and interrupt priority }

var
stdprio : [global] integer;
{ Driver process priority }
drprio : [global] integer;
{ Interrupt priority }
csr : [global] unsigned;
{ CSR address }
vector_reqa
[global(REQA)] unsigned;
{vector address, A request}
vector_reqb : [global(REQB)] unsigned;
{vector address, B request}
maintenance : [global(MAINT)] boolean;
{ Declared in YADRV module }
version : [external($YAVER)] packed array[! .. 6] of char;
[global] procedure initcsr;
begin
stdprio := std_proc_prio;
{ Final process priority }
drprio := std_int_prio * 32; { In PSW placement }
csr := 10'167770';
{CSR}
{

Note that the interrupt vector addresses below are not the default
addresses specified for the.DRV-11. The default vector addresses
are 300 and 304. The default addresses conflict with some other
devices more commonly used. Change the following addresses to 300
and 304 if your hardware configuration requires it.
}

vector_reqa := %0'340';
vector_reqb := %0'344';
version := 'V02.00'; .
maintenance := false;
end
{ procedure initcsr };

{Not maintenance mode}

6.8.3 YB Prefix File
The YB prefix file assigns hardware and driver process priorities, assigns default settings for
DRVl 1-B CSR bits, and invokes the DRVCF$ and CTRCF$ macros. (See Figure 6-8.)

Parallel Line Drivers

6~47

The symbols YB$FNC, YB$GO, YB$MAN, and YB$CYC determine the default settings for device
CSR bits. You can set alternate defaults by editing those global symbol definitions. You can also
reset the CSR bits at run time via Set Characteristics requests from your application program.
YB$FNC supplies the default values for the CSR bits FNCT 1 (bit 1), FNCT 2 (bit 2), and FNCT
3 (bit 3). The allowable values for the symbol reflect the bit positions-even values 0. through
14. (binary 1110) inclusive. The FNCT bits are available to the user device for user-defined
purposes.
YB$GO supplies the default value for the CSR bit GO (bit 0), which may be 0 or 1. Setting the
GO bit indicates that the ORVl 1-B registers have been set up for a OMA transfer, which can
then be initiated by either the user's program or the user device.
YB$MAN supplies the default value for the CSR bit MAINT (bit 12). It may be 0 or 1. The
MAINT bit is set when the device is being tested in loopback mode.
YB$CYC supplies the default value for the CSR bit CYCL (bit 8). It may be 0 or L The CYCL
bit indicates whether OMA transfers are to be initiated by the LSI-11 bus (Q-bus) arbiter (bit
set) or by the user device (bit clear). Setting the CYCL bit at run time with a Set Characteristics
command-see Section 6.5 (Request/Reply Packet Interface)-causes a OMA transfer to be
initiated as soon as the next transfer request is posted to the driver process. Clearing the bit
with Set Characteristics means that the actual OMA transfer must be initiated by the user device
after a transfer request has been posted by the application program. YB$CYC must be set when
the ORVl 1-B is being used in maintenance mode.
The ORVCF$ macro specifies the device name (YB) and the number of controllers to be supported
by the driver.
The CTRCF$ macro is invoked once for each controller to be serviced by the driver. It specifies
the controller identifier (A, B, ... ), the number of units (always 1), CSR and vector addresses,
and unit numbers.

6.8.4 VF Prefix File
The YF driver prefix file YFPFX.MAC (Figure 6-9) assumes the standard configuration for PIO
ports. The standard configuration for PIO transfer direction is port A (Unit 0) for input and
port B (Unit 1) for output. Port A can be configured for output transfers, and port B can be
configured for input transfers, or both ports can be configured for input or output transfers, as
required for a particular system application. If desired, only one port may be used. However,
if any changes are made to the standard configuration, you must edit the YFPFX.MAC file to
reflect those changes prior to building the application software.
YF$PPR defines the process software priority for the YF driver. The field can be modified to
fine-tune the relationship between the driver and other processes in the application.
YF$FPR defines the driver's interrupt service routine fork priority. By default, the value of
YF$FPR is set to 256 times the software priority.
YF$IPR defines the process initialization priority. That priority should be equal to that of all
other I/O device drivers.
YF$HPR defines the hardware interrupt priority. For the SBC-11/21 parallel port, the level is
fixed at 5.

6-48 Parallel Line Drivers

Figure 6-8:

ORV 11-B Driver Prefix Fiie (YBPFX.MAC) Excerpt

.title YBPFX

- DRV11--B Device driver prefix module

This software is furnished under a license and may be used or copied
only in accordance with the terms of such license.
Copyright (c) 1985, 1986 by Digital Equipment Corporation.
All rights reserved .
. mean
.mcall

drvcf$
ctrcf$

.macro
.br;
.br;
.error
. endc
.endc
.endm

cross MAN, CYC
IF YB$MAN = 1, YB$CYC MUST be = 1 .

; for cross-correlation of YB$MAN and YB$CYC
YB$PPR
YB$IPR
YB$HPR
YB$FNC
YB$GO
YB$MAN
YB$CYC

175.
250.
4.

Process priority
Process initialization priority
DRV11B hardware priority (do NOT change)

0.
; value to set FNCT 1, FNCT 2 and FNCT 3 bits
(allowable values for YB$FNC are all EVEN values 0.-14. inclusive)
1.
value to set GO bit ( 0 or 1 ONLY)
1.
set to 1. if in maintenance (loop-back) mode.
set to 0. otherwise.
1.
Used to set the CYCL bit in the CSR. Set this
to 1. if the DMA transfers are to be initiated
by the Q-bus arbiter and set to 0. if the
DMA transfers are to be initiated by the user
device. MUST be set to 1. if YB$MAN is 1 ..

drvcf$
ctrcf$
ctrcf$

dname=YB,nctrl=1
cname=A,nunits=1. ,csrvec=<172414,124>,units=<O>
cname=B,nunits=1. ,csrvec=<172424,130>,units=<O>

{End of user-settable parameters}
.end

YF$AIO defines the data direction for the 8-bit data port A; 0 = output, 1 = input. If the default
direction of that port is reversed, jumpers M59 through M66 on the FALCON or FALCON-PLUS
board must be changed from their factory configuration to reflect the prefix module settings.
YF$BIO defines the data direction for the 8-bit data port B; 0 = output, 1 = input. If the default
direction of that port is reversed, jumpers M59 through M66 on the FALCON or FALCON-PLUS
board must be changed from their factory configuration to reflect the prefix module settings.

Parallel Line Drivers 6-49

Figure 6-9:

SBC-11/21 PIO Driver Prefix File (YFPFX.MAC)

.title

- FALCON (SBC--11/21) 8255 PIO Device driver prefix module

YFPFX

This software is furnished under a license and may be used or copied
only in accordance with the terms of such license.
Copyright (C) 1982, 1986 by Digital Equipment Corporation.
All rights reserved.
.GLOBL

$YF

Haul in the driver from the library

YF$PPR
YF$IPR
YF$HPR

175.
250.
5

Process software priority
Process initialization priority
Hardware interrupt priority

YF$AIO

YF$BIO

Port A is input
Set to 0 for Port A output
Port B is output
Set to 1 for Port B input

.end

6.8.5 YK Prefix File
Figure 6-10 displays the YK prefix file driver YKPFX.MAC.
The following options are available when you configure the KXTl 1-CA or KXJl 1-CA 8-bit
parallel ports A and B:
•

Port can be input, output, or bit mode. In bit mode, the direction of each bit is programmed
individually.

•

DMA transfers in fixed-length or stop-on-pattern mode. In stop-on-pattern mode, you can
test data for specified patterns and can generate interrupt requests based on the match
obtained.

•

Programmable polarity-inverting or noninverting.

•

Pulse catchers can be inserted into an input data path. When a pulse is detected at the pulse
catcher input, its output is automatically set until it is cleared by the software's writing a
nonpulse level to the corresponding bit in the data register. In all other cases, attempted
writes to input bits are ignored. The pulse catcher is level-sensitive; therefore, if the impulse
is still at the pulse level when it is cleared, the output will again become enabled .

. •
•

Optional open-drain outputs, with no pull-up resistors provided.
Four handshake modes, including interlocked, strobed, pulsed, and 3-wire. When specified
as a port with handshake, the transfer of data into or out of the port and interrupt generation
is under handshake logic control.
With· interlocked handshake, the driver action must be acknowledged by the external device
before the next action can take place. An output port does not indicate that new data is
available until the external device indicates that it is ready for the data. Similarly, an input
port does not indicate that it is ready for new data until the data source indicates that
the previous byte of data is no longer available, thereby acknowledging the input port's

6:....50 Parallel Line Drivers

acceptance of the last byte. The handshake allows the YK driver to interface directly to a
port, with no external logic.
With strobed handshake, the data is strobed by external logic into and out of the port.
Unlike the interlocked handshake, the signal indicating that the port is ready for another
data transfer operates independently of any input acknowledgment. The external logic must
ensure that data does not transfer at a rate either too fast or too slow.
With a pulsed handshake, data is held for long periods of time and is gated with relatively
wide pulses into or out of the driver. A pulsed handshake is used to interface to mechanicaltype devices.
The 3-wire handshake is used when one output port is communicating with many input
ports simultaneously. It is essentially the same as the interlocked handshake, except that
two signals are used to indicate if an input port is ready for new data or if it has accepted
the present data. With the 3-wire handshake, output lines on many input ports can be
bused together with open-drain drivers; the output port knows when all ports have accepted
the data and are ready. Because this handshake requires three lines, only one port-either
A or B-can be a 3-wire handshake port at one time.

•

Pattern- or transition-recognition logic. In ports A and B, you can test data for specified
patterns and can generate interrupt requests based on the match obtained. The patternrecognition logic is independent of the port application. The pattern can be independently
specified for each bit as 1, 0, O-to-1 transition, 1-to-0 transition, or any transition. Two
modes of pattern-recognition operation are supported: AND and OR. Transition recognition
is illegal on ports with handshake.

•

Link option that provides one 16-bit port instead of two 8-bit ports .

In addition to the 8-bit parallel ports, the YK driver interfaces with a 4-bit special-purpose I/O
port, which is available as a 4-bit parallel port if no handshake mode was selected for the 8-bit
ports. Otherwise, this port provides the handshake signals.
The driver also interfaces with three independent 16-bit counter/timers with programmable
output duty cycles-pulsed, 1-shot, and square wave-and up to four external access lines for
each counter-count input, output, gate, and trigger. The counter/timer can be programmed to
be retriggerable or nonretriggerable.
Many operations are possible, depending on how the timer is programmed. If the counter/timer's
duty cycle is programmed in the pulse mode, the external "data available"' output is initiated by
the internal "data available" signal's-being detected "TC" cycles before.
Note
"TC" is the value programmed in the counter/timer Time Constant register.
The type of duty cycle-pulsed, 1-shot, or square-wave-determines how the
pulsed handshake operates with a counter/timer that is being used as the "data
available" output for the handshake.
If the counter/timer is programmed with the 1-shot duty cycle, the external "data available"

output follows the internal "data available" signal as soon as it is detected.

Parallel Line Drivers 6-51

If the counter/timer is programmed with a square-wave duty cycle, the external "data available"

output follows the internal "data available" signal at a predetermined time (TC clock cycles after
it is detected).
Note
The counter, gate, or trigger mode can be used only if the count bit used is
available. The count bit must be specified to be an input, even if the port bit is
programmed as an output bit, to allow the CPU to write that input directly.
In counter mode, the 1/0 line of the port associated with the counter/timer is used as an
external counter input; in gate mode, it is used as an external gate input to the counter/timer;
in trigger mode, it is used as a trigger input to the counter/timer.
When set to retrigger, each trigger causes the time constant value to be reloaded and. a new
countdown sequence to be initiated. When a counter/timer is programmed in square-wave
mode, a retrigger will cause the time constant value to be reloaded and the new countdown to
start on the first half of the square wave.
The KXTll-CA/KXJll-CA parallel port and timer/counter prefix file uses four configuration
macros. An initialization macro, YKCI$, defines symbols and other macros. The second, YKCP$,
configures a port. The third, YKCT$, configures a timer. The fourth, YKCE$, marks the end of
the configuration list. The second and third macros update internal symbols as they are used.
The symbol values indicate what features have been selected. Those values are used to prevent
the user from attempting to select an invalid configuration. Error messages are output to the
listing file or terminal if a conflicting option is requested.
The configuration macros generate a data table that is used by the driver at system initialization
time to configure the peripheral processor hardware registers.
Configuration Initialization Macro-YKCI$
Syntax
YKCI$

The configuration initialization macro YKCI$ must be the first macro used in the YK driver
prefix file. YKCI$ has no parameters associated with it; it initializes symbols and defines the
remainder of the macros and submacros to be used.
Port Configuration Macro-YKCP$
Syntax
YKCP$

chan=[A] ,ptype=[YK$BIT] ,hsh=[YK$INL] ,dskw=[O] ,out=[O],
inv=[O] ,in1=[0] ,oco=[FALSE] ,plnk=[FALSE] ,dma=[FALSE],
pat=[FALSE]

This macro is used to configure a particular port. The macro can be used by listing parameters in
the order that they are defined or by using the KEYWORD=VALUE format, where the value can
be a sum of bit definitions in the case of the direction, polarity, or one's catcher specifications.
If all parameters for a port cannot fit on a single line, the macro can be reused for the same
channel and the remainder of the parameters specified on the second usage. Any omitted
parameter will take on the default value as specified above in square brackets. Each parameter
is described below.

6-52

Parallel Line Drivers

ch an

Specifies the channel number to use. Permissible values are A, B, or C.
ptype

Specifies the port type: bit, input, or output. Permissible values are:
YK$BIT-bit port
YK$1NP-input port
YK$0UT-output port
hsh

Specifies the type of handshake mode: interlocked, strobed, 3-wire, or pulsed.
YK$INL-interlock
YK$STR-strobed
YK$3WI-3-wire (IEEE 488)
YK$PUL-pulsed
Note
Timer 3 must be configured and a run-time request sent in order to use
pulsed handshake. The timer set command must be sent prior to sending
the first command to the port.
dskw

Specifies the deskew time, in cycles. Permissible values are 0, 2, 4, 6, 8, 10, 12, 14, or 16.
out

Specifies the 1/0 direction for each bit. If set, the bit is output. The following symbols may
be OR' d together to define output bits.

Mnemonic Value (octal)
YK$BO
1
YK$Bl

YK$B2

YK$B3

YK$B4

YK$B5

YK$B6

100

YK$B7

200

inv

Specifies polarity of the bit. If a bit is set, the corresponding input or output bit of the
interface register is inverted. The symbols YK$BO through YK$B7 listed above may be OR'd
together to define inverted bits.

Parallel Line Drivers 6-53

inl

Specifies which input bits should have the one's catcher attribute. If a bit is set, the
corresponding input bit of the interface register will have the one's catcher enabled. The
symbols YK$BO through YK$B7 listed above may be OR'd together to define one's catcher
bits.

oco
Specifies which output bits have open drain. If not specified, outputs will be active pull up.
pink

If specified as TRUE, ports A and B will be linked together to form one 16-bit port.
dma
If specified, the port will use DMA.
pat

If specified, the port will use pattern recognition.

Timer Configuration Macro-YK CT$
This macro is used to configure a particular timer. The macro can be used by listing the
parameters in the order that they are defined or by using the KEYWORD=VALUE format. If
all parameters to be specified for a timer cannot fit on a single line, the macro can be reused
for the same timer number and the remainder of the parameters specified on the second usage.
Any parameter omitted takes on the default value specified as follows:

Syntax
YKCT$

tnum=[1] ,texto=[NO] ,textc=[NO] ,textt=[NO] ,textg=[NO],
tretre=[NO] ,tout=[YK$TPL] ,tlnk=[YK$TIN]

tnum
Defines the timer number: 1, 2, or 3
texto
NO
YES

Disables timer output
Enables timer output

NO
YES

Disables timer external count
Enables timer external count

NO
YES

Disables timer external trigger
Enables timer external trigger

NO -YES

Disables timer external gate
Enables timer external gate

NO
YES

Disables timer retrigger
Enables timer retrigger

textc

textt

textg

tretre

tout
Defines the type of timer output

6-54 Parallel Line Drivers

YK$TPL
YK$T1S
YK$TSQ

Pulse output
One shot
Square wave

tlnk
Defines the interaction of timers 1 and 2
YK$TIN
YK$1G2
YK$1T2
YK$1I2

Timers are independent
Timer 1 output gates timer 2
Timer 1 output triggers timer 2
Timer 1 output is timer 2 input

End Configuration Macro-YKCE$
This macro must be used after all port or timer macros have been used. The end macro builds
the configuration table from the local symbols that were defined while the other two mac;ros
were being used.
Parameter Interaction
Many inputs, outputs, and internals in the parallel port and timer/counter chip are multiplexed
among the various functions. Thus, several features are mutually exclusive or are not available
for particular ports or combinations of ports.
Error messages can occur during assembly of the YK prefix file if a chosen combination of
parameters is not a viable configuration. See the appropriate MicroPower /Pascal Messages
Manual for a list of the possible error messages.
The tables below show which combinations of parameters are invalid for the YKCP$ macro
when configuring ports A, B, and C. If marked with an X, the parameter combination is invalid
for the port. For example, when configuring port A, you cannot specify an inl value if you
specify ptype=YK$INP, YK$0UT, or YK$BID. The tables do not consider invalid combinations
among ports; see the configuration notes for those.
General Port and Timer Configuration Notes
Handshake Signals
•

If timer 3 has external output, bit 0 of port C cannot be a handshake signal.

•

Only a single port can specify pulsed handshake.

•

Only a single port can specify 3-wire handshake.

•

If one port uses 3-wire handshake, other port must be a bit port.

Port Outputs
•

Output lines of ports A and B must all be open collector or all be active pull-up.

•

If timer 1 has external output, bit 4 of port B must be an output.

•

If timer 2 has external output, bit 0 of port B must be an output.

•

If timer 3 has external output, bit 0 of port C must be an output.

Timer External Outputs
•

Port B must be a bit port to use timer 1 or timer 2 external output.

•

If timer 1 has external output, bit 4 of port B must be an output.

Parallel Line Drivers 6-55

•

If timer 2 has external output, bit 0 of port B must be an output.

•

Port C must be configured in order to use timer 3 external output.

•

To use external output for timer 3, port C must be configured.

•

If timer 3 has external output, bit 0 of port C must be an output.

•

If timer 3 has external output, bit 0 of port C cannot be a handshake signal.

Invalid YKCP$ Parameter Combinations for Port A

port A lYK$lYK$lYK$lYK$lYK$lYK$lYK$l
lBITlINPlOUTlINLlSTRlPULl3Wildskwloutlinvlin1locolplnkldmalpatl
-------+---+---+---+---+---+---+---+----+---+---+---+--~+~---+---+---+

YK$BIT

l X l X l X l X l X l X l X

:- X

-------+---+---+---+---+---+---+---+----+---+---+---+---+----+---+---+
YK$INP l X l
I X I
l
I
l
l X
I X I
I X I
I
I
I
I
-------+---+---+---+---+---+---+---+----+---+---+---+---+----+---+---+
YK$0UT l X I X I
l
I
I
I
I
I X I
I X I
l
I
I
l
-------+---+---+---+---+---+---+---+----+---+---+---+---+----+---+---+
YK$INL I X I
l
I X I X I X I
I
I
l
l
I
I
I
l
-------+---+---+---+---+---+---+---+----+---+---+---+---+----+---+---+
YK$STR I X I
I
I X l
l X l X l
l
l
l
l
I
I
-------+---+---+---+---+---+---+---+----+---+---+---+---+----+---+---+
YK$PUL l X I
I X I X I
I X I
I
l
l
l
I
l
I
-------+---+---+---+---+---+---+---+----+---+---+---+---+----+---+---+
YK$3WI l X l
l
l X I X I X I
I
I
I
I
l
I
I
I
-------+---+---+---+---+---+---+---+----+---+---+---+---+----+---+---+
d skw
: X l X l
l
:
l
l
l
l
l
l
l
:
:
-------+---+---+---+---+---+---+---+----+---+---+---+---+----+---+---+
out
l
l X : X :
:
:
:
l
l
l
l
l
l
l
l
l
-------+---+---+---+---+---+---+---+----+---+---+---+---+----+---+---+
inv
l
l
l
l
:
l
l
:
:
-------+---+---+---+---+---+---+---+----+---+---+---+---+----+---+---+
in1
:
: X : X l
l
:
-------+---+---+---+---+---+---+---+----+---+---+---+---+----+---+---+
oco
:
:
:
:
:
:
:
:
:
:
:
-------+---+---+---+---+---+---+---+----+---+---+---+---+----+---+---+
plnk
: X :
:
-------+---+---+---+---+---+---+---+----+---+---+---+---+----+---+---+
dma
:
l
:
l
:
l
:
l
l
l
-------+---+---+---+---+---+---+---+----+---+---+---+---+----+---+---+
pat
l
l
l
:
l
l
l
l
l
-------+---+---+---+---+---+---+---+---+----+---+---+---+---+----+---+
ML0-880-87

Port A Configuration Notes
•

If port A is a bit port (ptype=YK$BIT), bits 0-3 and bits 4-7 must all be inputs or all be
outputs. Thus, if port A is a bit port, the parameter out can have only the values 0, 17,

360, or 377 (octal).
•

If ports A and B are linked, port A cannot be a bit port.

•

To use handshake signals on port A, port C must be configured.

•

The value of oco for ports A and B must be the same.

6-56 Parallel Line Drivers

Invalid YKCP$ Parameter Combinations for Port B

port B lYK$1YK$lYK$lYK$1YK$1YK$1YK$1
lBITlINPlOUTlINLlSTRIPULl3Wiidskwioutlinvlin1 locolplnkldmalpati

-------+---+---+---+---+---+---+---+----+---+---+---+---+----+---+---+
l X l X I X l X l X l X l X l
l
l
l
l
I
I
I
-------+---+---+---+---+---+---+---+----+---+---+---+---+----+---+---+
YK$INP l X l
l X l
l
l
l X l X I
I X I
l X I
l
l
-------+---+---+---+---+---+---+---+----+---+---+---+---+----+---+---+
YK$0UT l X l X l
l
I
l
l X l
l X l
l X l
l
l
-------+---+---+---+---+---+---+---+----+---+---+---+---+----+---+---+
YK$INL I X l
l
l
l X I X I X I
l
l
I
l
l
l
l
l
-------+---+---+---+---+---+---+---+----+---+---+---+---+----+---+---+
YK$STR l X l
l
l X l
I X I X I
l
I
l
I
I
-------+---+---+---+---+---+---+---+----+---+---+---+---+----+---+---+
YK$PUL I X I
l
l X l X I
l X I
l
l
-------+---+---+---+---+---+---+---+----+---+---+---+---+----+---+---+
YK$3WI I X l
I
l X l X l X l
l
l
I
-------+---+---+---+---+---+---+---+----+---+---+---+---+----+---+---+
d skw
l X l X l
I
l
l
l
I
I
I
I
I
-------+---+---+---+---+---+---+---+----+---+---+---+---+----+---+---+
out
l
l X l X I
l
l
-------+---+---+---+---+---+---+---+----+---+---+---+---+----+---+---+
inv
l
l
I
l
l
l
l
l
l
I
l
I
YK$BI T l

-------+---+---+---+---+---+~--+---+----+---+---+---+---+----+---+---+

in 1

I X I X l

-------+---+---+---+---+---+---+---+----+---+---+---+---+----+---+---+
oco
:
:
:
:
:
:
:
:
:
:
-------+---+---+---+---+---+---+---+----+---+---+---+---+----+---+---+
plnk
l
l x l x l
I
l
I
I
I
: x I
-------+---+---+---+---+---+---+---+----+---+---+---+---+----+---+---+
dma
I
I
:
l
:
:
I
I
I
-------+---+---+---+---+---+---+---+----+---+---+---+---+----+---+---+
pat
l
l
l
I
l
l
l
l X l
I
I
-------+---+---+---+---+---+---+---+----+---+---+---+---+----+---+---+
ML0-881-87

Port B Configuration Notes
•

If ports A and B are linked, port B must be a bit port.

•

To use handshake signals on port B, port C must be configured.

•

The value of oco for ports A and B must be the same. That is, the output lines of ports A
and B must all be open collector or all be active pull-up.

Parallel Line Drivers 6-57

Invalid YKCP$ Parameter Combinations for Port C
port C lYK$lYK$lYK$lYK$lYK$lYK$lYK$l
lBITlINPlOUTlINLlSTRlPULl3Wildskwloutlinvlin1locolplnkldmalpatl

-------+---+---+---+---+---+---+---+----+---+---+---+---+----+---+---+
l X l X l X l X l X l X X l
l
l
X
X l X
-------+---+---+---+---+---+---+---+----+---+---+---+---+----+---+---+
YK$INP
X l X l X l X l X l X l X l X
X l X X l X l X l X l X
-------+---+---+---+---+---+---+---+----+---+---+---+---+----+---+---+
YK$0UT l X X l X l X l X l X X l X
X l X l X l X l X l X l X l
-------+---+---+---+---+---+---+---+----+---+---+---+---+----+---+---+
YK$INL l X l X l X l
l X l X l X l X l
l
l
l X l X l X l
-------+---+---+---+---+---+---+---+----+---+---+---+---+----+---+---+
YK$STR l X l X l X l X l
l X l X l X l
l
l
l
l X l X l X l
-------+---+---+---+---+---+---+---+----+---+---+---+---+----+---+---+
YK$PUL l X X l X X l X
X l X
l
l
l X
X
X
-------+---+---+---+---+---+---+---+----+---+---+---+---+----+---+---+
YK$3WI
X l X X X X X
X
l
X
X l X
-------+---+---+---+---+---+---+---+----+---+---+---+---+----+---+---+
dskw
X
X
X
X X X X : X
X X X X : X : X
X
-------+---+---+---+---+---+---+---+----+---+---+---+---+----+---+---+
out
: X : X
X
X
X X :
-------+---+---+---+---+---+---+---+----+---+---+---+---+----+---+---+
inv
X X
X
X
X
X
-------+---+---+---+---+---+---+---+----+---+---+---+---+----+---+---+
in 1
X X
X
X
X X
-------+---+---+---+---+---+---+---+----+---+---+---+---+----+---+---+
oco
:
: x : x :
: : x :
: : : x : x : x :
-------+---+---+---+---+---+---+---+----+---+---+---+---+----+---+---+
plnk
X X X X X X X
X
X X X X X
X X
-------+---+---+---+---+---+---+---+----+---+---+---+---+----+---+---+
dma
X X l ~
X X X X l X
X X X X X
X X l
-------+---+---+---+---+---+---+---+----+---+---+---+---+----+---+---+
pat
X X X X X X X
X
X X X X X
X X
--·-----+---+---+---+---+---+---+---+----+---+---+---+---+----+---+---+
YK$BIT l

ML0-882-87

Port C Configuration Notes
•

Port C is four bits wide; therefore, values for inv, inl, and out can have values only in the
range 0 to 17 (octal).

•

To use handshake signals on ports A and B, port C must be configured.

•

Port C handshake inputs cannot be defined as outputs.

•

Port C handshake outputs cannot be defined as inputs.

6-58 Parallel Line Drivers

Figure 6-10:

KXT 11-CA/KXJ 11-CA PIO Driver Prefix File (YKPFX.MAC)

.TITLE YKPFX - Parallel I/O and counter/timer Driver Prefix Module
.ident /V2.0/
THIS SOFTWARE IS FURNISHED UNDER A LICENSE AND MAY BE USED OR COPIED
ONLY IN ACCORDANCE WITH THE TERMS OF SUCH LICENSE.
COPYRIGHT (c) 1982, 1986 BY DIGITAL EQUIPMENT CORPORATION.
ALL RIGHTS RESERVED.
;+

This module is an example of using the special configuration
macros for the Parallel I/O and Counter-Timers on the KXT 11C.
The header at the beginning of the module lists the features that are
being configured.
This configuration provides:
1.
2.
3.
4.
5.
6.
7.

4 switch inputs
4 LED driver outputs
8 line parallel output port, with pattern match or DMA
2 pulsed handshakes (1 input, 1 output) for output port
1 status input line from parallel device
Timer 3 provides delay time in pulsed handshake
Timer 1 and 2 are linked (timer 1 =least sig word)

;DEFINE PRIORITIES FOR YK HANDLER
YK$HPR
YK$IPR
YK$PPR

Hardware priority
Initialization priority
Process priority

250.
180.

;CALL:

INITIALIZE MACRO
.MCALL
YKCI$

YKCI$

PORT A
; 'bit port' for reading switches and driving LEDs
; bits 0,1,2,3 are inputs .... bits 4,5,6,7 are inverted outputs
YKCP$
YKCP$

CHAN=A,PTYPE=YK$BIT,OUT=<YK$B4+YK$B5+YK$B6+YK$B7>
CHAN=A,INV=<YK$B4+YK$B5+YK$B6+YK$B7>

; PORT B
; parallel output port, with pulsed handshake
YKCP$

CHAN=B,PTYPE=YK$0UT,HSH=YK$PUL,PAT=YES,DMA=YES

Parallel Line Drivers 6-59

PORT C
handshake signals for port B
bit 0
acknowledge (input)
bit 1 = data available (inverted open collector output)
status input from external device
bit 2 = non-inverted input

YKCP$

CHAN=C,OUT=<YK$B1>,INV=YK$B1,0CO=YES

; TIMER 1
YKCT$

TNUM=1

; TIMER 2
; timer 1 output is timer 2 input

YKCT$

TNUM=2,TLNK=YK$1I2

; TIMER 3
YKCT$

TNUM=3

; END CONFIGURATION
YKCE$
.END

6-60 Parallel Line Drivers

Chapter 7
Analog-to-Digital Converter Driver
This chapter describes the use of the MicroPower/Pascal analog-to-digital converter (AD) driver,
which supports 1/0 operations on the ADVl 1-C and AXVl 1-C analog-to-digital (A/D) converter
boards. The ADVll-C and AXVll-C devices interface analog inputs to a MicroPower/Pascal
target processor, so that A/D conversions can be performed.
The chapter also describes a Pascal routine, WRITE_ANALOG_WAIT, that supports programmed 1/0 on the AAVll-C and AXVll-C digital-to-analog (D /A) converters. The devices
AAVl 1-C and AXVl 1-C D /A interface analog outputs to a target, so that D /A conversions can
be performed.

7. l Driver Features and Capabilities
The AD driver supports A/D conversion setup, reading of converted values, and returning of
device characteristics.
The A/D conversion setup operation sets up and enables A/D conversion, specifying the
method of triggering the conversion, the number of analog input channels to sample and their
identifying numbers, and the gain on each channel. Optionally, you can set a limit on the total
number of records (sets of samples) to return, after which read requests will be ignored. A/D
conversions can be started by a read request (immediate triggering), an external event trigger,
or a real-time clock input.
After the setup operation, the driver and device are ready for conversions to be triggered in the
specified manner. If external event or real-time clock triggering is in effect, A/D conversions
occur asynchronously with respect to user requests for converted data. Converted data is
transferred from the device to the driver's buffers by the driver's interrupt service routine (ISR).
Once in the ISR buffers, the data awaits user requests for transfer to user buffers.
A read operation returns one or more records to a user-specified buffer. If external or real-time
clock triggering is in effect, the read returns records from the asynchronous device-to-ISR input
stream; if none are available, the driver waits until externally-triggered conversions generate
more records. The size of the user buffer-a multiple of the number of channels sampled, times
two (for byte units)-determines the number of returned records. If immediate triggering is in
effect, the read request triggers the conversion and returns a single record to the user buffer.

Analog-to-Digital Converter Driver 7-1

Get Characteristics returns codes for device class and type.

7 .2 Performing Analog-to-Digital Conversions
For most MicroPower/Pascal applications, you perform A/D conversions in one of two ways:
1.

You can invoke Pascal I/O procedures that open files for converted data and then input
the data in accordance with the rules for standard Pascal ljO. The Pascal I/O proceduresOPEN, GET, READ, and so forth-are described in Chapter 9 of the MicroPower /Pascal
Language Guide. Note that this method requires that you call the support routine
SET_ANALOG_MODE to supply the necessary conversion control information before
reading data. (See item 2.)

You can invoke the Pascal support routines SET_ANALOG_MODE and READ_ANALOG.SIGNAL. Those routines provide high-level nonfile access to the A/D converters. The A/D
support routines issue Pascal SEND requests to the request queue semaphore of the AD
driver. The routines are described in Section 7.4.

Note
You can perform D/A conversions by using the WRITE_ANALOG_WAIT
support routine. (See Section 7.4.)
In addition to invoking the Pascal I/O procedures or A/D support routines, you must:
1.

Edit the DEVICES macro in the system configuration file to reflect the A/D controller
interrupt vector addresses

Edit the AD driver prefix file to reflect:

•

Number of controllers

•

[For each controller:] Controller identifier (A, B, ... ), CSR address, interrupt vector
address, number of controller units (1) and identifying number (0), and the ISR buffer
size

•

Hardware interrupt priority

•

Driver initialization and request-handling process priorities

Build into your application the following I/O system components:
•

AD driver process

•

[For real-time clock triggering:] KW driver process (see Chapter 8)

•

[For A/D conversion:] A/D support routine SET_ANALOG_MODE (from kit files
ADINC.P AS and ADSUB.PAS)

•

[For nonfile access:] A/D support routine READ_ANALOG_SIGNAL and/or D/A
programmed I/O routine (from kit files ADINC.PAS and ADSUB.P AS)

•

[For file OPEN:] Ancillary control process (ACP)

•

Pascal OTS routines for file service-built in automatically by MPBUILD for programs
that invoke Pascal I/O procedures-plus any I/O support routines you choose to include
(see kit files GETSET.PAS and GSINC.PAS)

7-2 Analog-to-Digital Converter Driver

For more information on setting up your application software for A/D conversions, see Chapter
4 of the MicroPower /Pascal Run-Time Services Manual, Section 7. 7 of this manual, and the
material on building system processes in the MicroPower/Pascal system user's guide for your
host system.
Alternatives to using the A/D support routines or the Pascal 1/0 procedures for A/D conversions
exist, but require more effort. You can:
•

Issue your own Pascal or MACR0-11 packet-level requests to the ACP and the driver,
bypassing the OTS file routines (lower-level file system access).

•

Issue your own Pascal or MACR0-11 packet-level requests to the driver, bypassing the
OTS file routines, the ACP, and the A/D support routines (low-level nonfile access).

The following sections describe the Pascal IjO procedure interface to the AD driver, the Pascal
support routine interface, the lower-level request/reply packet interface, the status codes that
can be returned to users of any interface, and the AD driver prefix file.

7 .3 Pascal 1/0 Procedure Interface
To perform standard Pascal IjO for A/D conversion data, you must open a file. Opening the
file associates a Pascal file variable with an A/D converter board. Invoke the OPEN procedure
as follows:
OPEN (filvar, 'ADcO:', ... )
where:
•

filvar is a Pascal file variable.

•

c is a controller identifier (A, B, ... ).

For example, 'ADAO:' would specify unit 0 of the first A/D converter (A) listed in the AD
driver prefix file.
The OPEN causes the Pascal OTS to send a packet-level open request to the ACP, which returns
a unit number and a driver request semaphore ID to the OTS. Subsequent 1/0 requests are
sent directly to the driver by the OTS, with no further ACP involvement.
After the OPEN and before reading data, you must call the support routine SET_ANALOG_MODE
in order to set up and enable A/D conversions. SET_ANALOG _MODE is described in Section
7.4.1.
In carrying out subsequent input, CLOSE, or PURGE operations on A/D converters, the Pascal
OTS uses the following packet-level driver functions:
•

Read Logical (IF$RDL)

•

Close (IF$CLS)

•

Purge (IF$PRG)

Analog-to-Digital Converter Driver 7-3

Pascal Get Characteristics functions are provided in the file GETSET .PAS on the
MicroPower /Pascal distribution kit. Those functions issue Get Characteristics (IF$GET) request packets to the driver.

7 .4 Pascal Support Routine Interface
The following support routines, written· in Pascal and independent of the file system, are
provided as an alternative high-level interface to the A/D and D /A hardware:
•

SET_ANALOG_MODE

•

READ_ANALOG_SIGNAL

•

WRITE~NALOG_WAIT

Note
The A/D routines SET_ANALOG_MODE and READ_ANALOG_SIGNAL use
all of the packet-level AD driver functions except Get Characteristics (IF$GET).
To perform that operation, use the Get Characteristics function (descriptor
version) in the kit file GETSET .PAS.

The SET_ANALOG_MODE routine, although not file-oriented, is required for
the Pascal 1/0 procedure (file system) interface as well as the Pascal support
routine interface.
The following sections describe the Pascal routines for A/D and D/ A 1/0. The A/D routines
SET_ANALOG_MODE and READ-ANALOG_SIGNAL each allocate an 1/0 packet, fill it in
with information based on the function parameters, send it to the AD driver queue semaphore,
and return immediately to the caller. If the routine has a reply parameter, the driver sends a
standard driver reply to the specified queue semaphore when the operation is complete. (The
driver reply packets are described in Section 7.5.)
The D /A routine WRITE_ANALOG_WAIT uses programmed 1/0 rather than the AD driver.
It writes values from a buffer to one or more D /A channels.
The following files on the MicroPower /Pascal distribution kit are required for using the routines:

File

Description

ADSUB.P AS

Analog 1/0 routine source module

ADINC.P AS

Analog 1/0 routine include file

IOPKTS.P AS

Pascal 1/0 include file

To use a source module, you must compile it and then merge it with the program at user-process
build time. The associated include files must be included in the program at compile time.

7-4 Analog-to-Digital Converter Driver

7 .4. 1 SET_ANALQG_MQDE
The SET_ANALOG__MODE procedure sets up and enables A/D conversion, specifying the
method of triggering the conversion, the number of analog input channels to sample and their
identifying numbers, and the gain on each channel. Optionally, you can set a limit on the total
number of records (sets of samples) to return, after which read requests will be ignored.
A/D conversions can be started by a read request (immediate triggering), an external event
trigger, or a real-time clock input. The read request or external input initiates the analog
conversion of the first channel of each sample, following which the A/D converter requests an
interrupt. The driver's ISR then initiates conversion of the second to nth channels.
External event triggering assumes either that an external event signal, asserted low, is connected
to EXT IN L at the 1/0 connector on the board and jumper F2 is connected or that jumper Fl
is connected for the LSI-11 bus (Q-bus) BEVNT line.
Real-time clock triggering assumes that the real-time clock (KWVll-C) is present and that
the clock output signal (CLK OVL-clock overflow, asserted low) is connected to RTC IN L
(real-time clock input, asserted low) on the A/D board.
After the SET_ANALOG__MODE operation, the driver and device are ready for conversions
to be triggered in the specified manner. If external event or real-time clock triggering is in
effect, A/D conversions occur asynchronously with respect to user requests for converted data.
Converted data is transferred from the device to the driver's buffers by the ISR. Once in the
ISR buffers, the data awaits user requests for transfer to user buffers.
The packet-level equivalent of SET_ANALOG__MODE is the IF$SET function.
The syntax for calling the procedure is as follows:
SET_ANALOG_MODE (buffer, trigger, count, ad_desc, reply);

Parameter

Type

Description

VAR buffer

AD_CONTROL _TYPE

User-constructed channel parameter block
specifying the number of channels to be sampled and the identifying number and gain for
each channel.

trigger

INTEGER

Value specifying the method for triggering
A/D conversions-CONVRT_IMED (0) for immediate triggering on receipt of a read request,
EXTERNAL_EVENT (16.) for external event
triggering, or REAL_TIME_CLOCK (32.) for
real-time clock triggering. (The values are defined in ADINC.P AS and correspond to CSR
bit positions.)

count

INTEGER

Optional specification of the total number
of records to be returned, after which read
requests are ignored; the default is 0, which
sets up a continuous read operation.

Analog-to-Digital Converter Driver 7-5

Parameter

Type

Description

VAR acLdesc

STRUCTURE_DESC

Initialized driver queue semaphore descriptor.

VAR reply

STRUCTURE_DESC

Optional initialized reply queue semaphore descriptor; if specified, it is the user's responsibility to wait for the reply.

The data type AD_CONTROL_TYPE, from ADINC.PAS, is shown below:
TYPE
ad_gain = (
ad_gain_1,
ad_gain_2,
ad_gain_4,
ad_gain_8 );
mpx_addr = 0 .. 15;

{Channel number}

ad_chan_desc = PACKED RECORD
chan_num
[BIT(12)] mpx_addr;
gain_sel
[BIT(4)] ad_gain;
END;
ad_control_type = RECORD
num_chan
INTEGER;
chan_ctrl
ARRAY [1 .. 16] OF ad_chan_desc;
END;

NUM_CHAN specifies the number of channels to be sampled.
CHAN _NUM designates the analog input channel (multiplexer address) to be sampled. The
channel number selects either one of 16 single-ended analog input channels or one of eight
differential input channels. Whether the analog input is single-ended or differential is determined
by the installed type of jumper (SI/DI).
GAIN _SEL specifies a gain-select value. The gain corresponding to the possible gain-select
values are shown below:
Value

Gain

Range

AD_GAIN_l
AD_GAIN_2
AD_GAIN_4
AD_GAIN_8

1
2
4
8

lOV
5V
2.5 v
1.25 v

Indication of success or failure of the setup operation is returned in the status field of the AD
driver reply packet.
Note
The AD_CONTRQL _TYPE data structure and its conversion control information
are diagrammed in Section 7.5.1.

7-6 Analog-to-Digital Converter Driver

7 .4.2 READ_ANALOG_SIGNAL
The READ_ANALOG_SIGNAL procedure returns records-sets of converted data-to a userspecified buffer.
If external or real-time clock triggering is in effect, READ_ANALOG_SIGNAL returns records
from the asynchronous device-to-ISR input stream; if none are available, the driver waits until
externally-triggered conversions generate more records. The size of the user buffer-a multiple
of the number of channels sampled, times two (for byte units)-determines the number of
records returned.
If immediate triggering is in effect, READ_ANALOG_SIGNAL triggers the conversion and
returns a single record to the user buffer.

The packet-level equivalent of READ_ANALOG_SIGNAL is the IF$RDL function.
The syntax for calling the procedure is as follows:
READ_ANALOG_SIGNAL (buffer, ad_desc, reply);

Parameter

Type

Description

VAR buffer

ARRAY[first. .last:
INTEGER] OF
INTEGER

Buffer to which one or more records will be
returned

VAR acLdesc

STRUCTURE_DESC Initialized driver queue semaphore descriptor

VAR reply

STRUCTURE_DESC Optional initialized reply queue semaphore descriptor; if specified, it is the user's responsibility
to wait for the reply

Each converted data value is the result of the A/D conversion on the specified channel and
gain. The range of the converted data values depends on the jumper configuration on the
boards. The range of values may be from -4000 (octal) to 3777 (octal) or from 0 to 7777 (octal).
See the hardware user's guide for details on setting the jumpers.
The converted data is stored in the specified buffer, which must begin on a word boundary, as
follows:

+-----------------+
I 1st channel val
<- Beginning of 1st record
I

1--

2nd channel val

1-I

--1

nth channel val I

-----------------1
1st channel val I <- Beginning of 2nd record
I

--1

2nd channel val I
I

--1

nth channel val I <- Last word of mth record

+-----------------+

ML0-883-87

Analog-to-Digital Converter Driver 7-7

The count of transferred bytes is returned in the actual-length field of the AD driver reply
packet.

7.4.3 WRITE_ANALOG_WAIT
The WRITE-ANALOG_WAIT procedure supports D /A conversion via programmed I/O
transfer. The procedure does not use a device driver. WRITE-ANALOG_WAIT interfaces
with the AAVl 1-C and AXVl 1-C D /A converters. It writes one to four (AAVl 1-C) or one to
two (AXVll-C) values from a buffer to one or more D/A channels. WRITE-ANALOG_WAIT
requires that the calling process have I/O page access.
The syntax for calling the procedure is as follows:
WRITE_ANALOG_WAIT (channels, buffer, state);

Parameter

Type

Description

VAR channels

ARRAY[ chan 1..
num_chan:dac_chan]
OF INTEGER

Array specifying channels for the corresponding
entries in the "buffer" array to be written to;
buffer[n] is written to channels[n]

VAR buffer

ARRAY[vall..
num_values:
dac_chan] OF
INTEGER;

Array of integers to be written to D /A converters
specified in the "channels" array

VAR state

UNSIGNED

Location to which to return status code; a returned value of 1 signals success, and a returned
value of -1 indicates an invalid parameter

The data type DAC_CHAN, from ADINC.PAS, is shown below:
TYPE
dac_chan = 0 .. 3;

7.5 Request/Reply Packet Interface
The packet-level functions provided by the AD driver are listed below by symbolic and decimal
function code:
Code

Function

IF$RDL (1)

Read Logical (Read Converted Data)

IF$SET (6)

Set Characteristics (Configure Device)

IF$GET (7)

Get Characteristics

If a request is received for an Open (IF$LOK or IF$ENT), a Close (IF$CLS), or a Purge

(IF$PRG), the driver returns an illegal function status code (ES$IFN), which the ACP (Open) or
OTS (Close/Purge) interprets as indicating that no device-dependent processing was required
for that operation.

7-8

Analog-to-Digital Converter Driver

Note
The MACR0-11 symbols used in this section are defined by the DRVDF$ macro,
which resides in the COMU and COMM kernel macro libraries. The equivalent
Pascal symbols are defined in the IOPKTS.P AS include file.
A single function modifier is recognized by the AD driver, as shown below:
Code

Function

FM$BSM (bit 13)

Signal binary /counting semaphore

The AD driver consists of an initialization process, which lowers its priority to become the
first controller's request handler process, plus an additional request handler process for each
controller configured. 1/0 requests for a controller are sent (using a Pascal SEND or a MACR011 SEND$) to the request queue semaphore waited on by that controller's request handler
process.
The request queue names and number of supported units for AD driver requests are shown
below:

Driver

Request
Queue Name

Number
of Units

Numbering

A/D converter

$ADc

The letter c in a queue name represents a controller designation (A, B, ... , as specified in an AD
driver prefix file).

Analog-to-Digital Converter Driver 7-9

The general format of the A/D request and reply packets is shown below:
AD
REQUEST
PACKET

+-----------------+
I
Standard

+-----------------+
Standard
I
I
I

,-,--

I--

'
,-'
I

packet

I
I

header

,----------------DP. FUN - I
Fune ti on
,----------------DP.UNI - I
i Unit
,----------------DP.SEQ - I Sequence number
I

I
I
I

Requesting

Funeindep
value
data

Reply
semaphore
identifier

driver
v

Request
I
I

data
Reserved

Funedep
value
data

DP.BUF -

Buffer

DP.PAR -

address

DP.LEN -

Buffer length

+-----------------+

usage

----------------Reply data
-----------------

- DP.FDD

Not
used

I
I

identifier

DP.DAD -

header

,----------------Function
- DP.FUN
,----------------Unit
- DP.UNI
,----------------Sequence number
- DP.SEQ
----------------Status code
- DP.STS
----------------Actual length
- DP.ALN
----------------Error info
- DP.ERR
----------------Reserved for
- DP.XTR

I
I
I

process

DP.SEM -

packet

I
I
I

I
I

DP.PDB -

I
I
I

AD
REPLY
PACKET

v
Ref
data
info
v

----------------Reserved

+-----------------+ ML0-884-87

7-10 Analog-to-Digital Converter Driver

7 .5. l Set Characteristics (Configure Device) Function
The Set Characteristics (IF$SET) function sets up and enables A/D conversion, specifying the
method of triggering the conversion, the number of analog input channels to sample and their
identifying numbers, and the gain on each channel. Optionally you can set a limit on the total
number of records (sets of samples) to return, after which read requests will be ignored.
A/D conversions can be started by a read request (immediate triggering), an external event
trigger, or a real-time clock input. The read request or external input initiates the analog
conversion of the first channel of each sample, following which the A/D converter requests an
interrupt. The driver's ISR then initiates conversion of the second to nth channels.
External event triggering assumes either that an external event signal, asserted low, is connected
to EXT IN L at the 1/0 connector on the board and jumper F2 is connected or that jumper Fl
is connected for the LSI-11 bus (Q-bus) BEVNT line.
Real-time clock triggering assumes that the real-time clock (KWVll-C) is present and that
the clock output signal (CLK OVL-clock overflow, asserted low) is connected to RTC IN L
(real-time clock input, asserted low) on the A/D board.
After the Set Characteristics operation, the driver and device are ready for conversions to be
triggered in the specified manner. If external event or real-time clock triggering is in effect, A/D
conversions occur asynchronously with respect to user requests for converted data. Converted
data is transferred from the device to the driver's buffers by the ISR. Once in the ISR buffers,
the data awaits user requests for transfer to user buffers.

Analog-to-Digital Converter Driver 7-11

The function-dependent portions of the Set Characteristics request and reply packets are shown
below:

DP.DAD

Trigger
- -----------------

- DP.FDD

----------------Record count
-----------------

I
I

Funedep
value
data

Not used

DP.BUF -

----------------Buffer

DP.PAR -

address

DP.LEN -

----------------Buffer length
+-----------------+

Ref
data
info
v
ML0-885-87

The trigger word specifies the method for initiating an A/D conversion. The value 0 specifies
immediate conversion on receipt of a read request, 16 (bit 4 set) specifies external triggering, and
32 (bit 5 set) specifies real-time clock triggering. (The values correspond to CSR bit positions.)
The record count specifies the total number of records (sets of converted data) to be returned,
after which end-of-file is considered to have been reached. Read requests received after that
point are ignored. A record count of 0 sets up a continuous read operation.
The buffer-address and buffer-length fields specify the location and length of a user-constructed
channel parameter block that gives control information for the conversion of the digitized data.
The control information consists of a count of the number of channels to be sampled, plus a
descriptor word for each channel, as shown below:

+-----------------+
Channel count
Gn : 1st chn no.
Gn : 2nd chn no.

I
I
I

1-----------------1
: Gn : nth chn no.I
+-----------------+
I

ML0-886-87

7-12 Analog-to-Digital Converter Driver

The 4-bit Gn field specifies a gain-select value, an unsigned binary integer in the range O
through 3. The gain corresponding to the possible gain-select values are shown below:

Value

Gain

Range

lOV

2.5 v

1.25 v

The channel number is a 12-bit unsigned integer in the range 0 through 15 designating the
analog input channel (multiplexer address) to be sampled. It selects either one of 16 singleended analog input channels or one of eight differential input channels. Whether the analog
input is single-ended or differential is determined by the installed type of jumper (SI/DI).

7 .5.2 Read Logical (Read Converted Data) Function
The read (IF$RDL) function returns records-sets of converted data-to a user-specified buffer.
If external or real-time clock triggering is in effect, the read returns records from the asynchronous
device-to-ISR input stream; if none are available, the driver waits until externally-triggered
conversions generate more records. The size of the user buffer-a multiple of the number of
channels sampled, times two (for byte units)-determines the number of records returned.
If immediate triggering is in effect, the read request triggers the conversion and returns a single
record to the user buffer.

The function-dependent portions of the read request and reply packets are shown below:

DP.DAD

----------------Not
used

----------------Reserved
----------------Not

DP.LEN

Funedep
value
data

used

address

Ref
data
info

----------------Buffer
DP.BUF DP.PAR -

- DP.FDD
I
I

----------------Buffer length

+-----------------+

Not used

v
ML0-887-87

Each converted data value is the result of the A/D conversion on the specified channel and
gain. The range of the converted data values depends on the jumper configuration on the
boards. The range of values may be from -4000 (octal) to 3777 (octal) or from 0 to rJ777 (octal).
See the hardware user's guide for details on setting the jumpers.

Analog-to-Digital Converter Driver 7-13

The converted data is stored in the specified buffer, which must begin on a word boundary, as
follows:

+-----------------+
I 1st channel val I <- Beginning of 1st record
I

1--

--1

I 2nd channel val I
:---1
I

1--

nth channel val

1----------------1st channel val
I

<- Beginning of 2nd record

1
I

1--

2nd channel val

1-I

1--

--,

I nth channel val I <- Last word of mth record

+-----------------+

ML0-888-87

The count of transferred bytes is returned in the actual-length field of the AD driver reply
packet.

7.5.3 Get Characteristics Function
The A/D Get Characteristics (IF$GET) function returns, in the function-dependent portion of
the reply message, the codes for A/D device class and type.
The function-dependent portions of the A/D Get Characteristics request and reply packets are
shown below:
I
I
I

DP.DAD -

-----------------,
I

I
I

--1

Funcdep
value
data

Not
used

,----------------: Type : Class
- DP.FDD
,----------------I

DP.BUF Ref
data
info

DP.PAR DP.LEN -

+-----------------+

In the preceding information:

7-14

•

Class is DC$RLT for real-time device class.

•

Type is RT$ADV for the ADVll-C, RT$AXV for the AXVll-C.

Analog-to-Digital Converter Driver

ML0-889-87

7 .6 Status Codes
If an A/D device or the AD driver detects an error during an I/O operation, the driver returns
an exception code in the status-code (DP.STS) field of the reply message. If you are performing

I/O with Pascal IjO statements-that is, not with send/receive statements or Pascal support
routine calls-the Pascal OTS will raise the corresponding exception (unless the operation was
an OPEN for which a STATUS return was specified). If no error is detected during the I/O
operation, a value of ES$NOR (0) is returned in the status-code (DP .STS) field of the reply
message.
The AD driver returns the following exception codes:

Code

Type

Description

- ES$IVP

HARD_IO

Invalid parameter: negative channel count, channel or gain out
of range

ES$IFN

SOFT_IO

Illegal function; also used internally to signal ACP or OTS that
no device-dependent processing of an Open, Close, or Purge
was required

Exception codes are defined in the ESCODE.P AS include file (included by EXC.P AS) for Pascal
users and by the EXMSK$ macro in the COMU/COMM macro libraries for MACR0-11 users.
Note
Not listed above are exception codes for OTS-detected I/O errors or for kerneldetected errors that the AD driver raises rather than passing back to the
requesting process. OTS-detected I/O errors are listed in Chapter 9 of the

MicroPower /Pascal Language Guide.

7. 7 AD Driver Prefix File
Figure 7-1 shows the AD driver prefix module. The following paragraphs describe the prefix
file macro calls and symbol definitions that can be edited to fit your application.
The symbols AD$IPR, AD$PPR, and AD$HPR define the initialization and request-handling
software priorities for the driver process and the hardware interrupt priority for the controller(s).
The DRVCF$ macro contains a field for the number of controllers on the target to be supported
by the driver. The dname field specifies the first two characters of the corresponding request
queue semaphore name.
The CTRCF$ macro is invoked once for each controller to be serviced by the driver. It gives
the controller name, number of units (1), CSR and vector addresses, unit number (0), and ISR
buffer size.
The ISR buffer size-normally a multiple of the record size (as determined by a
SET_ANALOG_MODE or IF$SET operation)-applies to each of two internal buffers that
receive converted data from the device for transfer to user buffers. The driver swaps the buffers
as necessary to maintain a steady flow of data.
The interrupt vectors must also be specified in the system configuration file, using the DEVICES
macro.

Analog-to-Digital Converter Driver 7-15

Figure 7-1:
.title

AD Driver Prefix File (ADPFX.MAC)
- AID Converter Prefix Module

ADPFX

THIS SOFTWARE IS FURNISHED UNDER A LICENSE AND MAY BE USED OR COPIED
ONLY IN ACCORDANCE WITH THE TERMS OF SUCH LICENSE.
COPYRIGHT (c) 1984, 1986 BY DIGITAL EQUIPMENT CORPORATION. ALL RIGHTS
RESERVED .
. mcall
.mcall
.mcall

drvcf$
ctrcf$
adisz$

adisz$
AD$PPR
AD$HPR
AD$IPR
drvcf $
ctrcf $
. end

7-16

184.
4

250.

Process priority
AID hardware priority
Process initialization priority

dname=AD,nctrl=1
cname=A,nunits=1. ,csrvec=<170400,400>,units=<O:O>,typrm=64 .

Analog-to-Digital Converter Driver

Chapter 8
Real-Time Clock Driver
This chapter describes the use of the MicroPower/Pascal real-time clock (KW) driver, which
supports I/O operations on the KWVll-C programmable real-time clock.
The KWVll-C can be programmed to count from one of five crystal-controlled frequencies,
from an external input frequency, from an external event or number of events, or from the
50/60 Hz line frequency on the LSI-11 bus (Q-bus). The clock can generate interrupts or can
synchronize the processor to external events. The clock has a counter that can be programmed
to operate in any of the following modes: single interval, repeated interval, external event
timing, or external event timing from zero base.
The KWVl 1-C clock has two Schmitt triggers. In response to external events, they can start
the clock, start analog-to-digital (A/D) conversions in an A/D converter (see Chapter 7), or
generate program interrupts to the processor.
An A/D conversion may be started at a crystal-controlled rate, at a line frequency rate (50/60
Hz), or from an external event input.
·
·

8. 1 KW Driver Features and Capabilities
The KW driver supports reading, enabling, and disabling of the KWVll-C real-time clock and
returning of standard device characteristics.
Read operations support the external event modes of the KWVll-C. You can record the time of
external events or the time between external events. In addition, two events can be monitored
with respect to each other.
The clock enabling operation sets up the clock for interval timing or as a free-running clock
used to initiate A/D conversions.
The clock disabling operation stops the clock by disabling interrupts on the device.
The Get Characteristics operation returns codes for device class and type.

Real-Time Clock Driver 8-1

8.2 Performing Real-Time Clock 1/0
For most MicroPower/Pascal applications, you perform real-time clock IjO by invoking the Pascal support routines READ_COUNTS_WAIT, READ_COUNTS_SIGNAL,
STARLJUCLOCK, and STOP_RTCLOCK. Those rol,ltines provide high-level nonfile access
to a clock. The KW support routines issue Pascal send requests to the request queue semaphore
of the KW driver. The routines are described in Section 8.3 (Pascal Support Routine Interface).
Note
DIGITAL recommends that you do not perform file-oriented operations on a
real-time clock. Although the KW driver does not prevent you from opening a
file for clock data, the operation is of little use; the KW read, clock enabling and
disabling, and Get Characteristics operations cannot be performed with standard
Pascal I/O statements, such as GET and WRITE.
In addition to invoking the KW support routines, you must:
1. Edit the DEVICES macro in the system configuration file to reflect the KW controller interrupt
vector addresses
2.

Edit the KW driver prefix file to reflect:
•

Number of controllers

•

[For each controller:] Controller identifier (A, B, ... ), CSR address, interrupt vector
address, number of controller units (1) and identifying number

•

Hardware interrupt priority

•

Driver initialization and request-handling process priorities

Build into your application the following I/O system components:
•

KW driver process

•

[For A/D conversion triggering:] AD driver process (see Chapter 7)

•

Pascal real-time clock support routines (from kit files KWSUB.PAS and KWINC.PAS)

For more information on setting up your application software for real-time clock IjO, see
Chapter 4 of the MicroPower /Pascal Run-Time Services Manual, Section 8.6 of this manual, and
the material on building system processes in the MicroPower/Pascal system user's guide for
your host system.
As an alternative to using the Pascal support routines described in this chapter to perform
real-time clock IjO, you can issue your own Pascal or MACR0-11 packet-level requests to the
driver (low-level nonfile access).
The following sections describe the Pascal support routine interface to the KW driver, the
lower-level request/reply packet interface, the status codes that can be returned to users of
either interface, and the KW driver prefix file.

8-2

Real-Time Clock Driver

8.3 Pascal Support Routine Interface
The following support routines, written in Pascal and independent of the file system, provide a
high-level interface to the real-time clock hardware:
•

READ_COUNTS_WAIT

•

READ_COUNTS_SIGNAL

•

START__RTCLOCK

•

STOP__RTCLOCK
Note
The real-time clock support routines perform all the packet-level KW driver
functions except Get Characteristics (IF$GET). See the kit file GETSET.PAS for
a nonfile-oriented Get Characteristics function.

The following sections describe the Pascal routines for real-time clock I/O. Each routine allocates
an I/O packet, fills it in with information based on the procedure parameters, and sends it
to the KW driver queue semaphore. Most of the routines then issue a RECEIVE request
for the KW driver reply and return to the caller after the reply is received. However, the
READ_COUNTS_SIGNAL routine returns to the caller immediately after SENDing to the
driver. If a reply parameter was specified on the READ_COUNTS~SIGNAL call, the driver
sends a standard driver reply via the specified queue semaphore when the operation is complete.
(The driver reply packets are described in Section 8.4.)
The following files on the MicroPower/Pascal distribution kit are required for using the routines:

File

Description

KWSUB.PAS

Real-time clock routine source module

KWINC.PAS

Real-time clock routine include file

IOPKTS.PAS

Pascal 1/0 include file

To use a source module, you must compile it and then merge it with the program at user-process
build time. The associated include files must be included in the program at compile time.

8.3. 1 READ_COUNTS_WAIT
The READ_COUNTS_WAIT procedure reads a block of counts from the programmable realtime clock. It issues a Read Physical request to the KW driver and waits until it is completed to
return. READ_COUNTS_WAIT can be used to record the time of external events or the time
between external events. Also, two events can be monitored with respect to each other.
External events are detected by Schmitt triggers, two of which reside on the KWVll-C board.
The primary Schmitt trigger is the second one, ST2. It can be used to cause interrupts or to
start the clock. The first Schmitt trigger, STl, can be used only to increment the clock.
To record the time of external events or the time between external events, a fixed rate is specified
for the source. The clock is started by either the driver setting the GO bit in the CSR or by the
first external event on Schmitt trigger 2. When the clock starts, the clock counter is cleared and
subsequently incremented at the specified rate. When an event occurs on Schmitt trigger 2, the

Real-Time Clock Driver 8-3

value of the counter is transferred to the buffer/preset register, and an interrupt is requested. If
zero-base is specified, the counter is zeroed; otherwise, the clock is incremented from its current
value. (Continuous incrementing gives the time of the event, and zero-base gives the time
between events.) The JSR reads the count from the buffer/preset register and copies it to the
user-specified buffer. An overrun condition occurs when a second external event occurs before
the JSR has read the count from the preceding external event and indicates that the events are
occurring too quickly for the system to handle. An overflow condition occurs when the clock
counter overflows before a second external event occurs and may indicate that too high a rate
was specified.
To measure the relative frequency of one event to another, proceed as above, but specify Schmitt
trigger 1 as the source. Instead of being incremented at a fixed rate, the clock is incremented
by the occurrence of another external event on Schmitt trigger 1.
The syntax for calling the procedure is as follows:
READ_COUNTS_WAIT (buffer, number, source, base, start, kw_desc, state);

Parameter

Type

Description

VAR buffer

ARRAY[first..last:
INTEGER] OF
INTEGER

Buffer that the counter is to be copied to
after each interrupt

number

INTEGER

Number of elements to be copied to the
count array

source

KW_RATE

Value indicating the source of the counts

base

KW_BASE_TYPE

Value indicating the base for counting

start

KW_START_TYPE

Value indicating how the clock is · to be
started

VAR kw_desc

STRUCTURE_DESC

Initialized driver queue semaphore descriptor

VAR state

UNSIGNED

Status code indicating success (ES$NOR=O)
or type of error (see Section 8.5)

8-4 Real-Time Clock Driver

The data types KW_RATE, KW_BASE_TYPE, and KW_START_TYPE, from KWINC.PAS, follow:
TYPE
kw_rate =
kwv_stop,
kwv_1MHz,
kwv_100kHz.
kwv_10kHz,
kwv_1kHz,
kwv_100Hz,
kwv_ST1,
kwv_line ) ;

{ stop the clock }
{ 1000000 Hz }
{ 100000 Hz }
{
10000 Hz }
{
1000 Hz }
{
100 Hz }
{ Schmitt Trigger 1 determines the
clock frequency }
{ Line frequency 50/60 Hz }

kw_base_type =
( rtc_continuous,
rtc_zero_base );

{ Time of event }
{ Elapsed time since previous event }

kw_start_type =
( immediate,
event);

{ The real-time clock is started
immediately }
{ The real-time clock is started
by an external event on Schmitt
trigger 2 }

KW_RATE specifies the source of the counts. The value KWV_STOP is illegal; KWV_lMHZ,
KWV_lOOKHZ, KWV_lOKHZ, KWV_lKHZ, and KWV_lOOHZ specify clock ticks at the
respective rates; KWV_STl specifies counts of events logged on Schmitt trigger 1; and
KWV_LINE specifies clock ticks at the line frequency (50 or 60 Hz).
KW_BASE_TYPE specifies the base for counting. The value RTC_CONTINUOUS specifies that
the count at any event is continuous from the first event; RTC---ZERO_BASE specifies that the
count resets to 0 after each event.
KW_START_TYPE specifies how the clock is to be started. The value IMMEDIATE specifies
that the clock is to be started immediately; EVENT specifies that the clock is to be triggered by
an external event on Schmitt trigger 2.

Real-Time Clock Driver 8-5

8.3.2 READ_COUNTS_SIGNAL
The READ_COUNTS_SIGNAL procedure reads a block of counts from the programmable
real-time clock. READ_COUNTS_SIGNAL is identical to READ_COUNTS_WAIT, except that
it returns immediately after issuing a read request to the KW driver. When the request is
completed, the specified semaphore is signaled. (Correspondingly, READ_COUNTS_SIGNAL
takes a reply parameter where READ_COUNTS_WAIT takes a state parameter.)
READ_COUNTS_SIGNAL can be used to record the time of external events or the time
between external events. Also, two events can be monitored with respect to each other. See
the READ_COUNTS_WAIT discussion of those operations.
The syntax for calling the procedure is as follows:
READ_COUNTS_SIGNAL (buffer, number. source. base, start, kw_desc, reply);

8-6

Parameter

Type

Description

VAR buffer

ARRAY[first..last:
INTEGER OF
INTEGER

Buffer that the counter is to be copied to
after each interrupt

number

INTEGER

Number of elements to be copied to the
count array

source

KW_RATE

Value indicating the source of the counts

base

KW_BASE_TYPE

Value indicating the base for counting

start

KW_START_TYPE

Value indicating how the clock is to be
started

VAR kw_desc

STRUCTURE_DESC

Initialized driver queue semaphore descriptor

VAR reply

STRUCTURE_DESC

Optional initialized reply queue semaphore
descriptor; if specified, it is the user's
responsibility to wait for the reply

Real-Time Clock Driver

The data types KW_RATE, KW_BASE_TYPE, and KW_START_TYPE, from KWINC.PAS, follow:
TYPE
kw_rate =
kwv_stop,
kwv_1MHz,
kwv_100kHz,
kwv_10kHz,
kwv_1kHz,
kwv_100Hz,
kwv_ST1,
kwv_line );
kw_base_type =
( rtc_continuous,
rtc_zero_base );
kw_start_type =
( immediate,
event);

{ stop the clock }
{ 1000000 Hz }
{ 100000 Hz }
{
10000 Hz }
{
1000 Hz }
{
100 Hz }
{ Schmitt Trigger 1 determines the
clock frequency }
{ Line frequency 50/60 Hz }
{ Time of event }
{ Elapsed time since previous event }
{ The real-time clock is started
immediately }
{ The real-time clock is started
by an external event on Schmitt
trigger 2 }

KW_RATE specifies the source of the counts. The value KWV_STOP is illegal; KWV_lMHZ,
KWV_lQOKHZ, KWV_lOKHZ, KWV_lKHZ, and KWV_lOOHZ specify clock ticks at the
respective rates; KWV_STl specifies counts of events logged on Schmitt trigger l; and
KWV_LINE specifies clock ticks at the line frequency (50 or 60 Hz).
KW_BASE_TYPE specifies the base for counting. The value RTC_CQNTINUOUS specifies that
the count at any event is continuous from the first event; RTC-2ERQ_BASE specifies that the
count resets to 0 after each event.
KW_START_TYPE specifies how the clock is to be started. The value IMMEDIATE specifies
that the clock is to be started immediately; EVENT specifies that the clock is to be triggered by
an external event on Schmitt trigger 2.
Indication of success or failure of the read operation is returned in the status field of the KW
driver reply packet.

Real-Time Clock Driver 8-7

8.3.3 START_RTCLOCK
The START_RTCLOCK procedure sets up the real-time clock for interval timing or as a freerunning clock used to initiate A/D conversions. START_RTCLOCK starts the real-time clock
running at a specified rate for either a single interval or a repeated interval. If signaling is
specified, the binary or counting semaphore designated by the user will be signaled at the end
of each interval. If no signaling is specified, clock interrupts are disabled; A/D conversions can
be triggered at the end of each interval while the clock runs freely.
The packet-level equivalent of START_RTCLOCK is the IF$ENA function.
The syntax for calling the procedure is as follows:
START_RTCLOCK

8-8

source, counts, single, start, signals, timer, kw_desc, state);

Parameter

Type

Description

source

KW_RATE

A value indicating the source of the counts

counts

INTEGER

Number of clock ticks at the specified rate
(KW_RATE) until the counter overflows

single

BOOLEAN

Value indicating whether the clock is to run
for a single interval (TRUE) or continuously
at the specified rate (FALSE)

start

KW_START_TYPE

Value indicating how the clock is to be
started

signals

BOOLEAN

Value indicating whether a semaphore is to
be signaled after each interval (TRUE) or not
(FALSE); if the value FALSE is specified, the
clock is started with clock interrupts disabled
and no signal is issued; FALSE should be
specified when the clock is being used to
initiate A/D conversions and no signaling
is desired

VAR timer

STRUCTURE_DESC

Optional descriptor for the binary or counting semaphore to be signaled at the end of
each interval

VAR kw_desc

STRUCTURE_DESC

Initialized driver queue semaphore descriptor

VAR state

UNSIGNED

Status code indicating success (ES$NOR=O)
or type of error (see Section 8.5)

Real-Time Clock Driver

The data types KW_RATE and KW_START_TYPE, from KWINC.PAS, are shown below:
TYPE

kw_rate =
kwv_stop,
kwv_1MHz,
kwv_100kHz,
kwv_10kHz,
kwv_1kHz,
kwv_100Hz,
kwv_ST1,
kwv_line );
kw_start_type =
( immediate,
event);

{ stop the clock }
{ 1000000 Hz }
{ 100000 Hz }
{
10000 Hz }
{
1000 Hz }
{
100 Hz }
{ Schmitt Trigger 1 determines the
clock frequency }
{ Line frequency 50/60 Hz }
{ The real-time clock is started
immediately }
{ The real-time clock is started
by an external event on Schmitt
trigger 2 }

KW_RATE specifies the source of the counts. The value KWV_STOP is illegal; KWV_lMHZ,
KWV_lOOKHZ, KWV_lOKHZ, KWV_lKHZ, and KWV_lOOHZ specify clock ticks at the
respective rates; KWV_STl specifies counts of events logged on Schmitt trigger 1; and
KWV_LINE specifies clock ticks at the line frequency (50 or 60 Hz).
KW_START_TYPE specifies how the clock is to be started. The value IMMEDIATE specifies
that the clock is to be started immediately; EVENT specifies that the clock is to be triggered by
an external event on Schmitt trigger 2.

Real-Time Clock Driver 8-9

8.3.4 STOP_RTCLOCK
The STOP_RTCLOCK procedure stops the KWVl 1-C programmable real-time clock by disabling
interrupts on the device.
The packet-level equivalent of STQP_RTCLOCK is the IF$DSA function.
The syntax for calling the procedure is as follows:
STOP_RTCLOCK ( kw_desc );

Parameter

Type

Description

VAR kw_desc

STRUCTURE_DESC

Initialized driver queue semaphore descriptor

If a READ_COUNTS_SIGNAL request is in progress when this procedure is invoked, the KW

driver reply to that request will indicate that the clock was stopped.

8.4 Request/Reply Packet Interface
The following packet-level functions provided by the KW driver are listed by symbolic and
decimal function code:
Code

Function

IF$RDP (0)

Read Physical

IF$GET (7)

Get Characteristics

IF$ENA (S)
IF$DSA (9)

Enable Clock
Disable Clock

If a request is received for an Open (IF$LOK or IF$ENT), the driver returns an illegal function

status code (ES$IFN), which the ACP interprets as indicating that no device-dependent processing
was required for that operation. However, as noted in Section 8.2, DIGITAL recommends that
you do not perform file-oriented operations on a real-time clock.
Note
The MACR0-11 symbols used in this section are defined by the DRVDF$ macro,
which resides in the COMU and COMM kernel macro libraries. The equivalent
Pascal symbols are defined in the IOPKTS.PAS include file.

8-10

Real-Time Clock Driver

A single function modifier is recognized by the KW driver, as shown below:

Code

Function

FM$BSM (bit 13)

Signal binary/ counting semaphore

The KW driver consists of an initialization process, which lowers its priority to become the
first controller's request handler process, plus an additional request handler process for each
configured controller. 1/0 requests for a controller are sent (using a Pascal SEND or a MACR011 SEND$) to the request queue semaphore waited on by that controller's request handler
process.
The request queue names and number of supported units for KW driver requests are shown
below:

Driver

Request
Queue Name

Number
of Units

Numbering

Real-time clock

$KWc

0 (normally)

The letter c in a queue name represents a controller designation (A, B, ... , as specified in the
KW driver prefix file).

Real-Time Clock Driver 8-11

The general format of the KW request and reply packets is shown below:
KW
REQUEST
PACKET

+-----------------+
Standard

packet

header

----------------DP.FUN Function
----------------DP.UNI Unit
----------------DP.SEQ Sequence number
----------------Requesting
DP.PDB process

header

I
I

Funeindep
value
data

identifier

DP.SEM -

----------------Reply
semaphore

DP.DAD -

Request

Funedep
value
data

I
I

DP.BUF DP.PAR -

address

----------------Buffer length
DP.LEN +-----------------+

usage

----------------Reply data
- DP.FDD
----------------Not
used

data

----------------Buffer

identifier

-----------------

KW
REPLY
PACKET

Ref
data
info
v

----------------Reserved

+-----------------+ ML0-891-87

The function-independent portions of the packets shown above are described in the request/reply
packet interface section of Chapter 1. The valid function and function-modifier codes for the
function (DP .FUN) field and the valid unit number for the unit (DP. UNI) field are listed at the
beginning of this section.
The function-dependent portions of the request and reply packets are described in the sections
that follow for each type of KW driver function.
Note
The MACR0-11 field names shown above do not represent offsets into the user's
send or reply buffers; they are offset symbols used by MACR0-11 drivers to
reference packets. For example, DP .FUN is a 6-byte offset from the packet
header.

8-12

Real-Time Clock Driver

8.4. 1 Read Physical Function
The Read Physical (IF$RDP) function reads a block of counts from the programmable real-time
clock. It can be used to record the time of external events or the time between external events.
Also, two events can be monitored with respect to each other.
External events are detected by Schmitt triggers, two of which reside on the KWVl 1-C board.
The primary Schmitt trigger is the second one, ST2. It can be used to cause interrupts or to
start the clock. The first Schmitt trigger, STl, can be used only to increment the clock.
To record the time of external events or the time between external events, a fixed rate is specified
for the source. The clock is started by either the driver setting the GO bit in the CSR or by the
first external event on Schmitt trigger 2. When the clock starts, the clock counter is cleared and
subsequently incremented at the specified rate. When an event occurs on Schmitt trigger 2, the
value of the counter is transferred to the buffer/preset register, and an interrupt is requested. If
zero-base is specified, the counter is zeroed; otherwise, the clock is incremented from its current
value. (Continuous incrementing gives the time of the event, and zero-base gives the time
between events.) The ISR reads the count from the buffer/preset register and copies it to the
user-specified buffer. An overrun condition occurs when a second external event occurs before
the ISR has read the count from the preceding external event and indicates that the events are
occurring too quickly for the system to handle. An overflow condition occurs when the clock
counter overflows before a second external event occurs and may indicate that too high a rate
was specified.
To measure the relative frequency of one event to another, proceed as above, but specify Schmitt
trigger 1 as the source. Instead of being incremented at a fixed rate, the clock is incremented
by the occurrence of another external event on Schmitt trigger 1.
The .function-dependent portions of the read request and reply packets are shown below:

DP.DAD

Clock control
- -----------------

----------------Count

-----------------

- DP.FDD
I
I

Funedep
value
data

Not used

DP.BUF -

----------------Buffer

DP.PAR -

address

DP.LEN -

----------------Buffer length

+-----------------+

-----------------1

I
I

Ref
data
info
v
ML0-890-87

Real-Time Clock Driver 8-13

The clock control word has the format shown below:
15

+-----------------------------------------------+
+-----------------------------------------------+
:
+------ Clock mode
+------------- Clock rate
+---------------------------------------- External trigger
I
I

I
I

ML0-892-.87

The bit fields shown contain clock control information. Proceeding from right to left in the
format above:
•

Bits 1 and 2 specify the clock's mode of operation, as shown below:

Value

Mode

External event timing

External event timing from zero base

In external-event timing mode, you can generate a pulse train while monitoring external
events, record the time of external events, or count external events. Two external events
can be monitored with respect to each other. The counter increments at the user-selected
clock rate or at the rate of external input until it overflows. An input at Schmitt trigger 2
(ST2) causes the contents of the counter to be loaded into the buffer/preset register (BPR),
where it can be read by the KW device driver.
External-event timing from a zero base is the same as external-event timing, except that the
clock is reset to 0 after each event.
•

8-14

Bits 3 through 5 select the clock rate, as shown below:

Value

Rate of Operation

STOP

1 MHz

100 kHz

10 kHz

1 kHz

100 Hz

STl external input

Line (50 / 60 Hz)

Real-Time Clock Driver

•

Bit 13, if set, specifies that the clock is to be started by an external event (Schmitt trigger
2); otherwise, the KW driver starts the clock immediately.

The count word (offset DP.DAD+2) supplies one of the following values:
•

The number of clock pulses that will generate the time delay required at the user-selected
clock frequency

•

The number of line inputs (BEVNT) that will generate a real-time reference to record the
time of an external event at Schmitt trigger 2 (ST2)

•

The number of external events to be counted at Schmitt trigger 1 (STl) before an overflow
occurs

The KW device driver copies the two's complement of the count value to the clock's buffer/preset
register.
The buffer-address and buffer-length fields specify the buffer to which the counter is to be
copied after each interrupt. The buffer address must be on a word boundary.

8.4.2 Enable Clock Function
The Enable Clock (IF$ENA) function sets up the real-time clock for interval timing or as a
free-running clock used to initiate A/D conversions. Enable Clock starts the real-time clock
running at a specified rate for either a single interval or a repeated interval. If signaling is
specified, the binary or counting semaphore designated by the user will be signaled at the end
of each interval. If no signaling is specified, clock interrupts are disabled; A/D conversions can
be triggered at the end of each interval while the clock runs freely.
The function-dependent portions of the Enable Clock request and reply packets are shown
below:

DP.DAD

Clock control
- -----------------

----------------Count
----------------Signal

- DP.FDD
I
I

Funedep
value
data

Not used

semaphore

DP.BUF DP.PAR DP.LEN

identifier

Not used

Ref
data
info
v

----------------+-----------------+

ML0-893-87

Real-Time Clock Driver 8-15

The clock control word has the format shown below:
15

+-----------------------------------------------+
+-----------------------------------------------+
,..
"'

.....

+- Signal semaphore

+------ Clock mode

+------------- Clock rate
+---------------------------------------- External trigger
ML0-894-87

The bit fields shown contain clock control information. Proceeding from right to left:
•

Bit 0, if set, causes a binary or counting semaphore to be signaled after each clock interrupt;
the bit should not be set when the clock is being used to trigger A/D conversions.

•

Bits 1 and 2 specify the clock's mode of operation, as shown below:
Value

Mode

Single interval

Repeated interval

In single-interval mode, the clock's counter is set, and the clock increments at the userselected clock rate until it overflows and stops.
In repeated-interval mode, the clock's counter is set, and the clock increments at the userselected clock rate until it overflows. Upon over.flow, the clock-over.flow signal is generated,
the clock's counter is reset, and counting continues. This mode is used for repeated clock
signals.
•

8-16

Bits 3 through 5 select the clock rate, as shown below:
Value

Rate of Operation

STOP

1 MHz

100 kHz

10 kHz

1 kHz

100 Hz

STl external input

Line (50 / 60 Hz)

Real-Time Clock Driver

•

Bit 13, if set, specifies that the clock is to be started by an external event (Schmitt t_;_·;~ger
2); otherwise, the KW driver starts the clock immediately

The count word (offset DP.DAD+2) supplies one of the following values:
•

The number of clock pulses that will generate the time delay required at the user-selected
clock frequency

•

The number of line inputs (BEVNT) that will generate a real-time reference to record the
time of an external event at Schmitt trigger 2 (ST2)

•

The number of external events to be counted at Schmitt trigger 1 (STl) before an overflow
occurs

The KW device driver copies the two's complement of the count value to the clock's buffer/preset
register.
The signal semaphore identifier field (beginning at offset DP.DAD+4) specifies the binary or
counting semaphore, if any, to be signaled after each clock interrupt.

8.4.3 Disable Clock Function
The Disable Clock (IF$DSA) function stops the KWVll-C programmable real-time clock by
disabling interrupts on the device.
If a read request is in progress when the clock is disabled, the KW -driver reply to that request
will indicate that the clock was stopped.

The function-dependent portions of the Disable Clock request and reply packets are not used.

8.4.4 Get Characteristics Function
The KW Get Characteristics (IF$GET) function returns the codes for real-time clock device class
and type in the function-dependent portion of the reply message.
The function-dependent portions of the Get Characteristics request and reply packets are shown
below:
I
I

DP.DAD -

-----------------:

I
I
I

--,

Type
Funcdep
value
data

Not
used

I Class

- DP.FDD

Not
used

DP.BUF Ref
data
info

DP.PAR DP.LEN -

+-----------------+

v
ML0-895-87

Real-Time Clock Driver 8-17

In the preceding information:
•

Class is DC$RLT for real-time device class.

•

Type is RT$KWV for the KWVl 1-C.

8.5 Status Codes
If an error is detected during an I/O operation by the real-time clock or the KW driver, the
driver returns an exception code in the status-code (DP.STS) field of the reply message. If no
error is detected during the I/O operation, a value of ES$NOR (0) is returned.

The KW driver returns the following exception codes:

Code

Type

Description

ES$ABT

HARD-10

I/O request aborted by user

ES$IVM

HARD_IO

Invalid mode

ES$IFN

SOFT_IO

Illegal function

Exception codes are defined in the ESCODE.P AS include file (included by EXC.PAS) for Pascal
users and by the EXMSK$ macro in the COMU /COMM macro libraries for MACR0-11 users.
Note
Not listed above are exception codes for kernel-detected errors that the KW
driver raises rather than passing back to the requesting process.

8.6 KW Driver Prefix File
Figure 8-1 shows the KW driver prefix module. The following paragraphs describe the prefix
file macro calls and symbol definitions that can be edited to fit your application.
The symbols KW$IPR, KW$PPR, and KW$HPR define the initialization and request-handling
software priorities for the driver process and the hardware interrupt priority for the controller(s).
The DRVCF$ macro contains a field for the number of controllers on the target to be supported
by the driver. The dname field specifies the first two characters of the corresponding request
queue semaphore name.
The CTRCF$ macro is invoked once for each controller to be serviced by the driver. It gives
the controller name, number of units (1), CSR and vector addresses, and unit number.
Note that the interrupt vectors must also be specified in the system configuration file, using the
DEVICES macro.

8-18

Real-Time Clock Driver

Figure 8-1:
.title

KW Driver Prefix File (KWPFX.MAC)

KWPFX

- Real-Time Clock Prefix Module

THIS SOFTWARE IS FURNISHED UNDER A LICENSE AND MAY BE USED OR COPIED
ONLY IN ACCORDANCE WITH THE TERMS OF SUCH LICENSE.
COPYRIGHT (c) 1985, 1986 BY DIGITAL EQUIPMENT CORPORATION. ALL RIGHTS
RESERVED .
. mcall
.mcall
.mcall

drvcf$
ctrcf$
kwisz$

kwisz$
KW$PPR
KW$HPR
KW$IPR

184.
5

250.
drvcf $
ctrcf$
ctrcf $

Process priority
Hardware priority
Process initialization priority
dname=KW,nctrl=1
cname=A,nunits=1. ,csrvec=<170420,440>,units=<O:O>
cname=B,nunits=1. ,csrvec=<170420,410>,units=<1:1>

.end

Real-Time Clock Driver 8-19

Chapter 9
Peripheral Processor OMA Driver
This chapter describes the use of the MicroPower/Pascal peripheral processor DMA (QD) driver,
which supports 1/0 operations on the KXTl 1-CA/KXJll-CA 2-channel DMA transfer controller
(DTC). The KXTl 1-CA/KXJl 1-CA DTC transfers data between any two of the following:
•

A local address

•

A Q-bus address

•

An 1/0 device on the arbiter processor's Q-bus

•

An 1/0 device connected directly to the KXTl 1-CA or KXJll-CA
Note
The QD driver can be used to perform DMA transfers via a KXTl 1-CA or
KXJl 1-CA parallel port. The QD driver coordinates such transfers_ with the
KXTl 1-CA/KXJll-CA parallel IjO (YK) driver. For details, see Section 9.3.4.

9. 1 QD Driver Features and Capabilities
The QD driver supports DMA read and write operations, channel allocation and deallocation,
and the returning of device status information, as follows:
•

Read and write operations transfer a specified number of data bytes between two locations.
Data is transferred by word (the default) or byte, using direct memory access. Once the
operation is initiated, there is no processor intervention.

•

Read and write operations have pattern recognition capabilities for terminating a transfer
when a specified pattern is found or a search limit is reached.

•

Channel allocation dedicates a specified unit for the exclusive use of the calling process.

•

Get Characteristics operations report standard device characteristics and return the contents
of device registers.

Peripheral Processor DMA Driver 9-1

9.2 Performing KXTl 1-CA/KXJl 1-CA OMA 1/0
For most MicroPower/Pascal KXTl 1-CA or KXJl 1-CA applications, you perform DMA transfers
by invoking Pascal support routines-$DMA_TRANSFER; $DMA_SEARCH, and so forth.
Those routines provide high-level nonfile access to the KXTll-CA/KXJll-CA DTC channels.
The QD support routines issue Pascal SEND requests to the request queue semaphore of the
QD driver. The routines are described in Section 9.3.

Note
You cannot perform file-oriented Pascal operations on the KXTl 1-CA/KXJllCA DTC. If you try to open a KXTl 1-CA/KXJl 1-CA DTC file, the QD driver
returns an unsupported function (ES$UFN) exception code, and the OTS raises
the exception (unless you requested a status return).
In addition to invoking the Pascal support routines, you must:
1.

Edit the DEVICES macro in the system configuration file to reflect the DTC interrupt vector
addresses

Edit the KXTll-CA/KXJll-CA DMA driver prefix file to reflect:

•

Number of controllers (normally 1)

•

[For each controller:] Controller identifier (A, B, ... ), CSR address, interrupt vector
address, number of controller units and their identifying numbers (0, 1)

•

Hardware interrupt priority

•

Driver initialization and request-handling process priorities

Build into .your application the following 1/0 system components:
•

KXTl 1-CA/KXJll-CA DMA driver process

•

Pascal KXTll-CA/KXJll-CA DTC support routines (from kit files OMA.PAS and
QDINC.PAS)

For more information on setting up your application software for KXTl 1-CA/KXJl 1-CA DMA
1/0, see Chapter 4 of the MicroPower/Pascal Run-Time Services Manual, Section 9.6 of this
manual, and the material on building system processes in the MicroPower /Pascal system user's
guide for your host system.
As an alternative to using the Pascal support routines for KXTll-CA/KXJll-CA DMA 1/0, you
can issue your own Pascal or MACR0-11 packet-level requests to the driver (low-level nonfile
access). In such a case, do not build the support routines into your application.
The following sections describe the Pascal support routine interface to the QD driver, the lowerlevel request/reply packet interface, the status codes that can be returned to users of either
interface, and the QD driver prefix file.

9-2

Peripheral Processor DMA Driver

9.3 Pascal Support Routine Interface
The following support routines, written in Pascal and independent of the file system, provide a
high-level interface to the KXTl 1-CA/KXJl 1-CA DMA channels:
•

$OMA_TRANSFER function

•

$DMA_SEARCH function

•

$DMA_SEARCH_TRANSFER function

•

$DMA_ALLOCATE function

•

$DMA_DEALLOCATE functio

•

$DMA_GET_STATUS function

The following sections describe the Pascal functions for KXTl 1-CA/KXJl 1-CA DMA 1/0. Each·
function takes an 1/0 packet, fills it with information based on the function parameters, and
sends the packet to the QD driver.
If a reply semaphore is provided in the function call, the function returns immediately after
sending the driver request. When the operation is complete, the driver sends a standard device
driver reply via the specified semaphore. (The driver reply is described in Section 9.4.) The
completion status returned in the reply packet must be processed by a routine that is waiting
on the semaphore. For transfer or search operations, the routine that waits on the semaphore
must also process the actual-length information in the packet.

no reply semaphore is provided-or if the function has no reply parameter
($DMA_ALLOCATE or $DMA_DEALLOCATE)-the function waits for the driver reply before
returning to the caller.

The following files on the MicroPower/Pascal distribution kit are required for using the functions:
Name

Description

IOPKTS.PAS

Pascal 1/0 include file

OMA.PAS

KXTll-CA/KXJll-CA DMA function source module

QDINC.PAS

KXTl 1-CA/KXJl 1-CA DMA function include file

To use a source module, you must compile it and then merge it with the program at user-process
build time. The associated include files must be included in the program at compile time.
The following data type from QDINC.P AS, referenced throughout this section, defines the QD
unit numbers for the support routine interface:
TYPE
DMA$UNIT_NUMBER = 0 .. 1; { 0 for channel A, 1 for channel B}

Peripheral Processor DMA Driver 9-3

9.3. 1 $DMA_TRANSFER
The $DMA_TRANSFER function transfers data between two locations. Each start address
is specified as part of a record of type DMA$ADDRESS. Each address can specify a Q-bus
memory address, an 1/0 device on the arbiter's Q-bus, a local memory address, or an 1/0
device connected directly to the KXTl 1-CA or KXJl 1-CA. In addition, each address record
contains control bit settings that select such options as 1/0 page reference and Q-bus mapping,
address incrementation, hardware request synchronization (used for OMA transfer via a KXTllCA/KXJll-CA parallel port), and use of byte-mode transfers.
The function returns a value of type DMA$BYTE_COUNT-the count of bytes transferred (0
if an error occurred or a reply parameter was provided).
The syntax for calling the function is as follows:
$DMA_TRANSFER ( source, dest, count, unit, reply )

Parameter

Type

Description

source

DMA$ADDRESS

Q-bus or local address from which data will
be transferred

dest

DMA$ADDRESS

Q-bus or local address to which data will be
transferred

count

DMA$BYTE_COUNT

Number of bytes to transfer

unit

DMA$UNIT_NUMBER

Optional unit number; default is 0 (channel
A)

DMA$SEM_POINTER

Optional pointer to an initialized reply
queue semaphore descriptor; default is NIL

The data types DMA$ADDRESS, DMA$BYTE_COUNT, and DMA$SEM_pQINTER, from
QDINC.PAS, are shown below.

Note
The DMA$ADDRESS, data structure and its addressing control bits are diagrammed in Section 9.4.1.

TYPE
DMA$ADDR_SPACE = (DMA$IBUS, DMA$QBUS);

{local or qbus space}

DMA$INCR_OPTION = (DMA$UP, DMA$DOWN, DMA$NOINC); {increment up,
down, or not at all }
DMA$WAIT_OPTION = (DMA$WAIT_O)

{ only 0 wait states is
supported}

DMA$REQ_OPTION = (DMA$NOWFR, DMA$WFR);

{ wait for request line active}

DMA$IO_OPTION = (DMA$NOIO, DMA$IO);

{

access I/0 page addresses }

DMA$BYTE_OPTION = (DMA$NOBYTE, DMA$BYTE); { nobyte (word) mode or byte
mode }

9-4 Peripheral Processor DMA Driver

DMA$ADRTYP_OPTION = (DMA$VIRTUAL, DMA$PHYSICAL); {virtual - need to
convert
to
physical,
physical - no need to
convert }
DMA$ADDRESS = PACKED RECORD
LOW: [POS(OO),WORD] UNSIGNED;

{ source or destination
dma address }
{ low portion of 22-bit
address}

HIGH: [POS(16),BIT(6)] 0 .. 63;

{high portion of 22-bit
address}
ADRTYP: [POS(22),BIT(1) DMA$ADRTYP_OPTION {physical or virtual}
IO: [POS(24) ,BIT(1)] DMA$IO_OPTION;
{ IO mode ? }
WS: [POS(25),BIT(2)] DMA$WAIT_OPTION;
{number of wait states to add}
INC: [POS(27) ,BIT(2)] DMA$INCR_OPTION; { UP or DOWN or NOINC }
WFR: [POS(29),BIT(1)] DMA$REQ_OPTION;
{wait for request?}
BM: [POS(30),BIT(1)] DMA$BYTE_OPTION;
{byte mode?}
SPACE: [POS(31),BIT(1)] DMA$ADDR_SPACE { IBUS OR QBUS}
END;
DMA$BYTE_COUNT =UNSIGNED;

{ number of bytes to transfer }

DMA$SEM_POINTER = - SEMAPHORE_DESC;

{ pointer to sem desc }

CONST
{

These constants are used to initialize variables of
type DMA$ADDRESS.
}

DMA$NORM_iBUS_ADDRESS = DMA$ADDRESS ( 0, 0, DMA$VIRTUAL, DMA$NOIO,
DMA$WAIT_O, DMA$UP, DMA$NOWFR,
DMA$NOBYTE, DMA$IBUS );
DMA$NORM_QBUS_ADDRESS = DMA$ADDRESS ( 0, 0, DMA$PHYSICAL DMA$NOIO,
DMA$WAIT_O, DMA$UP, DMA$NOWFR,
DMA$NOBYTE, DMA$QBUS );

In the function call, the source and the destination arguments must be records of type
DMA$ADDRESS.
If the DMA$VIRTUAL option is specified, either the interface routine or the driver converts the

address to a physical address. This is necessary because the DTC requires physical addresses.
If the DMA$PHYSICAL option is specified, the address is not converted. You must specify
a physical address for any Q-bus address. For unmapped applications, virtual addresses are
the same as physical addresses. Therefore, you can use either option. There is a little more
overhead if you use the DMA$VIRTUAL option, but the same source code can then be used in
both mapped and unmapped applications.
If you wish to convert a virtual buffer address to a physical address yourself, instead of letting
the interface routine or the driver do it, you can use the function $TRAN_VIRT_pHYS in
DMA.P AS to perform the conversion. This is necessary if a mapped arbiter application wants
to tell a KXTl 1-CA or KXJl 1-CA peripheral processor to use the DTC to transfer to or from a
Q-bus buffer. The arbiter application must convert the virtual Q-bus buffer address to a physical
Q-bus address and pass that physical address to the KXTl 1-CA or KXJll-CA.
If the addressing control option DMA$IO is specified, the DMA address references the I/O page
rather than normal memory locations.

Peripheral Processor DMA Driver 9-5

The DMA$WAIT_n options specify the number of wait states to be programmed into DMA
address access. Only a value of 0 wait states is supported.
The DMA$UP, DMA$DOWN, and DMA$NOINC options cause the address to be incremented,
decremented, or held constant during a transfer.
If the DMA$WFR option is specified, the driver waits for a hardware request (request line active)
for a transfer. This option is used to coordinate the DTC and the KXTll-CA/KXJll-CA PIO
port controller for a OMA transfer via a PIO port. (See Section 9.3.4.) Since this option applies
to the transfer in general and not to just one address, it may be specified in either the source
or the destination address record.
If the DMA$BYTE option is specified, data is transferred in byte mode rather than word mode.
Byte mode is supported only for I/Oto or from a local (internal bus) byte-oriented device-for
example, a parallel port or an asynchronous line-with the other address even. (Section 9.3.4
describes DMA transfer via a parallel port.) Use word mode for memory-to-memory {and Q-bus)
transfers. Byte-to-word and word-to-byte funneling are not supported. Since this option applies
to the transfer in general and not to just one address, it may be specified in either the source
or the destination address record.
If the DMA$QBUS option is specified, the DMA address is mapped to Q-bus space rather than
the internal bus. (Byte mode cannot be selected when DMA$QBUS is specified.)

9.3.2 $DMA_SEARCH
The $DMA_SEARCH function searches data for a user-specified search value, beginning at a
user-specified Q-bus or local address. The search terminates either when the search value is
matched or when a specified byte count expires.
The function returns a value of type DMA$BYTE_COUNT-the number of bytes searched (0
if an error occurred or if a reply parameter was provided).
The syntax for calling the function is as follows:
$DMA_SEARCH

source, count, val, mask, unit, reply )

Parameter

Type

Description

source

DMA$ADDRESS

Q-bus or local address at which search will begin

count

DMA$BYTE_COUNT

Maximum number of bytes to search

val

UNSIGNED

Search value

mask

UNSIGNED

Optional search mask; default is 0

unit

DMA$UNIT_NUMBER

Optional unit number; default is 0 {channel A)

DMA$SEM_POINTER

Optional pointer to an initialized reply queue
semaphore descriptor; default is NIL

The DMA$ADDRESS data type is listed and described in Section 9.3.1 and is diagrammed in
Section 9 .4 .1.

9-6

Peripheral Processor DMA Driver

The DMA$BYTE_COUNT and DMA$SEM_POINTER data types, from QDINC.PAS, are shown
below:
TYPE
DMA$BYTE_COUNT = UNSIGNED;

{ number of bytes to transfer or search }

DMA$SEM_POINTER = - SEMAPHORE_DESC;

{ pointer to sem desc }

Bits set to 1 in the mask parameter mask out bits in the object word. For example, to search
only the low-order byte of each word in a buffer, you should specify a mask parameter with
all eight high-order bits set to 1. Thus, the low-order byte of each word in the buffer will be
compared with the low-order byte of the search value parameter.
To search for a byte in a buffer, you must perform two search operations. You must first search
the low-order byte of each word and mask out the high, then search the high-order byte of
each word and mask out the low. When the high-order byte is being searched, the search
value must be shifted to the high-order byte. For example, to search a buffer for the byte
value, value_to_find, the appropriate search value and search mask parameters would be, for
the low-order search, VAL := value_to_find and MASK:= %0'177400', and, for the high-order
search, VAL := (value_to_find * 256) and MASK := %0'377'.

9.3.3 $DMA_SEARCH_TRANSFER
The $DMA_SEARCH_TRANSFER function causes data to be transferred until either a search
value is matched or a byte count expires. Each start address is specified with a record of type
DMA$ADDRESS. Each address can specify a Q-bus memory address, an 1/0 device on the
arbiter's Q-bus, a local memory address, or an 1/0 device connected directly to the KXT11-CA
or KXJl 1-CA. In addition, each address record contains control bit settings that select such
options as 1/0 page reference and Q-bus mapping, address incrementation, hardware request
synchronization (used for DMA transfer via a KXT11-CA/KXJ11-CA parallel port), and use of
byte mode transfers.
The function returns a value of type DMA$BYTE_COUNT-the number of bytes transferred
(0 if an error occurred or if a reply parameter was provided).

Peripheral Processor DMA Driver 9-7

The syntax for calling the function is as follows:
$DMA_SEARCH_TRANSFER ( source, dest, count, val, mask, unit, reply )

Parameter

Type

Description

source

DMA$ADDRESS

Q-bus or local address at which search will begin
and from which data will be transferred

dest

DMA$ADDRESS

Q-bus or local address to which data will be
transferred

count

DMA$BYTE_COUNT

Maximum number of bytes to transfer

val

UNSIGNED

Search value

mask

UNSIGNED

Optional search mask; default is 0

unit

DMA$UNIT_NUMBER

Optional unit number; default is 0 (channel A)

DMA$SEM_POINTER

Optional pointer to initialized reply queue semaphore
descriptor; default is NIL

The DMA$ADDRESS data type is listed and described in Section 9.3.1 and is diagrammed in
Section 9 .4 .1.
The DMA$BYTE_COUNT and DMA$SEM_POJNTER data types, from QDINC.PAS, are shown
below:
TYPE
DMA$BYTE_COUNT = UNSIGNED;

{ number of bytes to transfer or search }

DMA$SEM_POINTER =

{ pointer to sem desc }

SEMAPHORE_DESC;

In the function call, the source and the destination arguments must be records of type
DMA$ADDRESS.

9.3.4 KXTl 1-CA/KXJl 1-CA PIO with OMA
If you want to perform DMA transfers via a KXTl 1-CA or KXJl 1-CA parallel port, you must

first set up a DMA Read or a DMA Write request packet and send it to the YK driver and wait
for the reply. If the reply indicates normal status, you then send a DMA transfer command to
the DMA (QD) driver; otherwise, you report an error or wait. You must wait for each request
to complete, since only one PIO DMA operation can be in progress at a time. After the DMA
transfer completes, you send a DMA Complete request to the YK driver, which unlocks the
queue of requests for that port.
For guidelines to follow when performing DMA I/O on a KXTl 1-CA/KXJl l-CA parallel
port-and a sample program-see Section 6.4.2.4.

9.3.5 KXT11-CA/KXJ11-CA 1/0 Using SLU2A or SLU2B with OMA
You can use the DMA controller to transfer data to or from either of the serial line ports SLU2
channel A and SLU2 channel B. User-supplied software must perform the necessary setup to
make this work, however, since the TT and XS drivers do not support this capability.

9-8 Peripheral Processor DMA Driver

9.3.6 $DMA_GET_STATUS
The $DMA_GET_STATUS function returns status information-the contents of device
registers-from the specified DTC channel into a user-supplied buffer. The function returns a
Boolean value indicating success (TRUE) or failure (FALSE).
The syntax for calling the function is as follows:
$DMA_GET_STATUS (unit, regbuf, regbuf_size, reply)

Parameter

Type

unit

DMA$UNIT_NUMBER

Description

Optional unit number; default is 0 (channel
A)

VAR regbuf

DMA$DEVICE_REGS

Buffer to which status information is to be
returned

regbuLsize

INTEGER

Optional buffer size in bytes; default is
DMA$REGBUF_SIZE (92)

DMA$SEM_POINTER

Optional pointer to an initialized reply
queue semaphore descriptor; default is NIL

The data types DMA$SEM_POINTER and DMA$DEVICE_REGS, from QDINC.PAS, are shown
below.
Note
The DMA$DEVICE_REGS data structure is diagrammed in Section 9.4.3.
TYPE
DMA$SEM_POINTER = - SEMAPHORE_DESC;
DMA$DEVICE_REGS = PACKED RECORD
caoff _b_1
unsigned;
caoff_b_O
unsigned;
baoff _b_1
unsigned;
baoff_b_O
unsigned;
caoff_a_1
unsigned;
caoff_a_O
unsigned;
baoff_a_1
unsigned;
baoff _a_O
unsigned;

{ pointer to sem desc }

{ Device registers }

Peripheral Processor DMA Driver 9-9

catag_b_1
unsigned;
catag_b_O
unsigned;
batag_b_1
unsigned;
batag_b_O
unsigned;
catag_a_1
unsigned;
catag_a_O unsigned;
batag_a_1
unsigned;
batag_a_O
unsigned;
chaino_1
unsigned;
chaino_O
unsigned;
chaint_1
unsigned;
chaint_O
unsigned;
isr_1 : unsigned;
isr_O : unsigned;
stat_1 : unsigned;
stat_O : unsigned;
coc_1
unsigned;
coc_O
unsigned;
boc_1
unsigned;
boc_O
unsigned;
mmr : unsigned;
junk : [WORD(7)] ;
pat_1
unsigned;
pat_O
unsigned;
msk_1
unsigned;
msk_O
unsigned;
cmr_l_1
unsigned;
cmr_l_O
unsigned;
cmr_h_1
unsigned;
cmr_h_O
unsigned;
inv_1
unsigned;
inv_O : unsigned;
END;
CONST
{ Constant for the size of the register file }
DMA$REGBUF_SIZE = 92;

If you specify the reply parameter, values for the device class and type are returned in a standard
driver reply message. (See Section 9.4.3.)
If you specify a register buffer size of less than 92, only the number of bytes you request will
be returned.

9-10 Peripheral Processor DMA Driver

9.3.7 $DMA_ALLOCATE
The $DMA_ALLOCATE function allocates a specified DTC channel for the exclusive use of
the calling process. This function returns a Boolean value indicating success (TRUE) or failure
(FALSE).
The syntax for calling the function is as follows:
$DMA_ALLOCATE ( unit )

Parameter

Type

Description

unit

DMA$UNIT_NUMBER

Optional unit number; default is 0 (channel A)

9.3.8 $DMA_DEALLOCATE
The $DMA_DEALLOCATE function reverses the effect of a previous DEALLOCATE > QD
driver) $DMA_ALLOCATE call. This function returns a Boolean value indicating success
(TRUE) or failure (FALSE).
The syntax for calling the function is as follows:
$DMA_DEALLOCATE ( unit )

Parameter

Type

Description

unit

DMA$UNIT_NUMBER

Optional unit number; default is 0 (channel A)

9.3.9 KXTl 1-CA/KXJl 1-CA OMA Sample Program
Figure 9-1 shows a sample program, usable with the distributed QD driver prefix file, that
demonstrates two operations:
•

DMA transfers from a local buffer to the Q-bus and then back to another local buffer

•

DMA search and transfer from one local buffer to another

Peripheral Processor DMA Driver 9-11

Figure 9-1 : KXT l 1-CA/KXJ 11-CA OMA Sample Program
[ SYSTEM(MICROPOWER), PRIORITY(50),
DATA_SPACE(2100), STACK_SIZE (400)] PROGRAM QDTST;
{need more stack
for $tran_virt_phys function
call in dma.pas}
{$NOLIST}
%include 'iopkts.pas'
%include 'escode.pas'
%include 'qdinc.pas'

{get common I/O definitions.}
{get exception codes}
{get the QD data structures
and interface}

{$LIST}
CONST
BUFSIZE = %0'2000'; {byte size}
QBUSBUF = DMA$ADDRESS ( %0'32000', %0'1', DMA$PHYSICAL, DMA$NOIO,
DMA$WAIT_O, DMA$UP, DMA$NOWFR, DMA$NOBYTE,
DMA$QBUS ); {address is 32000(8) in low 16
bits, 1 in high 6 bits = 232000(8)}
VAR
buf1, buf2 :
packed array[1 .. bufsize] of BYTE;
{2 buffers}
address_1, address_2 : DMA$ADDRESS;
{addresses for DMA calls}
i,k : INTEGER;
{loop counters}
error : INTEGER;
{error flag 0->success, 1-> failure}
un : DMA$UNIT_NUMBER; {unit or channel number for DMA device}
my_reply_semaphore : SEMAPHORE_DESC; {reply semaphore descriptor}
my_reply_packet : IO_REPLY;
{reply semaphore}
BEGIN
IF NOT CREATE_QUEUE_SEMAPHORE (DESC := my_reply_semaphore) THEN
WRITELN ('Semaphore create failed');
error := O;
un := O;

{clear error flag};
{use unit 0};

* For this test, transfer to and from qbus, checking data.

FOR i := 1 to BUFSIZE DO
{ fill buffer with data }
BEGIN
buf1[i] ·= i mod 256;
buf2[i] ·= O;
END;
address_1 := DMA$NORM_IBUS_ADDRESS;
address_1.low := (ADDRESS(BUF1)): :UNSIGNED;
address_2 := DMA$NORM_IBUS_ADDRESS;
address_2.low := (ADDRESS(BUF2)): :UNSIGNED;
{ transfer ... }
IF 0 = $DMA_TRANSFER (
{ on this unit }
UNIT := un,
SOURCE := address_1,
{ from my local buff er }
DEST := QBUSBUF, ,
{ to the qbus buff er }
{ this much }
COUNT := BUFSIZE )
THEN
WRITELN ('Test 1 failed on write');

9-12 Peripheral Processor DMA Driver

{ transfer. . . }
IF 0 = $DMA_TRANSFER
UNIT := un,
{ on this unit }
DEST := address_2,
{ to my local buff er }
SOURCE := QBUSBUF,
{ from the qbus buff er }
COUNT := BUFSIZE )
{ this much }
THEN
WRITELN ('Test 1 failed on read');
FOR i := 1 to BUFSIZE DO
BEGIN
IF ( buf1[i] <> buf2[i] ) THEN
error := 1;
END;

{ check the data for errors }

IF ERROR=1 THEN WRITELN ('Test 1 data corrupted')
ELSE WRITELN ('Test 1 passed');
error
o·'
un := 1;

{clear error flag for next test}
{use unit 1};

* For the next test, transfer ibus to ibus, searching.

FOR i := 1 to BUFSIZE DO
buf2[i] := O;

{ clear buf 2 }

address_! := DMA$NORM_IBUS_ADDRESS;
address_1.low := (ADDRESS(BUF1)): :UNSIGNED;
address_2 := DMA$NORM_IBUS_ADDRESS;
address_2.low := (ADDRESS(BUF2)): :UNSIGNED;
k := $DMA_SEARCH_TRANSFER
{ transfer ... }
UNIT := un,
{ on this unit }
SOURCE := address_!,
{ from my local buffer }
DEST := address_2,
{ to my second buffer }
VAL := 49,
{ looking for a 49 }
MASK:= %0'177400',
{in the low byte}
COUNT := bufsize,
{ this much }
REPLY :=address (my_reply_semaphore) ); {reply semaphore}
{WAIT FOR TRANSFER TO COMPLETE - Could do some work here first}
RECEIVE (DESC := my_reply_semaphore,
VAL_DATA := my_reply_packet,
VAL_LENGTH :=SIZE (my_reply_packet) );
IF my_reply_packet.status <> es$nor THEN
WRITELN ('Test 2 failed')
ELSE
BEGIN
{49th byte should match. Since in word moae,
byte count should be 50, for full word}
IF (my_reply_packet.actual_length <> 50) THEN
WRITELN ('Test 2 matched on wrong byte');
FOR i := 1 TO my_reply_packet.actual_length DO
IF ( buf1[i] <> buf2[i] ) THEN
error := 1;
IF error = 1 THEN
WRITELN ('Test 2 data corrupted');
IF ((my_reply_packet.actual_length=50) AND (error = 0)) THEN
WRITELN ('Test 2 passed');
END;
END.

Peripheral Processor DMA Driver 9-13

9.4 Request/Reply Packet Interface
The packet-level functions provided by the KXTll-CA/KXJll-CA DMA driver are listed below
by symbolic and decimal function cotle:
Code

Function

IF$RDP (0)

Read Physical

IF$WTP (3)

Write Physical

IF$GET (7)

Get Characteristics

IF$ALL (8)
IF$DEA (9)

Allocate Channel
Deallocate Channel

If a request is received for an Open (IF$LOK or IF$ENT), the driver returns an unsupported

function code (ES$UFN). That causes the OTS to raise the exception, provided that the OTS/ACP
issued the open request and the user's OPEN statement did not specify a status return.
Note
The MACR0-11 symbols used in this section are defined by the DRVDF$ macro,
which resides in the COMU and COMM kernel macro libraries. The equivalent
Pascal symbols are defined in the IOPKTS.P AS include file.
The function modifiers recognized by the QD driver are shown below by symbolic code and bit
position:
Code

Function

FM$TTO (null)

Transfer data to/from DMA address without searching the data (default
for QD read or write)

FM$TSO (bit 6)

Search data beginning at DMA address until either a search value is
matched or a byte count (DP.SLN) expires; return count of bytes searched
in actual-length field or reply packet (QD read or write)

FM$TTS (bit 7)

Transfer and search data until either a search value is matched or a byte
count (DP.LEN) expires; return count of bytes transferred in actual-length
field of reply packet (QD read or write)

FM$BSM (bit 13)

Signal binary/ counting semaphore

The QD driver consists of an initialization process, which lowers its priority to become the DMA
controller's request handler process.
Note
The QD driver supports multiple controllers, but normally just one controller is
configured. See Section 9.6.
I/O requests are sent (using a Pascal SEND or a MACR0-11 SEND$) to the request queue
semaphore waited on by the QD driver process.

9-14 Peripheral Processor DMA Driver

The request queue names and number of supported units for QD driver requests are shown
below:

Driver
KXTll-CA or
KXJll-CA DMA

Request
Queue Name

Number
of Units

$QDc

1-2

Numbering
0 and 1 for channels A and
B

The letter c in a queue name represents a controller designation (normally A, as specified in the
QD driver prefix file). The number of units configured for the controller and their unit numbers
must be specified in the driver prefix file.
The general format of QD request and reply packets is shown below:

+-----------------+
Standard
1-- packet --1
1-- header --1
-----------------,
DP.FUN Function
-----------------,
DP.UNI Unit
-----------------1
DP.SEQ Sequence number
----------------DP.PDB Requesting

QD
REQUEST
PACKET

+-----------------+
Standard

I
I
I

packet

I
I

I
I
I

header

I
I
I

process

Funeindep
value
data

identifier

----------------DP.SEM Reply
·-- semaphore
·-- identifier
,----------------DP.DAD I

I
I
I

1--

DP.SRD -

Request

DP.SLN

DP.PAR -

v
I
I

Funedep
value
data

address

----------------Buffer length
DP.LEN +-----------------+

usage

----------------Reply data
- DP.FDD
----------------Not
used

data

----------------DP.BUF Buffer

-----------------,
Function
- DP.FUN
-----------------1
Unit
- DP.UNI
----------------Sequence number
- DP.SEQ
----------------Status code
- DP.STS
----------------Actual length
- DP.ALN
----------------Error info
- DP.ERR
----------------Reserved for
- DP.XTR
driver

I
I
I

I
I
I
I
I
I

l
I
I

I
I

QD
REPLY
PACKET

v
Ref
data
info
v

----------------Reserved

+-----------------+ ML0-896-87

Peripheral Processor DMA Driver 9-15

The function-independent portions of the packets shown above are described in the request/reply
packet interface section of Chapter 1. The valid function and function-modifier codes for the
function (DP.FUN) field and the valid unit numbers for the unit (DP.UNI) field are listed at the
beginning of this section.
The function-dependent portions of the request and reply packets are described in the sections
that follow for each type of QD driver function.
Note
The MACR0-11 field names do not represent offsets into the user's send or
reply buffers; they are offset symbols used by MACR0-11 drivers to reference
packets. For example, DP .FUN is a 6-byte offset from the packet header.

9.4. l Read and Write Functions
The QD driver transfers data between any two of the following:
•

A local address

•

A Q-bus address

•

An I/O device on the arbiter processor's Q-bus

•

An I/O device connected directly to the KXTll-CA or KXJll-CA (for example, the PIO
chip port A via DMA channel 1)

Depending on the function-modifier bit settings, read and write operations can transfer data
(FM$TSO and FM$TTS clear), search data for a user-specified value (FM$TSO set), or transfer
data while searching (FM$TTS set). Read operations transfer data from the address specified in
the record at I?P.DAD in the request packet to the address specified in the record at DP.BUF.
The address in the record at DP.DAD must contain a physical address, and the record must
be equivalent to the Pascal record of type DMA$ADDRESS. This record is described in more
detail below. The address in the record at DP.BUF may contain either a virtual address or a
physical address. If a virtual user buffer address is specified, all addressing control bits must be
defaulted (=O), and you must send the buffer address to the driver by reference, the standard
technique for sending packets to drivers.
If a physical address is specified, you must fill in the address record beginning at DP.BUF and
the length at DP.LEN as part of the request packet and send the entire packet by value only
(with a value length six bytes larger to include the address record and the length field). The
address record must be equivalent to the Pascal record of type DMA$ADDRESS. The driver
checks the request packet and can tell by a bit setting in the packet header whether the buffer
was sent by reference or by value. That determines whether the address record at DP.BUF
contains a virtual or physical address. If the address in the record at DP .BUF is virtual, then
the driver uses the virtual address and the PAR value that follows it (at DP.PAR) to convert the
virtual address to a physical address. Write operations transfer data from the· address specified
in the record at DP.BUF in the request packet to the address specified in the record at DP.DAD.
The rules about the address records are the same as they are for read operations.

9-16 Peripheral Processor DMA Driver

Search operations use the address specified in the record at DP.DAD as the starting point for
the search. The address in the record at DP.DAD must contain a physical address, and the
record must be equivalent to the Pascal record of type DMA$ADDRESS. The byte count should
be filled in at offset DP.SLN, immediately following the address record. For search operations,
the DP.BUF field is ignored, so the request packet may be sent to the driver by value only and
need not include this field.
Since the packet format is rather complex, it is recommended that you use the Pascal interface
routines whenever possible.
The method of accessing the address specified in a read or a write request is modified by the
addressing control bits in the address record. Those addressing control bits are described below.
The function-dependent portions of the QD read or write request and reply packets differ for
each of the three selectable operations (transfer, search, and transfer and search), as shown
below:

Peripheral Processor DMA Driver 9-17

DP.BUF buffer
sent E,z---rererence
I
I
I

I
I

,-----------------,
DMA
i

,-----------------,

DP. DAD - I

i-i

physical
address

--i
i

,-----------------,
I

R
A

DP.SLN - :

DP.SRD - i

F
E
R

1--

Not used

I
I

Funcd ep
value
data

1-I
I

1----------------Buffer

DP.BUF - i
I

DP.PAR - l

I
I

:--

--:

I
I
I

,--

I
I
I

Not used

I
,-I
I
I

address

.----------------DP.LEN - l Buffer length
I

+-----------------+

--1i
I
--1
I
I
I

,--

I
I

--1

I
I
I

I
I

1-----------------1

Ref
data
info
v

I
I
I

DP.DAD -

,----------------DMA

I
I
I

,-I
I
I

E
A
R

physical
address

,----------------Search length
,----------------DP.SRO Search pattern
:----------------Search mask
,----------------DP.BUF DP.SLN -

I
I
I

DP.PAR DP.LEN -

F
E
R
&

E
A
R

Not used

I
I

I
I
I

R
A
N

I
I

Funedep
value
data

DP.DAD -

,-,-I
I
I

Not used

I
I

+-----------------+

physical
address

----------------Not used
----------------DP.SRO Search pattern
----------------Search mask
----------------DP.BUF Buffer
DP.LEN -

Ref
data
info
v

----------------DMA

DP.SLN -

DP.PAR -

address

----------------Buffer length
+-----------------+

9-18 Peripheral Processor DMA Driver

I
I

Funedep
value
data

Not used

I
I
I
I

v
Ref
data
info
v
ML0-897-87

When both addresses are physical

I
I
I

DP.DAD

DMA
- 1----------------physical

-----------------

I
I
I

I
I

address

R
A
N

F
E
R

Funedep
value
data

----------------DP.SLN DP.SRD Not used

I
I

DMA
- ----------------physical
DP .PAR address
----------------DP.LEN Buffer length
+-----------------+

E
A
R

I
I
I

I
I

-----------------

DMA
- ----------------physical

I
I

address

1-1-----------------

DP.BUF

DP.DAD

Not used

----------------Search length
DP.SLN ----------------Search pattern
DP.SRO ----------------Search mask
1----------------DP.BUF 1-- Not used
DP.PAR --1
1-DP.LEN +-----------------+

Funedep
value
data

Not used

I
I
I
I

-----------------

I
I
I

R
A
N

F
E
R
&

E
A
R

I
I
I

I
I

I
I
I

1-----------------1
DMA
physical --1
1-- address
1-----------------1
Not used
DP.SLN -----------------1
Search pattern
DP.SRO -----------------1
Search mask
-----------------1
DMA
DP.BUF physical --1
address
DP.PAR -----------------1
Buffer length
DP.LEN +-----------------+
DP.DAD -

I
I
I

1----------------I
I

Funedep
value
data

Not used

I
I
I
I
I
I

1----------------I
I
I

I
I
I
I
I
I
I
I

v
ML0-898-87

Peripheral Processor DMA Driver 9-19

The DMA address record is a 2-word record that includes a 22-bit address and addressing
control bits. The address can be a local memory address, a local or Q-bus I/O page address, or
a Q-bus address. Local addresses can be virtual or physical, Q-bus addresses must be physical.
The format of the DMA address record (offset DP.DAD, and possibly offset DP.BUF), which is
equivalent to the Pascal record type DMA$ADDRESS, is shown below:
15 14 13 12 11

+-----------------------------------------------+
I
Low address
I
+-----------------------------------------------+
I l I I
I
I I I I High address
I
+-----------------------------------------------+
~

I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I

I
I
I
I
I
I
I
I
I
I
I
I
I
I

Address-type option

+------ I/O option
+----------- Wait option
+----------------- Incrementation option
+--------------------- Request option
+------------------------ Byte-mode option
+--------------------------- Q-bus option
ML0-899-87

Note
The MACR0-11 symbols for the address-modifier field settings described below
(AM$xxx) are defined by the QDDF$ macro, which resides in the COMU kernel
macro library. Their Pascal equivalents, defined in QDINC.PAS, are shown in
Section 9.3.1.
Proceeding from right to left in the format above:
•

Address-type field, if set, means the address is physical; if clear, the address is virtual. This
field is used only by the Pascal interface routines and is ignored by the QD driver. Default:
Virtual.

•

The IJO-option field, if set to AM$TIO (1), causes the DMA address to reference the I/O
page rather than normal memory locations. Default: Not IJO page.

•

The wait-option field specifies the number of wait states to be programmed into DMAaddress access-zero or no wait states (AM$WSO) is the only value supported. Default:
No wait states.

•

The incrementation-option field causes the DMA address to be incremented (AM$TIA),
decremented (AM$TDA), or held constant (AM$THA) during a transfer; this option can
be specified independently on either address for transfer operations. Default: Increment
address.

•

The request-option field, if set to AM$WFR (1), causes the driver to wait for a hardware
request (request line active) for a transfer to or from the DMA address; this is used to
coordinate the DTC and the KXTl 1-CA/KXJll-CA PIO port controller for DMA transfer
via a PIO port (see Section 9.4.2). Since this option applies to the transfer in general and

9-20 Peripheral Processor DMA Driver

not to just one address, it may be specified in either address record for transfer operations.
Default: No wait for request.
•

The byte-mode-option field, if set to AM$BMO (1), causes the data to be transferred in
byte mode rather than word mode; byte mode is supported only for I/Oto a local (internal
bus) byte-oriented device-for example, a parallel port or an asynchronous line-with the
other address even. (Section 9.4.2 describes OMA transfer via a parallel port.) Byte-to-word
and word-to-byte funneling are not supported. Since this option applies to the transfer in
general and not to just one address, it may be specified in either address record for transfer
operations. Default: Word mode.

•

The Q-bus-option field, if set to AM$TQB (1), causes the OMA address to be mapped to
Q-bus space; otherwise, the internal bus is accessed. Byte mode cannot be selected when
this field is set. Default: Not Q-bus.

Bits 15, 12 and 11, 10 and 9, 8, and 6 apply only to this address. Bits 14 and 13 apply to
the operation in general and may therefore be specified in either address record for transfer
operations.
The search-length (offset DP.SLN) field specifies the maximum length, in bytes, of the search
to be performed for search-only operations.
If the FM$TSO function modifier is specified, bits set to 1 in the search-mask (offset DP.SRO)

field mask out bits in the object word. For example, to search only the low-order byte of each
word in a buffer, you should specify a search mask with all eight high-order bits set to 1. Thus,
the low-order byte of each word in the buffer will be compared with the low-order byte of the
search pattern (offset DP.SRD+2).
Note
To search for a byte in a buffer, you must perform two search operations. You
must first search the low-order byte of each word and mask out the high, then
search the high-order byte of each word and mask out the low. When the
high-order byte is being searched, the search pattern must be shifted to the
high-order byte.
The actual-length (offset DP.ALN) field of the read or write reply packet returns the count of
bytes transferred, unless function modifier FM$TSO was specified, in which case it returns the
count of bytes searched.

9.4.2 KXT11-CA/KXJ11-CA PIO OMA Process
If you want to perform DMA transfers via a KXTl 1-CA or KXJl 1-CA parallel port, you must

first set up and send a OMA Read or a OMA Write request packet to the YK driver and wait
for the reply. If the reply indicates normal status, you then send a OMA transfer command to
the DMA (QD) driver; otherwise, you report an error or wait. You must wait for each request
to complete, since only one PIO OMA operation ·can be in progress at a time. After the DMA
transfer completes, you send a OMA Complete request to the YK driver, which unlocks the
queue of requests for that port.
For guidelines to follow when performing DMA I/O on a KXTll-CA/KXJll-CA parallel
port-and a sample Pascal program-see Section 6.4.2.4.

Peripheral Processor DMA Driver 9-21

9.4.3 KXTl 1-CA/KXJl 1-CA 1/0 Using SLU2A or SLU2B with OMA
You can use the OMA controller to transfer data to or from e~ther of the serial line ports SLU2
channel A and SLU2 channel B. User-supplied software must perform the necessary setup to
make this work, however, since the TT and XS drivers do not support this capability.

9 .41 4 Get Characteristics Function
The Get Characteristics function returns device class and type to the reply packet and the
contents of a specified unit's device registers to a user-specified buffer.
The function-dependent portions of the Get Characteristics request and reply packets are shown
below:
I
I

I
I

1-----------------1
DP.DAD I

I
I
I

I
I

--1

Not used

I
I
I
--1
I

1----------------Type
Class
- DP.FDD
1-----------------

Funcdep
value
data

I
I

1-1
I
I
I
I

I
1--

DP.PAR - I

address

1----------------DP .LEN - I Buffer length
+-----------------+
I

Not

1-1

1----------------DP.BUF - I
Buffer

used

1-1
I

l-----------------

1
I

Ref
data
info
v
ML0-900-87

In the information above:
•

Class is DC$RLT for real-time device class.

•

Type is RT$QDK for KXTl 1-CA/KXJll-CA OMA channel.

•

Buffer address and buffer length specify the location and size of the device register buffer.

The QD driver can return up to 92 bytes-46 words-of status information. If you specify a
buffer length smaller than 92, the driver returns only the number of bytes you request. The
format of the status information that is returned is shown below. See the KXT11-CA Single-Board
Computer User's Guide or KX/11-CA Single-Board Computer User's Guide for detailed descriptions
of the listed registers and counts.
·

9-22 Peripheral Processor DMA Driver

,---------------------------------------:
Master mode register
- Offset +56.
,---------------------------------------:
Not used
,---------------------------------------I

Not used
Pattern register, ch. 1

- Offset +72.

Pattern register, ch. 0
Mask register, ch. 1
Mask register, ch. 0
Channel mode register, low, ch. 1
Channel mode register, low, ch. 0
Channel mode register, high, ch. 1
Channel mode register, high, ch. 0
Interrupt vector register, ch. 1
Interrupt vector register, ch. 0
- Offset +90.
+----------------------------------------+
ML0-902-87

Peripheral Processor DMA Driver 9-23

+----------------------------------------+
Current address reg, offset, B, ch. 1 I - Offset 0
----------------------------------------!
Current address reg, offset, B, ch. O I
----------------------------------------:
Base address reg, offset, B, ch. 1
I
----------------------------------------!
Base address reg, offset, B, ch. 0
I
----------------------------------------:
Current address reg, offset, A, ch. 1 I
----------------------------------------'
Current address reg, offset A, ch. O
1

Base address reg, offset, A, ch. 1
Base address reg, offset, A, ch. O
Current address reg, seg/tag, B, ch. 1

----------------------------------------·
Current address reg, seg/tag, B, ch. O I
----------------------------------------:
Base address reg, seg/tag, B, ch. 1
I
----------------------------------------:
Base address reg, seg/tag, B, ch. 0
I
----------------------------------------:
Current address reg, seg/tag, A, ch. 1 I
Current address reg, seg/tag, A, ch. 0
Base address reg, seg/tag, A, ch. 1
Base address reg, seg/tag, A, ch. 0
Chain load address reg, offset, ch. 1
Chain load address reg, offset, ch. 0
Chain load address reg, seg/tag, ch. 1
' Chain load address reg, seg/tag, ch. 0
Inte~rupt

save register, ch. 1

Interrupt save register, ch. 0
Command/Status register, ch. 1
Command/Status register, ch. 0
Current operation count, ch. 1
Current operation count, ch. 0

,---------------------------------------:
Base operation count, ch. 1
·---------------------------------------:
Base operation count, ch. 0
:---------------------------------------I

ML0-901-87

9.4.5 Channel Allocation and Deallocation
An Allocate Channel operation dedicates a channel of the DTC for the use of a single process.
The IF$ALL function directs the QD driver to reject any future requests that are issued by tasks
other than the one that issued the IF$ALL request.

9-24 Peripheral Processor DMA Driver

Deallocate Channel reverses the effect of the Allocate Channel request
For each request, you specify the DTC channel number (offset DP.UNI). The function-dependent
portions of the channel allocation and deallocation request and reply packets are not used.

9 .5 Status Codes
If the QD driver detects an error during an I/O operation, the driver returns an exception code
in the status-code (DP.STS) field of the reply message. If no error is detected during the IjO
operation, the driver returns a value of ES$NOR (0) in the status-code field.

The QD driver returns the following exception codes:

Code

Type

Description

ES$ABT

HARD_IO

I/O abort, driver process deleted, request not
serviced

ES$DAL

HARD_IO

Device (channel) already allocated

ES$IVM

HARD_IO

Invalid mode

ES$IVP

HARD_IO

Invalid parameter: odd address specified for wordmode operation, byte mode illegal for Q-bus
transfer

ES$NXM

HARD_IO

Nonexistent or read-only memory

ES$NXU

HARD_IO

Non existent unit

ES$IFN

SOFT_IO

Invalid function code

ES$TIM

HARD_IO

(KXJl 1-CA only). A SACK (Q-bus grant request)
timeout occurred. This may occur if there is
heavy DMA activity on the Q-bus. The actual
length byte count indicates the number of bytes
that were successfully transferred. Depending on
your application requirements, you may be able to
restart the transfer from where it left off, restart
the entire transfer, or report an error.

ES$UFN

SOFT_IO

Unsupported function, file open attempted

Exception codes are defined in the ESCODE.P AS include file (included by EXC.P AS) for Pascal
users and by the EXMSK$ macro in the COMU/COMM macro libraries for MACR0-11 users.
Note
Not listed above are exception codes for kernel-detected errors that the QD
driver raises rather than passing back to the requesting process.

Peripheral Processor DMA Driver 9-25

9.6 QD Driver Prefix File
Figure 9-2 shows the QD driver prefix module. The QD driver priorities, CSR, vector, and
number of units are standard for the KXTl 1-CA or KXJl 1-CA board. The QD prefix file, as
supplied, should be appropriate for all applications and not need modification.
Figure 9-2:

KXT 11-CA/KXJ 11-CA OTC Driver Prefix File (QDPFX.MAC)

.nlist
.enabl
.list
.title

QDPFX - KXT11--CA/KXJ11--CA DTC Device Driver Prefix Module

THIS SOFTWARE IS FURNISHED UNDER A LICENSE AND MAY BE USED OR COPIED
ONLY IN ACCORDANCE WITH THE TERMS OF SUCH LICENSE.
COPYRIGHT (c) 1982, 1986 BY DIGITAL EQUIPMENT CORPORATION.
ALL RIGHTS RESERVED .
. MCALL
.mcall
QD$PPR
QD$HPR
QD$IPR
drvcf$

DRVCF$
ctrcf$
175.
4

250.

Process priority
OTC hardware priority
Process initialization priority

dname=QD,nctrl=1

;Specify vector and base CSR for Unit 0. Unit 0 has a vector of 224 and a
;base csr of 174402. Unit 1 has a vector of 230 and a base csr of 174400.
ctrcf$

cname=A,nunits=2. ,csrvec=<174402,224>,units=<0:1>

.end

9-26 Peripheral Processor DMA Driver

Chapter l 0
Instrument Bus Driver
This chapter describes the use of the MicroPower/Pascal IEEE-488 instrument bus (XE) driver,
which supports I/O operations on the IEQll-A instrument bus interface. The IEQll-A is a
DMA controller that can interface a MicroPower/Pascal target processor to two independent
instrument buses. Each bus can have up to 15 devices (including the IEQll-A) in a sequential
configuration.

10. 1 Instrument Bus Features and Capabilities
The following summary of the features and capabilities of the IEEE-488 bus and the IEQllA interface is intended to serve as a basis for discussion of the XE driver's features and
capabilities. The mnemonics listed for the bus lines and the IEQl 1-A hardware registers are
referenced throughout the chapter.
The IEEE-488 bus is a General Purpose Interface Bus (GPIB). ANSI/IEEE Standard 488-1978,
"IEEE Standard Digital Interface for Programmable Instrumentation," specifies the characteristics
of the bus and the functions it must perform.
The bus consists of 24 lines. Of these, eight lines are ground wires, and 16 carry information. Of
the 16 information lines, three are used for handshaking control, and five for bus management;
eight carry data between devices on the bus.
You will generally not be concerned with the control lines (NRFD, DAV, and NDAC), since the
hardware takes care of the handshaking.

Instrument Bus Driver 10-1

The five bus management lines are:
Line

Mnemonic

Attention

ATN

Service request

SRQ

Interface clear

IFC

End or identify

EOI

Remote enable

REN

The eight data lines are used to transfer a byte of data at a time across the bus.
At any time, one and only one device on the bus will act as bus controller. The bus controller
issues the commands needed to perform all data transfers. Each device on the bus has the
potential to perform the following functions:
•

Act as bus controller

•

Act as "talker" in a bus transfer

•

Act as "listener" in a bus transfer

•

Issue a service request to the bus controller

•

Respond to polls by the bus controller

The IEQl 1-A provides two independent ports to the IEEE-488 bus. These ports can interface
to two different buses or provide two ports into the same bus. Note that the ports are treated as
separate controllers-not as two units ofan IEQll-A controller-for the purposes of configuring
MicroPower/Pascal applications.

10-2 Instrument Bus Driver

The functioning of these ports is controlled by the use of eight hardware registers for each port.
The registers are:
Register

Mnemonic

Address

IEEE Status
Read: Address Status/Bus Status
Write: Int Mask 0 /Int Mask 1

ISR

76XXXO

IEEE Interrupt
Read: Int Status 0 /Int Status 1
Write: -/Address

IIR

76XXX2

IEEE Command
Read: Cmd Pass Thru/Write: Serial Poll/ Auxiliary Cmd

ICR

76XXX4

IEEE Data
Read: - /Data In
Write: Parallel Poll/Data Out

IDR

76XXX6

Control/Status

CSR

76XX10

Bus Address

BAR

76XX12

Byte Count

BCR

76XX14

Match Character

MCR

76XX16

The corresponding registers for the two ports have identical addresses. The setting of a
multiplexer bit in the CSR-based on a user-specified controller ID or unit number-determines
which port's register is referenced. Aside from register sharing, however, the two instrument
bus ports are functionally independent.
As indicated by the Read and Write designations above, the four "IEEE" register addresses
reference different registers, depending on whether a reference is a read or a write.

10.2 Driver Features and Capabilities
The instrument bus (XE) driver provides the basic mechanisms for control of the instrument bus
interface. Among the operations supported are DMA data transfers, bus controller operations,.
service requests, serial polling, and parallel polling.
All IEQl 1-A data transfers are DMA. Before a transfer, the device that will send the data is
addressed as "talker," and any device to receive the data is addressed as "listener." (A read or
write consists of enabling the DMA transfer and dropping the ATN line.)

Instrument Bus Driver 10-3

10.3 Performing Instrument Bus 1/0
For most MicroPower/Pascal applications, you perform instrument bus I/O by invoking Pascal
support routines-WRITE _IEQ, IEQ _p ASS_CONTROL, .IEQ __REQ _SERVICE, IEQ _SERIAL,
and so forth. Those routines provide high-level nonfile access to the IEQll-A instrument bus
ports. The XE support routines issue Pascal send requests to the request queue semaphore of
the XE driver. The routines are described in Section 10.4.

Note
You cannot perform file-oriented Pascal operations on the instrument bus ports.
If you try to open an instrument bus file, the XE driver returns an unsupported
function (ES$UFN) exception code and the OTS raises the exception (unless you
requested a status return).
In addition to invoking the Pascal support routines, you must:
1.

Edit the DEVICES macro in the system configuration file to reflect the instrument bus port
interrupt vector addresses

Edit the XE driver prefix file to reflect:

•

Number of IEQll-A controllers (instrument bus ports)-up to two per IEQll-A

•

[For each port:] Controller identifier (A, B, ... ), CSR address, interrupt vector address,
and number of controller units (1)

•

Hardware interrupt priority

•

Driver initialization and request-handling process priorities

Build into your application the following I/O system components:
•

XE driver process

•

Pascal instrument bus support routines (from kit files XESUB.PAS and XEINC.P AS)

For more information on setting up your application software for instrument bus If O, see
Chapter 4 of the MicroPower/Pascal Run-Time Services Manual, Section 10.8 of this manual, and
the material on building system processes in the MicroPower/Pascal system user's guide for
your host system.
As an alternative to using the Pascal support routines for instrument bus I/O, you can issue
your own Pascal or MACR0-11 packet-level requests to the driver (low-level nonfile access).
The following sections describe the Pascal support routine interface to the XE driver, the lowerlevel request/reply packet interface, the status codes and extended error information that can
be returned to users of either interface, and the XE driver prefix file.

10-4 Instrument Bus Driver

10.4 Pascal Support Routine Interface
The following support routines, written in Pascal and independent of the file system, provide a
high-level interface to the IEQl 1-A instrument bus ports:
•

READ_IEQ procedure

•
•

WRITE _IEQ procedure

•

WRITE _.EQI_IEQ procedure

•
•
•
•
•

IEQ _COMMAND procedure

•
•
•
•

IEQ_AUX_COMMAND procedure

•
•

SET_STATE function

IEQ _SERIAL procedure
IEQ _PARALLEL _POLL procedure
IEQ _PARALLEL _LOAD procedure
IEQ _PARALLEL _CONFIG procedure

IEQ __REQ _SERVICE procedure
IEQ _CONTROL_GTS procedure
IEQ _p ASS-CONTROL procedure
SET_1NT_MASK procedure
REC_JEQ _EVENT procedure

The XE support routines allow you to use all the packet-level driver functions except the
following:
•

Get Characteristics (IF$GET)

•

Serial Poll Over All Devices (IF$SPO)

•

Get Control (IF$GTC)

•

Recognize Event (IF$RES)

To perform the functions not performed by support routines, either use the lower-level
request/reply interface directly or write Pascal procedures that take a user-specified queue
semaphore ID and send the appropriate request packet to the driver. For the Get Characteristics
(IF$GET) function, you can use the Get Characteristics function (descriptor version) in the
distribution kit file GETSET.PAS. That function issues a Get Characteristics (1F$GET) request
packet to the driver.
The following sections describe the Pascal routines for instrument bus 1/0. Each routine allocates
an 1/0 packet, fills it in with information based on the function parameters, sends it to the
XE driver queue semaphore for the specified port, and returns immediately to the caller. If the
routine has a reply parameter, the driver sends a standard driver reply via the specified queue
semaphore when the operation is complete. (The driver reply packets are described in Section
10.5.)

Instrument Bus Driver 10-5

The following files on the MicroPower/Pascal distribution kit are required for using the routines:

File

Description

XESUB.PAS

Instrument bus routine source module

XEINC.PAS

Instrument bus routine include file

IOPKTS.PAS

Pascal I/O include file

To use a source module, you must compile it and then merge it with the program at user-process
build time. The associated include files must be included in the program at compile time.

l 0.4. l READ_IEQ
The READ_IEQ procedure requests a read operation. The caller receives data in DMA mode
from the device addressed as "talker."
In order for a device to be able to receive data, it must be addressed as "listener." If the unit is
controller-in-charge but not a listener when a read request is issued, the driver addresses the
unit as listener. If addressed in this manner, the unit will automatically be deaddressed after
the request has completed.
There are three ways in which a read request may terminate:
•

Byte count overflow

•

EOI termination

•

Match character termination

10-6 Instrument Bus Driver

The syntax for calling the procedure is as follows:
READ_IEQ (unit, unit_desc, buffer, leng, mlength, chr, reply);

Parameter

Type

Description

unit

INTEGER

Unit number (valid range is 0 through n-1
for n configured IEQl 1-A ports)

VAR unit_desc

STRUCTURE_DESC

Initialized driver queue semaphore descriptor

VAR buffer

PACKED ARRAY
[first.last:
INTEGER] of CHAR

Data buffer

leng

INTEGER

Buffer length

mlength

INTEGER

Match length up to 63 (decimal); 0 disables
match character processing

chr

CHAR

Match character

VAR reply

STRUCTURE_DESC

Optional initialized reply queue semaphore
descriptor; if specified, it is the user's
responsibility to wait for the reply

The count of bytes transferred is returned in the actual-length field of the XE driver reply packet.

l 0.4.2 WRITE_IEQ
The WRITE_IEQ procedure requests a write operation without EOI termination.
operation transmits data in DMA mode to all devices addressed as "listener."

A write

In order for a device to be able to send data, it must be addressed as "talker." If the unit is
not addressed as talker when a write request is issued, the driver automatically addresses the
unit as talker, using the auxiliary command Talk Only (TON) and deaddresses the unit after
the request has completed.
The packet-level equivalent of WRITE_IEQ is the IF$WTL function.

Instrument Bus Driver 10-7

The syntax for calling the procedure is as follows:
WRITE_IEQ (unit, unit_desc, buffer, Ieng, reply);

Parameter

Type

Description

unit

INTEGER

Unit number (valid range is 0 through n-1
for n configured IEQll-A ports)

VAR unit_desc

STRUCTURE_DESC

Initialized driver queue semaphore descriptor

VAR buffer

PACKED ARRAY
[first..last:
INTEGER] of CHAR

Data buffer

Ieng

INTEGER

Buffer length

VAR reply

STRUCTURE_DESC

Optional initialized reply queue semaphore
descriptor; if specified, it is the user's
responsibility to wait for the reply

The count of bytes transferred is returned in the actual-length field of the XE driver reply packet.

10.4.3 SET_STATE
The SET_STATE function can be used to perform one or more of the following state alterations,
listed in the order they are performed:
•

Issue master clear

•

Set system controller bit in CSR

•

Clear system controller bit in CSR

•

Set primary address

•

Send software reset

•

Set controller to controller active state

Master clear resets the IEQll-A controller without affecting other devices in the system.
Setting the system controller bit makes the specified controller the system controller.
Setting the primary address loads a user-specified address into the IEEE command register (ICR).
Software reset resets all of the TMS 9914 registers.
SET_STATE always returns the BOOLEAN value TRUE.
The packet-level equivalent of SET_STATE is the IF$SET function.

10-8 Instrument Bus Driver

The syntax for calling the function is as follows:
SET_STATE ( comm, unit, unit_desc, address

Parameter

Type

Description

comm

INTEGER

Command mask

unit

INTEGER

Unit number (valid range is 0 through n-1
for n configured IEQll-A ports)

VAR unit_desc

STRUCTURE_DESC

Initialized driver queue semaphore descriptor

address

INTEGER

Primary address, supplied only for the set
primary address operation

The mask word has the following format:
15

+-----------------------------------------------+
+-----------------------------------------------+
I
I

I
I

+- Issue master clear

I
I

+---- Send software reset

+------- Set sys control bit

+---------- Clear sys control
+------------- Set controller active
+---------------- Set primary address
ML0-903-87

10.4.4 WRITE_EOLIEQ
The WRITE_EOLJEQ procedure requests a write operation with End or Identify (EOI)
termination. A write operation transmits data in DMA mode to all devices addressed as
"listener." The EOI line is reset after the last byte is transmitted.
In order for a device to be able to send data, it must be addressed as "talker." If the unit is
not addressed as talker when a write request is issued, the driver automatically addresses the
unit as talker, using the auxiliary command Talk Only (TON) and deaddresses the unit after
the request has completed.
The packet-level equivalent of WRITE_EOLJEQ is the IF$WLE function.

Instrument Bus Driver 10-9

The syntax for calling the procedure is as follows:
WRITE_EOI_IEQ (unit, unit_desc, buffer, leng, reply);

Parameter

Type

Description

unit

INTEGER

Unit number (valid range is 0 through n-1
for n configured IEQll-A ports)

VAR unit_desc

STRUCTURE_DESC

Initialized driver queue semaphore descriptor

VAR buffer

PACKED ARRAY
[first. .last:
INTEGER] of CHAR

Data buffer

Ieng

INTEGER

Buffer length

VAR reply

STRUCTURE_DESC

Optional initialized reply queue semaphore
descriptor; if specified, it is the user's
responsibility to wait for the reply

The count of bytes transferred is returned in the actual-length field of the XE driver reply packet.

10.4.5 IEQ_COMMAND
The IEQ _COMMAND procedure requests a Write IEEE Remote Messages operation, which
outputs a buffer of command bytes via the data output register. The commands are grouped as
follows:
Values

Command Group

0-17

Address

20-37

Universal

40-77

Listen Address

100-137

Talk Address

140-177

Secondary

The IEQ11-A User's Guide lists and describes the commands in each group.
A Write IEEE Remote Messages request can be issued only by the controller-in-charge. In order
to output data via the data output register, the unit must be in controller active state (CACS).
If the unit is not in CACS when the request is issued, the driver attempts to enter that state,
issuing an error if it fails.
The packet-level equivalent of IEQ _COMMAND is the IF$CMD function.

10-10 Instrument Bus Driver

The syntax for calling the procedure is as follows:
IEQ_COMMAND (unit, unit_desc, comm, reply);

Parameter

Type

Description

unit

INTEGER

Unit number (valid range is 0 through n-1
for n configured IEQll-A ports)

VAR unit_desc

STRUCTURE_DESC

Initialized driver queue semaphore descriptor

VAR comm

ARRAY[first.last:
INTEGER] of
BYTE_RANGE

Buffer of command bytes

VAR reply

STRUCTURE_DESC

Optional initialized reply queue semaphore
descriptor; if specified, it is the user's
responsibility to wait for the reply

l 0.4.6 IEQ_SERIAL
The IEQ_SERIAL procedure requests that a serial poll be performed while the service request
(SRQ) bit is set. A serial poll is used by the controller-in-charge to determine which devices
have issued a service request.
A serial poll operation begins with the deactivation of all listeners. Each device specified in the
user's buffer is then addressed as "talker" for the purpose of reading its status byte. If bit 7 of
a status byte is set, the currently addressed talker was requesting service. The status byte is
copied to the user's buffer. If the SRQ bit is still set, the next device is addressed and the poll
continues; otherwise, the poll terminates.
The packet-level equivalent of IEQ _SERIAL is the IF$SPS function.
The following data types from XEINC.P AS are referenced below:
TYPE
ieq_address = PACKED RECORD
prim_addr,
sec_addr : [BYTE] BYTE_RANGE;
END;
ser_poll_buf = PACKED RECORD
addr : ieq_address;
status : INTEGER;
END;

Instrument Bus Driver 10-11

The syntax for calling the procedure is as follows:
IEQ_SERIAL (unit, unit_desc, len, buff, reply);

Parameter

Type

Description

unit

INTEGER

Unit number (valid range is 0 through n-1
for n configured IEQl 1-A ports)

VAR unit_desc

STRUCTURE_DESC

Initialized driver queue semaphore descriptor

len

INTEGER

Buffer length (currently ignored by driver,
which performs its own buffer length calculation)

VAR buff

ARRAY[ first. .last:
INTEGER] of
ser-poll_buf

Buffer of device/status parameter pairs

VAR reply

STRUCTURE_DESC

Optional initialized reply queue semaphore
descriptor; if specified, it is the user's
responsibility to wait for the reply

The first word of each parameter pair in the buffer gives a talker address. Extended addressing
is not used; however, you can write your own variation of the procedure to use extended
addressing. (See the description of the IF$SPS function in Section 10.5.6.)
The talker's status byte is returned to the second word of each pair.

10.4.7 IEQ_PARALLEL_POLL
The IEQ _PARALLEL _POLL procedure requests a parallel poll operation, used by the controllerin-charge to poll up to eight devices on the IEEE bus. The driver loops for 100 microseconds
to wait for the parallel poll to complete. The result of a parallel poll is a status byte that is
returned in an XE driver reply message-specifically, the low-order byte of the first word of the
function-dependent reply data. The byte contains a bit for each of eight devices selected via
the IEQ _p ARALLEL _CQNFIG procedure.
The packet-level equivalent of IEQ _PARALLEL _POLL is the IF$PPO function.

10-12 Instrument Bus Driver

The syntax for calling the procedure is as follows:
IEQ_PARALLEL_POLL (unit, unit_desc, reply);

Parameter

Type

Description

unit

INTEGER

Unit number (valid range is 0 through n-1
for n configured IEQl 1-A ports)

VAR unit_desc

STRUCTURE_DESC

Initialized driver queue semaphore descriptor

VAR reply

STRUCTURE_DESC

Optional initialized reply queue semaphore
descriptor; if specified, it is the user's
responsibility to wait for the reply

l 0.4.8 IEQ_PARALLELLOAD
The IEQ _PARALLEL _LOAD procedure requests that the parallel poll register be loaded with a
status byte. When a parallel poll is conducted, this information is transferred to the controllerin-charge. You should update this byte to reflect the state of the device.
The packet-level equivalent of IEQ_PARALLEL_LOAD is the IF$LPP function.
The syntax for calling the procedure is as follows:
IEQ_PARALLEL_LOAD (unit, unit_desc, stat);

Parameter

Type

Description

unit

INTEGER

Unit number (valid range is 0 through n-1
for n configured IEQl 1-A ports)

VAR unit_desc

STRUCTURE_DESC

Initialized driver queue semaphore descriptor

stat

INTEGER

Status byte to be placed in parallel poll
register

The format of the status byte is determined by an IEQ _p ARALLEL _CONFIG operation.

l 0.4.9 IEQ_PARALLEL_CONFIG
The IEQ _PARALLEL _CONFIG procedure requests a Parallel Poll Configure operation, used
by the controller-in-charge to configure other devices on the IEEE bus for a parallel poll. It
instructs those devices on how to respond to a parallel poll.
The packet-level equivalent of IEQ _p ARALLEL _CONFIG is the IF$PPC function.
The following data type from XEINC.P AS is referenced below:
TYPE
pp_buff er = packed record
l_addrs : [byte] byte_range;
cfg_byte : [byte] byte_range;
end;

Instrument Bus Driver 10-13

The syntax for calling the procedure is as follows:
IEQ_PARALLEL_CONFIG (unit, unit_desc, buff, reply);

Parameter

Type

Description

unit

INTEGER

Unit number (valid range is 0 through n-1
for n configured IEQ 11-A ports)

VAR unit_desc

STRUCTURE_DESC

Initialized driver queue semaphore descriptor

buff

ARRAY[first..last:
INTEGER] of
pp-buffer

Buffer of up to eight listener address/
configuration-byte parameter pairs

VAR reply

STRUCTURE_DESC

Optional initialized reply queue semaphore
descriptor; if specified, it is the user's
responsibility to wait for the reply

Each parameter pair in the buffer gives a listener address in the range 40 to 76 (octal) and a
configuration byte with a value in the range 0 to 7. The listener address selects a device and
the configuration byte value determines which bit in the parallel poll register the device will
update to reflect its state. The state of that bit is returned fo the controller-in-charge when a
parallel poll occurs.

10.4.10 IEQ_AUX_COMMAND
The IEQ-AUX_COMMAND procedure requests that an auxiliary command be issued by writing
a byte to the auxiliary command register. Auxiliary commands are used to enable and disable
most of the selectable features of IEQl 1-A registers.
The packet-level equivalent of IEQ-AUX_COMMAND is the IF$AUX function.
The syntax for calling the procedure is as follows:
IEQ_AUX_COMMAND (unit, unit_desc, aux_comm, reply);

Parameter

Type

Description

unit

INTEGER

Unit number (valid range is 0 through n-1
for n configured IEQll-A ports)

VAR unit_desc

STRUCTURE_DESC

Initialized driver queue semaphore descriptor

aux_comm

INTEGER

Auxiliary command

VAR reply

STRUCTURE_DESC

Optional initialized reply queue semaphore
descriptor; if specified, it is the user's
responsibility to wait for the reply

10-14 Instrument Bus Driver

The auxiliary commands are described in detail in the IEQ11-A User's Guide. Their values are
shown below:

Value

Command

Software reset

Release ACDS holdoff

Release RFD holdoff

Holdoff all data

Set new byte available false (bit 7 not applicable)

Assert force end or identify (FEOI) on next byte

Listen only

10.

Talk only

11.

Go to standby

12.

Take control asynchronously

13.

Take control synchronously

14.

Request parallel poll

15.

Send interface clear

16.

Send remote enable

17.

Request control

18.

Release control

20.

Pass through next secondary

24.

Service request bit 2

Bit 7

Clear/set bit (required for clear/set type of features)

l 0.4. 11 IEQ_REQ_SERVICE
The IEQ_REQ_SERVICE procedure performs a Request Service operation, which generates a
service request to the controller-in-charge and places a user-provided status byte in the serial
poll register. The controller-in-charge detects that the SRQ line has asserted and performs
a serial poll to determine which device requested service. When the requesting device is
addressed in a serial poll, the controller-in-charge reads the status byte from the serial poll
register. The meaning of the status byte is application dependent, but it should indicate to the
controller-in-charge the type of servicing required.

Note
Bit 6 of the status byte is used to set the SRQ line and is not available to the
user's program.
The packet-level equivalent of IEQ_REQ_SERVICE is the IF$RSV function .

. Instrument Bus Driver

10-15

The syntax for calling the procedure is as follows:
IEQ_REQ_SERVICE (unit, unit_desc, stat);

Parameter

Type

Description

unit

INTEGER

Unit number (valid range is 0 through n-1
for n configured IEQll-A ports)

VAR unit_desc

STRUCTURE_DESC

Initialized driver queue semaphore descriptor

stat

INTEGER

Status byte

10.4. 12 IEQ_CONTROL_GTS
The IEQ _CONTROL _GTS procedure requests a Go to Standby operation, used by the
controller-in-charge to go from controller active state (CACS) to controller standby state (CSBS).
If the unit is already in CSBS when the request is issued, no action is taken. A state error is
generated if the unit is not controller-in-charge.
Since the driver automatically goes to the state required to process a request, this procedure is
not normally needed.
The packet-level equivalent of IEQ_CQNTRQL_GTS'is the IF$GTS function.
The syntax for calling the procedure is as follows:
IEQ_CONTROL_GTS (unit, unit_desc, reply);

Parameter

Type

Description

unit

INTEGER

Unit number (valid range is 0 through n-1
for n configured IEQl 1-A ports)

VAR unit_desc

STRUCTURE_DESC

Initialized driver queue semaphore descriptor

VAR reply

STRUCTURE_DESC

Optional initialized reply queue semaphore
descriptor; if specified, it is the user's
responsibility to wait for the reply

10-16 Instrument Bus Driver

10.4.13 IEQ_PASS_CONTROL
The IEQ _p ASS-CONTROL procedure passes control to a user-specified device, which takes
control in controller active state. The device is addressed to receive control as "talker," a
handshake is completed, and control is passed (by releasing the ATN line).
The packet-level equivalent of IEQ_PASS_CONTROL is the IF$PCT function.
The syntax for calling the procedure is as follows:
IEQ_PASS_CONTROL (unit, unit_desc, t_addr, reply);

Parameter

Type

Description

unit

INTEGER

Unit number (valid range is 0 through n-1
for n configured IEQll-A ports)

VAR uniLdesc

STRUCTURE_DESC

Initialized driver queue semaphore descriptor

Laddr

INTEGER

Talker address in the range 100 to 136 (octal)

VAR reply

STRUCTURE_DESC

Optional initialized reply queue semaphore
descriptor; if specified, it is the user's
responsibility to wait for the reply

10.4. 14 SET_INT_MASK
The SET_JNT__MASK procedure sets up event recognition by specifying events for which
recognition is requested. Those events are subsequently detected and reported to the user. (See
the REC_JEQ_EVENT procedure.) The events are specified in a bit mask. If a bit is set in the
mask, recognition of the corresponding event is requested.
Normally, the controller-in-charge requests recognition of a service request, and devices that are
not controller-in-charge request recognition of all the other events.
Event recognition remains enabled until the procedure is called with an argument of 0.
The packet-level equivalent of SELJNT_MASK is the IF$SEM function.
The syntax for calling the procedure is as follows:
SET_INT_MASK (unit, unit_desc, mask);

Parameter

Type

Description

unit

INTEGER

Unit number (valid range is 0 through n-1
for n configured IEQll-A ports)

VAR unit_desc

STRUCTURE_DESC

Initialized driver queue semaphore descriptor

mask

INTEGER

Event mask

Instrument Bus Driver 10-17

The event mask has the following format:
12 11 10

+-----------------------------------------------+
I
I

I
I

I
.1

I
I

+----------------------------------------~-~~---+
r
A

, I
I
I
I
I
I
I

I
I

+- Service request

+---- Addr'd as listener
+------- Addr'd as talker
+---------- Deaddressed
+------------- Addr'd ext'd listener
+---------------- Addr'd ext'd talker
+------------------- Device clear
+---------------------- Device trigger
+------------------------- Remote/local change
+---------------------------- Received control
+------------------------------- Parallel poll config
I

I
I

+--------------~------------------- Parallel poll unconf
+----~-------------------------------- Interface clear
ML0-904-87

If recognition of an event represented by bits 1-9 is requested and the event occurs, the

IEEE-488 is locked until released by the program. The bus can be released only by an
IEQ_AUX_COMMAND call that releases ACDS holdoff (aux_comm = 1) or when a new
request is issued to the controller, in which case the driver automatically releases the bus.

10.4. 15 REC_IEQ_EVENl
The REC_IEQ_EVENT procedure returns notification of an event to the user. Event recognition
must previously have been enabled with a SET_INT_MASK call. If the event has already
occurred, the request is returned immediately with notification. Otherwise, the request waits
until the event occurs.
The packet-level equivalent of REC_IEQ-EVENT is the IF$REV function.
The syntax for calling the procedure is as follows:
REC_IEQ_EVENT (unit, unit_desc, reply);

10-18 Instrument Bus Driver

Parameter

Type

Description

unit

INTEGER

Unit number (valid range is 0 through n-1
for n configured IEQ 11-A ports)

VAR unit_desc

STRUCTURE_DESC

Initialized driver queue semaphore descriptor

VAR reply

STRUCTURE_DESC

Optional initialized reply queue semaphore
descriptor; if specified, it is the user's
responsibility to wait for the reply

The event notification takes the form of a status block that is returned in the XE driver reply
packet (first two words of the function-dependent portion-see Section 10.5.16). The return
status block has the following format:

+-----------------+
IEv Info I Status I
l--------+--------1
IUnit No.I Ev Codel
+-----------------+
ML0-905-87
The status code field has the value ES$NOR (0).
The event code indicates the event that has occurred as follows:

Value

Event

Service request

Addressed as listener

Addressed as talker

De addressed

Addressed as extended listener

Addressed as extended talker

Device clear

Device trigger

Remote /local change

10.

Received control

11.

Parallel poll configure

12.

Parallel poll unconfigure

13.

Interface clear

The event information byte contains the following event-dependent data:
•

If extended listener or talker, the extended address

Instrument Bus Driver 10-19

•

If a remote /local change occurred, 0 if the unit is in local mode, or 1 if the unit is in remote

mode
•

If a Parallel Poll Configure occurred, the PPE or PPD byte

•

For all other events, 0

l 0.5 Request/Reply Packet Interface
The packet-level functions provided by the XE driver are listed below by symbolic and decimal
function code:
Code

Function

IF$RDL (1)

Read Logical

IF$WTL (4)

Write Logical

IF$SET (6)
IF$GET (7)

Set Characteristics (Set State)
Get Characteristics (Sense State)

IF$WLE (24)
IF$CMD (25)

Write with EOI Termination
Write IEEE Remote Messages

IF$SPS (26)
IF$SPO (27)

Serial Poll While SRQ is Set
Serial Poll Over All Devices

IF$PPO (28)
IF$LPP (29)
IF$PPC (30)

Parallel Poll
Load Parallel Poll Register
Parallel Poll Configure

IF$AUX (31)
IF$RSV (32)

Auxiliary Command
Request Service

IF$GTC (34)
IF$GTS (35)
IF$PCT (36)

Get Control
Go to Standby
Pass Control

IF$SEM (37)
IF$REV (38)
IF$RES (39)

Set Event Mask
Wait for Event
Recognize Event

If a request is received for an Open (IF$LOK or IF$ENT), the driver returns an unsupported

function status code (ES$UFN). This will cause the Pascal OTS to raise an exception, provided
that the OTS / ACP issued the Open request and the user's OPEN statement did not specify a
status return.
Note
The MACR0-11 symbols used in this section are defined by the DRVDF$ macro,
which resides in the COMU and COMM kernel macro libraries. The equivalent
Pascal symbols are defined in the include files IOPKTS.P AS and XEINC.PAS.

10-20 Instrument Bus Driver

The function modifiers recognized by the XE driver are shown below by symbolic code and bit
position:

Code

Function

FM$LIS (bit 12)

Leave in state (do not reset previous state) after data transfer

FM$SRQ (bit 13)

Terminate data transfer on service request (SRQ)

FM$EAD (bit 13)

Use extended addressing in serial poll

FM$TCS (bit 14)

Take control synchronously (go to controller active state)

FM$BSM (bit 13)

Signal binary/ counting semaphore

The XE driver consists of an initialization process, which lowers its priority to become the
first controller's request handler process, plus an additional request handler process for each
controller configured. I/O requests intended for a particular controller (IEQl 1-A port) are sent
(using a Pascal SEND or a MACR0-11 SEND$) to the request queue semaphore waited on by
that controller's request handler process.
The request queue name and number of supported units for XE driver requests are shown
below:

Driver

Request
Queue Name

Number
of Units

Instrument bus

$XEc

l(per
controller)

Numbering
Sequentially upward from 0 in
prefix file order, crossing controller
and board boundaries

The letter c in a queue name represents a controller designation (A, B, ... , as specified in an XE
driver prefix file).

Instrument Bus Driver 10-21

The general format of the XE request and reply packets is shown below:
XE
REQUEST
PACKET

+-----------------+
Standard
I
I
I

1--

packet
header

--1
--1

I
I
I

packet

I
I
I
I
I

I
I

I
I
I

DP.PDE - -----------------1
Requesting

I
I
I

process

I
I
I
I
I
I
I
I
I
I

Funeindep
value
data

identifier

----------------DP.SEM Reply
semaphore
v

data

Funedep
value
data

Not used

I
I
I
I

--------------------------------Buffer
PP.BUF address
DP-. PAR ----------------Buff er length
DP.LEN +-----------------+

identifier

----------------DP.DAD Request

XE
REPLY
PACKET

header

---------~-------1I

Function
-----------------1
DP.UNI Unit
-----------------1
DP.SEQ Sequence number
DP.FUN

+-----------------+
Standard

I
I
I

I
I

Ref
data
info
v

usage

----------------Reply data
- DP.FDD
----------------Not
used

----------------Reserved

+-----------------+ ML0-906-87

10-22

Instrument Bus Driver

10.5. 1 Read Logical Function
The Read Logical (IF$RDL) function receives data from the device addressed as "talker." Note
that the IEQll-A interface is capable of receiving data in either processor or DMA mode.
However, the XE driver uses only the DMA mode. Status information may be exchanged
between devices by using polling requests, but the only method of receiving data is via reads.
In order for a device to be able to receive data, it must be addressed as "listener." If the unit is
controller-in-charge but not a listener when a read request is issued, the driver addresses the
unit as listener. If addressed in this manner, the unit will automatically be deaddressed after
the request has completed.
There are three ways in which a read request may terminate:
•

Byte count overflow

•

EOI termination

•

Match character termination

Match character detection allows you to stop a transfer upon detection of a given number of
consecutive end-of-string (EOS) characters. You specify the EOS character, which depends on
the device that is currently the talker.
A data transfer terminates and an error is returned if an Incomplete Handshake Error (ERR) or
Interface Clear Received (IFC) interrupt occurs.
If the function modifier FM$SRQ is set, a Service Request (SRQ) interrupt will terminate the

data transfer. The status code ES$STD and the extended error code IE.SRQ are returned in the
reply message.
The function-dependent portions of. the read request and reply packets are shown below:
I

I
I
I

I
I

-----------------.
DP.DAD Match character
----------------Match length
----------------I
I
I

Funedep
value
data

Not used

----------------DP.BUF Buffer
DP.PAR DP.LEN

address

Buffer length
- -----------------

+-----------------+

1----------------- - DP.FDD

I
I

1-1

I
I

.--

I
I
1--

Not used

1
I
I

1-1
I

1----------------I

1
I

Ref
data
info
v
ML0-907-87

The match-character (low-order byte) and match-length fields specify the match character and
the match-character count (up to 63 decimal) for match-character processing. A match length
of 0 disables the feature.

Instrument Bus Driver 10-23

10.5.2 Write and Write with EOI Termination Functions
The write functions (IF$WTL and IF$WTE) transmit data to all devices addressed as "listener."
Note that the IEQll-A interface is capable of transferring dat~ in either processor request or
DMA mode. However, the XE driver uses only the DMA mode. Status information may be
exchanged between devices by using the polling requests, but the only method of transmitting
data is via writes.
The IF$WLE request is identical to the IF$WTL request, except that it issues the auxiliary
command Force End or Identify (FEOI) before transmitting the last data byte. That causes the
EOI message to be sent with the last data byte. The EOI line is then reset.
In order for a device to be able to send data, it must be addressed as "talker." If the unit is
not addressed as talker when a write request is issued, the driver automatically addresses the
unit as talker, using the auxiliary command Talk Only (TON) and deaddresses the unit after
the request has completed.
A data transfer terminates and an error is returned if an Incomplete Handshake Error (ERR) or
Interface Clear Received (IFC) interrupt occurs.
If the function modifier FM$SRQ is set, a Service Request (SRQ) interrupt will terminate the
data transfer. The status code ES$STD and the extended error code IE.SRQ are returned in the
reply message.

The function-dependent portions of the write request and reply packets are shown below:

..
·----------------I
I

DP.DAD -

'
.-'1-,
I
I

Not used

·-'

Funcdep
value
data
I

I
I

1
I

Ref
data
info
v

1--

l----------------Buffer
DP.BUF - 1
DP.PAR -

l-----------------

I
I

1-1
I

address

l----------------DP.LEN - 1 Buffer length
+-----------------+

10-24 Instrument Bus Driver

1
I
I

- DP.FDD

1-1
I
I

1-1
I

Not used

1-1
I
I

1----------------1

ML0-908-87

10.5.3 Get Characteristics (Sense State) Function
The Get Characteristics (IF$GET) function returns the controller state and IEEE-status-register
contents in two status words.
The function-dependent portions of the Get Characteristics request and reply packets are shown
below:
I

·----------------'
.-.-I

DP.DAD -

I
I

1
I
I

Not
used

DP.BUF -

I Class

- DP.FDD

Controller state

Funcdep
value
data
I
I
I
I

IEEE status reg
Not
1-1
I
I

used

·----------------'
I

Ref
data
info

DP.PAR DP.LEN -

Type
I
I

+-----------------+

v
ML0-909-87

The possible controller-state values in the high-order byte of the first status word are shown
below:

Value

State

Controller idle

Controller active

Controller standby

The contents of the IEEE status register (read-only) are diagrammed and described in the
IEQ11-A User's Guide.

10.5.4 Set Characteristics (Set State) Function
The Set Characteristics (IF$SET) function can be used to perform one or more of the following
state alterations, listed in the order they are performed:
•

Issue master clear

•

Set system controller bit in CSR

•

Clear system controller bit in CSR

•

Set primary address

•

Send software reset

•

Set controller to controller-active state

Master clear resets the IEQll-A controller without affecting other devices in the system.

Instrument Bus Driver 10-25

Setting the system controller bit makes the specified controller the system controller.
Setting the primary address loads a user-specified address into the IEEE command register (ICR).
Software reset resets all of the TMS 9914 registers.
The function-dependent portions of the Set Characteristics request and reply packets are shown
below:
I
I
I

1-----------------1 - DP.FOO
I

DP.DAD -

Mask

I
I

--1

Primary address

Not

--1
I

Not used

I
I

--1

I
I
I
-- I
I
I
I

-----------------1
I
I

used

DP.BUF -

Ref
data
info

DP.PAR I

DP.LEN -

Funcde p
value
data

1-1
I

+-----------------+

ML0-910-87

The primary address is supplied for the set primary address operation only.
The mask word has the following format:
15

+-----------------------------------------------+
+-----------------------------------------------+
+- Issue master clear
+---- Send software reset
+------- Set sys control bit
+---------- Clear sys control
+------------- Set controller active
+---------------- Set primary address
I
I

I
I

I
.I

I
I

I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I

I
I
I
I
I
I
I
I
I
I
I
I
I
I

I
I
I
I
I
I
I
I
I
I

I
I

ML0-911-87

10-26 Instrument Bus Driver

l 0.5.5 Write IEEE Remote Messages Function
The Write IEEE Remote Messages (IF$CMD) function outputs a buffer of command bytes via
the data output register. The commands are grouped as follows:

Values

Command Group

0-17

Address

20-37

Universal

40-77

Listen Address

100-137

Talk Address

140-177

Secondary

The IEQ11-A User's Guide lists and describes the commands in each group.
The IF$CMD request can be issued only by the controller-in-charge. In order to output data via
the data output register, the unit must be in controller active state (CACS). If the unit is not in
CACS when the request is issued, the driver attempts to enter that state, issuing an error if it
fails.
The function-dependent portions of the IF$CMD request and reply packets are shown below:
I

DP.DAD -

-----------------:
--1
I
I
I
I
I
I

--1

Not used

I
I
I

--1

I
I

Funcde p
value
data

I
I
I

1-----------------1 - DP.FDD
1--

--1

I
I
I

--1

Not used

I
I
I

--1

I
I

DP.BUF DP.PAR DP.LEN -

Buffer
address
----------------Buffer length

+-----------------+

--1
I

-----------------:
I
I

Ref
data
info
v
ML0-912-87

The buffer-address and buffer-length fields give the location and length, in bytes, of the buffer
of command bytes.

Instrument Bus Driver 10-27

10.5.6 Serial Poll Functions
The serial poll (IF$SPS and IF$SPO) functions are used to perform a serial poll. A serial poll is
used by the controller-in-charge to determine which devices have issued a service request.
A serial poll operation begins with the deactivation of all listeners. Each device specified in the
user's buffer is then addressed as "talker" for the purpose of reading its status byte. If bit 7
of a status byte is set, the currently addressed talker was requesting service. The status byte
is copied to the user's buffer. If Serial Poll Over All Devices (IF$SPO) was requested, or if
the service request (SRQ) bit is still set, the next device is addressed and the poll continues;
otherwise, the poll terminates.
The function-dependent portions of the serial poll request and reply packets are shown below:
I

1-----------------1 - DP.FDt

1----------------DP.DAD -

I
I

l-1
I

Funcd ep
value
data

1-1
I

Not used

1-1

I
I
1--

I
I
I

I
I

1----------------Buffer

DP.BUF - l

1--

DP.PAR - I

--1

address

1-----------------1
DP.LEN - I Buff er length I
I

+-----------------+

I
1-I
I
I
1--

I
--1
I
I
I
--1

Not used

1-I
I
I

1--

I
I

--1

I
I
I

--1

I
I
I

I
I

1-----------------1

Ref
data
info
v
ML0-913-87

The buffer-address and buffer-length fields give the location and length, in bytes, of the buffer
that lists the devices to be polled. The buffer format is shown below:

+-----------------+
Sec ad I Prim adl
-----------------:
Status
I
-------~---------!

-----------------1
Sec ad I Prim adl
I

----~------------:
Status
I

+-----------------+
ML0-913A-87
The first word of each pair gives the talker address-with extended addressing if function
modifier FM$EAD is set. The talker's status byte is returned to the second word of each pair.

10-28 Instrument Bus Driver

10.5. 7 Parallel Poll Function
The Parallel Poll (IF$PPO) function is used by the controller-in-charge to perform a parallel
poll. The driver loops for 100 microseconds to wait for the parallel poll to complete. The result
of a parallel poll is a status byte that is returned in the low-order byte of the first word of the
function-dependent reply data. The byte contains a bit for each of eight devices selected via
the Parallel Poll Configure (IF$PPC) function.
The function-dependent portions of the Parallel Poll request and reply packets are shown below:
I
I
I

1----------------- DP.FDD
: Status

DP.DAD -

Funcdep
value
data
Not

I
I

I
I
I

.-DP.BUF DP.PAR DP.LEN -

used

I
1-1
I
I

·-1
I

Not

1-1
I
I
1-1
I

used

1----------------I

1
I
I
1-I
I

1
I
I
--1
I
I

l-I

--:I

1
I

Ref

data
info

+-----------------+

ML0-914-87

10.5.8 Load Parallel Poll Register Function
The Load Parallel Poll Register (IF$LPP) function loads a status byte into the parallel poll
register. When a parallel poll is conducted, this information is transferred to the controller-incharge. The user should update this byte to reflect the state of the device. The format of the
byte is determined by a Parallel Poll Configure (IF$PPC) function request.
The function-dependent portions of the IF$LPP request and reply packets are shown below:
I
I

-----------------.
Status byte
l
-----------------.
I

DP.DAD -

- DP.FDD

I
I

I
I
I

Funcde p
value
data

--1
I
I
I

Not used

I
I
I

Not used

DP.BUF Ref

data

DP.PAR -

info

DP.LEN -

I
I

+-----------------+

v
ML0-915-87

Instrument Bus Driver 10-29

l 0.5. 9 Parallel Poll Configure Function
The Parallel Poll Configure (IF$PPC) function is used by the controller-in-charge to configure
other devices on the IEEE bus for a parallel poll. It instructs those devices on how to respond
to a parallel poll.
The function-dependent portions of the IF$PPC request and reply packets are shown below:

DP.DAD -

- DP.FOO
I

Funcdep
value
data

Not used

Not used
I
I
I

1-1

DP.BUF -

I
I

·-----------------

Buffer

.-- address
.----------------DP.LEN - I Buffer length
+-----------------+
I

DP.PAR - I
I

I•

Ref
data
info
v
ML0-916-87

The buffer-address and buffer-length fields give the location and size, in bytes, of the
configuration data buffer. That buffer has the format shown below:

+-----------------+
I Config I Lis ad I
.-----------------·
·-----------------.
I Config I Lis ad I
+-----------------+
I

ML0-917-87

Each parameter pair in the buffer gives a listener address in the range 40 to 76 (octal) and a
configuration byte with a value in the range 0 to 7. The listener address selects a device, and
the configuration byte value determines which bit in the parallel poll register the device will
update to reflect its state. The state of that bit is returned to the controller-in-charge when a
parallel poll occurs.

10-30 Instrument Bus Driver

l 0.5. l O Auxiliary Command Function
The Auxiliary Command (IF$AUX) function issues an auxiliary command by writing a byte to
the auxiliary command register. Auxiliary commands are used to enable and disable most of
the selectable features of IEQl 1-A registers.
The function-dependent portions of the IF$AUX request and reply packets are shown below:
I
I
I

I
I
I

1-----------------1
DP.DAD Auxiliary cmd
-----------------1
--1
--1
--1
Not used
1---1
DP.BUF --1
1-DP.PAR 1---1
DP.LEN +-----------------+
I
I
I

I
I
I

I
I

Funedep
value
data

I
I
I

I
I
I
I

I
I
I

I
I

I
I
I

I
I

1-----------------1 - DP.FDD
1---1
1-- Not used --1
1---1
1---1
1-----------------1

Ref
data
info
v
ML0-918-87

The auxiliary commands are described in detail in the IEQ11-A User's Guide. Their values are
shown below:

Value

Command

Software reset

Release ACDS holdoff

Release RFD holdoff

Holdoff all data

Set new byte available false (bit 7 not applicable)

Assert force end or identify (FEOI) on next byte

Listen only

10.

Talk only

11.

Go to standby

12.

Take control asynchronously

13.

Take control synchronously

14.

Request parallel poll

15.

Send interface clear

Instrument Bus Driver 10-31

Value

Command

16.

Send remote enable

17.

Request control

18.

Release control

20.

Pass through next secondary

24.

Service· request bit 2

Bit 7

Clear/set bit (required for clear/set type of features)

10.5. 11 Request Service Function
The Request Service (IF$RSV) function generates a service request to the controller-in-charge
and places a user-provided status byte in the serial poll register. The controller-in-charge will
detect that the SRQ line has asserted and perform a serial poll to determine which device
requested service. When the requesting device is addressed in a serial poll, the controllerin-charge will read the status byte from the serial poll register. The meaning of the status
byte is application-dependent, but it should indicate the type of servicing required to the
controller-in-charge.
Note
Bit 6 of the status byte is used to set the SRQ line and is not available to the
user's program.
The function-dependent portions of the IF$RSV request and reply packets are shown below:
I
I

I
I
I

-----------------:
I Status

DP.DAD -

I
I

·----------------- - DP.FDD

Funcdep
value
data

Not used

--,
I

Not used

DP.BUF 1-1
I
I

data

DP.LEN -

+-----------------+

·-----------------,
I

I
I

Ref

DP.PAR -

,--

info
ML0-919-87

10.5.12 Get Control Function
The Get Control (IF$GTC) function is used by the controller-in-charge to go from controller
standby state (CSBS) to controller active state (CACS). If the unit is already in CACS when
the request is issued, no operation is performed. A state error is generated if the unit is not
controller-in-charge.

10-32

Instrument Bus Driver

Since the driver automatically goes to the state required to process a request, this request is not
normally needed.
The function-dependent portions of the Get Control request and reply packets are not used.

10.5. 13 Go to Standby Function
The Go to Standby (IF$GTS) function is used by the controller-in-charge to go from controller
active state (CACS) to controller standby state (CSBS). If the unit is already in CSBS when the
request is issued, no action is taken. A state error is generated if the unit is not controller-incharge.
Since the driver automatically goes to the state required to process a request, this request is not
normally needed.
The function-dependent portions of the Go to Standby request and reply packets are not used.

10.5. 14 Pass Control Function
The Pass Control (IF$PCT) function passes control to a user-specified device, which takes control
in controller active state. The device is addressed to receive control as "talker," a handshake is
completed, and control is passed (by releasing the ATN line).
The function-dependent portions of the Pass Control request and reply packets are shown
below:
I
I

1----------------I

- DP.FDD

DP.DAD - :1 ________________
Talk address _

I
I

Funcde p
value
data

Not used

--1

Not used

I
I
I

--1
I

DP.BUF I

1--

DP.PAR -

I
I
I

1--

DP.LEN -

I
I

--1

Ref

I
I
I

dat,a

--1
I
I

+-----------------+

info
v
ML0-920-87

The talker address must be in the range 100 to 136 (octal).

Instrument Bus Driver 10-33

10.5. 15 Set Event Mask ~unction
The Set Event Mask (IF$SEM) function sets up event recognition by specifying events for which
recognition is requested. Those events are subsequently detected and reported to the user. (See
the IF$REV and IF$RES requests.) The events are specified in a bit mask. If a bit is set in the
mask, recognition of the corresponding event is requested.
Normally the controller-in-charge requests recognition of a service request, and devices which
are not controller-in-charge request recognition of all the other events.
Event recognition remains enabled until the request is issued with an argument of 0.
The function-dependent portions of the IF$SEM request and reply packets are shown below:
12 11 10

I
I

I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I

I
I

I
I
I
I
I
I
I
I
I
I
I
I
I
I

I
I
I
I
I
I
I
I
I
I

I
I
I
I
I
I

I
I

+---~---------------------

Remote/local change

+---------------------------- Received control
+------------------------------- Parallel poll config
+---------------------------------- Parallel poll unconf
+------------------------------------- Interface clear
ML0-922-87

10-34 Instrument Bus Driver

The event mask has the following format:
15

12 11 10

+-----------------------------------------------+
+-----------------------------------------------+
+- Service request
+---- Addr'd as listener
+------- Addr'd as talker
+---------- Deaddressed
+------------- Addr'd ext'd listener
: +---------------- Addr'd ext'd talker
+------------------- Device clear
+---------------------- Device trigger
+------------------------- Remote/local change
+---------------------------- Received control
+------------------------------- Parallel poll config
+---------------------------------- Parallel poll unconf
+------------------------------------- Interface clear
I
I

I
I

I
I
!
I
I
I
I
I
I
I
I
I
I
I

I
I
I
I
I
I
I
I
I
I

I
I
I
I
I
I

I
I

ML0-922-87

If recognition of an event represented by bits 1-9 is requested and the event occurs, the IEEE488 is locked until released by the program. The bus can be released only by an IF$AUX
request with an argument of 1 (release ACDS holdoff) or when a new request is issued to the
controller, in which case the driver automatically releases the bus.

l 0.5. 16 Wait for Event and Recognize Event Functions
The event wait and recognition functions (IF$REV and IF$RES) return notification of an event to
the user. Event recognition must previously have been enabled with an IF$SEM request. If the
event has already occurred, the request is returned immediately with notification. Otherwise,
the request either waits until the event occurs (IF$REV) or returns with a status code indicating
that no event has occurred (IF$RES).

Instrument Bus Driver 10-35

The function-dependent portions of the IF$REV and IF$RES request and reply packets are
shown below:
I

I
I

DP.DAD -

·----------------'

I
I

Funcdep
value
data
Not

I
I
I

used

DP.BUF -

I
I

1-1
I
I

Not used

1-1

1----------------1
I

Ref
data
info

DP.PAR DP.LEN -

1----------------- - DP.FOO
1----------------IUnit No.I Ev Code
1----------------l Ev Info l Status

I
I
I

+-----------------+

v
ML0-923-87

The status field has the value 2 when no such event has occurred for IF$RES requests; otherwise,
it has the value ES$NOR (0).

The event code indicates the event that has occurred as follows:

Value

Event

Service request

Addressed as listener

Addressed as talker

De addressed

Addressed as extended listener

Addressed as extended talker

Device clear

Device trigger

Remote /local change

10.

Received control

11.

Parallel poll configure

12.

Parallel poll unconfigure

13.

Interface clear

10-36 Instrument Bus Driver

The event-information byte contains the following event-dependent data:
•

If extended listener or talker, the extended address

•

If a remote/local change occurred, 0 if the unit is in local mode, or 1 if the unit is in remote
mode

•

If a Parallel Poll Configure occurred, the PPE or PPD byte

•

For all other events, 0

10.6 Status Codes
If an error is detected during an 1/0 operation by the XE driver, the driver returns an exception
code in the status field of the reply message. Extended error codes are returned also; see Section
10.7.
If no error was detected, a value of ES$NOR (0) is returned in the status-code (DP.STS) field of

the reply message, and a value of IE.SVC (1) is returned in the error field of the reply message.
The XE driver returns the following exception codes:

Code

Type

Description

ES$ABT

HARD_IO

Driver aborted

ES$CTL

HARD_IO

Controller error

ES$IVP

HARD_IO

Bad match character count for read, bad talker address for
serial poll or Pass Control, bad listener address for Parallel Poll
Configure, bad Set Characteristics parameter

ES$SPD

HARD_IO

SRQ or IFC terminated data transfer

ES$IFN

SOFT_IO

Illegal function code, bad controller state, event recognition
already active

Exception codes are defined in the ESCODE.P AS include file (included by EXC.P AS) for Pascal
users and by the EXMSK$ macro in the COMU/COMM macro libraries for MACR0-11 users.

Note
Not listed above are exception codes for kernel-detected errors that the XE driver
raises rather than passing back to the requesting process.

Instrument Bus Driver 10-3 7

10. 7 Extended Error Information
The XE driver returns extended error information in the error-info (DP.ERR) field of the reply
message. The possible return values are listed below by symbolic and decimal error code:

Value

Meaning

-10

Data transfer terminated by IFC

-9

Bad listener address specified

-8

Bad match character count specified

-7

Bad talker address specified

-6

Event recognition already active

-5

Data transfer terminated by SRQ

-4

Error interrupt

-3

Bad controller state

-2

Bad parameter

-1

Invalid IEEE function

Successful completion

10. 8 XE Driver Prefix File
Figure 10-1 shows the XE driver prefix module. The following paragraphs describe the prefix
file macro calls and symbol definitions that can be edited to fit your application.
The DRVCF$ macro is invoked once in an XE prefix file. Its parameters are the device mnemonic
(XE) and the number of configured controllers (IEQll-A ports).
The CTRCF$ macro is invoked once for each configured controller. Its parameters are controller
identifier (A, B, ... ), number of units per controller (always 1), and controller CSR address and
vector address.
The XE$xxx symbols define the hardware interrupt priority and the driver initialization and
request-handling process priorities.

10-38 Instrument Bus Driver

Figure l 0-1:
.title

Instrument Bus Driver Prenx File (XEPFX.MAC)

XEPFX

- IEQ Device driver prefix module

drvcf$
ctrcf$
xeisz$

xeisz$
XE$PPR
XE$HPR
XE$IPR

175.
4

250.
drvcf $
drvcf $
ctrcf $
ctr cf$

, Process priority
IEQ hardware priority
Process initialization priority
dname=XE,nctrl=2
dname=XE,nctrl=1
cname=A,nunits=1,csrvec=<160150,420>,units=<O>
cname=B,nunits=1,csrvec=<160150,424>,units=<1>

.end

Instrument Bus Driver 10-39

Chapter 11
Network Service Process
This chapter describes the MicroPower /Pascal network service process (NSP), which in
cooperation with the ancillary control process (ACP), communication and protocol 1/0 drivers,
and the Pascal file system OTS (or equivalent user routines) allows a MicroPower/Pascal
application to communicate and exchange data with another application residing on a remote
computer.
The NSP provides two basic task-to-task facilities-MicroPower/Pascal DECnet and
MicroPower/Pascal (non-DECnet) communication. With DECnet, the remote application is
not restricted to MicroPower/Pascal applications but could be tasks running on VAX/VMS,
VAXELN, RSX, or any other operating system that supports DECnet. Without DECnet, the
remote application must be another MicroPower/Pascal process.

11 . 1 NSP Features and Capabilities
The NSP provides the following facilities:
•

In conjunction with the ACP process, ensures the orderly establishment of task-to-task
communication paths (called logical links)

•

Coordinates the sequencing and flow of data between the tasks

•

In conjunction with lower network layers, provides for retransmission of erroneous data
received

•

Performs reliability checks on the logical link to ensure that data communication paths are
in working order

•

Coordinates the orderly termination of logical links

•

Isolates multiple logical links so that several applications can access the network simultaneously

•

Informs the application of errors in establishing or manipulating the logical link

Network Service Process 11-1

MicroPower/Pascal DECnet is an Ethernet (DEQNA) or asynchronous serial line based facility
that is compatible with Digital Network Architecture (DNA) products. MicroPower/Pascal
communication is a facility that connects two processes on different MicroPower/Pascal target
machines by means of asynchronous or synchronous interfaces with lower overhead than
MicroPower/Pascal DECnet. Both facilities use standard Pascal input/output statements for
establishing logical links and data exchange.
Note
Transparent remote file access is not implemented.

11.2 Accessing the NSP for Task-to-Task Communication
For most MicroPower/Pascal applications, you access the NSP implicitly by opening a taskto-task communication path (logical link) with the Pascal OPEN statement and then issuing
Pascal statements_ that input or output data. With both MicroPower /Pascal DECnet and
MicroPower/Pascal (non-DECnet) communication, task-to-task communication is treated as just
another input/output device. Programs written to communicate with other tasks use standard
Pascal IfO statements. The data structure controlling access and interpretation of the data
exchanged by the programs is the file variable. The NSP places no restriction on the type or
content of the exchanged data other than that it must be consistent with the method of defining
files in Pascal. For example, programs may use TEXT, FILE of CHAR, or FILE of INTEGER when
defining the content of the messages passed between them. There is no enforced requirement
that both programs use the same definition. Once the logical link between the two tasks is
established, the data flow is bidirectional; either task may WRITE/PUT data to the logical link
or READ/GET data from it, and eventually CLOSE the link. The synchronization of data
direction is the responsibility of the two applications.
When two tasks communicate, one assumes the role of the active partner; it must identify the
remote computer and the name of the task with which it will communicate. The other task takes
the role of the passive partner, awaiting a request for communication from an active task. The
method of specifying task names varies for each operating system. This chapter and Chapter
9 of the MicroPower /Pascal Language Guide describe the method used by MicroPower/Pascal.
Please see the appropriate documentation for other operating systems.
Under MicroPower/Pascal, a passive task issues an OPEN statement of the form:
OPEN (fvar, 'SY$NET: "TASK=RECEIVER"', HISTORY: =NEW);

This specifies that the program is establishing itself as a passive task whose name is RECEIVER.
The program will remain in a wait state until an active task initiates a connection.
The active task issues an OPEN statement of the form:
OPEN (fvar, 'node:: "TASK=RECEIVER"', HISTORY:=OLD);

This specifies that the program is initiating a connection to a passive task whose name is
RECEIVER, located on node "node", that is waiting to accept a connection. The syntax of the
OPEN statements is compatible with VAX/VMS Pascal syntax for task-to-task communication.

11-2 Network Service Process

A passive task that is already engaged in a dialog with another task is not eligible to accept
another connection. (A file variable describes exactly one task-to-task dialog.) Since it is
sometimes desirable to have multiple active tasks initiate dialogs with a common passive task,
the passive task must, at the completion of the OPEN statement, spawn another process that
issues the identical OPEN statement. This new task will then be available for subsequent
connections.
For each MicroPower/Pascal application that engages in task-to-task communication, in addition
to issuing the OPEN and subsequent 1/0 procedure calls, you must:
1.

Edit the PROCESSOR macro in the system configuration file to specify a clock argument
(for line timing) and edit the DEVICES configuration macro to reflect the clock interrupt
vector address

Edit the NSP prefix file to indicate:
•

NSP initialization and request-handling process priorities

•

The node area, node number, and maximum segment size in particular, plus the
maximum number of concurrent logical links and number of kernel packets reserved
per buffer

•

The non-DECnet device(s) and/or the single DECnet device to be supported (NETDV$
macro)

Edit the ACP prefix file to enable network support (see Section 2.6)

Build into your application the following 1/0 system components:
•

NSP process

•

Communication and/or protocol (data-link) drivers as defined in the NSP prefix file

•

ACP process

•

Pascal OTS routines for file service-built in automatically by MPBUILD for programs
that invoke Pascal 1/0 procedures-plus any support routines you opt to include (see
kit files GETSET.PAS and GSINC.PAS)

For more information on setting up your application software for task-to-task communication,
see Section 11.6, Chapters 12 and 13, and the material on building system processes in the
MicroPower/Pascal system user's guide for your host system.

Note
It is possible to bypass the NSP in order to access a communication or protocol

(data-link) driver directly. This can be accomplished via send/receive operations
to a driver's request queue semaphore or, in the case of the asynchronous
DDCMP (CS) and KXTl 1-CA/KXJll-CA TPR (KX/KK) drivers, by opening the
device (for example, an OPEN of 'CSAO:'). Chapters 12 and 13 refer to these
forms of access as "data link level (send/receive) 1/0" and "nonmultiplexed
MicroPower/Pascal communication," respectively.
It is also possible, given detailed knowledge of the ACP and NSP request/reply

packet interfaces, to either bypass the file system OTS in order to access the
ACP directly (and through it the NSP), or bypass the file system OTS and the
ACP to access the NSP directly. Chapters 12 and 13 refer to such access as
"low-level file system access." However, the current version of this manual does
not provide detailed descriptions of the ACP and NSP send/receive interfaces.

Network Service Process 11-3

The following sections describe the Pascal file system interface to the NSP, the NSP Set and
Get Characteristics functions, the status codes that can be returned to users of the file system
or request/reply packet interfaces, and the NSP prefix file. Sample programs that illustrate
task-to-task communication conclude the chapter.

11.3 Pascal File System Interface
Standard PASCAL I/O statements are used to manage task-to-task communication in
MicroPower/Pascal. The OPEN statement establishes logical links between active and passive
tasks; the HISTORY and IjO specification parameters of the OPEN procedure are used to create
active and passive links. GET, PUT, READ, and WRITE transfer data over the logical link.
EOLN is valid on TEXT files over logical links and EOF is valid on any link. CLOSE and
PURGE gracefully terminate logical links. BREAK and EMPTY_BUFFER terminate RECORDS
in the RMS sense when sending data to operating systems that require explicit end-of-message
control (for example, VAX/VMS). WRITELN performs this function automatically on TEXT
files. See Chapter 9 of the MicroPower /Pascal Language Guide for descriptions of the Pascal 1/0
statements.

1 1.4 NSP Set and Get Characteristics Functions
The NSP supports the Set Characteristics (IF$SET) and Get Characteristics (IF$GET) standard
device driver functions. The Pascal file GETS ET.PAS contained in the distribution kit provides
the interface routines necessary to perform those functions.
Note
The MACR0-11 symbols used in this section are defined by the DRVDF$ macro,
which resides in the COMU and COMM kernel macro libraries. The equivalent
Pascal symbols are defined in the IOPKTS.P AS include file.

11.4. 1 Set Characteristics to $SECTL Queue Semaphore
You can issue a Set Characteristics request to the $SECTL queue semaphore in order to set the
DECnet node number of the local computer when none was specified in the NSP prefix file or
in an RSX- or VMS-host NCP command (for Ethernet downline loading).

11-4 Network Service Process

The function-dependent portion of the NSP Set Characteristics request packet is shown below:
I
I

1----------------I

DP.DAD -

1
I

Funcde p
value
data

I
I

1-1
I
I

1--

t-I

DP.BUF - .--

Not

used

--:
I

DP.PAR -

I
I
I
·-I
I

DP.LEN -

I
I

--:

1
I
I

1-1
I
I

--·
I
I
I
--1
I
I

:--

1----------------Ev Info I Status
- DP.FDD
1----------------IUnit No.I Ev Code
1----------------1

I
I

1-1

Not used

1-1
I
I

1----------------1

Ref
data
info

I
I

+-----------------+

ML0-923-87

Note
The MACR0-11 field name DP.DAD, shown above, does not represent an
offset into the user's send buffer; it is an offset symbol used by MACR0-11
1/0 servers to reference packets. DP.DAD is a 24-byte (decimal) offset from
the packet header.

11.4.2 Get Characteristics to $SECTL Queue Semaphore
You can issue a Get Characteristics request to the $SECTL queue semaphore in order to return
the local system node number (or 0 if it was not specified either in the NSP prefix file or in an
RSX- or VMS-host NCP command for Ethernet downline loading).
The function-dependent portions of the Get Characteristics request and reply packets are shown
below:
I
I

DP.DAD I
I

Funcdep
value
data

Not used
I
I
I

--1
I
I

-----------------1

I
I
I
I

I
I

:----------------: Type I Class
- DP.FDD
1----------------ILocal node number
1----------------I

1
I
I

1-1
I

Not used

1-1
I

1----------------I

1
I

ML0-924-87

In the reply information above:
•

Class is DC$SSV for system service class.

•

Type is SS$NSC for network session control.

Network Service Process 11-5

11.4.3 Get Characteristics to File Variable
You can use the module GETSET.PAS and the Pascal include file GSINC.PAS to issue a Get
Characteristics request to the logical-link file variable, in order to return the node number of
the remote partner.
In this case, the function-dependent portions of the Get Characteristics request and reply packets
are:
I
I
I

1-----------------1
DP.DAD I

I
I
I

Type

I
I

- DP.FOO

Class

I
I

Func-

Remo~e

node number

de p

value
data

Not used

-----------------1
I
I

Not used

--1
I
I
I
--1

I
I
I

------------------·
I
I

ML0-925-87

In the reply information above:
•

Class is DC$SSV for system service class.

•

Type is SS$NLL for network link server.

11.5 Status Codes

Any error detected by the NSP during an I/O operation is returned in the status-code field
of a reply message. If you are performing I/O with Pascal I/O statements-that is, not with
send/receive statements-the Pascal OTS will report the corresponding exception (unless the
operation was an OPEN for which a STATUS return was specified). The error codes listed in
this section are those generated by the NSP directly-not those generated by other I/O system
components involved in task-to-task data exchange.
If no error is detected during the I/O operation, the NSP returns a value of ES$NOR (0) in the

status-code field.

11-6 Network Service Process

The NSP returns the following exception codes:

Code

Type

Description

ES$ABT

HARD-10

1/0 request canceled or aborted. This status
is returned when the remote partner purges
the logical link. PURGE normally indicates
an abnormal termination of the logical link.

ES$DAL

HARD_IQ

Device already allocated. This status is
returned when an attempt to set the local
node number with Set Characteristics is
made and the local node number is already
defined.

ES$0VF

HARD_IQ

Data buffer overflow.

ES$DNU

SOFT-10

Destination node is unreachable. This status
indicates that the node requested by an
active task is not currently reachable via
the network.

ES$EOF

SOFT_IQ

End of file. This status is returned when
the remote partner closes the logical link.
CLOSE is the normal method of termination
of a logical link. The Pascal OTS interprets
this status and causes the EOF function to
return TRUE.

ES$IFN

SOFT_IO

Illegal function.

ES$IVL

SOFT_IQ

Invalid length.

ES$LRJ

SOFT_IO

Link rejected by the remote task. This status
indicates that the remote passive task exists
but has decided not to accept the logical
link. This error cannot occur if the remote
computer is another MicroPower /Pascal target.

ES$NRF

SOFT_IO

No reference data present.

ES$PAL

SOFT-10

Path to remote partner lost. This status
indicates that, although the remote partner
was at some time connected to the logical
link, there is no longer a network path to
the remote computer.

Network Service Process 11-7

Code

Type

Description

ES$TNF

SOFT_IO

Task not found. This .status indicates that
the node requested by the active task does
not contain the desired passive task.

ES$LNR

RESOURCE

Local network resource failure. This status
is returned when there are already NS$NLL
logical links in use and an attempt to open
another is made. If more concurrent logical
links are required, increase the NS$NLL
value in the NSP prefix file.

ES$RNR

RESOURCE

No resources at the remote computer. This
status indicates that the node requested by
the active task does not have sufficient
resources to create a logical link. This
error cannot occur if the remote computer is
another MicroPower/Pascal target.

Exception codes are defined in the ESCODE.P AS include file (included by EXC.P AS) for Pascal
users and by the EXMSK$ macro in the COMU and COMM macro libraries for MACR0-11
users.

11.6 NSP Prefix File
The NSP prefix module is shown in Figure 11-1. The following paragraphs describe the prefix
file macro calls and symbol definitions that can be edited to fit your application.
The modifiable constants and their default values (in decimal) are:

Symbol

Default

Description

NS$IPR

250

The priority of the NSP initialization procedure.

NS$PPR

175

The priority normally used for the NSP process. DIGITAL
recommends that the priorities of the ACP, the NSP, and
any driver used by the NSP be the same to avoid excessive
context switching.

11-8 Network Service Process

Symbol

Default

Description

NS$SGZ

256

The maximum individual data i:_nessage size. This value
is the size of the largest single message that the NSP
will transmit to a remote application. User file variables
may be larger (see the sample programs below) but
the Pascal I/O system and the NSP will transmit the
larger message as a sequence of smaller segments. The
application may also request that smaller messages be
transmitted by specifying the BUFFERSIZE parameter on
the OPEN statement. Finally, the actual data message
segment size used is the minimum of the BUFFERSIZE
parameters specified by both application program OPEN
statements (excluding 0) and the NS$SGZ parameter of
the NSP processes on each computer. By adjusting
this parameter and using the BUFFERSIZE parameter of
OPEN, the application can trade off RAM usage, and
network message traffic.

NS$NLL

The maximum number of concurrent logical links. Each
OPEN statement consumes one of these logical links, and
each CLOSE or PURGE releases one.

NS$XKP

The number of kernel packets reserved to the NSP process
in addition to one per communication buffer. If kernel
packets are a scarce resource in the application, reserving
some to the NSP will increase network performance.

NS$DNN

The DECnet node number.
For MicroPower/Pascal
DECnet, each node must have a node number. This value
can be supplied in the prefix file in an RSX- or VMShost NCP command (for Ethernet down-line loading)
or in a Set Characteristics request. The NCP value
applies for a mapped application that is configured to
respond to a network boot request (SYSTEM debug=NO,
netboot=YES). Otherwise, the prefix file value applies. If
network booting is disabled (SYSTEM netboot=NO) and
0 (zero) is specified in the prefix file, the NSP process
does not participate in DECnet until a node number is
defined using the Set Characteristics function.

NS$DNA

The DECnet area number. The formula NS$DNA * 1024.
+ NS$DNN defines the actual Phase IV DECnet node

address.
Communication devices used by the NSP fall into two categories-DECnet and MicroPower /
Pascal-only. DECnet devices are the QN driver (type=ETHER) for the DEQNA Ethernet interface
and the CS driver (type=POINT) for the asynchronous DDCMP interface. Only one of these
may be specified in the prefix file. MicroPower/Pascal-only devices (type=UPOWER) are the
CS driver, the XP driver for the DPVl l, the XS driver for the synchronous port of the KXTl 1CA/KXJl 1-CA, and the KX/KK drivers for the arbiter-KXTl 1-CA/KXJl l-CA communication
port.

Network Service Process 11-9

Figure 11-1:
.title

NSP Preftx File (NSPPFX.MAC)
NSPPFX - Network Services Process prefix module

macdf$,misdf$,nspdf$

; User changable symbols for the NSP process
NS$IPR
NS$PPR
NS$SGZ
NS$NLL
NS$XKP
NS$DNN
NS$DNA

;Initialization priority
;Normal process priority
256.
;Maximum data message size
4.
;Maximum number of concurrent logical links
2.
;Packets reserved in addition to one per buff er
0.
;DECnet node number (Unspecified)
;DECnet area number (Unspecified)
0.
250.

175.

The definition of the communication devices
For MicroPower-to-MicroPower devices:
NETDV$ QSEM=<ssssss>,UNIT=u,NUMBFR=b,TYPE=UPOWER,AREA=a,ADDRESS=n
or
NETDV$ TYPE=SELF
;To enable links to the local node (0: :)
For DECnet devices
NETDV$ QSEM=<ssssss>,UNIT=u,NUMBFR=b,TYPE=ETHER
or
NETDV$ QSEM=<ssssss>,UNIT=u,NUMBFR=b,TYPE=POINT

;Ethernet
;Async DDCMP

ssssss is a 6 character, upper case, blank filled device driver
named semaphore enclosed in angle brackets (e.g. QSEM=<$QNA >).
This parameter must be specified, there is no default.
u

is the unit number if the device driver is capable of
supporting multiple units. The default is O (zero).

is the number of input buffers dedicated to this device. The
number of buffers to use is dependent on the speed of the
device. The default is 4 (four) but can be set to 1 for low
speed lines and higher for broadcast lines. The number of
buffers greatly affects the RAM usage of the NSP process.
Each buffer also causes a kernel packet to be reserved to the NSP.

11-10 Network Service Process

The following parameters must be specified on Non-DECnet devices and
must NOT be specified on DECnet devices.
a

is the area number associated with the node. If no area is
specified, the area of the local node is used.

is the address within the area associated with the node.

If the node specified in the PASCAL OPEN statement is associated
with a MicroPower-to-MicroPower device then that device will be
used, otherwise it is assumed that the node can be reached by
the DECnet partner (designated router on Ethernet) . There is no
requirement that the MicroPower node on the other side of the
Non-DECnet device have NS$DNN = n and NS$DNA = a. These
parameters are used solely to differentiate between DECnet and
MicroPower intersystem environments.
Note 1: Any Non-DECnet devices must be specified first.
Note 2: There can be only 1 DECnet device specified.
NETDV$
NETDV$
NETDV$
NETDV$

qsem=<$CSA
type=SELF
qsem=<$CSA
qsem=<$QNA

>,unit=1,type=UPOWER,address=1023.

nsf in$
.end

;Generate the data structures
;and all done

>,unit=O,type=POINT
>,type=ETHER

l l . 7 Sample Programs
11. 7. l Transferring Data Between Two MicroPower/Pascal Nodes
The following two programs exchange data. The first is the active task that continually copies
and displays TEXT data from the passive task. The second is the passive task. Note that the
second program spawns an identical copy of the server process upon completion of the OPEN
statement. This is to ensure that there is always a passive task available.
[System(MicroPower)] program network_read;
var
: text;
ch : char;

Network Service Process

11-11

begin
while true do
begin
open (f, '5. 410: : 11 TASK=IDENTIFY 11 ' , BUFFERSIZE
,HISTORY :=OLD, OVERLAPPED :=ENABLE);
reset (f);
while not eof (f) do
begin
while not eoln (f) do
begin
output- := f-;
put(output);
get(f);
end;
writeln (output);
get(f);
end;
close (f);
end;
end.

[System(MicroPower)] program network_server;
[stack_size(300)] process identify(year : integer);
var
f : text;
begin
open(f,'SY$NET:'(TASK=IDENTIFY)',history:=new,buffersize:=80,
overlapped:=enable);
identify(year+1,relation:=independent);
rewrite(f);
writeln(f, 'Year of the city ',year:!);
writeln(f, 'Welcome stranger');
write(f,'You have contacted Logan 5 on the node UPOWER');
writeln(f);
writeln(f);
writeln(f, 'Things are pretty good here except no task may exist');
writeln(f, 'for more that 30 milliseconds. Gotta run now.');
writeln(f);
writeln(f, 'Remember: On the net, there is no Sanctuary.');
close(f);
end;
begin
identify(!);
end.

11-12 Network Service Process

11. 7 .2 Transferring Data Between MicroPower/Pascal and VAX/VMS
Nodes
The following programs demonstrate data exchange between a MicroPower/Pascal program/process and a VMS program. The method of data exchange is task-to-task communication. The VMS examples conform to the guidelines set forth in the VMS DECnet User's
Guide and those referenced in the VMS PASCAL Reference Guide. For methods of invoking a
task in other languages or on other operating systems, see the documents for those languages
or systems.
To send a record of data from a MicroPower/Pascal process to a VMS program, create a
command file in the appropriate VMS directory that will invoke the VMS passive task when
the MicroPower task requests it.
$! This is command file TV.COM
$

$RUN TV

!Assumes TV.EXE is in the same directory

This is the VMS PASCAL program that receives the data.
PROGRAM TV(INPUT,OUTPUT,F);
CONST BIG_ARRAY_SIZE = 1024;
TYPE BIG_ARRAY = ARRAY [1 .. BIG_ARRAY_SIZE] OF INTEGER;
VAR F : FILE OF BIG_ARRAY;
J : INTEGER;
BEGIN
OPEN (F,'SYS$NET',HISTORY:=OLD,ACCESS_METHOD:=SEQUENTIAL);
RESET(F);
FOR J := 1 TO BIG_ARRAY_SIZE DO
BEGIN
WRITE(OUTPUT,F-[J]);
IF F-[J] <> J
THEN WRITE(' <----Error, should have been ',j:1);
WRITELN;
END;
CLOSE(F);
END.

This is the MicroPower/Pascal program that constructs the data.
[system(micropower)] program TM(input,output);
const
big_array_size = 1024;
type
big_array = array [1 .. big_array_size] of long_integer;
var
f
file of big_array;
j : integer;
begin
open (f, '5.69"(USER PASSWORD): :"(TASK=TV)'" ,HISTORY:=OLD);
rewrite(f);
for j := 1 to big_array_size do f-[j]
j;
put(f);
break(f);
close(f);
end.

Network Service Process

11-13

In the example above, node 5.69:: is assumed to be the DECnet node number of the VMS
system, [USER] is the directory containing the TV.COM file, and PASSWORD is the valid
password for the USER. USER and PASSWORD (and the "characters" can be omitted to indicate
to VMS that the default DECnet account should be used.
This program uses a 4096-byte RECORD, which is the largest record that the VMS Pascal
run-time library will allow. For this example, the RECORD is simply an array of 4-byte integers
(VAX INTEGER is 4 bytes long, which is the size of a MicroPower/Pascal LONG-1NTEGER).
As long as the records are of compatible types, contents, and length, any record could be
exchanged. Files of type TEXT can also be used to utilize variable-line-length ASCII data.
The MicroPower /Pascal program above was installed in a kernel image that contained the QNA
(QNPFX) driver, the ACP (ACPPFX) process, and the NSP (NSPPFX) process. The NSPPFX file
was edited to assign the appropriate MicroPower/Pascal node identification (node number).
Using the same sample programs as above, the following code transfers data to a
MicroPower/Pascal task from a VMS image.
This is the VMS PASCAL program that constructs and sends the data:
PROGRAM TV(INPUT,OUTPUT,F);
CONST BIG_ARRAY_SIZE = 1024;
TYPE BIG_ARRAY =ARRAY [1 .. BIG_ARRAY_SIZE] OF INTEGER;
VAR F : FILE OF BIG_ARRAY;
J : INTEGER;
BEGIN
OPEN (F. 'UPOWER: : II (TASK=TM) II, • HISTORY: =NEW.
ACCESS_METHOD:=SEQUENTIAL);
REWRITE(F);
FOR J := 1 TO BIG_ARRAY_SIZE DO F-[J] := J;
PUT(F);
CLOSE(F);
END.

This is the MicroPower /Pascal program that receives the data:
[system(micropower)] program TM(input,output);
const
big_array_size = 1024;
type
big_array =array [1 .. big_array_size] of long_integer;
var
f
file of big_array;
j : integer;
begin
open (f, 'SY$NET: 11 (TASK=TM) ',history :=new);
reset(f);
for j := 1 to big_array_size do
begin
write(output,f-[j]);
if f-[j] <> j
then write(' <----Error, should have been ',j:1);
writeln;
end;
close(f);
end.

11-14 Network Service Process

In the example above, node UPOWER:: is assumed to be the DECnet node name of the
MicroPower/Pascal system. It is also assumed that the system manager for VMS has used NCP
to set the correspondence of the node name UPOWER with the appropriate node number and
that that node number corresponds to the one specified in the NSP prefix (NSPPFX) file. The
VMS image can then be invoked by the running of it interactively or in batch.
The examples process the data, which shows the method of data exchange. The VMS sending
program could have taken its data from a disk file and presented it to the MicroPower/Pascal
process. This could be a method of transferring files between the systems, assuming some
knowledge of the file names, contents, record formats, and record-blocking used by each system.
Files created on VMS are truly readable only by RMS. However, if the two programs agree to
exchange the data at the record level, the VMS Pascal program could read records from the file
(letting RMS worry about file format) and send compatible records to the MicroPower/Pascal
process. Then, the data exchange would be at the record level and would be independent of
the file characteristics.

11. 7 .3 Determining and Setting the Local Node Number
The following program determines the local node number and shows one way to set the node
number if it was not specified in the NSP prefix file or in an RSX- or VMS-host NCP command
(for Ethernet down-line loading).
[system(micropower)] program nettst(input,output);
%include 'GSINC'
var
local_node : unsigned;
main_sts : array [1 .. 2] of unsigned;
main_net : queue_semaphore_desc;
function ask_node(
var prompt:[readonly] packed array [l .. h:integer] of char
) : unsigned;
var
i : integer;
a,n : unsigned;
c : char;
begin
for i := 1 to h do write(prompt[i]);
write(' (area.number) ? ');
readln(a,c,n);
ask_node := n + (a * 1024);
end;

Network Service Process 11-15

begin
init_structure_desc(desc := main_net, name := '$SECTL');
if not Get_Desc_Characteristics(main_net,0,main_sts,size(main_sts))
then main_sts[2] := O;
if main_sts[2] <> 0
then
begin
main_sts[1] := main_sts[2] div 1024;
main_sts[2] := uand(main_sts[2] ,1023);
writeln('Local node is ',main_sts[1] :1, '. ',main_sts[2] :1);
end
else
begin
main_sts[2] := ask_node('What is the local node number');
if Set_Desc_Characteristics(main_net,0,main_sts,size(main_sts))
then ;
end;
local_node
main_sts[2];
end.

11-16 Network Service Process

Chapter 12
Asynchronous DDCMP Driver
This chapter describes the use of the MicroPower/Pascal asynchronous DDCMP (CS) driver,
which impl~ments the Digital Data Communications Message Protocol (DDCMP) for message
exchange over asynchronous serial lines.
The CS driver controls the transmission of data grouped into physical blocks (data messages)
over an asynchronous serial data link, while ensuring correct sequencing and integrity of the
messages. Those messages are exchanged with a partner program on a different computer that
also adheres to the DDCMP protocol.
Once the data is correctly exchanged, it is the responsibility of higher levels of softwarefor example, the MicroPower /Pascal network service process (NSP) or a user process-to
interpret the exchanged data. The calling process must agree with the partner software on the
format and meaning of the transmitted data. The transmitted data may, for example, contain
control information that allows the higher-level software to provide such services as message
segmentation or multiplexing of that exchange with other task-to-task "conversations" over the
serial line.
The CS driver differs from other MicroPower /Pascal drivers in that it controls the hardware not
directly but by issuing requests to another driver-the asynchronous serial line (TT) driver. For
that reason, the MicroPower/Pascal software classifies CS as a "protocol" device driver, whereas
the TT driver (Chapter 3) and the communication drivers (Chapter 13) are given hardware-based
classifications. The TT driver provides a basic byte transmission capability; the CS driver adds
message framing, message sequencing, error detection, and retransmission of messages. received
in error.
The CS driver supports DDCMP message exchange via the following asynchronous serial line
interfaces:
•

DLVll-type-DLVll, DLVll-E, DLVll-F, DLVll-J

•

DLART-type-KXTll-CA/KXJll-CA console, SBC-11/21, MXVll-A, MXVll-B

•

DZVll

•

DHVll

•

KXTll-CA/KXJll-CA multiprotocol chip

Asynchronous DDCMP Driver 12-1

When used in conjunction with the CS and TT drivers, the supported devices interface one
or more asynchronous serial lines to a MicroPower/Pascal target processor for communication
with other processors.
MicroPower/Pascal supports three distinct levels of communication device IjO:
•

MicroPower/Pascal DECnet

•

MicroPower /Pascal Communication

•

Data link level (send/receive) 1/0

Section 12.2 describes each level of communication device access and summarizes the possible
paths through the CS driver.

12. 1 CS Driver Features and Capabilities
The CS driver provides a standard driver interface to DDCMP, a byte-oriented data link
protocol. The MicroPower/Pascal implementation of DDCMP provides sequential, error-free
message delivery over an asynchronous serial communication link. The protocol performs the
following functions:

•

Message framing: constructs or interprets DDCMP data messages and control messages
(described below)

•

Error detection: detects errors in message headers or data via cyclic redundancy checksum
(CRC) checks

•
•

Retransmission of messages received in error
Message sequencing: numbers messages in order to prevent duplications or omissions and
to identify retransmissions

In a DDCMP data message, data to be transmitted is preceded by a header that includes a special
beginning character, a byte count that indicates the length of the data portion (up to 16383
bytes), and control information. The control information can include the number of the last
correctly received message (piggybacked acknowledgment) and the current packet's sequence
number. CRCs follow both the header and data portions.
In addition to the data messages, there are five control messages: ACK, NAK, REP, START, and
STACK. ACK conveys acknowledgment of successful message receipt when there is no reverse
traffic onto which to piggyback a response. NAK carries notification of an error and its cause,
while implicitly acknowledging successful receipt of all previous messages. REP is sent when
a transmitter times out waiting for acknowledgment; it requires an ACK or NAK response.
Also, in the MicroPower/Pascal implementation, REP is sent at user-defined intervals as a
"keep-alive" timing mechanism (unless the calling process-for example, the NSP-is timing
the line). START and STACK initialize a DDCMP link.
The DDCMP protocol can accommodate many different methods and modes of transmission.
The MicroPower/Pascal implementation uses full duplex transmission in asynchronous serial
mode.
Note
MicroPower/Pascal DDCMP is for point-to-point use only.
In the data
message, the select flag (used in half-duplex or multipoint configurations to

12-2

Asynchronous DDCMP Driver

turn transmitters on and off) is always 0, and the station address (used to
identify multipoint tributaries) is always 1.
Also, MicroPower/Pascal DDCMP does not support maintenance mode and the
messages associated with it.
The CS driver supports read and write operations, protocol enabling or disabling, and the
returning of "device" characteristics. Indirect reference pointers are honored on write operations
for the purpose of performing gathered writes into a DDCMP data message.
The CS driver can be accessed by the NSP (which normally implies filesystem OTS and ACP
involvement) in connection with setting up logical links and multiplexing them across physical
links (virtual circuits) for task-to-task I/O. The driver can also be opened for Pascal file I/O
without NSP involvement (for example, an OPEN of 'CSAO:'), or used directly by a user process
for data link level (send/receive) I/O.
The NSP uses the CS driver for the following types of task-to-task communication:
•

DECnet endnode support, for communication between a MicroPower/Pascal target and
another DECnet node-possibly another MicroPower/Pascal target, a VAX/VMS or RSX
system, or other system running DECnet

•

Asynchronous point-to-point communication between two MicroPower /Pascal targets

12.2 Performing Asynchronous DDCMP 1/0
MicroPower/Pascal supports three distinct levels of communication device IfO:
•

MicroPower/Pascal DECnet

•

MicroPower/Pascal communication

•

Data link level (send/receive) I/O

For most MicroPower /Pascal applications, asynchronous DDCMP message exchange is performed with the MicroPower/Pascal DECnet or MicroPower/Pascal communication facilities.
MicroPower/Pascal DECnet is an asynchronous serial line-based or Ethernet-based (DEQNA)
facility that is compatible with Digital Network Architecture (DNA) products.
Using
MicroPower/Pascal DECnet, a MicroPower/Pascal target machine may communicate with
processes in other MicroPower /Pascal targets, with processes in VAXELN targets, or with
tasks in VAX/VMS, RSX, or other systems.
MicroPower/Pascal communication allows the user to exchange data between processes on
different MicroPower/Pascal target machines by means of standard Pascal Input/Output
statements.

Note
Transparent remote file access is not supported. One method for transferring
files between systems, using task-to-task data exchange, is noted in Chapter 11.
Both the Micro Power /Pascal DECnet and communication facilities provide sequential, error-free
data delivery, while hiding the details of data exchange, such as initialization and error recovery.
Both facilities can carry on many task-to-task dialogs across a single physical link. The physical
link is controlled to ensure that there is no "crosstalk" between the multiplexed logical links.

Asynchronous DDCMP Driver 12-3

The MicroPower /Pascal DECnet and Communication facilities have the following components:
•

The NSP coordinates the flow of data between two processes. The NSP conforms to
the DNA specifications for the Session Control layer, the End Communication (Network
Services) layer, and the Routing layer of DECnet. See Chapter 11 for details.

•

The CS driver monitors the data transfer between two MicroPower/Pascal target machines
and performs the appropriate recovery algorithms to correct transmission errors. The CS
driver conforms to the DNA specification for DDCMP and the DECnet Data Link layer. (CS
is a protocol driver and does not control hardware directly; it uses the TT driver to perform
lower-level data link functions.)

•

The communication drivers (QN, XP, XS, KX, and KK) control communication device
hardware, performing such data link functions as message framing and error detection. See
Chapter 13 for details.

Note
When multiplexing of logical links over a CS serial line is not necessary, you can
eliminate the NSP from your application and open the serial line by specifying
"CSAO:" (for example) in the OPEN statement. Nonmultiplexing is a special
case of MicroPower/Pascal Communication and applies only to protocol-class
and communication-class drivers that allow direct opens-CS, KX, and KK.
For each MicroPower/Pascal application participating in DDCMP-based data exchange, in
addition to invoking the Pascal 1/0 procedures, you must:
1.

Edit the PROCESSOR macro in the system configuration file to specify a clock argument (for
line timing) and edit the DEVICES configuration macro to reflect the serial line controller
and clock interrupt vector addresses

Edit the TT driver prefix file to reflect:

•

[For each controller:] Controller type, CSR address, interrupt vector address, hardware
interrupt priority, and number of serial lines

•

[For each line:] JSR buffer size and line speed; XON/XOFF flow control and line editing
must be disabled

•

Driver initialization and request-handling process priorities

Edit the CS driver prefix file to reflect:
•

[For each .serial line:] TT queue semaphore identifier and TT unit number; the CS unit
number will normally NOT correspond to the TT unit number

12-4 Asynchronous DDCMP Driver

•

Other interface characteristics, such as the ACK timeout interval and (if the calling
process is not timing the line) the interval between "keep-alive" message transmissions

•

Driver initialization and request-handling process priorities

[For logical link OPEN:] Edit the NSP prefix file to define the communication devices
available to the NSP process. Non-DECnet devices precede a DECnet device, and only one
DECnet device may be specified. Specify TYPE parameter POINT for DECnet DDCMP.
For DDCMP Communication (non-DECnet), specify type UPOWER and supply an address
(parameters AREA and ADDRESS).

[For OPEN:] Edit the ACP prefix file to indicate whether NSP open support is required; the
default is inclusion of NSP open support. Also, check the ACP pool size; 180 bytes are
required per NSP open.

Build into each participating MicroPower/Pascal application the following 1/0 system
components:

•
•
•
•
•

TT driver process
CS driver process
[For logical link OPEN:] The NSP
[For OPEN:] The ACP
Pascal OTS routines for file service-built in automatically by MPBUILD for programs
that invoke Pascal 1/0 procedures-plus any 1/0 support routines you choose to include
(see kit files GETS ET.PAS and GSlNC.P AS)

For more information on setting up your application software for DDCMP protocol I/O, see
Chapter 4 of the MicroPower /Pascal Run-Time Services Manual, Section 12.6 of this manual, and
the material on building system processes in the MicroPower /Pascal system user's guide for
your host system.
When a module that contains Pascal I/O procedure invocations is built into your application,
Pascal OTS routines for file service are linked to the module. The OTS file routines perform
all Pascal operations on logical-link or device files, including opening, input, and output. In
particular, they perform the necessary low-level processing of high-level operations, such as
OPEN and WRITE. Thus, the basic mechanisms of MicroPower/Pascal I/0-the sending of
request packets to driver or NSP or ACP queue semaphores, the dispatching of interrupts, and
the signaling of reply semaphores-are concealed from the Pascal user.
As alternatives to using the MicroPower/Pascal DECnet or Communication facilities for DDCMP
protocol I/O, you can:
•

Issue your own Pascal or MACR0-11 packet-level requests to the ACP and an NSP logicallink server (or CS driver if no NSP), bypassing the OTS file routines (lower-level file system
access)

•

Issue your own Pascal or MACR0-11 packet-level requests to the CS driver, bypassing the
OTS file routines, the ACP, and the NSP (low-level nonfile access)

Asynchronous DDCMP Driver 12-5

Table 12-1 summarizes the possible paths through the CS driver. For reference, the three
levels of communication represented are MicroPower/Pascal DECnet, MicroPower/Pascal
Communication, and data link level (send/receive) I/O.

Table 12-1:

Asynchronous DDCMP 1/0 Paths and Interfaces

1/0 System Components

Interface

ACP/NSP

Prot

Comm/TT Pascal

MACR0-11

DECnet/DDCMP
or DDCMP
Communication

ACP/NSP

OPEN link

SEND$ to ACP (or NSP
using ACP format)

DDCMP
nonmux
Communication

ACP

OPEN comm.
line

SEND$ to ACP

SEND to
driver

SEND$ to driver

Type of
Communication

DDCMP (data
link level)

The following sections describe the Pascal I/O statement interfaces to the CS driver, the lowerlevel request/reply packet interface, the status. codes that can be returned to users of any
interface, and the CS driver prefix file.

12.3 Pascal 1/0 Procedure Interface
To perform standard Pascal I/O to a DDCMP communication line, you issue an OPEN statement
that associates a file variable with a logical link. (An alternative-the direct opening of a
communication line-is addressed below.) The file variable controls access and interpretation of
data as it is exchanged, via the serial line, with a cooperating program on a different machine.
No restriction is placed on the type or contents of the exchanged data, as long as all is consistent
with the method of defining files in Pascal. Programs may use TEXT, FILE of CHAR, FILE of
INTEGER, and so forth when defining the content of the messages passed between them. Nor
must both programs use the same definition.
To accomplish the dialog between tasks, one task must take the role of the initiator, or active
task, while the other defines itself as the target, or passive task. The passive task must define
a name that identifies the task to an active task; the active task specifies the name of the
passive task when initiating the connection. Task names can be up to 16 characters long. When
initiating the connection, the active task must specify the machine containing the passive task
it is attempting to locate. MicroPower/Pascal DECnet will dynamically determine the location
of each named machine. For MicroPower/Pascal Communication, each serial line is associated
with a static name that identifies the machine to which it is connected.
Once the connection between the two tasks is established, the dialog is bidirectional; that is,
either task may WRITE/PUT data to it or READ /GET data from it, and eventually close it,
as if it were a file residing on a local device. The synchronization of data direction is the
responsibility of the two programs.
·

12-6 Asynchronous DDCMP Driver

For example, a passive task can issue an OPEN statement of the form:
OPEN (fvar. 'SY$NET: "TASK=taskname"', HISTORY: =NEW);

This specifies that the program is establishing itself as a passive task with the name "taskname".
The program will remain in a wait state until an active task initiates a connection.
The active task issues an OPEN statement of the form:
OPEN (fvar, 'node:: "TASK=taskname'", HISTORY:=OLD);

This specifies that the program is initiating a connection to a passive task named "taskname"
located on node "node" that is waiting to accept a connection. The syntax of the OPEN is
compatible with VAX/VMS Pascal syntax for task-to-task communication.
A passive task that is already engaged in a dialog with another task is ineligible to accept
another connection. (A file variable describes exactly one task-to-task dialog.) If you want
multiple active tasks to initiate dialogs with a common passive task, the passive task must, at
the completion of the OPEN statement, spawn another process that issues the identical OPEN
statement. The new task will then be available for subsequent connections.
The preceding discussion of the OPEN statement applies to MicroPower/Pascal DECnet and to
MicroPower/Pascal Communication in the case where several "conversations" are occurring on
the data channel. However, if the serial line is to be used by a single process in one target
talking to a single process in another target, you can avoid the overhead of the NSP process
simply by not installing it into the application image. The two application processes can then
OPEN the communication line directly with:
OPEN (filvar, 'CSAu:, ... )

where:
•

filvar is a Pascal file variable.

•

u is a DDCMP unit number (0, 1, ... ).

For example, 'CSAl:' would specify the second serial line unit listed in the CS driver prefix file.
Note
Any number of serial lines are supported, but the number is limited for each
type of controller configured in the TT prefix file-up to four for DZVl 1, up
to eight for DHVll, one for most others. The range of valid identifying unit
numbers is 0 through (n-1) for n lines configured in the CS driver prefix file.
Lines are numbered sequentially upward from 0 in the order they appear in the
prefix file, independently of the specified TT unit numbers. Note that TT and
CS unit numbers normally do not match; TTAO is normally off limits to the CS
driver because of its implicit (default) association with the standard Pascal file
variables INPUT and OUTPUT.
MicroPower /Pascal Communication will place the process in a wait state until the other process
issues a similar OPEN statement, at which time the two processes may begin exchanging data.
Note
The Pascal EOLN procedure is valid for TEXT data exchanged over a logical
link, and the EOF procedure is valid for any link. The CLOSE and PURGE
procedures are used to terminate logical links gracefully.

Asynchronous DDCMP Driver 12-7

For examples of data transfer between two MicroPower /Pascal targets or between a
MicroPower /Pascal process and a VMS image, see Chapter 11.

12.4 Request/Reply Packet Interface
The packet-level functions provided by the CS driver are listed below by symbolic and decimal
function code:
Code

Function

IF$RDL (1)

Read Logical

IF$WTL (4)

Write Logical

IF$GET (7)

Get Characteristics

IF$ENA (8)
IF$DSA (9)

Enable Protocol
Disable Protocol

IF$LOK (16)
IF$ENT (17)

Lookup (equivalent to Enable Protocol)
Enter (equivalent to Enable Protocol)

IF$CLS (20)
IF$PRG (21)

Close (equivalent to Disable Protocol)
Purge (Disable Protocol variant)

Note
The MACR0-11 symbols used in this section are defined by the DRVDF$ macro,
which· resides in the COMU and COMM kernel macro libraries; the equivalent
Pascal symbols are defined in the IOPKTS.P AS include file.
The function modifiers recognized by the CS driver are shown below by symbolic code and bit
position:
Code

Function

FM$NTR (bit 6)

Calling process (NSP) will time the line, disable keep-alive (Enable
Protocol)

FM$IRP (bit 6)

Indirect reference pointers, perform gathered write (write)

FM$BSM (bit 13)

Signal binary/ counting semaphore

The CS driver consists of an initialization process, which lowers its priority to become the first
controller's request handler process; a timer process; and for each line, a receiver process and
a transmitter process. The single request-handling process handles all serial line units specified
in the CS driver prefix file. DDCMP 1/0 requests for any controller or line are sent (using a
Pascal SEND or a MACR0-11 SEND$) to the request queue semaphore waited on by the CS
static process.
The timer process runs approximately once a second to handle REP timing (the sending of
'"keep-alive" messages at user-defined intervals when the calling process is not timing the line),
retransmissions, protocol initialization, and orderly protocol shutdown. (Shutdown can be
triggered by a user request, a protocol error, or ACK timeout.)

12-8 Asynchronous DDCMP Driver

The receiver process for each line continually reads the line's incoming byte stream, interprets
DDCMP messages, and processes them according to their type. Read Logical requests (with the
minimum/maximum modifier set) are sent to the TT driver on an as-needed basis.
The transmitter process for each line gets messages from the line's outgoing queue, constructs the
required DDCMP data messages and control messages, and executes the appropriate DDCMP
sequences to send the user data. Write Logical requests are sent to the TT driver to put strings
of bytes into the outgoing byte stream.
The request queue name and number of supported units for CS driver requests are:

Driver

Request
Queue Name

Number
of Units

DDCMP

$CSA

1-n

Numbering
0 through (n-1) in prefix file order, independently of
TT unit numbers

Note that TT and CS unit numbers normally do not match; TTAO is normally off limits to
the CS driver because of its implicit (default) association with the standard Pascal file variables
INPUT and OUTPUT.

Asynchronous DDCMP Driver 12-9

The general format of the CS driver request and reply packets is shown below:
cs

REQUEST
PACKET

DP.FUN

+-----------------+
Standard

packet

header

Function

cs
REPLY
PACKET

- DP.FUN

DP.UNI -

Unit

DP.SEQ -

Sequence number

DP.PDB -

Requesting

Funcind ep
value
data

process
identifier

I
I
I
I
I
I
I

Unit

- DP.UNI

Sequence number

- DP.SEQ

Status code

I
I

- DP.STS

-----------------1
Actual length
- DP.ALN

I
I
I

Error info

I
I
I

Reserved for

- DP.ERR

DP.SEM -

- DP.XTR

semaphore

driver

I
I

--1

identifier

usage

-----------------1
Type i Class i - DP.FDD
-----------------1
I

DP.DAD I
I

Not used

Funcd ep
value
data

Not
used

DP.BUF -

Buffer

DP.PAR -

address

DP.LEN -

Buffer length

+-----------------+

Ref
data
info
v

Reserved
+--------------~--+

ML0-926-87

The function-independent portions of the packets shown above are described in Chapter 1,
Section 1.3 (Request/Reply Packet Interface). The valid function and function-modifier codes
for the function (DP.FUN) field and the valid unit numbers for the unit (DP.UNI) field are listed
at the beginning of this section.
The following sections describe the function-dependent portions of the request and reply packets
for each type of CS driver function.
Note
The MACR0-11 field names shown above do not represent offsets into the user's
send or reply buffers; they are offset symbols used by MACR0-11 drivers to
reference packets. For example, DP .FUN is a 6-byte offset from the packet
header.

12-10 Asynchronous DDCMP Driver

12.4. 1 Enable Protocol and Disable Protocol Functions
The Enable (IF$ENA), Lookup (IF$LOK), and Enter (IF$ENT) functions each cause the timer
process to initialize the protocol for a specified line. If the calling process rather than the
CS driver will time the line, the calling process should issue the IF$ENA request with the
FM$NTR (bit 6 in the function word) set. This disables the sending of "keep-alive" messages at
user-defined intervals by the CS driver.
The Disable (IF$DSA), Close (IF$CLS), and Purge (IF$PRG) functions stop the protocol for the
specified line and wait for the receiver and transmitter to shut down before returning to the
user. The Purge function differs from Disable and Close only in that it causes abort (ES$ABT)
status to be set for any pending 1/0 requests that are returned after the stop action is initiated.
The function-dependent portions of the request and reply packets are not used. You specify the
unit (line) to be enabled or disabled in the unit field (offset DP.UNI) of the request packet.

12.4.2 Read and Write Functions
Read and write functions transfer data to or from a user buffer. If the calling process is using
the CS driver as a component in a higher-level protocol, the data to be received or transmitted
includes control information for higher levels to interpret. Indirect reference pointers are honored
for write requests.
A read request causes a user packet to be placed in the receiver queue for the specified CS serial
line unit.
A write request causes the user request to be assigned a message number and placed in the
transmitter queue for the specified CS serial line unit.
The function-dependent portions of the read and write request and reply packets are shown
below:

- DP.FDD

Not used

ML0-927-87

For a read, the buffer-address and buffer-length fields specify the buffer that will receive data
from the incoming DDCMP message stream for the specified line. The receiver process for
that line interprets the incoming DDCMP messages and locates the data to be handed to the
user. If more data was received from a DDCMP data message than the user requested, an

Asynchronous DDCMP Driver

12-11

overflow (ES$0VF) error is returned, but the requested data length is copied to the buffer and
the actual-length field (offset DP.ALN) of the reply filled appropriately.
For a write, the buffer-address and buffer-length fields specify the location and length of the data
to be transmitted. Alternatively, if function modifier FM$IRP (bit 6 of the function word) is set,
the buffer-address and buffer-length fields point to a table of 3-word data buffer specifications.
Thus, the driver can do gathered writes from many buffers into one DDCMP data message.
The transmitter process for the specified line frames the required DDCMP data messages and
control messages and executes the appropriate DDCMP sequences to send the data.

12.4.3 Get Characteristics Function
The Get Characteristics request returns, in the reply message, codes for DDCMP "device" class
and type.
The function-dependent portions of the Get Characteristics request and reply packets are shown
below:

Type

DP.DAD -

- DP.FDD

: Class

I
I
I
I
I

I
I
I

--1
I
I

1-1
I

Funcde p

value
data

Not
used

Not
v

used

I
I
I

-----------------1

I
I

DP.BUF Ref

data

DP.PAR -

info

DP.LEN -

+-----------------+

In the reply information above:
•

Class is DC$PRL for protocol device class.

•

Type is PR$CDM for asynchronous DDCMP communication.

12-12

Asynchronous DDCMP Driver

ML0-928-87

12.5 Status Codes
If an error is detected during an 1/0 operation by a serial interface device, the asynchronous
line driver, or the CS driver, the CS driver returns an exception code in the status-code (DP.STS)
field of the reply message. If you are performing 1/0 with Pascal 1/0 statements-that is,
not with send/receive statements or Pascal support routine calls-the Pascal OTS will raise the
corresponding exception (unless the operation was an OPEN for which a STATUS return was
specified). If no error is detected during the 1/0 operation, a value of ES$NOR (0) is returned
in the status-code (DP .STS) field.

The CS driver returns the following exception codes:

Code

Type

Description

ES$ABT

HARD_IO

1/0 aborted: user stopped protocol

ES$DAL

HARD_IO

Device already allocated: protocol already started

ES$NXU

HARD_IO

Nonexistent unit: bad unit number

ES$0VF

HARD_IO

Data buffer overflow, data truncated

ES$EOF

SOFT-10

End of file: communication lost

ES$1FN

SOFT-10

Illegal function code

Exception codes are defined in the ESCODE.P AS include file (included by EXC.P AS) for Pascal
users and by the EXMSK$ macro in the COMU/COMM macro libraries for MACR0-11 users.
Note
Not listed above are exception codes for 1/0 errors detected at higher levels
or for kernel- or TT-driver-detected errors that the CS driver raises rather than
passing back to the requesting process.

12.6 CS Driver Prefix File
Figure 12-1 shows the CS driver prefix module. The following paragraphs describe the prefix
file macro calls and symbol definitions that can be edited to fit your application.
The symbols CS$1PR and CS$PPR define the initialization and request-handling software
priorities for the CS driver process.
CS$TMO defines the length of time the driver will wait for a positive acknowledgment (ACK)
of a message before declaring the line down; the default is 60 seconds.
CS$REP defines the interval between REP requests, which are issued to keep the line "alive"
if the calling process is not timing the line. The default is 3 seconds. (REP also initiates error

recovery after an ACK timeout.)
The CSDEV$ macro is invoked once for each serial line unit available to the CS driver. You
specify the TT driver request semaphore name ( <$TTA > ) and a valid TT unit number.
Remember that TT units are numbered sequentially up from 0 in the order they appear in the
TT prefix file, crossing controller boundaries. CS units are also numbered sequentially up from
0 in the order they are defined, independently of the specified TT unit numbers. Note that the
CS and TT unit numbers usually do not match; TTAO is normally off limits to the CS driver

Asynchronous DDCMP Driver 12-13

because of its implicit (default) association with the standard Pascal file variables INPUT and
OUTPUT.
Terminal-oriented functions like flow control (XON/XOFF) and editing must be disabled for the
CS lines; see the TT driver prefix file description in Section 3.8.

12-14

Asynchronous DDCMP Driver

Figure 12-1:

CS Driver Prefix File (CSPFX.MAC)

.title CSPFX - Serial communications driver prefix module
;+

macdf$,misdf$,cspfx$

; User changable symbols for CSDRV
CS$IPR
CS$PPR
CS$TMO
CS$REP

250.
175.
60.
3.

;Initialization priority
;Normal process priority
;Seconds without ACK before declaring line down
;Seconds between REP requests

The definition of the serial line units available to the CSDRV process
Each entry is considered an independent unit number when issuing requests
to the $CSA queue semaphore. This first entry is unit 0 and so
forth. Pascal programs may OPEN these units by including the unit
number in the device specification (e.g. OPEN(f, 'CSA3:');)

Each entry is in the following form:
CSDEV$

QSEM=<ssssss>,UNIT=n

ssssss

is a 6 character, upper case, blank filled device driver
named semaphore enclosed in angle brackets (e.g.
QSEM=<$TTA >). This parameter must be specified, there is
no default.

is the unit number if the device driver is capable of
supporting multiple units. The default is 0 (zero).

These units are normally those defined within the terminal driver prefix
file (e.g. qsem=<$TTA >,unit=1). When defining lines to the
terminal driver for use by CSDRV, you must NOT specify XON/XOFF or
EDITING as you would for lines connected to a terminal. Also
remember that $TTAO: is normally used for the Pascal file variables
INPUT and OUTPUT.
For example:
ttctr$ type=TT$DL, csr=176510, vector=310, hprio=4, nlines=1
ttlin$ ibuf=32., parm1=0. parm2=0, speed=<whatever>
At this time, only lines controlled by the terminal driver are supported.

Asynchronous DDCMP Driver 12-15

CSDEV$
CSDEV$
CSDEV$

qsem=<$TTA >,unit=O
qsem=<$TTA >,unit=1
qsem=<$TTA' >,unit=2

csf in$
.end

;Generate the data structures
;and all done

12-16 Asynchronous DDCMP Driver

;$TTAO is normally INPUT/OUTPUT
;Define CSAO:
;Define CSA1:

Chapter 13
Communication Drivers
This chapter describes the use of the MicroPower/Pascal communication drivers, which support
message-framing and error detection for point-to-point or broadcast communication with external
processors. A communication driver provides the calling process with direct control of the
supported communication device for the purpose of moving data. Typically, these drivers are
used as "data link" drivers (ISO /DNA terminology) by the MicroPower/Pascal network service
process (NSP) or by a user process that implements a communication protocol (for example,
HDLC or X.25 LAPB). The calling process normally provides for guaranteed sequential message
delivery (via message sequencing and retransmission on error) and, in the case of the NSP,
multiplexing of "conversations" (logical links) over a physical link.
The communication drivers support the devices and protocols listed below:

Driver

Supported Devices and Protocols

DEQNA Ethernet interface, Ethernet data link protocol (usable as base for
DECnet)

DPVl 1 synchronous serial line interface, bit-synchronous mode (usable as base
for bit-oriented protocol, such as HDLC or LAPB)

KXTl 1-CA/KXJl l-CA synchronous serial line interface (usable as base for bitoriented protocol)

KXTl 1-CA/KXJll-CA two-port RAM, peripheral processor side of two-port
RAM protocol

KXTl 1-CA/KXJl 1-CA two-port RAM, arbiter side of two-port RAM protocol

The supported devices interface an external processor to a MicroPower/Pascal target processor
so that cooperating processes on the two machines can communicate.
Note
The MicroPower/Pascal definition of "communication driver" leaves out two
communication-related drivers-the asynchronous serial line (TT) driver and
the asynchronous DDCMP (CS) driver. Those drivers support point-to-point

Communication Drivers

13-1

communication via serial line interfaces (DLVll, DHVll, DZVll, DLARTs,
KXTll-CA or KXJll-CA multiprotocol chip).
The TT driver is not considered a communication driver, because it receives
and transmits bytes rather than messages. Nevertheless, it is also usable as a
data link driver within a communication protocol. (See the CS driver.) The TT
driver is addressed in Chapter 3.
The CS driver is considered a protocol driver rather than a communication
driver, because it does not drive a communication hardware device. Rather,
it sends requests to the TT driver, which moves the data through the serial
interface. Like the communication drivers, the CS driver frames messages and
is used by the NSP. However, the CS driver also guarantees sequential message
delivery, which communication protocol drivers nearly always do and which
communication hardware drivers often do not. The CS driver is addressed in
Chapter 12.
MicroPower/Pascal supports three distinct levels of communication device 1/0:
•

MicroPower/Pascal DECnet

•

MicroPower/Pascal Communication

•

Data link level (send/receive) 1/0

Section 13.2 describes each level of communication device access; Table 13-1 summarizes the
possible paths through the communication (and protocol) drivers.

13. 1 Communication Driver Features and Capabilities
The communication drivers support read and write operations, channel enabling or disabling,
and the returning of device characteristics and/ or status. Indirect reference pointers are honored
on write operations for the purpose of performing gathered writes.
Also, the drivers support operations that are specific to the devices or protocols they support.
For driver-specific features and capabilities, see Sections 13.1.1 (Ethernet), 13.1.2 (synchronous
point-to-point), and 13.1.3 (KXTl 1-CA/KXJl 1-CA two-port RAM communication).
All communication drivers can be accessed by the NSP (which normally implies file system
OTS and ACP involvement) in connection with setting up logical links and multiplexing them
across physical links (virtual circuits) for task-to-task 1/0 or by a user process for data link
level (send/receive) 1/0. The KXTll-CA/KXJll-CA two-port RAM drivers have the additional
capability of being opened for Pascal file 1/0 without NSP involvement (for example, an OPEN
of 'KXAO:').

13-2 Communication Drivers

The NSP supports the following combinations of communication (and protocol) drivers:

Drivers

Type of Communication

<-> DECnet

DECnet/Ethernet endnode support for communication between
a MicroPower /Pascal target and another DECnet node-possibly
another MicroPower/Pascal target, a VAXELN target, a VAX/VMS
or RSX system, or other system running DECnet

<-> DECnet

DECnet/ asynchronous DDCMP endnode support for communication between a MicroPower/Pascal target and another DECnet
node-see Chapter 12

<-> CS

Asynchronous point-to-point communication between two MicroPower /Pascal targets-see Chapter 12

XP or XS
KX

<-> XP or XS

<-> KK

Synchronous point-to-point communication between two MicroPower /Pascal targets
Peripheral processor two-port RAM protocol between the MicroPower/Pascal arbiter and MicroPower/Pascal KXTll-CA/KXJllCA

13. 1. 1 Ethernet Communication
The DEQNA (QN) driver provides a standard driver interface to the Ethernet. When used
with the filesystem OTS, the ACP, and the NSP, the QN driver provides an Ethernet base for
Micro Power /Pascal DECnet endnode support.
When used directly via Pascal or MACRO send requests (bypassing the file system, the ACP, and
the NSP), the QN driver provides probabilistic data delivery without the message retransmission
or sequencing of the DECnet protocols. Direct use of the Ethernet requires a firm grasp of
communication protocols. The protocol layered above the Ethernet should include a mechanism
for message acknowledgment and sequencing. (See the remarks accompanying the XP /XS
driver discussion, below.) Also, the Ethernet places a 1500-byte limit on the data portion of
a message frame. Larger data packets should be segmented into smaller frames by the user's
protocol.

Note
The QN driver plays a role, and must be present, if an application is configured
to respond to network requests to trigger reloading of the target (SYSTEM
debug=NO, nettrigger=YES). See Chapter 13 of the MicroPower /Pascal-RSX/VMS
System User's Guide and Section 4.3.11 of the MicroPower/Pascal Run-Time
Services Manual for details on DECnet/Ethernet downline loading.

Communication Drivers 13-3

Ethernet data delivery allows for individual system addressing or broadcast (multicast)
addressing. Each message frame on the Ethernet consists of a destination address, a source
address, a user-defined protocol number, a data portion, and a Frame Check Sequence (FCS),
as follows:

+-----------------+
Destination
node
address
Source
node
address
Protocol type
User

data
Frame Check
Sequence

+-----------------+
ML0-929-87
The basic unit of Ethernet operation is the portal, which is a unique protocol number and a
set of addresses for that protocol. The user of the QN driver issues an Enable Portal request
to identify those parameters and directs the QN driver to deliver incoming messages directed
to the specified addresses and protocol to the user. The QN driver is capable of supporting
multiple concurrent portals, as long as each protocoljaddress list is unique.
The QN driver prefix file (QNPFX.MAC) allows the selection of the maximum number of portals,
the number of receive buffers, and the size of each buffer. The number of and size of each
buffer affect the RAM requirements of the QN driver.

13.1.2 Synchronous Point-to-Point Communication
The XP and XS drivers provide a common user interface to the DPVl l synchronous serial
line controller (XP) and the KXTll-CA/KXJll-CA multiprotocol chip SLU2 Channel A
(XS) for synchronous serial 1/0. Each driver allows you to establish an elementary bitoriented communication channel. The drivers perform the following functions of bit-oriented
communication procedures:
•

Synchronization (flag detection)

•

Transparency (bit stuffing)

•

Invalid frame detection

•

Frame abortion detection

•

Frame Check Sequence (FCS) checking/ calculation

13-4 Communication Drivers

Either driver can be used by user-written software as a component in performing bit-oriented
communication procedures, such as CCITT X.25, ISO HDLC, and others.
The XP and !XS drivers send and receive frames of data and handle modem control for fullduplex channels. Basic HDLC-style framing and error detection are provided. A frame has the
following general format (byte units NOT implied):

+--------+
: Flag
1-------: User
I

I
I
I
I

data

1-------: FCS
1-------: Flag I
+--------+
ML0-930-87
I

Both the leading and trailing flag bytes have the binary value 01111110 with no bit stuffing.
Data sent by the driver has the FCS appended to form a frame. If any errors are detected as
the driver sends the frame, the transmission is aborted and the frame resent. Frames received
by the driver use the embedded FCS to verify the frame; the FCS is then removed. If the FCS
checking indicates that the frame was received in error, or if the frame was aborted or invalid,
the frame is discarded with no indication to the user. Otherwise, the data is returned to the
user.
Because frames that are received in error are discarded, user software must be able to determine
when a frame that was sent has not been received. Typically, a sequence number/timeout
scheme is used for this purpose, as follows:
•

A sequence number is included in the data portion of each frame.

•

As the user software receives each frame, it responds by sending a frame acknowledging
the receipt of the frame with that sequence number.

•

After a period of time, if the originator of a frame determines that no acknowledgment for
that frame has been received, it resends the frame.

13. 1.3 Peripheral Processor Two-Port RAM Communication
The MicroPower /Pascal peripheral processor two-port RAM (KX and KK) drivers together
implement a protocol, operating through the KXTl 1-CA or KXJl 1-CA two-port RAM, for
transfer of data between a Q-bus arbiter processor and any of up to 14KXTl1-CA or KXJl l-CA
peripheral processors. The KX driver resides in the arbiter processor and supports the arbiter
side of the protocol; the KK driver resides in each KXTl 1-CA or KXJl 1-CA and supports the
peripheral processor side of the protocol.
The KX and KK drivers implement the protocol via read and write commands that they issue
to. each other. The drivers perform as many data transfers as necessary to complete a read or
write request. Each KX read or write transfers data between an arbiter buffer and the data area
of a two-port RAM data channel; each KK read or write transfers data between a KXTl 1-CA

Communication Drivers 13-5

or KXJl 1-CA buffer and a two-port RAM channel data area. The drivers operate in full duplex
mode; reads and writes may go on concurrently.
The KX driver supports up to 14 KXTll-CAs or KXJll-CAs running on the Q-bus. The KX
driver communicates with each KXTl 1-CA/KXJl 1-CA and its resident two-port RAM (KK)
driver via the command and status registers of two-port RAM data channels 0 and 1 and their
respective 4- and 12-byte data areas. Each data channel configured in your application-one or
two per KXTll-CA or KXJll-CA-is assigned a unit number by the KX driver for purposes of
communication. Each unit is associated with a unique interrupt to the KX driver to permit fast
communication. The KK driver manages the two data channels of its KXTl 1-CA/KXJl l-CA as
separate units, numbered 0 and 1, respectively.
See Appendix B for a description of the KXTl 1-CA/KXJl 1-CA two-port RAM protocol.

13.2 Performing Communication Device 1/0
For most MicroPower/Pascal applications, communication device 1/0 is performed with the
MicroPower/Pascal DECnet or MicroPower/Pascal communication facilities.
MicroPower/Pascal DECnet is an Ethernet (DEQNA) or asynchronous serial line-based facility
that is compatible with Digital Network Architecture (DNA) products. Using MicroPower/Pascal
DECnet, a MicroPower/Pascal target machine may communicate with processes in other
MicroPower/Pascal targets, with processes in VAXELN targets, or with tasks in VAX/VMS,
RSX, or other systems.
MicroPower/Pascal Communication allows the user to exchange data between processes on
different MicroPower/Pascal target machines, using standard Pascal Input/Output statements.
Note
Transparent remote file access is not supported. One method for transferring
files between systems, using task-to-task data exchange, is noted in Chapter 11.
Both the MicroPower/Pascal DECnet and Communication facilities allow sequential, error-free
data delivery, while hiding the details of data exchange, such as initialization and error recovery.
Both facilities can carry on many task-to-task dialogs across a single physical link. The physical
link is controlled to ensure that there is no "crosstalk" between the multiplexed logical links.
The MicroPower/Pascal DECnet and Communication facilities have the following components:
•

•

The CS driver monitors the data transfer between two MicroPower/Pascal target machines
and performs the appropriate recovery algorithms to correct transmission errors. The CS
driver conforms to the DNA specification for the Digital Data Communications Message
Protocol (DDCMP) and the DECnet Data Link layer. (CS is a protocol driver and does not
control hardware directly; it uses the TT driver to perform lower-level data link functions.
See Chapter 12 for details.)

•

The communication drivers (QN, XP, XS, KX, and KK) control communication device
hardware, performing such data link functions as message framing and error detection.

13-6 Communication Drivers

Both MicroPower/Pascal DECnet and Communication treat task-to-task communication as a
normal input/output device. Programs written to communicate with other tasks use standard
Pascal I/O statements. The data structure controlling access and interpretation of the data
exchanged by the programs is the file variable. The OPEN statement establishes logical links
between both active and passive tasks; the HISTORY and I/O specification arguments to the
OPEN procedure create active and passive links. GET, PUT, READ, and WRITE statements
transfer data over the logical link. EOLN is valid on text files over logical links, and EOF is valid
on any link. CLOSE and PURGE are used to terminate logical links gracefully. Chapter 9 of
the MicroPower /Pascal Language Guide describes the exact syntax of the Pascal I/O statements.
Note
The following applies to KXTl 1-CA/KXJ11-CA two-port RAM communication
only. When multiplexing of logical links over a KXT11-CA/KXJ11-CA two-port
RAM data channel is not necessary, you can eliminate the NSP from your
application and open the data channel by specifying "KXAO:" (for example) in
the OPEN statement. Nonmultiplexing is a special case of MicroPower/Pascal
Communication and applies only to communication and protocol drivers that
allow direct opens-KX, KK, and CS.
For each participating MicroPower/Pascal application, in addition to invoking the Pascal I/O
procedures, you must:
1. Edit the DEVICES configuration macro to reflect the communication controller interrupt
vector addresses; if the QN driver is required, edit the PROCESSOR macro in the system
configuration file to specify a clock argument (for line timing) and edit the DEVICES
configuration macro to reflect the clock interrupt vector addresses
2.

Edit the communication driver prefix file(s) to reflect:
•

Number of controllers

•

[For each controller:] Controller identifier (A, B, ... ), CSR address, interrupt vector
address, and number of controller units (portals for QN, two-port RAM data channels
for KX)

•

Hardware interrupt priority

•

Other interface characteristics, such as the number and size of DEQNA receive buffers,
DEQNA unit (portal) numbers, or XP /XS station address

•

Driver initialization and request-handling process priorities

[For logical link OPEN:] Edit the NSP prefix file to define the communication devices
available to the NSP process. Non-DECnet devices precede a DECnet device, and only one
DECnet device may be specified. Specify TYPE parameter ETHER for DEQNA. For DPV11,
KXT11-CA/KXJ11-CA synchronous, or KXT11-CA/KXJ11-CA two-port RAM, specify type
UPOWER and supply an address (parameters AREA and ADDRESS).

Communication Drivers 13-7

Build into each participating MicroPower/Pascal application the following I/O system
components:
•

Communication driver process

•

[For logical link OPEN:] The NSP

•

[For OPEN:] The ACP

•

Pascal OTS routines for file service-built in automatically by MPBUILD for programs
that invoke Pascal I/O procedures-plus any IJO support routines you opt to include
(see kit files GETSET.PAS and GSINC.PAS)

For more information on setting up your application software for communication device I/O,
see Chapter 4 of the MicroPower/Pascal Run-Time Services Manual, Section 13.7 of this manual,
and the material on building system processes in the MicroPower/Pascal system user's guide
for your host system.
When a module that contains Pascal I/0 procedure invocations is built into your application,
Pascal OTS routines for file service are linked to the module. The OTS file routines perform
all Pascal operations on logical-link or device files, including opening, input, and output. In
particular, they perform the necessary low-level processing of high-level operations such as
OPEN and WRITE. Thus, the basic mechanisms of MicroPower/Pascal I/0-the sending of
request packets to driver or NSP or ACP queue semaphores, the dispatching of interrupts, and
the signaling of reply semaphores-are concealed from the Pascal user.
As alternatives to using the MicroPower/Pascal DECnet or Communication facilities for
communication device IJO, you can:
•

Issue your own Pascal or MACR0-11 packet-level requests to the ACP and an NSP logicallink server (or KXTl 1-CA/KXJl 1-CA two-port RAM driver if no NSP), bypassing the OTS
file routines (lower-level file system access)

•

Issue your own Pascal or MACR0-11 packet-level requests to the drivers, bypassing the
OTS file routines, the ACP, and the NSP (low-level nonfile access); alternatively, existing
applications that require them can invoke Pascal routines that support nonfile access (see
Section 13. 7)

13-8 Communication Drivers

Table 13-1 summarizes the possible paths through the communication (and protocol) drivers.
For reference, the three levels of communication represented are MicroPower/Pascal DECnet,
MicroPower/Pascal Communication, and data link level (send/receive) 1/0.

Table 13-1: Communication 1/0 Paths and Interfaces

1/0 System Components

Interface

Prot

Comm/TT Pascal

MACR0-11

OPEN link

SEND$ to ACP (or NSP
using ACP format)

SEND to
driver

SEND$ to driver
SEND$ to ACP (or NSP
using ACP format)

Type of
Communication

ACP/NSP

DECnet/Ethernet

ACP/NSP

Ethernet (data
link level)
DECnet/DDCMP
or DDCMP
Communication

ACP/NSP

OPEN link

DDCMP non-mux
Communication

ACP

OPEN comm. SEND$ to ACP line

SEND to
driver

SEND$ to driver

XP/XS

OPEN link

SEND$ to ACP (or NSP
using ACP format)

XP/XS

SEND to
driver

SEND$ to driver

SEND$ to ACP (or NSP
using ACP format)

DDCMP (data
link level)
Synchronous
serial
Communication

ACP/NSP

Synchronous
serial (data
link level)
KXTll-CA/
KXJll-CA TPR
Communication

ACP/NSP

KX/KK

OPEN link

KXTll-CA/
KXJll-CA TPR
nonmux
Communication

ACP

KX/KK

OPEN device SEND$ to ACP

KX/KK

Call support

KXTll-CA/
KXJll-CA TPR
(data link level)

SEND$ to driver
routines or
SEND to driver

The following sections describe the Pascal 1/0 statement interfaces to the communication drivers,
the lower-level request/reply packet interface, the status codes that can be returned to users of
any interface, and the communication driver prefix files.

Communication Drivers 13-9

13.3 Pascal 1/0 Procedure Interface
To perform standard Pascal 1/0 to a communication device, you issue an OPEN statement
that associates a file variable with a logical link-or, optionally for the KXTl 1-CA/KXJl 1-CA
two-port RAM, a device channel. The file variable controls access and interpretation of data
as it is exchanged, via the communication device, with a cooperating program on a different
machine. No restriction is placed on the type or contents of the exchanged data, as long as
all is consistent with the method of defining files in Pascal. Programs may use TEXT, FILE
of CHAR, FILE of INTEGER, and so forth when defining the content of the messages passed
between them. Nor must both programs use the same definition.
To accomplish the dialog between tasks, one task must take the role of the initiator, or active
task, while the other defines itself as the target, or passive task. The passive task must define
a name that identifies the task to an active task; the active task specifies the name of the
passive task when initiating the connection. Task names can be up to 16 characters long. When
initiating the connection, the active task must specify the machine containing the passive task it
is attempting to locate. MicroPower/Pascal DECnet will dynamically determine the location of
each named machine. For MicroPower/Pascal Communication, each data channel is associated
with a static name that identifies the machine to which it is connected.
Once the connection between the two tasks is established, the dialog is bidirectional; that is,
either task may WRITE/PUT data to it or READ /GET data from it, and eventually close it,
as if it were a file residing on a local device. The synchronization of data direction is the
responsibility 'of the two programs.
For example, a passive task can issue an OPEN statement of the form:
.

OPEN (fvar, 'SY$NET: "TASK=taskname'" , HISTORY: =NEW) ;

This specifies that the program is initiating a connection to a passive task named "taskname"
located on node "node" that is waiting to accept a connection. The syntax of the OPEN is
compatible with VAX/VMS Pascal syntax for task-to-task communication.
A passive task that is already engaged in a dialog with another task is ineligible to accept
another connection. (A file variable describes exactly one task-to-task dialog.) If you want
multiple active tasks to initiate dialogs with a common passive task, the passive task must, at
the completion of the OPEN statement, spawn another process that issues the identical OPEN
statement. The new task will then be available for subsequent connections.
The preceding discussion of the OPEN statement applies to MicroPower/Pascal DECnet and
to MicroPower/Pascal Communication in the case where several "conversations" are occurring
on the data channel. However, for KXTl 1-CA/KXJl 1-CA two-port RAM communication, if
the data channel is to be used by a single process in one target talking to a single process in
another target, you can avoid the overhead of the NSP process simply by not installing it into
the application image. The two application processes can then OPEN the communication line
direct! y with:
OPEN (filvar, 'ddcu: ' • . . . )

13-10 Communication Drivers

where:
•

filvar is a Pascal file variable.

•

dd is the driver identifier (KX for arbiter side, KK for peripheral processor side).

•

c is a KXTl 1-CA/KXJll-CA identifier (A through N for KX, A for KK).

•

u is a KXTl 1-CA/KXJl 1-CA unit number (0, 1).

For example, 'KXAO:' would specify the first unit (0) of the first KXTl 1-CA/KXJl l-CA (A)
listed in the KX driver prefix file.

Note
Up to two units are supported for each KXTl 1-CA or KXJl 1-CA. KX units are
numbered 0 and 1 in the order that their CSR and vector values are specified
in the KX driver prefix file. KK unit numbers are 0 for data channel 0 and 1 for
data channel 1.
MicroPower/Pascal Communication will place the process in a wait state until the other process
issues a similar OPEN statement, at which time the two processes may begin exchanging data.

Note
The Pascal EOLN procedure is valid for TEXT data exchanged over a logical
link, and the EOF procedure is valid for any link. The CLOSE and PURGE
procedures are used to terminate logical links gracefully.
For examples of data transfer between two MicroPower /Pascal targets or between a
MicroPower/Pascal process and a VMS image, see Chapter 11.

13.4 Request/Reply Packet Interface
The packet-level functions provided by the communication drivers are listed below by symbolic
and decimal function code:

Code

Function

IF$RDP (0)
IF$RDL (1)

Read Physical (equivalent to Read Logical)
Read Logical

IF$WTP (3)
IF$WTL (4)

Write Physical (equivalent to Write Logical)
Write Logical

IF$GET (7)

Get Characteristics

IF$ENA (8)
IF$DSA (9)

Enable
Disable

IF$STP (10)

Stop Requests (DPVll, KXTl 1-CA/KXJll-CA synchronous)

IF$SMD (11)

Set Modem Semaphore (DPVll, KXTl 1-CA/KXJll-CA synchronous)

The DEQNA, DPVll, and KXTll-CA/KXJll-CA synchronous drivers cannot be opened
directly-that is, without NSP involvement-because of the handshakes they perform. If a
request is received for an Open (IF$LOK or IF$ENT), the driver returns an unsupported function

Communication Drivers 13-11

code (ES$UFN). This causes the OTS to raise the exception, provided the OTS/ ACP issued the
Open request and the user's OPEN statement did not specify a status return.
The KXTl 1-CA/KXJl l-CA two-port RAM drivers allow direct opens (for example, an OPEN
of 'KXAO'). If a request is received for an Open (IF$LOK or IF$ENT), an illegal functio11 status
code (ES$1FN), which the ACP (Open) or OTS (Close/Purge) interprets as indicating that no
device-dependent processing was required for that operation.

Note
The MACR0-11 symbols used in this section are defined by the DRVDF$ macro,
w~h resides in the COMU and COMM kernel macro libraries. The equivalent
Pascal symbols are defined in the IOPKTS.PAS include file.
The function modifiers recognized by the communication drivers are shown below by symbolic
code and bit position:
Code

Function

FM$IRP (bit 6)

Indirect reference pointers, perform gathered write (Write Logical)

FM$ANY (bit 6)

Enable promiscuous mode (QN Enable)

FM$RAD (bit 7)

Recognize address (XP or XS Enable)

FM$KRR (bit 6)
FM$KWR (bit 7)

Kill read requests (XP or XS Stop)
Kill write requests (XP or XS Stop)

FM$BSM (bit 13)

Signal binary/ counting semaphore

The QN, XP, XS, and KX drivers each consist of an initialization process, which lowers its
priority to become the first controller's request handler process, plus an additional request
handler process for each configured controller. (If a nonzero timer value is specified in the QN
driver prefix file, the QN driver starts up an internal timer process as well.) 1/0 requests for a
controller are sent (by means of a Pascal SEND or a MACR0-11 SEND$) to the request queue
semaphore waited on by that controller's request handler process.
The KK driver is a single (static) process, beginning as an initialization process and then lowering
its priority to the running level specified in the KK prefix file. 1/0 requests are sent (using a
Pascal SEND or a MACR0-11 SEND$) to the request queue semaphore waited on by the driver
process.

13-12 Communication Drivers

The request queue names and number of supported units for communication driver requests are
shown below:

Driver

Request
Queue Name

Number
of Units

Numbering

DEQNA

$QNc

1-4 (portals)

In prefix file

DPVll

$XPc

KXTll-CA or
KXJll-CA
synchronous

$XSc

KXTll-CA or
KXJl 1-CA TPR

$KXc

1-2

0 and 1 in prefix file order

KXTll-CA or
KXJl 1-CA TPR

$KKA

1-2

0 for channel 0 and 1 for channel 1

The letter c in a queue name represents a controller designation (A, B, ... , as specified in a driver
prefix file). The number of units configured for each controller must be specified in a prefix file.
The general format of the communication device request and reply packets is shown below:

Communication Drivers 13-13

COMM
REQUEST
PACKET

+-----------------+
Standard
·-- packet

+-----------------+
Standard

I
I
I
I
I
I

packet

header

----------------DP.FUN
Function
----------------DP.UNI Unit
----------------DP.SEQ Sequence number
----------------DP.PDB Requesting
process
identifier

header

I
I
I
I
I
I
I
I
I
I

Funeindep
value
data

----------------DP.SEM Reply
semaphore
identifier

----------------DP.FOO Semaphore
structure
ID

----------------Not
used

DP.BUF -

----------------Buffer

DP.PAR -

address

DP.LEN -

----------------Buffer length
+-----------------+

COMM
REPLY
PACKET

driver
v

usage

----------------Type
Class
- DP.FOO
----------------I
I

I
I

Funedep
value
data
v

Reply data

----------------Not used

1----------------1-- Reserved --1
--1
1-+-----------------+ ML0-931-87
I

Ref
data
info
v

I
I
I

I
I

The function-independent portions of the packets shown above are described in Chapter 1,
Section 1.3 (Request/Reply Packet Interface). The valid function and function-modifier codes
for the function (DP.FUN) field and the valid unit numbers for the unit (DP.UNI) field are listed
at the beginning of this section.
The function-dependent portions of the request and reply packets are described in the sections
that follow for each type of communication driver function.
Note
The MACR0-11 field names shown above do not represent offsets into the user's
send or reply buffers; they are offset symbols used by MACR0-11 drivers to
reference packets. For example, DP .FUN is a 6-byte offset from the packet
header.

13-14 Communication Drivers

13.4. 1 DEQNA (QN) Functions
13.4. 1. 1 QN Enable Portal
The Enable Portal (IF$ENA) function initializes a portal and returns a prefix-file-assigned portal
number in the unit field of the reply packet. Once a portal has been enabled, read and write
requests can be issued, using the returned portal (unit) number.
The portal is the basic unit of QN operation. It consists of a unique user-defined protocol number
and a set of 48-bit Ethernet addresses for that protocol. Protocol numbers and addresses are
kept in an active portal list; the addresses are also placed in an address recognition table.
An Enable request specifies the protocol number and the addresses to be enabled for a portal.
If the modifier bit FM$ANY (bit 6 in the function word) is set, promiscuous mode is enabled,
causing the DEQNA driver to return all Ethernet messages without address/protocol checks.
No other portals may be enabled if promiscuous mode is enabled. The function-dependent
portions of the QN Enable request and reply packets are not used for an enable promiscuous
mode request.

For nonpromiscuous Enables, the function-dependent portions of the request and reply packets
are as follows:

DP.DAD

----------------Not used

DP.BUF -

----------------Buff er

DP.PAR -

address

DP.LEN

- DP.FDD
I
I

----------------Buffer length
+-----------------·

Funedep
value
data

Not used

v
Ref
data
info
v
ML0-932-87

Communication Drivers 13-15

The buffer-address and buffer-length fields give the location and length of an address/protocol
buffer, constructed as follows:

+-----------------+
Protocol number
Address count
First
Ethernet
address

1-----------------1
l
nth
:
1---1
:
Ethernet
:
I

1--

--1

address

+-----------------+
ML0-933-87
The maximum number of addresses per portal is currently defined as four. Additionally, the
OEQNA restricts the total number of unique addresses for all portals (that is, the maximum
number of address recognition table entries) to 14. If an Enable request specifies more than
four addresses or causes the recognition table to overflow, an error is returned and the portal is
not enabled.

13.4. 1.2 QN .Read and Write
A DEQNA read (IF$RDL) request for a correctly enabled portal causes a user packet to be
placed in the read queue for the specified portal (unit). Incoming messages from the Ethernet
are checked against the addresses and protocol number currently enabled for the portal. If a
protocoljaddress match is found, the data is copied from the receive buffer to a user-specified
buffer. If no match was found, the message is discarded.
If promiscuous mode is enabled (see the Enable function), read data is copied from the receive
buffer to the user buffer with no protocoljaddress checking.

A write (IF$WTL) request for a correctly enabled portal causes a user-specified buffer to be
transmitted via the DEQNA interface.

13-16 Communication Drivers

The function-dependent portions of the QN read or write request and reply packets are shown
below:

----------------DP.DAD -

I
I
I

I
I

Funedep
value
data

Not used

·----------------- - DP.FDD

:
I

·-'
I
I

,--

Not used

'·-·-'
·----------------'
I
I

----------------DP.BUF Buffer
DP.PAR DP.LEN -

address

----------------Buffer length
+-----------------+

Ref
data
info
v

ML0-934-87

For a read, the buffer-address and buffer-length fields specify the buffer that will receive the
data. After a successful read, the user's buffer contains an Ethernet header (destination, source,
and type) and the Ethernet data, as follows:

+-----------------+
i
Destination
:
,-:
,-I

--,
:
--,
I

node

address

,-----------------,
I
Source
i
I

--,
--,
I

node

I
I

address

I
I
I

-----------------,
Protocol type :
-----------------,
User
I
I

--,
--,

data

I
I

+-----------------+
ML0-935-87
The Frame Check Sequence (FCS) is not returned.
No Ethernet message is returned to more than one read request. If more data was received from
the Ethernet message than the user requested, an overflow error (ES$0VF) is returned, but the
requested data length is copied to the buffer, and the actual-length field (offset DP.ALN) filled
appropriately.
For a write, the data to be written must include the standard Ethernet header, as shown above.
The buffer-address and buffer-length fields specify the location and length of the data buffer.
Alternatively, if write function modifier FM$IRP (bit 6 of the function word) is set, the bufferaddress and buffer-length fields point to a table of 3-word data buffer specifications. Thus, the
driver can do gathered writes from many buffers into one Ethernet packet.

Communication Drivers 13-17

If the source-node-address field for a write is all zeros, the driver automatically fills in the board

address; otherwise, the specified address is used.
If the message to be written is too short, the driver zero-fills the message to the minimum length.

The minimum length of an Ethernet message is 60 (decimal) bytes, including the destination,
source, and protocol fields (14 bytes).
If the DEQNA hardware collision detection/retry logic indicates a failure to transmit the data,

an "unsafe" error (ES$UNS) is returned.

13.4. l .3 QN Get Characteristics
The Get Characteristics request returns codes for device class and type, plus the 48-bit Ethernet
node address of the controller in use.
The function-dependent portions of the QN Get Characteristics request and reply packets are
shown below:
I

-----------------,

DP.DAD -

I
I
I

,-----------------,
Type : Class : - DP.FDD
-----------------,
Controller
:
I

I
I

Funcdep
value
data
Not

--,
--,

board
address

I
I
I
I

-----------------,
Not used
:
-----------------,
I

used

DP.BUF -

I
I

DP.PAR -

I
I

--1

DP.LEN -

Ref
data
info

I
I

+-----------------+

v
ML0-936-87

In the reply information above:
•

Class is DC$COM for communication device class.

•

Type is CM$ETH for Ethernet device type.

13.4. 1.4 QN Disable Portal
The Disable Portal (IF$DSA) function disables a portal and removes the portal's addresses from
the address recognition table.
The function-dependent portions of the QN Disable request and reply packets are not used. You
specify the portal to be disabled in the unit field (offset DP.UNI) of the function-independent
portion of the request packet.

13-18 Communication Drivers

13.4.2 DPV 11 and KXT 11-CA/KXJ 11-CA Synchronous Communication (XP
and XS) Functions
13.4.2. 1 XP or XS Enable and Disable
The XP or XS Enable function turns a line on and readies it for communication. It also enables
interrupts on transitions of modem control signals. (See Section 13.4.2.5.)
If the function modifier FM$RAD (bit 7 in the function word) is set, automatic recognition of the

secondary station address is also enabled. Only messages prefixed with the correct secondary
address reach the user.
The XP or XS Disable function turns a line off and disconnects it from any communication.
Any outstanding 1/0 requests to the line are returned with abort (ES$ABT) status.
The function-dependent portions of the XP or XS Enable and Disable request and reply packets
are not used.

13.4.2.2 XP or XS Read and Write
The XP or XS read function causes the next correctly received frame of data to be passed from
the device to a user-specified buffer.
The XP or XS write function causes a user-supplied buffer of data to be transmitted as a single
frame to the device. If a transmission underflow occurs, the frame is retransmitted.
Because the XP and XS drivers perform bit-oriented communication functions-flag detection, bit
stuffing, invalid frame detection, frame abortion detection, and FCS checking/ calculation-any
frame returned by a read request is a valid frame with a correct FCS and with all bit stuffing
removed. Correspondingly, frames transmitted by the write request have appropriate bit stuffing
and FCS added by the driver.
The indirect reference pointer modifier FM$IRP (bit 6 of the function word) is honored for write
requests. This allows the driver to perform gathered writes from many buffers into one frame.
The function-dependent portions of the XP or XS read and write request and reply packets are
shown below:
I

-----------------·
I

DP.DAD -

Funcdep

Not used

:----------------- - DP.FDD
·-·-- Not used
·-'

•

I
I

value
data

1
I
I

I
I

DP.BUF -

Buff er

DP.PAR -

address

Ref
data
info

Buffer length

DP.LEN -

+-----------------+

,-'
I

:-----------------

ML0-937-87

Communication Drivers 13-19

For a read, the buffer-address and buffer-length fields specify the buffer into which a frame will
be read. The frame returned in the buffer does not include the FCS.
For a write, the buffer-address and buffer-length fields specify the location and length of the
data to be written. Alternatively, if write function modifier FM$IRP is set, the buffer-address
and buffer-length fields point to a table of 3-word data buffer specifications.

13.4.2.3 XP or XS Get Characteristics
The Get Characteristics request returns codes for device class and type, plus bit settings for the
Ring, Carrier Detect, Clear to Send, and Data Set Ready modem controls.
The function-dependent portions of the XP or XS Get Characteristics request and reply packets
are shown below:

----------------DP.DAD -

I
I
I

1----------------- - DP.FDD
: Type : Class
1----------------:
Reserved
1----------------l Line parameter
1----------------:
Not
.
I

I
I

Funedep
value
data

Not

1--

used
DP.BUF -

DP.LEN -

1
I
I

used

1----------------1

DP.PAR

+-----------------+

Ref
data
info
v
ML0-938-87

In· the preceding reply information:
•

Class is DC$COM for communication device class.

•

Type is CM$DPV for DPVll device type, or CM$XSK for KXTl 1-CA/KXJll-CA
synchronous communication device type.

The format of the line parameter is shown below:
15

+-----------------------------------------------+
+-----------------------------------------------+
,..
,..
,..
I
I

I
I

,..

I
I

Ring

+---- Carrier Detect
+------- Clear to Send

+---------- Data Set Ready
ML0-939-87

13-20 Communication Drivers

Bits 0 (Ring) through 3 (Data Set Ready) are modem control bits. Proceeding from right to left
in the format above:
•

Bit 0, if set, indicates a Ring, informing the target processor that an incoming call signal is
being received by the modem.

•

Bit l, if set, indicates Carrier Detect, informing the target processor that the data channel
signal is OK and the receiver is ready.

•

Bit 2, if set, indicates Clear to Send, informing the target processor that the modem is ready
to transmit data.

•

Bit 3, if set, indicates Data Set Ready, informing the target processor that the modem is in
data mode and ready to operate.

13.4.2.4 XP or XS Stop
The XP or XS Stop function causes all pending reads and/or writes to be returned with abort
(ES$ABT) status.
The function-dependent portions of the XP or XS Stop request and reply packets are not used.
You select the type of requests to be stopped by setting the read requests bit (FM$KRR), the
write requests bit (FM$KWR), or both, in the function word of the request packet.

13.4.2.5 XP or XS Set Modem Semaphore
The Set Modem Semaphore (IF$SMO) function specifies the binary or counting semaphore to
be signaled upon each modem interrupt. Modem interrupts are generated when a change in
modem status occurs on a specified line. Modem interrupts are enabled for a line when the line
is enabled. (See Section 13.4.2.1.)
The function-dependent portions of the Set Modem Semaphore request and reply packets are
shown below:
I
I
I

I
I
I

1----------------Semaphore

DP.FDD - :
I

structure
ID

1----------------- - DP.FDD
1

I
I

Funcdep
value
data

I
I

1-1
I

1-1
I
I

Not used

1-1
I
I

1--

DP.BUF -

Not used

I
I

1----------------1
I

Ref
data
info

DP.PAR DP.LEN -

+-----------------+

v
ML0-940-87

The binary or counting semaphore specified at offset DP.FOO is signaled whenever a modem
control interrupt occurs on the line.

Communication Drivers 13-21

The calling program is responsible for issuing a Get Characteristics request to determine the
current status on each signal.

13.4.3 KXT 11-CA/KXJ 11-CA Two-Port RAM (KX and KK) Functions
13.4.3. 1 KX or KK Read and Write
Read and write operations transfer data between a buffer in an arbiter process and a buffer in a
KXTl 1-CA/KXJll-CA process, via a two-port RAM data channel. All transfers are initiated by
the KX driver placing a read or write command in the command register for a user-specified data
channel; however, for the transfer to occur, there must be a matching request queued for that
channel at the KK driver end. In other words, KX writes must be matched by KK reads, and KX
reads must be matched by KK writes. To help synchronize arbiter and KXTl 1-CA/KXJll-CA
transfer requests, the KK driver can interrupt the KX driver when data is available or when data
has been requested at the KXTl 1-CA/KXJl 1-CA end.
The KX and KK drivers operate in full duplex mode; reads and writes may go on concurrently.
The indirect reference pointer modifier FM$IRP (bit 6 of the function word) is honored for write
requests by both drivers. This allows the drivers to perform gathered writes from many buffers
in one request.
The read functions (IF$RDP and IF$RDL) instruct the KX driver to get data from a specified
unit and place it in a user-specified data area. If necessary, the request is held until the
KXTll-CA/KXJll-CA with the specified unit number becomes ready.
The write functions (IF$WTP and IF$WTL) instruct the KX driver to send data to a specified unit
from a user-specified data area. If necessary, the request is held until the KXTl 1-CA/KXJl 1-CA
with the specified unit number becomes ready.
The read functions (IF$RDP and IF$RDL) instruct the KK driver to get data from the two-port
RAM on the Q-bus. The immediate action caused by the request is the setting of a data
requested" bit and the interrupting of the Q-bus, if bus interruption is enabled. The read request
is queued and completes when the arbiter transfers data across the Q-bus to satisfy the request.
The data is placed in a user-specified data area.
/1

The write functions (IF$WTP and IF$WTL) instruct the KK driver to move data from a userspecified area across the Q-bus to the arbiter. The arbiter must issue a corresponding read
request before the request can complete. The immediate action caused by the request is the
setting of a data available" bit and the interrupting of the arbiter, if interruption is enabled.
The request is queued until the arbiter issues a read request to take the data.
/1

13-22 Communication Drivers

The function-dependent portions of the read and write request and reply packets are shown
below:
I

DP.DAD - 1----------------I

1
I
I

Func-

I
I

d ep

1--

1
I
I

- DP.FDD
I
I

1-1

Not used

value
data
I
I
I
I

1-1

1----------------I

DP.BUF -

Buffer

DP.PAR -

address

Ref
data
info

Buffer length

DP.LEN -

+-----------------+

ML0-941-87

For a read, the buffer-address and buffer-length fields specify the buffer into which data will be
read.
For a write, the buffer-address and buffer-length fields specify the location and length of the
data to be written. Alternatively, if write function modifier FM$IRP is set, the buffer-address
and buffer-length fields point to a table of 3-word data buffer specifications.

13.4.3.2 KX or KK Get Characteristics
The Get Characteristics function returns bit settings that indicate the two-port RAM device class
and the two-port RAM driver type in the function-dependent portion of the reply message.
The function-dependent portions of the Get Characteristics request and reply packets are shown
below:

Type

DP.DAD -

I Class

- DP.FDD

Funcde p

value
data

used

Not
I
I
I

.-DP.BUF -

used

I
I

1--

DP.LEN -

I
I

1-1
I

+-----------------+

-----------------1
I

I
I

DP.PAR -

Not

Ref
data
info
v
ML0-943-87

Communication Drivers 13-23

In the information above:
•

Class is DC$COM for communication device class.

•

Type is CM$KXK for arbiter two-port RAM driver, or CM$KKK for peripheral processor
two-port RAM driver.

13.4.3.3 KX or KK Enable and Disable
The KX or KK Enable and Disable requests return with normal status without performing any
channel-related operations.

13.5 Status Codes
If an error is detected by a communication device or driver during an IjO operation, the driver
returns an exception code in the status-code (DP.STS) field of the reply message. If you are

performing I/O with Pascal I/O statements-that is, not with send/receive statements or Pascal
support routine calls-the Pascal OTS raises the corresponding exception (unless the operation
was an OPEN for which a STATUS return was specified). If no error was detected during the
I/O operation, a value of ES$NOR (0) is returned in the status-code field.
The communication drivers return the following exception codes:

Code

Type

Description

ES$ABT

HARD_IO

I/O request canceled by user or aborted by remote node

ES$DAL

HARD_IO

Device already allocated: line already enabled (XP, XS)

ES$IVD

HARD__IO

Invalid data: too many addresses for portal or for address recognition
table (QN)

ES$IVM

HARD_ro

Invalid mode: promiscuous mode already enabled or enabled with
portals active (QN)

ES$NXU

HARD__IO

Nonexistent unit (QN, KX, KK)

ES$0VF

HARD_ro

Data overflow: received data overflows data buffer

ES$UNS

HARD_ro

Unsafe volume: line not enabled (XP, XS); interface not on (KX);
failure to transmit detected by DEQNA (QN)

ES$DCF

SOFT_IQ

Device full: no portals available (QN)

ES$IFN

SOFT_IO

Illegal function code; also used internally by KX and KK drivers to
signal ACP or OTS that no device-dependent processing of an Open,
Close, or Purge was required

ES$IVL

SOFT_IO

Invalid data length specified (QN)

ES$NRF

SOFT_IO

No reference data present

ES$UFN

SOFT_IO

Unsupported function; file open (for example, OPEN of 'QNAO:')
attempted (QN, XP, XS)

Exception codes are defined in the ESCODE.P AS include file (included by EXC.P AS) for Pascal
users and by the EXMSK$ macro in the COMU/COMM macro libraries for MACR0-11 users.

13-24 Communication Drivers

Note
Not listed above are exception codes for 1/0 errors detected at higher levels
or for kernel-detected errors that the communication drivers raise rather than
passing back to the requesting process.

13.6 Communication Driver Prefix Files
Figures 13-1 through 13-5 show the communication driver prefix modules. The following
sections describe the prefix file macro calls and symbol definitions that can be edited to fit your
application.

13.6. l QN Prefix File
The symbols QN$IPR, QN$PPR, and QN$HPR define the initialization and request-handling
software priorities for the Ethernet driver process and the hardware interrupt priority for the
DEQNA controller(s).
The DRVCF$ macro defines the number of DEQNA controllers on the target to be supported by
the driver. The dname field specifies the first two characters of the corresponding request-queue
semaphore name.
The CTRCF$ macro is invoked once for each controller to be serviced. It gives the controller
name, the maximum number of portals, CSR and vector addresses, the number of receive buffers
(in the range 3 to 12), the size of each receive buffer (in the decimal range 256 to 1514), a timer
interval value (10 to 60 seconds in msecs., or 0), and portal unit numbers.

Note
The driver's internal timer process checks at user-specified intervals to determine
if the DEQNA board is operational. This is done to protect against the tendency
of some versions of the DEQNA board to lock up. If no messages have been
received from the board in the specified interval, the timer process assumes
that the board is locked and resets the board (requeuing any transmit that was
pending).
The timer interval is specified via the "timer" value. in the prefix file. DIGITAL
recommends that the interval remain set at 20 seconds (in msecs.) for
applications that use the DEQNA board in a DECnet/Ethernet environment.

Communication Drivers 13-25

Figure 13-1:
.TITLE

DEQNA Driver Prefix File (QNPFX.MAC)
QNPFX - DEQNA Ethernet driver prefix file

drvcf$,ctrcf$

Define the hardware and software priorities associated with the QNA.
QN$IPR
QN$PPR
QN$HPR

250.
175.
4

Initialization priority
Process priority
Hardware priority

3 <= numbufs <= 12.
; 256. <= size <= 1514.
10 seconds <= timer <= 60. seconds
numbuf = 4.
bufsz = 512.
numprt = 3
timer = <20.*1000.>

number of portals available
timer in msecs (20 seconds)

drvcf$ dname=QN, nctrl=1
ctrcf$ ·
cname=A,nunits=numprt,csrvec=<174440,400,numbuf ,bufsz,timer>,units=<0:2>
.END

13.6.2 XP and XS Prefix Files
The symbols Xx$1PR, Xx$PPR, and Xx$HPR define the initialization and request-handling
software priorities for the XP or XS driver process and the hardware interrupt priority for the
DPVll or KXTl 1-CA/KXJll-CA multiprotocol chip serial line channel A controller(s ).
The DRVCF$ macro defines the number of controllers on the target to be supported by the
driver. The dname field specifies the first two characters of the corresponding request-queue
semaphore name.
The CTRCF$ macro is invoked once for each controller to be serviced. It gives the controller
name, number of units (1), CSR and vector addresses, and station address. The unit number is

13-26 Communication Drivers

Figure 13-2:
.TITLE

DPV 11 Driver Prefix File (XPPFX.MAC)
XPPFX

- DPV11 Prefix File

drvcf$, ctrcf$
250.
175.
6

Process initialization priority
; Process running priority
; Hardware priority

dname=XP, nctrl=1
cname=A, nunits=1, csrvec=<160010,500,123>

.end

Communication Drivers 13-27

Figure 13-3:
.TITLE

KXT 11-CA/KXJ 11-CA Synchronous Serial Driver Prefix File (XSPFX.MAC)
XSPFX

- KXT-11 Bit Synchronous Prefix File

drvcf$, ctrcf$
250.
175.
4

Process initialization priority
; Process running priority
; Hardware priority

dname=XS, nctrl=1
cname=A, nunits=1, csrvec=<175700,140,123>

.end

13.6.3 KX and KK Prefix Files
The KX prefix module invokes the DRVCF$ and CTRCF$ macros and assigns hardware and
driver process priorities on the arbiter side.
The DRVCF$ macro specifies the device name (KX) and number of controllers. Each KXTl 1CA/KXJl l-CA on the arbiter is considered to be one controller. Use the nctrl argument of the
DRVCF$ macro to specify the number of KXTll-CA/KXJll-CA boards that are plugged into
the Q-bus.
Use one CTRCF$ macro to configure each KXTl 1-CA or KXJll-CA; you should have parameter
in the DRVCF$ macro. The nunits parameter can have a value of 1 or 2. Unit numbers for
each CTRCF$ macro are allocated, starting at 0, in the order the CSR/vector pairs are given.
The CSR/vector pairs can be specified in any order. The CTRCF$ macro ignores any value
given for the units parameter; specify units= < 0 > .
Note that the specified interrupt vectors must also be specified in the system configuration file,
using the DEVICES macro.
Table 13-2 shows the two-port RAM data channel addresses associated with each KXTllCA/KXJll-CA identification (ID) switch position. Note that for each KXTl 1-CA or KXJll-CA
in your system, you must select an identification switch position that is unique in the system
and either a high or low base address range.

13-28 Communication Drivers

Table 13-2:
KXTll-CA/
KXJll-CA
ID Switch
Position

Two-Port RAM Data Channel Addresses
High-Range Channel
Address Oumper:
In=KXT, Out=KXJ)

Low-Range Channel
Address Oumper:
Out=KXT, In=KXJ)

Channel 0

Channel 1

S T A N D-A L 0 N E

MODE

S T A N D-A L 0 N E

MODE

17762110

17762120

17760110

17760120

17762150

17762160

17760150

17760160

17762210

17762220

17760210

17760220

17762250

17762260

17760250

17760260

17762310

17762320

17760310

17760320

17762350

17762360

17760350

17760360

17777410

17777420

17775410

17775420

17777450

17777460

17775450

17775460

17777510

17777520

17775510

17775520

17777550

17777560

17775550

17775560

17777610

17777620

17775610

17775620

17777650

17777660

17775650

17775660

17777710

17777720

17775710

17775720

17777750

17777760

17775750

17775760

Table 13-3 shows the default ID, CSR address, and interrupt vector values that are supplied in
the KX driver prefix file (as distributed on the MicroPower/Pascal kit). These values assume
low base address ranges for all 14 KXTl 1-CAs or KXJll-CAs (2 through 15).

Table 13-3:

KX Prefix File Defaults

KXTll-CA/
KXJll-CA ID
Switch Position

s
s

0
1

Default
Unit 0
Vector

Default
Unit 0
CSR

Default
Controller
ID ($KXx)

Default
Unit 1
Vector

Default
Unit 1
CSR

160110

500

160120

504

160150

510

160160

514

Communication Drivers 13-29

Table 13-3 (Cont.):

KX Prefix File Defaults

KXTll-CA/
KXJll-CA ID
Switch Position

Default
Controller
ID ($KXx)

Default
Unit 0
CSR

Default
Unit 0
Vector

Default
Unit 1
CSR

Default
Unit 1
Vector

160210

520

160220

524

160250

530

160260

534

160310

540

160320

544

160350

550

160360

554

175410

560

175420

564

175450

570

175460

574

175510

600

175520

604

175550

610

175560

614

175610

620

175620

624

175650

630

175660

634

175710

640

175720

644

175750

650

175760

654

There are no controller or unit parameters to modify in the KK prefix module for the KXTl 1CA/KXJl l -CA side. These parameters are always the same for each KXTl 1-CA or KXJl 1CA-Controller A and units 0 and 1. The CSR for unit -0 is 175010, and the vector is 120;
the CSR for unit 1 is 175020, and the vector is 124. The module defines hardware and driver
process priorities and references the global $KK, which extracts the KK driver from the device
driver library during the application build.

13-30 Communication Drivers

Figure 13-4:
.title

KXT 11-CA/KXJ 11-CA Two-Port RAM Driver Prefix File (KXPFX.MAC)
KXPFX

- KXT11--CA/KXJ11--CA Two port memory device dr~ver

This software is furnished under a license and may be used or copied
only in accordance with the terms of such license.
Copyright (c) 1984, 1986 By Digital Equipment Corporation.
All rights reserved .
. SBTTL

Edit History

Module name:

KXPFX.MAC

System: MicroPower/Pascal Prefix files

.mcall
.mcall
KX$PPR
KX$HPR
KX$IPR
drvcf$
ctrcf $
ctrcf $
ctrcf $
ctrcf $
ctr cf$
ctr cf$
ctr cf$
ctr cf$
ctrcf $
ctr cf$
ctr cf$
ctrcf $
ctrcf$
ctrcf $

drvcf$
ctrcf$
175.
4

250.

Process priority
Hardware priority
Process initialization priority

dname=KX,nctrl=1
cname=A,nunits=2. ,csrvec=<160110,500,160120,504>,units=<O>
cname=B,nunits=2. ,csrvec=<160150,510,160160,514>,units=<O>
cname=C,nunits=2. ,csrvec=<160210,520,160220,524>,units=<O>
cname=D,nunits=2. ,csrvec=<160250,530,160260,534>,units=<O>
cname=E,nunits=2. ,csrvec=<160310,540,160320,544>,units=<O>
cname=F,nunits=2. ,csrvec=<160350,550,160360,554>,units=<O>
cname=G,nunits=2. ,csrvec=<175410,560,175420,564>,units=<O>
cname=H,nunits=2.,csrvec=<175450,570,175460,574>,units=<O>
cname=I,nunits=2.,csrvec=<175510,600,175520,604>,units=<O>
cname=J,nunits=2.,csrvec=<175550,610,175560,614>,units=<O>
cname=K,nunits=2.,csrvec=<175610,620,175620,624>,units=<O>
cname=L,nunits=2.,csrvec=<175650,630,175660;634>,units=<O>
cname=M,nunits=2. ,csrvec=<175710,640,175720,644>,units=<O>
cname=N,nunits=2.,csrvec=<175750,650,175760,654>,units=<O>

.end

Communication Drivers 13-31

Figure 13-5:
.TITLE
MODULE

KXT 11-CA/KXJ 11-CA Two-Port RAM Driver Prefix File (KKPFX.MAC)
KKPFX - KXT11--CA/KXJ11--CA TWO PORT RAM DEVICE DRIVER PREFIX

$KK

== 5
== 250.
== 175 .

Hardware priority
Initialization priority
Process priority

. END

13. 7 Peripheral Processor Communication Support Routines
The following Pascal routines provide a nonfile-oriented interface to the KXTl 1-CA/KXJl 1-CA
two-port RAM data channels:
•

KX_READ_DATA function

•

KX_WRITE_DATA function

•

KK_READ_DATA function

•

KK_WRITE_DATA function
Note
These routines are provided primarily for existing applications (developed with
Version 1 of MicroPower/Pascal) that require them. They perform all packetlevel driver functions except Get Characteristics (IF$GET). A non-file-oriented
Get Characteristics function is provided in the distribution kit file GETSET.PAS.

The following sections describe the Pascal functions for non-file-oriented two-port RAM I/O.
Each function allocates an I/O packet, fills it with information based on the function parameters,
and sends it to the KX or KK driver.
If a reply queue semaphore is specified in the function call, the function returns immediately

after sending the driver request. When the operation is complete, the driver sends a standard
device driver reply via the specified semaphore. (The driver reply is described in Section 13.4.)
The completion status and the actual length returned in the reply packet must be processed by
a routine that is waiting on the semaphore.
If no reply semaphore is provided, the function waits for the two-port RAM driver reply before

returning to the caller.

13-32 Communication Drivers

The following files on the Micro Power /Pascal distribution kit are required for using the functions:
File

Description

KXRWD.PAS

KX function source module

KKRWD.PAS

KK function source module

KXINC.PAS

KX function include file

KKINC.PAS

KK function include file

IOPKTS.PAS

Pascal I/O include file

To use a source module, you must compile it and then merge it with the program at user-process
build time. The associated include files must be included in the program at compile time.
The following data structures, referenced further below, define the KX and KK unit numbers for
this interface:
TYPE
$KX_unit = 0 .. 1;
$KK_unit = 0 .. 1;

See Section 13.4 for more information about KXTl 1-CA/KXJll-CA unit numbers.

13.7. l KX_READ_DATA
The KX_READ_DATA function transfers data from a KXTll-CA/KXJll-CA buffer to an arbiter
buffer and returns a completion-status value of type UNSIGNED. See Section 13.5 for a list of
completion-status values.
The syntax for calling this function is as follows:
KX_READ_DATA ( buffer,length,ret_length,controller,unit,reply,seq_num)

Parameter

Type

Description

VAR buffer

UNIVERSAL

Data buffer

length

UNSIGNED

Buffer length

VAR reLJ.ength

UNSIGNED

Variable that returns number of bytes actually
transferred-not returned if reply parameter provided

controller

CHAR

Optional controller (KXTl 1-CA/KXJl 1-CA) designation letter; default is 'A'

unit

$KX_unit

Optional unit number specifying the unit to send
requests to; default is 0

Communication Drivers 13-33

Parameter

Type

Description

STRUCTURE_DESC_PTR

Optional pointer to initialized reply queue
semaphore descriptor; default is NIL, which
causes function to create necessary semaphore
for user, then deletes it at end of function call

seq_num

UNSIGNED

Optional user-defined word value, returned unmodified in driver reply packet; default is 0 (0 is
returned in reply packet)

The buffer and length parameters specify the location and length of the buffer into which data
will be read.
If no reply parameter is provided, the function sets the parameter ret-1ength to the number of
bytes transferred by the operation. Otherwise, the count of bytes transferred is returned in the
actual-length field of the KX driver reply packet.

13.7.2 KX_WRITE_DATA
The KX_WRITE_DATA function transfers data from an arbiter buffer to a KXTll-CA or KXJllCA buffer and returns a completion-status value of type UNSIGNED. See Section 13.5 for a list
of completion-status values.
The syntax for calling this function is as follows:
KX_WRITE_DATA ( buffer,length,ret_length,controller,unit,reply,seq_num )

Parameter

Type

Description

VAR buffer

UNIVERSAL

Data buffer

length

UNSIGNED

Buffer length

VAR ret-1ength

UNSIGNED

Variable that returns number of bytes actually
transferred-not returned if reply parameter is
provided

controller

CHAR

Optional controller (KXTll-CA/KXJll-CA) designation letter; default is 'A'

unit

$KX_unit

Optional unit number specifying the unit to send
the data to; default is 0

STRUCTURE_DESC_pTR

Optional pointer to initialized reply queue
semaphore descriptor; default is NIL, which
causes function to create necessary semaphore
for user, then delete it at end of function call

seq_num

UNSIGNED

Optional user-defined word value, returned unmodified in driver reply packet; default is 0 (0 is
returned in reply packet)

The buffer and length parameters specify the location and length of the data to be sent through
the dual-port registers.

13-34 Communication Drivers

If no reply parameter is provided, the function sets the parameter reLJ.ength to the number of
bytes transferred by the operation. Otherwise, the count of bytes transferred is returned in the
actual-length field of the KX driver reply packet.

13.7.3 KK_READ_DATA
The KK_READ_DATA function transfers data from the arbiter to a KXTll-CA/KXJll-CA
buffer and returns a completion-status value of type UNSIGNED. See Section 13.5 for a list of
completion-status values.
The syntax for calling this function is as follows:
KK_READ_DATA ( buffer,length,ret_length,unit,reply,seq_num )

Parameter

Type

Description

VAR buffer

UNIVERSAL

Data buffer

length

UNSIGNED

Buffer length

VAR reLJ.ength

UNSIGNED

Variable that returns number of bytes actually
transferred-not returned if reply parameter provided

unit

$KK_unit

Optional unit number specifying unit the request
is to be sent to; default is 0

STRUCTURE_DEsc_pTR

Optional pointer to initiaiized reply queue semaphore
descriptor; default is NIL

seq_num

UNSIGNED

Optional user-defined word value, returned unmodified in driver reply packet; default is 0 (0 is
returned in reply packet)

If no reply parameter is provided, the function sets the parameter reLJ.ength to the number of
bytes transferred by the operation. Otherwise, the count of bytes. transferred is returned in the
actual-length field of the KK driver reply packet.

13.7.4 KK_WRITE_DATA
The KK_WRITE_DATA function transfers data from a KXTll-CA or KXJll-CA buffer to the
arbiter and returns a completion-status value of type UNSIGNED. See Section 13.5 for a list of
completion-status values.
The syntax for calling this function is as follows:
KK_WRITE_DATA ( buffer,length,ret_length,unit,reply,seq_num )

Parameter

Type

Description

VAR buffer

UNIVERSAL

Data buffer

length

UNSIGNED

Buffer length

Communication Drivers 13-35

Parameter

Type

Description

VAR ret-1ength

UNSIGNED

Variable that returns number of bytes actually
transferred-not returned if reply parameter provided

unit

$KK_unit

Optional unit number specifying unit that data is
to be sent to; default is 0

STRUCTURE_DESC_PTR

Optional pointer to initialized reply queue semaphore
descriptor; default is NIL

seq_num

UNSIGNED

Optional user-defined word value, returned unmodified in driver reply packet; default is 0 (0 is
returned in reply packet)

If no reply parameter is provided, the function sets the parameter ret-1ength to the number of
bytes transferred by the operation. Otherwise, the count of bytes transferred is returned in the
actual-length field of the KK driver reply packet.

13-36 Communication Drivers

Chapter 14
Guide to Writing a Device Driver
This chapter explains how to write custom device drivers-device drivers that are not supplied in
your MicroPower/Pascal distribution kit-for use in MicroPower/Pascal applications. DIGITAL
intends to maintain the existing interface between device drivers and the kernel. However,
because of the intimate relationship between the kernel and device drivers, some unavoidable
changes may occur as new features are added to new versions of the MicroPower/Pascal
product. Thus, device drivers written for the current version of MicroPower /Pascal may require
modification for use with later versions.

14. 1 Device Driver Overview
A device driver is a set of processes, routines, and tables that process I/O requests for a hardware
device or device controller. In general, device drivers are restricted to device-specific aspects of
IjO processing; device-independent I/O processing common to other drivers or system services
is performed by other system components.
Device drivers process I/O requests by performing many or all of the following functions:
•

Defining the peripheral device for the system

•

Preparing the device hardware and/ or its controller for operation at system start-up

•

Performing device-dependent I/O preprocessing

•

Translating programmed requests for I/O operations into device-specific hardware commands

•

Activating-starting or enabling-the device

•

Responding to any interrupt requests generated by the device hardware; a device driver can
also poll devices

•

Responding to requests to stop (abort) the I/O operation

•

Reporting device errors to the requesting process

•

Returning completion status-successful completion or error-to the process that requested
the I/O operation

Guide to Writing a Device Driver 14-1

A process requests 1/0 service from a particular device by sending a request packet to the
device driver's request queue. The communication between the requesting process and the
device driver, including request and reply packet formats, is described in detail in Chapter 1.
Interrupt dispatching and interrupt service routines are described in detail in Chapter 7 of the
MicroPower /Pascal Run-Time Services Manual. You must become thoroughly familiar with the
technical material presented in those chapters before attempting to write a device driver.
The global symbol names shown in this chapter have 2-letter device identifiers, which also
appear as part of the module name. (For example, the 2-letter device identifiers shown as xx
are replaced with DY in the RX02 device driver.) DIGITAL reserves the range ZA to ZZ for
customer use. Thus, in order to avoid conflicts, use identifiers in the range ZA to ZZ only for
device drivers that you write.
A dollar sign ($) in the module name identifies the symbol as an address, constant, or macro.
A dollar sign as the first character in the name indicates that the symbol is an address. If the
dollar sign is the third character in the name, the symbol is a constant. If the dollar sign is the
last character in the name, the symbol is a macro.
When adding a custom device driver to your application, you will generally write or edit three
separate source modules:
•

The driver prefix module (xxPFX.MAC or xxPFX.P AS)

•

The driver impure-area definition macro (xxISZ$) or program (if Pascal)

•

The driver proper (xxDRV.MAC or xxDRV.PAS)

Device drivers designed and written by DIGITAL include the three source modules listed above.
The driver prefix module and impure-area definition macro make it easier to modify driver
operations to conform to a particular hardware configuration. However, if the configuration of
your hardware is not likely to change, you can write a device driver without using either the
driver prefix module or the driver impure-area. macro.
When designing and writing device drivers, carefully consider the conventions presented in the
remaining sections of this chapter. DIGITAL discourages the use of kernel interfaces in device
driver designs other than those described in this chapter.
When writing source modules in MACR0-11, follow the sample coding standard contained
in Appendix E of the PDP-11 MACR0-11- Language Reference Manual. Also see the sample
MACR0-11 device driver listed in Appendix D as a guide for designing and writing your
custom device driver.
The remaining sections in this chapter contain specific guidelines for writing each module.

14-2 Guide to Writing a Device Driver

14.2 Device Driver Prefix Module
The device driver prefix module statically allocates the impure area required for the device
driver and defines certain device-specific parameters, such as:
•

Priority values for the driver initialization process, request-handling process, and device
hardware interrupt priority

•

Number of hardware device controllers that the driver must support

•

CSR address for each controller

•

Interrupt vector address for each controller

•

Number of units and unit numbers supported on each controller

The device-specific information is available to the driver in the form of tables of constants and
text.
One device driver prefix module is generally required for each device driver. The module name
has the format xxPFX.MAC (or xxPFX.PAS), where xx identifies the device driver supported by
the module. For example, DYPFX.MAC is the device driver prefix module for DYDRV.MAC,
the RX02 device driver.
A driver prefix module generally contains two or more macro invocations, which you must edit
in order to specify the hardware that is to be supported by the device driver. The specific macros
invoked in the prefix module are the driver configuration macro (DRVCF$) and the controller
configuration macro (CTRCF$), which reside in the COMM and COMU kernel macro libraries.
(Some drivers and driver-related system processes have special requirements and invoke neither
the DRVCF$ nor the CTRCF$ macros; for example, see the TT, CS, and NSP prefix files.)

14.2. 1 Priority Assignments
The driver prefix module defines global symbols for process and hardware priority, as follows:

Parameter

Definition

xx$PPR

Process priority for controller process

xx$HPR

Hardware interrupt priority

xx$IPR

Initialization process priority

DIGITAL recommends an initialization process priority (xx$IPR) of 250 and a controller process
priority (xx$PPR) of 175. Use of those recommended (default) priorities helps avoid unnecessary
context switching in most cases. You can, however, specify higher or lower priorities as the
application requires.
Note
In the current version of MicroPower/Pascal, all initialization procedures in
Pascal processes execute at software process priority 248. The initialization
priorities are currently followed only by DIGITAL-supplied device drivers written
in MACR0-11. This may change in a future release.

Guide to Writing a Device Driver 14-3

Hardware device interrupt requests at levels 4 to 7 are supported only by
LSI-11/23, SBC-11/21, and LSI-11/73 microcomputers. LSI-11 and LSI-11/2
microcomputers support interrupt requests only at level 4. (That is, only bit 7 in
the PSW controls interrupts. When the bit is set, interrupts are disabled; when
the bit is cleared, interrupts are enabled.)
Device hardware interrupt priority relative to two or more devices at the same
interrupt request level is determined by the relative electrical position of each
device along the LSI-11 bus. The device electrically closest to the microcomputer
module receives the highest interrupt priority; similarly, the device farthest from
the microcomputer receives the lowest priority at a particular interrupt request
level.
User processes requesting IjO operations should have priorities less than or equal to those of
drivers unless the application requirements for a high priority process dictate otherwise.

14.2.2 DRVCF$ Macro
DRVCF$, the first macro to be invoked, is the driver configuration macro and specifies the driver
prefix and the number of controllers to be supported by the driver. DRVCF$ defines global
symbols used for configuration. The DRVCF$ macro and its parameters are as follows:
DRVCF$

dname=xx,nctrl=n

Parameter

Definition

2-letter device identifier

Integer specifying the number of controllers that the device driver must support

When executed, DRVCF$ invokes the device driver impure-area definition macro (xxISZ$),
which is device-specific. DRVCF$ directly or indirectly defines the following global symbols:
Parameter

Definition

xx$ISZ

Number of bytes needed for the fixed part of the impure area by a
controller process

xx$SSZ

Number of bytes needed for stack space per controller process, excluding
guard words

xx$USZ

Number of additional bytes needed for each unit supported by the driver

xx$MXU

Maximum number of units that can be supported by a single controller

$xxIMP

Address of the driver impure area

xx$NUM

Number of controllers to be supported in this configuration

$xxPUR

Address of the driver configuration data; DRVCF$ produces the data
structure shown below for the device driver initialization process; names
prefixed with DC. are offsets from $xxPUR

14-4 Guide to Writing a Device Driver

xPUR::

+----------------+
DC.DID
. I
----------------1
DC.PCD
I
----------------1
DC.SSZ
I

DC.NCT
DC.XMU
DC.CID (xxA)

1---------------1
I

I
I
I

1----------------1
I
(xxn)
I
+----------------+
ML0-944-87
I

Name

Definition

DC.DID

2-letter device identifier (xx)

DC.PCD

Pointer to the device driver process-creation data ($xxPCD); label
$xxPCD:: immediately precedes a CRPC$P macro call in the driverproper source (see Section 14.4.4.3); the reference to $xxPCD generated
by DRVCF$ causes the driver to be brought in from the driver object
library

DC.SSZ

Process stack size, in bytes (xx$SSZ)

DC.NCT

Number of controllers supported by a single controller (nctrl)

DC.XMU

Maximum number of units supported by a controller (xx$MXU)

DC.CID

Pointer to the controller A initialization data; additional data words
follow, one for each controller (B, C, ... n), as required

The DRVCF$ macro must always be invoked before the controller configuration macro CTRCF$.

14.2.3 CTRCF$ Macro
Separate invocations of the controller configuration macro (CTRCF$) are required for each
controller supported. Each CTRCF$ macro specifies:
•

The driver prefix

•

The controller code (A, B, C, and so forth)

•

The addresses of the controller's CS Rs and interrupt vectors

•

The numbers of the specific units supported on the controller

•

The hardware type and extra parameters, if used by the driver being configured

Guide to Writing a Device Driver 14-5

The CTRCF$ macro and its parameters are as follows:
CTRCF$ cname,nunits,<csr1,vec1[,csr2,vec2 ... ,csrn,vecn]>,units,
<type1,xprm1[,type2,xprm2 ... ,typen,xprmn]>

Parameter

Definition

cname

1-letter controller identifier

nunits

Integer specifying the number of units that the controller must support

csrl,vecl

CSR address for the first unit and address of the controller's first interrupt
vector

csr2,vec2,
csrn,vecn

Parameter pairs for additional units (2 to n)

units

Angle-bracketed list of integers, specifying the unit numbers of the units
supported on the controller. You can specify unit numbers in one of two
ways. You can enumerate the unit numbers explicitly, separating them
with commas:
nunits=8. ,units=<1,2,3,4,5,6,7,8>

You can also use a colon (:) to indicate a range of unit numbers:
nunits=8.,units=<0,2,7:12>

Note
The units parameter is ignored by some drivers,
which may instead assume a single unit number of
0. The individual driver chapters describe the unit
numbering for each distributed driver.
typel

Asynchronous serial line type (TU58 driver) or JSR buffer size (analog-todigital converter driver) associated with the first CSR; not used by other
standard drivers but available for user-written drivers

xprml

Baud rate (TU58 driver); not used by other standard drivers but available
as extra parameter for the first CSR for user-written drivers

typen

Serial line type (TU58 driver) or other parameter for the nth CSR

xprmn

Baud rate (TU58 driver) or extra parameter for the nth CSR

Note
The type-and-parameter pair is omitted for most
drivers.
The CTRCF$ macro defines the symbols listed below. The xx characters in the symbols represent
a 2-letter device identifier. The letter c in the symbols represents a letter that identifies an
individual controller. (For example, $DYACS is the correct symbol for the CSR address for the
RX02, controller A.)

14-6 Guide to Writing a Device Driver

Parameter

Definition

$xxcG1

Address of the low stack guard word for controller c

$xxcG2

Address of the high stack guard word for controller c

$xxcIM

Address of the impure area for controller c

$xxcPU

Address of the pure-code configuration data for controller c

$xxcCS

CSR address for controller c

$xxcVE

Interrupt vector address for controller c

CTRCF$ produces the data structure shown below for the device driver initialization process.
Names prefixed with CC. are offsets from $xxcPU.

+----------------+
CC.IMP
i
1----------------1
CC.ISZ
----------------1
CC.PCS
+--<-----------------1
CC.NUN
l
----------------1
CC.USP
----------------1

$xxcPU::

I
I
I

csrvec: +---->

csr1
vec1

csrn
vecn
typrm:

----->

type1
xprm1

I
I
I

1----------------1
:
typen
:
1----------------1
:
xprmn
i
+----------------+
ML0-945-87

Guide to Writing a Device Driver 14-7

Name

Definition

CC.IMP

Address of the impure area for controller c ($xxcIM)

CC.ISZ

Number of bytes in the impure area for controller c (impsiz)

CC.PCS

Pointer to the CSR/vector-pair list (csrvec)

CC.NUN

Number of units supported by controller c (nunits)

CC.USP

Specification of the unit numbers supported by the controller; a list of integers
separated by commas or colons and terminated by a zero byte; a pair of integers
separated by a colon represents a range of unit numbers-for example, 2:4
specifies units 2, 3, and 4

csrvec

A series of word pairs containing the CSR address and vector address for each
unit

typrm

A series of word pairs containing extra parameters for each unit-zero if not
used by the driver being configured; among the standard drivers, only the TU58
and analog-to-digital converter drivers use typrm

CTRCF$ generates the controller impure area, as follows:
$xxcIM::
.blkb
.even
.blkw
.blkb
.blkw

$xxcG1::
$xxcG2::

xx$ISZ

Impure area

xx$SSZ

Low stack guard word
Stack space
High stack guard word

The symbols xx$ISZ and xx$SSZ are defined by the impure-area definition macro, xxISZ$, which
is invoked by the DRVCF$ macro. See Sections 14.2.2 and 14.3 for more information.

14.2.4 Sample Driver Prefix Module (DYPFX.MAC)
The following is an example of a driver prefix module .
. NLIST
.ENABL
.LIST
.TITLE

DYPFX

- RX02 Prefix File

drvcf$, ctrcf$

DY$IPR
DY$PPR
DY$HPR

250.
175.
5

drvcf $
ctrcf $
ctrcf $

Process initialization priority
Process priority
RX02 hardware priority

dname=DY,nctrl=1
cname=A,nunits=2. ,csrvec=<177170,264>,units=<0:1>
cname=B,nunits=2. ,csrvec=<177200,270>,units=<0,1>

.end

14-8 Guide to Writing a Device Driver

14.3 Device Driver Impure-Area Definition Macro (xxlSZ$)
The device driver impure-area definition macro defines configuration parameters required by the
device driver prefix module. When adding a custom device driver to the system, build a roacro
library with the device driver impure-area definition macro in it, for use during assembly of the
driver and prefix files. (The impure-area definition macros for the standard device drivers reside
in the COMU and COMM macro libraries.) The macro should include the following parameters:
Parameter

Definition

xx$ISZ

Number of bytes needed for the fixed part of the impure area by a
controller process

xx$SSZ

Number of bytes needed for stack space per controller process
Note
Process stack size requirements depend on whether
the system is mapped or unmapped. The symbol
$MINST defines the minimum process stack sizethe number of bytes on the process stack required
by the kernel for its own use.
The value of
$MINST is larger for unmapped systems than for
mapped systems. Processes can make optimum use
of memory by defining process stack requirements
in terms of $MINST (defined in the MISDF$ macro).
For example:
mxx$SSZ = $MINST+n

In the example above, n is the number of bytes on the process
stack needed by the process itself.
xx$USZ

Number of additional bytes needed for each unit supported by the driver

xx$MXU

Maximum number of units that can be supported by a single controller

You obtain the values for the symbols xx$ISZ and xx$USZ from the assembly listing of the
driver proper. When these values change through program modification, edit the xxISZ$ macro
to reflect the changes.
The DY driver impure-area definition macro, DYISZ$, defines configuration parameters as
follows:

Guide to Writing a Device Driver 14-9

.MACRO
.if
.endc
.MACRO
DY$USZ
DY$SSZ
DY$ISZ
DY$MXU
. ENDM
.IF

DYISZ$ range=nogbl
NDF $MINST
.mcall MISDF$
misdf $
DRVR .. X
='X 0
='X $MINST+110
='X 112
='X 2
DRVR ..
.dsabl LC
IDN <range>,<GLOBAL>
drvr .. <=>

.!FF
drvr .. <>
.ENDC
.ENDM

.enabl LC
DYISZ$

14.4 Device Driver Proper
The device driver proper is the device driver source module. (The device driver prefix module
and the impure-area definition macro previously described provide configuration information
required by the driver proper.) The following paragraphs describe the composition of the device
driver source module.
By convention, a device driver source has a file name of the form xxDRV.MAC. In general,
device drivers supplied by DIGITAL in the MicroPower/Pascal distribution kit conform to
MicroPower/Pascal and MACR0-11 coding conventions. You can use the RX02 device driver
MACR0-11 source file, DYDRV.MAC, as an example when you write device drivers in MACR011; a listing of DYDRV.MAC is in Appendix D.
When writing device drivers in Pascal, refer to the YADRV.PAS source code for the DRVll
device driver; YADRV.P AS and its prefix file, YAPFX.P AS, are included on the distribution kit.
A device driver written in MACR0-11 is divided into several discrete sections:
•

•

Module header

•

Functional description

•

Local macro definitions

•

Externally defined symbol defaults

•

Private and/ or local data and symbol definitions, including:
Impure area common to all copies of the driver
Pure data tables

•

An initialization process that creates the required data structures, initializes impure areas,
and starts the controller processes

•

An impure area that contains state information for the controller processes

14-10 Guide to Writing a Device Driver

•
•

A constant data area that contains constants and tables

•

One or more interrupt service routines that respond to interrupts from the device

•

One or more fork routines that signal the controller processes when the device requires
further attention

•

A reply routine that returns completion status-successful completion or error code-to the
process that requested the 1/0 operation

•

A termination procedure that deallocates owned resources previously obtained by the
controller process before deleting the controller process

•

Error-processing routines that:

One or more controller processes that wait for 1/0 requests, activate the device, and wait
for a response or a timeout

Retry on recoverable errors
Report nonrecoverable errors to the requesting process
Return to the pool 1/0 request packets that cannot be returned to the requester
Driver components are discussed in detail in the following sections.

14.4. 1 Copyright Page
Although optional, the copyright page is recommended if your source module distribution is to
be controlled or if it contains proprietary information. Refer to source files contained in your
MicroPower/Pascal distribution kit for examples of DIGITAL's copyright statement. Refer to
your legal consultant for the wording of your own copyright statement.
At the top of the copyright page-first entry in the source module-include .title and .ident
directives. These direct MACR0-11 to place correct headings at the top of each assembly listing
page, including source module name and version. For example:
.title

xxDRV.MAC - Widget driver

.ident

/V02.00/

All information, except the .title and .ident directives, is in the form of comments. That is, each
line of text is preceded by a semicolon (;).

14.4.2 Module Header
The module header contains the module name-for example, xxDRV.MAC-system, or
application, name, author, creation date, and a brief history of source modifications. Although
the information contained in the module header is optional, it is a convenient place to track
changes to the source module during the development cycle.

14.4.3 Functional Description
The functional description is also optional. All information in this section is in the form of
comment lines. This section contains documentation on how other modules interface with the
driver as 1/0 requests are processed and any other design interface information needed for
using the device driver in an application.

Guide to Writing a Device Driver 14-11

14.4.4 Declarations
Declarations include system macro requirements, local macro definitions, external symbol
definitions-global symbols defined in the driver prefix module-and local symbol definitions,
as required. The following sections describe the declarations.

14.4.4. 1 Local Macro Definition
This section contains all macro definitions for local macros referenced by the device driver.
(Local macros are referenced only by the device driver proper.)

14.4.4.2 Externally Defined Symbols
The section of externally defined symbols may include symbols containing default values. You
need the macros listed when assembling the devic~ driver module. Default values for the
macros can be changed, as required, by device driver code. For example, a macro may state
the number of retries for read request processing. The particular device driver may also process
read-with-no-retries requests, requiring the default value modification.

14.4.4.3 Process Definition
The device driver source must define the controller A process as a static process and, if multiple
controllers are supported, request a dynamic process. Defining controller A as a static process is
done by issuing the DFSPC$ kernel primitive (described in Chapter 3 of the MicroPower /Pascal
Run-Time Services Manual). All parameters except ini are required. The following example is
the process definition for the DY device driver:
DFSPC$ pid=$DYADR,pri=DY$IPR,cxo=O,typ=PT.DRV,grp=1,ter=DYSTP,
cxl=O,sti=$DYAG2,stl=$DYAG1,sth=$DYAG2,start=DYINIT,ini=O

14-12

Guide to Writing a Device Driver

Parameter

Definition

pid

$DYADR, the name of the static process (DY di:iver, controller A)

pri

DY$IPR, the initialization-process priority specified in the driver prefix
module

cxo

0-no predefined bit-mask symbols defining hardware context

typ

PT.DRY, indicating device driver (DRIVER) mapping

grp

1, the exception-handling group code of which the process is a member

ter

DYSTP, the DY device driver termination routine entry point

cxl

0 (null parameter)

sti

$DYAG2, the address of the high guard word for the stack; the address
loaded into the SP when the process starts

stl

$DYAG1, the address of the low stack guard word; specifies the lower
boundary of the stack

sth

$DYAG2, the address of the high stack guard word; specifies the upper
boundary of the stack definition macro, DYISZ$

start

DYINIT, the initialization-process entry address

ini

0 (null parameter)

The driver must request a dynamic process if the device driver supports multiple controllers and
if the common device driver initialization routine $DDINI is used in the driver's initialization
process. You request a dynamic process by issuing the CRPC$P kernel primitive (described in
Chapter 3 of the MicroPower /Pascal Run-Time Services Manual), immediately preceded by the
label $xxPCD::. The following example is the dynamic process request for the DY device driver:
$DYPCD::
CRPC$P pdb=PDB,pri=DY$PPR,cxo=O,grp=1,ter=DYSTP,cxl=O,sti=O,
stl=O,sth=O,start=DYSTRT,ini=O

Parameter

Definition

pdb

PDB, the argument block address

pri

DY$PPR, the controller process priority specified in the driver prefix
module

cxo

0-no predefined bit-mask symbols defining hardware context

grp

1, the exception-handling group code of which the process is a member

ter

DYSTP, the entry point for the termination routine

cxl

0 (null parameter)

sti

0 (no source of initial stack address specified); $DDINI will supply the
proper value for this parameter

Guide to Writing a Device Driver 14-13

Parameter

Definition

stl

0 (no source of low boundary address of process stack); $DDINI will
supply a value for this parameter

sth

0 (no source of high boundary address of process stack); $DDINI will
supply a value for this parameter

start

DYSTRT, the controller process entry address-typically the address
immediately following the $DDINI call

ini

0 (null parameter)

A reference to $DYPCD:: is generated by the DRVCF$ macro in the DY driver prefix file;
that reference causes the DY driver to be brought in from the driver object library during the
application build. See the DRVCF$ macro description in Section 14.2.2.
Sections 14.4.5 and 15.2.3 describe the $DDINI subroutine.

14.4.4.4 Impure-Area Definition
The impure area is the writable data area for the device driver. Each copy of the controller
process has its own impure area. Additional space may be allocated in a section according to
the number of drivers supported by the controller process. You can see typical contents of the
impure area by examining the DY device driver source. Note that the request semaphore SDB
is the first item in the impure area and that the ISR impure area is also contained within the
impure-area definition.

14.4.4.5 Pure-Area Definition
The pure-area definition is a read-only area that is shared by all driver processes. This area
typically contains text, tables, and data that never require modification. In a mapped system,
the protection for this area is read-only. For example, in the DY device driver, this area includes
a function-code verification table, a device characteristics table, and a table of error-return codes
common to all controller processes.

14.4.5 Initialization Process
The initialization process typically creates one or more queue semaphores (by which the
requesting processes communicate with the device driver), starts the driver processes for each
controller, and initializes the impure area. The driver initialization process is a statically-defined
process that executes at very high priority at start-up time. Priority value 250 (decimal) is
recommended for start-up initialization. A range of priorities permits specific initialization
processes to execute before others, as required.
A common device driver initialization routine, $DDINI, simplifies initialization-process coding for
drivers written in MACR0-11. (See Section 15.2.3.) This routine creates the queue semaphore
for each controller process and clears the controller process impure area; $DDINI creates the
queue semaphore structure descriptor block for controller $xxc in the first 12 bytes of the impure
area. If there are multiple controllers in the application, $DDINI creates additional copies of
the controller process as needed.

14-14

Guide to Writing a Device Driver

For example, the initialization procedure in the DY device driver performs its functions by
calling the $DDINI routine. The required input data is contained in $DYPUR and a pointer to
$DYPUR is passed in RS. ($DYPUR is as described in Section 14.2.2.)
DYINIT: MOV
CALL

#$DYPUR,R5
$DDINI

-> Configuration data for RX02
; Common device driver initialization
; routine

[Subtitle and comments omitted -- see Appendix D]
DYSTRT:

$DDINI exits with the stack containing the controller ID and pointers to the impure area and
initialization data, as shown in Section 15.2.3. The controller processes, normally entered
immediately following $DDINI execution, must, immediately on entry, remove this controllerspecific information from the stack for use by the driver code.

14.4.6 Controller Process
The controller process performs the following functions:

•
•
•

Initiates the I/O functions

•

Waits for I/O completion or device timeout and returns status to the requester

Reads driver requests
Validates the requests

There is usually at least one controller process executing for each controller.
You can save some memory by having the initialization process become the controller process
rather than create a copy of the driver process. This is done by lowering the process priority
to that of the controller process. In the case of multiple driver processes, the initialization
process becomes the first driver process and creates copies for each additional process. ($DDINI
performs this function.)
The DY device driver controller process includes several routines and subroutines that prepare
the driver for I/O, receive and validate I/O requests (queue server), and execute the I/O
requests. An overview of the major routines and their functions is provided below.
The DY driver controller process entry point is DYSTRT. Upon entry, the controller process
removes and saves the pointers passed by $DDINI; however, it discards the controller ID. The
controller process then creates an unnamed binary semaphore that will connect the driver's ISR
to the I/O request service process. and will connect the interrupt vector to the ISR.
The DYREQ (Request Process Queue Server) routine and three subroutines-DOREQ (Verify and
Begin Request), DYTRAN (Start Transfer or Retry), and DYDONE (Finish Processing Request)contain the device driver's main request-processing code. Those routines perform the following
functions:
•

Sets up retry count for request

•

Validates unit number specified in request; returns an error message if invalid

•

Checks function code specified in request; returns an error message if invalid

•

Copies device characteristics to the queue element for message returned to the process
requesting the I/O operation

Guide to Writing a Device Driver 14-15

•

Performs device-specific operations and calls the interrupt procedure (subroutine)

•

Returns an appropriate completion status message to the process requesting the 1/0
operation once the 1/0 operation is completed

Other subroutines include: INWAIT (Start Function and Wait for Interrupt from Floppy), DOSILO
(Initiate Silo Fill or Empty Command), DOXFER (Start Sector Read or Write), DYDOFN (Start
Transfer or Silo Operation), DYERR (Error Handler), and REPLY (Return Status Message). (The
DY driver's ISR routine and termination procedure are described in Sections 14.4.7 and 14.4.10,
respectively.) Those routines are called, as appropriate, when processing read, write, and other
operations with the RX02 hardware.

14.4. 7 Interrupt Service Routine (ISR)
This section gives a brief overview of the interrupt service routine (ISR). A more detailed
description of interrupts, kernel interrupt dispatching, and the JSR is provided in Chapter 7 of
the MicroPower/Pascal Run-Time Services Manual. Carefully read that chapter before designing
or writing ISRs.
Interrupt service routines process the interrupt requests issued by the device hardware. ISRs
have the following characteristics:
•

Very limited con text

•

Very brief execution periods

•

Restricted processing capabilities

In a mapped system, the mapping of an JSR uses the kernel PARs and is designed to be very
fast. Kernel P ARs 2 and 3 are saved and then set up to map the driver /ISR code and data.
The rest of the mapping context is that of the kernel-the 1/0 page (PAR 7), system common
(PARs 4 through 6, as required), and the kernel code (PARs 0 and 1). See the ISR mapping
diagram in Chapter 2 of the MicroPower /Pascal Run-Time Services Manual.
To map the ISR code and data via kernel PARs 2 (code) and 3 (data), specify PT.DRV (driver
process mapping) for the TYP parameter in the DFSPC$ macro invocation (see Section 14.4.4.3).
At application-build time, relocate the driver/JSR code and data virtual addresses to fall within
the PAR 2 and PAR 3 address ranges, respectively. You do this by specifying the /0:40000/X
(RT host) or /R0:40000 /AL (RSX/VMS host) option in the RELOC utility command string.
(See the MicroPower /Pascal-RT System User's Guide or the MicroPower /Pascal-RSX/VMS System
User's Guide for a detailed explanation of RELOC utility options.)
Note
The preceding paragraph assumes that the driver process size does not exceed
BK words. As long as the process does not exceed BK words, the driver and ISR
can be mapped according to the driver /ISR mapping conventions outlined in
Chapter 2 of the MicroPower/Pascal Run-Time Services Manual, and a non-PIC
(faster-executing) ISR can be used. DIGITAL recommends that you follow the
driver/JSR mapping conventions if at all possible. When the driver size exceeds
BK words, you must use device-access or privileged-process mapping for the
driver process, and the ISR must be PIC.

14-16 Guide to Writing a Device Driver

When an ISR is called, the kernel sets the CPU priority to the value specified in the CINT$
primitive issued by the device driver. Since other interrupts at this level and lower cannot
occur during interrupt-level processing, the amount of time spent executing ISR code must be
minimized.
Before issuing any kernel primitive, the ISR must go to fork-level processing. This is done by
issuing a FORK$ call. Once the ISR is at fork level, the CPU priority is set to 0, permitting
other interrupts to be serviced.
A very brief ISR is contained in the DY device driver ($DYINT). Upon entry, the ISR immediately
issues a FORK$ request. Once at fork level, the ISR restores registers, checks for errors, and
JMPs the routine that initiated the RX02 function. Since the RX02 is a DMA device, all data
transfers have been completed, and the interrupt simply informs the device driver of that fact.
The DY driver is listed in Appendix D.
Other device drivers require more extensive ISRs. A more extensive ISR might perform 1/0 or
queue operations internally.

1.4.4. 8 Fork Routine
An ISR issues a FORK$ call to exit processing at interrupt level and to enter fork-level processing
whenever the ISR must issue a kernel primitive request-for example, in order to signal the
controller process. Kernel primitives cannot be issued at interrupt level.
The code following the FORK$ call is the fork routine and is generally shown as part of the
ISR. When at fork level, the fork routine continues execution with ISR mapping, but at a CPU
priority of 0; thus, other interrupts, including lower-priority interrupts, can be serviced. Only
ISR routines, interrupted kernel primitive execution, and other fork routines are executed at fork
level; all fork routines are completed before returning to the interrupted process level.

14.4. 9 Reply Subroutine
The reply subroutine returns completion status to the process that requested the I/O operation.
Status indicates either successful completion or an appropriate error code. DIGITAL supplies the
$DRPLY (Send Device Driver Reply) subroutine, described in Section 15.2.8, for that purpose.
The caller of the reply subroutine inserts the status code, error code, and byte count (actual
length) involved in the I/O operation in the reply queue element (message packet). If this is
deferred until just before the reply, the driver can modify the original request packet and return
it as a reply packet-rather than allocating a separate reply packet.
Upon entry, the reply subroutine should receive a pointer to the message packet.
The DY driver REPLY (Return Status Message) routine sets up and executes a call to the $DRPLY
subroutine.

Guide to Writing a Device Driver 14-17

14.4. 1O Termination Procedure
Each device driver includes a termination procedure that is entered whenever the device driver
is stopped (aborted). The termination procedure deallocates, in an orderly manner, all resources
that the driver had previously acquired. The termination procedure performs the following
functions:
Disables interrupts on the appropriate controller hardware

•

Cancels any active timeout requests

•

Returns all outstanding requests to the requesting process with abort status, if possible;
otherwise, the termination procedure returns the request packet(s) to the kernel pool

•
•
•

Destroys all structures created by the driver
Deletes all processes created by the driver
Deletes the driver controller process

For an example of a termination procedure, refer to the DY driver DYSTP (Request Process
Termination) routine. DYSTP disables interrupts, returns abort status to waiting processes,
deletes all structures, and finally deletes the driver process.

14.4. 11 Error-Processing Routines
The driver processes several categories of errors, as follows:
•

Invalid request packets

•

Exceptions (traps-memory timeouts, illegal instructions, and so forth)

•

Drive or controller hardware errors

•

Resource famine (insufficient kernel pool to allocate structures, and so forth)

14.4. 11. 1 Invalid Requests
Drivers are responsible for validating I/O request packets as completely as possible. Processing
an invalid request as though it were valid can corrupt a system; every attempt must be made
to prevent that from happening. If possible, the driver returns the invalid packet to the sender.

14.4. 11.2 Exceptions
Exceptions are memory timeouts, illegal instructions, traps, and so forth, as follows:
•

Invalid parameters in the 1/0 request packet-for example, a request to write into read-only
memory or a request to access nonexistent memory

•

One or more programming errors in the device driver

•

A hardware failure-CPU error, memory error, or controller error

•

Nonexistent hardware

14-18 Guide to Writing a Device Driver

Device drivers must validate all the I/O request packets to prevent exceptions caused by
invalid parameters. Thorough testing will minimize exceptions caused by programming errors.
Hardware errors should be anticipated so their occurrence does not cause unexpected run-time
errors that corrupt memory contents or produce other unpredictable results. The deviceinitialization process must detect exceptions caused by nonexistent hardware in order to avoid
unexpected run-time errors.
Applications should include exception handlers for all types of exceptions that may be caused
by the processing of bad data in a request packet. For example, if an incorrect address supplied
in the request packet causes the driver to generate a memory fault (trap to 4), the driver should
provide a memory fault exception handler for the problem. (Exception handling and dispatching
are discussed in Chapter 6 of the MicroPower /Pascal Run-Time Services Manual.)

14.4. 11.3 Drive or Controller Errors
Drive or controller errors can be either recoverable or nonrecoverable. In the case of recoverable
errors, the device driver should retry eight times before considering the error nonrecoverable,
unless the requesting process has specified in the I/O request packet that retries are disabled.
In the case of nonrecoverable errors, the device driver returns an appropriate error status to the
requesting process.

14.4. 11.4 Resource Famine
If a standard device driver or the common initialization routine $DDINI cannot obtain enough
memory to create a process or structure, it reports an exception by calling the common exceptionreporting routine $DDEXC (see Section 15.2.2), which issues an $REXC kernel primitive request.
Resource famine errors should occur only during the debugging stages of application program
development.

Guide to Writing a Device Driver 14-19

Chapter 15
Device Driver Macros and Subroutines
This chapter describes macros and subroutines that can be used by device drivers written in
MACR0-11.

15. l Driver Macros
The following driver macros are available from the kernel macro libraries COMM and COMU
for the use of user-written device drivers:
Macro

Description

ADP AR$

Accept virtual address and return the address of corresponding kernel
PAR

DRMAP$

Remap Virtual Address

DRPAR$

Read Contents of PAR or PDR Register

DRVDF$

Define Driver Packet Symbols

DSCXW$

Disable MMU Context Switch

DWP AR$

Write to PAR or PDR Register

ENCXW$

Enable MMU Context Switch

IBADR$

Increment Byte Address and Check for PAR Tick Overflow

IWADR$

Increment Word Address and Check for PAR Tick Overflow

MVBYT$

Move Byte from/to Virtual Addresses

MVBYU$

Move Byte from/to Virtual Addresses from user-mode

MVMAP$

Move Word from/to Virtual Addresses in mapped case only

MVVAD$

Move Address and PAR

Device Driver Macros and Subroutines 15-1

Macro,

Description

MVWRD$

Move Word from/ to Virtual Addresses

MVWRU$

Move Word from/to Virtual Addresses from user-mode

SPL$

Set Priority Level

XTAD$

Compute Bus Extended Address

To use a driver macro, you list the macro name in an .MCALL statement in your driver source
file and then invoke the macro in accordance with the syntax shown in this chapter. In addition,
if you assemble the driver by manually invoking the assembler (rather than letting MPBUILD
do it for you), you must include in the assembler command line the COMM or COMU macro
library and the appropriate qualifier (for example, "/ML").
The purpose of many of the driver macros is to allow a driver to be written for both mapped
and unmapped systems without conditional assembly. Where the mapped (COMM) versions
of the macros generate code that manipulates virtual addresses and PAR values, the unmapped
(COMU) versions generate shorter code sequences, with no PAR references, or no code at all.

Note
Driver prefix file macros and system configuration macros are not included in
this section. The driver prefix file macros, such as DRVCF$ and CTRCF$,
are described in Chapter 14. The system configuration macros, including the
driver-related DEVICES macro, are described in the MicroPower /Pascal Run-Time

Services Manual.

15-2

Device Driver Macros and Subroutines

15. 1. 1 ADPAR$ (Return PAR Address)
The ADP AR$ macro accepts a virtual address and returns the address of the corresponding
kernel PAR. This macro may be useful if you want the driver to treat part of the request packet
as a standard user buffer (with a virtual address and a PAR value) in common driver code. You
can use either the kernel PAR or the driver PAR because the request packet is in the kernel
impure area.
Syntax
ADPAR$ viradr,paradr

Parameter

Definition

viradr

The virtual address you enter. This argument has the form:
[1TIRADR=]virtual-address

paradr

The location to receive the PAR address. This argument has the form:
[PARADR=]PAR address

Semantics
In the mapped case, the ADP AR$ macro generates:
MOV
MOV
ASH

RO,-(SP)
viradr,RO
#-13. ,RO

BIC

rc7,RO
RO

ASL
ADD
MOV
MOV

#K.ISAO,RO
RO,paradr
(SP)+,RO

No code is generated in the unmapped case.

Device Driver Macros and Subroutines 15-3

15. 1.2 DRMAP$ (Remap Virtual Address)
The DRMAP$ macro converts a virtual address and its associated PAR value into an address
and PAR value that are usable in the caller-specified PAR. The resulting address is adjusted to
the lower boundary of the specified PAR. For example, DRMAP$ allows drivers and ISRs to
convert the buffer address and PAR value received for an I/O request in order to use PAR 1
(which the kernel-mode ISR must save and restore) during data transfers. The DRMAP$ macro
generates a call to the $DRMAP routine that resides in the mapped driver object library DRVM.
All registers are preserved across the call.

Syntax
DRMAP$ srcadr,srcpar,dstadr,dstpar,parnum

Parameter

Definition

srcadr

The address to remap. This argument has the form:
[SRCADR=]source-address

srcpar

The PAR value for SRCADR. This argument has the form:
[SRCPAR=]source-par

dstadr

The location to receive the remapped address. This argument has the form:
[DSTADR=]destination-address

dstpar

The location to receive the remapped PAR value. This argument has the form:
[DSTPAR=]destination-par

parnum

The PAR number to map to. The default is # 1. This argument the form:
[PARNUM=]par-number

Semantics
In the mapped case, the DRMAP$ macro generates the following code:
MOV
srcpar,-(SP)
MOV
srcadr,-(SP)
parnum,-(SP)
MOV
.GLOBL $DRMAP
PC,$DRMAP
JSR
MOV
(SP)+,dstadr
MOV
(SP)+,dstpar

In the unmapped case, the macro generates:
MOV

srcadr,dstadr

15-4 Device Driver Macros and Subroutines

Example

The following NSP source excerpt transfers user-requested read data to a user-specified buffer
and then replies to the user.
RO contains the count of bytes to be transferred, Rl points to the start of the data to be copied,
and R4 points to the user request packet (also used for the reply). The buffer to receive the
read data is specified by the DP.BUF and DP.PAR fields of the request packet.
Other symbols for the example are defined by macros DRVDF$ (DP.xxx packet offsets), PCBDF$
(PCB symbols for ENCXW$ and DSCXW$), and IODF$ (U.ISAl and U.ISDl, the user PAR 1
and PDR 1 1/0 page addresses). There are global symbols, U.ISAO-U.ISA7, that define the 1/0
page addresses of user PARs 0-7, respectively. There are also global symbols U.ISDO-U.ISD7
that define the 1/0 page addresses of user PDRs 0-7, respectively. Similarly, K.ISAO-K.ISA7
and K.ISDO-K.ISD7 define the 1/0 page addresses of kernel PARs 1-7 and kernel PDRs 1-7,
respectively.
In the excerpt, DRMAP$ maps the user-specified virtual-address/PAR pair to PAR 1 for the
transfer of the read data. The ENCXW$, DWPAR$, and DSCXW$ macros and the $BLXIO and
$DRPLY subroutines are described in detail elsewhere in this chapter.
60$:

70$:

MDV
RO,DP.ALN(R4) ;This is the actual length transferred
BEQ
70$
;Could be zero length message
ENCXW$
pcb=©#$RUN
;Turn on MMU context switching now
DWPAR$
#77406,U.ISDi ;Initialize PDR 1 to full access
DRMAP$
srcadr=DP.BUF(R4),srcpar=DP.PAR(R4),
dstadr=R2,dstpar=©#U.ISA1,parnum=#1
CALL
$BLXIO
;Copy RO bytes from (R1) to (R2)
DSCXW$
pcb=©#$RUN
;Turn off MMU context switching now
CALL
$DRPLY
;Give response to user

Device Driver Macros and Subroutines 15-5

15.1.3 DRPAR$ (Read Contents of PAR or PDR Register)
The DRPAR$ macro fetches the contents of a PAR or PDR register.
Syntax
DRPAR$ parnam,where

Parameter

Definition

parnam

The PAR to be read. This argument has the form:
[PARNAM=]par-name

where

The destination for the PAR contents. This argument has the form:
[WHERE=]destination-address

Semantics
In the mapped case, the DRP AR$ macro generates:
MOV

~#parnam,where

No code is generated in the unmapped case.
Example
DRPAR$

U.ISA1,-(SP)

;Save the contents of user PAR 1
;on the stack

15-6 Device Driver Macros and Subroutines

15. 1.4 DRVDF$ (Define Driver Packet Symbols)
The DRVDF$ macro defines symbols required for packet-level use of the MicroPower /Pascal
device drivers, including:
•

1/0 packet field offsets (DP.xxx)

•

Function codes (IF$xxx)

•

Function modifiers (FM$xxx)

•

Device class codes (DC$xxx) and type codes

The DRVDF$ symbols are listed in Chapter 1 and referenced throughout this manual.
Syntax
DRVDF$ range

Parameter

Definition

range

A parameter that determines if the symbols are global. The default is nogbl for
not global. This argument has the form:
[RANGE=]nogbl
or
[RANGE=]global

Device Driver Macros and Subroutines 15-7

15. 1.5 DSCXW$ (Disable MMU Context Switch)
The DSCXW$ macro disables MMU context switching (CX$KT) for a process control block
(PCB). It is used with the ENCXW$ (Enable MMU Context Switch) macro, described in Section
15.1.7.
The ENCXW$ and DSCXW$ macros are used by drivers that are actively accessing a user
buffer (implying non-DMA transfers) from user mode. The two macros allow you to reduce
MMD-register-saving overhead by enabling MMU context switching only when necessary.
Setting CX$KT causes the kernel to save/restore the MMU registers-a lengthy sequencewhen the driver blocks/resumes. Since the drivers block frequently-waiting for the next user
request-repeated saving/restoring of the MMU registers occurs. To reduce that overhead, use
ENCXW$ and DSCXW$ to bracket code that modifies mapping to access the user buffer, leaving
MMU context switching disabled when not needed. (See the example in Section 15.1.2.)
Use of the ENCXW$ and DSCXW$ macros requires a firm grasp of MMU context switching.
DSCXW$ requires DRIVER or PRIVILEGED mapping, because the generated code accesses the
PCB. You must also define PCB symbols by invoking the PCBDF$ macro.
All registers are preserved across the macro call, except for a user-specified work register (if
provided).
Syntax
DSCXW$ pcb[,reguse]

Parameter

Definition

pcb

The address of the PCB for which MMU context switching is to be disabled.
This argument has the form:
[PCB=]pcb-address

reguse

An optional parameter that specifies a register to use for the operation; if not
specified, extra instructions that save and restore a register are generated. This
argument has the form:
[REGUSE=]register-spec

Semantics
In the mapped case, if the RECUSE parameter is not provided, the ENCXW$ macro generates
the following code:
MDV RO,-(SP)
MOV pcb,RO
BICB
#CX$KT,PC.CXW(RO)
MOV
(SP)+,RO

If mapped, and RECUSE is provided, the following is generated:
MOV
BICB

pcb,reguse
#CX$KT,PC.CXW(reguse)

No code is generated in .the unmapped case.

15-8 Device Driver Macros and Subroutines

Application Note
A space improvement can be made to any driver that keeps a copy of its process descriptor
(filled in by means of a GTST$ kernel primitive call) only for the purpose of supplying the
driver's PCB address to ENCXW$ and DSCXW$. The kernel symbol $RUN can be used instead
to supply the current PCB address (DSCXW$ pcb=@#$RUN ... ), thereby potentially eliminating
the driver's need for the copy of the PDB and the services of the GTST$ kernel primitive.

Device Driver Macros and Subroutines 15-9

15.1.6 DWPAR$ (Write to PAR or PDR Register)
The DWP AR$ macro loads a PAR or PDR register.
The example in Section 15.1.2 illustrates the use of DWPAR$·.
Syntax
DWPAR$ from,parnam

Parameter

Definition

from

The address from which data will be loaded. This argument has the form:
[FROM=] source-address

parnam

The PAR to be loaded. This argument has the form:
[PARNAM=]par-name

Semantics
In the mapped case, the DWPAR$ macro generates:
MOV

from,©#parnam

No code is generated in the unmapped case.
Example
DWPAR$

#77406,U.ISD!

;Set PDR 1 for full RW access

15-10 Device Driver Macros and Subroutines

15. 1. 7 ENCXW$ (Enable MMU Context Switch)
The ENCXW$ macro enables MMU context switching (CX$KT) for a process control block (PCB).
It is used with the DSCXW$ (Disable MMU Context Switch) macro, described in Section 15.1.5.
The ENCXW$ and DSCXW$ macros are used by drivers that are actively accessing a user
buffer (implying non-DMA transfers) from user mode. The two macros allow you to reduce
MMD-register-saving overhead by enabling MMU context switching only when necessary.
Setting CX$KT causes the kernel to save/restore the MMU registers-a lengthy sequencewhen the driver blocks/resumes. Since the drivers block frequently-waiting for the next user
request-repeated saving/restoring of the MMU registers occurs. To reduce that overhead, use
ENCXW$ and DSCXW$ to bracket code that modifies mapping to access the user buffer, leaving
MMU context switching disabled when not needed. (See the example in Section 15.1.2.)
Use of the ENCXW$ and DSCXW$ macros requires a firm grasp of MMU context switching.
ENCXW$ requires DRIVER or PRIVILEGED mapping, because the generated code accesses the
PCB. You must also define PCB symbols by invoking the PCBDF$ macro.
All registers are preserved across the macro call, except for a user-specified work register (if
provided).

Syntax
ENCXW$ pcb[,reguse]

Parameter

Definition

pcb

The address of the PCB for which MMU context switching is to be enabled.
This argument has the form:
[PCB=]pcb-address

reguse

Semantics
In the mapped case, if the RECUSE parameter is not provided, the ENCXW$ macro generates
the following code:
MOV
MOV
BISB
MOV

RO,-(SP)
pcb,RO
#CX$KT,PC.CXW(RO)
(SP)+,RO

If mapped, and RECUSE is provided, the following is generated:
MOV
BISB

pcb,reguse
#CX$KT,PC.CXW(reguse)

No code is generated in the unmapped case.

Device Driver Macros and Subroutines 15-11

Application Note
A space improvement can be made to any driver that keeps a copy of its process descriptor
(filled in by means of a GTST$ kernel primitive call) ONLY for the purpose of supplying the
driver's PCB address to ENCXW$ and DSCXW$. The kernel symbol $RUN can be used instead
to supply the current PCB address (ENCXW$ pcb=@#$RUN ... ), thereby potentially eliminating
the driver's need for the copy of the PDB and the services of the GTST$ kernel primitive.

15-12 Device Driver Macros and Subroutines

15. 1. 8 IBADR$ (Increment Byte Address and Check for PAR Tick Overflow)
The IBADR$ macro increments a virtual byte address that has been remapped via the $DRMAP
macro to point to the next byte. It also checks for overflow of the PAR field and adjusts the
address and the PAR accordingly.
Since the result of $DRMAP is an address adjusted to the lower boundary of a PAR, simply
incrementing the address is safe until approximately SK-64 bytes have been transferred. If there
is no need to handle such large transfers, you do not need to use this macro.

Syntax
IBADR$ addr,par,?skip

Parameter

Definition

addr

The byte address that was previously remapped via DRMAP$. This argument
has the form:
[ADDR=]byte-address

The PAR value associated with the byte address. This argument has the form:

par

[PAR=]par-value

?skip

A label name for use by a branch instruction in the generated code.
argument has the form:

This

[?SKIP=] label-name

Semantics
In the mapped case, the IBADR$ macro generates the following code:
INC
addr
BITB #77,addr
BNE
skip
SUB
#100,addr
INC
par
skip:

In the unmapped case, the macro generates:
INC

addr

Device Driver Macros and Subroutines 15-13

15.1.9 IWADR$ (Increment Word Address and Check for PAR Tick Overflow)
The IWADR$ macro increments a virtual word address that has been remapped via the $DRMAP
macro to point to the next word. It also checks for overflow of the PAR field and adjusts the
address and the PAR accordingly.
Since the result of $DRMAP is an address adjusted to the lower boundary of a PAR, simply
incrementing the address is safe until approximately 8K-64 bytes have been transferred. If there
is no need to handle such large transfers, you do not need to use this macro.
Syntax
IWADR$ addr,par,?skip

Parameter

Definition

addr

The word address that was previously remapped via DRMAP$. This argument
has the form:
[ADDR=]word-address

par

The PAR value associated with the word address. This argument has the form:
[PAR=]par-value

A label name for use by a branch instruction in the generated code.
argument has the form:

?skip

[?SKIP=] label-name

Semantics
In the mapped case, the IBADR$ macro generates the following code:
ADD
BITB
BNE
SUB
INC
skip:

#2,addr
#77,addr
skip
#100,addr
par

In the unmapped case, the macro generates:
ADD

#2,addr

15-14 Device Driver Macros and Subroutines

This

15. 1. l O MVBYT$ (Move Byte from/to Virtual Addresses)
The MVBYT$ macro allows an ISR to move a byte of data from and to caller-specified virtual
addresses. A caller-specified PAR value is used to map the user data area with kernel APR 1.
Kernel PAR 1 is saved before and restored after this operation.
MVBYT$ is used with the DRMAP$ (Remap Virtual Address) and IBADR$ (Increment Byte
Address and Check for PAR Tick Overflow) macros. Specifically, you use DRMAP$ to adjust
a virtual-address/PAR pair to a PAR 1 virtual-address/PAR pair (specifying PARNUM=#l) in
order to set up the MVBYT$ (or other data-moving operation).
MVBYT$ works only in kernel mode. Fork routines should not use MVBYT$.

Syntax
MVBYT$ src,dst,par

Parameter

Definition

src

The source address. This argument has the form:
[SRC=]source-address

dst

The destination address. This argument has the form:
[DST=]destination-address

par

The PAR value used to map the user data area. This argument
[PAR=]par-value

Semantics
In the mapped case, the MVBYT$ macro generates the following code:
MOV
MOV
MOVB
MOV

C#K.ISA1,-(SP)
par,C#K.ISA1
src,dst
(SP)+,C#K.ISA1

In the unmapped case, the macro generates:
MOVB

src,dst

Device Driver Macros and Subroutines 15-15

15. 1. 11 MVBYU$ (Move Byte from/to Virtual Addresses from User-Mode)
The MVBYU$ macro moves a byte from the source to the destination in the unmapped case. In
the mapped case, it optionally saves the user PAR 1 value, maps user APR 1 using the value
par, and moves a byte. It then optionally restores user PAR 1. This macro only works in user
mode; that is, from driver processes. ISRs should not use MVBYU$.
The calling process should enable MMU context switching before invoking this macro and
disable it after invoking the macro. The DCSXW$ and ENCXW$ macros are provided for this
purpose.

Syntax
MVBYU$

src,dst,par,savmap,resmap

Parameter

Definition

src

The source address. This argument has the form:
[SRC=]source-address

dst

The destination address. This argument has the form:
[DST=]destination-address

par

The PAR value used to map the user data area. This argument has the form:
[PAR] par-value

savmap

The saving of the mapping registers. The default is NO. This argument has the
form:
SAVMAP=YES or NO

resmap

The restoring of the mapping registers. The default is NO. This argument has
the form:
RESMAP=YES or NO

Semantics
In the mapped case, with SAVMAP and RESMAP both defaulted to NO, the MVBYU$ macro
generates:
MOV
MOV
MOVB

In the unmapped case, the MVBYU$ macro generates:
MOVB

src,dst

15-16 Device Driver Macros and Subroutines

15. 1. 12 MVMAP$ (Move Word from/to Virtual Addresses in Mapped Case
Only)
The MVMAP$ macro moves a word from the source to the destination in the mapped case
only.

Syntax
MVMAP$

src,dst

Parameter

Definition

src

The source address. This argument has the form:
[SRC=]source-address

dst

The destination address. This argument has the form:
[DST=]destination-address

Semantics
In the mapped case, the MVMAP$ macro generates:
MOV

src,dst

No code is generated in the unmapped case.

Device Driver Macros and Subroutines 15-17

15. 1. 13 MVVAD$ (Move Address and PAR)
The MVVAD$ macro moves an address and the associated PAR to another pair of words.
Syntax
MVVAD$ srcadr,srcpar,dstadr,dstpar

Parameter

Definition

srcadr

The address to be moved. This argument has the form:
[SRCADR=]address

srcpar

The PAR value to be moved. This argument has the form:
[SRCPAR=]par-value

dstadr

The address destination. This argument has the form:
[DSTADR=]destination-address

dstpar

The PAR destination. This argument has the form:
[DSTPAR=]destination-par

Semantics
In the mapped case, the MVVAD$ macro generates the following code:
MDV
MDV

srcadr,dstadr
srcpar,dstpar

In the unmapped case, the macro generates:
MDV

srcadr,dstadr

15-18 Device Driver Macros and Subroutines

15. 1. 14 MVWRD$ (Move Word from/to Virtual Addresses)
The MVWRD$ macro allows an ISR to move a word of data from and to caller-specified virtual
addresses.
A caller-specified PAR is used to map the user data area with kernel APR 1.
MVWRD$ is used with the DRMAP$ (Remap Virtual Address) and IWADR$ (Increment Word
Address and Check for PAR Tick Overflow) macros. Specifically, you use DRMAP$ to adjust
a virtual-address/PAR pair to a PAR 1 virtual-address/PAR pair (specifying PARNUM=#l) in
order to set up the MVWRD$ (or other data-moving operation).
MVWRD$ works only in kernel mode. Fork routines should not use MVWRD$.

Syntax
MVWRD$ src,dst,par

Parameter

Definition

src

The source address. This argument has the form:
[SRC=]source-address

The destination address. This argument has the form:

dst

[DST=]destination-address

The PAR value used to map the user data area. This argument has the form:

par

[PAR=]par-value

Semantics
In the mapped case, the MVWRD$ macro generates the following code:
MDV
MDV
MDV
MDV

O#K.ISA1,-(SP)
par,O#K.ISA1
src,dst
(SP)+,O#K.ISA1

In the unmapped case, the macro generates:
MDV

src,dst

Device Driver Macros and Subroutines 15-19

15. 1. 15 MVWRU$ (Move Word from/to Virtual Addresses from User-Mode)
The MVWRU$ macro moves a word from the source to the destination in the unmapped case.
In the mapped case, MVWRU$ optionally saves the user PAR ·1 value, maps user APR 1 using
the value par, and moves the word. It then optionally restores user PAR 1. This macro only
works in user mode; that is, from driver processes. ISRs should not use MVWRU$.
The calling process should enable MMU context switching before invoking this macro and
disable it after invoking the macro. The DCSXW$ and ENCXW$ macros are provided for this
purpose.

Syntax
MVWRU$ src,dst,par,savmap,resmap

Parameter

Definition

src

The source address. This argument has the form:
[SRC=]source-address

dst

The destination address. This argument has the form:
[DST=] destination-address

par

The PAR used to map the user data area. This argument has the form:
[PAR] par-name

savmap

The saving of the mapping registers. The default is NO. This argument has the
form:
SAVMAP=YES or NO

resmap

The restoring of the mapping registers. The default is NO. This argument has
the form:
RESMAP=YES or NO

Semantics
In the mapped case, if SAVMAP and RESMAP are defaulted to NO, the MVWRU$ macro
generates:
MOV
MOV
MOV

In the unmapped case, the MVWRU$ macro generates:
MOV

src,dst

15-20 Device Driver Macros and Subroutines

15. 1. 16 SPL$ (Set Priority Level)
The SPL$ macro is used by a driver process executing in user mode to raise its hardware priority
to 7 and lower it back to 0. It is useful for avoiding race conditions between drivers and their
IS Rs.
In the mapped case, SPL$ issues a call to the Set Hardware Priority Level ($SPL) kernel
primitive, which resides in the mapped kernel object library P AXM. In the unmapped case, it
performs a byte operation on the low byte of the PSW.
Note
RO is destroyed in the mapped case of SPL$ but preserved in the unmapped
case.
SPL$ has a potentially dangerous global effect and should be used with caution. In particular,
once a driver is at priority 7, it must not issue any primitives (other than $SPL).
SPL$ cannot be used from ISR or fork level. However, ISR or fork routines can use the SPL
macro, which resides in the COMM and COMU kernel macro libraries. SPL performs a byte
operation on the low byte of the PSW in both the mapped and unmapped cases.
Syntax
SPL$ pri[,savreg]

Parameter

Definition

pri

The hardware priority level to set; must be 0 or 7. This argument has the form:
[PRI=]7
or
[PRI=]O

savreg

The specification to save or not save RO; can be YES or NO. The default is NO.
This argument has the form:
[SAVREG=]YES
or
[SAVREG=]NO

Semantics
In the mapped case, the SPL$ macro generates the following code:
MOV
MOV

#<pri*40>,-(SP)
SP.RO

!OT

.word $SPL
INC
(SP)+

In the unmapped case, the macro generates:
MOV
MTPS

#<pri*40>,-(SP)
(SP)+

Device Driver Macros and Subroutines 15-21

15. 1. 17 XTAD$ (Compute Bus Extended Address)
The XTAD$ macro computes the extended address bits and the physical bus address from a
specified virtual address and PAR value. RO is destroyed. The XTAD$ macro generates a call
to the $XTADR subroutine that resides in the mapped driver object library DRVM.
XTAD$ is primarily used to compute full 22-bit addresses for DMA device drivers.
equivalent Pascal method is shown below.

The

Syntax
XTAD$ vadd,par,pos,ext,addr

Parameter

Definition

vadd

The virtual address. This argument has the form:
[VADD=]virt-address

The PAR value. This argument has the form:

par

[PAR=] par-value

The bit position, in the EXT argument, at which the low-order bit of the extended
address is to be placed. This argument has the form:

pos

[POS=]bit-number

The target address for the shifted extended address bits. This argument has the
form:

ext

[EXT=]address

The target address for the low-order address bits. This argument has the form:

addr

[ADDR=]address

Semantics
In the mapped case, if the POS argument is 0, the XTAD$ macro generates the following code:
CMP
MOV
MOV
MOV
MOV
JSR
MOV
MOV
MOV

-(SP),-(SP)
SP.RO
par,-(SP)
vadd,-(SP)
RO,-(SP)
PC,$XTADR
(SP)+,addr
(SP)+,RO
RO.ext

15-22 Device Driver Macros and Subroutines

If mapped and POS is nonzero, the macro generates:
CMP
MDV
MDV
MDV
MDV
JSR
MDV
MDV
ASH
MDV

-(SP),-(SP)
SP,RO
par,-(SP)
vadd,-(SP)
RO,-(SP)
PC,$XTADR
(SP)+,addr
(SP)+,RO
#pos,RO
RO.ext

In the unmapped case, if the ADDR parameter is not provided, the macro generates:
CLR
MDV

ext
vadd,RO

If unmapped and ADDR is provided, the macro generates:
CLR
MDV
MDV

ext
vadd,RO
RO,ADDR

Example of Pascal Equivalent
Given the virtual page base (P ARV) and the virtual address (ADDR) of a data item, the following
Pascal sequence translates those values into the 22-bit physical address (BUS_ADDRESS) of the
data item:
VAR
addr : UNSIGNED;
parv : UNSIGNED;
bus_address : LDNG_INTEGER;
{Enough for all 22 bits}
offset : UNSIGNED;
BEGIN
offset := UAND(addr,i.D'17777');
{How far from page base}
bus_address := parv;
{Conv page base to 32 bits}
bus_address
(bus_address * 64) + offset; {Construct full addr}
END;

Device Driver Macros and Subroutines 15-23

15.2 Driver Subroutines
The following driver subroutines are available from the driver object libraries DRVM and DRVU
for the use of user-written device drivers:

Routine

Description

$BLXIO

Block Move

$DDEXC

Report Exception for Device Driver

$DDINI

Device Driver Initialization

$DRALR

Allocate Memory

$DRDSP

Deallocate Dynamic Memory

$DRHIN

Initialize Heap

$DRNEW

Allocate Dynamic Memory

$DRPLY

Send Device Driver Reply

$SV02

Save/Restore Registers 0-2

$SV03

Save/Restore Registers 0-3

$SV05

Save/Restore Registers 0-5

To use a driver subroutine, you reference the subroutine name in a call statement in your driver
source file, following any appropriate conventions noted in this chapter for that subroutine. In
addition, if you build the driver into your application manually (rather than letting MPBUILD
do it for you), you must merge the driver with the DRVM or DRVU driver library by including
DRVM or DRVU in the MERGE command line, with the appropriate qualifier (for example,
"/LB").
Note
The $DRMAP and $XTADR subroutines are described in Section 15.1 (the driver
macros section) rather than this section, because they are accessed with macro
calls. See the DRMAP$ and XTAD$ macro descriptions.

15-24 Device Driver Macros and Subroutines

15.2.1 $BLXIO (Block Move)
The $BLXIO subroutine moves data from one buffer to another. It assumes that all data is
currently mapped within the calling process's virtual address space. Given a source address,
destination address, and byte count-that may be even or odd, in any combination-$BLXIO
selects the most efficient means of transfer.
$BLXIO works in both mapped and unmapped systems.
The example in Section 15.1.2 illustrates the use of $BLXIO.

Calling Syntax
JSR

PC,$BLXIO

Input
RO must contain the number of bytes to be moved, Rl the source address, and R2 the destination
address.

Output
Upon return, the data has been copied. RO has been destroyed, Rl points to the byte after the
last byte of the source, and R2 points to the byte after the last byte of the destination.

Device Driver Macros and Subroutines 15-25

15.2.2 $DDEXC (Report Exception for Device Driver)
The $DDEXC subroutine reports an exception for a driver. The routine is usually called
immediately after a kernel primitive request has returned an error. $DDEXC does not returnexcept in the unusual case where the driver has an exception handler. After the exception is
reported, the calling process is stopped.
$DDEXC works in both mapped and unmapped systems.

Calling Syntax
JSR

PC,$DDEXC

Input
RO must contain the exception code to be reported-normally an error code that was returned
by a kernel primitive.

15-26 Device Driver Macros and Subroutines

15.2.3 SODINI (Device Driver Initialization)
The $DDINI subroutine performs standard device driver initialization. It creates the queue
semaphore for each controller process ($xxc). If there are multiple controllers in the application,
$DDINI creates additional copies of the controller process as needed. The impure area for each
controller process is cleared.
Registers 0 through 4 are modified.
Any errors detected by $DDINI are reported via the $DDEXC subroutine and are not recoverable.
$DDINI works in both mapped and unmapped systems.
See also the prefix file macros DRVCF$ (Configure Device Driver) and CTRCF$ (Configure
Controller), described in Chapter 14.

Calling Syntax
JSR

PC,$DDINI

<start-address>:

The address of the instruction after the $DDINI call is normally the start address for the calling
(first controller) process and for each additional controller process as well. Upon return from
$DDINI, the first controller process falls into the start code. Subsequent controller processes
are entered at the start address specified by a CRPC$P macro start-address parameter, which
normally matches the label on the instruction after the $DDINI call.

Input
RS contains the address of the driver configuration data area ($xxPUR::). That area is defined
by the prefix file macro DRVCF$, described in Chapter 14.

Output
For each controller, the controller ID and pointers to the controller's impure area and initialization
data are returned on the stack, as shown below. The controller processes are normally entered
immediately following $DDINI execution. Each controller process must remove this controllerspecific information from the stack immediately on entry for use by the driver code.

+--------------------+
-> Impure area
<-- SP
,--------------------,
:
-> Init data
:
1--------------------1
:
Controller ID
:
+--------------------+
I

ML0-946-87

The initialization data area (at $xxcPU::) is defined by the prefix file macro CTRCF$, described
in Chapter 14.
The controller ID is 0 for controller A, 1 for controller B, and so forth.

Device Driver Macros and Subroutines 15-27

15.2.4 $DRALR (Allocate Memory)
The $DRALR subroutine allocates memory from the kernel in a consistent manner, using the
$ALRG (Allocate Region) kernel primitive. All registers· are preserved across the call.
$DRALR works in both mapped and unmapped systems.

Calling Syntax
JSR

PC,$DRALR

Input
The size, in bytes, to be allocated is passed on the stack.

Output
If no memory is available, the carry bit is set. Otherwise, offset and PAR values describing the
allocated memory are returned on the stack.

Example
MOV
JSR
BCS
MOV
MOV

#size,-(SP)
PC,$DRALR
error
(SP)+,addr
(SP)+,par

Supply size in bytes
Call allocate routine
Branch if no memory available
Get virtual address
and PAR value

15-28 Device Driver Macros and Subroutines

15.2.5 $DRDSP (Deallocate Dynamic Memory)
The $DRDSP subroutine deallocates heap memory that was allocated with the $DRNEW
(Allocate Dynamic Memory) subroutine. ($DRNEW and $DRDSP are analogous to NEW and
DISPOSE in Pascal.)
All registers are preserved across a $DRDSP call.
$DRDSP works in both mapped and unmapped systems.

Calling Syntax
JSR

PC,$DRDSP

Input
The address of the block of memory to deallocate, the block size in bytes, and a pointer to the
head of the free memory list are passed on the stack, as follows:

+--------------------+
:
Return PC
<-- SP
1-------------------:
-> Head of list
1-------------------:
Size
1--------------------1
:
Block address
:
+--------------------+
I

ML0-947-87

Output
On exit, the stack is as follows:

+--------------------+
Return PC
<-- SP
+--------------------+
ML0-948-87

Error Returns

The following error code can be returned in RO, with the carry bit set:
Code

Type

Description

ES$DDP

EX$RSC

DISPOSE of already disposed pointer

Device Driver Macros and Subroutines 15-29

15.2.6 $DRHIN (Initialize Heap)
The $DRHIN subroutine initializes a memory heap, which can then be managed with the
$DRNEW (Allocate Dynamic Memory) and $DRDSP (Deallocate Dynamic Memory) subroutines.
All registers are preserved across a $DRHIN call.
DRHIN$ works in both mapped and unmapped systems.

Calling Syntax
JSR

PC,$DRHIN

Input
The heap size in bytes, the address of the heap base, and an address to receive a pointer to the
head of the free memory list are passed on the stack, as follows:
+-------~------------+

Return PC

<-- SP

-> Head of list
Block address
Size

+--------------------+ML0-949-87
Output
On exit, the stack is as follows:

+--------------------+
i
Return PC
l <-- SP
+--------------------+ML0-950-87

15-30 Device Driver Macros and Subroutines

15.2.7 $DRNEW (Allocate Dynamic Memory)
The $DRNEW subroutine allocates a block of memory from a memory heap that has been
initialized with the $DRHIN (Initialize Heap) subroutine. ($DRNEW is analogous to NEW in
Pascal.)
All registers are preserved across a $DRNEW call.
$DRNEW works in both mapped and unmapped systems.

Calling Syntax
JSR

PC,$DRNEW

Input
The requested allocation in bytes and a pointer to the head of the free memory list are passed
on the stack, as follows:

+--------------------+
:
Return PC
<-- SP
1-------------------:
-> Head of list
:-------------------:
Size
+--------------------+
I

ML0-951-87

Output
The address. of the allocated block is returned on the stack. (0 is returned if an error occurred.)
On exit, the stack is as follows:

+--------------------+
Return PC
I <-- SP
1--------------------1
I
Block address
I
+--------------------+
ML0-952-87
I

Error Returns
Two error codes can be returned in RO, with the carry bit set:
Code

Type

Description

ES$NMP

EX$RSC

Insufficient space for structure

ES$NLZ

EX$RSC

NEW of length zero

Device Driver Macros and Subroutines 15-31

15.2.8 $DRPLY (Send Device Driver Reply)
The $DRPLY subroutine sends a standard device-driver reply packet to a reply semaphore, as
specified in a packet that the caller of the routine supplies. If the supplied packet specifies a
short reply (function modifier FM$BSM), the specified binary or counting semaphore is signaled.
Otherwise, a full driver reply is sent to the specified queue semaphore.
If any error occurs, the packet is deallocated.

$DRPLY requires DRIVER or PRIVILEGED mapping, because it uses the SGLQ$ (Signal Queue
Semaphore) primitive rather than the higher-level SEND$ primitive.
$DRPLY works in both mapped and unmapped systems.
The example in Section 15.1.3 illustrates the use of $DRPLY.

Calling Syntax
JSR

PC,$DRPLY

Input
R4 points to the packet to be returned. The 3-word reply semaphore field of that packet (offset
DP.SEM) specifies the reply semaphore to be signaled, or 0 if none. The function word of that
packet contains the FM$BSM modifier (bit 13), which must be set for short replies and cleared
otherwise.

Output
R4 is cleared; all other registers are preserved.

15-32 Device Driver Macros and Subroutines

15.2.9 $SV02, $SV03, and $SV05 (Save/Restore Registers)
$SV02, $SV03, and $SV05 are co-routines for saving and restoring registers. Each $SVOn routine
saves registers 0 through n (where n=2, 3, or 5), calls the calling subroutine (JSR PC,@(SP)+),
restores the registers, and returns. The net effect for the calling subroutine is to save registers
in such a way that they are automatically restored upon exit from the calling subroutine. See
the example below.
The $SVOn co-routines do not destroy the registers in the process of saving them. Thus,
arguments can safely be passed in registers to a subroutine that calls an $SVOn co-routine.
The $SVOn routines work in both mapped and unmapped systems.

Calling Syntax
JSR

Rn,$SVOn

where n is 2, 3, or 5

Input
(Registers, stack, or none)

Output
After calling $SVOn, where n is 2, 3, or 5, n+2 words have been pushed on the stack. If you
want to manipulate saved register m on the stack, the offset is (m*2)+2. See the example below.

Example
JSR

PC,SUB

Call a subroutine
Continue processing

BR
SUB:

JSR
MOV
RETURN

R2,$SV02

Save RO - R2
Perform some operation
#error,<0*2>+2(SP); Put return value in saved RO
Return, restoring registers

Device Driver Macros and Subroutines 15-33

Appendix A
Directory Structure and File Storage
File-structured devices having a series of directory segments at the beginning of the device are
called directory-structured devices. The directory segments contain entries describing the names,
lengths, and creation dates of files on the device. Disks, diskettes, and TU58 cassettes may be
directory-structured devices.
You can directly access any file on a directory-structured device, regardless of its location.
Therefore, directory-structured devices are sometimes called random-access or block-replaceable
devices.
MicroPower/Pascal software includes an ancillary control process (ACP) and utility routines
that can create and maintain directories. (Directory support must be enabled in the ACP prefix
file; see Chapter 2.) The ACP stores files and maintains directories in the same format as the
RT-11 file system.
This appendix first outlines the structure of a random-access device, then describes the contents
of a device directory and explains how to split a directory segment, and lastly discusses file
storage.

A. l Structure of a Random-Access Device
A random-access device consists o[ a series of 256-word blocks. Blocks 0 to 5 are reserved for
system use and cannot be used for data storage. The device directory begins at block 6. Figure
A-1 shows the format of a random-access device.

Directory Structure and File Storage A-1

Figure A-1 : Format of Random-Access Device
OCTAL
BLOCK NUMBER

CONTENTS

BOOT BLOCK (RESERVED)

HOME BLOCK (RESERVED)

RESERVED

6
}

DIRECTORY SEGMENT 1

}

DIRECTORY SEGMENT 2

}

DIRECTORY SEGMENT N

10
11

•

•
•
x
X+1
FILES

STORED DATA

END OF DEVICE
ML0-796-87

A. 1. 1 Home Block
Block 1 of a random-access device is called the home block and contains information about the
volume and its owner. Figure A-2 and Table A-1 show the format and contents, respectively,
of the home block.

A-2 Directory Structure and File Storage

Figure A-2:

Format of Home Block
1 1 1 1 1 1 1 1 2 2 2 2 2 2 2 2 3 3 3 3 3 3 3 3
0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7

000 a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a
040 a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a
100 a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a
140 a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a
200 a a

b b b b b b b b b b b b b b b b b b b b b b b b b b b b

240 b b b b b b b b b b
300
340
400
440
500
540
600
640
700 c c d d
740 h h h h i

e e f
i

J J J J j

g g

h h h h h h h h

k k

ML0-797-87

Table A-1:

Contents of Home Block

Default

Field

Location

Contents

000-201

Bad-block replacement table

204-2Sl

INITIALIZE/RESTORE data area

700-701

Radix-SO VRT (reserved for DIGITAL)

000000

702-703

Block !)Umber of first user file (reserved
for DIGITAL)

000000

722-723

Pack-cluster size

000001

724-72S

Block number of first directory segment

000006

726-727

System version

Radix-SO V3A

730-743

Volume identification

RTl lA and 7 spaces

744-7S7

Owner name

12 spaces

760-773

System identification

DECRTl lA and 4 spaces

776-777

Checksum

In the home block, the contents of all areas except the checksum are undefined and are reserved
for future use by DIGITAL. The checksum is computed by adding all the bytes into a word;
then the word is negated.

Directory Structure and File Storage A-3

A. 1.2 Directory
The directory of a random-access device consists of a series of two-block segments.
segment is 512 words long and contains the names, lengths, and creation dates of files.

Each

A directory can have from 1 to 31 segments. During device initialization, you establish the
size of the directory area by determining the number of segments in the directory. In general,
you should select many segments if you need to store many small files on a large device. To
obtain more space for storing large files on a small device, you can select the minimal number
of segments and reduce the size of the directory area.
Each directory segment consists of a 5-word segment header and entries containing file
information. Each segment ends with an end-of-segment marker. Figure A-3 shows the
general format of a directory segment.
Figure A-3:

Format of Directory Segment

SEGMENT HEADER
ENTRIES

•

•
END-OF-SEGMENT
MARKER
ML0-798-87

Note
An example program that reads a directory and prints the file names is included
on the MicroPower/Pascal distribution kit. See the file FSP AS.PAS.

A-4 Directory Structure and File Storage

A. 1.2. 1 Directory Segment Header
The directory segment header consists of five words; the remaining 507 words of the 2-block
segment are for directory entries. The contents of the header words are as follows:

Word

Contents

The total number of segments in this directory. The valid range is from 1 to 31(decimal).
If you do not specify the number of segments you require when you initialize the
device, the default number of segments for that device is allocated.
·

The segment number of the next logical directory segment. The directory is a linked
list of segments; word 2 is the link between the current segment and the next logical
segment. If this word is 0, there are no more segments in the list.

The number of the highest segment in use. The ACP increm_ents this counter each
time it opens a new segment. Note that the system maintains this counter only in
word 3 of the header for the first directory segment, ignoring the third word of the
header of the other segments.

The number of extra bytes per directory entry; always an unsigned, even octal number;
extended directory entries are described in Section A.1.2.3.

The block number on the device at which the stored data monitored by this segment
begins.

Directory Structure and File Storage A-5

A. 1.2.2 Directory Entry
The rest of the directory segment consists of directory entries, followed by an end-of-segment
marker. Figure A-4 shows the format of a directory entry.
Figure A-4:

Format of Directory Entry
STATUS WORD
FILE NAME (CHARS 1-3)
IN RADIX-50
FI LE NAME (CHARS 4-6)
IN RADIX-50
FILE TYPE
(1 TO 3 CHARACTERS)
IN RADIX-50
TOTAL FILE LENGTH

JOB#

CHANNEL#

CREATION DATE
OPTIONAL EXTRA WORDS

•
•
•
ML0-799-87

The first word of each directory entry is the status word, which describes the condition of the
files stored on the device. The high-order byte of the status word contains a code representing
the type of file (tentative, permanent, protected permanent). The low-order byte is reserved and
should always be 0. Figure A-5 illustrates the status word.
Figure A-5:

Format of Status Word
TYPE OF FILE

RESERVED
ML0-800-87

A-6 Directory Structure and File Storage

There are five valid status word values, as follows:
Status Word
(octal)

Meaning

400

Tentative file.

1000

Empty area (the ACP does not use the name, file type, or date fields in an
empty directory entry).

2000

Permanent file.

102000

Protected permanent file. (See Note below.)

4000

End-of-segment marker. (See Section A.1.2.4.)

The ACP uses three kinds of directory entries: tentative entries, empty entries, and permanent
entries. These three entry types categorize areas as temporary data, available space on the
device, or permanent data. The device directory always contains sufficient entries to describe
the entire device.
•

A tentative file is in the process of being created. When a process requests that a new file
be created, the ACP creates a tentative file. The process must close the file to make the
tentative file permanent. If you do not eventually close a tentative file, the system deletes
it.

•

An empty entry defines an area of the device that is available for use. Thus, when you
delete a file, you create an empty area.

•

A permanent file is a tentative file that has been closed. Permanent files are unique; that is,
only one file can exist with a specific name and file type on a device. If another file exists
with the same name and type when the program closes the current tentative file, the ACP
deletes the first file, thus replacing the old file with the new file.
Note
The ACP provides a mechanism to prevent a file from being deleted. A file is
protected when the high bit of its status word is set. Note that only permanent
files can be protected. You can protect and unprotect files by using the RT11 RENAME command, the IF$PRO and IF$UNP functions of the ACP (see
Chapter 2), or the Pascal PROTECT_FILE and UNPROTECT_FILE routines (see
Chapter 9 of the MicroPower /Pascal Language Guide).

The second, third, and fourth words in a directory entry contain the Radix-SO representation of
the file name and file type. For empty areas, the ACP normally ignores these words.
The fifth word in a directory entry contains the total file length-the number of blocks the file
occupies on the device. Attempts to read or write outside the limits of the file result in an
end-of-file error.
The sixth word in a directory entry contains a pointer to an active file in the ACP.
The seventh word of a directory entry contains the file's creation date. When a program
creates a tentative file, the ACP moves the system date word into the creation date slot for
the entry. To have your files dated, you must enable kernel clock services and call the
SET_SYSTEM_DATE_TIME procedure. (See kit files DATTIM.PAS and TIMER.PAS.) If no

Directory Structure and File Storage A-7

date was set, the date word equals 0. Figure A-6 shows the format of the date word. Bit 15 is
used to indicate the end-of-file status.
Figure A-6:

Format of Date Word
15

MONTH,
IN DECIMAL.
(1-12)

DAY,
IN DECIMAL
(1-31)

YEAR MINUS 110,
IN OCTAL

ML0-801-87

A. 1.2.3 Extended Directory Entry
Normally, directory entries are seven words long, but by using the RT-11 DUP utility program
with the /Z:n option, you can allocate extra words for each directory entry when you initialize
the device. The fourth word of the directory segment header contains the number of extra
bytes you specify. Although the RT-11 DUP command lets you allocate extra words, the ACP
provides no means to manipulate this extra information conveniently. When the ACP initializes
a directory, no extra bytes are allocated. Any program that needs to access these words must
perform its own operations on the directory. Programs that manipulate the directory should
use bit-test (BIT) instructions rather than compare (CMP) instructions.

A. 1.2.4 End-of-Segment Marker
The ACP uses the end-of-segment marker, a status word of 4000 (octal), to determine when it
has reached the end of the directory segment during a directory search. Note that an end-ofsegment marker can appear as the last word of a segment. It does not have to be followed by
a file name, file type, or other entry information.

A-8 Directory Structure and File Storage

A.2 Directory Use
A.2. l Sample Directory Segment
The directory listing shown in Figure A-7 describes a double-density diskette with 11 files.
Figure A- 7:

Directory Listing

DIRECTORY/FULL DYO:
29-AF'f<·-· 79
SIJAF'
.SYS

< UNUSED >

l <7-···FEB····/<J

.SAV
:~~ :I.
1.9
EDIT .SAV
20
LIBR • SAV
4~.)
MACRO .SAV
< UNUSED >
61.3
11 FILES, 284 BLOCKS
690 FF~EE Bl... DCKS

DUF'

:I. 9····FEH····7 1?
l 9····FEH ..··/ 1?
1 1»····FEB··.. 7<;>
:I. 9·-·FEB···· 79

RT:l.:l.SJ.SY!:;
PIP
.SAV
n:rn
• SA')
l... JNI\
.~:lf')V

DUMP

• Stil.J

SIF'F'

.~:>AV

6~'5

1 <;>····FEB-79

:1.6
:1.7
3/

1 <;>--FEB--79

2 1i>····APl:;:·-·/9

:1. 9··-FEB····79

:I. 9··-FEB-··}<;>

19-··FEB-·· 79

DIRECTORY/SUMMARY DYO:
29--APR··.. 79
11 FILES IN SEGMENT 1
4 AVAILABLE

SEGMENTS~

1 IN USE

11 FILES, 284 BLOCKS
690 FREE BLDCl':S

>
ML0-1104-87

Figure A-8 shows the contents of segment 1 of the diskette directory, obtained by dumping
absolute block number 6 of the device.

Directory Structure and File Storage A-9

Figure A-8:

Directory Segment
HEADER:

4
0
1
0
16

ENTRIES:

2000
75131
62000
75273
30

5147
2000
71677
142302
75273
101
-

5147
1000
16315
54162
75273
115
-

5147
2000
62570
0
73376
20
-

5147
2000
16130
0
73376
25
-

5147
2000
15172
0
73376
21

5147
2000
17751
76400
73376
23

5147

FOUR SEGMENTS AVAILABLE
NO NEXT SEGMENT
HIGHEST OPEN IS #1
NO EXTRA BYTES PER ENTRY
FILES START AT DEVICE BLOCK 16 OCTAL
PERMANENT FILE
RADIX-50 FOR SWA
RADIX-50 FOR P
RAD IX-50 FOR SYS
FILE IS 30 OCTAL BLOCKS LONG
USED ONLY FOR TENTATIVE FILES
CREATED ON 19-FEB-79
PERMANENT FILE
RAD IX-50 FOR RT1
RADIX-50 FOR 1SJ
RAD IX-50 FOR SYS
101 OCTAL BLOCKS LONG
USED ONLY FOR TENTATIVE FILES
CREATED ON 19-FEB-79
EMPTY AREA (THE FILE DXMNFB.SYS WAS DELETED)
RADIX-50 FOR DXM
RADIX-50 FOR NFB
RADIX-50 FOR SYS
115 OCTAL BLOCKS LONG
'usED ONLY FOR TENTATIVE FILES
CREATED 19-FEB-79
PERMANENT FILE
RADIX-50 FOR PIP
RADIX-50 FOR SPACES
RADIX-50 FOR SAV
20 OCTAL BLOCKS LONG
USED ONLY FOR TENTATIVE FILES
CREATED 19-FEB-79
PERMANENT FILE
RADIX-50 FOR DUP
RADIX-50 FOR SPACES
RADIX-50 FOR SAV
250CTALBLOCKSLONG
USED ONLY FOR TENTATIVE FILES
CREATED 19-FEB-79
PERMANENT FILE
RADIX"50 FOR DIR
RADIX-50 FOR SPACES
RADIX-50 FOR SAV
21 OCTAL BLOCKS LONG
USED ONLY FOR TENTATIVE FILES
CREATED 19-FEB-79
PERMANENT FILE
RADIX-50 FOR EDI
RADIX-50 FORT
RADIX-50 FOR SAV
23 OCTAL BLOCKS LONG
USED ONLY FOR TENTATIVE FILES
CREATED 19-FEB-79
ML0-802-87

(Continued on next page)

A-10 Directory Structure and File Storage

Figure A-8 (Cont.):

Directory Segment

2000
46166
42300
73376
45
-

5147
2000
46152
70200
73376
24

5147
2000
16125
62000
73376
7
-

5147
2000
50553
71330
73376
55
-

5147
2000
74070
62000
73376
15
-

11647
1000
000325
063471
023364
·1145
-

4000

PERMANENT FILE
RADIX-50 FOR LIN
RADIX-50 FORK
RADIX-50 FOR SAV
45 OCTAL BLOCKS LONG
USED ONLY FOR TENTATIVE FILES
CREATED 19-FEB-79
PERMANENT FILE
RADIX-50 FOR LIB
RADIX-50 FOR R
RADIX-50 FOR SAV
24 OCTAL BLOCKS LONG
USED ONLY FOR TENTATIVE FILES
CREATED 19-FEB-79
PERMANENT FILE
RADIX-50 FOR OUM
RADIX-50 FOR P
RADIX-50 FOR SAV
7 OCTAL BLOCKS LONG
USED ONLY FOR TENTATIVE FILES
CREATED 19-FEB-79
PERMANENT FILE
RADIX-50 FOR MAC
RADIX-50 FOR RO
RADIX-50 FOR SAV
55 OCTAL BLOCKS LONG
USED ONLY FOR TENTATIVE FILES
CREATED 19-FEB-79
PERMANENT Fl LE
RADIX-50 FOR SIP
RADIX-50 FOR P
RADIX-50 FOR SAV
150CTALBLOCKSLONG
USED ONLY FOR TENTATIVE FILES
CREATED 29-APR-79
EMPTY AREA (NEVER USED SINCE INITIALIZATION)
RADIX-50 FOR EM (STORED AT INITIALIZATION)
RADIX-50 FOR PTY (STORED AT INITIALIZATION)
RADIX-50 FOR FIL (STORED AT INITIALIZATION)
1145 OCTAL BLOCKS LONG
USED ONLY FOR TENTATIVE FILES
(THE DATE IS NOT SIGNIFICANT)
END-OF-SEGMENT-MARKER
ML0-803-87

To find the starting block of a particular data file, first find the directory segment containing
the directory entry for that file. Next, add to the starting block number (the fifth word of
that directory segment header) the length of each permanent, tentative, and empty entry in the
directory before your file. In Figure A-8, for example, the permanent file RTl lSJ.SYS begins at
block number 46 (octal)-starting block (16) plus SWAP.SYS length (30)-on the device.

Directory Structure and File Storage A-11

A.2.2 Splitting a Directory Segment
Whenever the ACP stores a new file on a volume, it searches through the directory for an
empty area that is large enough to accommodate the new tentative file. When it finds a suitable
empty area, it creates the new file as a tentative file followed by an empty area, sliding the rest
of the directory entries down to make room for the new entry. Figure A-9 shows how the ACP
stores a new file as a tentative file followed by an empty area.
Figure A-9:

Storing a New File
BEFORE

AFTER

BLOCK 6
SEGMENT 1

HEADER

PERMANENT 1

PERMANENT 2

PERMANENT 3

EMPTY

TENTATIVE

PERMANENT 4

EMPTY

END-OF-SEGMENT

PERMANENT 4
END-OF-SEGMENT

END OF BLOCK 7
END OF BLOCK 7

ML0-804-87

This procedure works properly if the empty entry and the entries following it can move
downward. If the segment is full, however, the ACP must split the segment, if possible, in
order to store the new entry. Figure A-10 illustrates a directory segment that is full.

A-12 Directory Structure and File Storage

Figure A-1 O:

Full Directory Segment
BLOCK 6
SEGMENT 1
HEADER
PERMANENT 1
PERMANENT 2
PERMANENT 3
PERMANENT 4
PERMANENT 5
• MORE ENTRIES

END-OF-SEGMENT,
END OF BLOCK 7
ML0-805-87

First, the ACP checks the header for the number of available segments. If there are none, a
"directory full" error results, and you cannot store the new file. You can consolidate empty space
on the volume at this point by using RT-11 commands or the Pascal SQUEEZE_DIRECTORY
procedure (kit file SQUEEZ.P AS) to pack the directory segments and then can try the operation
again. You could also delete any unneeded files.
If another directory segment is available, the ACP divides the current segment by first finding

a permanent or tentative entry near the middle of the segment and saving its first word. In
place of the first word, the ACP puts an end-of-segment marker. It then saves the current link
information, links the current segment to the next available segment, and writes the current
segment back to the volume.
Next, the ACP restores the first word of the middle entry to the copy of the segment that is
still in memory and restores the link information. The ACP slides the middle entry and all
subsequent entries to the top of the segment. Then the ACP writes this segment to the volume
as the next available segment. Finally, the ACP reads segment 1 into memory and updates the
information in its header, at which point the ACP begins its search again for a suitable empty
entry to accommodate the new file.
Note
Throughout this process the Extra-Bytes word remains unchanged.
Figures A-11 and A-12 summarize the process of splitting a directory segment. In this example,
segment 1 was the only segment in use. It contained an empty entry, but did not have room
for a tentative entry in addition to the empty one. After the split, segments 1 and 2 are both
about half full.

Directory Structure and File Storage A-13

Figure A-11:

Directory Before Splitting
HIGHEST SEGMENT IN USE: 1
NUMBER OF SEGMENTS AVAILABLE: 2
BLOCK 6
SEGMENT 1

BLOCK 10
SEGMENT 2

HEADER
PERMANENT 1
L.

PERMANENT 2
PERMANENT 3
PERMANENT 4
PERMANENT 5
EMPTY
PERMANENT 6
PERMANENT 7
END-OF-SEGMENT,
END OF BLOCK 7

END OF BLOCK 11
ML0-806-87

A-14 Directory Structure and File Storage

Figure A-12:

Directory After Splitting
BLOCK 6
SEGMENT 1
LINK
HEADER

BLOCK 10
SEGMENT 10

HEADER

PERMANENT 1

PERMANENT 5

PERMANENT 2

EMPTY

PERMANENT 3

PERMANENT 6

PERMANENT 4

PERMANENT 7

EN D-0 F-SEGM ENT

END-OF-SEGMENT

•
•
•

•
•
•
END OF BLOCK 7

•
•
•

•

END OF BLOCK 11

ML0-807-87

After a directory segment splits, the ACP can store the new file in either the new segment or
the old one, depending on which segment now contains the empty area. Segment 2 contains
the empty area in Figure A-12.
Thus far, the link word (word 2 of segment header) seems superfluous, since the segments are
always in numerical order. However, consider a situation in which four segments are available:
segment 1 fills and overflows into segment 2; segment 2 fills and overflows into segment 3; and
segments l, 2, and 3 are half full and are linked in the order in which they are located on the
volume (blocks 6, 10, and 12). The picture changes if you delete a large file from segment 2,
leaving a large empty entry, and add many small files to the volume. Segment 2 now fills up
and overflows into the next free segment, segment 4, so that the links become visibly significant:
segment 1 links to 2, segment 2 links to segment 4, and segment 4 links to segment 3 because
segment 2 previously linked to segment 3. Figure A-13 illustrates this example.

Directory Structure and File Storage A-15

Figure A-13:

Directory Links

HIGHEST SEGMENT IN USE: 3
NUMBER OF SEGMENTS AVAILABLE: 4

BLOCK 6

BLOCK10

BLOCK12

SEGMENT 1

SEGMENT 2

SEGMENT 3

LIN~

I_______, LIN~'

- _ _ _ _ _,..

HIGHEST SEGMENT IN USE: 4
NUMBER OF SEGMENTS AVAILABLE: 4

BLOCK6

BLOCK10

BLOCK 12

SEGMENT 1

SEGMENT 2

SEGMENT 3

I__. . ,.___

LIN~ ..

BLOCK 14
SEGMENT 4

_ ______..I ..LINK
LINK
ML0-808-87

A.2.3 File Storage
The ACP uses the tentative, empty, and permanent entry types to describe completely the
contents of a random-access device. All files reside on blocks that are contiguous on a device.
There are several advantages and disadvantages to this method of storing data.

A.2.4 Method
When data is stored in contiguous blocks, 1/0 is more efficient. Transfers to large buffers are
handled directly by the hardware for certain disks; seeks between blocks and program interrupts
between blocks are eliminated. File data is processed simply and efficiently, since the data is
not encumbered by link words in each block. Routines to maintain the directory are relatively
small, because the directory structure is simple. File operations, such as open, delete, and close,
are performed quickly, with few disk accesses, because only the directory must be accessed, not
additional bit maps or retrieval pointers.
One disadvantage of this method of storing data is that a small device can become fragmented,
requiring a squeeze operation to consolidate its free space. Another disadvantage is that once
a file is closed, a running program cannot easily increase its size. Only a small number of
output files can be opened simultaneously, even on a large device, unless the limits of the file
sizes are known in advance. Finally, this scheme precludes the use of multiple and hierarchical
directories.
In summary, any method of storing data has its advantages and disadvantages.
The
contiguous block method is used because its simple structure and low overhead suit typical
MicroPower /Pascal applications.

A-16 Directory Structure and File Storage

Figure A-14 shows a simplified diagram of a random-access device that has a total of 250 blocks
of space available for files after blocks 0 to 5 and the directory are accounted for. The device
in the figure has two permanent files and one empty area stored on it.

Figure A-14:

Random-Access Device with Two Permanent Files
PERMANENT
80 BLOCKS

EMPTY
150 BLOCKS

PERMANENT
20 BLOCKS
ML0-809-87

When you create a file, your program must allocate the space for the file. If you do not know the
actual size, as is often the case, the space you allocate should be large enough to accommodate
all the data possible.
The ACP creates a tentative file on the device with the length you specified. The tentative file
must always be followed by an empty area to enable the ACP to recover unused space if less
data is written to the file than you originally estimated. Figure A-15 shows a tentative file
whose allocated size is 100 blocks. Note that the total amount of space on the device, 250
blocks in this case, remains constant.

Figure A-15:

Random-Access Device with One Tentative File
PERMANENT
80 BLOCKS

TENTATIVE
100 BLOCKS

EMPTY
50 BLOCKS

PERMANENT
20 BLOCKS
ML0-810-87

Suppose, for example, that while the file is being created by one process, another process enters
a new file, allocating 25 blocks for it. The device would appear as shown in Figure A-16.
Remember that every tentative file must be followed by an empty area.

Figure A-16:
PERMANENT
80 BLOCKS

Random-Access Device with Two Tentative Files
TENTATIVE
100 BLOCKS

EMPTY
0 BLOCKS

TENTATIVE
25 BLOCKS

EMPTY
25 BLOCKS

PERMANENT
20 BLOCKS
ML0-811-87

When the ACP finishes writing data to the device, it closes the tentative file. The ACP then
makes the tentative file permanent. The length of the file is the actual size of the data that
was written. The size of the empty area is its original size, plus any unused space from the
tentative file.
Figure A-17 shows the same device after both tentative files are closed. The first file's actual
length is 75 blocks; the second file's length is 10 blocks.

Directory Structure and File Storage A-17

Figure A-17:

Random-Access Device with Four Permanent Files

PERMANENT
80 BLOCKS

PERMANENT
75 BLOCKS

EMPTY
25 BLOCKS

PERMANENT
10 BLOCKS

EMPTY
40 BLOCKS

PERMANENT
20 BLOCKS
ML0-812-87

This method of storing files makes it impossible to extend the size of an existing file from within
a running program. To make an existing file appear to be bigger, you can read the existing file,
allocate a new, larger tentative file, and write both the old and new data to the new file. You
can then delete the old file.

A.2.5 Size and Number of Files
The number of files you can store on a MicroPower/Pascal device depends on the number of
segments in the device's directory and the number of extra words per entry. If you use no extra
words, each segment can contain 72 entries.
The maximum number of directory segments on a MicroPower/Pascal device is 31 (decimal).
Use the following formula to calculate the theoretical maximum number of directory entries
and, thus, the maximum number of files:
512 - 5
31 *

-2
7 + N

In the formula above, N represents the number of extra information words per directory entry.
If N is 0, the maximum number of files you can store on the device is 2230 (decimal).

Note that all divisions are integer and that the remainder should be discarded.
In the formula above, the -2 is required for two reasons. First, in order to create a file, the
tentative file must be followed by an empty area. Second, a 1-word end-of-segment entry must
exist.
If you store files sequentially (that is, one immediately after another) without deleting any

files, roughly one-half the theoretical maximum number of files will fit on the device before a
directory overflow occurs. This situation results from the way the ACP splits filled directory
segments.
When a directory segment becomes full, requiring the opening of a new segment, the ACP
moves approximately one-half of the directory entries of the filled segment to the new segment.
Thus, when the final segment is full, all previous segments have approximately one-half of their
total capacity. See Section A.2.2 for a detailed explanation of how the ACP splits a directory
segment.
If you add files continually to a device without issuing the RT-11 SQUEEZE monitor command

or calling the Pascal SQUEEZE_DIRECTORY procedure (see kit file SQUEEZ.PAS), you can
use the following formula to compute the maximum number of entries and, thus, the maximum
number of files:

A-18 Directory Structure and File Storage

s
(M - 1)*

- + S
2

In the formula above, M represents the maximum number of segments.
You can use the following formula to compute S:

512 - 5

- 2

7 + N

In the formula above, N represents the number of extra information words per entry.
You can realize the theoretical total of directory entries (see the first formula above) by using
the RT-11 SQUEEZE command or the Pascal SQUEEZE_DIRECTORY procedure to compress
the device when the directory fills up.

Directory Structure and File Storage A-19

Appendix B
KXT 1 1-CA and KXJ 11-CA Peripheral Processors
This appendix contains information you will need for writing MicroPower/Pascal applications
for the KXTl 1-CA or KXJll-CA Peripheral Processor. Additional information for KXTl 1CA/KXJl 1-CA device drivers is contained in the following chapters:

Chapter

Driver

Asynchronous serial line/ terminal (TT)

TU58 (DD)

KXTl 1-CA/KXJll-CA parallel lines and timer/counters (YK)

KXTl 1-CA/KXJll-CA DMA transfer controller (QD)

KXTll-CA/KXJll-CA two-port RAM (KX and KK), KXTll-CA/KXJll-CA synchronous serial line (XS)

B. 1 KXT 1 1-CA/KXJ 1 1-CA Hardware and Applications
The KXTll-CA/KXJll-CA Peripheral Processor is an LSl-11, single-board, 16-bit computer
with local memory and communication ports. You can use it as a self-contained stand-alone
system or as a component (peripheral processor) of an LSI-11-based multiple processor system.
In a multiple processor system, you can add up to 14 user-programmed KXTll-CA/KXJll-CA
Peripheral Processors to traditional Q-bus systems and communicate with them from the LSI-11
CPU acting as arbiter. The software architecture is master/slave (not to be confused with the
bus-master /bus-slave hardware concept) which means the KXTl 1-CA/KXJll-CA application
(slave) performs operations only on command from the arbiter application (master). The
master application runs in the Q-bus arbiter processor and controls the KXTl 1-CA/KXJl lCA application by sending it messages over the KXTl 1-CA/KXJl 1-CA two-port RAM (TPR)
registers in the 1/0 page. The KXTll-CA/KXJll-CA can also transfer data to and from main
memory with its DMA transfer controller (DTC) facility.
When configured for stand-alone operation, the KXTl 1-CA or KXJl 1-CA is completely selfcontained with no Q-bus required.

KXT11-CA and KX/11-CA Peripheral Processors

B-1

MicroPower/Pascal supports KXTll-CA and KXJll-CA single-board computers as stand-alone
systems or as peripheral processors in a multiple processor environment. You can also
program the KXTl 1-CA/KXJll-CA using the MACR0-11 language. In peripheral processing
applications, you can then incorporate the processors into arbiter applications based on the
RT-11, RSX-llM, RSX-UM-PLUS, Micro/RSX, MicroVMS, or MicroPower/Pascal operating
environment.
In addition to DIGITAL's standard Q-bus software development tools, you can choose from
the following five software products that provide tools for KXTl 1-CA/KXJll-CA application
development:
•

MicroPower/Pascal

•

Peripheral Processor Tool Kit-RT-11

•

Peripheral Processor Tool Kit-RSX

•

Peripheral Processor Tool Kit-Micro/RSX

•

Peripheral Processor Tool Kit-MicroVMS

MicroPower/Pascal software provides tools for developing KXTl l-CA/KXJl 1-CA stand-alone
or peripheral processor applications in MicroPower/Pascal and MACR0-11 under the control
of the MicroPower/Pascal run-time kernel. Included are drivers for the following KXTl 1CA/KXJll-CA on-board devices:
•

Asynchronous serial 1/0

•

Synchronous serial IjO

•

Parallel I/O and counter-timers

•

Real-time clock

•

OMA transfer

For peripheral processor applications, device drivers provide communication through the TPR.
They allow a MicroPower/Pascal application on the KXTl 1-CA/KXJl l-CA to communicate
with a MicroPower/Pascal, RT-11, RSX-11, or MicroVMS application in the arbiter processor.
MicroPower/Pascal provides a device driver for MicroPower/Pascal arbiter applications. The
drivers for RT-11, RSX-11, and MicroVMS are available in the tool kits.
KXTl 1-CA/KXJl 1-CA peripheral processor tool kits provide tools for using peripheral processors
in traditional Q-bus systems. Support is provided for RT-11, RSX-llM, RSX-llM-PLUS,
Micro/RSX, and MicroVMS arbiter applications to load and communicate with KXTl 1CA/KXJl 1-CA peripheral processors across the Q-bus. The drivers communicate with KXTl 1CA/KXJl l-CA processors programmed in MicroPower/Pascal.
If those tools do not meet your needs, you can program the KXTl 1-CA or KXJl 1-CA in
the MACR0-11 assembly language, using the standard PDP-11 application development tools
(MACR0-11, LINK, ODT, MACDBG, and so on).
If your KXTl 1-CA/KXJl 1-CA application program uses ROM, you can load it with the DECprom
program (VMS systems).

B-2

KXTl 1-CA and KX/11-CA Peripheral Processors

B. 1. 1 KXT 11-CA Hardware Features
Figure B-1 shows the general layout of the following major hardware components. DIGITALsupplied software supports most but not all hardware features; the software documentation
describes the supported features.
Figure B-1:

KXT 11-CA Hardware Features
PARALLEL
DEVICES

ASYNCHRONOUS
SERIAL DEVICE

ASYNCHRONOUS/SYNCHRONOUS
SERIAL DEVICES

r--------,--.-,,t++++~f*+++-r--r--r-r-ir++r--r--r""0000-r----.....+-t-r----..--,.........,..++.......-..............---~

Boot/
SelfTest
Switch

LEDs
Parallel 1/0
Counter-Timers

SLU1
Console

SLU2
Channel A

SLU2
Channel B

System
ID
Switch

T-11 Processor, Native Firmware, Native RAM, ROM/RAM User Sockets

DMA Transfer Controller

Two-Port RAM

ML0-814-87

•

DIGITAL DCT-11microprocessor-A16-bit, 7-MHz microprocessor that executes the PDP11 basic instruction set.

•

On-board memory-Local memory consisting of 32K bytes of static read/write memory
(RAM), sockets for up to 32K bytes of PROM or static RAM, and SK bytes of native
firmware. Additional features include eight memory map configurations and battery backup
for native RAM.

•

Native firmware-Provides:
Power-up self-test
Optional loopback tests
Hardware initialization
Serial ODT accessible from a console terminal or via the Q-bus

KXT11-CA and KX]l 1-CA Peripheral Processors

B-3

Application start-up: ROM, TU58 boot, or load from the Q-bus arbiter
't

•

TPR-A 16-word interface to the Q-bus that passes control information and data between the
KXTll-CA and the arbiter. The RAM is divided into three areas: one area for KXTll-CA
native firmware commands and two areas for application message passing.

•

2-channel DTC-A device that provides for memory and 1/0 data transfers between the
local KXTl 1-CA and global memory on the Q-bus, using direct memory access. Permitted
transfer combinations are:
Local memory to global memory
Global memory to local memory
Local memory to local memory
Global memory to global memory

•

Parallel 1/0 interface-Contains two bidirectional 8-bit input/ output ports, one 4-bit control
port, and three 16-bit programmable counter-timers.

•
•

Console port (DLART)-Provides DLl 1-compatible asynchronous serial communication .
Multiprotocol controller-Provides 2-channel synchronous/ asynchronous serial 1/0 communication.

•

System ID switch-Sets the system identification address and establishes the KXTl 1-CA
for Q-bus or stand-alone operation.

•

~oot/Self-test switch-Selects bootstrap and firmware self-test operations .

•

Configuration jumpers-Electrical jumpers on the KXTl 1-CA circuit board that select some
of the hardware configuration options (other options are software-configurable).

See the KXTl 1-CA Single-Board Computer User's Guide for detailed information about the KXTl 1CA hardware.

B. 1.2 KXJ 11-CA Hardware Features
Figure B-2 shows the general layout of the following major hardware components. DIGITALsupplied software supports most but not all hardware features; the software documentation
describes the supported features.

B-4

KXTl 1-CA and KX/11-CA Peripheral Processors

Figure B-2:

KXJ 11-CA Hardware Features
PARALLEL
DEVICES

ASYNCHRONOUS
SERIAL DEVICE

ASYNCHRONOUS/SYNCHRONOUS
SERIAL DEVICES

........._.,...,M-+++~~+-----....-.~-----0000-------+-r--.--.-.....-...+-t-..-----~~--.

--~~--..

Boot/
SelfTest
Switch

LEDs
Parallel 1/0
Counter-Timers

System

SLU1

SLU2

Console

Channel A

Channel B

ID
Switch

J-11 Processor, Native Firmware/User ROM, 512 KB RAM

OMA Transfer Controller

Two-Port RAM

ML0-813-87

•

J-11 (DCJll-AC) 16-bit microprocessor
Executes extended PDP-11 instruction set (140 instructions including floating-point).
Contains memory management unit for three levels of memory protection and 4M byte
addressing.
Operates at 14 MHz.

•

Memory
512K bytes of dynamic RAM
Can be accessed by local (on-board) devices and, if enabled as shared memory, also by
Q-bus devices
Up to 64K bytes of PROM; 16K bytes of which is for firmware

•

Native firmware-Provides:
Power-up self test
Optional loopback tests

KXT11-CA and KX/11-CA Peripheral Processors

B-5

Hardware initialization
Application start-up: ROM, TU58 boot, or load from the Q-bus arbiter
•

TPR-A 16-word interface to the Q-bus that passes control information and data between
the KXJll-CA and the arbiter. The RAM is divided into three areas: one area for KXJll-CA
native firmware commands and two areas for application message passing.

•

2-channel OTC-A device that provides for memory and 1/0 data transfers between the
local KXJl 1-CA and global memory on the Q-bus, using direct memory access. Permitted
transfer combinations are:
Local memory to global memory
Global memory to local memory
Local memory to local memory
Global memory to global memory

•

Parallel IJO interface-Contains two bidirectional 8-bit input/ output ports, one 4-bit control
port, and three 16-bit programmable counter-timers.

•

Console port (DLART)-Provides DLll-compatible asynchronous serial communication.

•

Multiprotocol controller-Provides 2-channel synchronous/asynchronous serial IJO communication.

•

System ID switch-Sets the system identification address and establishes the KXJl 1-CA for
Q-bus or stand-alone operation.

•

Boot/Self-test switch-Selects bootstrap and firmware self-test operations.

•

Configuration jumpers-Electrical jumpers on the KXJll-CA circuit board that select some
of the hardware configuration options (other options are software-configurable).

See the KX]l 1-CA Single-Board Computer User's Guide for detailed information about the KXJl 1CA hardware.

B. 1.3 Using the KXT 11-CA or KXJ 11-CA as a Peripheral Processor
Peripheral processor applications help you off-load tasks from a conventional LSl-11 processor
application. This improves overall system performance by distributing the application task load.
You can add up to 14 peripheral processors (KXTs and/or KXJs) to a traditional LSl-11 (Q-bus)
system configuration in the same way you add other IJO device controllers. (See Figure B-3.)
The difference between the KXT or KXJ and conventional 1/0 devices is that the KXT and KXJ
are user programmable while conventional 1/0 devices are not.

B-6 KXT11-CA and KX]11-CA Peripheral Processors

Figure B-3:

Adding Peripheral Processors to Traditional LSl-11 Systems

USER
INTERFACE
r

.A.

ARBITER
CPU

PERIPHERAL
PROCESSOR

Ja
1'

•••

PERIPHERAL
PROCESSOR

,,
j~

Q-BUS

,,
~~

MEMORY

1/0

DEVICE

•••

1/0

DEVICE
ML0-822-87

•

Guaranteed response time-A dedicated KXT or KXJ can ensure a specific interrupt response
time.

•

Data collection and reduction-The arbiter is relieved of the overhead of the interrupts
required to control devices and the CPU Q-bus time required to refine and format the data.

•

Machine control-The arbiter processor gives high-level commands to the peripheral
processor. The peripheral processor translates the commands to the level required by
the device(s) and monitors progress. The arbiter application merely issues commands and
manages higher-level application tasks.

•

Communication protocol handling-The peripheral processor relieves the arbiter processor
from the tasks of handling communication line interrupts, packing/unpacking messages,
and formatting them. Only data is transferred to and from the arbiter.

KXT11-CA and KX]ll-CA Peripheral Processors

B-7

B. 1.3. 1 Peripheral Processor Hardware Configuration
The application system consists of one Q-bus arbiter CPU (for example, LSI-11/23, LSI-11/73,
or SBC-11/21-PLUS) and up to 14 peripheral .processors attached to the Q-bus. The KXT and
KXJ cannot be bus arbiters.
Communication between the arbiter and the peripheral processor takes place over the Q-bus
through the TPR. The TPR' s control, status and data registers, and vectors appear in the
arbiter's I/O page. Programs can access the registers in ways similar to those of IjO devices.
The peripheral processor's hardware configuration options determine where its TPR area appears
in the arbiter's I/O page.

B. 1.3.2 Peripheral Processor Application Software Configuration
A master application in the arbiter processor directs slave peripheral processor operations (Figure
B-4). Communication takes place over the Q-bus, using messages to transfer data and to control
the KXT or KXJ hardware and its application software. Communication can take place using the
TPR or the DTC. If desired, the peripheral processor can interrupt the arbiter application when
it completes the requested task.
Figure B-4:

Peripheral Processor Application Software Configuration

--- -

--- -- -

-Q-BUS-

commands and messages

OMA data transfers

KX
driver

__ J

OD
driver

KK
OD
driver
driver
_ _ _! _ _

arbiter application

peripheral
processor
application

LSl-11 PROCESSOR

KXT11-CA
or KXJ11-CA

I KK
I driver

_ _ L __

•••

peripheral
processor
application
KXT11-CA
or KXJ11-CA
ML0-824-87

B-8

KXT11-CA and KX/11-CA Peripheral Processors

B. 2 Developing KXT 1 1-CA and KXJ 1 1-CA Applications
This section describes both the procedures for developing a peripheral processor application and
the specific considerations for such applications.

B.2. l Partitioning the Application
The first step in developing applications using one or more KXTll-CAs or KXJll-CAs is to
determine if your application can be partitioned to take advantage of multiple processors. There
must be a set of processes that can be performed usefully in parallel and within the capabilities
of the KXT or KXJ hardware. In addition, it must be possible to direct and monitor the progress
of the process through messages or transfer of blocks of data. Some characteristics of processes
that are good candidates for KXT or KXJ applications are:

•

Input/Output processes with critical interrupt latency requirements-By assigning processes
with critical interrupt latency requirements to dedicated peripheral processors, you can
ensure that the rest of the application does not interfere with the service of critical devices.

•

Input/Output processes with a high frequency of interrupts-peripheral processors can
relieve the arbiter from the continual context switching required to process interrupt-driven
1/0.

•

Input/Output data reduction processes-By assigning one or more peripheral processors to
1/0 processes that require large quantities of input data and produce a small amount of
output, you can save arbiter processing time. The peripheral processor receives the data,
decodes it, and reduces it to the required subset, discarding the rest.

•

Computational processes-The KXT or KXJ can perform parallel computational operations
by using the DTC to transfer data directly to its memory, perform the operation, and transfer
the data back to Q-bus memory. On a KXJ, if the data is in KXJ memory, it can be accessed
directly from the arbiter and the KXJ. There is then no need to transfer the data from Q-bus
memory to local memory and back.

•

Real-time control functions-You can assign a KXT or KXJ to control functions that require
constant interaction with a device but little interaction. with the main application. The
arbiter can then direct the peripheral processor with high-level commands.

B.2.2 Designing the Peripheral Processor Application System
For a peripheral processor application, you must design an application-level communication
protocol between the arbiter application and the peripheral processor to command the peripheral
processor (conceptually an intelligent 1/0 device) to perform its functions-for example, start,
stop, and transfer data. The commands are generally formatted into messages and sent through
the 2-port RAM (TPR). MicroPower/Pascal provides the KX/KK device driver pair to facilitate
TPR communication.
In addition to commands, data can be sent to the peripheral processor either by using the TPR
to send data as messages or directly by using the DMA transfer controller (DTC). (The choice of
method is governed by such criteria as the amount of data and the frequency of transmission.)
When you use the DTC, the arbiter typically passes to the peripheral processor a message
specifying the location (Q-bus physical address) and size of the data buffer to transfer. The
peripheral processor application then directs the DTC locally to make the transfer.

KXT11-CA and KX/11-CA Peripheral Processors

B-9

In general, you should use the TPR to send small or infrequently issued messages. You should
use the DTC to send large or frequently issued messages, especially if it can be done in parallel
with other peripheral processor processes. When to use the DTC depends on the application
and must be determined on a case-by-case basis.

B.2.3 Software and Hardware Configuration Guidelines
This section tells you how to configure the MicroPower/Pascal software and KXTll-CA and
KXJl 1-CA hardware. There are four main areas of concern:
•

The location of RAM and ROM

•

The system configuration, stand-alone or peripheral processor

•

The 1/0 device options

•

The bootstrap start-up option

B.2.3. l Configuring Memory
KXTll-CA native memory has eight jumper-selectable configurations (maps), as shown in Figure
B-5. Each map defines a particular combination of native (local) RAM and user-installed RAM
or ROM residing in the user sockets of the KXTl 1-CA.

B-10

KXT11-CA and KX/11-CA Peripheral Processors

Figure B-5:

KXT l 1-CA Memory Map Conftgurations
177777
2KB 1/0 PAGE

2KB 1/0 PAGE

4KB Native Firmware ROM

4KB Native Firmware ROM
160000

2KB Self-te~ .Qv!:.r~y

BKB

Native
Firmware
Extension

140000

Native
Firmware
Extension

Reserved 64 Bytes
120000

User

16KB
User

ROM/RAM

100000

Reserved 64 Bytes

Reserved
64 Bytes

Native
RAM
24KB

Native
RAM
32KB

User

16KB
User

32KB
User

ROM/RAM

MAP4

MAPS

MAP6

MAP?

60000

Native
RAM
32KB

40000

20000

0
MAPO

MAP 1

MAP2

MAP3

ML0-823-87

B.2.3.2 Memory Configuration Steps
When you configure KXTl 1-CA memory, you must specify parameters in the software
configuration file and install jumpers on the KXTl 1-CA circuit board:
1.

Select a map according to the requirements of your application.

Specify the number of the map you selected in the KXTl lC configuration file macro.

Install additional ROM or RAM in the user sockets.
Note
If your application uses ROM, consider substituting RAM in its place during
debugging so you can use the P ASDBG debugging program.

KXTl 1-CA and KXJl 1-CA Peripheral Processors

B-11

4.
5.

In the configuration file's MEMORY macro, specify each contiguous block of RAM and
ROM defined by the selected map and the ROM or RAM installed in the user sockets.
Install the map selection jumpers on the KXTl 1-CA circuit board. (The KXTl 1-CA SingleBoard Computer User's Guide shows the location of these jumpers.)

Select an appropriate setting for the boot/self-test switch. (See Table B-2.)

B.2.3.3 Memory Selection Rules
MicroPower /Pascal software can use any KXTl 1-CA memory map option as long as you
observe the following configuration rules:
1.

You can select any memory map for RAM-only applications that is appropriate for the type
of RAM devices installed in the user sockets.

You can select maps 4, 5, 6, or 7 for MicroPower/Pascal applications that use ROM.
MicroPower/Pascal memory allocation rules require that you configure all ROM in memory
addresses lower than those assigned to RAM. Thus, you should not specify maps 0 to 3 if
your MicroPower/Pascal application uses ROM.

If your application will be loaded from TU58 DECtape II, you must configure RAM to start

at address 0.
4.

Do not configure your application to use the highest 64 bytes of native RAM. This area
is reserved for KXTl 1-CA native firmware. The location of this 64-byte area depends on
which memory map you select with the boot/self-test switch. (See Figure B-5.) If you are
going to use RAM in the user sockets, assign it to low memory addresses (maps 4 to 7).

Do not configure your application to use nonexistent memory addresses (address space
identified as NXM in Figure B-5).

Never configure the SK-byte block of memory addresses shown in maps 3 and 6 and
designated SK-byte Native Firmware Extension. These addresses reference locations in the
native firmware socket that are outside the address space of the native firmware ROM
provided by DIGITAL.

Table B-1 summarizes MicroPower/Pascal map usage.'
Table B-1:

B-12

MicroPower/Pascal Usage of KXT 11-CA Memory Maps

Map

Usage

32K bytes of native RAM; 4K bytes ROM/RAM in user sockets mapped high. Do not
allocate memory between 77700 and 77777.

32K bytes of native RAM; BK bytes ROM/RAM in user sockets mapped high. Do not
allocate memory between 77700 and 77777.

32K bytes of native RAM; 16K bytes ROM/RAM in user sockets mapped high. -Do not
allocate memory between 77700 and-77777.

32K bytes of native RAM; 16K bytes ROM/RAM in user sockets mapped high. Do not
allocate memory between 77700 and 77777.

KXT11-CA and KX]ll-CA Peripheral Processors

Table B-1 (Cont.):

MicroPower/Pascal Usage of KXTl 1-CA Memory Maps

Map

Usage

32K bytes of native RAM; 4K bytes ROM/RAM in user sockets mapped low. Do not
allocate memory between 137700 and 137777.

32K bytes of native RAM; SK bytes ROM/RAM in user sockets mapped low. Do not
allocate memory between 137700 and 137777.

32K bytes of native RAM; 16K bytes ROM/RAM in user sockets mapped low. Do not
allocate memory between 137700 and 137777.

24K bytes of native RAM; 32K bytes ROM/RAM in user sockets mapped low. Do not
allocate memory between 157700 and 157777.

B.2.4 Configuring the KXT 11-CA or KXJ 11-CA System Environment
This section tells you how to set up the KXTl 1-CA or KXJll-CA for its system environment.
The features you can select include stand-alone operation or peripheral processor operation
and the system's start-up options (application bootstrap device, console ODT operation, and
self-test program execution). When you select these features, you must configure jumpers and
switches on the KXTll-CA or KXJll-CA circuit board and change some of the parameters of
the KXTl lC or KXJllC macro in the configuration file.
The system ID switch and the boot/self-test switch specify to the native firmware the desired
environmental and operational features of the KXTll-CA or KXJll-CA. The boot/self-test
switch determines when the self-tests will be performed and how the application program will
be initialized.

B.2.4. 1 Selecting Stand-Alone or Peripheral Processor Operation
You can select stand-alone or peripheral processor operation with the system ID switch on the
KXTl 1-CA circuit board.
To use stand-alone mode, select switch position 0 or 1. In stand-alone mode, the TPR is
disabled, since no Q-bus is required. To use peripheral processing mode, select switch positions
2 to 15. You can configure a maximum of 14 peripheral processors (KXTll-CAs and/or
KXJl 1-CAs) in a Q-bus system by selecting switch positions 2 to 15.
In peripheral processing mode, the TPR is enabled and connected to the Q-bus. Each switch
position selects a different base address for the TPR registers in the arbiter's 1/0 page. The
switch selects addresses from a high or low range, depending on whether or not you install the
TPR base address jumper on the KXTl 1-CA or KXJll-CA circuit board.
If you are using a KXJll-CA as a peripheral processor for a board later than etch revision Fl,
configure the board so that the J-11 processor does not request a Q-bus grant for the bus lock
instructions (TSTSET, WRTLCK, and ASRB). This action disables both the Q-bus lock capability
and DMA bus timeouts for those instructions.

Section B.5 lists system ID switch settings and the associated IjO page base addresses of the
TPR. When selecting the TPR base addresses, avoid conflicts between the KXTl 1-CA or KXJl 1CA processor's TPR 1/0 page registers and 1/0 page registers allocated to other devices on the
application system's Q-bus.

KXT11-CA and KXJ11-CA Peripheral Processors

B-13

Each system ID switch number you select must be unique among all system ID switch numbers
for KXTll-CA or KXJll-CA processors on the same Q-bus. The number need not be in
a continuous sequence with the system ID switch numbers selected for other KXTl 1-CA or
KXJll-CA processors on the Q-bus.
Specify the CSR address implied by the system ID switch and TPR base address jumper setting
you select in the KX device driver prefix file. You can insert this information in the file
manually with an editor or automatically during execution of MPBUILD, as described in the

MicroPower /Pascal System User's Guide.
B.2.4.2 Selecting KXTl 1-CA or KXJl 1-CA Initialization and Self-Test Options
KXTl 1-CA and KXJl 1-CA firmware provide initialization and diagnostic self-test functions that
are selected by the boot/self-test switch on the KXTll-CA and KXJll-CA circuit boards. They
are power-up features that provide for hardware initialization, automatic self-tests, console ODT,
application bootstrapping, and execution of control routines that handle local restart interrupts to
allow the arbiter to gain control of the KXTl 1-CA or KXJl 1-CA. Tables B-2 and B-3 summarize
the boot/self-test switch functions for the KXT and KXJ respectively.

B-14 KXTl 1-CA and KX]l 1-CA Peripheral Processors

Table B-2:

lnltlallzatlon/Self-Test Options for the KXT 11-CA

Boot/Self-Test Switch Position*
Initialize/Test
Feature

Start-up in ROM

x x x

Boot from TU58
DECtape

x x

Load RAM from
arbiter and run

Enter debugging
(ODT) mode
Perform user
ROM tests

Perform auto
self-tests

x x x

x
x

x
x x

Dedicated test
mode
Reserved

*Switch positions 7 and 11 to 15 are reserved. If you apply power to
the KXT11-CA with these positions selected, it will not function and
the LED display will indicate a fatal error.
Do not use switch
positions 8, 9, or 10 when using MicroPower/Pascal. These positions
are for dedicated testing.
ML0-829-87

KXT11-CA and KX/11-CA Peripheral Processors

B-15

Table B-3:

Initialization/Self-Test Options for the KXJ-11-CA

Boot/Self-Test Switch Position*
Initialize/Test
Feature

Start-up in ROM

Boot from TU58
DECtape

Perform user
ROM tests

Enter debugging
(ODT) mode

Load RAM from
arbiter and run

Perform auto
self-tests

x
x

Dedicated test
mode

x x
x

x
x

Reserved
*Do not use switch positions 7 through 15 when using MicroPower/Pascal.
ML0-828-87

ROM Application Start-up-Boot/Self-test switch positions 0, l, and 2 allow you to execute a
ROM application. The native firmware transfers control to the ROM code by emulating a trap
to location 24. Consequently, you must configure the ROM to start at address 0 (maps 4 to 7)
to ensure that the contents of vector 24 are preserved.
Switch position 0 inhibits the automatic self-tests. By using this switch position, you can reduce
application start-up time to a minimum. Choose this position only when necessary to maintain
acceptable application performance.
Switch position 1 inhibits the user ROM checksum test. This allows you to start an application
that was loaded into ROM that contains no checksum or that was loaded into ROM with a
checksum that was calculated by an algorithm that is incompatible with the test. Section B.9
describes the procedure to use with the DECprom program to calculate and program ROM
checksums for KXTl 1-CA and KXJl 1-CA applications. The KX.Tl 1-CA Single-Board Computer
User's Guide and the KX/11-CA Single-Board Computer User's Guide describe the checksum
algorithms for the two boards.

B-16

KX.Tl 1-CA and KX.f11-CA Peripheral Processors

Use switch position 2 if your ROM application contains a user ROM checksum.
TU58 and RSP Bootstrap-If you are going to load your application image from a TU58
DECtape II drive or an RSP (radial serial protocol) link, select switch position 3. This causes
the TU58 primary bootstrap to execute on power-up and load your application using RSP from
a TU58 DECtape II subsystem or other system through SLUl (DLART). Once the primary
bootstrap begins receiving the boot block from the TU58, it checks that the first word of the
block is in the range 240 to 277 (octal). If true, it considers this block to be a valid boot block,
loads the remaining blocks into RAM, and starts the program. If the first word's value is invalid,
the primary bootstrap continues to check, alternating between unit 0 and unit 1, until it finds a
valid boot block.
When your application will be loaded from TU58 DECtape II, you must configure RAM to start
at address 0.
Loading from the Arbiter-You can load your peripheral processor application from a system
storage device via the arbiter. If your arbiter application runs under MicroPower/Pascal, you
can use the Pascal procedure KXT_LOAD or KXJ_LOAD described in Section B.10. If your
arbiter application runs under RSX-11 or RT-11, you can use the KUI utility program described
in the Peripheral Processor Tool Kit/RSX Reference Manual or Peripheral Processor Tool Kit/RT

Reference Manual.
Boot/Self-test switch positions 5 and 6 instruct the KXTll-CA or KXJll-CA to wait for a
command over the Q-bus either from KXT_LOAD or KXJ_LOAD or from KUI. The automatic
self-tests are performed first if you select switch position 5; they are inhibited if you select
switch position 6.
Automatic Self-Tests-The automatic self-tests are a subset of the self-test functions that the
native firmware provides. These tests are run when the boot/self-test switch is in positions 1,
2, 3, and 5.
The automatic self-tests include a:
•

CPU test

•

RAM test

•

ROM test, native and user (if selected)

•

CSR test, NXM test of all native CSRs and the TPR (read-only test)

•

DMA test, local-to-local DMA transfers

•

BEVENT test (KXJl 1-CA only)

The tests report diagnostic errors, using the LED display on the KXTl 1-CA or KXJl 1-CA
circuit board and the TPR system control registers. The LED display reports automatic self-test
diagnostic data and general KXTl 1-CA or KXJl 1-CA status. Control registers 2 and 3 of the
TPR contain the test status information on completion of the nonfatal tests. Register 2 indicates
which tests failed, and register 3 specifies the type of failure. Register 3 is overwritten only if
an error was encountered and will contain the valid discrete error code for the last test that
found an error.

KXT11-CA and KXJ11-CA Peripheral Processors B-17

The native firmware considers failure of the following self-tests as a fatal condition and will not
allow the application to run:

•
•
•
•

CPU test
Native RAM test (KXTll-CA only)
Native ROM test
CSR test (TPR portion)

The tests report fatal errors only in the LED indicators, since the firmware disables the TPR
under these conditions.
The results of the remaining nonfatal tests do not prevent the application from running and are
reported in the LED display and the TPR system control registers. The user application should
check for these nonfatal error conditions to see if they affect the application.
The KXTll-CA Single-Board Computer User's Guide and the KX]ll-CA Single-Board Computer
User's Guide discuss the meaning of all LED displays and the TPR registers and associated error
codes.
If you do not select the automatic self-tests, you can reduce application start-up time to a

minimum. However, these tests are useful diagnostic tools. You should bypass them only when
necessary to maintain acceptable application performance.

Debugging (ODT) Mode-When you use boot/self-test switch position 4, the KXTll-CA enters
console ODT through SLUl (DLART). Select this switch position when you want to debug your
application with PASDBG.
Dedicated Test Mode-This mode is for dedicated diagnostic testing; the tests permit no
execution of application code. On a KXTl 1-CA you select the tests with boot/self-test switch
positions 8, 9, and 10. Use of these switch positions causes RAM to be mapped to low memory
addresses by overriding the selected memory map jumper settings. ROMs jumpered for high
memory mapping are mapped to their corresponding positions in low memory.
Switch positions 8 and 9 select the automatic self-tests and I/O port loopback tests; position 9
includes the ROM test. You must install loopback connectors on the I/O ports for these tests.
Switch position 10 selects the automatic self-tests and then causes the KXTl 1-CA to wait for
self-test commands through the TPR from the arbiter.
The KXTll-CA Single-Board Computer User's Guide and KX]ll-CA Single-Board Computer User's
Guide provide further information.
On a KXJll-CA, switch position 7 selects the automatic self-tests and I/O port loopback tests.

Note
On a KXJll-CA, do not use boot/self-test positions 8-15 if you are using
MicroPower /Pascal.

B-18 KXTll-CA and KX]ll-CA Peripheral Processors

B.3 KX/KK Device Driver Communication Protocol
This section describes the protocol that the KX and KK device drivers use to communicate with
one another through the 2-port RAM (TPR). It contains information to assist you in designing
your own KX or KK device driver, so it can communicate with the DIGITAL-supplied KX or
KK driver. The KX and KK drivers are used when the KXTl 1-CA or KXJll-CA is set up for
peripheral processor operation.
The protocol provides a master-slave relationship between the arbiter processor and the
peripheral processor. (Do not confuse master-slave with the bus-master/bus-slave hardware
concept.) The KK driver running on the peripheral processor uses the TPR to emulate a
traditional Q-bus peripheral device. The KX driver running on the arbiter communicates with
this device. The protocol implements a request-reply dialog between the arbiter on the Q-bus
and the peripheral processor to ensure correct and complete transfer of data between them.
The arbiter is the master in all transactions with the peripheral processor, which is the slave
(see Figure B-6). The peripheral processor must receive a command from the arbiter before
passing any data to the arbiter or before receiving any data from the arbiter.

B.3. l Communication Mechanisms
The basic TPR hardware communication mechanisms are:
•

Command register for each data channel-used by the master to pass commands to the
slave

•

Status register for each data channel-used by the slave to pass error and operational status
to the master

•

Data registers-4 bytes for data channel 0 and 12 bytes for data channel 1-used for passing
data between the master and the slave

•

QIR register in the slave-used by the slave to interrupt the master

KXTl 1-CA and KX/11-CA Peripheral Processors

B-19

Figure B-6:

KX/KK Device Driver Communication Linkage

~-- -

- - MASTER,-- - - -_.;...- - - - - -SLAVE- -

----..j

Arbiter

Two-Port RAM

Peripheral
Processor

----Data
Channel 1

...
KX
Driver

-- ------

- -- -...
L{
I
I
-

Data
ChannelO

-- --

Data Register

-- .....-

Status Register

Command Register

... I

Data Register
Status Register

-- ----......

Sy stem Control Re gisters

Data
Channel 1

Command Register

...

QIR

],
t-'

.....

---Data

KK
Driver

ChannelO

-- ------~

System Control Registers

ML0-825-87

The interface between the arbiter and the peripheral processor consists of layers of software.
The lowest layer contains MACRO definitions for the bits in the command and status registers of
the TPR. The next layer consists of the KX and KK drivers that move data between a peripheral
processor process and a process in the arbiter.
The protocol provides the arbiter with commands that cause the following:

B-20

•

Device initialization of the peripheral processor

•

Arbiter read request/peripheral processor write reply sequence

•

Arbiter write request/peripheral processor read reply sequence

•

Interrupts from the peripheral processor to the arbiter to be enabled or disabled

KXT11-CA and KX/11-CA Peripheral Processors

The following sections describe the special meanings the protocol assigns to the TPR registers
in the context of KX/KK driver operations. Figure B-7 shows the TPR's general layout.
Figure B- 7:

TPR Register Layout

Base+36---

Data Register
Data Register
Data Register (note 5)
Data Register (note 5)

Data Channel 1

Data Register
Data Register
KW.DST
KW.DCC
Base+20---

Status Register (arbiter read-only)
Command Register (note 1)
Data Register
Data Register

KW.DST
KW.DCO
Base+ 10 - - -

Status Register (arbiter read-only)
Command Register (note 2)
Data Register
Data Register
Status Register (arbiter read-only)

Base+OO - - -

Command Register (note 3)

Peripheral
Processor
System Control
Registers (note 4)

t
ML0-815-87

Note 1

Writing to this register from the arbiter causes a level 5 interrupt through vector 124
on the peripheral processor.

Note 2

Writing to this register from the arbiter causes a level 5 interrupt through vector 120
on the peripheral processor.

Note 3

Writing to this register from the arbiter causes the peripheral processor to restart the
native firmware.

Note 4

The system control registers are not part of the protocol. They are used by the KUI
utility program, diagnostic programs, and possibly user-written programs.

Note 5

Generally, the TPR at base+30 is a command register for a -third data channel and
the TPR at base+32 is a status register for that channel. For the KX/KK protocol;
the second and third data channels are combined to form a larger data channel. To
make this work, the TPR interrupts for this channel must be disabled.

KXT11-CA and KXJ11-CA Peripheral Processors

B-21

B.3.2 KX/KK Protocol Definition
In the protocol, a data channel's command register (KW.DCO in Figure B-7) controls ownership
of the contents of the data channel's data register. If the command register is zero, the KX
driver owns the data channel's registers. If the command register is nonzero, the KK driver
owns them. A data channel's status register (KW.DST in Figure B-7) is owned by the KK driver.
The KX driver can only read the status registers.
If the KX driver communicates with the KK driver with interrupts disabled, the KX driver must
poll the command register (KW.DCO), using it as the ownership flag for the data channel. To
poll the KK driver, the KX driver must:

Poll the command register until it becomes zero. The zero condition means the KK driver
is idle and any previous command has been completed.

Fill in the data registers as necessary (for example, for a write). Then issue a command
by writing it into the command register. This procedure causes the KK driver to execute
the command. Once the command register has been written, the KX driver cannot alter
the contents of any of the data channel's registers. Consequently, the KX driver must write
the data being transferred by the command into the data registers before the command is
issued.

Poll the command register until it becomes zero. At that time, the status register data
reflects the status of the previous command. The KX driver should check the status register
and can then issue further commands (as in step 2).

Note
In the MicroPower/Pascal implementation, the KX driver always tells the
KK driver to use the mode with interrupts enabled.
If the KX driver communicates with the KK driver with interrupts enabled, the KK device driver
uses the Q-bus interrupt register (QIR) to signal the KX driver that an operation has been
completed. The KK driver interrupts the KX driver after a command has been completed, the
proper status and/or data bits have been set, and the command register has been cleared.

By using the interrupt-on-data-av~ilable (KC.IDA) and interrupt-on- data-requested (KC.IDR)
bits of the Enable Interrupts command, the KX driver can instruct the KK driver to interrupt
the KX driver when the KS.DA and/or KS.DR status register bits change from 0 to 1. This
mechanism allows the KK driver to interrupt the KX driver when a user write or read request
comes in on the KK side.
With interrupts enabled, the KX driver should still check the command register to make sure
it has a value of 0 before filling in the data and issuing a command. However, the KX driver
does not need to poll the command register after that because the KX driver interrupts when it
completes executing the command.

B-22

KXT11-CA and KX]11-CA Peripheral Processors

B.3.2. 1 KX and KK Driver Transactions
The transactions between the KX driver and the KK driver are:
1.

The KX driver tests the command register. If it is zero, the driver proceeds to the next step;
if it is nonzero, the driver repeats this step.
KK Driver

KX Driver
Data Register
Status Register

Is it zero? ..,.__

Command Register
ML0-816-87

Since the command register is zero, the KX driver owns the data channel and can write
data to or read data from the data registers, as implied by the pending command. The KX
driver issues the command by writing it to the command register. The act of writing the
command to the command register, thereby making it nonzero, switches ownership of the
data channel to the KK driver.
KX Dr~ver
Read/Write data .._....

KK Driver
Data Register
Status Register

Command ---..

Command Register
ML0-817-87

The KK driver is interrupted by the KX driver writing to the command register. The KK
driver now owns the data channel. It reads and validates the command. During this time,
if interrupts are enabled, the KX driver can wait for another user request.
KX Driver

KK Driver
Data Register
Status Register
Command Register

- - . Validate the command
ML0-818-87

KXT11-CA and KX/11-CA Peripheral Processors

B-23

If the KK driver detects an error in the command, it reports this error in the status register

and proceeds with step 4.
KX Driver

KK Driver
Data Register
Status Register

._.__ Channel Error Status

Command Register
ML0-819-87

If the KK driver detects no error, it performs the command, moves any data required by

the command into or out of the data registers, and writes the status of the channel into the
status register.
KX Driver

KK Driver
Data Register
Status Register
Command Register

~ Read/Write any data

..,__ Channel Status
_ . . Read the command
ML0-819A-87

The KK driver completes the transaction by zeroing the command register, thus transferring
ownership of the data channel back to the KX driver. If interrupts are enabled, the KK
driver interrupts the KX driver by queueing an interrupt to the QIR. The vector written to
the QIR is the vector that was passed in the enable interrupts command used to initialize
the interface.
KX Driver

KK Driver
Data Register
Status Register
Command Register

..,_. Zero
ML0-820-87

B-24

KXT11-CA and KX]11-CA Peripheral Processors

Finally, the KX driver regains ownership of the data channel in one of the following ways:
•

Polling the command register and testing for zero

•

Waiting for an interrupt and testing the command register on being interrupted to find
it is zero
Once it gains ownership, the KX driver checks the status register for error and status
information and reads from or writes to the data registers, as implied by the pending
command. From this point the cycle repeats.
KX Driver

KK Driver

Read/Write data ..._..

Data Register

Status .,.__

Status Register

Is it zero?

Command Register
ML0-821-87

B.3.2.2 Message Communication Between the KX and KK Drivers
The KX driver controls the passing of messages. Data is passed across the TPR interface on a
channel only when the KX driver issues a read data or write data command. Before any user
read or write requests are made to the KX driver, the KK driver must be running (that is the
peripheral processor has started) or an error occurs. For each user request on the KX side, there
must be a corresponding user request on the KK side. If there is a user read request on the KX
side, there must be a corresponding user write request on the KK side and vice versa.
In the transactions between the KX and KK drivers over the TPR (Section B.3.2.1), the number
of bytes in a data transfer is limited by the number of data registers in the channel (4 bytes
for data channel 0 and 12 bytes for data channel 1). However, at the user application-program
level of communication, the protocol provides for longer messages by using an end-of-message
(EOM) indicator. Thus, a user read or write request to the KX or KK driver causes multiple
transactions over the TPR if the message is larger than the size of the data channel.
When the KX driver receives a user write request from the arbiter program, it performs as
many TPR write data operations as necessary to send the entire message. The byte count in
the command for all operations except the last is the size of the data channel. For each KX
write data operation, the KK driver completes the transaction by moving the data from the TPR
channel's data registers to the user's buffer. On the last write operation, the KX driver sets the
EOM indicator in the data channel's command register. The byte count for the last write is the
number of bytes remaining in the message. The EOM indicator informs the KK driver that all
data has been sent for this user request. Therefore, the arbiter program's user write request and
the peripheral processor program's user read request are both complete.
When the KX driver receives a user read request from the arbiter program, it performs as
many read data operations as necessary to receive the entire message. For each KX read data
operation, the KK driver completes the transaction by moving data from the user's buffer to the
TPR data registers. The byte count in the command register for all operations except the last
is the size of the data channel. When the last data from the user's buffer is placed in the data
registers, the KK driver sets the EOM indicator in the data channel's status register. The byte

KXT11-CA and KX/11-CA Peripheral Processors

B-25

count for the last read is the number of bytes left in the message. The EOM indicator informs
the KX driver that all data has been sent for this user request. Therefore, the arbiter program's
user read request and the peripheral processor program's user write request are both complete.
Normally, you should make sure that the number of bytes in the user read request on one
side equals the number of bytes in the corresponding user write request on the other side.
However, if the user write request from either side is for fewer bytes than the user read request
on the other side, the number of bytes received is less than the number of bytes specified in the
user's read request. If the user's write request from either the arbiter program or the peripheral
processor program writes more data than the corresponding user read request specifies on the
other side, a data overrun error occurs. For user read requests on the KX side, when the system
detects a data overrun, the KX driver issues a reset command to terminate the user's write
request on the KK side.

B.3.2.3 Synchronizing KX and KK Device Driver Operations
To synchronize TPR operations, the KX and KK drivers use three interrupts:
•

On command completion

•

When data is available (indicating that the KK driver has a pending user write request)

•

When data is requested (indicating that the KX driver has a pending user read request)

These interrupts are issued by the KK driver to the KX driver. With the last two interrupts
enabled, the KX driver does not issue a write data command for a user write request, unless
the data-requested bit is set in the TPR status register; nor does it issue a read data command
for a user read request unless the data-available bit is set in the TPR status register. In either
case, it waits for an interrupt to come in from the KK driver, indicating that the appropriate
user request is pending on the KK side.
The interrupts for data available and data requested come in asynchronously to the KX driver,
which means that the KX driver cannot tell when the interrupt comes in. A potential for race
conditions occurs if a data-available interrupt comes in while the KX driver is filling in the TPR
registers to start a write, or if a data-requested interrupt comes in while the KX driver is filling
in the TPR registers to start a read. To avoid the possibility of the driver's filling in the registers
part way, having an interrupt come in, and then the interrupt service routine's writing over the
partially filled TPR area, use the following method:
1.

Issue all read data and write data commands from the interrupt service routine. This method
precludes the possibility of the interrupt service routine's writing over a partially filled-in
TPR channel.

When a user read or write request comes in on the KX side, start the transaction by issuing
from driver level either an enable interrupts command (if interrupts are not yet enabled) or
a Get Status command (if interrupts are enabled). In either case, the KK driver executes the·
command and interrupts back to the KX driver when the command finishes. The interrupt
service routine, which is entered when the interrupt comes in, can then issue the first read
data or write data command to continue the read or write request.

Note
The Get Status command is preferred in this instance because a No-op is a
0 command, which can cause protocol problems: 0 in the command register
normally indicates that the KX driver has control.

B-26

KXT11-CA and KX/11-CA Peripheral Processors

From this point on, the rest of the message is sent, in pieces dictated by the size of the TPR
data area, by the KX interrupt service routine when an interrupt comes in from the KK driver.
This interrupt typically is for completion of the previous command. The KX driver interrupt
service routine can check the data-requested bit in the TPR status word and a local flag to
find out whether to continue a write. The local flag indicates whether a write is in progress.
Similarly, the interrupt service routine can check the data-available bit and a local flag, to find
out whether a read is in progress, to know whether to continue a read. The following sections
define the command and status registers. The definitions are defined in the source of the KX
driver (KX.MAC).

B.3.3 Command Register Definition
151413121110 9 8 7 6 5 4 3 2 1 0
x

KW.DCO

Command field (KC.COM)
._____ _ _ _ _ Interrupt when data available (KC.IDA)
.....___ _ _ _ _ _ Interrupt when data requested (KC. IDR)
....___ _ _ _ _ _ _ _ Length field (KC.LEN)
" ' " - - - . : - - - . . . . , . ; - - - - - - - End of message (KC.EOM)
v
~---------- Vector number field (KC.VEG)
ML0-826-87

Bit 5 is always set to 0. Bits KC.IDA, KC.IDR, and KC.EOM and fields KC.LEN and KC.VEC
have meaning for specific commands only.

B.3.3. 1 Command Field (KC.COM)
The command field, KC.COM, contains one of the following commands, issued to the KK driver
from the KX driver. You can use the codes (which are in decimal) in your program as word
indexes in a table.
No-op Command KC$NOP (Code 0)
A null operation. The KK driver places the data channel's status in the status register (KW.DST)
and clears the command register (KW.DCO). If interrupts are enabled (KC$EI command), a
Q-bus interrupt occurs.
Reset KK Driver to KX Driver Command KC$RSM (Code 2)
Resets ownership of the TPR to the KX.driver. The KK driver reports the channel's status in the
status register (KW.DST) and clears the command register (KW.DCO). If interrupts are enabled
(KC$EI command), a Q-bus interrupt occurs.
This command is used to complete a user read request on the KX side and the corresponding
user write request on the KK side that terminates because of an error, for example, buffer
overflow. This procedure notifies the KK driver that it should complete its write request and
that there are no more read data commands for this read/write request.

KXT11-CA and KX/11-CA Peripheral Processors

B-27

Enable Interrupt Command KC$EI (Code 4)
Enables interrupt mode in the KK driver. The address of the vector to use must be in the
KC.VEC field (bits 8 to 15) of the command register and must be the vector address divided by
four.
After this the KK driver interrupts the KX driver when it finishes executing a command. The
KK driver sets the interrupt-enabled bit (KS.JEN) in the status register when the driver executes
this command.
If the interrupt-when-data-available bit (KC.IDA) is also set when this command is issued, the

KK driver also interrupts the KX driver whenever new data is available (when a new user write
request is processed on the KK side). The KK driver uses a local flag to keep track of whether
this mode is active.
If the interrupt-when-data-requested bit (KC.IDR) is also set when this command is issued, the

KK driver also interrupts the KX driver whenever new data is requested (when a new user read
request is processed on the KK side). The KK driver uses a local flag to keep track of whether
this mode is active.
Disable Interrupt Command KC$DI (Code 6)
Disables interrupt mode in the KK driver. The KK driver places the channel's status in the
status register, including clearing the interrupt-enabled bit (KS.JEN), and clears the command
register. Completion of the command never interrupts the KX driver. After this, the KK driver
does not interrupt the KX driver unless an enable interrupt command is issued.
Get Status Command KC$GS (Code 8)
Instructs the KK driver to place its internal status in the data registers. This status information
is currently undefined and reserved by DIGITAL. The command is effectively the same as the
No-op command. The KK driver places the channel status in the status register ahd clears the
command register. If interrupts are enabled (KC$EI command), a Q-bus interrupt occurs.
Read Status Command KC$SS (Code 10)
Instructs the KK driver to read the new internal status from the data registers. This status
information is currently undefined and reserved by DIGITAL. The command is effectively the
same as the No-op command. The KK driver places the channel's status in the status register
and clears the command register. If interrupts are enabled (KC$EI command), a Q-bus interrupt
occurs.
Read Data Command KC$RD (Code 12)
Causes the KK driver to place bytes of data into the channel's data registers. The maximum
number of bytes to transfer is specified by the data length field KC.LEN (see Section B.3.3.4).
The KK driver must be ready to send the data (as indicated by the data-available KS.DA bit in
the status register) or it will return a no-data-available (KE$NDA) error in the status register.
This indicates a protocol error if the interrupt-when-data-available mode is being used. In that
mode, the KX driver does not issue this command when a user read request is made on the
KX side if the data-available (KS.DA) bit is not set. Instead, the KX driver issues the read
data command only after the KK driver receives a user write request and interrupts with the
data-available (KS.DA) bit set.

B-28

KXT11-CA and KX/11-CA Peripheral Processors

The KK driver:
•

Moves the data into the data registers

•

Sets the number of bytes being transferred in the actual length field (KS.ALN) of the status
register

•

Sets the end-of-message bit (KS.EOM) in the status register if this is the last transfer in the
user message

•

Sets any other status

•

Clears the command register and interrupts the arbiter if interrupts are enabled

If the user buffer being filled with data on the KX side overflows, the KX driver reports a buffer
overflow error and issues a reset KK-driver-to-KX-driver command (KC$RSM) thereafter.

Write Data Command KC$WD (Code 14)
Causes the KK driver to accept bytes of data from the channel's data registers. The maximum
number of bytes to transfer is specified by the data length field KC.LEN (see Section B.3.3.4).
The KK driver must be ready to accept the data (as indicated by the data-requested KS.DR bit
in the status register) or it returns the no-data-requested (KE$NDR) error in the status register.
This procedure indicates a protocol error if the interrupt-when-data-requested mode is being
used. In that mode, the KX driver does not issue this command when a user write request is
made on the KX side if the data-requested (KS.DR) bit is not set. Instead, the KX driver issues
the write data command only after the KK driver receives a user read request and interrupts
with the data-requested (KS.DR) bit set. If the user buffer being filled with data on the KK side
overflows, excess data is discarded and the KK driver returns a buffer overflow (KE$0VR) error
status.
The KK driver:
•

Examines the data length field (KC.LEN) for the number of bytes being transferred

•

Removes the number of bytes specified by KC.LEN from the data registers

•

Tests for the EOM bit (KC.EOM) to find if this is the last transfer in the message

•

Places its status in the status register

•

Clears the command register and interrupts the arbiter if interrupts are enabled

B.3.3.2 Interrupt-When-Data-Available Bit (KC.IDA)
When set to l, the interrupt-when-data-available bit, KC.IDA, indicates that the KK driver should
interrupt the KX driver when the data-available bit (KS.DA) of the status register changes from
0 to 1. The KK driver sets the KS.DA bit when a new user write request is processed on the KK
side. The bit is cleared when a write request has been completed unless another write request
is pending. The KC.IDA bit is meaningful only when used with the KC$EI command.

KXT11-CA and K.X]11-CA Peripheral Processors

B-29

B.3.3.3 Interrupt-When-Data-Requested Bit (KC.IDR)
When set to 1, the interrupt-when-data-requested bit, KC.IDR, indicates that the KK driver
should interrupt the KX driver when the data-requested bit (KS.DR) in the status register
changes from 0 to 1. The KK driver sets the KS.DR bit when a new user read request is
processed on the KK side. The bit is cleared when a read request has been completed unless
another read request is pending. The KC.IDR bit is meaningful only when used with the KC$EI
command.

B.3.3.4 Data Length Field (KC.LEN)
The data length field, KC.LEN, indicates the maximum number of bytes to be transferred by
a read-data (KC$RD) or write-data (KC$WD) command. This field is meaningful only when
used with the KC$RD and KC$WD commands. The maximum length is the number of bytes
which can fit in the data registers for the channel (4 for channel 0 and 12 for channel 1) or the
number of bytes remaining in the message, if the number of bytes remaining is less than the
number of bytes which can fit in the data registers for the channel.

B.3.3.5 End-of-Message Bit (KC.EOM)
When set to l, the end-of-message bit, KC.EOM, indicates that the last byte in the current write
ends the user message. This bit is meaningful only when used with the KC$WD command. A
corresponding bit in the status word is set by the KK driver for KX read commands (KC$RD) to
indicate that the last byte in the current KK write ends the user message.

B.3.3.6 Vector Number Field (KC.VEC)
The vector number field, KC.VEC, specifies the vector number (vector address divided by four)
of the interrupt vector being activated by the enable interrupt command (KC$EI). Subsequently,
this vector is written to the QIR register by the KK driver when it interrupts the KX driver. This
field is meaningful only when used with the KC$EI command. Each channel on each peripheral
processor on the system must have a unique vector.

B.3.4 Statl:JS Register Definition
151413121110 9 8 7 6 5 4 3 2 1 0
KW.DST

+.___ _ Error code field (KS.ERG)
,___ _ _ _ Data requested (KS.DR)
._____ _ _ _ _ End of message (KS.EOM)
....__ _ _ _ _ _ Data available (KS.DA)
.___ _ _ _ _ _ _ _ _ Actual length field (KS.ALN)
' - - - - - - - - - - - - - - - Interrupt enabled (KS.IEN)
....____ _ _ _ _ _ _ _ _ _ _ _ Interface ready (KS.ON)
.___ _ _ _ _ _ _ _ _ _ _ _ _ Cumulative error (KS.ERR)

ML0-827-87

Bit 12 is set to 0.

B-30 KXTl 1-CA and KXf 11-CA Peripheral Processors

B.3.4. 1 Error Code Field (KS.ERC)
The error code field, KS.ERC, contains the following status or one of the following errors after
a requested command operation. The codes are designed to let your program index them from
a table. When a code other than success (KE$0K) is set, the cumulative error bit (KS.ERR) is
also set. The KX driver can check the KS.ERR bit for any error and then only needs to check
the particular error codes if that bit is set.
Operation Successful Status KE$0K (Code 0)
The operation previously requested completed without errors.
No Data Available Error KE$NDA (Code 2)
The read data command (KC$RD) was rejected, because no data was available. This rejection
indicates the occurrence of a protocol error if the interrupt-when-data-available mode is being
used.
No Data Requested Error KE$NDR (Code 4)
The write data command (KC$WD) was rejected, because no data was requested by the KK
driver. This rejection indicates the occurrence of a protocol error if the interrupt-when-datarequested mode is being used.
Illegal Command Error KE$1LC (Code 6)
The command specified in the command field (KC.COM) of the command register is invalid.
Illegal Length Error KE$1LL (Code 8)
The number of bytes specified in the data length field (KC.LEN) of the command register is
invalid. The length is zero or it exceeds the number of bytes in the data registers for the
channel.
Illegal Vector Error KE$1LV (Code 10)
The vector number (vector address divided by four) specified in the vector number field (KC.VEC)
of the command register is invalid.
KK Driver Buffer Overflow Error KE$0VR (Code 12)
The user buffer being filled by a write data (KC$WD) command on the KK side overflowed,
and excess data was discarded.

B.3.4.2 Data-Requested Bit (KS.DR)
When set to 1, the data-requested bit, KS.DR, indicates the KK driver is requesting data. Thus,
the KK driver is ready to execute a write data (KC$WD) command issued by the KX driver. The
KK driver sets this bit when a new user read request is processed. The KK driver clears the bit
when the user read request has been completed, unless another read request is pending.

B.3.4.3 End-of-Message Bit (KS.EOM)
When set to 1, the end-of-message bit, KS.EOM, indicates that the last byte in the current
transfer ends the message. This bit is meaningful only for ending user read requests on the KX
side to indicate that the corresponding user write request on the KK side has been completed.

KXT11-CA and KX/11-CA Peripheral Processors

B-31

B.3.4.4 Data-Available Bit (KS.DA)
When set to 1, the data-available bit, KS.DA, indicates data is available to be read from the KK
driver. Thus, the KK driver is ready to execute a read data (KC$RD) command issued by the KX
driver. The KK driver sets this bit when a new user write request is processed. The KK driver
clear$ the bit when the user write request has been completed, unless another write request is
pending.

B.3.4.5 Actual Length Field (KS.ALN)
The actual length field, KS.ALN, is set to the number of bytes actually transferred in response
to a KX driver read data (KC$RD) or write data (KC$WD) command.

B.3.4.6 Interrupt-Enabled Bit (KS.IEN)
When set to 1, the interrupt-enabled bit, KS.IEN, incates an enable interrupt (KC$EI) command
completed successfully, and the KK driver interrupts the arbiter for the specified interrupt
condition(s).

B.3.4.7 Interface-Ready Bit (KS.ON)
When set to 1, the interface-ready bit, KS.ON, indicates to the KX driver that the KK driver is
ready to perform the protocol.

B.3.4.8 Cumulative-Error Bit (KS.ERR)
When set to 1, the cumulative-error bit, KS.ERR, indicates an error condition exists. The error
code is in the error code (KS.ERC) field. When this bit is set to 1, the KS.ALN field is not
meaningful, and you should ignore its contents.

B.3.5 Interface Initialization
At system start-up, the TPR is locked from write access by the KX driver side, and the status and
command registers are in a cleared state. The KX driver waits for the KK driver to initialize itself
and indicate its readiness by setting the interface-ready bit (KS.ON) in the status register to 1.
The KK driver cannot clear the KS.ON bit until it has permanently ceased TPR communication.

B-32

KXT11-CA and KX/11-CA Peripheral Processors

B.4 KXT l 1-CA and KXJ 11-CA CSR and Vector Assignments
This section lists the interrupt vector assignments for all KXTl 1-CA devices and their associated
CSRs. See Section B.5 for the interrupt vector and CSR assignments for the TPR.

CSR
Address

Device

177560177562

SLUl console
DLART receiver

177564177566

SLUl console
DLART
transmitter

175700175716

SLU2 hardware

Do not specify this vector as an argument to the
MicroPower/Pascal DEVICES macro.
The kernel
routes its interrupts from this vector through vectors
140 to 174.

175720175736

8254 timer 0
and timer 1

Timer 0 and timer 1 on the 8254 device provide timing
for SLU2.

100

177520

Line frequency clock

Interrupts through this vector are enabled in the
MicroPower/Pascal kernel if CLOCK=ON in the
KXTl 1C macro. The MicroPower /Pascal clock driver
enables the interrupt with or without specifying
CLOCK=ON.
CSR 177520 is KXTCSRA. Bit 6 enables/disables the
line frequency clock as in the usual clock CSR at
177546. However, the other bits are allocated to serve
other functions.

104

175720175736

8254 timer 2

MicroPower/Pascal does not support this timer. You
must write your own driver for it. Specify vector 104
in the MicroPower/Pascal DEVICES macro. Timer 2
is enabled by bit 7 in KXTCSRA (address 177520)

120

175010175016

TPR data
channel 0

This vector is used when the arbiter writes to TPR
word 4 (command register for data channel 0).

124

175020175036

TPR data
channel 1

This vector is used when the arbiter writes to TPR
word 8 (command register for data channel 1).

177532

QIR

Q-bus interrupt register. The MicroPower/Pascal KK
device driver writes the arbiter's vector address to use
for TPR operations.

Q-BUS
interrupt
answer-back

This vector is used when the arbiter acknowledges
the interrupt requested by the MicroPower/Pascal KK
device driver over the QIR.

Vector

130

Comments

KXTl 1-CA and KX]l 1-CA Peripheral Processors

B-33

CSR
Address

Device

Comments

134

175030175036

TPR data
channel 2

This vector is used when the arbiter writes to word
12 of the TPR (enabled by a bit in KXTCSRD). Words
12 to 15 of the TPR form data channel 2, which
is not supported by the MicroPower/Pascal KK/KX
device driver. Instead MicroPower/Pascal uses these
locations as the last four words of data channel 1.
Do not specify this vector in the MicroPower/Pascal
DEVICES macro.
Module KSLU2 in MicroPower/Pascal's kernel fans
out the interrupts from SLU2, the multiprotocol chip,
through the vector at 70 to the vectors 140 to 174.

140

175700175736

SLU2 channel A
character
received

144

175700175736

SLU2 channel A
character sent

150

175700175736

SLU2 channel A
error

154

175700175736

SLU2 channel A
modem control

160

175700175736

SLU2 channel B
character
received

164

175700175736

SLU2 channel B
character sent

170

175700175736

SLU2 channel B
error

174

175700175736

SLU2 channel B
modem control

200

177000177140

Parallel I/O
port A

This vector is set up by the KXTl 1-CA/KXJll-CA
native firmware and used by parallel I/O port A.

204

177000177140

Parallel I/O
port B

This vector is set up by the KXTl 1-CA/KXJll-CA
native firmware and used by parallel I/O port B.

210

177000177140

Parallel I/O
timers

This vector is set up by the KXTll-CA/KXJll-CA
native firmware and used by parallel I/O port countertimers.

Vector

B-34

KXT11-CA and KX/11-CA Peripheral Processors

Vector

CSR
Address

220

Device

Comments

Arbiter RESET

This vector is used when the arbiter's BRESET signal is
asserted. BRESET is asserted when the arbiter executes
a RESET instruction or its RESTART switch is toggled.
Many device interrupts are enabled and disabled by
setting bits in the CSRs.

224

174400174536

DTC channel 0

The native firmware sets up this vector.

230

174400174536

DTC channel 1

The native firmware sets up this vector.

175000175006

TPR system
control

The first four words of the TPR used for KXTl 1-CA
or KXJll-CA native firmware/arbiter communication.
When the arbiter writes to word 0 (TPR command
register), the KXTl 1-CA restarts at 173004.

B.5 System ID Switch Positions, Two-Port RAM CSR and Vector
Assignments
This section shows the CSR and interrupt vector assignments for the TPRs that are selected by
the KXTll-CA or KXJll-CA system ID switch. These registers and vectors appear in the 1/0
page and vector area of arbiter memory. The table also shows the associated KX device driver
logical unit IDs.
The KX device driver passes data between the arbiter CPU and up to 14 peripheral processors
running on the Q-bus. The driver communicates with the KK device driver in the KXTl 1-CA
or KXJl 1-CA through the command and status registers in the data channel areas of the TPR.
(See Section B.3 for more information.)
TPR Base
Jumper
In=KXT
Out=KXJ

Address
Jumper
Out=KXT
In=KXJ

Default Vectors
MicroPower

17762100

17760100

500,504

17762140

17760140

510,514

17762200

17760200

520,524

17762240

17760240

530,534

17762300

17760300

540,544

17762340

17760340

550,554

ID
Switch
Position

MicroPower
KX Driver
ID

Stand-alone mode

KXT11-CA and KX/11-CA Peripheral Processors

B-35

ID
Switch
Position

MicroPower
KX Driver
ID

TPR Base
Jumper
In=KXT
Out=KXJ

Address
Jumper
Out=KXT
In=KXJ

Default Vectors
MicroPower

17777400

17775400

560,564

17777440

17775440

570,574

17777500

17775500

600,604

B-36

17777540

17775540

610,614

17777600

17775600

620,624

17777640

17775640

630,634

17777700

17775700

640,644

17777740

17775740

650,654

KXT11-CA and KX/11-CA Peripheral Processors

B.6 Sample MicroPower/Pascal Configuration File
The following is a copy of the Micro Power /Pascal configuration file that you must edit according
to your hardware and software requirements in preparation for building a KXTl 1-CA application .
. enabl

; Configuration file for a KXT11--CA target
THIS SOFTWARE IS FURNISHED UNDER A LICENSE AND MAY BE USED OR COPIED
ONLY IN ACCORDANCE WITH THE TERMS OF SUCH LICENSE.
COPYRIGHT (c) 1984, 1986 BY DIGITAL EQUIPMENT CORPORATION.

Module name: CFDKTC.MAC
System: Micropower/Pascal
Modified:
RLP

23-Apr-86

Changed DMA vectors to match KXJ.

KXT11-CA and KX]11-CA Peripheral Processors

B-37

MEMORY base=nnn,size=mmm,type=ROMIRAM,parity={YESINO},[csr=nnnnnn],
volatile={YESINO},res={YESINO}[,name=string]
DEVICES
vectaddri,vectaddr2, ... ,vectaddr6
RESOURCES [stack= .. KIS], [packets=20.], [structures=3000.], [ramtbl=20.]
PRIMITIVES pi,p2,p3,p4,p5,p6
Parameters can be:
ALL
- All primitives (default for pi, ... ,p6)
BCSEM - Binary and counting semaphore primitives
COMPLX - Complex primitives
EXCMGT - Exception handling primitives
INTMGT - Interrupt handling primitives
LOGNAM - Logical name primitives
DRAM
- Region allocation, sharing, and mapping primitives
PRMGT - Process management primitives
QSEMN - Nonprivileged queue-semaphore primitives
QSEMP - Privileged queue-semaphore primitives
RBUF
- Ring buffer primitives
STRMGT - Structure management primitives
TIMER - Clock service primitives
Vi
- All Vi primitives
xxxx
- where xxxx is a specific primitive name (no $)
Required if processor type is FALC or FALCPLUS -FALCON trapi40={BHALTINXM},break={ROMODTISFWODTIEXCEPTIONIIGNOREIHANG}
Required if processor type is KXTiiC -KXTiiC bhalt={YESINO},reset={IGNOREIBOOTIRSTBOTIINTRPT},map=n
Required if processor type is KXJiiC -KXJiiC bhalt={YESINO},reset={IGNOREIBOOTIRSTBOTIINTRPT}
TRAPS

ti,t2,t3,t4,t5,t6,t7,t8
Parameters can be:
ALL - TR4, TiO, BPT, EMT, and TRP (standard LSI--ii set)
TR4
Trap to 4 (bus timeout)
TiO
Trap to iO (reserved instruction)
BPT Breakpoint instruction tr,ap
EMT
EMT instruction trap
TRP
TRAP instruction trap
MPT
Memory parity error
FIS
FIS exception trap
FPP
FPP exception trap
MMU - Memory management fault
BRK - FALCON (SBC--ii/2i) BREAK level-7 trap
LOGICAL name, string
ENDCFG

If the value of the SYSTEM macro optimize argument is YES, the RESOURCES,
TRAPS, and PRIMITIVES macros are required. If the optimize argument value is
NO (default), the RESOURCES, TRAPS, and PRIMITIVES macros are defaulted and
should not appear in the configuration file .
. enabl

GBL

.mcall

CONFIGURATION

.sbttl

System Configuration File For KXTii--CA Target

CONFIGURATION

B-38

KXT11-CA and KX/11-CA Peripheral Processors

SYSTEM

debug=YES, optimize=YES

PROCESSOR

mmu=NO, type=KXT11C, vector=400, clock=60HZ, clkcsr=177520

; ADDRCHECK defaults to DEBUG
; value

MEMORY
base=O, size=511., type=RAM
Assumes 32KB of volatile native RAM (map 0): Note that the highest 64 bytes
; of the native RAM (1 memory block) must not be described here, since it is
; used by the native firmware and therefore is not allocatable.
KXT11C

bhalt=YES, reset=IGNORE, map=O

;Factory map configuration

RESOURCES

packets=10., structures=2048.

;Small pools for packets
;and kernel structures

PRIMITIVES

ALL

TRAPS

ALL

;Implies T4, T10, BPT, EMT, and TRP

DEVICES

60,64,100

;Console serial line (SLU1)
;and clock vectors

DEVICES

104

;Spare timer vector, if used

DEVICES

224,230

;DMA vectors

DEVICES

120,124,130

;Two-Port RAM arbiter write interrupts

DEVICES
DEVICES

140' 144. 150. 154
160, 164, 170, 174

;SLU2 pseudo-vectors - channel A
;SLU2 pseudo-vectors - channel B

200,204,210

;PIO and counter/timer vectors

DEVICES

Include the following only if reset=INTRPT in KXT11C macro
DEVICES
220
;Simulated QBUS reset-interrupt vector
ENDCFG
.end

KXT11-CA and KX]11-CA Peripheral Processors

B-39

B. 7 Sample Configuration Files for the KXJ l 1-CA
.enabl

; Configuration File For Unmapped KXJ11--CA Target
THIS SOFTWARE IS FURNISHED UNDER A LICENSE AND MAY BE USED OR COPIED
ONLY IN ACCORDANCE WITH THE TERMS OF SUCH LICENSE.
COPYRIGHT (c) 1986 BY DIGITAL EQUIPMENT CORPORATION. ALL RIGHTS RESERVED.
;+

Module name: CFDKJU.MAC
System: Micropower/Pascal
Functional Description:
This module describes a hardware and system software configuration in
which an application is to run. The file must be edited by the user to
reflect a specific application environment and then be assembled. The
resulting object module is used to build the kernel.
The following set of macros may be used in a configuration file. The
CONFIGURATION macro must be the first macro evoked. The ENDCFG macro must
be the last. A configuration file must contain at a minimum the
CONFIGURATION, SYSTEM, PROCESSOR, MEMORY, DEVICES, and ENDCFG macros.
In the following condensed syntax descriptions, brackets ([ ... ]) indicate
optionality, braces ({ ... }) enclose alternatives, and single parameter
values shown in optional arguments indicate defaults.

B-40

CONFIGURATION [version-name]
SYSTEM optimize={YESINO},debug={YESINO},addrcheck={YESINO}
PROCESSOR mmu={YESINO},[fpu={FP11IFISIFPA}],
type={L112IL1123IFALCIFALCPLUSIJ11IKXT11CIKXJ11CICMR21},
j11map={YESINO}, [vector=nnnn],
clock={NONEl50HZl60HZl100HZl800HZ},[clkcsr=nnnnnn]
(Vector default is 1000 octal for an L11x or J11 target type,
400 octal for the other target types.)
Note: Standard clock CSRs, if present, are:
For an LSI11/23-PLUS or J-11 = 177546
For a KXT11--CA or KXJ11--CA
= 177520
Default is no clock csr. Do not specify clkcsr unless
there is a clock csr.
MEMORY base=nnn,size=mmm,type=ROMIRAM,parity={YESINO},[csr=nnnnnn],
volatile={YESINO},res={YESINO}[,name=string]
DEVICES
vectaddr1,vectaddr2, ... ,vectaddr6
RESOURCES [stack= .. KIS], [packets=20.], [structures=3000.], [ramtbl=20.]
PRIMITIVES p1,p2,p3,p4,p5,p6
Parameters can be:
ALL
- All primitives (default for pi, ... ,p6)
BCSEM - Binary and counting semaphore primitives
COMPLX - Complex primitives
EXCMGT - Exception handling primitives
INTMGT - Interrupt handling primitives
LOGNAM - Logical name primitives
DRAM
- Region allocation, sharing, and mapping primitives
PRMGT - Process management primitives
QSEMN - Nonprivileged queue-semaphore primitives

KXT11-CA and KX/11-CA Peripheral Processors

QSEMP - Privileged queue-semaphore primitives
RBUF
- Ring buffer primitives
STRMGT - Structure management primitives
TIMER - Clock service primitives
Vi
- All Vi primitives
xxxx
- where xxxx is a specific primitive name (no $)
Required if processor type is FALC or FALCPLUS -FALCON trap140={BHALTINXM},break={ROMODTISFWODTIEXCEPTIONIIGNOREIHANG}
Required if processor type is KXT11C -KXT1iC bhalt={YESINO},reset={IGNOREIBOOTIRSTBOTIINTRPT},map=n
Required if processor type is KXJ11C -KXJ11C bhalt={YESINO},reset={IGNOREIBOOTIRSTBOTIINTRPT}
TRAPS

t1,t2,t3,t4,t5,t6,t7,t8
Parameters can be:
ALL - TR4, T10, BPT, EMT, and TRP (standard LSI--11 set)
TR4
Trap to 4 (bus timeout)
TiO Trap to 10 (reserved instruction)
BPT - Breakpoint instruction trap
EMT - EMT instruction trap
TRP
TRAP instruction trap
MPT - Memory parity error
FIS - FIS exception trap
FPP
FPP exception trap
MMU - Memory management fault
BRK - FALCON (SBC--11/21) BREAK level-7 trap
LOGICAL
name, string
ENDCFG
If the value of the SYSTEM macro optimize argument is YES, the RESOURCES,
TRAPS, and PRIMITIVES macros are required. If the optimize argument value is
NO (default), the RESOURCES, TRAPS, and PRIMITIVES macros are defaulted and
should not appear in the configuration file .
. enabl
.mean
.sbttl

GBL
CONFIGURATION
System Configuration File For Unmapped KXJ11--CA Target

CONFIGURATION
SYSTEM
PROCESSOR

debug=YES, optimize=YES

; ADDRCHECK defaults to DEBUG
; value
mmu=NO, type=KXJ11C, vector=400, clock=60HZ, clkcsr=177520

;Leave 128. bytes just below 160000 for the firmware stack
MEMORY
base=O, size=<28.*32.-2>, type=RAM
; Uses a total of 56KB of volatile native RAM - 128(i0) bytes
KXJ11C

bhalt=NO, reset=IGNORE

RESOURCES

packets=10., structures=2048.

PRIMITIVES

ALL

TRAPS

ALL

;Small pools for packets
;and kernel structures

;Implies T4, T10, BPT, EMT, and TRP

KXT11-CA and KX]ll-CA Peripheral Processors

B-41

DEVICES

104

;Console serial line (SLU1)
;and clock vectors
;Spare timer vector, if used

DEVICES

120,124,130

;Two-Port RAM arbiter write interrupts

DEVICES
DEVICES

140. 144. 160. 164
160, 164, 170, 174

;SLU2 pseudo-vectors - channel A
;SLU2 pseudo-vectors - channel B

200,204,210

;PIO and counter/timer vectors

;

60,64, 100

DEVICES

Include the following only if reset=INTRPT in KXJ11C macro
DEVICES
;Simulated QBUS reset-interrupt vector
220
DEVICES

224,230

;DMA vectors

ENDCFG
.end
.enabl

; Configuration File for Mapped KXJ11--CA Target without J11 mapping support;
; 32 KW of memory. Also includes the PIO chip vectors.
THIS SOFTWARE IS FURNISHED UNDER A LICENSE AND MAY BE USED OR COPIED
ONLY IN ACCORDANCE WITH THE TERMS OF SUCH LICENSE.
COPYRIGHT (c) 1986 BY DIGITAL EQUIPMENT CORPORATION. ALL RIGHTS RESERVED.
;+

Module name: CFDKJM.MAC
System: Micropower/Pascal
Functional Description:
This module describes a hardware and system software configuration in
which an application is to run. The file must be edited by the user to
reflect a specific application environment and then be assembled. The
resulting object module is used to build the kernel.
The following set of macros may be used in a configuration file. The
CONFIGURATION macro must be the first macro evoked. The ENDCFG macro must
be the last. A configuration file must contain at a minimum the
CONFIGURATION, SYSTEM, PROCESSOR, MEMORY, DEVICES, and ENDCFG macros.
In the following condensed syntax descriptions, brackets ([ ... ]) indicate
optionality, braces ({ ... }) enclose alternatives, and single parameter
values shown in optional arguments indicate defaults.
CONFIGURATION [version-name]
SYSTEM optimize={YESINO},debug={YESINO},addrcheck={YESINO}
PROCESSOR mmu={YESINO},[fpu={FP11IFIS}],
type={L112IL1123IFALCIFALCPLUSIJ11IKXT11CIKXJ11C},
[vector=nnnn],
clock={NONEl50HZl60HZl100HZl800HZ}, [clkcsr=nnnnnn]
(Vector default is 1000 octal for an L11x or J11 target type.)
Note: Standard clock CSRs, if present, are:
For an LSI11/23-PLUS or J-11 = 177546
For a KXT11--CA or KXJ11--CA
= 177520
MEMORY base=nnn,size=mmm,type=ROMIRAM,parity={YESINO},[csr=nnnnnn].
volatile={YESINO},res={YESINO}[,name=string]

B-42

KXTl 1-CA and KX/11-CA Peripheral Processors

DEVICES
vectaddri,vectaddr2, ... ,vectaddr6
RESOURCES [stack= .. KIS]. [packets=20.], [structures=3000.], [ramtbl=20.]
PRIMITIVES pi,p2,p3,p4,p5,p6
Parameters can be:
ALL
- All primitives (default for pi, ... ,p6)
BCSEM - Binary and counting semaphore primitives
COMPLX - Complex primitives
EXCMGT - Exception handling primitives
INTMGT - Interrupt handling primitives
LOGNAM - Logical name primitives
DRAM
- Region allocation, sharing, and mapping primitives
PRMGT - Process management primitives
QSEMN - Nonprivileged queue-semaphore primitives
QSEMP - Privileged queue-semaphore primitives
RBUF
- Ring buff er primitives
STRMGT - Structure management primitives
TIMER - Clock service primitives
Vi
- All Vi primitives
xxxx
- where xxxx is a specific primitive name (no $)
Required if processor type is FALC or FALCPLUS -FALCON trapi40={BHALTINXM},break={ROMODTISFWODTIEXCEPTIONIIGNOREIHANG}
Required if processor type is KXTiiC -KXTiiC bhalt={YESINO},reset={IGNOREIBOOTIRSTBOTIINTRPT},map=n
Required if processor type is KXJiiC -KXJiiC bhalt={YESINO},reset={IGNOREIBOOTIRSTBOTIINTRPT}
TRAPS ti,t2,t3,t4,t5,t6,t7,t8
Parameters can be:
ALL - TR4, TiO, BPT, EMT, and TRP (standard LSI--ii set)
TR4 - Trap to 4 (bus timeout)
TiO - Trap to iO (reserved instruction)
BPT - Breakpoint instruction trap
EMT - EMT instruction trap
TRP - TRAP instruction trap
MPT - Memory parity error
FIS - FIS exception trap
FPP - FPP exception trap
MMU - Memory management fault
BRK - FALCON (SBC--ii/2i) BREAK level-7 trap
LOGICAL
name, string
ENDCFG
If the value of the SYSTEM macro optimize argument is YES, the RESOURCES,
TRAPS, and PRIMITIVES macros are required. If the optimize argument value is
NO (default), the RESOURCES, TRAPS, and PRIMITIVES macros are defaulted and
should not appear in the configuration file,
.enabl

GBL

.mcall

CONFIGURATION

KXT11-CA and KX]11-CA Peripheral Processors

B-43

.sbttl
System Configuration File for Mapped KXJ11--CA Target
CONFIGURATION
SYSTEM
debug=YES, optimize=NO
; ADDRCHECK defaults to DEBUG
; value
PROCESSOR mmu=YES, type=KXJ11C, j11map=no, vector=400, clock=60HZ, clkcsr=177520
;Leave a hole of 128. bytes for the firmware stack just below 160000
; Uses 64KB of volatile native RAM total
MEMORY
base=O, size=<<28.*32.>-2>, type=RAM
MEMORY
base=<28.*32.>, size=<4.*32.>, type=RAM
KXJ11C

bhalt=YES, reset=IGNORE

DEVICES

60,64,100

;Console serial line (SLU1)
;and clock vectors

; DEVICES

104

;Spare timer vector, if used

DEVICES

120,124,130

;Two-Port RAM arbiter write interrupts

DEVICES
DEVICES

140, 144, 150, 154
160, 164, 170, 174

;SLU2 pseudo-vectors - channel A
;SLU2 pseudo-vectors - channel B

DEVICES

200,204,210

;PIO and counter/timer vectors

; Include the following only if reset=INTRPT in KXJ11C macro
; DEVICES
220
;Simulated QBUS reset-interrupt vector
;DEVICES
ENDCFG
.end
.enabl

224,230

;OMA.vectors

; Configuration File for Mapped KXJ11--CA Target with J11 Mapping Support.
; Also includes all 512 KB of memory.
THIS SOFTWARE IS FURNISHED UNDER A LICENSE AND MAY BE USED OR COPIED
ONLY IN ACCORDANCE WITH THE TERMS OF SUCH LICENSE.
COPYRIGHT (c) 1986 BY DIGITAL EQUIPMENT CORPORATION. ALL RIGHTS RESERVED.
;+

Module name: CFDKJJ.MAC
System: Micropower/Pascal
Functional Description:
This module describes a hardware and system software configuration in
which an application is to run. The file must be edited by the user to
reflect a specific application environment and then be assembled. The
resulting object module is used to build the kernel.
The following set of macros may be used in a configuration file. The
CONFIGURATION macro must be the first macro evoked. The ENDCFG macro must
be the last. A configuration file must contain at a minimum the
CONFIGURATION, SYSTEM, PROCESSOR, MEMORY, DEVICES, and ENDCFG macros.
In the following condensed syntax descriptions, brackets ([ ... ]) indicate
optionality, braces ({ ... }) enclose alternatives, and single parameter
values shown in optional arguments indicate defaults.
CONFIGURATION

B-44

[version-name]

KXTl 1-CA and KX/11-CA Peripheral Processors

SYSTEM optimize={YESINO},debug={YESINO},addrcheck={YESINO}
PROCESSOR mmu={YESINO},[fpu={FP11IFISIFPA}],
type={L112IL1123IFALCIFALCPLUSIJ11IKXT11CIKXJ11CICMR21},
j11map={YESINO},[vector=nnnn],
clock={NONEl50HZl60HZl100HZl800HZ}, [clkcsr=nnnnnn]
(Vector default is 1000 octal for an L11x or J11 target type,
400 octal for the other target types.)
Note: Standard clock CSRs, if present, are:
For an LSI11/23-PLUS or J-11 = 177546
For a KXT11--CA or KXJ11--CA
= 177520
Default is no clock csr. Do not specify clkcsr unless
there is a clock csr.
MEMORY base=nnn,size=mmm,type=ROMIRAM,parity={YESINO}, [csr=nnnnnn],
volatile={YESINO},res={YESINO}[,name=string]
DEVICES
vectaddr1,vectaddr2, ... ,vectaddr6
RESOURCES [stack= .. KIS], [packets=20.], [structures=3000.], [ramtbl=20.]
PRIMITIVES p1,p2,p3,p4,p5,p6
Parameters can be:
ALL
- All primitives (default for pi, ... ,p6)
BCSEM - Binary and counting semaphore primitives
COMPLX - Complex primitives
EXCMGT - Exception handling primitives
INTMGT - Interrupt handling primitives
LOGNAM - Logical name primitives
DRAM
- Region allocation, sharing, and mapping primitives
PRMGT - Process management primitives
QSEMN - Nonprivileged queue-semaphore primitives
QSEMP - Privileged queue-semaphore primitives
RBUF
- Ring buff er primitives
STRMGT - Structure management primitives
TIMER - Clock service primitives
V1
- All V1 primitives
xxxx
- where xxxx is a specific primitive name (no $)
Required if processor type is FALC or FALCPLUS -FALCON trap140={BHALTINXM},break={ROMODTISFWODTIEXCEPTIONIIGNOREIHANG}
Required if processor type is KXT11C -KXT11C bhalt={YESINO},reset={IGNOREIBOOTIRSTBOTIINTRPT},map=n
Required if processor type is KXJ11C -KXJ11C bhalt={YESINO},reset={IGNOREIBOOTIRSTBOTIINTRPT}
TRAPS t1,t2,t3,t4,t5,t6,t7,t8
Parameters can be:
ALL - TR4, T10, BPT, EMT, and TRP (standard LSI--11 set)
TR4
Trap to 4 (bus timeout)
Trap to 10 (reserved instruction)
T10
BPT
Breakpoint instruction trap
EMT
EMT instruction trap
TRP
TRAP instruction trap
MPT
Memory parity error
FIS
FIS exception trap
FPP
FPP exception trap
MMU - Memory management fault
BRK
FALCON (SBC--11/21) BREAK level-7 trap
LOGICAL
name, string
ENDCFG

KXT11-CA and K.Xf 11-CA Peripheral Processors

B-45

GBL

.mcall

CONFIGURATION

.sbttl

System Configuration File for Mapped KXJ11--CA Target

CONFIGURATION
; ADDRCHECK defaults to DEBUG
; value
;Defaults to J11MAP=yes for type=KXJ11C or J11
;PROCESSOR
mmu=YES, type=KXJ11C, vector=400, clock=60HZ, clkcsr=177520
; Uses a total 512KB of volatile native RAM
;Must leave a hole for the native firmware stack area (128. bytes starting at
;157600)
;MEMORY
base=O, size=<28.*32.-2>, type=RAM
;Note: base could also be specified as 1600(8), size as 16200(8).
MEMORY
base=<28.*32.>, size=<228.*32.>, type=RAM
bhalt=NO, reset=IGNORE
KXJ11C
DEVICES
60,64,100
;Console serial line (SLU1)
;and clock vectors
; DEVICES
104
;Spare timer vector, if used
SYSTEM

debug=YES, optimize=NO

DEVICES

120,124,130

;Two-Port RAM arbiter write interrupts

DEVICES
DEVICES

140,144,150,154
160,164,170,174

;SLU2 pseudo-vectors - channel A
;SLU2 pseudo-vectors - channel B

;DEVICES

200,204,210

;PIO and counter/timer vectors

; Include the following only if reset=INTRPT in KXJ11C macro
; DEVICES
220
;Simulated QBUS reset-interrupt vector
;DEVICES
224,230
;OMA vectors
ENDCFG
.end

B-46

KXTl 1-CA and KX/11-CA Peripheral Processors

;File CFR8KJM.MAC - for 27128 chips .
. enabl
LC
;+

; Configuration File for Mapped KXJ11--CA ROM/RAM Target without J11 mapping
; support. With 27128 ROM chips.
THIS SOFTWARE IS FURNISHED UNDER A LICENSE AND MAY BE USED OR COPIED
ONLY IN ACCORDANCE WITH THE TERMS OF SUCH LICENSE.
COPYRIGHT (c) 1986 BY DIGITAL EQUIPMENT CORPORATION. ALL RIGHTS RESERVED.
;+

Module name: CFR8KJM.MAC
System: Micropower/Pascal
Functional Description:
This module describes a hardware and system software configuration in
which an application is to run. The file must be edited by the user to
reflect a specific application environment and then be assembled. The
resulting object module is used to build the kernel.
The following set of macros may be used in a configuration file. The
CONFIGURATION macro must be the first macro evoked. The ENDCFG macro must
be the last. A configuration file must contain at a minimum the
CONFIGURATION, SYSTEM, PROCESSOR, MEMORY, DEVICES, and ENDCFG macros.
In the following condensed syntax descriptions, brackets ([ ... ]) indicate
optionality, braces ({ ... }) enclose alternatives, and single parameter
values shown in optional arguments indicate defaults.
CONFIGURATION [version-name]
SYSTEM optimize={YESINO},debug={YESINO},addrcheck={YESINO}
PROCESSOR mmu={YESINO},[fpu={FP11IFIS}],
type={L112IL1123IFALCIFALCPLUSIJ11IKXT11CIKXJ11C},
[vector=nnnn],
clock={NONEl50HZl60HZl100HZl800HZ}, [clkcsr=nnnnnn]
(Vector default is 1000 octal for an L11x or J11 target type.)
Note: Standard clock CSRs, if present, are:
For an LSI11/23-PLUS or J-11 = 177546
For a KXT11--CA or KXJ11--CA
= 177520
MEMORY base=nnn,size=mmm,type=ROMIRAM,parity={YESINO}, [csr=nnnnnn],
volatile={YESINO},res={YESINO}[,name=string]
DEVICES
vectaddr1,vectaddr2, ... ,vectaddr6
RESOURCES [stack= .. KIS], [packets=20.], [structures=3000.]. [ramtbl=20.]
PRIMITIVES p1,p2,p3,p4,p5,p6
Parameters can be:
ALL
- All primitives (default for.pi, ... ,p6)
BCSEM - Binary and counting semaphore primitives
COMPLX - Complex primitives
EXCMGT - Exception handling primitives
INTMGT - Interrupt handling primitives
LOGNAM - Logical name primitives
DRAM
- Region allocation, sharing, and mapping primitives
PRMGT - Process management primitives
QSEMN - Nonprivileged queue-semaphore primitives
QSEMP - Privileged queue-semaphore primitives
RBUF
- Ring buff er primitives
STRMGT - Structure management primitives

KXT11-CA and KXJ11-CA Peripheral Processors

B-47

TIMER
Vi
xxxx

Clock service primitives
- All Vi primitives
- where xxxx is a specific primitive name (no $)

Required if processor type is FALC or FALCPLUS -FALCON trapi40={BHALTINXM},break={ROMODTISFWODTIEXCEPTIONIIGNOREIHANG}
Required if processor type is KXTiiC -KXTiiC bhalt={YESINO},reset={IGNOREIBOOTIRSTBOTIINTRPT},map=n
Required if processor type is KXJiiC -KXJiiC bhalt={YESINO},reset={IGNOREIBOOTIRSTBOTIINTRPT}
TRAPS ti,t2,t3,t4,t5,t6,t7,t8
Parameters can be:
ALL - TR4, TiO, BPT, EMT, and TRP (standard LSI--ii set)
TR4 - Trap to 4 (bus timeout)
TiO - Trap to iO (reserved instruction)
BPT - Breakpoint instruction trap
EMT - EMT instruction trap
TRP - TRAP instruction trap
MPT - Memory parity error
FIS - FIS exception trap
FPP - FPP exception trap
MMU - Memory management fault
BRK - FALCON (SBC--ii/2i) BREAK level-7 trap
LOGICAL
name, string
ENDCFG
If the value of the SYSTEM macro optimize argument is YES, the RESOURCES,
TRAPS, and PRIMITIVES macros are required. If the optimize argument value is
NO (default), the RESOURCES, TRAPS, and PRIMITIVES macros are defaulted and
should not appear in the configuration file .
. enabl
.mcall
.sbttl

GBL
CONFIGURATION
System Configuration File for Mapped KXJii--CA Target

CONFIGURATION
SYSTEM

debug=NO, optimize=YES

; ADDRCHECK defaults to DEBUG
; value
PROCESSOR mmu=YES, type=KXJ11C, j11map=no, v'ector=400, clock=60HZ, clkcsr=i77520
;User ROM at 2000000(8) to 2037777(8) is also visible at 0(8) - 37777(8)
;MEMORY
base=O, size=400, type=ROM
;This shows the same thing using n*32. notation instead
;MEMORY
base=O, size=<8.*32.>, type=ROM
\Leave a hole of i28. bytes for the firmware stack just below i60000
;MEMORY
base=iOOO, size=i576, type=RAM
;This shows the same thing using n*32. notation instead
;MEMORY
base=<i6.*32.>, size=<<i2.*32.>-2>, type=RAM
;Now go from 160000(8) to the top of RAM memory - 1777777(8)
;MEMORY
base=1600, size=16200, type=RAM
;This shows the same thing using n*32. notation instead
;MEMORY
base=<28.*32.>, size=<228.*32.>, type=RAM

B-48

KXTl 1-CA and KXf 11-CA Peripheral Processors

;ROM at 2000000(8) - 2037777(8) already configured at 0 - 37777(8). Above
;that, at 2040000(8) - 2077777(8) is the firmware. Then the same user code
;which is at 2000000(8) is visible again at 2100000(8) - 2137777(8), followed
;by the firmware again at 2140000(8) - 2177777(8).
KXJ11C

bhalt=NO, reset=IGNORE

RESOURCES

packets=10., structures=2048.

PRIMITIVES
TRAPS
DEVICES

ALL
ALL
60,64'100

; DEVICES

104

;Implies T4, T10, BPT, EMT, and TRP
;Console serial line (SLU1)
;and clock vectors
;Spare timer vector, if used

DEVICES

120,124,130

;Two-Port RAM arbiter write interrupts

DEVICES
DEVICES

140,144,150,154
160,164,170,174

;SLU2 pseudo-vectors - channel A
;SLU2 pseudo-vectors - channel B

;DEVICES

200,204,210

;PIO and counter/timer vectors

;Small pools for packets
;and kernel structures

; Include the following only if reset=INTRPT in KXJ11C macro
; DEVICES
220
;Simulated QBUS reset-interrupt vector
;DEVICES

224,230

;OMA vectors

ENDCFG
.end
;File CFRKJM.MAC
.enabl
LC
;+

; Configuration File For Mapped KXJ11--CA ROM/RAM Target without J11 mapping
; support. With 27256 ROM chips.
THIS SOFTWARE IS FURNISHED UNDER A LICENSE AND MAY BE USED OR COPIED
ONLY IN ACCORDANCE WITH THE TERMS OF SUCH LICENSE.
COPYRIGHT (c) 1986 BY DIGITAL EQUIPMENT CORPORATION. ALL RIGHTS RESERVED.
;+

Module name: CFRKJM.MAC
System: Micropower/Pascal
Functional Description:
This module describes a hardware and system software configuration in
which an application is to run. The file must be edited by the user to
reflect a specific application environment and then be assembled. The
resulting object module is used to build the kernel.
The following set of macros may be used in a configuration file. The
CONFIGURATION macro must be the first macro evoked. The ENDCFG macro must
be the last. A configuration file must contain at a minimum the
CONFIGURATION, SYSTEM, PROCESSOR, MEMORY, DEVICES, and ENDCFG macros.
In the following condensed syntax descriptions, brackets ([ ... ]) indicate
optionality, braces ({ ... }) enclose alternatives, and single parameter
values shown in optional arguments indicate defaults.

KX.T11-CA and KX.]11-CA Peripheral Processors

B-49

CONFIGURATION [version-name]
SYSTEM optimize={YESINO},debug={YESINO},addrcheck={YESINO}
PROCESSOR mmu={YESINO},[fpu={FP11IFIS}],
type={L112IL1123IFALCIFALCPLUSIJ11IKXT11CIKXJ11C},
[vector=nnnn],
clock={NONEl50HZl60HZl100HZl800HZ}, [clkcsr=nnnnnn]
(Vector default is 1000 octal for an L11x or J11 target type.)
Note: Standard clock CSRs, if present, are:
For an LSI11/23-PLUS or J-11 = 177546
For a KXT11--CA or KXJ11--CA
= 177520
MEMORY base=nnn,size=mmm,type=ROMIRAM,parity={YESINO},[csr=nnnnnn],
volatile={YESINO},res={YESINO}[,name=string]
DEVICES
vectaddr1,vectaddr2, ... ,vectaddr6
RESOURCES [stack= .. KIS], [packets=20.], [structures=3000.]. [ramtbl=20.]
PRIMITIVES p1,p2,p3,p4,p5,p6
Parameters can be:
ALL
- All primitives (default for p1, ... ,p6)
BCSEM - Binary and counting semaphore primitives
COMPLX - Complex primitives
EXCMGT - Exception handling primitives
INTMGT - Interrupt handling primitives
LOGNAM - Logical name primitives
DRAM
- Region allocation, sharing, and mapping primitives
PRMGT - Process management primitives
QSEMN - Nonprivileged queue-semaphore primitives
QSEMP - Privileged queue-semaphore primitives
RBUF
- Ring buff er primitives
STRMGT - Structure management primitives
TIMER - Clock service primitives
V1
- All V1 primitives
xxxx
- where xxxx is a specific primitive name (no $)
Required if processor type is FALC or FALCPLUS -FALCON trap140={BHALTINXM},break={ROMODTISFWODTIEXCEPTIONIIGNOREIHANG}
Required if processor type is KXT11C -KXT11C bhalt={YESINO},reset={IGNOREIBOOTIRSTBOTIINTRPT},map=n
Required if processor type is KXJ11C -KXJ11C bhal t={YES INO}, reset={IGNORE IBOOT.I RSTBOT IINTRPT}
TRAPS t1,t2,t3,t4,t5,t6,t7,t8
Parameters can be:
ALL - TR4, T10, BPT, EMT, and TRP (standard LSI--11 set)
TR4
Trap to 4 (bus timeout)
T10
Trap to 10 (reserved instruction)
BPT Breakpoint instruction trap
EMT - EMT instruction trap
TRP
TRAP instruction trap
MPT - Memory parity error
FIS
FIS exception trap
FPP
FPP exception trap
MMU - Memory management fault
BRK
FALCON (SBC--11/21) BREAK level-7 trap
LOGICAL
name, string
ENDCFG
If the value of the SYSTEM macro optimize argument is YES, the RESOURCES,
TRAPS, and PRIMITIVES macros are required. If the optimize argument value is

B-50

KXT11-CA and KX/11-CA Peripheral Processors

NO (default), the RESOURCES, TRAPS, and PRIMITIVES macros are defaulted and
should not appear in the configuration file .
. enabl
.mcall
.sbttl

GBL
CONFIGURATION
System Configuration File For Mapped KXJ11--CA Target

CONFIGURATION
SYSTEM
PROCESSOR

debug=NO, optimize=YES
; ADDRCHECK defaults to DEBUG
; value
mmu=YES, type=KXJ11C, j11map=no, vector=400, clock=60HZ, clkcsr=177520

;ROM at 2000000(8) to 2077777(8) is also visible at 0(8) - 77777(8)
MEMORY
base=O, size=1000, type=ROM
;This shows the same thing using n*32. notation instead
;MEMORY
base=O, size=<16.*32.>, type=ROM
;Leave a hole of 128. bytes for the firmware stack just below 160000
MEMORY
base=1000, size=1576, type=RAM
;This shows the same thing using n*32. notation instead
;MEMORY
base=<16.*32.>, size=<<12.*32.>-2>, type=RAM
;Now go from 160000(8) to the top of RAM memory - 1777777(8)
MEMORY
base=1600, size=16200, type=RAM
;This shows the same thing using n*32. notation instead
;MEMORY
base=<28.*32.>, size=<228.*32.>, type=RAM
;ROM at 2000000(8) - 2077777(8) already configured at 0 - 77777(8).
;Get the rest of the ROM - starting at 2100000(8). Firmware resides from
;2140000(8) to 2177777(8).
MEMORY
base=21000, size=400, type=ROM
;This shows the same thing using n*32. notation instead
;MEMORY
base=<272.*32.>, size=<8.*32.>, type=ROM
KXJ11C
RESOURCES

bhalt=NO, reset=IGNORE
packets=10., structures=2048.

PRIMITIVES

ALL

TRAPS

ALL

;Implies T4, T10, BPT, EMT, and TRP

DEVICES

60,64,100

; DEVICES

104

;Console serial line (SLU1)
;and clock vectors
;Spare timer vector, if used

DEVICES

120, 124, 130

;Two-Port RAM arbiter write interrupts

DEVICES
DEVICES

140, 144, 150, 154
160, 164, 170, 174

;SLU2 pseudo-vectors - channel A
;SLU2 ps~udo-vectors - channel B

;DEVICES

200,204,210

;PIO and counter/timer vectors

;Small pools for packets
;and kernel structures

; Include the following only if reset=INTRPT in KXJ11C macro
; DEVICES
220
;Simulated QBUS reset-interrupt vector
;DEVICES

224,230

;OMA vectors

ENDCFG
.end

KXT11-CA and KX/11-CA Peripheral Processors

B-51

B.8 Shared Memory on a KXJ
KXJ shared memory is memory on the KXJ that, when enabled (as shared memory), becomes
visible on the Q-bus. The KXJ shared memory is then directly accessible from both the KXJ and
the arbiter. In addition, this memory is then accessible by means of the DMA chip on other
peripheral processors (KXTll-CAs or KXJll-CAs). KXJ shared memory facilitates the sharing
of data between the arbiter and the KXJ. The starting Q-bus address for the KXJ shared memory
can be set up at any address so that the entire range of addresses is available on the Q-bus
side.
Normally, the KXJ shared memory is started right above the configured memory on the Q-bus.
The size of this memory can be any multiple of 4KW up to 256KW minus the size of the KXJ
application. The KXJ shared memory is at the top of memory on the KXJ side.

Example
You enable KXJ shared memory starting at 1000000(8) on the Q-bus with a size of 24KW
(140000(8) bytes). The KXJ shared memory is visible at locations 1000000 to 1137777 on the
arbiter side. That memory is visible on the KXJ side at a start address of 2000000 - 140000 =
1640000; so it is visible at addresses 1640000 to 1777777.
Use the procedure KXJ_ENABLE_SHARED to enable KXJ shared memory, and the procedure
KXJ-DISABLE_SHARED to disable KXJ shared memory. These procedures are called from the
KXJ side only. The following files on the MicroPower/Pascal distribution kit are required for
using these procedures:

Name

Description

KXJSHR.P AS

KXJl 1-CA shared memory procedures module

MISC.PAS

Miscellaneous procedures include-file

To use a source module, you must compile it and then merge it with the program at user-process
build time. The associated include-file must be included in the program at compile time.
To use KXJ shared memory:
1.

Set up a MicroPower/Pascal shared region on the arbiter side and another one on the KXJ
side that corresponds to the KXJ shared memory area you intend to use.
You need to know the start address and size on the Q-bus side. Once you know the size,
it fixes the start address on the KXJ side at 2000000(8) minus the size. If you don't know
the needed size, pick a size large enough for all possible needs, but less than the size of
the KXJ application.
Use the appropriate MEMORY macro in the kernel configuration file on each side-specify
start, size, res=YES, and name. (The names on the two sides can be different.) At system
start-up time, the kernel on each side allocates the region and creates a shared region of
the specified name.

B-52

Enable the KXJ shared memory by using the KXJ-ENABLE_SHARED procedure. If the
Q-bus start address and size are known at build time, the KXJ application uses those
parameters to enable shared memory. Otherwise, the arbiter determines the parameters and
communicates them to the arbiter by means of the KX/KK communication interface.

KXT11-CA and KX/11-CA Peripheral Processors

Once the shared memory is enabled, each side can access its MicroPower/Pascal shared
region by using the name specified in the MEMORY macro.
You then use the
MAP_WINDOW procedure (or the MAPW$ primitive from MACR0-11) to map to the
shared region (which is also the KXJ shared memory).
On the arbiter side, if the processor supports caching, the accessing process must disable
cache in each PAR that maps to KXJ shared memory by specifying caching:=disable in the
MAP_WINDOW primitive call. This is necessary because accesses by the KXJ to the KXJ
shared memory do not invalidate the arbiter cache.

To synchronize access to KXJ shared memory, pass messages between the arbiter and the
KXJ by using the KX/KK communication interface.

When you have finished using KXJ shared memory, you can disable it by using the
KXJ_DISABLE_SHARED procedure.
If you have more than one KXJ and plan to use KXJ shared memory on them, you can either

set up one MicroPower shared region in the arbiter to include all the KXJ shared memory
for all KXJs, or you can set up a separate MicroPower/Pascal shared region to correspond
to each KXJ shared memory.

B.8.1 KXJ_ENABLE_SHARED
Enables KXJ shared memory at the specified Q-bus starting address for the specified size. The
KXJ shared memory is at the top of memory on the KXJ side. The range of Q-bus addresses
must be available.
Syntax
KXJ_ENABLE_SHARED (start,size,status)

Parameter

Type

Description

start

LONG_INTEGER

Q-bus physical starting address in bytes.
multiple of 4KW (20000(8)).

size

LONG_INTEGER

Size of shared region in bytes. Must be a multiple of 4KW
(20000(8)). Must be less than 2000000(8) minus size of
KXJ application.

status

var status

Optional parameter for return of status information.

Must be a

Error Returns
ES$ILV
Either the start or size is an illegal value-not a multiple of 4KW; or the size is
greater than or equal to 2000000(8).
No error is reported if the KXJ shared memory overlaps the KXJ application.
However, this may cause unpredictable results since the arbiter application may
corrupt the KXJ application.

KXT11-CA and KX/11-CA Peripheral Processors

B-53

B.8.2 KXJ_DISABLE_SHARED
Disables KXJ shared memory, making it no longer visible on the Q-bus.
Successive
KXJ_ENABLE_SHARED calls perform implicit KXJ_DISABLE_SHARED calls before reenabling
KXJ shared memory. You need not perform a KXJ_DISABLE _SHARED first.
Syntax
KXJ_DISABLE_SHARED (status)

Parameter

Type

Description

status

var status

Optional parameter for return of information.

Error Returns
None.

B.8.3 Arbiter and KXJ Configuration Files and Applications
The following files show an arbiter configuration file, an arbiter application, a KXJ configuration
file, and a KXJ application. The arbiter sends the Q-bus start address 1200000(8) and size
20000(8) to the KXJ by means of the KX/KK communication interface. The KXJ application
enables shared memory and tells the arbiter the status of the operation. The arbiter then
initializes the KXJ shared memory area with the values 1 to 4096 and tells the KXJ it is ready
for it to increment the values. The KXJ increments the values by 1 and notifies the arbiter that
it has completed the operation. The arbiter checks the values and, if they are correct, tells the
KXJ to increment the values again. This process continues until the KXJ has incremented all
the values 100 times. Then the arbiter tells the KXJ to disable shared memory. After that, the
entire operation is repeated, starting with the enabling of KXJ shared memory.
-Config file for arbiter side - shared memory example
;File cfdmash2.mac - arbiter side for shared memory test. Includes kx support.
;Use a MPP static shared region for the KXJ shared memory area .
. enabl
LC
;+

; Configuration file for a mapped LSI--11/23 target
THIS SOFTWARE IS FURNISHED UNDER A LICENSE AND MAY BE USED OR COPIED
ONLY IN ACCORDANCE WITH THE TERMS OF SUCH LICENSE.
COPYRIGHT (c) 1984, 1986 BY DIGITAL EQUIPMENT CORPORATION. ALL RIGHTS RESERVED.
;+

Module name: CFDMASH2.MAC
System: Micropower/Pascal

B-54 KXTl 1-CA and KX/11-CA Peripheral Processors

Functional Description:
This module describes a hardware and system software configuration in
which an application is to run. The file must be edited by the user to
reflect a specific application environment and then be assembled. The
resulting object module is used to build the kernel.
The following set of macros may be used in a configuration file. The
CONFIGURATION macro must be the first macro evoked. The ENDCFG macro must
be the last. A configuration file must contain at a minimum the
CONFIGURATION, SYSTEM, PROCESSOR, MEMORY, DEVICES, and ENDCFG macros.
In the following condensed syntax descriptions, brackets ([ ... ]) indicate
optionality, braces ({ ... }) enclose alternatives, and single parameter
values shown in optional arguments indicate defaults.
CONFIGURATION [version-name]
SYSTEM optimize={YESINO},debug={YESINO},addrcheck={YESINO}
PROCESSOR mmu={YESINO},[fpu={FP11IFIS}].
type={L112IL1123IFALCIFALCPLUSIJ11IKXT11CIKXJ11C},
[vector=nnnn],
clock={NONEl50HZl60HZl100HZl800HZ}, [clkcsr=nnnnnn]
(Vector default is 1000 octal for an L11x or J11 target type.)
Note: Standard clock CSRs, if present, are:
For an LSI11/23-PLUS or J-11 = 177546
For a KXT11--CA or KXJ11--CA
= 177520
MEMORY base=nnn,size=mmm,type=ROMIRAM,parity={YESINO},[csr=nnnnnn].
volatile={YESINO},res={YESINO}[,name=string]
DEVICES
vectaddr1,vectaddr2, ... ,vectaddr6
RESOURCES [stack= .. KIS], [packets=20.], [structures=3000.], [ramtbl=20.]
PRIMITIVES p1,p2,p3,p4,p5,p6
Parameters can be:
ALL
- All primitives (default for p1, ... ,p6)
BCSEM - Binary and counting semaphore primitives
COMPLX - Complex primitives
EXCMGT - Exception handling primitives
INTMGT - Interrupt handling primitives
LOGNAM - Logical name primitives
DRAM
- Region allocation, sharing, and mapping primitives
PRMGT - Process management primitives
QSEMN - Nonprivileged queue-semaphore primitives
QSEMP - Privileged queue-semaphore primitives
RBUF
- Ring buffer primitives
STRMGT - Structure management primitives
TIMER - Clock service primitives
V1
- All V1 primitives
xxxx
- where xxxx is a specific primitive name (no $)
Required if processor type is FALC or FALCPLUS -FALCON trap140={BHALTINXM},break={ROMODTISFWODTIEXCEPTIONIIGNOREIHANG}
Required if processor type is KXT11C -KXT11C bhalt={YESINO},reset={IGNOREIBOOTIRSTBOTIINTRPT},map=n
Required if processor type is KXJ11C -KXJ11C bhalt={YESINO},reset={IGNOREIBOOTIRSTBOTIINTRPT}

KXT11-CA and KX]l 1-CA Peripheral Processors

B-55

TRAPS t1,t2,t3,t4,t5,t6,t7,t8
Parameters can be:
ALL - TR4, Tio·, BPT, EMT, and TRP (standard LSI--11 set)
TR4
Trap to 4 (bus timeout)
T10 Trap to 10 (reserved instruction)
BPT Breakpoint instruction trap
EMT
EMT instruction trap
TRP
TRAP instruction trap
MPT - Memory parity error
FIS
FIS exception trap
FPP
FPP exception trap
MMU - Memory management fault
BRK
FALCON (SBC--11/21) BREAK level-7 trap
LOGICAL
name, string
ENDCFG
If the value of the SYSTEM macro optimize argument is YES, the RESOURCES,
TRAPS, and PRIMITIVES macros are required. If the optimize argument value is
NO (default), the RESOURCES, TRAPS, and PRIMITIVES macros are defaulted and
should not appear in the configuration file .

. enabl
GBL
.mcall
CONFIGURATION
.sbttl
System Configuration File For Mapped LSI--11/23 Target
CONFIGURATION
.
SYSTEM
debug=YES, optimize=NO
; ADDRCHECK defaults to DEBUG
; value
; Optimize=NO implies the defaults for RESOURCES, PRIMITIVES, and TRAPS
macros
PROCESSOR mmu=YES, type=L1123, clock=60HZ
MEMORY
base=O, size=<32.*32.>, type=RAM
;Assumes 32K words of
;volatile RAM
;MPP shared region for KXJ shared memory area. 128 KW at starting at
;1200000(8). This is assumed to be the maximum size region we will ever need
;in the application.
MEMORY
base=12000, size=<128.*32.>, type=RAM, res=YES, name=ARBSHR
DEVICES
60,64,100,300,304
;Vectors for console terminal, clock,
;and a second serial-line unit
DEVICES
500,504
;KX driver units.
ENDCFG
.end
-User program for arbiter side - shared memory example
{file tshra2.PAS - arbiter side.}
[ SYSTEM(MICROPOWER), PRIORITY(50),
DATA_SPACE(2100), STACK_SIZE (200)] PROGRAM tshra2;
{Have the KXJ set enable an area of shared memory, initialize the first
4 KWs, tell the KXJ to update it, then check it. Do the update and
check 100 times. Then have the KXJ disable the shared memory. Then
enable the shared region again, and so on. Always with the same start
address (1200000(8)) and size (40000(8)). The MPP shared region is
created at build time.}

B-56

KXT11-CA and KXJ11-CA Peripheral Processors

{$NOLIST}
%include 'micropower$lib:escode.pas'
%include 'micropower$lib:misc.pas'
%include 'micropower$lib:kxinc.pas'
%include 'micropower$lib:dram.pas'
{$LIST}
CONST
message_ length
big_array_size

{ get exception codes}
{ get shared memory routine}
{ get KX routines}
{ get dynamic ram routines}

4096;

TYPE
big_array =array [1 .. big_array_size] of integer;
{Define fields in Message which contain the Qbus starting address and the
size, both in bytes}
other = record
a : integer;
addr : long_integer;
addr1 : long_integer;
d : integer;
end;
VAR
message : array [1 .. message_length] of integer;
{First word contains the command:
1 enable shared memory
2 ok to access the region and add 1 to each value
3 disable shared memory.
On an enable shared memory command, the second and third words are for
passing the Qbus starting address for the shared memory area in bytes.
The fourth and fifth words are for passing the size of the shared
memory area in bytes.
The last word is for status returns:
1 success
2
enable shared memory failed
3 protocol error
4
end of test
}

my_exc_status : exc_status;
actual_length,rwstatus : unsigned;
i,j ,k,error : integer;
test_array : big_array;
q : Abig_array;
MY_RIB : region_id_block;
start_addr : long_integer;
start,size_region : unsigned;
start_region : unsigned;
ready : CHAR;
readyb : boolean;
{Main program}
BEGIN

KXT11-CA and KX/11-CA Peripheral Processors

B-57

readyb := false;
while not readyb do
begin
writeln ('Type R when you are ready to begin');
readln (ready);
if (ready="R") or (ready="r") then
readyb ·= true;
end;
while true do
begin
{Set start and size of shared region}
start_addr := %0'1200000';
message: :other.addr := %0'1200000';
start_region := ushort ((message: :other.addr) div 64);
message: :other.addr1 := %0'40000';
size_region := ushort ((message: :other.addr1) div 64);
message[1] := 1;
rwstatus := kx_write_data (buffer := message,
length := 2*message_length,
ret_length
actual_length);
IF rwstatus <> es$nor THEN
begin
WRITELN ('Write of shared memory command failed');
stop
end
else
begin
kx_read_data (buffer := message,
rwstatus
length := 2*message_length,
ret_length := actual_length);
i f message [message_length] <> 1 then
begin
writeln ('Enable shared memory failed');
stop;
end
else
begin
access_shared_region (rib := my_rib,
name := 'ARBSHR');
map_window (rib := my_rib,
caching := disable,
{disable caching}
length := size(big_array),
offset := 0,
window_ptr := q);
for j := 1 to big_array_size do
begin
test_array [j] · = j ;
q~[j]

·= j;

end;

B-58

KXTl 1-CA and KX/11-CA Peripheral Processors

for j := 1 to 100 do
begin
for k := 1 to big_array_size do
test_array[k] := test_array[k]+1;
message[1] := 2;
message[message_length] := 0;
rwstatus := kx_write_data (buffer := message,
length := 2*message_length,
ret_length := actual_length);
rwstatus
kx_read_data (buffer := message,
length := 2*message_length,
ret_length := actual_length);
if message[message_length] <> 1 then
begin
writeln ('Error on KXJ access
',j);
writeln ('Error is: ',message[message_length]);
end
else
begin
error := O; {Clear error count}
for i := 1 to big_array_size do
if q-[i] <> test_array[i] then
error := error + 1;
if error <> 0 then
begin
writeln ('Error on pass
',j,'. ',error,' errors.');
stop;
end;
end;
END;
writeln ('All 100 accesses passed.');
message[1] := 3; {disable shared memory}
message[message_length] := O;
rwstatus := kx_write_data (buffer := message,
length := 2*message_length,
ret_length := actual_length);
rwstatus ·= kx_read_data (buffer := message,
length := 2*message_length,
ret_length := actual_length);
if message[message_length] <> 1 then
begin
writeln ('Error disabling shared memory.');
stop;
end;
end;
unmap_window (length := size(big_array),
window_ptr := q);
end;
end;
end.

KXTl 1-CA and KX/11-CA Peripheral Processors

B-59

-Conf ig file for the KXJ side for shared regions
;File CFDTSHRL3.MAC - create static shared region RESSHR for KXJ shared
memory
;of size 128 KW
.enabl
LC
;+

; Configuration File For Mapped KXJ11--CA Target without J11 mapping support
THIS SOFTWARE IS FURNISHED UNDER A LICENSE AND MAY BE USED OR COPIED
ONLY IN ACCORDANCE WITH THE TERMS OF SUCH LICENSE.
COPYRIGHT (c) 1986 BY DIGITAL EQUIPMENT CORPORATION. ALL RIGHTS RESERVED.
;+

Module name: CFDTSHRL3.MAC
System: Micropower/Pascal
Functional Description:
This module describes a hardware ·and system software configuration in
which an application is to run. The file must be edited by the user to
reflect a specific application environment and then be assembled. The
resulting object module is used to build the kernel.
The following set of macros may be used in a configuration file. The
CONFIGURATION macro must be the first macro evoked. The ENDCFG macro must
be the last. A configuration file must contain at a minimum the
CONFIGURATION, SYSTEM, PROCESSOR, MEMORY, DEVICES, and ENDCFG macros.
In the following condensed syntax descriptions, brackets([ ... ]) indicate
optionality, braces ({ ... }) enclose alternatives, and single parameter
values shown in optional arguments indicate defaults.
CONFIGURATION [version-name]
SYSTEM optimize={YESINO},debug={YESINO},addrcheck={YESINO}
PROCESSOR mmu={YESINO},[fpu={FP11IFIS}],
type={L112IL1123IFALCIFALCPLUSIJ11IKXT11CIKXJ11C},
[vector=nnnn] .
clock={NONEl50HZl60HZl100HZl800HZ}, [clkcsr=nnnnnn]
(Vector default is 1000 octal for an L11x or J11 target type.)
Note: Standard clock CSRs, if present, are:
For an LSI11/23-PLUS or J-11 = 177546
For a KXT11--CA or KXJ11--CA = 177520
MEMORY base=nnn,size=mmm,type=ROMIRAM,parity={YESINO},[csr=nnnnnn],
volatile={YESINO},res={YESINO}[,name=string]
DEVICES
vectaddr1,vectaddr2, ... ,vectaddr6
RESOURCES [stack= .. KIS]. [packets=20.] ,[structures=3000.] ,[ramtbl=20.]
PRIMITIVES p1,p2,p3,p4,p5,p6
Parameters can be:
ALL
- All primitives (default for p1, ... ,p6)
BCSEM - Binary and counting semaphore primitives
COMPLX - Complex primitives
EXCMGT - Exception handling primitives
INTMGT - Interrupt handling primitives
LOGNAM - Logical name primitives
DRAM
- Region allocation, sharing, and mapping primitives
PRMGT - Process manag'ement primitives
QSEMN - Nonprivileged queue-semaphore primitives

B-60

KXT11-CA and KX/11-CA Peripheral Processors

QSEMP - Privileged queue-semaphore primitives
RBUF
- Ring buff er primitives
STRMGT - Structure management primitives
TIMER - Clock service primitives
V1
- All V1 primitives
xxxx
- where xxxx is a specific primitive name (no $)
Required if processor type is FALC or FALCPLUS -FALCON trap140={BHALTINXM},break={ROMODTISFWODTIEXCEPTIONIIGNOREIHANG}
Required if processor type is KXT11C -KXT11C bhalt={YESINO},reset={IGNOREIBOOTIRSTBOTIINTRPT},map=n
Required if processor type is KXJ11C -KXJ11C bhalt={YESINO},reset={IGNOREIBOOTIRSTBOTIINTRPT}
TRAPS t1,t2,t3,t4,t5,t6,t7,t8
Parameters can be:
ALL - TR4, T10, BPT, EMT, and TRP (standard LSI--11 set)
TR4 - Trap to 4 (bus timeout)
T10 - Trap to 10 (reserved instruction)
BPT - Breakpoint instruction trap
EMT - EMT instruction trap
TRP - TRAP instruction trap
MPT - Memory parity error
FIS - FIS exception trap
FPP - FPP exception trap
MMU - Memory management fault
BRK - FALCON (SBC--11/21) BREAK level-7 trap
LOGICAL
name, string
ENDCFG
If the value of the SYSTEM macro optimize argument is YES, the RESOURCES,
TRAPS, and PRIMITIVES macros are required. If the optimize argument value is
NO (default), the RESOURCES, TRAPS, and PRIMITIVES macros are defaulted and
should not appear in the configuration file .

. enabl
.mcall
.sbttl

GBL
CONFIGURATION
System Configuration File For Mapped KXJ11--CA Target

CONFIGURATION
SYSTEM
PROCESSOR

debug=YES, optimize=YES

; ADDRCHECK defaults to DEBUG
; value
mmu=YES, type=KXJ11C, j11map=no, vector=400, clock=60HZ,
clkcsr=177520

; Uses 64KB of volatile native RAM total in low memory
;Leave a hole of 128. bytes for the firmware stack just below 160000
MEMORY
base=O, size=<<28.*32.>-2>, type=RAM
MEMORY

base=<28.*32.>, size=<4.*32.>, type=RAM

;Create a shared region from 1000000(8) to 1777777(8), at the top of RAM
;memory. Use this for mapping the shared memory which is enabled on the Qbus.
;It is set up as the maximum size of shared memory which might ever get enabled
;in the application (128 KW).
MEMORY
base=10000, size=<128.*32.>, type=RAM, res=YES, name=RESSHR

KXT11-CA and KX/11-CA Peripheral Pro1.- ?ssors

B-61

KXJ11C

bhalt=YES, reset=IGNORE

RESOURCES

packets=10 .. structures=2048.

PRIMITIVES

ALL

TRAPS

ALL

;Implies T4, T10, BPT, EMT, and TRP

DEVICES

60,64,100

; DEVICES

104

;Console serial line (SLU1)
;and clock vectors
;Spare timer vector, if used

DEVICES

120,124,130

;Two-Port RAM arbiter write interrupts

DEVICES
DEVICES

140' 144. 150. 154
160,164,170,174

;SLU2 pseudo-vectors - channel A
;SLU2 pseudo-vectors - channel B

DEVICES

200,204,210

;PIO and counter/timer vectors

;Small pools for packets
;and kernel structures

; Include the following only if reset=INTRPT in KXJ11C macro
; DEVICES
220
;Simulated QBUS reset-interrupt vector
;DEVICES
224,230
;DMA vectors
ENDCFG
.end
-User program -- KXJ side
{file tshrl3s.pas - assumes MPP "shared region" is created at build
time, with the name RESSHR. We just ACCESS it here and then map to it.
Make it a big shared region - map at approproate offset to get to the
start of the Qbus shared area. Size of KXJ shared memory area may vary.
Need device access for kxj_enable_shared and kxj_disable_shared}
[ SYSTEM(MICROPOWER), PRIORITY(50),
DATA_SPACE(2100), STACK_SIZE (200),DEV_ACCESS] PROGRAM tshrl3;
{$NOLIST}
~
{ get exception codes}
%include 'micropower$lib:escode.pas'
{ get shared memory routine}
%include 'micropower$lib:misc.pas'
{ get KK routines}
%include 'micropower$lib:kkinc.pas'
{ get dynamic ram routines}
%include 'micropower$lib:dram.pas'
{$LIST}
TYPE
big_array =array [1 .. 4096] of integer;
other = record
a : integer;
addr : long_integer;
addr1 : long_integer;
d : integer;
end;
CONST
message_length = 6;
big_array_size = 4096;

B-62

KXT11-CA and KXf 11-CA Peripheral Processors

VAR
message : array [1 .. message_length] of integer;
{First word contains the command:
1
enable shared memory
2 = ok to access the region and add 1 to each value
3 =disable shared memory.
The last word is for status returns:
1
success
2
enable shared memory failed
3
protocol error
4
end of test
}

my_exc_status
exc_status;
actual_length,rwstatus : unsigned;
i,j ,bigloop : integer;
q :, -Big_array;
MY_RIB : region_id_block;
start_addr,local_start_addr
long_integer;
start : unsigned;
shared_size : long_integer;
shared_size_particks : integer;
offset_into_region : unsigned;
{Main program}
BEGIN
bigloop := O;
while true do
begin
bigloop := bigloop +1;
rwstatus := kk_read_data (buffer := message,
length := 2*message_length,
ret_length := actual_length);
IF rwstatus <> es$nor THEN
WRITELN ('Read of shared memory info from arbiter failed')
else
begin
if message[!] <> 1 then
begin
writeln ('Wrong command. Should be an enable shared memory command.');
message[message_LENGTH]
3;
end
else
begin
start_addr :=message: :other.addr;
shared_size := message: :other.addr1;
shared_size_particks := ushort (shared_size div 64);
kxj_enable_shared(start := start_addr,
size := shared_size,
status := my_exc_status);
if my_exc_status.EXC_CODE = es$nor then
begin
writeln ('Enable shared memory
',bigloop,' succeeded');
local_start_addr
%0'2000000' - shared_size;

KXT11-CA and KX/11-CA Peripheral Processors

B-63

message[message_length]
1;
end
else
begin
writeln ('Enable shared memory
',bigloop,'
'failed. Status code is ',
oct(my_exc_status.exc_code), 'octal.');
message[message_length] := 2;
end;
rwstatus := kk_write_data (buffer :=message,
length := 2*message_length,
ret_length := actual_length);
access_shared_region (rib := my_rib,
name := 'RESSHR');
{May have to alter this depending on where the shared area starts
compared to where the statically created shared region starts}
offset_into_region := ushort(local_start_addr div 64);
offset_into_region := offset_into_region my_rib.region_address;
map_window (rib := my_rib,
length := size(big_array) ,
offset := offset_into_region,
window_ptr
q);
for j := 1 to 100 do
begin
rwstatus
kk_read_data (buffer := message,
length := 2*message_length,
ret_length
actual_length);
if message[1] <> 2 then
begin
writeln ('Protocol error.');
message [message_length] := 3;
end
else
begin
for i := 1 to big_array_size do
q- [i] : = q- [i] + 1;

message[message_length] := 1;
end;
rwstatus := kk_write_data (buffer := message,
length := 2*message_length,
ret_length := actual_length);
writeln ('Access
',j,' to shared region completed.');
end;
rwstatus := kk_read_data (buffer := message,
length := 2*message_length,
ret_length
actual_length);
if message[1] <> 3 then
begin
writeln ('Protocol error, should be disabling.');
message[message_length]
3;
end
else
kxj_disable_shared (status := my_EXC_STATUS);
if my_exc_status.EXC_CODE = es$nor then
begin
writeln ('Disable shared memory

B-64

KXT11-CA and KXf 11-CA Peripheral Processors

bigloop,' succeeded');
message [message_length] := 1;
end
else

BEGIN
writeln ('Disable shared memory
bigloop,' failed. Status code is ',
oct(my_exc_status.exc_code),'octal. ');
message[message_length] := 4;
end;
rwstatus := kk_write_data (buffer := message,
length := 2*message_length,
ret_length := actual_length);
end;
unmap_window (length := size(big_array),
window_ptr := q);
end;
end;
end.

B. 9 Calculating Checksums for PROMS
This section tells you how to use the VMS DECprom program to calculate checksums for PROM
devices (programmable read-only memories) on the KXTl 1-CA. The checksums calculated by
this method can be verified by the ROM checksum test performed by the KXTl 1-CA self-tests in
the native firmware. The KXT11-CA Single-Board Computer User's Guide describes the algorithm
that the ROM checksum test uses to calculate checksums.
DECprom calculates only checksums for PDP-11 processors based on a 16-bit system word.
The ROM checksum test in the KXTl 1-CA native firmware expects that each PROM device will
contain its own (byte) checksum. Therefore, you must calculate a separate checksum for each
PROM device, then load the appropriate checksum value into the last location of each device.
The following procedure assumes you know how to use DECprom. See the VAX/VMS DECprom
User's Guide for detailed reference information.
1.

Using an initialization file that is appropriate for your PROM devices, run DECprom.

Set the system word width to 16 bits.

Load the PROM devices from the input file type of your choice (.MIM, .LDA, .SAV) but
leave the last location of each PROM empty.

Exit DECprom.

Perform steps 1 and 2 (above), but set the system word width to eight bits. This allows
DECprom to calculate a byte-wide checksum.

LIST the contents of each PROM in a binary (.SAV) file. This will produce a file for the
low-byte device and a file for the high-byte device.

Calculate a separate checksum for each file (CALC_CHECKSUM command).

Store the appropriate checksum in the last location of each device (STORE_CHECKSUM
command).

KXT11-CA and KX]11-CA Peripheral Processors

B-65

For the KXJl 1-CA, the standard DECprom checksum algorithm is used, but with one checksum
for the native firmware and another checksum for the user application, if any. See the KX/11CA Single-Board Computer User's Guide for details on how to burn ROM chips and include
checksums.

B. l O Load Application onto KXT l 1-CA/KXJ l 1-CA Procedure
KXT_LOAD and KXJ_LOAD are MicroPower/Pascal procedures that run on the arbiter and
are used to load and start a MicroPower/Pascal application on a KXTll-CA or KXJll-CA
respectively. The procedure reads in a .MIM file one block at a time and commands a KXTllCA or KXJll-CA to DMA each block into its local memory. When all blocks have been loaded
into the KXT's or KX]'s memory, QBUS ODT commands are given to the KXT or KXJ thereby
causing it to start the application (jump to the address contained in octal location 24).

B. l 0. l .MIM File
The file that the KXT_LOAD or KXJ_LOAD procedure loads is the KXT or KXJ memory image
file (.MIM) that is output by the MIB utility. To be loaded onto a KXTll-CA with KXT_LOAD,
the memory image must be in an unmapped format. For a KXJl 1-CA, the memory image can
be either mapped or unmapped. Neither the KXT nor the KXJ memory image being loaded
should contain the Debug Service Module (DSM).
The .MIM file may or may not have the TU58 boot program installed in it. The load utility
will skip over and ignore the boot if it exists. Thus, a memory image loadable in two different
ways can be built. The memory image can be copied to a TU58 tape and booted via the KXT
or KXJ console port or it can reside on one of the arbiter's file-structured devices and be booted
via the KXT_LOAD or KXJ_LOAD procedure.

B. l 0.2 User's Interface
You gain access to the KXT_LOAD or KXJ_LOAD procedure by including the definition file
MISC.PAS in your program source. You must compile the module KXTLO.PAS (which contains
the source code for both KXT_LOAD and KXJ_LOAD) and merge it with your program at
user-process build time.
A process that calls the KXT_LOAD or KXJ_LOAD procedure must observe the following
guidelines:
•

The process must have access to the 1/0 page.

•

The KXT_LOAD or KXJ_LOAD procedure can load only one KXT or KXJ at a time. If
multiple KXT /KXJ loads are required, the calling process must either serialize them or have
multiple processes calling the KXT_LOAD or KXJ_LOAD procedure.

B-66 KXTl 1-CA and KX/11-CA Peripheral Processors

The syntax for calling the KXT_LOAD procedure is given below. The syntax for calling the
KXJ_LOAD procedure is the same as that for calling KXT_LOAD except for the obvious need
to change occurrences of KXT to KXJ:
KXT_LOAD (KXT_ADDR,MIMF,STATUS);

Parameter

Type

Description

KXT__ADDR

UNSIGNED

Virtual address of KXTl 1-CA

VAR MIMF

[READO NLY]P ACKED
ARRAY [ L..U:
INTEGER ] OF CHAR

File name

VAR STATUS

EXC_STATUS

System error code optional argument

B. 10.3 Program Example
The following program uses the KXT_LQAD procedure to load a sample KXTl 1-CA application
into KXTll-CA ID 2 with the board configured for the low address range. (KXTll-CA ID
numbers are listed in Section B.5.) The KXJl 1-CA application is similar, with "KXJ" replacing
"KXT."
[SYSTEM(MICROPOWER), STACK_SIZE(1000), PRIORITY(10), DATA_SPACE(3000),
DEV_ACCESS ]
PROGRAM LOADK ;
{ Define the Load Procedure }
%include 'MISC.PAS'
{ Define Address for KXT11--CA ID 2 }
CONST
KXT2_ADDR = %0'160100'
{ Define Error Return Status }
VAR
LOAD_RESULTS : EXC_STATUS ;
{ Main Program }
BEGIN
KXT_LOAD (KXT_ADDR := KXT2_ADDR,
MIMF := 'DYAO:EXKXT.MIM',
STATUS := LOAD_RESULTS);
END.

KXT11-CA and KX]11-CA Peripheral Processors

B-67

Appendix C
XL Serial Line Driver
This chapter describes the use of the MicroPower/Pascal XL serial line driver, which supports
operations on terminals and other devices attached to serial line interfaces.
Note
In Version 2 of MicroPower/Pascal, the XL driver has been superseded by the
TT driver, described in Chapter 3. However, the XL driver is supplied on the
distribution kit in three versions (PDP-11 mapped, PDP-11 unmapped, and
KXTl 1-CA) for existing applications that require it. DIGITAL recommends that
applications use the TT driver.
Since the XL driver has been superseded by the TT driver, support for new
hardware has not been added. Therefore, the XL driver is not supported on the
KXJll-CA.

C. l PDP-11 XL Driver
The XL device driver supports If O operations on devices connected through a DLVl 1 type of
serial line interface unit. The DLVll, DLVll-E, DLVll-F and DLVll-J; the MXVll-A and
MXVll-B serial lines; and the SBC-11/21 serial lines are supported by the XL driver.
The XL driver performs input and output operations in either block mode or ring mode. In
block-mode input, a specified number of bytes are transferred directly from the serial line unit
to the requester's buffer space, per read request. In block-mode output, a specified number of
bytes are transferred from the requester's data buffer to the serial line unit, per write request.
Block-mode input is provided for input devices that, presumably, transmit data in blocks, or
bursts of characters, of predetermined length, with some time lapse between block transmissions.
In ring-mode input, the driver continuously transmits bytes from the serial line unit to an input
ring buffer specified by the requester. Once initiated by a Connect Receive Ring Buffer request
for a given unit, the input operation continues until the ring buffer is disconnected.

XL Serial Line Driver

C-1

In ring-mode output, the driver continuously transmits bytes from an output ring buffer, as they
become available, to the specified serial line unit. The requester or some other process must first
put characters into the ring buffer. Following this, the process issues a Connect Transmit Ring
Buffer request for a given unit, which starts the output transfer. The output operation continues
until the ring buffer is disconnected. Ring mode is intended for unbounded or interactive input,
such as from a terminal keyboard or an instrument that continuously monitors some fluctuating
quantity-for example, a voltage or temperature.
For output requests, the driver provides optional XOFF /XON control character processing. If
requested, the driver inhibits the output side of a given serial line unit when it detects an
XOFF character on the input side and reenables the output when a subsequent XON character
is received.
For interface units that support modem control (DLVl 1-E), the driver allows you to enable dataset interrupts and to receive data-set status information, analogous to RCSR contents, when
such interrupts occur. The driver also allows you to get (inspect) data-set status information
and to set certain XCSR and RCSR bits; this permits you to control baud rate, if programmable,
to exercise modem control, and to transmit break signals.
The XL driver normally consists of two processes-a request-handling main process and a
line-control subprocess. These two processes control all the serial line interface units that may
be configured on the target system. In ring buffer output mode, however, a helper process is
created for each line so connected, to facilitate low-overhead output operations.
The driver's request queue semaphore name is $XLA. The desired serial line is specified in the
function request by a configuration-determined unit number.
Each DLVl 1 interface unit is factory-configured with standard device register and interrupt
vector addresses. When more than one serial line unit is included in a system, or if the
standard address assignments are not desired, you must reconfigure the unit(s) in question for
appropriate device register andinterrupt vector addresses. In any case, the device register and
vector addresses used-whether standard or not-must be specified in a kernel configuration
file (see Chapter 4 of the MicroPower /Pascal Run-Time Services Manual) and in a driver prefix
file (see Section C.1.4).

C-2

XL Serial Line Driver

C. 1. l Functions Provided
The following functions provided by the XL driver are listed by symbolic and decimal function
code:

Code

Function Performed

IF$RDP (0)
IF$RDL (1)

Read Physical
Read Logical

IF$WTP (3)
IF$WTL (4)

Write Physical
Write Logical

IF$SET (6)
IF$GET (7)

Set Status
Get Status

IF$CRR (8)
IF$CXR (9)
IF$DRR (10)
IF$DXR (11)
IF$RSC (12)

Connect Receive Ring Buffer
Connect Transmit Ring Buffer
Disconnect Receive Ring Buffer
Disconnect Transmit Ring Buffer
Report Data-Set Status Change

For serial line service, there is no distinction between physical and logical function requests;
either function code may be used for block mode. One device-dependent function modifier bit
is significant for an output function request-either a write or a Connect Transmit Ring Buffer
function-as it enables automatic XOFF /XON control, as described below.

C. 1. 1. l Read Function
The IF$RDP or IF$RDL function is performed in block mode. The driver reads a specified
number of characters from the serial line unit into the buffer area identified in field DP.BUF of
the request message. No device-dependent function modifiers apply to a read operation request.
Read requests to a unit that has been connected to a ring buffer are not supported.

C. 1. 1.2 Write Function
The IF$WTP or IF$WTL function is performed in block mode; the source and amount of
the data to be transferred are specified by the DP.BUF field of the request message. One
device-dependent function modifier applies to write functions, as follows:

Bit

Significance

FM$XCK (11)

Enable automatic XOFF /XON processing if set; disable same if cleared

For automatic XOFF /XON processing, the driver intercepts any XON and XOFF characters that
occur in the input from a given interface unit. Receipt of an XOFF character causes the driver to
inhibit output from the same interface unit until a subsequent XON character is received. The
output line is initially assumed to be enabled. (Multiple successive XON or XOFF characters
have the same effect as one such character.) If XOFF /XON processing is not requested, the
driver passes all input characters to the user.
Write requests to a unit that has been connected to a ring buffer are not supported.

XL Serial Line Driver C-3

C. 1. 1.3 Connect Receive Ring Buffer Function
The IF$CRR function connects a user-specified ring buffer to a serial line unit and initiates input
to that ring buffer. Any input occurring on the line is transferred to the ring buffer identified
in request field DP.SGL; field DP.BUF of the request message is ignored. Input into the ring
buffer continues until the ring buffer is disconnected. No device-dependent function modifiers
apply to a Connect Receive Buffer request.

Note
When a line is connected to a ring buffer, all hardware errors are ignored,
including parity errors, framing errors, and overrun errors.

C. 1. 1.4 Disconnect Receive Ring Buffer Function
The IF$DRR function disconnects a user-specified ring buffer from a serial line unit. Any
subsequent input occurring on the line is ignored. No device-dependent function modifiers
apply to a Disconnect Receive Buffer request.
This request will not be honored for any line that a ring buffer was created for and connected
to as specified by the driver prefix file.

C. 1. 1.5 Connect Transmit Ring Buffer Function
The IF$CXR function connects a user-specified ring buffer to a serial line unit and initiates
output from that ring buffer. Any data put into the ring buffer identifier in request field
DP.SGL is output on the specified line. Field DP.BUF of the request message is ignored. One
device-dependent function modifier applies to write functions, as follows:

Bit

Significance

FM$XCK (11)

Enable automatic XOFF /XON processing if set; disable same if cleared

XOFF /XON processing is performed as described above for block-mode operations.

C. 1. 1.6 Disconnect Transmit Ring Buffer Function
The IF$DXR function disconnects a user-specified ring buffer from a serial line unit.
device-dependent function modifiers apply to a Disconnect Receive Buffer request.

C.1.1.7 Report Data-Set Status Change Function
The IF$RSC function allows the requester to wait for a change of data-set (modem) status to
occur on a specified serial line unit. When such a change occurs, the driver returns a standard
IF$GET reply message containing status information, as described in Section C.1.1.9. This
function is used to wait for signals, such as ring, lost carrier, and so forth.
When this function is requested, the driver assumes that modem control (data-set interrupts) has
been enabled by a previous Set Status (IF$SET) request. If this request is issued with data-set
interrupts disabled, the process will wait indefinitely. (Data-set control is meaningful only if the
specified serial line unit is a DLVl 1-E configured for full modem control.)

C-4 XL Serial Line Driver

For this function, you must specify a queue semaphore at DP .SGL to be signaled when a status
change occurs on the specified unit. The request holds for only one event. More than one
request for notification may be posted for a specified unit.

C. 1. 1.8 Set Status Function
The IF$SET function sets the specified interface unit's RCSR and/or XCSR with control bits that
allow the following actions to occur:
1.

Enable/disable modem control (DLVll-E only)

Load modem-status bits (DLVl 1-E only):
a.

Data terminal ready

Request to send

Secondary transmit

Transmit a break

Set programmable baud rate (DLVll-E, DLVll-F, MXVll-B, and SBC-11/21 only)

The desired status settings for the receiver status register are indicated by the bit settings of word
DP.RPS of the request message. The desired status settings for the transmitter status register
are indicated by the bit settings of word DP.XPS of the request message. The status-control
word is described in the next section.

c. l. 1. 9 Get Status Function
The IF$GET function returns information about the interface unit's status. The driver reads the
specified unit's RCSR and XCSR and returns selective information about its settings in the reply
message. Software-specified parameters are returned for both the receiver and the transmitter.
(The status information is specific to the hardware and varies accordingly.)

C. 1. 1. 1O Device-Independent Function Modifiers
If bit FM$BSM of DP.FUN is set, the XL driver signals a binary or a counting semaphore, as
described in Chapter 1. The setting of bit FM$INH of DP.FUN (inhibit soft-error retry) is not
meaningful for serial line service and is ignored by the XL driver.

C. 1.2 Function-Dependent Request Formats
The function-independent portion of a driver request message is described in Chapter 1. The
function-dependent portion of a XL driver request (following field DP .SEM) is described below
for each type of function.

XL Serial Line Driver C-5

C. 1.2. 1 Block-Mode Read or Write Functions
The function-dependent portion of a block-mode read request (function code IF$RDP or IF$RDL)
or of a write request (function code IF$WTP or IF$WTL) is shown below:

Portion of
the request
sent by value

DP.DAD -

Not used

DP.BUF -

-----------------,
Buffer address l

DP.PAR -

PAR value

--,

I
--1

Buffer length

DP.LEN -

Portion of the
request sent
by reference

+-----------------+

ML0-953-87

The unit number in the function-independent portion of the request selects the desired lineinterface unit; unit numbering starts at 0. The buffer address specifies the destination of the
data to be read or the source of the data to be written. The buffer-length v~lue determines the
length, in bytes, of the data transfer.

C. 1.2.2 Connect Receive or Transmit Ring Buffer Functions
The function-dependent portion of a Ring Buffer Connect request for either input or output
(function code IF$CRR or IF$CXR) is shown below:

Ring buffer

DP.RBF -

Portion of
the request
sent by value

Structure
ID

,-'
I

l-1
I

1-,
I

l--

Not used
I
I

--:

'
'
+-----------------+

C-6

XL Serial Line Driver

ML0-954-87

The unit number in the function-independent portion of the request selects the desired lineinterface unit; unit numbering start at 0. Field DP.RBF specifies, by structure ID, the destination
ring buffer for an input operation or the source buffer for an output operation. On input,
individual characters are put into the ring buffer as they are received; on output, individual
characters are transmitted from the ring buffer as they become available by action of the user
process. In either case, the length of the transfer is unlimited.

C.1.2.3 Disconnect Receive or Transmit Ring Buffer Functions
The function-dependent portion of a Ring Buffer Disconnect request, for either input or output
(function code IF$DRR or IF$DXR), is shown below. Its format is identical to that for the
connect request:

DP.REF -

Ring buffer
Structure

Portion of
the request
sent by value

Not used

+-----------------+

ML0-955-87

The unit number in the function-independent portion of the request specifies the line-interface
unit from which the ring buffer is to be disconnected. Field DP.RBF specifies, by structure ID,
the ring buffer that was previously connected to the unit in question. All input to or output
from the ring buffer ceases when the request is acted on by the driver.

C. 1.2.4 Set Status Function
The function-dependent portion of a Set Status request (function code IF$SET) is shown below:

XL Serial Line Driver C-7

I
I
I

,----------------DP.FDD - I
Not used
,----------------DP.RPS - I
RCSR
'----------------DP.XPS XCSR
I

DP.RSS -

Input status

DP.XSS -

Output status

:--

Portion of
the request
sent by value

Not used

+-----------------+

ML0-956-87

The request packet fields shown above have the following significance:

Field

Significance

DP.RPS

Status control bits to be set in the receiver CSR; these bit settings are hardwaredependent

DP.XPS

Status control bits to be set in the transmitter CSR; these bit settings are
hardware-dependent

DP.RSS

Receiver software status bit settings

DP.XSS

Transmitter software status bit settings

The bit settings of DP.RPS are used to set status control bits in the RCSR. DP.XPS is used to
set status control bits in the XCSR of the specified interface unit.
The format of the receiver _status-setting word is as follows:
15

+-------------------------------+
I I I I I I : I : : lei islrltlri
lxlxixlxlxixlxtxlxixlclxlxlxlrlel

+-------------------------------+
ML0-957-87
Proceeding from right to left in the format above:
•

The re bit (0), if set, advances the paper tape reader in DIGITAL-modified TTY units (L T33C, LT35-A,C) and clears the RCVR DONE bit in the RCSR (bit 7). The function of this bit
is hardware-dependent.

•

The tr bit (1), if set, indicates data terminal ready (DLVll-E only).

•

The rx bit (2), if set, indicates request to send (DLVl 1-E only).

•

The sx bit (3), if set, indicates secondary Xmit (DLVl 1-E only).

•

The ec bit (5), if set, enables modem control (DLVl 1-E only).

C-8 XL Serial Line Driver

The format of the transmitter status-setting word for the DLVll, DLVll-E, DLVll-F, DLVll-J,
and MXVll-A serial line interfaces is as follows:
15

+-------------------------------+
/b/b/b/b/l/ : : : : : : : : : :s:
lblblblblrlxlxlxlxlxlxlxlxlxlxlbl

+-------------------------------+
ML0-958-87
Proceeding from right to left in the format above:
•

The sb bit (0), if set, requests a BREAK to be transmitted on the output line.

•

The lr bit (11), if set, allows a new baud rate to be loaded.

•

The bb bits (12 to 15) indicate the desired baud rate for the unit, if the lr bit is also set
(valid only if the baud rate is programmable on the indicated unit).

The format of the transmitter status-setting word for the MXVl 1-B and SBC-11 /21 serial line
interfaces is as follows:
15

+-------------------------------+
l l l l l l l l l l lblb/blmlllsl
lxixlxlxlx/xlx/x/xlxlb/blblt/r/bl

+-------------------------------+
ML0-959-87
Proceeding from right to left in the format above:
•

The sb bit (0), if set, requests a BREAK to be transmitted on the output line.

•

The lr bit (1), if set, allows a new baud rate to be loaded.

•

The mt bit (2), if set, facilitates a maintenance self-test. When this bit is set, the transmitter
serial output is connected to the receiver serial input while the external serial input is
disconnected.

•

The bb bits (3 to 5) indicate the desired baud rate for the unit, if the lr bit is also set (valid
only if the baud rate is programmable on the indicated unit).

The format of the software status-setting words is as follows:
15

+-------------------------------+
l l l l l xi l l l l l l l l l l l
lxlxlxlxlcixixlxlxlxlxlxlxlxlxlxl

+-------------------------------+
ML0-960-87
Proceeding from right to left in the format above:
•

The xc bit (11), if set, requests XON/XOFF processing for the input side. No meaning is
assigned to this bit for the output side.

XL Serial Line Driver

C-9

C.1.2.5 Get Status Function
The function-dependent portion of a reply to a Get Status request (function code IF$GET) is
shown below:

DP. RPS -

--------+-------Type l Class
--------+-------RCSR

DP.XPS

XCSR

DP.RSS -

Input status

DP. CLS -

DP.XSS -

All the
request is
returned by value

Output status

+-----------------+

ML0-962-87

In the information above:
•

Class is DC$TER for serial line interfaces.

•

Type indicates the specific type of DLVl 1 interface, as follows:
TT$DL Minimum serial line capability (DLVl l, DLVl l-J, MXVl 1-A)
TT$DLE DLVl 1-E
TT$DLF DLVl 1-F
TT$DLT MXVll-B, SBC-11/21

The bit settings of DP .RPS and DP .XPS are used to report the setting of status control bits in
the RCSR and XCSR of the specified interface unit. The format of the status-setting word is as
follows:
15

+-------------------------------+
I lricicl isl I I I lml I I I I I
lxlilsldlxlrlxlxlxlxlclxlxlxlxlxl

+-------------------------------+
ML0-961-87
Proceeding from right to left in the preceding format:

C-10

•

The me bit (5), if set, indicates that modem control is enabled on the line.

•

The sr bit (10), if set, indicates secondary receive.

•

The cd bit (12), if set, indicates carrier detect.

•

The cs bit (13), if set, indicates clear to send.

•

The ri bit (14), if set, indicates that a ring has occ:urred.

XL Serial Line Driver

The format of the software status-setting words is as follows:
15

+-------------------------------+
I I I c I ri xi l I I I I I I I I I I
lxlxlflglclxlxlxlxlxlxlxlxlxlxlxl

+-------------------------------+
ML0-963-87
Proceeding from right to left in the format above:
•

The xc bit (11), if set, indicates XON/XOFF processing for the input side. No meaning is
assigned to the output side.

•

The rg bit (12), if set, indicates that the port is connected to a ring buffer. This is a read-only
bit.

•

The cf bit (13), if set, indicates that the port was connected to a ring buffer during
configuration.

C. 1.2.6 Report Data-Set Status Change Function
The function-dependent portion of a Report Data-Set Status Change request (function code
IF$RSC) is shown below:

DP.SGL -

Semaphore
Structure

Portion of
the request
sent by value

Not used

+-----------------+

ML0-964-87

The unit number in the function-independent portion of the request selects the desired lineinterface unit. Field DP.SGL specifies, by structure ID, the queue semaphore to be signaled
when a status change occurs on the specified unit.
The function-dependent portion of a reply to the Report Data-Set Status Change request is the
same as a reply to the Get Status function.

XL Serial Line Driver C-11

The bit settings of word DP .RPS are used to indicate the setting of status control bits in the
RCSR of the specified interface unit when a modem-state change occurs. The format of the
status-return word (identical to the word returned by Get Status) is as follows:
15

+-------------------------------+
I Ir: c: c: : s: I I : Iml : : : I :
ixlilsidixirlxlxixlxicixixlxixixi

+-------------------------------+
ML0-965-87
Proceeding from right to left in the format above:
•

The me bit (5), if set, indicates that modem control is enabled on the line.

•

The sr bit (10), if set, indicates secondary receive.

•

The cd bit (12), if set, indicates carrier detect.

•

The cs bit (13), if set, indicates clear to send.

•

The ri bit (14), if set, indicates that a ring has occurred.

C. l .3 Status Codes
The XL driver returns the following completion-status codes in field DP.STS of the reply
message:
Code

Meaning

ES$NOR

Normal success

ES$IFN

Invalid function code

ES$NXU

Nonexistent unit

ES$0VR

Overrun error on received data

ES$PAR

Parity error on received data

c. 1.4 PDP-11 XL Prefix File
Figure C-1 shows the PDP-11 XL driver prefix module, XLPFX.MAC. There are three other XL
prefix files: XLPFXD.MAC, for building an LSI application with debug support; XLPFXF.MAC,
for building a FALCON or FALCON-PLUS application with debug support; and XLPFXK.MAC,
for building a KXTl 1-CA application with debug support. Section C.2.4 discusses XLPFXK.MAC.
The other three prefix files differ prima~ily in the default CSR and vector addresses they provide.
The default CSR and vector assignments are as follows:
•

In XLPFX.MAC, CSR=l 77560 and VEC=60 (LSI console terminal port)

•

In XLPFXD.MAC, CSR=176500 and VEC=300 (Nonconsole terminal port)

•

In XLPFXF.MAC, CSR=176540 and VEC=120 (FALCON or FALCON-PLUS SLU2 port)

The following paragraphs describe the prefix file macro calls and symbol definitions that can be
edited to fit your application.

C-12

XL Serial Line Driver

$XLPRM labels a word specifying the number of serial line units to be supported by the XL
driver. You must modify that value to reflect the number of lines described in the prefix module,
that is, the number of line-definition (LINDF$) macros used in the file.

Note
When building an application with debug support, you must not specify a
LINDF$ macro for the host-to-target serial line used by P ASDBG. That line,
which must be connected to the target's console-terminal port, is handled directly
by the debug service module. (The default line definition in the XLPFX.MAC file
assumes an LSI application without debug support; it describes a line connected
to the LSI console terminal port-CSR 177560.)
LINDF$ is a macro call that supplies information about each supported line. One LINDF$ macro
must be used per serial line and must supply at least the vector and CSR addresses (receive side
only) for the line. A line type must also be specified for other than the basic DLVl 1 type of
line interface unit; the symbol TT$DLE must be specified, for example, for a DLVl 1-E interface
unit. An initial line speed must be specified if a line is configured for programmable baud rate.
The other LINDF$ arguments pertain to optional start-up time creation and connection of input
and output ring buffers for a given line.
Unit number assignments correspond to the order in which the LINDF$ macros occur in the
prefix file. That is, the first or only LINDF$ macro implicitly defines unit 0, the second defines
unit 1, the third defines unit 2, and so on.
The complete LINDF$ macro keyword syntax is as follows:
LINDF$
vec,csr,typ[=TT$DL] ,rnam,rsiz[=12.] ,ratt,rmod,xnam,
xsiz[=80.] ,xatt,xmod,spd

vec

The receive-side interrupt vector address for a given line; the transmit vector for that line is
assumed to follow the receive vector by 5 bytes. For example, vec=300 specifies a receive
vector at location 300 and implies a corresponding transmit vector at location 304.

csr
The receive-side CSR (RCSR) address for a given line; the transmit CSR (XCSR) for that
line is assumed to follow the RCSR by four bytes. For example, cs:r=176500 specifies an
RCSR at location 176500 and implies a corresponding XCSR at location 176504.
typ

The set of functional capabilities to be ~upported by the line, in terms of an interface unit
type:
TT$DL for the minimum common functions provided by a DLVll or DLVll-J interface
TT$DLE for a DLVll-E interface
TT$DLF for a DLVll-F interface
TT$DLT for a DLART-type interface jumpered for programmable baud rate.
Additional information on type TT$DLT is given below. The default is typ=TT$DL. Note
that type TT$DL can be specified for any kind of interface unit, provided that only common
DLVl 1 line functions are utilized.

XL Serial Line Driver C-13

rnam

The name of a receive ring buffer to be created and automatically connected to the line
by the XL driver at start-up time. The name must contain six characters, including trailing
blanks, if needed-for example, rnam= <INBUF > . The rnam parameter is optional.
rsiz

The size, in an even number of bytes, of the receive buffer. The default size is 12 bytes.
The rsiz parameter is meaningful only if you specify rnam.
raft

The access attribute of the receive buffer. Specify ratt=SA$RIR for record-oriented input
access (default) or ratt=SA$RIS for stream-oriented input access. The ratt parameter is
meaningful only if you specify rnam.
rmod

Receive-side mode bits. Specify rmod=F$XCHK to enable automatic XON/XOFF checking.
xnam

The name of a transmit ring buffer to be created and automatically connected to the line
by the XL driver at start-up time. The name must contain six characters, including trailing
blanks if needed-for example, xnam= <OUTBUF> . The xnam parameter is optional.
xsiz

The size, in an even number of bytes, of the transmit buffer. The default size is 80 bytes.
The xsiz parameter is meaningful only if you specify xnam.
xatt

The access attribute of the transmit buffer. Specify ratt=SA$ROR for record-oriented output
access (default) or ratt=SA$ROS for stream-oriented output access.
xmod

Transmit-side mode bits; currently unused.
spd

The initiat or start-up, speed setting for a line configured for programmable baud rate. For
example, spd=1200. specifies an initial line speed of 1200 baud.
The spd argument sets the receive-side baud rate in the XL driver for the serial line at
start-up time, assuming that the line speed is programmable. The spd argument is valid
only if the type value is TT$DLE, TT$DLF, or TT$DLT. If the line type is TT$DLE or
TT$DLF, the valid speed values are 50, 75, 110, 134, 150, 300, 600, 1200, 1800, 2000, 2400,
3600, 4800, 7200, 9600, or 19,200. (The value 134 indicates 134.5 baud.) If the line type
is TT$DLT, the valid speed values are 300, 600, 1200, 2400, 4800, 9600, 19,200, or 38,400.

C-14

XL Serial Line Driver

The optional ring buffer connection capability is provided primarily to support ring buffer 1/0
via Pascal file variables. It allows the line that will be opened for ring buffer 1/0 to be connected
to named ring buffers by the XL driver at start-up time.
The type symbol TT$DLT indicates a serial line of the type implemented on the MXVll-B
multifunction board and on the FALCON or FALCON-PLUS SBC-11/21 microcomputer. That
type of line supports programmable baud rate in addition to common DLVl 1 capabilities. For
an MXVll-B line configured for programmable baud rate, or for an SBC-11/21 serial line,
specify typ=TT$DLT and give the spd argument. To use a baud rate that has already been
set-by the kernel, as specified in the KXTl 1 configuration macro, for example-omit the spd
argument. For an MXVl 1-B line with hardwired baud rate, indicate the line type as TT$DL.
The XL$xPR definitions specify software priorities associated with the driver process and the
hardware priority for all serial line interrupts.
Note that the interrupt vectors specified and implied in the XLPFX.MAC prefix file must also be
specified in the system configuration file, using the DEVICES macro.

XL Serial Line Driver C-15

Figure C-1:

XL Driver Prefix File (XLPFX.MAC)

MACDF$,IODF$,QUEDF$,DRVDF$,XLISZ$,LINDF$

macdf $
quedf $
drvdf $
xlisz$

GLOBAL

dfalt$

F$XCHK,4000

$XLPRM
This table serves as a configuration data area for the XL driver.
The first word contains the total number of DLV-11 type lines in the
configuration. Subsequent data is set by the LINDF$ macro.
There must be one LINDF$ macro call for each line.
The csr and vector for each lines receive side must be defined;
The transmit side csr and vector addresses are assumed to follow
the receive addresses by 4 bytes each.
The TYP argument specifies a particular type of DL-11. This is the
value returned for a get characteristics. The standard terminal type
codes are shown below:
TT$DL

The device supports the minimum common DLV-11
type functions
TT$DLE
The device supports DLV-11E capabilities
TT$DLF
The device supports DLV-11f capabilities
TT$DLT
The device supports a DLART, ie. compatible with
FALCON, MXV11--B
As an option, ring buffers may be pre-allocated for each line.
In this case, the driver will create named ring buffer structures
of a given size and attributes. The receive and transmit rings
are defined separately. X-OFF/X-ON checking may be enabled on a
receive ring buffer if desired with the RMOD parameter.
Currently, unit numbers for each line correspond to the order in which
the LINDF$ macros are called.
For example:
$XLPRM:: .word

; Define two lines

LINDF$
csr=177560,vec=60,typ=TT$DLF,rnam=<XLIO >,rsiz=10.,
ratt=SA$RIS,rmod=F$XCHK,xnam=<XLOO >,xsiz=80.,xatt=SA$ROS
LINDF$

csr=176500,vec=300

.end

C-16 XL Serial Line Driver

Defines a line on unit 0 with predefined stream-attribute buffers for
both receive and transmit sides and defines another line on unit 1.
Unit O above has X-OFF/X-ON checking enabled. The controller for unit O
is a DL-11F. Note that you must pass a 6 character blank padded string
for the ring buffer structure names as shown above.
The data defined by this macro is used by the XL drivers initialization
routines to connect to interrupt vectors and create ring buff er
structures .
. GLOBL

$XL

XL$PPR
XL$FPR
XL$HPR
XL$IPR

175.
175.*256.
4

250.

pdat$
$XLPRM:: .word
LINDF$
.end

;Haul in the XL driver from the library

Process priority
Fork process priority
hardware priority
process initialization priority

Define only one line

csr=177560,vec=60,rmod=F$XCHK,rnam=<XLIO

>,xnam=<XLOO

C.2 Peripheral Processor XL Driver
The peripheral processor XL device driver supports asynchronous I/ 0 operations on devices
connected to any of the three serial I/O ports on the peripheral processor. This driver is
identical to the PDP-11 XL driver described in Section C.l, except that it includes support for
the multiprotocol chip that resides on the peripheral processor. Thus, the driver can concurrently
service up to three serial ports on the peripheral processor.

Note
The three serial ports on the peripheral processor can be used by the TU58
(DD) driver as well as by the XL driver. See Chapter 4 for a description of the
DD driver interface.
In addition, one of the peripheral processor's serial lines-the multi protocol chip
"A" port-can be used for synchronous serial If O via the XS device driver. See
Chapter 13 for a description of the XS driver interface.
The first serial I/O port on the peripheral processor is a standard DL Asynchronous
Receive/Transmit (DLART) device. The second port provides all the features of a DLVllE, including modem control, but has a different hardware interface. The third port provides all
the features of a standard DLART device but has a different hardware interface.
The driver performs serial input/output operations in either block mode or ring mode. In
block-mode input, a specified number of bytes are transferred directly from the serial line unit
to the requester's buffer space. In block-mode output, a specified number of bytes are transferred
from the requester's data buffer to the serial line unit.

XL Serial Line Driver C-17

In ring-mode input, the driver continuously transmits bytes from the serial line unit to an input
ring buffer specified by the requester. Once initiated by a Connect Receive Ring Buffer request
for a given unit, the input operation continues until the ring buffer is disconnected.
In ring-mode output, the driver continuously transmits bytes from an output ring buffer, as
they become available, to the specified serial line unit. The requester or some other process
must first put characters into the ring buffer and then issue a Connect Transmit Ring Buffer
request, which starts the output transfer. The output operation continues until the ring buffer
is disconnected. Ring mode is intended for unbounded or interactive data paths.
For either type of output request, the driver provides optional XON/XOFF control character
processing. If requested to do so, the driver inhibits the output side of a given serial line unit
when it detects an XOFF character on the input side of the same channel. Output resumes
when an XON is subsequently received.
For the port that supports modem control, the driver allows you to enable data-set interrupts
and to receive data-set status information when such interrupts occur. The driver allows you to
get data-set status information and to set certain XCSR and RCSR bits. By this mechanism, you
can control baud rates, enable interrupts if a modem control signal changes, set modem control
signals, and transmit break signals.
The driver's request queue semaphore name is $XLA. The desired serial line is specified in the
function request by a configuration-determined unit number.
The configuration for all asynchronous serial devices attached to a processor must be specified
in the peripheral processor XL driver prefix file XLPFXK.MAC. (See Section C.2.4.)

C.2. 1 Functions Provided
The functions provided by the peripheral processor XL driver are listed below by symbolic and
decimal function code:

C-18

Code

Function Performed

IF$RDP (0)
IF$RDL (1)

Read Physical
Read Logical (equivalent to Read Physical)

IF$WTP (3)
IF$WTL (4)

Write Physical
Write Logical (equivalent to Write Physical)

IF$SET (6)
IF$GET (7)

Set Status
Get Status

IF$CRR (8)
IF$CXR (9)
IF$DRR (10)
IF$DXR (11)
IF$RSC (12)

Connect Receive Ring Buffer
Connect Transmit Ring Buffer
Disconnect Receive Ring Buffer
Disconnect Transmit Ring Buffer
Report Data-Set Status Change

XL Serial Line Driver

C.2. 1. 1 Read Function
The read function (code IF$RDP or IF$RDL) is performed in block mode. The driver reads a
specified number of characters from the serial line unit into the buffer area identified in field
DP .BUF of the request message.
Read requests to a unit that has been connected to a ring buffer are not supported.

C.2. 1.2 Write Function
The write function (code IF$WTP or IF$WTL) is performed in block mode. The source and
amount of the data to be transferred are specified by the DP.BUF and DP.LEN fields of the
request message.
The function modifier bit FM$XCK (bit 11) in the function code word (offset DP .FUN) is used
to enable or disable automatic XON/XOFF processing. If the bit is set, the driver intercepts any
XOFF character from the input side of the line and disables output for the same channel until
a subsequent XON character is received. Multiple successive XON or XOFF characters have
the same effect as just one such character. If XON/XOFF processing is not selected, the driver
passes all input characters to the requester. The XON/XOFF function modifier bit has no effect
if the feature has been permanently enabled via a Set Status request.
Write requests to a unit that has been connected to a ring buffer are not supported.

C.2.1.3 Connect Receive Ring Buffer Function
The Connect Receive Ring Buffer function (code IF$CRR) connects a user-specified ring buffer
to a serial line unit and initiates input to that ring buffer. Any input occurring on the line is
transferred to the ring buffer identified in request field DP.SGL; field DP.BUF of the request is
ignored. Input into the ring buffer continues until the ring buffer is disconnected.
Note
When a line is connected to a ring buffer, all hardware exceptions are ignored,
including parity exceptions, framing exceptions, and overrun exceptions.

C.2. 1.4 Disconnect Receive Ring Buffer Function
The Disconnect Receive Ring Buffer function (c9de IF$DRP) disconnects a user-specified ring
buffer from a serial line unit. Any subsequent input occurring on the line is ignored.
This request will not disconnect a ring buffer that was attached to a line by the driver prefix
file.

C.2. 1.5 Connect Transmit Ring Buffer Function
The Connect Transmit Ring Buffer function (code IF$CXR) connects a user-specified ring buffer
to a serial line unit and initiates output from that ring buffer. Any data put into the ring buffer
identified in request field DP.SGL is output on the specified line. Field DP.BUF is not used. The
function modifier bit FM$XCK is used to enable or disable automatic XON /XOFF processing as
previously described in the write function section.

XL Serial Line Driver

C-19

C.2. 1.6 Disconnect Transmit Ring Buffer Function
The Disconnect Transmit Ring Buffer function (code IF$DXR) disconnects a user-specified ring
buffer from a serial line unit.

C.2.1.7 Set Status Function
The Set Status function (code IF$SET) sets the specified unit's hardware transmit control register
(XCSR) and/ or the receive control register (RCSR) according to values that are contained in
the request. (For the multiprotocol chip, the hardware is not formatted in that manner, but
the information is unpacked from the 2-word format so that applications written for a DL-type
device will run on a multiprotocol device.) The receiver software status word in the request
allows the permanent enabling of XON/XOFF processing or allows XON/XOFF processing to
be selected via the function modifier bit in the write function.

C.2. 1.8 Get Status Function
The Get Status function (code IF$GET) returns a packet containing the class and type of
hardware, the software status of the receive and transmit circuits, and two words read from the
hardware. (For the multiprotocol chip, the hardware is not formatted in that manner, but the
information is packed into a 2-word format so that applications written for DL-type devices will
run on a multiprotocol device.)

C.2.1.9 Report data-set status change function
The Report Data-Set Status Change function (code IF$RSC) allows the requester to wait for a
change of data-set (modem) status. When a change occurs, the driver returns a standard Get
Status reply, as described in the Get Status sections. When this function is requested, the driver
assumes that modem control has been enabled via a previous Set Status (IF$SET) request. If
modem control was not enabled, the wait process will hang indefinitely.
For this function, you must specify a queue semaphore at offset DP.SGL that is to be signaled
when a status change occurs on the specified unit. For each change request received, a Get
Status reply is returned immediately, and a second reply in the same format is returned when
a change occurs in the state of the modem inputs. Although several requests can be sent at
once, only one reply will be returned per input change.

C.2. 1. 1o Device-Independent Function Modifiers
If modifier FM$BSM (bit 13) of DP.FUN is set, the peripheral processor XL driver signals a
binary or counting semaphore, as described in Chapter 1.

C.2.2 Function-Dependent Request Formats
The function-independent portion of a driver request message is described in Chapter 1.

Note
For the Disconnect Transmit Ring Buffer function (code IF$DXR), field DP.ALN
in the function-independent portion of the reply packet returns the number of
untransmitted bytes that remain in the disconnected ring buffer.
The function-dependent portion of an XL driver request following field DP .SEM is described
below for each type of function.

C-20

XL Serial Line Driver

C.2.2. l Block-Mode Read or Write Functions
The function-dependent portion of a block-mode read or write request is shown below:

DP.DAD -

Portion of
the request
sent by value
Not used

DP.BUF -

Buffer address

DP.PAR -

PAR value

DP.LEN -

Buffer length

Portion of the
request sent
by reference

+-----------------+

ML0-966-87

The unit number in the function-independent portion of the request selects the desired serial
unit; unit numbering starting at 0. The buffer address specifies the destination of the data to be
read or the source of the data to be written. The buffer-length value determines the length, in
bytes, of the data transfer. The PAR value is filled in by the operating system.

C.2.2.2 Connect Receive or Transmit Ring Buffer Functions
The function-dependent portion of a Ring Buffer Connect request for either input or output is
shown below:

DP.RBF -

Ring buff er
Structure

Portion of
the request
sent by value

Not used

+-----------------+

ML0-967-87

The unit number in the function-independent portion of the request selects the desired serial
unit; unit numbering starts at 0. Field DP.RBF specifies, by structure ID, the destination ring
buffer for an input operation or the source buffer for an output operation. On input, individual
characters are put into the ring buffer as they are received; on output, individual characters are

XL Serial Line Driver C-21

transmitted from the ring buffer as they become available by action of the user process. In
either case, the length of the transfer is unlimited.

C.2.2.3 Disconnect Receive or Transmit Ring Buffer Functions
The function-dependent portion of a Ring Buffer Disconnect request for either input or output
is shown below:
·I

-----------------,
Ring buffer
I
--.
Structure
I

DP.REF -

--,

Portion of
the request
sent by value

I
I
I

-----------------,

I
I
I
I
I
I

I
I

,-I
,--

--,
--,
I
--,

Not used

I
I
I

I
I

.--

--1

I
I

+-----------------+
ML0-968-87

The unit number in the function-independent portion of the request selects the serial unit from
which the ring buffer is to be disconnected. Field DP.RBF specifies, by structure ID, the ring
buffer that was previously connected to the unit in question. All input to or output from the
ring buffer ceases when the request is acted on by the driver.

C.2.2.4 Set Status Function
The function-dependent portion of a Set Status request (code IF$SET) is shown below:

I
I
I

DP.FDD -

-----------------,
Not used

DP.RPS -

RCSR

DP.XPS -

XCSR

DP.RSS -

Input status

Portion of
the request
sent by value

Not used

+-----------------+
ML0-969-87

C-22

XL Serial Line Driver

The previous request packet fields have the following significance:

Field

Significance

DP.RPS

Status control bits to be set in the multiprotocol receiver control hardware
(equivalent to DL-device receiver CSR); not used for the DLART device

DP.XPS

Status control bits to be set in the DLART transmitter CSR or in the multiprotocol
hardware equivalent; the bit settings are hardware-dependent

DP.RSS

Receiver software status bit settings

The format of the receiver status-setting word (offset DP .RPS) is as follows:
15

+-------------------------------+
I I I I l I l iti I ieiti iritl I
lxlxlxlxlxlxlxlmlxlxicisixlxlrlxi

+-------------------------------+
ML0-970-R7

Proceeding from right to left in the format above:
•

The tr bit (1), if set, indicates data terminal ready.

•

The rx bit (2), if set, indicates request to send.

•

The ts bit (4), if set, indicates terminal in service.

•

The ec bit (5), if set, enables modem control (modem control lines are active).

•

The tm bit (8), if set, indicates test mode.

The format of the transmitter status-setting word (offset DP.XPS) for the DLART device is as
follows:
15

+-------------------------------+
I I I l I l l I l I lblblblmllisi
lxlxlxixlxlxixixlxlxlblblbitlribl

+-------------------------------+
ML0-971-87

Proceeding from right to left in the format above:
•

The sb bit (0), if set, requests a BREAK to be transmitted on the output line.

•

The lr bit (1), if set, allows a new baud rate to be loaded (bit PBRE on hardware).

•

The mt bit (2), if set, enables self-test; whatever is written to the transmit data register is
looped back and received by the receive data register.

•

The bb bits (3 to 5) indicate the desired baud rate for the unit (bits PBRO, PBRl, and PBR2
on hardware).

XL Serial Line Driver C-23

The format of the transmitter status-setting word (offset DP.XPS) for a multiprotocol device is
as follows:
15

+-------------------------------+
lblblblblblblblblblb~blblblblblsl
lblblblblblblblblblblblblblblblbl

+-------------------------------+
ML0-972-87
Proceeding from right to left in the format above:
•

The sb bit (0), if set, requests a BREAK to be transmitted on the output line; the bit must
be cleared when the baud rate is set.

•

The bb bits (1 to 15) indicate the desired baud rate; the valid octal values are:
Baud Rate

Value

307.2Kb
153.6Kb
76.8Kb,
38.4Kb
19.2Kb
9600
4800
2400
1200
600
300
150
110

2
4
10
20
40
100
200
400
1000
2000
4000
10000
12722

The format of the software status-setting word (offset DP.RSS) is as follows:
15

+-------------------------------+
I I I I I xi I I I I I I I I I I I
lxlxlxlxlclxlxlxlxlxlxlxlxlxlxlxl

+-------------------------------+
ML0-973-87
The xc bit (11), if set, enables XON/XOFF processing regardless of the state of the XON/XOFF
function modifier bit within the block write or Connect Transmit Ring Buffer commands. (See
Section C.2.2.1.)

C-24 XL Serial Line Driver

C.2.2.5 Get Status Function
The function-dependent portion of a reply to a Get Status request (function code IF$GET) is
shown below:

DP. RPS -

--------+-------Type : Class
--------+-------RCSR

DP.XPS -

XCSR

DP.RSS -

Input status

DP. CLS -

DP.XSS -

All the
request is
returned by value

Output status

+-----------------+

ML0-974-87

In the information above:
•

Class is DC$TER, indicating a serial line.

•

Type indicates the specific type of serial line device, as follows:
TT$DLT

Serial line with programmable baud rate, exception indicator flags, and a
self-test mode-the DLART port on the KXTl 1-CA.

TT$DM

First or second port on the multiprotocol chip on the KXTl l-CA when
used in the asynchronous data-leads-only mode. The port then supplies the
functionality of the TT$DLT type device.

TT$DMM

Multiprotocol line operating in asynchronous serial mode.
Contains
full modem control, mandatory programmable baud rate, mandatory
programmable vector address, and exception indicator flags. Only the
first port on the multiprotocol device can be this device type and then only
when this driver or no driver is in control of the second multiprotocol port.

The other reply packet fields shown above have the following significance:

Field

Significance

DP.RPS

Status control bits returned from the multiprotocol receive control hardware
(equivalent to DL-device receiver CSR) if modem control is in use; not used for
the DLART device

DP.XPS

Status control bits returned from the DLART transmitter CSR or from the
multiprotocol hardware equivalent; the bit settings are hardware-dependent

DP.RSS

Receiver software status bit settings

DP.XSS

Transmitter software status bit settings

XL Serial Line Driver C-25

The format of the receiver status word (offset DP.RPS) is as follows:
15

+-------------------------------+
I lilclrldl I ltl I leltl lrltl I
lxlclslrlmlxlxlmlxlxlclslxlxlrlxl

+-------------------------------+
ML0-975-R7
Proceeding from right to left in the format above:
•

The tr bit (1), if set, indicates data terminal ready.

•

The rx bit (2), if set, indicates request to send.

•

The ts bit (4), if set, indicates terminal in service.

•

The ec bit (5), if set, indicates that modem control is enabled on the line; modem control
lines are active.

•

The tm bit (8), if set, indicates test mode.

•

The dm bit (11), if set, indicates data mode (TT$DMM type only).

•

The rr bit (12), if set, indicates receiver ready.

•

The cs bit (13), if set; indicates clear to send.

•

The ic bit (14), if set, indicates incoming call (TT$DMM type only).

The format of the transmitter status word (offset DP.XPS) for the DLART device is as follows:
15

+-------------------------------+
I : : : I I I I : : lblblblmlllsl
lxlxlxlxlxlxlxlxlxlxlblblbltlrlbl

+-------------------------------+
ML0-976-87
Proceeding from right to left in the format above:

C-26

•

The sb bit (0), if set, indicates transmitting break.

•

The Ir bit (1), if set, indicates programmable baud rate enabled (bit PBRE on hardware).

•

The mt bit (2), if set, indicates that self-test mode is active; whatever is written to the
transmit data register is looped back and received by the receive data register.

•

The bb bits (3 to 5) indicate the baud rate for the unit (bits PBRO, PBRl, and PBR2 on
hardware).

XL Serial Line Driver

The format of the transmitter status word (offset DP .XPS) for a multiprotocol device is as
follows:
15

+-------------------------------+
lblblblblblblblblblblblb/blblblsl
/b/b/b/blblblblblblblblblblblblbl

+-------------------------------+
ML0-977-87

Proceeding from right to left in the format above:
•

The sb bit (0), if set, indicates transmitting BREAK.

•

The bb bits (1 to 15) indicate the baud rate; the octal values are:
Baud Rate

Value

307.2Kb
153.6Kb
76.8Kb
38.4Kb
19.2Kb
9600
4800
2400
1200
600
300
150
110

2
4
10
20
40
100
200
400
1000
2000
4000
10000
12722

The formats of the receiver and transmitter software status words (offsets DP.RSS and DP.XSS)
are identical, as follows:
15

+-------------------------------+
: : : cl ri x: : i i : : : : : : : :
ixixiflglcixixixixixlxixixixixixi

+-------------------------------+
ML0-978-87
Proceeding from right to left in the format above:
•

The xc bit (11), if set, indicates XON/XOFF processing for the input side. No meaning is
assigned to the output side.

•

The rg bit (12), if set, indicates that the port is connected to a ring buffer.

•

The cf bit (13), if set, indicates that the port was connected to a ring buffer during
configuration.

XL Serial Line Driver C-27

C.2.2.6 Report Data-Set Status Change Function
The function-dependent portion of a Report Data-Set Status Change request (function code
IF$RSC) is shown below:

DP.SGL -

Semaphore
Structure

Portion of
the request
sent by value

Not used

+-----------------+

ML0-979-87

The unit number in the function-independent portion of the request selects the desired serial
line. Field DP.SGL specifies, by structure ID, the queue semaphore to be signaled when a status
change occurs on the specified unit.
The function-dependent portion of a reply to the Report Data-Set Status Change request is the
same as a reply to the Get Status function.

C.2.3 Status Codes
The XL driver returns the following completion-status codes in field DP.STS of the reply
message:
Code

Meaning

ES$NOR

Normal success

ES$IFN

Invalid function code

ES$NXU

Nonexistent unit

ES$0VR

Overrun exception on received data

ES$PAR

Parity exception on received data

C.2.4 KXTl 1-CA XL Prefix File
The XL prefix module to configure the XL driver for a KXTl 1-CA, XLPFXK.MAC, is similar to the
XL prefix files XLPFX.MAC, XLPFXD.MAC, and XLPFXF.MAC. (See Section C.1.4.) However,
because the configuration of the board is fixed, fewer modifications to the file are required.
There are always three serial lines: the console line at vector 60, multiprotocol channel A, and
multiprotocol channel B. You should normally use three LINDF$ macros to configure the XL
driver, as illustrated in Figure C-2 and described below. However, if you connect a TU58 to

C-28 XL Serial Line Driver

the KXTl 1-CA, the TU58 driver will use one of the serial lines. If this is the case, be sure that
XLPFXK.MAC does not also define the same line for the XL driver. If you use the XS driver,
the XS driver will always use multiprotocol channel A; in that case, be sure to omit channel A
from the XL driver configuration.
typ

The following typ values are permitted in the LINDF$ macro for the XL driver with the
KXTll-CA:
•

TT$DLT for the console channel at vector 60

•

TT$DM for KXTl 1-CA multiprotocol channel data only

•

TT$DMM for KXTl 1-CA multiprotocol channel with full modem control. Multiprotocol
channel A is the only channel that can be of this type, and then only when the XL
driver (or no driver) is in control of multi protocol channel B.

vec

The vectors for the asynchronous lines on the KXTl 1-CA are:
Line

Vector

Console

Channel A

140

Channel B

160

csr

The control status registers for the three lines are:
Line

CSR

Console

177560

Channel A

175700

Channel B

175710

The other LINDF$ arguments correspond to the LINDF$ arguments in XLPFX.MAC, described
in Section C.1.4.

XL Serial Line Driver

C-29

Figure C-2:
.title

KXT 11-CA XL Driver Prefix File (XLPFXK.MAC)
XLPFXK

KXT11-CA XL DEVICE DRIVER PREFIX MODULE

MACDF$,IODF$,QUEDF$,DRVDF$,XLISZ$,LINDF$

macdf $
quedf $
drvdf $
xlisz$

GLOBAL

dfalt$

F$XCHK,4000

This module contains an example of using the configuration macros
to configure asynchronous serial lines on the KXT11-CA.
$XLPRM
This table serves as a configuration data area for the XL driver.
The first word contains the total number of asyncronous serial lines
in the configuration. Subsequent data is set by the LINDF$ macro.
There must be one LINDF$ macro call for each line.
The csr and vector for each line's ·receive side must be defined;
The transmit side csr and vector addresses are assumed to follow
the receive addresses by 4 bytes each.
The TYP argument specifies a particular type of Serial device. This is
the value returned for a get characteristics. The standard terminal type
codes are shown below:
TT$DL
TT$DLE
TT$DLF
TT$DLT
TT$DM
TT$DMM

The device supports the minimum common DLV-11
type functions
The device supports DLV-11E capabilities
The device supports DLV-11f capabilities
The device supports a DLART, ie. compatible with
FALCON, MXV11--B, or the console port on the KXT11-CA.
The data leads only multiprotocol channel on KXT11-CA
The multiprotocol channel with modem control on the
KXT11-CA.

As an option, ring buffers may be pre-allocated for each line.
In this case, the driver will create named ring buffer structures
of a given size and attributes. The receive and transmit rings
are defined separately. X-OFF/X-ON checking may be enabled on a receive
ring buffer if desired with the RMOD parameter.
Currently, unit numbers for each line correspond to the order in which
the LINDF$ macros are called.

C-30

XL Serial Line Driver

For example:
$XLPRM:: .word

; Define two lines

LINDF$
csr=177560,vec=60,typ=TT$DLT,rnam=<XLIO >,rsiz=10.,
ratt=SA$RIS,rmod=F$XCHK,xnam=<XLOO>,xsiz=80. ,xatt=SA$ROS,spd=9600
LINDF$

typ=TT$DM,csr=175710,vec=160,spd=9600

.end
Defines a line on unit 0 with predefined stream-attribute buffers for
both receive and transmit sides and defines another line on unit 1.
Unit 0 above has X-OFF/X-ON checking enabled. The controller for unit 0
is a DLART. Note that you must pass a 6 character blank padded string
for the ring buffer structure names as shown above.
The data defined by this macro is used by the XL drivers initialization
routines to connect to interrupt vectors and create ring buffer structures .

. GLOBL
XL$PPR
XL$HPR
XL$IPR

$XL
175.
250.

Process priority
hardware priority for port on KXT11-CA
Process initialization priority

Define two lines

pdat$
$XLPRM : : . word

Multiprotocol channel B with ring buffers and data leads only
LINDF$

typ=TT$DM,csr=175710,vec=160,rmod=F$XCHK,rnam=<XLIO>,rsiz=134.,
xnam=<XLOO >,xsiz=80.,spd=9600

Multiprotocol channel A with ring buffers and modem control
LINDF$

typ=TT$DMM,csr=175700,vec=140,rmod=F$XCHK,rnam=<XLI1>,rsiz=134.,
xnam=<XL01 >,xsiz=80. ,spd=9600
.end

XL Serial Line Driver C-31

Appendix D
Sample MACR0-1 l Device Driver
Source code for the RX02 device driver, DYDRV.MAC, is provided in this appendix as a sample
device driver written in MACR0-11. The associated prefix file, DYPFX.MAC, is listed in Chapter
4 and is available on the distribution kit.
The DY driver's impure-area definition macro, DYISZ$, resides in the COMU and COMM macro
libraries and is invoked in the driver source code. See Section 14.3 for a listing of the DYISZ$
macro.
In this appendix, long macro invocations (DFSPC$ and CRPC$) are continued on a second line.
When writing source code in MACR0-11, however, the entire invocation must be on one line.

Note
For an example of a driver coded in Pascal, see the DRVl 1 (YA) driver source
files (YADRV.P AS and YAPFX.P AS) included on the distribution kit. The YA
driver is described in Chapter 6 .

. nlist
.enabl
.list
.title
.ident

Sample MACR0-11 Device Driver D-1

THIS SOFTWARE IS FURNISHED UNDER A LICENSE AND MAY BE USED AND COPIED
ONLY IN ACCORDANCE WITH THE TERMS OF SUCH LICENSE AND WITH THE
INCLUSION OF THE ABOVE COPYRIGHT NOTICE. THIS SOFTWARE OR ANY OTHER
COPIES THEREOF MAY NOT BE PROVIDED OR OTHERWISE MADE AVAILABLE TO ANY
OTHER PERSON. NO TITLE TO AND OWNERSHIP OF THE SOFTWARE IS HEREBY
TRANSFERRED.
THE INFORMATION IN THIS SOFTWARE IS SUBJECT TO CHANGE WITHOUT NOTICE
AND SHOULD NOT BE CONSTRUED AS A COMMITMENT BY DIGITAL EQUIPMENT
CORPORATION.
DIGITAL ASSUMES NO RESPONSIBILITY FOR THE USE OR RELIABILITY
SOFTWARE ON EQUIPMENT THAT IS NOT SUPPLIED BY DIGITAL.
.SBTTL

ITS

Edit History

Module name: DYDRV.MAC
System: MicroPower/Pascal
Author: ERS
ERS
ERS
ERS

Creation date: 21-JUL-82
15-NOV-82 fix IS$0FL to IS$0VF
20-APR-83 fix recursive errors
24-Feb-84 Update for V2.0

Functional Description:
This module provides device driver services for the RX02 flexible
diskette. It controls any number of RX02 drives. The driver can
read, write, and format single or double density diskettes .

. sbttl

Declarations

; System macro requirements
.enabl

GBL

.mcall

macdf$, iodf$, quedf$, drvdf$, dcdf$, ccdf$, dyisz$

macdf $
iodf $
quedf $
drvdf $
dcdf $
ccdf$
dyisz$
.mcall
.mcall

D-2

cint$s, crpc$p, crst$s, dapk$s, dint$s, dlpc$, dlst$s
fork$, sgnl$s, sglq$s, waiq$s, wait$s, waqc$s, xtad$

Sample MACR0-11 Device Driver

; Local macro definitions:

External symbols which are necessary to assemble this module but
which may have default definitions:

dfalt$

DY$RTY,10.

Retry count

; External symbols defined in the driver prefix module.
.globl
.globl
.globl

DY$IPR
DY$PPR
DY$HPR

DY initialization priority
DY process priority
RX02 hardware priority

Data and symbols owned by this module are defined here and storage is
allocated in the appropriate data section.

; Local symbol definitions:
;+

Define offsets within and size of the impure area required by the DY
driver for each controller process.

Sample MACR0-11 Device Driver D-3

psect$

.TEMP. ,<RO,D,LCL,ABS,OVR>

.temp.:
REQSEM:
UNTMAP:

.blkb
.blkb

SD.SIZ

ADTYPE:

.blkb

SIZE:
FORMAT:
RTYCNT:
SAVDEN:
DENPTR:
SAVR3:
INTRTN:
PACKET:
ERROR:
STATUS:
SECSIZ:
LSN:
SECTOR:
TRACK:
WRDCNT:
COUNT:
TEMP:
BUFFER:
RX2CSR:
RX2DB:
VECTOR:
ISRENB:
SAVSP:
$DYDNE:
ISRIMP:
CNTSEM:

.even
.blkb
.blkb
.blkb
.even
.blkw
.blkw
.blkw
.blkw
.blkw
.blkw
.blkw
.blkw
.blkw
.blkw
.blkw
.blkw
.blkw
.blkw
.blkw
.blkw
.blkw
.blkw
.blkw

Request semaphore SDB
Unit allocation bit map. Only 2 bits
required since only 2 units per controller
Physical or logical
0 physical,1 logical
flag for get characteristics
flag for format command
Total number of retrys (0 if RTYINH)

DY$MXU

saved density for each drive
-> savden[unit]
saved R3 for returns after interrupt
interrupt return address
Pointer to request packet
Error code
Status code
sector size in words
logical sector number (logical accessing)
Sector (only if physical accessing)
Track
# of words this request
# of words this transfer
Temporary word for dyerr
Buff er address of user buff er
Address of RX02 CSR
Address of RX02 Data Buff er
Interrupt vector
ISR has been enabled ie. main process
is or will shortly block on $DYDNE semaphore
saved stack pointer
Address of control SDB
ISR impure area
Control semaphore sdb

.blkw
.blkw
.blkb
.even

SD.SIZ

- . temp.

.. ISZ

Size of impure area .

Validate parameters specified in the dyisz$ macro
.if LT
<DY$ISZ - .. ISZ>
.error
DY$ISZ
Impure area too small as specified in DYISZ$
. error
.. ISZ
Edit DYISZ$ in DRVDEF, replacing value for DY$ISZ
.endc
.if GT

<DY$MXU - 2>
.error
DY$MXU

; RX02 supports a maximum of 2 drives per controller

.endc
.if LT

<DY$SSZ - <$MINST+110>>
.error
DY$SSZ
; Stack size specified in DYISZ$ is too small

.endc
.if GT

DY$USZ
.error

DY$USZ

Value specified in DYISZ$ is unnecessary

.endc
RX02 Device Register D~finitions:
Control and Status Register Bit Definitions

D-4

Sample MACR0-11 Device Driver

CSGO

CS FUN
CSUNIT
CSUN1
CSDONE
CS INT
CS TRAN

16
20
20
40
100
200

CSDN
CSHEAD
CSRX02
CSXM
CS IN IT
CS ERR

400
1000
4000
30000
40000
100000

Initiate function
function bits
Unit bit
Unit one
Done bit
Interupt enable
Transfer request (implies RX02 is
ready for rest of command string.
Double density request
Select second head
Controller is RX02
XM bits
RX11 initialize
Error

; CSR Function Codes in Bits 1-3
CSFBUF
CSEBUF
CSWRT
CSRD
CSFMT
CSRDST
CSWRTD
CSMAIN

0*2
1*2
2*2
3*2
4*2
5*2
6*2
= 7*2

;O - Fill silo (pre-write)
;1 - Empty silo (post-read)
;2 - Write sector
;3 - Read sector
;4 - Format
;5 - Read status
;6 - Write sector with deleted data
;7 - Maintenance

as sum$
as sum$
as sum$

CSRD&2
NE 0
CSWRT&2 EQ 0
CSWRTD&2 EQ 0

2 bit must be on in read
2 bit must be off in write
2 bit must be off in write

; Error and Status Register Bit Definitions
ESCRC
ESSID1
ESID
ES ACLO
ESDNER
ESDDEN
ESDDAT
ESDRDY
ESUNIT
ES HEAD
ESWDCT
ESNXM

CRC error
Side 1 ready
Initialize done
RX power failure
Density error
Drive density
Deleted data mark
Drive ready
Unit selected
Head selected
Word count overflow during fill or empty
Non-existent memory

1
2
4

10
20
40
100
200
400
1000
2000
4000

; Device parameters
LB SIZE
NUMSEC
NUMCYL
NUMTRK
SECTSZ

988.

( 26.
77.
1

256 .
. sbttl

RX02 logical block size
Number of sectors
Number of cylinders (tracks in hdw parlance)
Number of tracks (surf aces)
Number of bytes/sector double density
Process definition

dfspc$
pid=$DYADR,pri=DY$IPR,cxo=O,typ=PT.DRV,grp=1,ter=DYSTP,cxl=O,
sti=$DYAG2,stl=$DYAG1,sth=$DYAG2,start=DYINIT,ini=O
pdat$

Sample MACR0-11 Device Driver D-5

$DYPCD::
crpc$p
pdb=PDB,pri=DY$PPR,cxo=O,grp=1,ter=DYSTP,cxl=O,sti=O,stl=O,sth=O,
start=DYSTRT,ini=O
impur$
PDB:

.blkb

SD.SIZ

PDB for creating driver processes

pdat$
Action Routine Dispatch Table:
PLTABL:

.byte
.byte
.byte
.byte
.byte
.byte
.byte
.byte
.even

0
1
200
0
1
200
377
377

Read physical
Read logical
Reserved
Write physical
Write logical
Reserved
Get characteristics
Set characteristics

; Device Characteristics Table:
DTABLE:

.byte
.byte
.word
.byte
.byte
.word

DTBSIZ

DC$DSK
DK$DY2
LBSIZE,O
NUMSEC
NUMTRK
NUMCYL
- DTABLE

Class is disk
Type is RX02
Number of logical blocks
Number of sectors
Number of tracks
Number of cylinders
Size of table

; Table of error returns corresponding to bits in the error and status register
ERLIST:
ES$CTL
ES$PAR
0
0

ES$PWR
ES$IVM
0
0

ES$UNS
0
0

ES$0VF
ES$NXM

Return controller error if no error bits set
Parity error for CRC error
Nothing for Side 1 ready
Nothing for initialize done
Power fail for RX power failure
Invalid mode for density error
Nothing for drive density
Nothing for deleted data mark
Unsafe for drive not ready
Nothing for unit selected
Nothing for reserved bit
Word count overflow during fill or empty
Non-existent memory

pure$

D-6

Sample MACR0-11 Device Driver

.sbttl

DYINIT

- Power Up Initialization Process

DYINIT - This process creates an instance of the device
driver process for each controller (after the first, this
process becomes the first controller process) present on
the particular configuration. It creates a request semaphore
(named successively $DYA, $DYB, ... ) for each controller
specified by the $DYCFG table created by the configuration
procedure.
Control passes to this process on power up. It runs at highest
priority (255.) and then lowers its priority to become the first
controller process.

DYINIT:
CALL
.sbttl

MOV
#$DYPUR,R5
$DDINI
DYSTRT

-> Configuration data for RX02
Common device driver initialization
routine

- Request Process !nit Procedure

DYSTRT - This is the entry point for each process serving a device
controller. A pointer to the impure area of the controller
is passed on the stack.
(SP)

DYSTRT:

Pointer to impure area

MOV
MOV
BIT

(SP)+,R5
(SP)+,R4
(SP)+,RO

-> impure area
-> initialization data
Throw away the controller id

Create an unnamed binary semaphore to serve as an interrupt semaphore
connecting the ISR to the I/O request service process.
MOV
ADD
CLR
MOV

R5,R2
#CNTSEM,R2
SD.NAM(R2)
R2,$DYDNE(R5)

Copy impure pointer
-> Interrupt semaphore
Clear name field in SOB
Save pointer to SOB

assum$ ST.BSM eq 0
#ST.BSM
crst$s sdb=R2, styp=#O, satr=#O, value=#O
BCS
20$
If CS, create semaphore failed
MOV
MOV
MOV
ADD
MOV

CC.PCS(R4) ,R1
(R1),RX2CSR(R5)
(R1)+,RX2DB(R5)
#2,RX2DB(R5)
(R1) ,VECTOR(R5)

-> CSR/VECTOR LIST
-> CSR
Compute -> Data buff er register
-> VECTOR

Connect the interrupt vector to the !SR.
cint$s vec=(R1),ps=#DY$HPR*40,val=#O,isr=#$DYINT,imp=R5,pic=#O
BCC
30$
; Br if no error

Sample MACR0-11 Device Driver D-7

20$:

CALL

$DDEXC

report kernel error (code in RO)
no return

30$:

MDV
push$
push$
ADD
push$
ADD
CALL
TST
BNE
MDV
BR

SP,SAVSP(R5)
#DY$MXU
R4
#CC. USP, (SP)
R5
#UNTMAP, (SP)
$UNTMP
(SP)+
DYREQ
#ES$ICD,RO
20$

save the stack pointer
Maximum number of units on RX02
Compute address of unit list

.sbttl

DYREQ

Compute address of unit bitmap
Set bitmap for supported drives
Any errors?
Br.if not
Invalid conf ig data
report error

- Request Process Queue Server

;+
This is the I/D request service process. This process
starts a request when the controller is idle. The !SR
will complete the request (unless a verification error)
and all other pending requests. When the !SR is finished
all pending requests, it will signal the $DYDNE semaphore,
unblocking this process.
R5 ->
R4

Impure area (at request semaphore SOB)
Modified

.enabl LSB
DYREQ:

1$:

2$:

3$:

MDV
CLR
waiq$s
BCC
CALL

SAVSP(R5) ,SP
ISRENB(R5)
sdb=R5,qelm=R4
2$
$DDEXC

ass um$
MDV
CALL
BCS

REQSEM EQ 0
R4,PACKET(R5)
DDREQ
DYREQ

wait$s

sdb=$DYDNE(R5)

BCS

BR
DYREQ
.dsabl LSB
.sbttl

D-8

DDREQ

reset the stack in case of error
isr is inactive
Wait for a request packet
Br if no error
report kernel error (code in RO)
Does not return
Save -> packet in impure area
Verify & start request
br if verification error. Don't
wait on the binary semaphore
if the interrupt routine will
not be active
wait for controller to complete
all requests
br on errors
wait for another request

- Verify and begin a request

Sample MACR0-11 Device Driver

Verify and setup to start a request. This routine has two
returns: A return with the carry clear indicates the request
passed the verification tests and the !SR will become active.
With the carry set on return, the request did not pass the
verification tests and the !SR will not be started.
Inputs:
R5 -> impure area
R4 -> request packet
R3,R2,R1,RO modified
CALL DOREQ
.enabl LSB
DOREQ:
; Set up retry count, if not inhibited by function modifier
MOVB
BIT
BEQ
CLRB

#DY$RTY,RTYCNT(R5)
#FM$INH,DP.FUN(R4)
10$
RTYCNT(R5)

Set up retry count.
See if retry is inhibited.
If EQ, no, retry if errors
Else inhibit retry on error

10$:
Validate unit number

(ALL RX02'S HAVE MAX. OF TWO DRIVES)

CLR
MDV
push$
ADD
CLR
MOVB
BNE
CLR

SIZE(R5)
#CSUN1,R3
R5
#UNTMAP, (SP)
-(SP)
DP.UNI(R4),(SP)
20$
R3

Clear to convert byte to word
Specified unit number
Br if not unit zero
It is unit zero

20$:

push$
CALL
TST
BNE
MDV
BR

#DY$MXU
$UNTVA
(SP)+
30$
#ES$NXU,R2
90$

Maximum number of units
Validate unit number
Unit number valid?
Br if so
Else non-existent unit error
Return message/process next request

30$:

CLR
CLR
MDV
ADD
CLR
MOVB
ASL
ADD
MOV
BIS
MDV
TST
BEQ
ASL
MDV

ERROR(R5)
STATUS(R5)
R5,R2
#SAVDEN,R2
-(SP)
DP.UNI(R4),(SP)
(SP)
(SP)+,R2
R2,DENPTR(R5)
(R2) ,R3
#64. ,R1
ODENPTR(R5)
40$
R1
R1,SECSIZ(R5)

Clear error flags
and status flags
Compute -> density table

40$:

clear flags
Assume unit one is wanted.
Compute -> unit bit map

Change byte to word
Get unit number
get word off set
R2 -> density
save -> in impure area
assume previous density
sector size single density words
Is it single density?
br if so
make double density
save sector size

Sample MACR0-11 Device Driver

D-9

Check function codes:
0,1=READ 3,4=WRITE 2,5=ILLEGAL 6=SET, 7=GET, 10+=ILLEGAL

50$:

BIS
MOV
BIC
CMP
BLE
ADD
CMP
BHI
MOVB
BPL
ASLB
BEQ
asswn$
asswn$
ASR
BCC
INCB
BR

60$:
70$:
80$:
90$:

100$:

#CSGO!CSRD!CSINT,R3
; asswne read command
DP.FUN(R4),R1
; R1 = function code and modifiers
#C77,R1
; Clear all but function bits
R1 ,#IF$RDL
write command?
50$
no
#CSWRT-CSRD,R3
Make the read comman~ a write
R1 ,#IF$GET
Check for legal range of code
80$
Br if illegal function
PLTABLE(R1),RO
Read or write function?
Br if so
100$
Get or set characteristics?
RO
Br if not, a reserved code which
80$
we treat as illegal
<IF$GET&1> EQ 1
<IF$SET&1> EQ 0
R1
Get or set characteristics
Br if set, which we don't support
80$
SIZE(R5)
flag get characteristics request
start request
DYTRAN

MOV
BR
MOV
BR
MOV
MOV
CALL
SEC
RETURN

#ES$IVP,R2
90$
#ES$IDA,R2
90$
#ES$IFN,R2
R2,STATUS(R5)
REPLY

CMPB
BNE
BIT
BEQ

R1,#IF$WTP
120$
#FM$WFM,DP.FUN(R4)
120$

invalid parameter
invalid device address
Return illegal function code
set up error code
signal user
special return
Process next request
Physical write?
Br if not
Format disk?
Br if not

Format the diskette

110$:

CMP

#"FO,DP.DAD(R4)

BNE

80$

BIC
BIS
BIS

#CSFUN,R3
#CSFMT!CSINT!CSGO,R3
#CSDN,R3

A safety check to verify that the
user really wants to format the disk
Br if he really didn't want to do it
Return illegal function code
clear function bits
Set up format command
asswne double density

BIT

#FM$WSD,DP.FUN(R4)

Single density?

BEQ
BIC
INCB
BR

110$
#CSDN,R3
FORMAT(R5)
DYTRAN

No
yes, clear density bit
set format flag
let's do it ...

Set up transfer ...
Compute extended address bits

D-10 Sample MACR0-11 Device Driver

120$:

130$:
140$:

150$:

MDV
CLC
RDR
BCS
MDV
xtad$

DP.LEN(R4) ,RO

BIS
MDVB
BEQ
MDV
CMP
BGE
ASL
TST
BNE
ASL
MDV
BR

R2,R3
PLTABLE(R1),ADTYPE(R5)
140$
DP.DAD(R4) ,R2
R2,#LBSIZE
70$
R2
<ODENPTR(R5)
130$
R2
R2,LSN(R5)
150$

MDV
CMP
BGE
MDV
MDV
CMP
BGT
MDV

DP.CYL(R4),R2
R2,#NUMCYL
70$
R2,TRACK(R5)
DP.SEC(R4),R2
R2,#NUMSEC
70$
R2,SECTDR(R5)

physical access .. get track

.BR

DYTRAN

start transfer

.dsabl

LSB

.sbttl

DYTRAN

get number of bytes
set up for rotate
RO
convert to words
60$
br if odd byte count
RO,WRDCNT(R5)
; save it
vadd=DP.BUF(R4),par=DP.PAR(R4),pos=12.,ext=R2,addr=BUFFER(R5)
set xm bits
See if this is physical or logical.
br if physical
get logical block number
too big?
sector = block * 2 (double den)
are we double density?
br if yes
sector = block * 4 single density
save logical sector number
continue
check argument

check sectors
save sector

- Start transfer or retry

Inputs:
R5 -> impure area
R3
f untion
R4,R2,R1,RO modified
BR

DYTRAN

.enabl LSB
DYTRAN:
TSTB
BEQ
MDV
CALL
BR

FDRMAT(R5)
1$
#111,R2
INWAIT
DYDDNE

format command?
nope
Magic number for format command
Do it
all finished ...

1$:
TSTB
SIZE(R5)
Get characteristics?
BEQ
30$
no
Copy device characteristics to the queue element
MDV
#DTABLE,RO
-> Device characteristics table
MDV
PACKET(R5),R1
-> Queue element
ADD
#DP.DAD,R1
-> Device characteristics block
#DTBSIZ,R2
MDV
= Number of bytes in table

Sample MACR0-11 Device Driver

D-11

20$:

MOVB
SOB
BIC
BIS
CLR
CALL
MDV
BIT
BNE
ASR

Copy data
Loop until done
clear function bits
set up read status
no second command
wait for interrupt
get # of blocks (dual density)
dual density?
br if yes
single density

10$:

MDV
MDV
BIT
BNE
MDV
BR

R1 -> Packet
set size to correct value
drive ready?
br if so
else drive unsafe
Return

BIT
BNE
CALL
CALL
BIT
BEQ
CALL
MDV
ASL
ADD
BCC
ADD

#1*2,R3
40$
DOSI LO
DOXFER
#1*2,R3
50$
DOSILO
COUNT(R5),R2
R2
R2,BUFFER(R5)
60$
#10000,R3

write function?
no read
Fill silo for write
do transfer to/from disk
read function?
No write
For read empty silo
size of transfer (words)
convert to bytes
update buff er address
Br if carry clear
overflow into xm bits

TSTB
BNE
INC
CMP
BGE
INC
BR

ADTYPE(R5)
70$
SECTOR(R5)
#NUMSEC,SECTOR(R5)
80$
TRACK(R5)
80$

physical accessing?
br if logic~l
bump sector number
Past end of track
nope
increment track number

INC

LSN(R5)
COUNT(R5) ,WRDCNT(R5)
30$
#1*2,R3
DYDO NE
ADTYPE(R5)
DYDO NE

update logical sector number
update word count
br if more to do
read request?
yes, we are done
Physical transfer?
yes, no need to zero fill

21$:
30$:
40$:

50$:

update values
60$:

70$:
80$:

SUB

BHI
BIT
BNE
TSTB
BEQ

zero fill partial logical block
MDV
MDV
ADD

#1,WRDCNT(R5)
R5,R1
#STATUS,R1

set up 1 word transfer
Get -> to zero word

NOTE: xtad$ macro uses RO
xtad$

D-12

Sample MACR0-11 Device Driver

BIC
BIS
MOV
BIT
BEQ
ASR
BIT
BNE
.BR

90$:

#CSXM,R3
R4,R3
#3,R1
#CSDN,R3
90$
R1
R1,LSN(RS)
30$
DYDO NE

clear xm bits
set new xm bits
test for block done
double density?
no block # multiple of 4
Block # even
are we through?
nope ... continue

.dsabl LSB
.sbttl

DYDONE

- Finish processing a request

RS -> impure area
R4
modified
BR

DYDO NE

.enabl

LSB

CLR
CALL

<ORX2CSR(RS)
REPLY

DYDONE:
disable interrupts
reply if needed

test for new packets , start if any
else signal semaphore and exit
10$:

waqc$s
BEQ
MOV
CALL
BCS

sdb=RS,qelm=R4
20$
R4,PACKET(RS)
DOREQ
10$

20$:

BR
sgnl$s

30$
sdb=$DYDNE(RS)

30$:

RETURN

another packet?
nope ... go signal process
yes, save -> new packet
start request
illegal request ...
controller not started
otherwise return
Signal queue process
controller is idle
Dismiss the real interrupt

.dsabl LSB
.sbttl

INWAIT

- Start function and wait for interrupt from floppy

RS -> impure area
R3 command
R2 second command (0 if none)
CALL

INWAIT

Note:

Only registers R5 and R3 are preserved across
call to INWAIT

.ENABL

LSB

INWAIT: MOV
TST
BM!

(SP)+,INTRTN(R5)
<ORX2CSR(R5)
DYERR

save return point
is error bit set?
yes ... check it out

****
****

Sample MACR0-11 Device Driver

D-13

10$:

INC
BEQ
MOV
MOV
TST
BEQ

ISRENB(RS)
10$
R3,<0RX2CSR(RS)
R3,SAVR3(RS)
R2
30$

flag main process is (will) blocked
if it rolled over .. do it again
Start command
Save command for after intr
format or read status?
no .. return

Note: When running on an LSI, 4.S micro seconds must elapse
between loading the function and testing the transfer bit
20$:

BITB
BEQ
MOV

30$:
CLC
RETURN

no special return
does not return to caller
but to caller's caller

.DSABL

LSB

.sbttl

DOSILO

- Initiate a silo fill or empty command

Inputs:
RS -> impure area
R3
command
Outputs:
R4
R2

DOSILO:

10$:

20$:

D-14

word count this transfer
buff er address

Note:

Only registers RS and R3 are preserved across
call to DOSILO

.ENABL

LSB

MOV
MOV
BIC

(SP)+,INTRTN(RS)
WRDCNT(R5),R2
#2*2,R3

TST
BM!
INC
BEQ
MOV

BIS
MOV
CMP

#2*2,R3
SECSIZ(R5),R4
R4,R2

BLOS
MOV
MOV
MOV
BR

20$
R2,R4
R4,COUNT(RS)
BUFFER(R5),R2
DYDOFN

.DSABL

LSB

Sample MACR0-11 Device Driver

save return address
get word count for xf er
Change read/write to
fill/empty command
is error bit set?
****
yes ... check it out ****
flag main process is blocked
if it rolled over .. do it again
start command
Fix command from above
get sector size
is sector size smaller
than word count left?
yes, just read a sector
no, read remain count
save transfer count
get -> to buff er
go load count and
address, start

.sbttl

DOXFER

- Start a sector read or write

;+
Inputs:
R3 command
R5 -> impure area
Outputs:
R4
R2

sector
track

Note:

Only registers R5 and R3 are preserved across
call to DOXFER

.ENABL

LSB

DOXFER: MDV
TST
BM!
10$:
INC
BEQ
MDV

(SP)+,INTRTN(R5)
<ORX2CSR(R5)
DYERR
ISRENB(R5)
10$
R3,<0RX2CSR(R5)

save return address
is error bit set?
****
yes ... check it out ****
flag main process is blocked
if it rolled over .. do it again
initiate function

Note: When running on an LSI 4.5 micro seconds must elapse
between loading the function and testing the transfer bit

20$:
30$:

40$:

50$:

TSTB
BNE
MDV
MDV
BR

ADTYPE(R5)
20$
SECTOR(R5) ,R4
TRACK(R5),R2
DYDOFN

Physical transfer?
No, we must compute interleave
get sector in r4
track in r2
start operation

MDV
MDV
CMP
BHI
ADD
;SEC
ROL
DEC
BGT
MOVB
CLRB
SWAB
CMP
ROL

#8. ,R2
LSN(R5),R4
#26.*200,R4
40$
#-26.*200,R4
R4
R2
30$
R4,R2
R4
R4
#12. ,R4
R4

ASL
ADD
ADD
ADD
ASR
INC
SUB
BGE
ADD
.BR

R2
R2,R4
R2,R4
R2,R4
R2
R2
#26. ,R4
50$
#27. ,R4
DYDOFN

loop count
Logical sector number
Does 26 go into dividend?
Br if not, c clear (bhi => bee)
Subtract 26 from dividend
C = 1 from 'add' above
Shift dividend and quotient
dee loop count
Br till divide done
Copy track number
remove track number from remainder
get remainder
c=1 if 13<=r4<=25, else c=O
sector*2 (2:1 interleave)
[+1 (c) if sector 13-25]
double the track number
skew the sector
by adding in
6 * track number
undouble track number
and make it 1-76 (skip 0 for ansi)
Modulo sector into range 1-26
loop until remainder goes neg
put sector in range 1-26
start transfer

.DSABL

LSB

.sbttl

DYDOFN

- Start a transfer or silo operation

Sample MACR0-11 Device Driver

D-15

Inputs:
R5 -> impure area
R4
first value (sector or word count)
R3
original function code
R2
second value (track or address)
.ENABL

LSB

DYDOFN:
MOV

R3,SAVR3(R5)

; save command for aft~r intr

Note: When running on an LSI, 4.5 micro seconds must elapse
between loading the function and testing the transfer bit
10$:

BITB
BEQ
MOV
BITB
BEQ
MOV
CLC
RETURN

20$:

is TR set?
br if not
load sector/word count
is TR set?
wait for TR
now track/address
no special return
bye

.DSABL LSB
.sbttl

$DYINT

- Interrupt Service Routine (!SR)

$DYINT - Interrupt Service Routine
This code is invoked whenever an interrupt is received from the RX02.
This routine restores R5 and R3 and jumps the routine which
initiated the function. If there are any errors, DYERR is called
to investigate and possible retry.
The !SR must be PIC code, so AMA is disabled here .

.
$DYINT:

10$:

fork$
BCS
MOV
MOV
TST
BM!
JMP
RETURN

D-16

Sample MACR0-11 Device Driver

Request fork processing
If CS, previous fork not processed
restore pointer to impure area
restore r3 (command)
any errors?
handle errors
continue where we left off
???

.sbttl

DYERR

- Error handler

Handles errors from RX02 and retrys function if retries are not
inhibited.
RS ->
R3

Impure area
command

DYERR

R4,R2,R1,RO modified .

. ENABL

LSB

DYERR:
MOV
©RX2DB(R5) ,RO
MOV
RO,COUNT(R5)
BIT
#ESDNER,RO
BEQ
20$
MOV
DENPTR(R5),R2
(R2)+,R3
BIC
NEGB
-(R2)
;SEC/CLC
(R2)+
INCB
-(R2) ,R3
BIS
BCS
10$
ASR
LSN(R5)
ASL
SECSIZ(R5)
BR
20$

save error register
save it COUNT(R5)
Density error?
no handle in usual manner
-> density
Turn off bit if on
tricky way to change 1 -> O
c=1 if density was double, single
and 0 -> 1
turn on double bit if not on
br if it was double
single -> double 1/2 sector
double sector size
and continue

10$:

ASL
ASR

LSN(R5)
SECSIZ(R5)

double -> single 2* sector
1/2 sector size

20$:

MOV

start an initialize
wait before setting ie since
initialize clears csr

DECB
BLE

RTYCNT(R5)
30$

decrement retry count
If LE, exhausted or inhibited

BIT
BNE
MOV
MOV
CLR
CALL
MOV
MOV
BIT
BEQ
JMP

#ESACLO,RO
40$
R3,TEMP(R5)
#CSINT,R3
R2
INWAIT
TEMP(R5) ,R3
COUNT(R5) ,RO
#ESCRC!ESDNER,RO
30$
DYTRAN

was the error AC low?
yes ... any more would be useless
save command
get interrupt enable
no second command for inwait
do it
restore command
RO = saved RX2DB
Is it a CRC or density error ?
If EQ, no, it's a hard error
Try again

Sample MACR0-11 Device Driver D-17

Hard error, or retrys exhausted or inhibited.
; This code is to check drive ready bit which is
; valid only after a read status or initialize ....
30$:

MOV
BIC
BIT
BNE
BIS

#ESDRDY,R2
R2,RO
R2,(QRX2DB(R5)
40$
R2,RO

Get ready bit
clear drive not ready bit
drive ready?
Yes .. retry if possible
set drive not read bit

40$:

push$

Copy error/status register

MOV

#ERLIST,RO

-> list of status codes each error

BIC

#170000!ESHEAD!ESUNIT!ESDDEN!ESDDAT!ESSID1,(SP)
Clear bits which don't
indicate errors
Br if no further bits to check
60$
R1, (RO)+
Update error status pointer
(SP)
Set carry if error and Z if no more
errors
Br if not right error
50$
(SP)+
Remove remnant of status register
(RO) ,STATUS(R5)
Copy status indicator
(RO) ,#ES$PWR
was AC low the error?
yes .. any more is useless ....
80$

50$:

60$:

BEQ
BIT
ASR
BCC
TST
MDV
CMP
BEQ

This routine reads the extended error code from the RX02
and places it in the error word to be shipped back to the user
BIC
BIS

MDV
ADD

#CSXM!CSFUN,R3
#CSMAIN,R3
R5,R2
#SECTOR,R2

clear function and xm bits
Read error reg
set up -> to buff er addr

NOTE: xtad$ macro uses RO
xtad$

vadd=R2,par=(Q#K.ISA3,pos=12. ,ext=R4,addr=R1

BIS
MOV
CALL
MOVB

R4,R3
R1,R2
INWAIT
SECTOR(R5) ,ERROR(R5)

JMP

DYDO NE

TST
BNE
CALL
JMP

ISRENB(R5)
70$
REPLY
DYREQ

.dsabl

LSB

Set new xm bits
set up low address
Go do it.
Put RX02's response in 'ERROR'.

70$:
80$:

D-18

Sample MACR0-11 Device Driver

is the main process blocked?
br if so .. unblock it
otherwise reply
and get next request

.sbttl

- Return Status Message Subroutine

This routine dispatches the reply to the user if he requested one .
R5

CALL

.enabl

LSB

Impure area

pure$
REPLY:

10$:

MDV
BEQ

PACKET(R5) ,R4
40$

R4 -> request packet
no packet ... exit

MDV
MDV
BEQ
as sum$

DP.LEN(R4) ,DP.ALN(R4)
STATUS(R5),DP.STS(R4)
20$
ES$NDR EQ 0

Copy byte count requested
Copy status code
If EQ, all bytes were xfered.

MDV
ASL

WRDCNT(R5),R2
R2
R2,DP.ALN(R4)
ERRDR(R5),DP.ERR(R4)
$DRPLY
PACKET(R5)

# of words left in xfer
make it bytes
Subtract number left from total
Put error code from READM in queue.
reply to user
no more packet
and return

SUB

20$:

MDV
CALL
CLR
40$: RETURN
.dsabl

LSB

.sbttl

DYSTP

- Request process termination routine

This is the stop process section. It signals all the processes that are
waiting that with the abort code and deletes the structures and the process.
DYSTP:
©RX2CSR(R5)
#ES$ABT,STATUS(R5)
REPLY

10$:

CLR
MDV
CALL

20$:

waqc$s
sdb=R5,qelm=R4
BCS
20$
BNE
10$
dlst$s
sdb=R5
dlst$s
sdb=$DYDNE(R5)
dint$s
vec=VECTDR(R5)
dlpc$

Disable further interrupts
Send abort status code to
all waiting processes?
any more requests?
br if error
yes ... send abort code
Delete all structures
created.
Disconnect from interrupt vector

.end

Sample MACR0-11 Device Driver

D-19

Index
A
AD driver
features and capabilities, 7-1
Get Characteristics function,
7-14
prefix file, 7-15
status codes, 7-15
ADP AR$ macro (Return PAR
address), 15-3
Analog-to-digital conversions, 7-2
Ancillary Control Process (ACP)
FALACP, 2-11
features and capabilities, 2-1
file 1/0, 2-2
prefix file, 2-9
status codes, 2-8
Application development
configuration guidelines, B-10
initialization and self-test
options, B-14
KXTll-CA
memory configuration
steps, B-11
partitioning, B-9
peripheral processor, B-9
tools
MicroPower/Pascal, B-2
summary, B-2
Application loading
KXJ_LOAD, B-66
KXT_LOAD, B-66
peripheral processor, B-66
Applications
overview
peripheral processor, B-1
peripheral processor, B-6
software configuration, B-8

Arbiter process
application, B-54
communication with peripheral
processor, B-8
configuration file, B-54
1/0 page area, B-8
Arbiter processor
device drivers, B-2
LSl-11, B-1
operating system environment,
B-2
peripheral processor
relationship, B-1
Asynchronous 1/0
DDCMP, 12-3
serial, 3-2
Automatic self-tests
error reporting, B-18

B
$BLX10 subroutine (Block move),
15-25
Boot/Self-test switch, B-13, B-14
Boots,trap loader
radial serial· protocol (RSP),
B-17
TU58 DECtape II, B-17
Buffering, hardware, 3-20

c
Checksum
calculating with DECprom,
B-65
specifying ROM test, B-16
Command register
KW.DCO, B-22

Index-1

Index

Communication Device 1/0
DECnet, 13-6
Communication driver
features and capabilities, 13-2
Communication support routines
peripheral processor, 13-32
Configuration file
CFDKTC.MAC, B-3 7
MicroPower/Pascal sample,
B-37
CONFIGURATION macro, B-37
Configuration macro
device controller, 14-5
device driver, 14-4
Configuring Memory, B-10
Console ODT
hardware setup, B-18
Control and Status Register (CSR)
KX device driver, B-14
Conversions
analog-to-digital, 7-2
Copyright page
device driver, 14-11
Counter/Timer
support routines
external pulses, 6-21
KXTll-CA/KXJll-CA, 6-9
linking counters, 6-24
CS driver
Disable Protocol function,
12-11
Enable Protocol function, 12-11
features and capabilities, 12-2
Get Characteristics function,
12-12
prefix file, 12-13
Read function, 12-11
status codes, 12-13
Write function, 12-11

D
Data transfers
DMA Transfer Controller
(DTC), B-1
two-port RAM registers (TPR),
B-1
DCT-11 microprocessor
general description, B-3
DD driver
Get Characteristics function,
4-22

lndex-2

DD driver (cont'd.)
Logical Read function, 4-20
Logical Write function, 4-20
Physical Read function, 4-21
Physical Write function, 4-21
$DDEXC subroutine (Report
exception), 15-26
$DDINI macro (Device driver
initialization), 15-27
Debugging
console ODT hardware setup,
B-18
Declarations
device driver, 14-12
DECnet
communication device 1/0,
13-6
DECprom
calculating ROM checksums,
B-65
Device controller
configuration macro, CTRCF$,
14-5
errors
nonrecoverable, 14-19
recoverable, 14-19
Device controller process
device driver, 14-15
Device driver
arbiter processor, B-2
configuration macro, DRVCF$,
14-4
copyright page, 14-11
declarations, 14-12
device controller process, 14-15
error-processing routines, 14-18
errors
resource famine, 14-19
exception codes, 14-18
externally defined symbols,
14-12
functional description, 14-11
impure-area definition, 14-14
. impure-area definition macro,
xxISZ$, 14-9
initialization process, 14-14
invalid requests, 14-18
local macro definition, 14-12
macros
compute bus extended
address, 15-22

Index

Device driver
macros (cont'd.)
define driver packet
symbols, 15-7
disable MMU context
switch, 15-8
enable MMU context
switch, 15-11
increment byte address,
15-13
increment word address,
15-14
move address and PAR,
15-18
move byte, 15-15
move byte (user-mode
only), 15-16
move word, 15-19
move word (mapped case
only), 15-17
move word (user-mode
only), 15-20
read PAR or PDR register,
15-6
remap virtual address, 15-3
return PAR address, 15-3
set priority level, 15-21
write to PAR or PDR
register, 15-10
module header, 14-11
overview, 14-1
peripheral processor, B-2
prefix module, 14-3
DYPFX.MAC, 14-8
priority assignments, 14-3
process definition, 14-12
pure-area definition, 14-14
reply subroutine, 14-17
sample MACR0-11 program,
D-1
source module, 14-10
subroutines
allocate dynamic memory,
15-31
allocate memory, 15-28
block move, 15-25
deallocate dynamic
memory, 15-29
initialize device driver,
15-27
initialize heap, 15-30
report exception, 15-26

Device driver
subroutines (cont'd.)
save/restore registers,
15-33
send device driver reply,
15-32
termination procedure, 14-18
Device 1/0
Digital Network Architecture
(DNA), 13-6
Device name, parsing, 2-10
DEVICES macro, B-37
Digital Network Architecture
(DNA)
device 1/0, 13-6
Disk drivers
features and capabilities, 4-2
prefix files, 4-26
status codes, 4-24
Disk 1/0, 4-3
DL driver
Get Characteristics function,
4-12
Logical Read function, 4-10
Logical Write function, 4-10
Physical Read function, 4-11
Physical Write function, 4-11
DMA 1/0
KXTll-CA/KXJll-CA, 9-2
DMA Transfer Controller (DTC)
data transfers, B-1
DMA transfers
parallel 1/0, 9-8, 9-21
sample program, 9-11
serial line unit, 9-8, 9-22
$DRALR subroutine (Allocate
memory), 15-28
$DRDSP subroutine (Deallocate
dynamic memory), 15-29
$DRHIN subroutine (Initialize
heap), 15-30
DRMAP$ macro (Remap virtual
address), 15-4
$DRNEW subroutine (Allocate
dynamic memory), 15-31
DRPAR$ macro (Read PAR or
PDR register), 15-6
$DRPLY subroutine (Send device
driver reply), 15-32
DRVDF$ macro (Define driver
packet symbols), 15-7

Index-3

Index

DSCXW$ macro (Disable MMU
context switch), 15-8
DTC
See DMA Transfer Controller
(DTC)
DU driver
Get Characteristics function,
4-18
Logical Read function, 4-17
Logical Write function, 4-17
DWPAR$ macro (Write to PAR or
PDR register), 15-10
DY driver
Get Characteristics function,
4-16
Logical Read function, 4-13
Logical Write function, 4-13
Physical Read function, 4-14
Physical Write function, 4-14
format subfunctions, 4-15

E
ENCXW$ macro (Enable MMU
context switch), 15-11
Error information, extended, 4-26,
6-44, 10-38
Error-processing routines
device driver, 14-18
Errors
automatic self-tests
reporting, B-18
device controller
nonrecoverable, 14-19
recoverable, 14-19
device driver
resource famine, 14-19
KXTll-CA
fatal, B-15
self-tests
reporting, B-15
Ethernet communication
QN driver, 13-3.
Exception codes
device driver, 14-18
External pulses
counter/timer support routines,
6-21

F
FALACP, 2-11

Index-4

Features and capabilities
AD driver, 7-1
Ancillary Control Process
(ACP), 2-1
communication driver, 13-2
CS driver, 12-2
disk drivers, 4-2
Instrument bus, 10-1
KW driver, 8-1
MU driver, 5-1
Network Service Process (NSP),
11-1
parallel line driver, 6-2
QD driver, 9-1
TT driver, 3-1
XE driver, 10-3
File IJO
Ancillary Control Process
(ACP), 2-2
File system interface, Pascal, 2-3
File variable
Get Characteristics request,
11-6
Fork routine
Interrupt Service Routine (ISR),
14-17
Format subfunctions
DY driver
Physical Write function,
4-15
Functional description
device driver, 14-11
Functions
Allocate Channel
QD driver, 9-24
Auxiliary Command
XE driver, 10-31
Clear Timer
YK driver, 6-43
Close, 2-7
Deallocate Channel
QD driver, 9-24
Delete, 2-7
Disable
KK driver, 13-24
KX driver, 13-24
XA driver, 6-31
XP driver, 13-19
XS driver, 13-19
Disable Clock
KW driver, 8-17
Disable Portal

Index

Functions
Disable Portal (cont'd.)
QN driver, 13-18
Disable Protocol
CS driver, 12-11
$DMA, 9-11
$DMA_ALLOCATE
QD driver, 9-11
$DMA_GET_STATUS
QD driver, 9-9
$DMA_SEARCH
QD driver, 9-6
$DMA_SEARCH_TRANSFER
QD driver, 9-7
$DMA_TRANSFER
QD driver, 9-4
DMA Complete
YK driver, 6-41
DMA Read
YK driver, 6-41
DMA Write
YK driver, 6-41
Enable
KK driver, 13-24
KX driver, 13-24
XA driver, 6-30
XP driver, 13-19
XS driver, 13-19
Enable Clock
KW driver, 8-15
Enable Portal
QN driver, 13-15
Enable Protocol
CS driver, 12-11
Enter, 2-6
Get Characteristics, 2-5
AD driver, 7-14
CS driver, 12-12
DD driver, 4-22
DL driver, 4-12
DU driver, 4-18
DY driver, 4-16
KK driver, 13-23
KW driver, 8-17
KX driver, 13-23
MU driver, 5-12
Network Service Process
(NSP), 11-4
QD driver, 9-22
QN driver, 13-18
TT driver, 3-9
VM driver, 4-23

Functions
Get Characteristics (cont'd.)
XA driver, 6-30
XD driver, 4-19
XE driver, f0-25
XP driver, 13-20
XS driver, 13-20
YA driver, 6-32
YB driver, 6-36
YF driver, 6-37
YK driver, 6-39
Get Control
XE driver, 10-32
Go to Standby
XE driver, 10-33
KK_READ_DATA, 13-35
KK_WRITE_DATA, 13-35
KX_READ_DATA, 13-33
KX_WRITE_DATA, 13-34
Load Parallel Poll Register
XE driver, 10-29
Logical Read, 2-5
DD driver, 4-20
DL driver, 4-10
DU driver, 4-17
DY driver, 4-13
VM driver, 4-23
XD driver, 4-18
Logical Write, 2-5
DD driver, 4-20
DL driver, 4-10
DU driver, 4-17
DY driver, 4-13
VM driver, 4-23
XD driver, 4-18
Lookup, 2-6
Parallel Poll
XE driver, 10-29
Parallel Poll Configure
XE driver, 10-30
Pass Control
XE driver, 10-33
Physical Read, 2-4
DD driver, 4-21
DL driver, 4-11
DY driver, 4-14
Physical Write, 2-4
DD driver, 4-21
DL driver, 4-11
DY driver, 4-14
Protect, 2-7
Purge, 2-7

Index-5

Index

Functions (cont'd.)
Read
CS driver, 12-11
KK driver, 13-22
KX driver, 13-22
MU driver, 5-11
QD driver, 9-16
QN driver, 13-16
TT driver, 3-7
XA driver, 6-29
XP driver, 13-19
XS driver, 13-19
YA driver, 6-31
YB driver, 6-33
YF driver, 6-36
YK driver, 6-38
READ_PIO, 6-9
Read Logical
converted data, 7-13
XE driver, 10-23
Read Physical
KW driver, 8-13
Read Timer
YK driver, 6-43
Recognize Event
XE driver, 10-35
Rename, 2-7
Reposition Tape
MU driver, 5-12
Request Service
XE driver, 10-32
Rewind Tape
MU driver, 5-13
Serial Poll
XE driver, 10-28
SET_STATE
XE driver, 10-8
Set Characteristics, 2-5
configure device, 7-11
Network Service Process
(NSP), 11-4
TT driver, 3-9
XE driver, 10-25
YB driver, 6-35
Set Event Mask
XE driver, 10-34
Set Modem Semaphore
TT driver, 3-14
XP driver, 13-21
XS driver, 13-21
Set Pattern
YK driver, 6-40

.lndex-6

Functions (cont'd.)
Set Timer
YK driver, 6-42
Stop
XP driver, 13-21
XS driver, 13-21
Stop Request
TT driver, 3-15
Unprotect, 2-7
Wait for Event
XE driver, 10-35
Write
CS driver, 12-11
KK driver, 13-22
KX driver, 13-22
MU driver, 5-11
QD driver, 9-16
QN driver, 13-16
TT driver, 3-8
XA driver, 6-29
XE driver, 10-24
XP driver, 13-19
XS driver, 13-19
YA driver, 6-31
YB driver, 6-33
YF driver, 6-36
YK driver, 6-38
Write IEEE Remote Messages
XE driver, 10-27
Write Tape Mark
MU driver, 5-13
Write with EOI Termination
XE driver, 10-24
YK_CLEAR_TIMER, 6-21
YK_PORT_READ, 6-10
YK_PORT_WRITE, 6-11
YK_READ_TIMER, 6-20
YK_SET_PATTERN, 6-12
YK_SET_TIMER, 6-19

G
Get Characteristics function
file variable, 11-6
$SECTL Queue Semaphore,
11-5

H
Hardware
configuration
guidelines, B-10
peripheral processor, B-8

Index

Hardware (cont'd.)
features
KXTl 1-CA, B-3
jumper
memory map, B-18
TPR base address, B-13
overview
peripheral processor, B-1
setup
peripheral processor, B-13
stand-alone processor, B-13
Hardware buffering, 3-20

1/0
asynchronous DDCMP, 12-3
asynchronous serial, 3-2
disk files, 4-3
DMA transfers, 9-2
instrument bus, 10-4
page area, B-8
parallel lines, 6-3
performing, 1-7
procedure interface, Pascal, 3-3,
4-5, 5-8, 6-5, 7-3, 13-10
real-time clock, 8-2
request/reply packets, 1-11
system arctiitecture, 1-3
TMSCP tape files, 5-2
IBADR$ macro (Increment byte
address), 15-13
Impure-area definition
device driver, 14-14
Impure-area definition macro
device driver, 14-9
Initialization options
selecting, B-14
Initialization process
device driver, 14-14
Instrument bus
features and capabilities, 10-1
1/0, 10-4
,
Interrupt Service Routine (ISR)
fork routine, 14-17
overview, 14-16
Invalid requests
device driver, 14-18
IWADR$ macro (Increment word
address), 15-14

j
Jumper
memory map, B-18
TPR base address, B-13

K
KK_READ_DATA function, 13-35
KK_WRITE_DATA function,
13-35
KK driver
Disable function, 13-24
Enable function, 13-24
Get Characteristics function,
13-23
prefix file, 13-28
Read function, 13-22
status codes, 13-24
two-port RAM communication,
13-5
Write function, 13-22
KUI program, B-17
KW driver
Disable Clock function, 8-17
Enable Clock function, 8-15
features and capabilities, 8-1
Get Characteristics function,
8-17
prefix file, 8-18
Read Physical function, 8-13
status codes, 8-18
KX/KK protocol
command register definitions,
B-27
concepts, B-22
driver transactions, B-23
interface initialization, B-32
KC.COM command field, B-27
KC.EOM bit, B-30
KC.IDA bit, B-28, B-29
KC.IDA command register bit,
B-22
KC.IDR bit, B-28, B-30
KC.IDR command register bit,
B-22
KC.LEN field, B-28, B-30
KC.NOP no-op command, B-27
KC.VEC field, B-28, B-30
KC$DI command, B-28
KC$EI command, B-28
KC$GS command, B-28
KC$RD command, B-28

Index-7

Index

KX/KK protocol (cont'd.)
KC$RSM command, B-27
KC$SS command, B-28
KC$WD command, B-29
KE$ILC code, B-31
KE$ILL code, B-31
KE$IL V code, B-31
KE$NDA code, B-31
KE$NDR code, B-31
KE$0K code, B-31
KE$0VR code, B-31
KS.ALN field, B-32
KS.DA bit, B-32
KS.DA status register bit, B-22
KS.DR bit, B-31
KS.EOM bit, B-31
KS.ERC field, B-31
KS.ERR bit, B-32
KS.IEN bit, B-28, B-32
KS.ON bit, B-32
KW.DCO register, B-22
master/slave relationship, B-19
message communication, B-25
overview, B-19
status register definitions, B-30
synchronizing operations, B-26
KX_READ_DATA function, 13-33
KX_WRITE_DATA function,
13-34
KX device driver
logical unit IDs, B-35
KX driver
Control and Status Register
(CSR), B-14
Disable function, 13-24
Enable function, 13-24
Get Characteristics function,
13-23
prefix file, 13-28
Read function, 13-22
status codes, 13-24
two-port RAM communication,
13-5
Write function, 13-22
KXJll-CA
See also Peripheral processor
application, B-54
configuration file, B-54
hardware
features, B-4
shared memory, B-52
stand-alone operation, B-1

lndex-8

KXJ_DISABLE_SHARED
procedure, B-54
KXJ_ENABLE_SHARED
procedure, B-53
KXJ_LOAD routine
application loading, B-66
loading KXJl l -CA, B-17
MIM File, B-66
user's interface, B-66
KXTll-CA
See also Peripheral processor
application loading, B-66
CSR assignments, B-33
DCT-11 microprocessor
features, B-3
fatal error, B-15
hardware
features, B-3
interrupt vector assignments,
B-33
loading from arbiter, B-17
memory
general description, B-3
memory configuration steps,
B-11
stand-alone operation, B-1
KXTl 1-CA/KXJl 1-CA
See Peripheral processor
KXTllC macro, B-37
KXT_LOAD routine
application loading, B-66
loading KXTl 1-CA, B-17
MIM file, B-66
program example, B-67
user's interface, B-66

L
LED display, B-18
fatal errors, B-15
Linking counters
counter/timer support routines,
6-24
Loading
KXJll-CA
KXJ_LQAD routine, B-17
KXTll-CA
from arbiter, B-17
from RT-11 and RSX-11
systems, B-17
KXT_LOAD routine, B-17
TU58 DECtape II, B-17

Index

Logical unit IDs
KX device driver, B-35
Loopback tests, B-18
LSl-11 systems
adding peripheral processors,
B-7
arbiter processor, B-1

M
Macro definition, local
device driver, 14-12
Memory
KXTll-CA
configuration steps, B-11
general description, B-3
selecting maps, B-10
map
configuration rules, B-12
map layout, B-11
MEMORY macro, B-37
Memory map
jumper, B-18
TPR base address, B-13
MicroPower/Pascal
configuration guidelines, B-10
device drivers, B-2
features, B-2
sample KXTll-CA configuration file, B-3 7
Module header
device driver, 14-11
MU driver
features and capabilities, 5-1
Get Characteristics function,
5-12
prefix file, 5-15
Read function, 5-11
Reposition Tape function, 5-12
Rewind Tape function, 5-13
status codes, 5-14
Write function, 5..:11
Write Tape Mark function, 5-13
MVBYT$ macro, Move byte,
15-15
MVBYU$ macro, Move byte
(user-mode only), 15-16
MVMAP$ macro, Move word
(mapped case only), 15-17
MVVAD$ macro (Move address
and PAR), 15-18 ..
MVWRD$ macro, Move word,
15-19

MVWRU$ macro, Move word
(user-mode only), 15-20

N
Network Service Process (NSP)
features and capabilities, 11-1
Get Characteristics function,
11-4
prefix file, 11-8
Set Characteristics function,
11-4
status codes, 11-6
task-to-task communication,
11-2
Node number, local
determine and set, 11-15

p
Packet interface, request/reply
overview, 1-8
Parallel 1/0, 6-3
DMA process
KXTl 1-CA/KXJl 1-CA,
6-15
DMA transfers, 9-8, 9-21
status codes, 6-43
support routines
KXTl 1-CA/KXJll-CA, 6-9
SBC-11/21, 6-8
Parallel line driver
features and capabilities, 6-2
prefix files, 6-45
Parallel processing, B-9
Pascal
file system interface, 2-3, 11-4
1/0 procedure interface, 3-3,
4-5, 5-8, 6-5, 7-3, 12-6,
13-10
support routines interface, 5-4,
6-7, 7-4, 8-3, 9-3, 10-5
Peripheral processor
adding to LSl-11 systems, B-7
application development, B-9
design, B-9
MicroPower/Pascal, B-2
RT-11 and RSX tool kits,
B-2
tool kits, B-2
applications, B-6
overview, B-1
partitioning, B-9

Index-9

Index

Peripheral processor
applications (cont'd.)
software configuration, B-8
arbiter processor relationship,
B-1
communication support
routines, 13-32
communication with arbiter
process, B-8
configuring hardware, B-10
configuring software, B-10
device drivers, B-2
environment, B-1
configuring system, B-13
hardware
configuration, B-8
overview, B-1
setup, B-13
jumper
TPR base address, B-13
programming languages, B-2
Q-bus limits, B-13
software architecture, B-1
system ID switch, B-35
two-port RAM registers (TPR),
B-1
XL driver, C-17
Prefix files
AD driver, 7-15
Ancillary Control Process
(ACP), 2-9
CS driver, 12-13
disk drivers, 4-26
KK driver, 13-28
KW driver, 8-18
KX driver, 13-28
MU driver, 5-15
Network Service Process (NSP),
11-8
parallel line driver, 6-45
QD driver, 9-26
QN driver, 13-25
TT driver, 3-16
XA driver, 6-45
XE driver, 10-38
XL driver
KXTll-CA, C-28
PDP-11, C-12
XP driver, 13-26
XS driver, 13-26
YA driver, 6-46
YB driver, 6-47

Index-10

Prefix files (cont'd.)
YF driver, 6-48
YK driver, 6-50
Prefix module
device driver, 14-3, 14-8
priority assignments, 14-3
PRIMITIVES macro, B-37
Priority assignments
device driver prefix module,
14-3
Procedures
IEQ_AUX_COMMAND
XE driver, 10-14
IEQ_COMMAND
XE driver, 10-10
IEQ _CONTROL _GTS
XE driver, 10-16
IEQ _PARALLEL _CONFIG
XE driver, 10-13
IEQ _PARALLEL _LOAD
XE driver, 10-13
IEQ _PARALLEL _POLL
XE driver, 10-12
IEQ _P ASS_CONTROL
XE driver, 10-17
IEQ_REQ_SERVICE
XE driver, 10-15
IEQ_SERIAL
XE driver, 10-11
READ_ANALOG_SIGNAL,
7-7
READ_COUNTS_SIGNAL,
8-6
READ_COUNTS_WAIT, 8-3
READ_IEQ
XE driver, 10-6
READ_TAPE, 5-5
REC_IEQ _EVENT
XE driver, 10-18
REPOSITION_TAPE, 5-6
REWIND_TAPE, 5-7
SET_ANALOG_MODE, 7-5
SET_INT_MASK
XE driver, 10-17
SET_pIQ_MODE, 6-8
START__RTCLOCK, 8-8
STOP_RTCLOCK, 8-10
WRITE_EOI_IEQ
XE driver, 10-9
WRITE_IEQ
XE driver, 10-7
WRITE_PIO, 6-8

Index

Procedures (cont'd.)
WRITE_TAPE, 5-5
WRITE_TAPE_MARK, 5-7
Process definition
device driver, 14-12
PROCESSOR macro, B-37
Programming languages
peripheral processor, B-2
Pure-area definition
device driver, 14-14

Q
Q-bus
KXTl 1-CA limitations, B-13
QD driver
Allocate Channel function, 9-24
Deallocate Channel function,
9-24
$DMA_ALLOCATE function,
9-11
$DMA_DEALLOCATE
function, 9-11
$DMA_GET_STATUS
function, 9-9
$DMA_SEARCH_TRANSFER
function, 9-7
$DMA_SEARCH function, 9-6
$DMA_TRANSFER function,
9-4
features and capabilities, 9-1
Get Characteristics function,
9-22
prefix file, 9-26
Read function, 9-16
status codes, 9-25
Write function, 9-16
QN driver
Disable Portal function, 13-18
Enable Portal function, 13-15
Ethernet communication, 13-3
Get Characteristics function,
13-18
prefix file, 13-25
Read function, 13-16
Write function, 13-16
Queue names, request, 1-9
Queue Semaphore
Get Characteristics, 11-5
Set Characteristics, 11-4

R
Radial serial protocol (RSP)
bootstrap loader, B-17
RAM
configuration rules, B-12
selecting maps, B-10
Random-access device
contiguous file storage, A-16
method, A-16
directory, A-4
entry, A-6
extended entry, A-8
fragmented, A-12
sample segment, A-9
segment header, A-5
end-of-segment marker, A-8
home block, A-2
size and number of files, A-18
structure, A-1
READ_ANALOG_SIGNAL
procedure, 7-7
READ_COUNTS_SIGNAL
procedure, 8-6
READ_COUNTS_WAIT
procedure, 8-3
READ_PIO function, 6-9
READ_TAPE procedure, 5-5
Read Logical function
converted data, 7-13
Real-time clock IJO, 8-2
Reply subroutine
device driver, 14-17
REPOSITION_TAPE procedure,
5-6
Request/Reply packet interface,
2-4, 4-7, 5-9, 6-25, 7-8, 8-10,
9-14, 10-20, 12-8, 13-11
overview, 1-8
TT driver, 3-5
Request queue names, 1-9
RESOURCES macro, B-37
REWIND_TAPE procedure, 5-7
ROM
application start-up
selecting, B-16
calculating checksums, B-65
configuration rules, B-12
selecting maps, B-10
specifying checksum test, B-16

Index-11

Index

s
Sample program
DMA transfers, 9-11
task-to-task communication,
11-11, 11-13
SBC-11/21 PIO support routines,
6-8
$SECTL Queue Semaphore
Get Characteristics, 11-5
Set Characteristics, 11-4
Self-tests
automatic, B-17
error reporting, B-15
ROM applications, B-16
selecting options, B-14
Serial line unit
DMA transfers, 9-8, 9-22
SET_ANALOG_MODE
procedure, 7-5
SET_PIO_MODE procedure, 6-8
Set Characteristics function
configure device, 7-11
$SECTL Queue Semaphore,
11-4
SLUl
loading programs from TU58
DECtape II, B-17
Software architecture
master/slave concept, B-1
Source code
XD driver, 4-30
Source module
device driver, 14-10
SPL$ macro (Set priority level),
15-21
Stand-alone processor
hardware setup, B-13
START_RTCLOCK procedure, 8-8
Starting
ROM application, B-16
Status codes
AD driver, 7-15
Ancillary Control Process
(ACP), 2-8
CS driver, 12-13
disk drivers, 4-24
KK driver, 13-24
KW driver, 8-18
KX driver, 13-24
MU driver, 5-14
Network Service Process (NSP),
11-6

lndex-12

Status codes (cont'd.)
parallel 1/0, 6-43
QD driver, 9-25
TT driver, 3-15
XE driver, 10-3 7
XL driver, C-28
PDP-11, C-12
STQP_RTCLOCK procedure, 8-10
$SV02 subroutine (Save/Restore
registers), 15-33
$SV03 subroutine (Save/Restore
registers), 15-33
$SV05 subroutine (Save/Restore
registers), 15-33
Switch
system ID, B-14
Symbols, externally defined
device driver, 14-12
Synchronous serial 1/0
XP driver, 13-4
XS driver, 13-4
System architecture, 1/0, 1-3
System control registers
two-port RAM registers (TPR),
B-17
System ID switch, B-13
selecting, B-14

T
Target system
loading and starting, B-14
Task-to-task communication
Network Service Process (NSP),
11-2
sample program, 11-11, 11-13
Termination procedure
device driver, 14-18
Tests
automatic self-tests, B-17
dedicated off-line, B-18
loopback, B-18
obtaining status information,
B-17
TMSCP tape IjO, 5-2
TPR
See Two-port RAM registers
(TPR)
TRAPS macro, B-37
TT driver
features and capabilities, 3-1
Get Characteristics function,
3-9

Index

TT driver (cont'd.)
prefix file, 3-16
Read function, 3-7
request/reply packet interface,
3-5
Set Characteristics function, 3-9
Set Modem Semaphore
function, 3-14
status codes, 3-15
Stop Request function, 3-15
Write function, 3-8
TU58 DECtape II
bootstrap loader, B-17
Two-port RAM registers (TPR)
communication
KK driver, 13-5
KX driver, 13-5
disabling, B-13
enabling, B-13
peripheral processor, B-1
selecting base address, B-13
system control registers, B-17

v
VM driver
Get Characteristics function,
4-23
Logical Read function, 4-23
Logical Write function, 4-23

w
WRITE_PIO procedure, 6-8
WRITE_TAPE_MARK procedure,
5-7
WRITE_TAPE procedure, 5-5

x
XA driver
Disable function, 6-31
Enable function, 6-30
Get Characteristics function,
6-30
prefix file, 6-45
Read function, 6-29
Write function, 6-29
XD driver
Get Characteristics function,
4-19
Logical Read function, 4-18
Logical Write function, 4-18
source code, 4-30·

XE driver
Auxiliary Command function,
10-31
features and capabilities, 10-3
Get Characteristics function,
10-25
Get Control function, 10-32
Go to Standby Function, 10-33
IEQ__AUX_COMMAND
procedure, 10-14
IEQ _COMMAND procedure,
10-10
IEQ _CONTROL _GTS
procedure, 10-16
IEQ _PARALLEL _CONFIG
procedure, 10-13
IEQ_PARALLEL_LOAD
procedure, 10-13
IEQ _p ARALLEL _POLL
procedure, 10-12
IEQ _p ASS_CONTROL
procedure, 10-17
IEQ _REQ _SERVICE
procedure, 10-15
IEQ _SERIAL procedure, 10-11
Load Parallel Poll Register
function, 10-29
Parallel Poll Configure function,
10-30
Parallel Poll function, 10-29
Pass Control function, 10-33
prefix file, 10-38
READ_IEQ procedure, 10-6
Read Logical function, 10-23
REC_IEQ _EVENT procedure,
10-18
Recognize Event function,
10-35
Request Service function, 10-32
Serial Poll function, 10-28
SET_INT_MASK procedure,
10-17
SET_STATE function, 10-8
Set Characteristics function,
10-25
Set Event Mask function, 10-34
status codes, 10-3 7
Wait for Event function, 10-35
WRITE_EQI_IEQ procedure,
10-9
WRITE_IEQ procedure, 10-7
Write function, 10-24

Index-13

Index

XE driver (cont'd.)
Write IEEE Remote Messages
function, 10-27
Write with EOI Termination
function, 10-24
XL Driver
Report Data-set Status Change
function, C-28
XL driver
Block-Mode Read function,
C-21
Block-Mode Write function,
C-21
Connect Receive Ring Buffer
function, C-21
Connect Transmit Ring Buffer
function, C-21
function-dependent request
formats, C-5, C-20
Get Status function, C-25
KXTll-CA
prefix file, C-28
PDP-11, C-1
Connect Receive Ring
Buffer function, C-4
Connect Transmit Ring
Buffer function, C-4
device-independent
function modifiers,
C-5
Disconnect Receive Ring
Buffer function, C-4
Disconnect Transmit Ring
Buffer function, C-4
functions, C-3
Get Status function, C-5
prefix file, C-12
Read function, C-3
Report Data-Set Status
Change function, C-4
Set Status Function, C-5
status codes, C-12
Write Function, C-3
peripheral processor, C-17
Connect Receive Ring
_, Buffer function, C-19
Connect Transmit Ring
Buffer function, C-19
device-independent
function modifiers,
C-20

lndex-14

XL driver
peripheral processor (cont'd.)
Disconnect Receive Ring
Buffer function, C-19
Disconnect Transmit Ring
Buffer function, C-20
functions provided, C-18
Get Status function, C-20
Read function, C-19
Report Data-Set Status
Change function,
C-20
Set Status function, C-20
Write function, C-19
Ring Buffer Disconnect
'function, C-22
Set Status function, C-22
status codes, C-28
XP driver
Disable function, 13-19
Enable function, 13-19
Get Characteristics function,
13-20
prefix file, 13-26
Read function, 13-19
Set Modem Semaphore
function, 13-21
Stop function, 13-21
synchronous serial 1/0, 13-4
Write function, 13-19
XS driver
Disable function, 13-19
Enable function, 13-19
Get Characteristics function,
13-20
prefix file, 13-26
Read function, 13-19
Set Modem Semaphore
function, 13-21
Stop function, 13-21
synchronous serial 1/0, 13-4
Write function, 13-19
XTAD$ macro (Compute Bus
Extended Address), 15-22

y
YA driver
"Get Characteristics function,
6-32
prefix file, 6-46
Read function, 6-31

Index

YA driver (cont'd.)
Write function, 6-31
YB driver
Get Characteristics function,
6-36
prefix file, 6-47
Read function, 6-33
Set Characteristics function,
6-35
Write function, 6-33
YF driver
Get Characteristics function,
6-37
prefix file, 6-48
Read function, 6-36
Write function, 6-36
YK_CLEAR_TIMER function,
6-21
YK_PORT_READ function, 6-10
YK_PORT_WRITE function, 6-11
YK_READ_TIMER function, 6-20
YK_SET_p ATTERN function,
6-12
YK_SET_TIMER function, 6-19
YK driver
Clear Timer function, 6-43
DMA Complete function, 6-41
DMA Read function, 6-41
DMA Write function, 6-41
Get Characteristics function,
6-39
prefix file, 6-50
Read function, 6-38
Read Timer function, 6-43
Set Pattern function, 6-40
Set Timer function, 6-42
Write function, 6-38

Index-15

HOW TO ORDER
ADDITIONAL DOCUMENTATION

From

Call

Alaska, Hawaii,
or New Hampshire

603-884-6660

Rest of U.S.A.
and Puerto Rico*

800-258-1710

Write

Digital Equipment Corporation
P.O. Box CS2008
Nashua, NH 03061

* Prepaid orders from Puerto Rico must be placed with DIGITAL's local subsidiary (809-7547575)
Canada

800-267-6219
(for software
documentation)
613-592-5111
(for hardware
documentation)

Software Distribution Center (SDC)
Digital Equipment Corporation
Westminster, MA 01473

Internal orders
(for software
documentation)
Internal orders
(for hardware
documentation)

Digital Equipment of Canada Ltd.
100 Herzberg Road
Kanata, Ontario, Canada K2K 2A6
Attn: Direct Order desk

617-234-4323

Publishing & Circulation Serv. (P&CS)
NR03-1/W3
Digital Equipment Corporation
Northboro, MA 01532
·

MicroPower/Pascal 1/0
Services Manual
AA- F015C-TK

READER'S
COMMENTS

Note: This form is for document comments only. DIGIT AL will use comments
submitted on this form at the company's discretion. If you require a written
reply and are eligible to receive one under Software Performance Report (SPR)
service, submit your comments on an SPR form.

Did you find this manual understandable, usable, and well organized? Please make suggestions for
improvement.

Did you find errors in this manual? If so, specify the error and the page number.

Please indicate the type of user /reader that you most nearly represent:

D Assembly language programmer
D Higher-level language programmer
D Occasional programmer (experienced)
D User with little programming experience

D Student programmer
D Other (please specify)

Name

Date

Organization
Street
City

State

Zip Code
or Country

Do Not Tear - Fold Here and Tape

111111

BUSINESS REPLY MAIL
FIRST CLASS PERMIT N0.33 MAYNARD MASS.
POSTAGE WILL BE PAID BY ADDRESSEE

DIGITAL EQUIPMENT CORPORATION
CORPORATE USER PUBLICATIONS
ML05-5/E45
146 MAIN STREET
MAYNARD, MA 01754-2571

Do Not Tear - Fold Here

NO POSTAGE
NECESSARY
IF MAILED
INTHE
UNITED STATES