Digital PDFs

AA-PEYCA-TE

July 1991

324 pages

Original

13MB

Document:	KAV30 Programmer’s Reference Information
Order Number:	AA-PEYCA-TE
Revision:	0
Pages:	324
Original Filename:	AA-PEYCA-TE_KAV30_Programmers_Reference_Information_Jul91.pdf

OCR Text

KAV30

Programmer’s Reference Information

Part Number: AA—PEYCA-TE

KAV30
Programmer's Reference Information
Order Number: AA—-PEYCA—TE

July 1991
This guide describes the KAV30 software and describes how to develop
real-time applications for the KAV30.

Revision Information:

This is a new guide.

Operating System and Version: VMSVersion 5.0 or higher,
VAXELN Version 4.2 or higher
Software Version:

Digital Equipment Corporation
Maynard, Massachusetts

VAXELN KAV Toolkit Extensions for VMS
Version 1.0

July 1991
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.
Restricted Rights: Use, duplication, or disclosure by the U.S. Government is subject to
restrictions as set forth in subparagraph (c)(1)(ii) of the Rights in Technical Data and Computer
Software clause at DFARS 252.227-7013.
© Digital Equipment Corporation 1991.
All Rights Reserved.
The postpaid Reader’s Comments forms at the end of this document request yourcritical
evaluation to assist in preparing future documentation.
The following are trademarks of Digital Equipment Corporation: CVAX, DEC, DECnet,
DECwindows, Digital, r‘'\VAX, ULTRIX, VAX, VAX Ada, VAX C, VAX FORTRAN, VAXELN,

VAXELN Pascal, VMS, and the DIGITAL logo.

68000 and Motorola are registered trademarks of Motorola, Inc. Intel is a trademark of Intel
Corporation.

This document was prepared using VAX DOCUMENT,Version 2.0.

Contents
Preface . Le ee ee eee ee eee eee eee eee eee

KAV30 Overview
1.1
1.2
1.3
1.3.1
1.3.2

KAV30 Hardware... .... 2... 0. ce eee eee eee
VAXELN Toolkit... 0... 0.0.0.0. cc ee eee ee nee
KAV380 Software... . 0. cc eee ee eens
Naming Conventions ............ 0c eee eee eee tenes
KAV30 System ServiceS .......... 000 cee eee ee eee es

1-1
1-2
1-4
1-4
1-5

2 KAV30 Functionality
2.1
2.2
2.3
2.4
2.9
2.6
2./
2.8
2.9
2.10
2.10.1
2.10.2
2.11
2.12
2.13

VMEbus Master Functionality ......... 0... 000. eee ee eae
VMEbus Slave Functionality ...... 0... 0.0... 0c cc eee ee
VSB Master Functionality ...... 2.0... 0... ccc ee eee
VMEbus Arbiter Functionality... ...... 0.0.0.0... 00 cee eee
VSB Arbiter Functionality ..... 2.0.0.0... 0... cc ee ees
VMEbus Deadlock ......... 0... 0 ee eee
VMEbus Utility Bus Signals ......... 0.2... 0... cc ee eee
DAL Bus Timeouts...... 2.0.0.0... ccc ee ee ees
Parity Errors ...... 0.0.0.0. ccc ee eee eee eee

VMEbus Interrupt Handler Functionality ..................
Handling Vectored Interrupts ............. 00.00 eee
Handling Autovectored Interrupts .................00005
VMEbus Interrupt Requester Functionality.................
VSB Interrupt Handler Functionality .....................
KAV30 Interrupt Priority........ 0... 00. c cee eee ee ees

2-1
2-2
2-3
2-3
2-4
2-4
2-4
2-5

2-6

2-6
2-6
2-8
2-10
2-12
2-12

KAV30 Kernel
3.1
3.1.1
3.1.2
3.2
3.3
3.4
3.5
3.6
3.6.1
3.6.2
3.6.3
3./
3.8

Asynchronous System Trap Processing ..............022005
AST Delivery ........ 0... ccc ee eee eee eee

AST Data Structures ..... 0.0.0... 0. eee ee eee

Timers ......

Calendar/clock
FIFO Buffers .

Battery Backed-Up RAM .......... 0... 0. cee ce ee es
Scatter-Gather Map... ..... 0... ccc cee ee eee ees
Outgoing SGM... ee ee ens
Incoming SGM... 1... eens
Byte Swapping During SGM Operations ................
Communicating with Another KAV30 ...............220005

KAV30 Error Logging Support ............ 2.0000 eee eee eae

3-1
3-2
3-3
3-5
3-6
3-9
3-10
3-10
3-10
3-14
3-18
3-21
3-24

4 KAV30 System Services
KAV$BUS_BITCLR .......... 0. ccc eee eens
KAV$BUS_BITSET ........0. 0... ccc ccc eens
KAV$BUS_READ ......... 0... c cece cee eens
KAV$BUS_WRITE ......... 0... cece cect eee eens
KAV$CHECK_BATTERY ......... 0.0... cece eee eee ees
KAV$CLR_AST
KAV$DEF_AST
KAV$FIFO_READ ......... 0... cece eee eens
KAV$FIFO_WRITH 2... ce ee eee
KAV$GATHER_KAV_ERRORLOG.............. 200000 e eee
KAV$IN_MAP
KAV$INT_VME
KAV$LIFO_WRITH 2. ee ee ee eee
KAV$NOTIFY_FIFO 2.0.0.0... cece eee ees
KAV$OUT_MAP.......... 0.0 ccc cee ce eee een ees
KAV$QUE_AST .. 0... cece eee eee ees
KAV$RTC....
KAV$RW_BBRAM ............ 0. cece cece eect eee eens
KAV$SET_AST
KAV$SET_CLO CK. tne eee
KAV$TIMERS
KAV$UNMAP

4-2
410
4-16
4-23
4-30
4-34
4-37
4-41
4-46
4-51
4-58
4-67
4-74
4-78
4-84
4-96
4100
4-116
4-122
4-127
4-131
4-144

KAV$VME_SETUP ........... 0.00.0 cece eee eee eee eens

5 Developing KAV30 Applications
5.1
Design Guidelines ....... 0... 0... eee eee
5.1.1
Accessing the VMEbus and VSB Address Space ..........
9.1.1.1
Directly Accessing the VMEbus and VSB Address
No)0
9.1.1.2
Using the KAV$BUS_READ and KAV$BUS_WRITE
SeYVICES 2... ee ee ee eee eens
9.1.2
Writing Asynchronous System Trap Routines ............
9.2
Coding Guidelines ........ 0... 0. ccc eee ee eens
9.2.1
VAX Ada 1... ccc ee eee eens
9.2.1.1
Coding Asynchronous System Trap Routines in
VAX Ada ...... ccc ee eee eens
5.2.2
VAX CLL ee ee eee eee eens
VAX FORTRAN ......... 0... cc eee eens
5.2.3
9.2.4
VAXELN Pascal... .. 0... ce ee eee
9.2.4.1
Coding AST Routines in VAXELN Pascal ............
Compiling and Linking KAV30 Applications ................
9.3
9.4
Building KAV30 System Images............... 0.000002
5.4.1
Configuring the VMEbus and VSB..................0.5.
Loading and Running KAV380 System Images ...............
9.5
Debugging KAV30 Applications ............ 0.0.00 cc eee eee
9.6
3./
Developing SCSI Class Drivers ............ 0.0.00. c cee eeee
9.8
Building a SCSI Class Driver into an Application ............

9-2

5-3
5-3
5-3
5-4
o—4
o—/
3-8
3-9
9-9
9-12
9-13
5-14
9-20
9-20
9-22
9-23

A Initial KAV30 Configuration
A.1
A.2

Hardware Configuration ......... 0.0.0.0 cece eee eee ee ees
Software SettingS..... 0... . 0c ccc ee ee ee eee nee

A-1
A-2

B Example Programs—linterprocessor Communication
B.1
B.2

FIFO Producer ............... 0c cc eee eee eee teen eee eas
FIFO Consumer ............... ccc cece ee eee ee ee ee ene es

B-1
B-5

C Example Programs—MVME335 Device Driver
C.1
C.2

Device Driver... .. 2.0.0... 0c cc ee eee ee ees
Interrupt Service Routine ......... 0... 0c eee ee ees

C-1
C-16

D Example Programs—VDAD DeviceDriver
D.1

Device Driver... 0... 0.0... ccc ee eee eens

D.3

Test Program .. 0.0... . 0. ccc ee ee en eee eens

D-21

Host and Run-Time System Software ................5.
Converting VMEbus Interrupt Vectors into VAX Interrupt

1-3

D.2
D.4
D.5

Definitions File ... 0... 0.0... ee eee ees

Build File... . 0... ee ee eens
Data File 2... eee eee eens

D-1

D—17

D-—25
D-—25

Glossary
Index
Figures
1—1
2-1

VectOrs 2. ee een eee eee eee eens

2—/

2-2

Constructing an 8-bit VMEbus Interrupt Vector ..........

2-11

3-1

ASB Fields 2... 20... ee eens

3-4

3-2

AST Queue... ... ce eee ee eee ee

3-4

3-3
3-4

Calendar/clock Address Map ............... 000 ee euee
KAV30 as Producer and Consumer .................04-

3-8
3-11

3-5

KAV30 as Neither Producer or Consumer ...............

3-12

3-6

3-9
3-10
3-11
3-12

Outgoing SGM Conversion to VMEbus or VSB A32
Addresses... 0.0... cc ccc ee ee eee eee eee eee
Outgoing SGM Conversion to VMEbus or VSB A24
AddYeSSES .. 1... ee eee eee eee eee
Outgoing SGM Conversion to VMEbus or VSB A16
Addresses... 0... cc ee en ee eee eee eens
A32 Incoming VMEbus Address............... 000000 ee
A24 Incoming VMEbus Address................000005%
Incoming SGM Conversion of A832 VMEbus Addresses .....
Incoming SGM Conversion of A24 VMEbus Addresses .....

3-15
3-16
3-17
3-17
3-18

3-13

Little-Endian Storage Format .............. 2.0000 eae

3-19

3-7
3-8

3-13
3-14

3-14
3-15
3-16
3-17
3-18
3-19
4—1
5-1
5-2
5-3

Big-Endian Storage Format ............ 0.000 c ee eee eeee
Mode 0 Byte Swapping. ........ 0.00... ce eee eee eee
Mode 2 Byte Swapping.......... 0... ccc eee ee ees

Mode 3 Byte Swapping... .. 2.2.2... 0. cee ee eee eens
Sample Master Error Log Entry ...................000.

Sample Slave Error Log Entry.................02 0000
Programming the Real-Time Clock ................ le
A Remote Debugging Configuration.................00.4
A Local Debugging Configuration..................0000Sample Add Device Description Menu ..................

Tables

1-1
2-1
2-2
2-3
2-4
2-5
2-6
3-1
3-2
51

KAV30 System Services ....... 0.0.00: eee eens
Interrupt Source Codes .......... 2... cc eee eee tees
System Control Block Layout.....................00005
SCB Vector Offsets for Autovectored ISRs ...............
VMEbus Address Lines A<8..1>.........00 0.0.0.0. 08 ee
KAV30 Interrupt Pins ........... 0... 0... eee eee eee

KAV30 Interrupt Priorities ............ 00. cee eee eee
Internal Master Error Code.............. 0.0000 e eee
Internal Slave Error Code ............. 0.000 cee eee eee

2-10
2-11
2-13
2-14
3-27
3-28
9-12

vil

Preface
This guide describes the KAV30 software and describes how to develop realtime applications for the KAV30.

Who Should Read This Guide
This guide is for programmers who want to develop real-time applications
for the KAV30. This guide assumes that the reader is familiar with the

VAXELN™ Toolkit and that the reader can program in oneof the following
computer languages:

VAX Ada™

VAX C™

VAX FORTRAN™

VAXELN Pascal™

Structure of This Guide
This guide is divided into five chapters, four appendixes, a glossary, and an
index:
e

Chapter 1 gives an overview of the KAV30 hardware and software.

Chapter 2 describes the KAV30 bus functionality and related topics.

Chapter 3 describes how the KAV30 hardwarerelates to the KAV30
software.

Chapter 4 describes the KAV30 system services.

Chapter 5 describes how to develop applications for the KAV30.

Appendix A describes the initial KAV30 hardware and software
configuration.

Appendix B lists source code which demonstrates interprocessor
communication between two KAV30s.

Appendix C lists source code which implements an MVME 335 device
driver.
Appendix D lists source code which implements a VDAD device driver.
The glossary defines some important terms used in this guide.

Associated Documents
For more information, see the following documents:

KAV30 Software Cover Letter (AV-PEYFA-TE)
KAV30 Software Product Description (AE-PFB5A-TE)
KAV30 System Support Addendum (AE-PFB6A-TE)
KAV30 Software Installation and System Testing Information
(AA-PEYAA-TE)
KAV30 Hardware Cover Letter (AV-PFSSA-TE)
KAV30 Hardware Installation and User’s Information (AA-PFM6A-TE)

Related Documents
For additional information, see the following documents:
VMEbusSpecification, Revision C.1 (PRINTEX, Phoenix, AZ, USA)
The VME Subsystem Bus (VSB) Specification, Revision B.1 (Motorola®,
Phoenix, AZ, USA)

rtVAX 300 Hardware User’s Guide
rtVAX 300 Programmer’s Guide
Introduction to VAXELN
VAXELN rtVAX 300 Supplement
VAXELN Ada User’s Guide
VAXELN Application Design Guide
VAXELN C Runtime Library Reference Manual
VAXELN C Reference Manual

VAXELN Development Utilities Guide
VAXELN FORTRAN Runtime Library Reference Manual
VAXELN Guide to DECwindows

VAXELN Installation Guide

VAXELN Internals Manual
VAXELN Master Index and Glossary

VAXELN Messages Manual
VAXELN Pascal Language Reference Manual

VAXELN Pascal Runtime Library Reference Manual
VAXELN Pocket Reference

VAXELWNRelease Notes
VAXELN Runtime Facilities Guide
For detailed information about VAXELN,Digital Equipment Corporation
recommends the VAXELN Internals and Data Structures manual. The
VAXELN Internals and Data Structures manual describes the internal
data structures and operations of the VAXELN Kernel andits associated
subsystems.
For information about the VAX architecture, Digital recommends the following
documents:
Henry M. Levy and Richard H. Eckhouse, Jr., Computer Programming
and Architecture: The VAX, Second Edition, Bedford, (Massachusetts): The

Digital Press, 1989

Timothy E. Leonard, editor, The VAX Architecture Reference Manual,

Bedford (Massachusetts): The Digital Press, 1987

Conventions
The following conventions are used in this guide:
Convention

Description

Note

A note contains information that is of special
importance to the reader.

Convention

Description

UPPERCASE

Words in uppercase indicate the following:
e

VMS™reserved words and identifiers

VAXELNreserved words and identifiers

KAV30 reserved words and identifiers

VAX signal lines

VMEbussignallines

italic type

Italic type emphasizes important information and
indicates the complete titles of manuals.

boldface type

Boldface type indicates the first occurrence of terms

Monospace Type

Monospace type indicates system displays and user
input.

[]

In system service format descriptions, brackets
enclose optional system service arguments.

defined either in text, in the glossary, or both.

Brackets are also used in the syntax of a directory
name in a VMSfile specification.
Horizontal ellipsis points indicate that you repeat
the preceding item one or more times.
Vertical ellipsis points in a figure or example
indicate that not all the information the system
displays is shown.
nnn

A period in numerals signals the decimal point
indicator. For example, 1.75 equals one and threefourths.

mnnnn.nnn nn

A space character separates groups of 3 digits in
numerals with 5 or more digits. For example, 10
000 equals ten thousand.

<n..n>

Three or more consecutive signal line numbers
are enclosed in angle brackets, with the first line
number separated from the last line number with
two periods(..). For example, signal lines </..4>
represent signal lines 7, 2, 3, and 4.

xii

KAV30 Overview
This chapter gives an overview of the KAV30 hardware and software. It briefly
describes the following:
e

KAV30 hardware

VAXELN Toolkit

KAV380 software

The KAV30 software and hardware operate in a host and target system
environment. You use the KAV30 software to develop and build VAXELN
applications on a VMS(host) system. Then, you down-line load, run, and

debug the applications on the KAV30 (target) system. The KAV30 is a
single-board computer that allows VAXELN applications to interface with

VMEbus and VME subsystem bus (VSB) devices.

The KAV30 software is a VMSlayered product that forms an extension to
the VAXELN Toolkit. The VAXELN Toolkit is a set of developmenttools that
allows you to develop real-time applications quickly and easily for the VAX™
family of computers.

1.1 KAV30 Hardware
This section describes the KAV30 hardware. The KAV30is a single-board
computer that allows VAXELN applications to interface with VMEbus and VSB
devices. The KAV30 contains the following hardware:
e

An rtVAX™ 300 real-time processor, which includes a CVAX™

microprocessor, a floating point coprocessor, and a second-generation

Ethernet controller
e

Logic circuitry that implements a scatter-gather map (SGM)

4M or 16M bytes of system random-access memory (RAM)

Up to 1M bytes of user read-only memory (ROM)

Four 255-longwordfirst-in/first-out (FIFO) buffers

KAV30 Overview

1-1

Introduction

32K bytes of battery backed-up RAM (programmers can access 22K bytes)

A calendar/clock

Counter/timers

A second-generation small computer systems interface (SCSI) controller

Twoserial line ports: the console port and the auxiliary port

A watchdog timer

Logic circuitry that implements VMEbus arbiter and bus request
functionality

Logic circuitry that implements VSB arbiter and bus request functionality

e
e

Logic circuitry that implements VMEbus interrupt request and handler

functionality

Logic circuitry that implements VSB interrupt request and handler

functionality

1.2 VAXELNToolkit
This section describes the VAXELN Toolkit. The VAXELN Toolkit is a set of
developmenttools that allows you to develop real-time applications quickly and
easily for the VAX family of computers. The VAXELN Toolkit consists of the
following:
e

VAXELN Host System Software, which consists of the following:
—

1—2

High-level language compiler (supported languages are VAXELN Ada,

VAX C, VAX FORTRAN, and VAXELN Pascal)

—

Object module libraries

—

System Builder

—

Debugger

VAXELN Run-Time System Software, which consists of the following:
—

VAXELNkernel

—

Run-time libraries

—

Network andfile services

—

Device drivers

—-

VAXELN DECwindows™client functionality

KAV30 Overview

Introduction

Error-logging support
e

VAXELN Utilities, which consist of the following:

VAXELN Performance Utility (EPA)
VAXELN Display Utility (EDISPLAY)
VAXELN Command Language Utility (ECL)
Local Area Transport (LAT) Control Program (LATCP)
Outbound remote terminal utility (SET_HOST)
Figure 1—1 shows how the components of the VAXELN Toolkit are distributed
between the host and target systems. The figure also shows the host and
target connected by an Ethernet.
Figure 1-1

Host and Run-Time System Software

VMS Host

VAXELNTarget

Host System Software
— VAXELN PASCAL Compiler
— VAXELNLibraries
— VAXELN System Builder
~ VAXELN Debugger

Run-Time System Software
— Kernel
— Run-Time Libraries
— Device Drivers
— Network Drivers

— VAXELNUtilities

— VMSUtilities, Editors, CMS, MMS
— DECwindowsLibraries

— File Service

~ Error Logging Service
— VAXELNUtilities
— DECwindows Server

Other
Targets
Ethernet

KAV30 Overview

1-3

Introduction

See the Introduction to VAXELN for information on the VAXELN Toolkit. For

more detailed information, see the VAXELN Development Utilities Guide and
the VAXELN Runtime Facilities Guide.

1.3 KAV30 Software
This section describes the KAV30 software. The KAV30 software is a VMS
layered product that forms an extension to the VAXELN Toolkit. It simplifies
the development of VAXELN applications that use the KAV30. The KAV30
software consists of the following:
e

The KAV30 kernel

ASCSI port driver

Automated initialization of the KAV30

You can specify initialization parameters when you build the VAXELN
system.

Sample applications, including a device driver for a VMEbus device

The KAV30 system exerciser

The KAV30 kernel is a VAXELN kernel image that is designed specifically for
the KAV30. It has the following features:

System services that you can use to set up and control the KAV30

Asynchronous notification of events by means of asynchronous system traps
(ASTs) for KAV30 kernel services and user-written device drivers

Error logging to battery backed-up RAM

VMEbus and VSB exception handling

1.3.1 Naming Conventions
The KAV30 software conforms to the naming conventions set out in the Guide
to Creating VMS Modular Procedures. The namesare derived from thefacility
prefix. Thefacility prefix for the KAV30 software is KAV$. All the KAV30
software names (such as system services, global variables, and status codes)
begin with KAV$.
Note

Because the dollar sign ($) is not part of the VAX Ada characterset,
KAV30 kernel services in VAX Ada have the facility prefix KAV_
instead of KAV$.

1-4

KAV30 Overview

Introduction

1.3.2 KAV30 System Services
The KAV30 system services allow you to do the following tasks:
e

Initialize the KAV30

Set up and control access to the devices on the VMEbus and VSB

Set up and control the KAV30 FIFO buffers

Set up and control the calendar/clock and counter/timers

Exchange data with VMEbus and VSB devices

Read and write the battery backed-up RAM on the KAV30

Gather error information from the battery backed-up RAM

Use ASTs in user-written device drivers

Table 1-1 summarizes the KAV30 system services. See Chapter 4 for more
detailed information on each system service.
Table 1-1

KAV30 System Services

System Service

Description

KAV$BUS_BITCLR

Clears the bits at a VMEbus or VSB address

KAV$BUS_BITSET

Sets the bits at a VMEbus or VSB address

KAV$BUS_READ

Reads the contents of a VMEbus or VSB address

KAV$BUS_WRITE

Writes data to a VMEbus or VSB address

KAV$CHECK_BATTERY

Checks the power supply to the battery backedup RAM andthe calendar/clock

KAV$CLR_AST

Clears a device’s AST queue

KAV$DEF_AST

Creates an asynchronous system block (ASB) for
an event on a VMEbusor VSB device

KAV$FIFO_READ

Reads data from a KAV30 FIFO buffer

KAV$FIFO_WRITE

Writes data to a KAV30 FIFO buffer

KAV$GATHER_KAV_ERRORLOG

Reads error log information from the KAV30
battery backed-up RAM

KAV$IN_MAP

Maps a 64K byte page of VMEbus address space
to the KAV30 process address space
(continued on next page)

KAV30 Overview

1—5

Introduction

Table 1—1 (Cont.) KAV30 System Services
System Service

Description

KAV$INT_VME

Generates vectored VMEbusinterrupts

KAV$LIFO_WRITE

Writes data to a KAV30 last-in/first-out (LIFO)
buffer

KAV$NOTIFY_FIFO

Delivers an AST when a specified event occurs
in a KAV30 FIFO buffer

KAV$OUT_MAP

Maps KAV30 system I/O space to the VMEbus
or VSB address space, in 64K byte pages

KAV$QUE_AST

Queues an AST for delivery to a process

KAV$RTC

Performs real-time clock functions, using the
KAV30 calendar/clock

KAV$RW_BBRAM

Reads or writes the KAV30 battery backed-up
RAM

KAV$SET_AST

Places an entry in a device’s AST queue

KAV$SET_CLOCK

Sets the KAV30 system clock and the calendar
/clock

KAV$TIMERS

1-6

Sets a counter/timer and delivers an AST when

the timer interval expires

KAV$UNMAP

Unmaps VMEbus address space from KAV30
system RAM, or KAV30 system RAM from the
VMEbusaddress space

KAV$VME_SETUP

Configures the VMEbus and VSBinterrupt
delivery mechanism

KAV30 Overview

KAV30 Functionality
This chapter describes the KAV30 bus functionality and related topics. It gives
information on the following:
VMEbus master functionality
VMEbusslave functionality

VSB master functionality
VMEbusarbiter functionality
VSBarbiter functionality
VMEbus deadlock
VMEbusutility bus signals
Data and address lines (DAL) bus timeouts
Parity errors

VMEbusinterrupt handler functionality
VMEbusinterrupt requester functionality
VSB interrupt handler functionality
KAV30 interrupt priority

2.1 VMEbus Master Functionality
This section describes the KAV30 VMEbus master functionality. The KAV30
includes logic circuitry that implements VMEbus master functionality. That is,
the KAV30 can start read/write operations between itself and other devices on
the VMEbus. To start read/write operations on the VMEbus, the KAV30 must
first get control of the VMEbus. To do this, the KAV30 can use any one of the
four VMEbusbus request (BR) lines. When it has control of the VMEbus, the
KAV30 VMEbus masterlogic circuitry can perform the following transfers:
VMEbus Al6, A24, and A32 data transfers
KAV30 Functionality 2-1

KAV30 Functionality

Read-modify-write transfers

See The VMEbus Specification for more information about VMEbus data
transfers.
The KAV30 VMEbus masterlogic circuitry can operate in the following modes:

Release-when-done (RWD) or release-on-request (ROR)

Fair or not fair

Hidden or not hidden
Note

The KAV30 can operate in hidden mode only when the other masters
on the VMEbus system operate in hidden mode.

The KAV30, by default, issues bus requests to the VMEbus, using BR line 3
while operating in the ROR,not fair, and not hidden modes. See The VMEbus

Specification for more information about the VMEbus master operation modes.

2.2 VMEbus Slave Functionality
This section describes the KAV30 VMEbusslave functionality. The KAV30
includes logic circuitry that implements the VMEbusslave functionality.

That is, another master module on the VMEbus system can start read/write

operations between itself and the KAV30. The KAV30 VMEbusslave logic
circuitry can access the following devices on the KAV30:
e

System RAM

FIFO buffers

VMEbusreset register

The KAV30 VMEbusslavelogic circuitry can process the following transfers:
e

VMEbus Al16, A24, and A832 data transfers

VMEbus D08, D16, D32, and block mode data transfers

Read-modify-write transfers

See The VMEbus Specification for more information about VMEbus data
transfers.

2-2

KAV30 Functionality

The VMEbusslave logic circuitry requests control of the DAL bus whenit
wants to respond to a VMEbuscycle. The KAV30 central processing unit
(CPU), when appropriate, indicates that the VMEbusslave logic circuitry can
use the DAL bus. When the VMEbusslave logic circuitry finishes using the
bus it signals the KAV30 CPU and returnscontrol of the bus to the CPU.
However, when the KAV30 wants to perform a read-modify-write cycle, the

VMEbusslave data interface logic circuitry does not return control of the DAL

bus until it completes the read and write cycles.
Note

The devices that transfer data into the KAV30 by direct memory access
(DMA) can use a block size of up to 4 longwords.
If a VMEbus device uses a block size that is greater than 4 longwords, a bus

timeout occurs on the VMEbusdevice.

2.3 VSB Master Functionality
This section describes the KAV30 VSB master functionality. The KAV30
includes logic circuitry that implements VSB master functionality. That is,
the KAV30 can start read/write operations between itself and other devices on
the VSB. The KAV30 supports VSB ALTERNATE, SYSTEM,and I/O address

spaces. See the VME Subsystem Bus (VSB) Specification for more information

about the VSB address spaces.

Note

The VSB masterlogic circuitry does not assert the VSB LOCKsignal
when the KAV30 CPU performs a read-modify-write cycle.

2.4 VMEbus Arbiter Functionality
This section describes the KAV30 VMEbusarbiter functionality. The KAV30
includeslogic circuitry that implements VMEbusarbiter functionality. The
KAV30 can perform prioritized or round-robin arbitration, using the four
VMEbusbus request and bus grant levels. Use the VMEbus arbiter switch to
enable the VMEbusarbiter functionality. Use the VAXELN System Builder
to configure the VMEbusarbiter functionality. See the KAV30 Hardware

Installation and User Information for more information about the VMEbus

KAV30 Functionality 2-3

KAV30 Functionality
arbiter switch. See Section 5.4.1 for more information about configuring the
VMEbusarbiter functionality.
Only one VMEbusarbiter can be on a VMEbussystem, and that arbiter must
reside in the leftmost slot of the VMEbussystem (slot 1). When you use the
KAV30 as a VMEbusarbiter, the KAV30 can also provide the VMEbus system
clock and logic circuitry to drive the VMEbus SYSRESEHTsignal.

2.5 VSB Arbiter Functionality
This section describes the KAV30 VSB arbiter functionality. The KAV30
includes logic circuitry that implements VSB arbiter functionality. You can
use software to enable and configure the VSB arbiter functionality (see
Section 5.4.1 for more information).

Only one VSB arbiter can be on a VSB system, and that arbiter must reside in
the leftmost slot of the VSB system (slot 0).

2.6 VMEbus Deadlock
This section describes how the KAV30 deals with VMEbus deadlock. A
deadlock can occur on the KAV30 when the KAV30 VMEbusslave logic
circuitry requests control of the DAL bus at the same time as the KAV30
CPU requests control of the VMEbus. In such a case, the VMEbusslave logic
circuitry is using the VMEbus and is requesting ownership of the DAL bus,
while the KAV30 CPUis using the DAL bus andis requesting ownership of the
VMEbus.
Such deadlocks are handled by the hardware. Whenthis deadlock situation

occurs, the KAV30 postpones the KAV30 CPU’s request for the VMEbus and
allows the VMEbusslave logic circuitry to own the DAL bus. When the
VMEbusslave logic circuitry returns control of the DAL bus, the postponed
CPU request for the VMEbus is resumed.

2./ VMEbusUtility Bus Signals
This section describes the KAV30 VMEbusutility bus signals. The KAV30 uses
the following VMEbusutility bus signals:
e

SYSRESET
Whenenabled, the SYSRESETsignal can generate a local reset pulse on
the KAV30 with the same duration as the SYSRESETsignal. This pulse
allows the system to initialize the KAV30 at the same timeas the other
modules on the VMEbussystem.

2-4 KAV30 Functionality

KAV30 Functionality

The VMEbus SYSRESETsignal jumper controls the interaction between
the KAV30 and the SYSRESETsignal. See the KAV30 Hardware

Installation and User’s Information for more information about the

VMEbus SYSRESETsignal jumper.

VMEbus Global Reset Register
A VMEbuswrite access via the SGM to the VMEbusglobal reset register
causes a 10 microsecond (ys) local reset pulse.

ACFAIL

The KAV80 interrupts its CPU at interrupt priority level 1K when the

VMEbus ACFAILsignal is asserted.
e

SYSFAIL
The KAV30 VMEbus master interface logic circuitry can assert the
SYSFAIL signal and respond to assertions of the SYSFAIL signal.
When the KAV30 detects an assertion of the SYSFAIL signal, it performs
one of the following actions:
-

The KAV30 delivers an AST

To deliver an AST,call the KAV$SET_ASTroutine with the KAV$K_
VME_SYSFAIL device code and AST routine address as arguments.
-

The KAV30calls an interruptservice routine (ISR) at vector 5401.

The KAV30 performs one of these two actions. The KAV30 cannot ignore
the assertion of the SYSFAIL signal. The action that the KAV30 performs
depends on the setting of the VAXELN System Builder System Parameter
1. See Section 5.4.1 for more information.
See The VMEbus Specification for more information about the VMEbusutility
signals.

2.8 DAL Bus Timeouts
This section describes DAL bus timeouts. The KAV30 CPU, SCSI controller,

and master logic circuitry can act as DAL bus masters. The DAL bus
generates an error when it times out. The default DAL bus timeout period
is approximately 20 us. You can use the KAV$TIMERSservice to change the
DAL bus timeout period. However, Digital™ strongly recommends that you do
not changethis value.

KAV30 Functionality 2-5

KAV30 Functionality

2.9 Parity Errors
This section describes parity errors. When the KAV30 CPUstores data in its

system RAM,it sends one parity bit with each byte of data. It sends an even
parity bit when a byte has an even address, and an odd parity bit when a byte
has an odd address. When the CPU reads a byte of system RAM,it checks the
parity bit.

2.10 VMEbusInterrupt Handler Functionality
This section describes the KAV30 VMEbusinterrupt handler functionality. The
KAV30 includes logic circuitry that implements VMEbus interrupt handler
functionality. The VMEbus interrupt handlerlogic circuitry can handle
interrupt-requests (IRQs) that it receives from the devices on the VMEbus.
The KAV30 VMEbusinterrupt handler logic circuitry can receive IRQs on the
VMEbuslines IRQ<1..7> and the POWER_FAIL line. When it receives more

than one IRQ, the interrupt handler logic circuitry assigns priorities to the
requests depending on the line on which it receives the requests. It handles
requests in the order of the highest priority to the lowest priority. The IRQs on

the POWER_FAILline have the highest priority. The IRQs on the IRQ7 line
have the next highest priority, and so on to the IRQs on the IRQ1 line, which

have the lowest priority.

VMEbus autovectored interrupts occur when a module asserts a VMEbus IRQ
line but does not provide an interrupt vector. Often VMEbus systems use
the VMEbus IRQ 2 line for autovectored interrupts. The KAV30 hardware
can handle only autovectored interrupts on the VMEbus IRQ7 line. However,
an application program can emulate a vectored VMEbus IRQ 7 interrupt by
forcing a VMEbusinterrupt-acknowledge (IACK)cycle from the software.
Note
Do not use VMEbus IRQ lines for vectored and autovectored interrupts.

2.10.1 Handling Vectored Interrupts
The KAV30 receives 8-bit interrupt vectors from the VMEbus. However, the
KAV30 CPU expects 16-bit interrupt vectors. Therefore, the KAV30 interrupt
handler logic circuitry must convert the 8-bit interrupt vectors it receives into
16-bit interrupt vectors that the KAV30 CPU can process. Figure 2—1 shows

this conversion.

2-6

KAV30 Functionality

The VAX interrupt vector consists of the following data:
e

Bits <0,1> and <12..15> contain the value 0

Bits <2..9> contain the 8-bit VMEbus interrupt vector

Bits <10,11> contain the interrupt source code (see Table 2—1)

Figure 2-1 Converting VMEbusInterrupt Vectors into VAX Interrupt Vectors
7

VMEbusInterrupt Vector
6
5
4
3
2

Interrupt

Source
Code

VAX Interrupt Vector

Table 2—1 describes the interrupt source codes. The KAV30 CPU uses these
interrupt source codes to determine the source of an interrupt.
Table 2-1

Interrupt Source Codes

Bit 11

Bit 10

Type of Interrupt

UART interrupts

Local interrupts (including VMEbus and VSB autovectored
interrupts)
(continued on next page)

KAV30 Functionality 2-7

KAV30 Functionality

Table 2—1 (Cont.) Interrupt Source Codes
Bit 11

Bit 10

Type of Interrupt

VMEbusvectored interrupts

Not used

The KAV30 CPU usesbits <2..15> of the VAX interrupt vector as a pointer
to a longword in the system control block (SCB). This longword contains the
address of the interrupt service routine for that interrupt. Table 2—2 describes
the layout of the SCB.
Table 2-2 System Control Block Layout
Address Range

Contents

0000ig to O3FCi¢

Interrupt vectors for various system exceptions and software
interrupts such as powerfailure, access violation, and so on

0400:g to O7FCig

KAV30 interrupt vectors

08001g to OBFCig

VMEbusinterrupt vectors for vectored VMEbus interrupts

OC00i¢ to FFFCig

Not Used

The low-order two bits of each SCB vector determine the stack on which the
interrupt is to be serviced. For all the KAV30, VMEbus, and VSB interrupts
these two bits have the value 1, which means that the processor services the
interrupts on the interrupt stack. The remaining bits contain the address of
the ISR.

2.10.2 Handling Autovectored Interrupts
The KAV80 can handle autovectored interrupts on any of the seven VMEbus
IRQ<1..7> lines. However, the KAV30 hardware can take longer to handle

autovectored interrupts that it receives on VMEbus IRQ lines1, 2, or 3. Using

VMEbus IRQ lines 1, 2, or 3 for autovectored interrupts can take 20 ps longer,
before the appropriate ISR executes, and 40 ps longer, after the ISR executes.
When another VMEbus module generates an autovectored interrupt on one of
the VMEbusIRQ lines, the KAV30 hardware performs the following actions:

2-8

It interrupts the CPU.

The CPU requests an interrupt vector.

KAV30 Functionality

If the IRQ is on the VMEbusIRQ lines 1, 2, or 3, the KAV30 hardware

sometimes performsthe following actions:
a.

Generates a VMEbus IACKcycle.
Because the interrupting module is generating an autovectored
interrupt, it does not respond with an interrupt vector. The cycle
times out after approximately 20 ns.

The KAV30 hardware asserts the VAX ERRsignal, which causes the
CPUto start executing a passive release ISR.

Because the other VMEbus modulestill asserts the VMEbus IRQ line,
the CPU again requests an interrupt vector. This request interrupts

the process of starting the passive release ISR.
3.

The KAV30 hardware returns an interrupt vector that was previously
programmed into the hardware by the KAV30 kernel.

The CPU starts executing the appropriate ISR. The CPU uses the interrupt
vector to determine which ISR it executes.

The ISR accesses the other VMEbus module and causesit to stop asserting

the VMEbus IRQ line.

The CPU finishes executing the ISR.

When the KAV30 hardware performs steps A to D, it now causes the
CPU to resume executing the passive release ISR. The passive release
ISR writes an error log entry and finishes executing. This process takes
approximately 40 us.

Because autovectored interrupts received on the VMEbus IRQ lines 1, 2, and 3

can take 60 ps longer to process by the KAV30 hardware, Digital recommends

that you use the VMEbusIRQ lines 4, 5, 6, and 7 only for autovectored
interrupts.

When autovectored interrupts occur, the KAV30 hardware gives the interrupt
vector to the CPU. The KAV30 hardware was programmed by the KAV30
kernel with the vectors that the kernel gives in response to autovectored IRQs.
Table 2—3 lists these vectors. This table describes the condition that causes the
interrupt and gives its offset (in hexadecimal) into the SCB.

KAV30 Functionality 2-9

KAV30 Functionality

Table 2-3 SCB Vector Offsets for Autovectored ISRs
Description

Offset into SCB

Autovectored VMEbus IRQ1

50016

Autovectored VMEbus IRQ2

50416

Autovectored VMEbus IRQ3

508i¢

Autovectored VMEbus IRQ4

50Cig

Autovectored VMEbus IRQ5

51016

Autovectored VMEbus IRQ6

51416

Autovectored VMEbus [RQ7

51816

Autovectored VSB IRQ

54Ci¢

Note
The SCB also contains vectors for SCSI IRQs and the VMEbus

SYSFAIL signal. The vector for SCSI IRQsis at an offset of 550 ¢.
The vector for SCSI ERR interruptsis at an offset of 554g. The vector
for the VMEbus SYSFAILsignalis at an offset of 5401¢.
See The VMEbus Specification for more information on VMEbusinterrupt

handler functionality.

2.11 VMEbus Interrupt Requester Functionality
This section describes the KAV30 VMEbusinterrupt requester functionality.
The KAV30 includes logic circuitry that implements VMEbusinterrupt

requester functionality. The VMEbusinterrupt requester logic circuitry can
generate vectored IRQs, which any module on the VMEbus,including the
KAV30 VMEbusinterrupt handler logic circuitry, can handle.

The KAV30 VMEbusinterrupt requester logic circuitry can request interrupts,
using VMEbus lines IRQ<1..7>. It places IRQs on these VMEbus IRQ lines

according to the priority of the IRQ. The KAV30 VMEbusinterrupt requester

logic circuitry asserts an IRQ line until an interrupt handler acknowledges

the request. When an interrupt handler acknowledges the request, the KAV30
stops asserting the IRQ lines and sends an interrupt vector to the interrupt
handler.
When the KAV30 requests an interrupt it generates an 8-bit interrupt vector,

which it places on the VMEbus. Figure 2—2 shows how the KAV30 CPU
constructs the 8-bit VMEbusinterrupt vector.
2-10

KAV30 Functionality

The VMEbusinterrupt vector consists of the following data:
e

Bits <2..0> contain VMEbus address lines A<3..1> respectively. These

Bits <7..3> contain bits <8..4> of the interrupt vector that the user provides

address lines represent the IRQ level being acknowledged. Table 2—4
explains the contents of these threebits.

Figure 2-2 Constructing an 8-bit VMEbusInterrupt Vector

UserInterrupt Vector

a,
—

A<3> A<2> A<1>

kit |
4

VMEbusInterrupt
Vector

See The VMEbus Specification for more information on VMEbusinterrupt
requester functionality.
Table 2—4 VMEbus AddressLines A<3..1>
Bit 3

Bit 2

Bit1

VMEbusIRQ line

Not used

IRQ1

IRQ2

IRQ3
(continued on next page)

KAV30 Functionality 2-11

KAV30 Functionality

Table 2—4 (Cont.) VMEbus Address Lines A<3..1>
Bit 3

Bit 2

Bit1

VMEbus IRQline

1
1
1
1

0
0
1
1

0
1
0
1

IRQ4
IRQ5
IRQ6
IRQ7

2.12 VSB Interrupt Handler Functionality
This section describes the KAV30 VSB interrupt handler functionality. The
KAV30 includes logic circuitry that implements VSB interrupt handler
functionality. The VSB interrupt handler logic circuitry can handle IRQsit
receives from devices on the VSB. Although the VSB specification defines
the handling of vectored as well as autovectored interrupts, the KAV30 VSB
interrupt handler logic circuitry can handle only autovectored interrupts.
See the VME Subsystem Bus (VSB) Specification for more information on VSB
interrupt handler functionality.

2.13 KAV30 Interrupt Priority
This section describes the KAV30 interrupt priority scheme. The KAV30 CPU
receives IRQs on seven interrupt pins, as follows:

The DAL buserror pin

The VAX HALT pin

The VAX POWER_FAIL pin

The VAX IRQ pins<3..0>

The KAV30 CPU assigns interrupt priority levels (IPLs) to these pins as shown
in Table 2-5.

2-12 KAV30 Functionality

KAV30 Functionality

Table 2-5 KAV30 Interrupt Pins
Interrupt Pin

Interrupt Priority Level (Hexadecimal)

DAL bus error

1F (exception)

VAX HALT

VAX POWER_FAIL

VAX IRQ 3

VAX IRQ 2

VAX IRQ 1

VAX IRQ 0

When the KAV30 CPU receives more than one IRQ, it services the IRQs in the

order of highest priority to lowest. The IRQs on the 1F (exception) level have

the highest priority, IRQs on IPL 1F have the next highest priority, and so on

to the IRQs on IPL 14, which have the lowest priority.

The KAV30 CPUalso prioritizes interrupts within each IPL. Table 2—6
describes this priority scheme. In this table, the priority scheme is shown as
follows:
e

An en dash (—) prefixes sources that have an equal priority.

A numberprefixes sources that have an unequal priority. The magnitude
of the numberis inversely related to the priority of the source. That is, the
number1 prefixes the source with the highest priority.

KAV30 Functionality 2-13

KAV30 Functionality

Table 2-6 KAV30 Interrupt Priorities
IPL

Interrupting Condition

IPL 1F:

Occurrence of bus timeouts

Occurrence of an IPL 1F control and status register (CSR) bit
interrupting conditions, when the relevant CSR bit is configured to
cause an interrupt on IPL 1F
Issuing of the break commandfrom a device connected to the KAV30
serial line ports
Setting of the KAV30 reset/halt switch to the halt position
Receiving a trigger boot message from a device on an Ethernet network

IPL 1E:

Occurrence of an IPL 1E CSRbit interrupting conditions, when the
relevant CSR bit is configured to cause an interrupt on IPL 1E
Assertion of the VMEbus ACFAILsignal
Receiving an autovectored VMEbus IRQ on the IRQ7 line

IPL 17:

Occurrence of IPL 17 CSR bit interrupting conditions, including the
following:
—

Receiving interrupts at IPL 17

—

Occurrence of FIFO buffer 3 full and empty errors

—

Occurrence of FIFO buffer 2 full and empty errors

—

Receiving VMEbus autovectored IRQs on the IRQ5 or IRQ6 line

Receiving a vectored IRQ on the VMEbus IRQ5 and IRQ6 lines
(continued on next page)

2-14 KAV30 Functionality

KAV30 Functionality

Table 2-6 (Cont.) KAV30 Interrupt Priorities
IPL
IPL 16:

Interrupting Condition

Occurrence of rtVAX 300 INTIM 10 milliseconds (ms) timer input
Occurrence of IPL 16 CSR bit interrupting conditions, including the
following:
—

Receiving interrupts at IPL 16

—

Receiving SCSI interrupts

—

Receiving VSB interrupts

—

Receiving VMEbusautovectored IRQs on the IRQ3 or IRQ4 line

Receiving vectored IRQs on the VMEbus IRQ4 line
IPL 15:

Occurrence of Ethernet controller interrupts
Occurrence of IPL 15 CSR bit interrupting conditions, including the
following:
—

Receiving interrupts at IPL 15

—

Occurrence of FIFO buffer 1 full and empty errors

—

Occurrence of FIFO buffer 0 full and empty errors

—

Receiving of VMEbus autovectored IRQs on the IRQ1 or IRQ2 line

Receiving of vectored IRQs on the VMEbus IRQ3 line

IPL 14:

Receiving of an interrupt from the KAV30 UART
Occurrence of IPL 14 CSR bit interrupting conditions
Receiving of vectored IRQs on the VMEbus IRQ1 and IRQ2 lines

KAV30 Functionality 2-15

KAV30 Kernel
This chapter describes how the KAV30 hardware relates to the KAV30
software. It gives information on the following:
e

Asynchronous system trap processing

Timers

Calendar/clock

FIFO buffers

Battery backed-up RAM

Scatter-gather map

Communicating with another KAV30

KAV30 error logging support

3.1 Asynchronous System Trap Processing
This section describes how the KAV30 processes ASTs. In real-time systems,
a process must be able to respond to events that occur asynchronously to

the execution of the process. These events can result from actions by other
processes in the system, by peripheral devices, or by the operating system

itself. When a user program starts an event that can complete asynchronously

(for example, an analog-to-digital conversion), it can specify the address of an
AST routine. An AST routineis a procedure in the user program that the
operating system calls when a particular event occurs.

The operating system maintains a queue of ASBs for each process. Each entry

in the queue describes one requested AST and contains the address of the AST
routine to be called when a specified event occurs.
If the user process is active when the system delivers an AST, the system

interrupts the process and transfers control to the first AST routine in the

queue. Each AST routine in the queue executes in turn. Whenthe last AST
routine in the queue returns, the user process resumes where it stopped.

KAV30 Kernel

3-1

KAV30 Kernel

If the user process is inactive when the system delivers an AST, the process

wakes up for the execution of the delivered ASTs. After the last AST is
delivered the process returnsto the original state.

Whenthe programsspecify an AST routine, they can also specify an associated
argument called the AST parameter, which will be passed to the AST routine.
The KAV30 kernel queues ASTs to a process in the current access mode (user
or kernel). The kernel mode ASTs havehigher priority than the user mode
ASTs, and the KAV30 kernel places them ahead of user mode ASTsin the
queue.

3.1.1 AST Delivery
The VAXELNapplications can include device drivers for the devices on the
VMEbusor VSBthat the KAV30 interacts with.
Each device driver that uses ASTs contains initialization code that calls
the KAV$DEF_ASTservice to set up a queue called an AST queue. Each
entry in the AST queueis a data structure called an ASB. The ASB contains
information about the AST routine for a particular event relating to the
device. (The KAV$DEF_ASTservice returns a code that the KAV$CLR_AST,
KAV$SET_AST and KAV$QUE_ASTservices subsequently use to identify this
ASB.)
Each device driver that uses ASTs also includes an input/output (I/O) section,
in which the program calls the KAV$SET_ASTroutine to place data in an ASB.
See Section 3.1.2 for information about ASBs and ASB queues.
After the KAV30 starts I/O, the relevant device driver returns control to the

main program. When the device finishes performing I/O, it sends an IRQ
signal to the KAV30.

If the IRQ is a vectored IRQ, the KAV30 processor sends an IACKsignal to the
device, which then sends an interrupt vector back to the module. The KAV30
processor uses this vector to specify an offset into the SCB. At the specified
offset in the SCB, there is a longword vector that contains the address of an
ISR.
If the IRQ is an autovectored IRQ, the KAV30 processor does not acknowledge

the interrupt. Instead the KAV30 transfers control directly to the ISR whose
address is contained in a predefined SCB vector. See Section 2.10 for more
information.

Regardless of whether the IRQ is vectored or autovectored, the ISR executes at
a device IPL.

3-2

KAV30 Kernel

There are 32 interrupt priority levels, in increasing order of priority from 0 to
31. The IPLs 16 to 31 are hardware IPLs, and the IPLs 0 to 15 are software
IPLs. There are four device IPLs: IPL 20 to IPL 23. User processes execute

at IPL 0, the lowest priority level. AST delivery executes at IPL 2, and AST

routines execute at IPL 0.

The KAV30 kernel calls an ISR, which can include a call to the KAV$QUE_AST

service (any ISRs executing at a higher IPL end before this ISR completes).
The KAV30 kernel queues an AST to a process when the corresponding event
occurs.

3.1.2 AST Data Structures
Several ASTs can be outstanding for a process at any time. The KAV30 kernel
stores the ASTs in a FIFO queue. The entries in the queue are ASBs, which
contain the following fields:
e

ASB type code
This field indicates whether the ASB is pending or free. The ASB is

pendingif it contains information about an AST that the KAV30 kernel has
not yet delivered. The ASBisfree if it does not contain information about

an AST — this arises if the KAV$SET_ASTservice has not yet placed
information in the ASB, or if the KAV30 kernel has delivered the AST.

Using the KAV$CLR_ASTservice frees all the pending ASBs.

The ASBtypecodefield contains either the value ASB$K_ASBPENDor
the value ASB$K_ASBFREE, which indicates whether the ASB is pending
or free.
e

PCB address
This field contains the address of the PCB for the process that receives the
AST.

AST address
This field contains the address of the AST routine.

AST parameter

This field contains an optional parameter to the AST routine. This
parameter can specify a data value or the addressof a block of data values.
e

AST flag
If this flag is set, the KAV30 kernel requeues the ASB to the AST pending
queue for the device event immediately after delivery. If the flag is cleared,
the KAV30 kernel clears the ASB after it delivers the AST.

KAV30 Kernel

3-3

KAV30 Kernel

Figure 3-1 ASB Fields
FLINK

<_<

BLINK
ASB
Type Code}

AST
Flags

Device Code

PCB Address
AST Address
AST Parameter

Figure 3—1 illustrates the fields in the ASB.
The head of the AST queueis located in the Process Control Block (PCB). The

KAV30 kernel modifies the standard VAXELN PCB by adding two longword

fields, PCB$A_ASTFLK and PCB$A_ASTBLKto the end of the PCB. These

fields are pointers to the AST queue for that process, as shown in Figure 3-2.
See the Introduction to VMS System Services guide for more information.
The Introduction to VMS System Services is part of the VMS programming
documentation.

Figure 3-2 AST Queue
PCB
ASB
AST Queue

Listahead

3-4

KAV30 Kernel

<——>

ASB
<>

<—>

KAV30 Kernel

3.2 Timers
This section describes the KAV30 timers. There are five 32-bit timers and two

16-bit timers on the KAV30. The 32-bit timers are for general-purpose use.

One 16-bit timer is a watchdog timer andthe otheris the local bus timeout
timer.
Each timer operates as follows: you use the KAV$TIMERSservice to load a
value into the timer register. The value then decrements on each clock cycle
until it reaches zero. When the value reaches zero, the KAV30 delivers an AST.

To calculate the value that you must load, divide the required timer interval by
the clock period. The clock period is 400 nanoseconds(ns).
A 16-bit timer can time intervals up to (246 — 1) clock cycles, so the maximum

interval that you can useis as follows:

916 _ 4 — 65 535
Maximuminterval = 65 535 x 400 ns
= 26.214 ms

The 32-bit timers are made up of two 16-bit timers. The low-order word in
the timer acts as a prescaler. Every time the prescaler decrements to zero, the

high-order word decrements by one. The minimum value that you can specify
for the prescaler is two. A 32-bit timer can time intervals up to (2!) times
longer than a 16-bit timer can, that is, intervals of up to (222 — 1) clock cycles,
so the maximum interval that you can useis as follows:

9324 — 4 294 967 295
Maximum interval = 4 294 967 295 x 400 ns

= 28.633 minutes(min)
A convenient way to program a timeris to load the value 2500 into the
prescaler. Because the clock period is 400 ns, this value causes the prescaler
to decrement to zero in 1 ms. Then, to time intervals in multiples of 1 ms,

load the multiple into the high-order word. However, the timer loads the
multiple into the high-order word after the prescaler first decrements to
zero. Therefore, to ensure that the timer expires after the correct number
of decrements, subtract one from the value that you load into the high-order
word. For example, to set a timer to expire after 1 s, load the value 2500 into
the prescaler and 1000 minus oneinto the high-order word. The value you load
into the timeris as follows:

(65 536 x (1000 — 1)) + 2500 = 65 472 964 = 03E709C44¢
KAV30 Kernel

3—5

KAV30 Kernel

The KAV30 also has a watchdog timer and a local bus timeout timer. These
are 16-bit timers. If the watchdog timer expires, a system reset occurs. The
local bus timeout timer is used by the rtVAX 300 to monitor the DAL bus.
Digital strongly recommends that you do not change the value of the local bus

timeout timer, because this can lead to unpredictable results and VMEbus or

VSB errors.

You can program the timers, using the KAV$TIMERSservice. See the
description of the KAV$TIMERSservice for more information.

3.3 Calendar/clock
This section describes the calendar/clock on the KAV30. The calendar/clock

maintains the time and date in units ranging from one-hundredth of a second
to a year and leap year, as well as providing counters for the day of the week,
day of the month, and day of the year. The calendar/clock keeps the time and

date in binary coded decimal (BCD) format.

The calendar/clock has the following features:
e

Alarm

You can set the calendar/clock to interrupt the KAV30 at a specified time.
You can also set it to interrupt after a specified interval.
e

Timesave RAM
The calendar/clock has a timesave area, in which it stores the contents of

the clock in the event of a powerfailure.
e

Twelve-hour and 24-hourclock

The calendar/clock can operate in 12-hour mode or 24-hour mode. In
12-hour mode, you can specify A.M. and P.M.

3-6

KAV30 Kernel

Julian date
The calendar/clock also provides the date in Julian format. The Julian date
is the numberof elapsed days in the year. For example, the Julian format

for March 17, 1991 is 076 (because March 17 is the seventy-sixth day of the

year). The Julian format for March 17, 1992 is 077 (because 1992 is a leap

year and March 17 is the seventy-seventh day).
e

Device RAM

The calendar/clock contains 31 bytes of general purpose RAM, which you
can read from or write to using the KAV$RTC system service. Either a

battery or the VMEbusstandby power supply backs up the device RAM.
e

Timers

The calendar/clock has two 16-bit timers. The VMEbus uses one of these
timers as a bus timeout timer. This timer controls the length of time

within which the VMEbus must respond to an attempt by the KAV30

to gain control of the bus. Digital strongly recommends that you do not

change the value of this timer because this can lead to unpredictable
results.

The second 16-bit timer is for general use. You can program this timer

in the same way as the other KAV30 timers. See Section 3.2 for more
information.

Figure 3-3 shows the address mapof the calendar/clock. The first 31 bytes

contain time and date information. The second 31 bytes are general-purpose

RAM.

You can use the KAV$RTC system service to carry out the following operations

on the calendar/clock:
e

Interrupt the KAV380 at a specified time (alarm)

Interrupt the KAV30 when the interval you specify elapses (periodic alarm)

Read the time at which the calendar/clock is set to interrupt the KAV30

Set the time at which the calendar/clock interrupts the KAV30

Read the calendar date

Set the calendar date

Read data from the calendar/clock RAM

Write data to the calendar/clock RAM

Read data from the calendar/clock timesave area

KAV30 Kernel

3-7

KAV30 Kernel

Figure 3-3 Calendar/clock Address Map
1F

1E
1D
1C
1B
1A
19
18
17
16
15

Page Select = 0

RAM/TEST

Page Select = 1

RAM

RAM
RAM
RAM
RAM
RAM
RAM
RAM
RAM
RAM

RAM

13
12

RAM

OE
OD
oC
0B
OA

RAM
RAM
RAM
RAM
RAM

10
OF

RAM
RAM

08
07
06

RAM

Seconds Clock Counter

1/1000

Interrupt Routing Register

Interrupt Control Register 1

Periodic flag Register

Interrupt Control Register 0

Timer 1 Control Register
Timer 0 Control Register

02
{01

Output ModeRegister
Real Time Mode Register

00]

Main Status Register |

Write data to the calendar/clock timesave area

See the description of the KAV$RTC service for more information.

3-8

KAV30 Kernel

3.4 FIFO Buffers
This section describes the FIFO buffers on the KAV30. The KAV30 contains

four independently operating FIFO buffers. The purpose of the FIFO buffers
is to enable an intelligent device on the VMEbus to exchange data with the
KAV30. The VMEbus devices can write data into the FIFO buffers, and the

KAV30 can then read the data from the buffers. Similarly, the KAV30 can

write data into the FIFO buffers, and the VMEbusdevice can then read the
data from the buffers.

Each FIFO buffer is organized into 255 longwords. However,it is possible to
perform longword, quadword, and octaword operations on the FIFO buffers.

When you perform quadword and octaword operations on the FIFO buffers,
the FIFO logic circuitry writes or reads the message as an atomic collection of
longwords.

Any device on the VMEbus (including the KAV30) can read from and write to
the FIFO buffers in FIFO mode, or write to the buffers in LIFO mode.

A device that writes the data into the KAV30 FIFO buffers is called the
producer. A device that reads the data from the buffers is called the
consumer. The KAV30 can act as a producer or as a consumer, as shown in

Figure 3-4. The KAV30 can also act neither as the producer or the consumer.
In that case, two devices on the VMEbus act as producer and consumer, as
shown in Figure 3-5.

The FIFO logic circuitry indicates an error when you read a message from an
empty FIFO buffer, or write a message to a full FIFO buffer.

You can read/write the FIFO buffers, using the KAV$FIFO_READ, KAV$FIFO_
WRITE, and KAV$LIFO_WRITEsystem services. See Chapter 4 for more
information.
You can configure the KAV30 to notify you when a FIFO buffer changesits
state under one or more of the following circumstances:
e

Whenthe state changes from empty to not-empty

When the state changes from not-empty to empty

When the state changes from not-emptyto full

See the description of the KAV$NOTIFY_FIFO for more information.

KAV30 Kernel

3-9

KAV30 Kernel

3.5 Battery Backed-Up RAM
This section describes the battery backed-up RAM on the KAV30. The battery

backed-up RAM allows you to store information that you want to protect in the
event of a system or powerfailure. For example, you can write error messages

to the battery backed-up RAM. If the system fails, the error information

will still be in the RAM after the system is rebooted. You can use the error
information to analyze the cause of the failure. However, you mustinstall the

battery jumper during the hardwareinstallation to enable this functionality.
See the KAV30 Hardware Installation and User’s Information for more
information.

Programs can use 22 of the 32K bytes of battery backed-up RAM.Of the
remaining 10K bytes, 8K bytes are reserved for use by the KAV30 kernel and
2K bytes are reserved for future use by Digital.

You can read from and write to the battery backed-up RAM, using the
KAV$RW_BBRAM service. See the description of the KAV$RW_BBRAM
service for more information.

3.6 Scatter-Gather Map
This section describes the SGM. The SGMis the part of the KAV30 hardware
that allows the devices on the VMEbusto access the KAV30 and allows the
KAV30 to access the devices on the VMEbus or VSB. The SGM has twoparts:
the outgoing SGM and the incoming SGM.
The KAV30 uses the outgoing SGM while operating in master mode, that is,
when the KAV380 accesses the devices on the VMEbus or VSB. It uses the
incoming SGM while operating in slave mode, that is, when the devices on the
VMEbusaccess the KAV30.

3.6.1 Outgoing SGM
The outgoing SGM maps KAV30 system (SO) virtual address space to the
address space of a target device on the VMEbus or VSB. This makes the
address space of a target device visible to the KAV30, and enables the KAV30
kernel to access the target device address space.

3-10

KAV30 Kernel

Figure 3—4 KAV30 as Producer and Consumer
KAV30 as a Producer
Consumer

Producer

KAV30

Other Device

VMEbus

KAV30 as a Consumer
Consumer

Producer

KAV30

Other Device

VMEbus

When you configure the KAV30, you pass the base address of the device on the
VMEbusor VSB to the KAV$OUT_MAPkernel service. This service returns
the KAV30 SO space virtual address that corresponds to the base addressof the
VMEbusor VSB device. To write data to an offset in the address space of the

KAV30 Kernel

3-11

KAV30 Kernel

Figure 3-5 KAV30 as Neither Producer or Consumer
Producer
Other Device

Consumer
KAV30

Other Device

i{t__ft_‘f
VMEbus

VMEbus or VSBdevice, add the offset to the virtual address returned by the
KAV$OUT_MAPservice, and write to the resulting address.

The outgoing SGM can map 230M bytes of KAV30 I/O space to the VMEbusor
VSB address space. The size of the VMEbus or VSB address space depends on
the type of addressing you use, as follows:
e

When you use VMEbus or VSB A382 addressing you can access 4G bytes of
address space

When you use VMEbus or VSB A24 addressing you can access 14M bytes

When you use VMEbus or VSB A16 addressing you can access 64K bytes of

of address space
address space

The outgoing SGM logic circuitry uses one SGM entry to map each 64K bytepage of KAV80 I/O space to the VMEbusor VSB address space. However, the
first SGM entry for a device specifies the base VMEbus or VSB addressofits
memory-mappedI/O space. You can map up to 3584 64K byte-pages of KAV30
S50 space to the VMEbus of VSB address space. See the description of the
KAV$OUT_MAPservice for more information.
When the KAV30 sends a VAX address, bits <15..0> of the VAX address

remain unchanged in the VMEbus or VSB address, and the outgoing SGM
logic circuitry uses the remainder of the VAX address as an index into the
outgoing SGM. Figure 3-6 illustrates the conversion of a VAX address into
an A32 VMEbus or VSB address. Figure 3-7 illustrates the conversion of a

3-12

KAV30 Kernel

VAX address into an A24 VMEbus or VSB address. Figure 3-8 illustrates the
conversion of a VAX address into an Al6 VMEbus or VSB address.

Figure 3-6 Outgoing SGM Conversion to VMEbus or VSB A32 Addresses
31.----.--- 28

27 ....----------- 16

15 2.22.22. eee eee eee eee eee 00

Index into
Outgoing SGM

apt
Address Within 64K Bytes Page

VAX
Address

Outgoing SGM

se 16 15 2.2 eee eee eee eee 00
From the SGM

From the VAX Address

VMEbus
or VSB
Address

KAV30 Kernel

3-13

KAV30 Kernel

Figure 3-7 Outgoing SGM Conversion to VMEbus or VSB A24 Addresses
31...28 27_....-.-.-------------- 16
Index into
Outgoing SGM

15 .......------------------- eee 00
sa:
Address Within 64K Bytes Page

VAX
Address

Outgoing SGM

312.----------. 24 23... -nn-neneee 16 15 ...-..--.-.-----.-------------- 00
Don’t Care Bits

From the SGM

From the VAX Address

VMEbus
or VSB
Address

3.6.2 Incoming SGM
The incoming SGM maps one or more 64K byte-pages of VMEbus address
space to the KAV30 process (PO) virtual address space. The size of the VMEbus
address space depends on the size of the VMEbus address. The VMEbus A24
addresses can access up to 1M byte, or sixteen 64K byte-pages of address
space. The VMEbus A32 addresses can access up to 4M bytes, or 256 64K
byte-pages of address space.
To program the incoming SGM,call the KAV$IN_MAPservice and specify an
entry number in the incoming SGM.This entry numberindicates the 64K
byte-page of VMEbus address space that you want to map into KAV30 PO

space. The KAV$IN_MAP service returns the virtual address to which the
incoming SGM mapsthe base address of the 64K byte-page of VMEbus address

space.

3-14

KAV30 Kernel

Figure 3-8 Outgoing SGM Conversion to VMEbus or VSB A16 Addresses
3122-28 27.2. nnn nnn een eee eee 16
Index into
Outgoing
SGM

15 ....-..---------------- eee eee 00
att 64K Bytes Page
Address Within

VAX
Address

Outgoing SGM

ee sn ko 00
Don’t Care Bits

VMEbus
or VSB
Address

From the VAX Address

When the KAV30 maps a page of VMEbus address space to a page of PO space,
it sets both the page boundaries where the low-order 16 bits areall 0.
The following list describes the VMEbus addresses for each type of addressing:
e

A382 addressing
The VMEbusphysical address for A82 addressing consists of the following:
—

Bits 0 to 15 represent an address within a 64K byte-page

—

Bits 16 to 23 represent an index into the incoming SGM

—

Bits 24 to 31 are taken from the setting of the KAV30 VMEbus A32
base slave addressregister

KAV30 Kernel

3-15

KAV30 Kernel

The KAV30 base address specifies the part of the VMEbus address

space allocated to the module. For A32 addressing, each device has
16M bytes of VMEbus address space. You can set bits 24 to 31 by

calling the KAV$VME_SETUPservice to set up the VMEbussystem.
Figure 3-9 shows the A32 incoming VMEbus address.

Figure 3-9 A32 Incoming VMEbus Address
VMEbus A32
Base Slave Address}

Index into
Incoming SGM

Address Within 64K Bytes Page

A24 addressing
The VMEbus physical address for A24 addressing consists ofthe following:
Bits 0 to 15 represent an address within a 64K byte-page
Bits 16 to 19 represent the 4 low-order bits of an SGM entry
In A24 addressing, the incoming SGMcan map upto sixteen 64K bytepages of VMEbus address space into PO space, so the SGM can have a
maximum of 16 entries.
Bits 20 to 23 are taken from thesetting of the KAV30 rotary switch.
This switch specifies the KAV30 VMEbus base slave address.
The KAV30 base address specifies the part of the VMEbus address
space allocated to the module. For A24 addressing mode, each device
has 1M bytes of VMEbus address space. You can set bits 20 to 23 by
using the KAV30 rotary switch. See the KAV30 Hardware Installation
and User's Information for more information.
Bits 24 to 31 are don't carebits.

Figure 3-10 shows the A24 incoming VMEbus address.
When the KAV30 receives a VMEbusaddress, the conversion process it uses

differs depending on the type of VMEbus address that it receives. Figure 3-11
shows howit converts A832 VMEbusaddresses. Figure 3-12 shows how it
converts A24 VMEbus addresses.

3-16

KAV30 Kernel

Figure 3-10 A24 Incoming VMEbus Address
31-----------.- 24 23....20 19 ---.1615 .-.- eee eee eee 00
Don't Care Bits

VMEbus
A24 Base!

Slave

Address

Figure 3-11

Index
into

j||Incoming

Address within 64K Bytes Page

SGM

Incoming SGM Conversion of A32 VMEbus Addresses

31 1. -- eee eee eee 24 23__-..-..----- 1615... 0 eee eee eee 00

VMEbus A32
Base Slave
Address

index

Neex SGM

Address Within 64K Byte Page

VMEbus

Address

ncoming

Incoming SGM

31 30 29 28 27 26 25 24 23__.___..-----.16 15... eee eee eee eee eee ee eee 00
010

ololololo

From the SGM

From the VMEbus Address

VAX
Address

The SGM can map the VMEbusaddress space into the KAV30 FIFO buffers

instead of into PO space. Another device on the VMEbus can then access the
information in the FIFO buffers.

KAV30 Kernel

3-17

KAV30 Kernel

Figure 3-12 Incoming SGM Conversion of A24 VMEbus Addresses
31 ----------ee 24 23222220 19 22-1615 oi eee 00
VMEbus Index
VMEbus
Don't Care Bits
|A2¢ Base} into
Address Within 64K Bytes Page
Address
Slave

Address

|Incoming

SGM

Incoming SGM

31 30 29 28 27 26 25 24 23... 1 eee.16 152 eee eee eee eee 00
010

O10

10]0

From the SGM

From the VMEbus Address

VAX
Address

See the description of the KAV$IN_MAPservice for more information.

3.6.3 Byte Swapping During SGM Operations
The KAV30 arranges the bytes in each longwordit uses in little-endian format.
However, VMEbus and VSB devices arrange the bytes in a longword in bigendian format. Therefore, when you want to transfer information between the
KAV30 and a big-endian device, swap the bytes in the longword to preserve

the order of the data. Figure 3-13 showsthe little-endian data format.
Figure 3-14 shows the big-endian data format.

3-18

KAV30 Kernel

Figure 3-13 Little-Endian Storage Format

Word 1

Word 0

The KAV30 can perform the following types of byte swapping:

Mode 0 swapping
Two terms are commonly used to describe mode 0 byte swapping: no swap,
and byte and word swap. The term no swap refers to the relative position

of the bytes in the two formats. That is, both devices process the data in
the same order. For example, the byte at bit 0 in the big-endian formatis
the byte at bit 0 in the little-endian format. The term byte and word swap

refers to the hardware operation that the byte swaplogic circuitry performs

on the data. That is, the byte swap logic swaps the low-order and high-

order bytes in each word, and then swaps the low-order and high-order
words in the longword. Figure 3-15 shows mode0 byte swapping.
Mode 1 swapping

Mode1 swapping is Digital reserved.

KAV30 Kernel 3-19

KAV30 Kernel

Figure 3-15 Mode 0 Byte Swapping
S31... ene ee. 24 23..........- 16 15............ 3 0

Byte 3

Byte 2

Byte 1

Byte 0

aoendian

Byte 0

Byte 1

Byte 2

Byte 3

KAV30

O.....-..------ ts ee 15 16..........- 23 24.....--.-.-- 31

3-20

KAV30 Kernel

Mode 2 swapping
Note

When you use mode 2 swapping, you can perform only word-aligned
word accesses and longword-aligned longword accesses.
Mode 2 swappingis also referred to as word swapping. This is because the

low-order and high-order words in the longword are swapped. Figure 3-16

shows mode 2 swapping.

Mode 3 swapping
Note

When you use mode 3 swapping, you can perform only word-aligned

word accesses and longword-aligned longword accesses.

Two terms are commonly used to describe mode 3 byte swapping: byte

and word swap, and no swap. The term byte and word swap refers to the

relative position of the bytes in the two formats. That is, although the
two formats receive identical data, big-endian devices process the data in
a different manner than thelittle-endian devices. For example, the byte
at bit 0 in the big-endian format is identical to the byte at bit 24 in the
little-endian format. The term no swap refers to the hardware operation
that the byte swap logic circuitry performs on the data. That is, the byte

swaplogic circuitry does not perform any hardware operation on the data.
Figure 3-17 shows mode 3 byte swapping.

3.7 Communicating with Another KAV30
This section describes how two KAV30s can communicate with each other. A
KAV30 can communicate with another KAV30 in two ways:
e

By using shared memory pages to access the system RAM of the other

KAV30

KAV30 Kernel

3-21

KAV30 Kernel

Figure 3-16 Mode 2 Byte Swapping
31..2-----ee. 24 23........-- 16

15..__.....-- B

7 ieee wenn eee eee 0

Word 1

Word 0

Word 1

Big—Endian
Device

KAV30

O....--------e. 7 8...--------- 15 16........-.. 23 24.....-.-....- 31

Two KAV30s in a VMEbus system can communicate using shared memory
pages. The shared memory pages map physical pages from one of the

modules into a virtual address space on both modules. The module whose

physical page the shared memory page uses is the slave module. However,

it is possible to configure the system so that the physical memory of both
modules has a shared memory page.

3-22

KAV30 Kernel

Figure 3-17 Mode 3 Byte Swapping
9 0
Longword

Big-Endian
Device

Longword

KAV30

Onn een e eee nenee 31

The shared memory pages provide the fastest method for one KAV30 to

pass information to another KAV30, because the modules have the data

area mapped into their virtual address space.

When two KAV30s use shared memory pages to communicate, the
application program must provide proper synchronization methods to
ensure data integrity.
e

By reading and writing the FIFO buffers on the other module
Two KAV30s can also communicate using the KAV30 FIFO buffers. To

write data to the FIFO buffer of another KAV30, the first module uses
the KAV$BUS_WRITE kernel service with the KAV$MFIFOACCESS

modifier to write the data to the VMEbus address space. The second
module uses its incoming SGM to map the FIFOs onto the VMEbusaddress

space. The second module then uses the KAV$FIFO_READservice to read
the data in the FIFO buffers.

KAV30 Kernel

3-23

KAV30 Kernel

The FIFO buffers method has the advantage that the sender does not have
to wait for the receiver to process data before it sends more data to the
receiver.
Communicating using the KAV30 FIFO buffers is preferable, except when you

wantto transfer large amounts of data. In this case, the shared memory pages
methodis preferable.
In VMEbussystems containing two KAV30s, ensure that you do not configure

the modules at the same VMEbusbase address.
Note

When a VMEbussystem contains two KAV30s with the same VMEbus

base address, unpredictable results occur.

3.8 KAV30 Error Logging Support
This section describes the KAV30 error logging support. The KAV30 logs errors

that you generate in its battery backed-up RAM. When you build error-logging

into the system, the KAV30 also logs errors in the KAV30 errorlog file. The

KAV30 kernel creates the error log file and sends it to the host system if a
DECnet™connection to the host is available.
The KAV30 logs the following errors:

Bus errors and timeouts

Invalid SGM entries

SGM accessviolations

You can analyze the KAV30 error log file, using the VMS Error Log Utility.
However, the reports that this utility generates are primarily intended to assist
Digital Customer Services personnel. (See the VAXELN Development Utilities
Guide for more information on VAXELNerror logging.)
Note

You might want to build two versions of a system: one with error
logging support and the other without error logging support. Then,if
problemsarise, you can run the version with error logging to analyze

the problem.

3-24 KAV30 Kernel

KAV30 Kernel

Error log-reports contain two sections: the identification section and the
device-dependent data section. The identification section consists of thefirst
four lines of the report. The device-dependent data section, which follows the

identification section, contains information about the selected error log entries.

Each line in this section gives a hexadecimal value and a short description
of what the value signifies. See the VMS Error Log Utility Manual for more

information.

There are two types of error log entry: error log entries for errors that occur

while the KAV30 acts in master mode, and error log entries for errors that
occur while the KAV30 acts in slave mode. Figure 3-18 shows a sample error
log report entry for an error that occurred while the KAV30 wasacting in
master mode. Figure 3-19 shows a sample error log report entry for an error

that occurred while the KAV30 was acting in slave mode.
Figure 3-18 Sample Master Error Log Entry
TKK KKK RIK KEK KKK KKKKKEKK ENTRY

644, KKK KKK KKK KKK KKK KKK KEKE KR KEK KKK KK

ERROR SEQUENCE 20479.
DATE/TIME 1-FEB-1991 21:30:31.53
SCS NODE: KAV30E
SSNDERR MESSAGE

KA300

CPU REV# 7.

LOGGED ON:

FW REV# 1.0

SID 0A000006
SYSTYPE 09100002

MESSAGE TEXT

00007E0C

Status Code ©

3944000B

VME/VSB Master AM & Error Code & Retry Count

00F03038

VME/VSB Address Accessed

8000B7c0
00c80009

Pc ©
PSL @

KKEKKKKKRKKKKKKKKEKKEKKKKKE KKK KKKK KKK RK KKK KK KEK KKEK KEKE KKK KKK KRKK KEK KKKKKKKKKKKKKKKKKK

Figure 3-19 Sample Slave Error Log Entry
KKK KK KK KERR KKK KKK A KKKKEKEKKEEKAK ENTRY

DU KR KKK KKK KKK KKK KKK KERR KKK KKK KK KK

ERROR SEQUENCE 2.
DATE/TIME 28-Jan-1991 15:15:30.87
SCS NODE: KAV30D
SSNDERR MESSAGE

KA300

CPU REV# 7.

LOGGED ON:

FW REV# 1.0

SID 0A000006
SYSTYPE 09100002

(continued on next page)

KAV30 Kernel

3-25

KAV30 Kernel

Figure 3-19 (Cont.) Sample Slave Error Log Entry
MESSAGE TEXT

00007E3C

Status Code @

00000084

VME Slave Error Status

00000001

VME Slave Error count

KKEKKKKRKKKKKRKEKKKEK KE KKK KKK KKK KKK KK KKK KKK KR KKKKK KERR KE KKK KKK RKKRKKKKKRKKKEKKKEKKE

The following list explains the information labeled with callouts in Figure 3—18
and Figure 3-19.
@

Thefirst four lines make up the identification section. See the VMS Error
Log Utility Manual for a description of the information contained in the

identification section.

This line gives the following information:
e

The mechanism used to write the error log entry into the errorlog file

The CPU type

Hardware and firmwarerevision levels

® This line gives the KAV30 status code for the error. The status codes
returned by KAV30 services are similar to those returned by VAXELN
kernel procedures. All of these codes follow the VAX convention for

status codes. A message is associated with each status code. You can
use the ELN$GET_STATUS_TEXT VAXELN message-processing routine

to retrieve the message text associated with a specified status code. An

application can use these routines to retrieve a message text from the
system messagefiles or user-created messagefiles. See the VAXELN
Runtime Facilities Guide for more information.
©

The contents of this line depend on whether the error occurred while the
KAV30 was acting in master mode or slave mode:
e

3-26

Ifthe error occurred while the KAV30 was acting in master mode, this

line provides the following:
—-

The VMEbus or VSB Address Modifier (AM) bits

—

The internal master error code

—

The number of times the KAV30 kernel retried to gain control of
the VMEbus or VSB

KAV30 Kernel

The high-order byte of the status code provides the AM bits that the
KAV30 was using when the error occurred.

The next byte gives the internal master error code. Table 3—1 explains
the bits of the internal master error code.
Internal Master Error Code

Bit

Value

The SGM entry for the VMEbus or VSB addressis valid.

Table 3-1

Meaning
The SGM entry for the VMEbus or VSB address is invalid.

The SGM entry for the VMEbus or VSB addressis write protected.

The KAV30 local bus timeout timer has not expired.

The SGM entry for the VMEbusor VSB addressis not write protected.

The KAV80 local bus timeout timer has expired.

The KAV30 was trying to gain control of the VSB when the error
occurred.

The KAV30 did not access one of the FIFO buffers on the module when
the error occurred.

The KAV30 accessed one of the FIFO buffers on the module when the
error occurred.

The VMEbus IACKcycle did not fail.

The KAV30 was trying to gain control of the VMEbus whenthe error
occurred.

The VMEbus IACKcycle failed.
0

The KAV30 did not have control of the VMEbus or VSB whentheerror
occurred.

The KAV30 was performing a write operation whenthe error occurred.

The KAV30 had control of the VMEbus or VSB whentheerror occurred.

The KAV30 was performing a read operation when the error occurred.

The low-order word contains the numberof times the KAV30 kernel
retried to gain control of the bus (this does include the retries
performed by the KAV30 hardware). In this sample master error
log entry the KAV30 kernel performed eight software retries.

If the error occurred while the KAV30 wasacting in slave mode,this
line gives the internal slave error code. Table 3—2 explains the bits of
the internal slave error code.

KAV30 Kernel

3-27

KAV30 Kernel

Table 3—2 Internal Slave Error Code

The SGM entry for the VMEbus addressis invalid.

O&O

The SGM entry for the VMEbusaddressis not write protected.

The SGM entry for the VMEbus address is write protected.

The KAV30 local bus timeout timer has not expired.

Meaning
The SGM entry for the VMEbus addressis valid.

The KAV30 local bus timeout timer has expired.
The KAV30 was accessing system RAM when theerror occurred.

Value

oOo

Bit

The KAV30 wasaccessing the FIFO buffers when the error occurred.
Whenthe bit 3 has the value 1, the KAV30 was accessing a FIFO port
whenthe error occurred.
Whenthe bit 3 has the value 1, the KAV30 was accessing FIFO memory
whenthe error occurred.
The KAV30 was performing a write operation when the error occurred.
The KAV30 was performing a read operation whenthe error occurred.
Whenbit 3 has the value 1, bit 6 contains the value of the least

significant bit of the FIFO port number that you were accessing when

the error occurred.

Whenbit 3 has the value 1, bit 7 contains the value of the most

significant bit of the FIFO port number that you were accessing when

the error occurred.

The contents of this line depend on whetherthe error occurred while the
KAV30 was acting in master mode or slave mode:
If the error occurred while the KAV30 was acting in master mode, this
line gives the VMEbusor VSB address that the KAV30 tried to access.
In this case, the address was OOFO 30388,¢. The address is always
longword aligned.
If the error occurred while the KAV30 was acting in slave mode, this

line gives the address being accessed when the error occurred.

This line is displayed in the error log entry only when the error occurred

while the KAV30 was acting in master mode. This line gives the value
of the Program Counter (PC) when the error occurred. If the KAV30
was trying to perform a read operation, the PC points to the failing
instruction. If the module was trying to perform a write operation by
accessing the VMEbusor VSBdirectly rather than using the KAV$BUS_

3-28 KAV30 Kernel

KAV30 Kernel

READ or KAV$BUS_WRITEkernelservices, this PC is of no value. This

is because the rtVAX 300 processor performs disconnected write operations
(see Section 5.1.1 for more information).
This line is displayed in the error log entry only when the error occurred
while the KAV30 was acting in master mode. This line lists the value of
the processor status longword when theerror occurred.

KAV30 Kernel

3-29

4
KAV30 System Services
This chapter describes the KAV30 system services. Each service description
has the following format:
e

An overview of the service

Thecall format for the service in each supported language

A list of the arguments for the service

A list of the status values returned by the service

A list of related services

Examples

KAV30 System Services 4-1

KAV$BUS_BITCLR

KAV$BUS_BITCLR
Clears the bits at a specified VMEbus or VSB address according to a specified
bit mask.
Note

This service performs read-modify-write cycles on the VMEbus or VSB.
The VMEbus or VSB address that you specify must be mapped to the KAV30
system virtual address (SO) space via the incoming SGM.
You can clear the bits in a byte, a word, or a longword. However, the VMEbus

or VSB device containing the bits that you want to clear must allow the type
of access that you specify. Also, when you wantto clear the bits in a word or a
longword, ensure that the address you specify is aligned to a word or longword.

The bit mask indicates the bits that you want to clear. For each bit that is
set in the bit mask, this service clears the corresponding bit at the VMEbusor
VSBaddress.
Calls to this service can result in VMEbus or VSBerrors such as arbitration
failures and bus timeouts. When the KAV$M_NO_RETRYflag in the
KAV$OUT_MAP service is not set, the KAV30 retries 29 times to clear the

bits. However, the KAV30 kernel can direct the module to perform additional
retries—you can specify this when you build the system. See Section 5.4 for
more information.

4-2 KAV30 System Services

KAV$BUS_BITCLR

Ada Call Format
WITH KAVDEF:
KAV_BUSBITCLR ([STATUS => status,]
DATA_TYPE => data_type,
VIRTUAL_ADDRESS => virtual_address,
MASK => mask);

argument information
status :

out

CONDITION_HANDLING.COND_VALUE._
TYPE;

data_type :

INTEGER;

virtual_address:

SYSTEM.ADDRESS;

mask :

INTEGER;

C Call Format
#include $vaxelnc
#include "eln$:kavdef.h"

int kav$bus_bitclr ([status],
data_type,

virtual_address,

mask)

argumentinformation
int

*status;

int

data_type;

void

*virtual_address;

int

mask;

KAV30 System Services 4-3

KAV$BUS_BITCLR

FORTRAN Call Format

INCLUDE ’ELN$:KAVDEF.FOR’

CALL KAV$BUSBITCLR ((status|,

%VAL(data_type),
virtual_address,

%VAL(mask))

argumentinformation
INTEGER*4
INTEGER*4
INTEGER*4
INTEGER*4

status

data_type
virtual_address
mask

Pascal Call Format

INCLUDE $KAVDEF:

KAV$BUS_BITCLR ([STATUS := status]
data_type,

virtual_address,

mask)

argumentinformation
status:

INTEGER;

data_type :

INTEGER;

virtual_address:

AANYTYPE;

mask :

INTEGER;

4-4 KAV30 System Services

KAV$BUSBITCLR

Arguments
status

Usage:

Longword (unsigned)

Access:

Write only

Mechanism:

Reference

VAX Type:

cond_value

Receives the completion status.
data_type
Usage:
VAX Type:

Access:
Mechanism:

Longword (unsigned)
longword_unsigned

Read only
Value

Specifies whether this service clears the bits in a byte, a word, or a longword.
Specify one of the following values:
KAV$K_BYTE
KAV$K_LONGWORD
KAV$K_WORD

Clears the bits in a byte
Clears the bits in a longword
Clears the bits in a word

The VMEbus or VSB device containing the bits that you want to clear must
allow accesses of the type that you specify.
virtual_address
Usage:
Longword (unsigned)
VAX Type:
longword_unsigned
Access:
Read only
Mechanism:

Value

Specifies the virtual address, in SO address space, of the bits that you want to
clear.
To calculate the VMEbusor VSB address, follow these steps:
1.

Calculate the base address of the VMEbus or VSB device containing the

bits that you want to clear. The KAV$OUT_MAP service returns the base
VMEbusor VSB addressof a device. See the description of the KAV$OUT_
MAP service for more information.
Calculate the offset, into the device’s address space, of the bits that you
want to clear.

KAV30 System Services 4-5

KAV$BUS_BITCLR
3.

Add the base address to theoffset.

mask
Usage:
VAX Type:
Access:
Mechanism:

Longword (unsigned)
longword_unsigned
Read only
Value

Specifies the bit mask that indicates the bits to clear. The bit mask is the
type that you specify in the data_type argument. For example, if you specify

KAV$K_WORDfor the data_type argument, the bit mask is in the low-order 16
bits of the mask address.

Status Values
KAV30$_BAD_PARAM

You did not specify a parameter in the correct
format.

KAV30$_BUS_ARB_ERROR
KAV30$_BUS_RD_ERROR
KAV30$_BUS_WRT_ERROR
KAV30$_INVALID_SG_
ENTRY
KAV30$_NO_BUS_RD_RESP
KAV30$_NO_BUS_WRT_
RESP
KAV30$_WRPROT_SG_
ENTRY
KER$_BAD_COUNT

A VMEbusor VSBarbitration failure occurred.
A VMEbusor VSBreaderror occurred.
A VMEbusor a VSB write error occurred.
You specified an invalid SGM entry.

You attempted to write to a write-protected
SGM entry.
You did not specify the correct number of

KER$_BAD_VALUE

You did not specify a value in the correct

KER$_NO_ACCESS
KER$_SUCCESS

The service could not access an item.

4-6 KAV30 System Services

There was no read response from the device.

There was no write response from the device.

arguments.

format.

The operation was successful.

KAV$BUS_BITCLR

- Related Services
KAV$BUS_BITSET
KAV$BUS_READ

KAV$BUS_WRITE

Examples
The following code is an example program that calls the KAV$BUS_
BITCLRservice:
/*
*

Facility:

KAV30 VAXELN System Services programming example.

*
*
x

Description:

This is an example program demonstrating the calling
procedures for the following KAV System Services:
1. KAVSVMESETUP
(Configure VMEbus interrupting,...)

x
x

2.
3.

*
*
x

Abstract:

*
*

Language:

Notes: (1)

*
*
*
*
*

KAVSBUSBITCLR

(Map onto VMEbus address)
(Set a bit at a VMEbus address)
(Clear

tee)

This program assumes that there is a VME-bus device located
on the bus, at the address specified below.
It performs a bit-clear and a bit-set on two of this

device’s registers.

KAVSOUTMAP
KAVSBUSBITSET

(2)
(3)

Vax C; Version 3.1

If there is no device located on the VME-bus at the

specified address, then the KAV System Service routines
will return errors (in the ‘status’ variable).
The device is assumed to be set up for 24-bit addressing.
In the interests of program clarity, no error checking has
been included.

*/
#include
#include
#include

stdio
Svaxelnc
<elnS:kavdef.h>

KAV30 definitions file.

KAV30 System Services 4-7

KAV$BUS_BITCLR
/x
*

The following definitions are device-specific.

*/
#define

DEVICEADDRESS

#define
#define

#define

REGISTERBASE

Oxfe0000

0x0e00

/*
/*
/*

/*
/*

Base address of the device.

The rotary switch on the KAV
module must be set up to
agree with this addressing.

Offset of first register.
Offset of second register.

*/
*/
*/

*/
*/

main ()

{

unsigned long

amcode,

unsigned long

buffer,
entry,
viraddr,
physaddr ;
*registerladdress,

int

setupfunctions,

*register2address ;

/* Note these are address POINTERS. */

status,
pagecount,

unsigned char

mapfunctions ;
bit0 = 0x01,
bit7 = 0x80 ;

/* Bit-0 (least significant bit in byte).
/* Bit-7 (most
..... ).

x/
x/

/*
*

Setup the VME functions to disable the VME-device from interrupting.

buffer

= 0x00000000;

setupfunctions = KAV$KALLOWVMEIRQ;

/* No IRQ allowed by VME-device */

KAVSVMESETUP( &status, setupfunctions, &buffer );
/x
*

Map into the device register region.

pagecount

=1;

/* Number of 64K pages.

amcode

= KAVSKUSER24 ;

/* Standard User Mode addressing. */

physaddr

mapfunctions
KAVSOUTMAP(

= DEVICEADDRESS ;

= KAVSMVME + KAVSMMODE0SWAP; /* Byte/Word Swapping.

&status, é&entry, pagecount,

physaddr, &viraddr,
amcode, mapfunctions) ;

/*
x

Setup the register pointers (virtual)

registerladdress = viraddr + REGISTERBASE + REGISTER1OFFSET ;
register2address
viraddr + REGISTERBASE + REGISTER2OFFSET ;
4-8 KAV30 System Services

KAV$BUS_BITCLR

/* (we are now able to access the device’s registers)
x

x
*

SET bit-0 in first register.

KAVSBUS_BITSET (

&status,
KAVSK_BYTE,

registerladdress,

bitO )

;

/*
*

CLEAR bit-0 in second register.

KAVSBUS BITCLR(

} /*

end

&status,

KAVSKBYTE,

register2address,
bit? ) ;
-program-

KAV30 System Services 4-9

KAV$BUS_BITSET

KAV$BUS_BITSET
Sets the bits at a specified VMEbus or VSB address according to a specified bit
mask.
Note

This service performs read-modify-write cycles on the VMEbusor VSB.

The VMEbus or VSB address that you specify must be mapped to the KAV30

system virtual address (SO) space via the incoming SGM.

You can set the bits in a byte, a word, or a longword. However, the VMEbus

or VSB device containing the bits that you want to set must allow the type
of access that you specify. Also, when you want to set the bits in a word or a
longword, ensure that the address you specify is aligned to a word or longword.
The bit mask indicates the bits that you want to clear. For each bit that is set
in the bit mask, the service sets the corresponding bit in the VMEbus or VSB
address.

The calls to this service can result in VMEbus or VSBerrors such as
arbitration failures and bus timeouts. When the KAV$M_NO_RETRYflag

in the KAV$OUT_MAP serviceis not set, the KAV30 retries 29 times to set the

bits. However, the KAV30 kernel can direct the module to perform additional
retries — you can specify this when you build the system. See Section 5.4 for
more information.

4-10 KAV30 System Services

KAV$BUS_BITSET

Ada Call Format
WITH KAVDEF;
KAV_BUSBITSET ([STATUS => status,]
DATA_TYPE => data_type,

VIRTUAL_ADDRESS => virtual_adadress,

MASK => mask);

argumentinformation
status :

out

CONDITION_HANDLING.COND_VALUE_

data_type :

INTEGER;

virtual_address:

SYSTEM.ADDRESS;

mask :

INTEGER;

TYPE;

C Call Format
#include $vaxelnc
#include "eln$:kavdef.h"

int kav$bus_bitset ([statusl,
data_type,

virtual_address,

mask)

argumentinformation
int

*status;

int

data_type;

void

*virtual_address;

int

mask;

KAV30 System Services 4—11

KAV$BUS_BITSET

FORTRANCall Format

INCLUDE ’ELN$:KAVDEF.FOR’
CALL KAV$BUS_BITSET ([status},

%VAL(data_type),
virtual_address,

%WVAL(mask))

argumentinformation
INTEGER*4
INTEGER*4
INTEGER*4
INTEGER*4

status

data_type
virtual_address
mask

Pascal Call Format

INCLUDE $KAVDEF:

KAV$BUSBITSET ([STATUS:= status]
data_type,

virtual_adaress,
mask)

argumentinformation

4-12

status :

INTEGER;

data_type :

INTEGER;

virtual_address:

SANYTYPE;

mask :

INTEGER;

KAV30 System Services

KAV$BUS_BITSET

Arguments
status

Usage:

Longword (unsigned)

VAX Type:
Access:

cond_value
Write only

Mechanism:

Reference

Receives the completion status.
data_type
Usage:
VAX Type:

Access:
Mechanism:

Longword (unsigned)
longword_unsigned

Read only
Value

Specifies whether this service sets the bits in a byte, a word, or a longword.
Specify one of the following values:
KAV$K_BYTE
KAV$K_LONGWORD
KAV$K_WORD

Sets the bits in a byte
Sets the bits in a longword
Sets the bits in a word

The VMEbus or VSB device containing the bits that you want to set must allow
the type of access that you specify.
virtual_address
Usage:

Longword (unsigned)

Mechanism:

Value

VAX Type:
Access:

longword_unsigned
Read only

Specifies the virtual address, in SO address space, of the bits that you want to
Set.

To calculate the VMEbus or VSB address,follow these steps:
1.

Calculate the base address of the VMEbus or VSB device containing the
bits that you want to set. The KAV$OUT_MAPservice returns the base
VMEbusor VSB addressof a device. See the description of the KAV$OUT_
MAP service for more information.

Calculate the offset into the device’s address space of the bits that you
want to clear.
KAV30 System Services 4—13

KAV$BUS_BITSET

Add the base addressto the offset.

mask
Usage:
VAX Type:
Access:
Mechanism:

Longword (unsigned)
longword_unsigned
Read only
Value

Specifies the bit mask that indicates the bits to set. The bit mask is of the
type that you specify in the data_type argument. For example, if you specify
KAV$K_WORDfor the data_type argument, the bit maskis in the low-order 16
bits of the mask address.

Status Values
KAV30$_BAD_PARAM

You did not specify a parameter in the correct
format.

KAV30$_BUS_ARB_ERROR
KAV30$_BUS_RD_ERROR
KAV30$_BUS_WRT_ERROR
KAV30$_INVALID_SG_
ENTRY
KAV30$_NO_BUS_RD_RESP
KAV30$_NO_BUS_WRT_
RESP
KAV30$_WRPROT_SG_
ENTRY
KER$_BAD_COUNT

A VMEbusor VSBarbitration failure occurred.
A VMEbusor VSBread error occurred.
A VMEbusor a VSB write error occurred.

You specified an invalid SGM entry.
There was no read response from the device.
There was no write response from the device.
You tried to write to a write-protected SGM
entry.

You did not specify the correct number of
arguments.

KER$_NO_ACCESS

You did not specify a value in the correct
format.
The service could not access an item.

KER$_SUCCESS

The operation was successful.

KER$_BAD_VALUE

4-14 KAV30 System Services

KAV$BUS_BITSET

Related Services
KAV$BUS_BITCLR
KAV$BUS_READ

KAV$BUS_WRITE

Examples
See the examples in the description of the KAV$BUS_BITCLRservice.

KAV30 System Services 4—15

KAV$BUS_READ

KAV$BUS_READ
Reads the contents of a VMEbus or VSB address. The VMEbusor VSB address
you read must be mapped to the KAV30 system virtual address (SO) space via
the outgoing SGM.

You can read data in byte, word, or longword format. However, ensure that the

VMEbusor VSB device from which you read data allows the type of access you
specify.

Whenyoucall this service to read data from a FIFO buffer on another VMEbus
or VSB device, specify the KAV$M_FIFO_ACCESS and KAV$K_LONGWORD

values in the data_type argument. This causes the KAV$BUS_READ service
to read data from the same VMEbus or VSB address each time. If you do
not specify the value KAV$M_FIFO_ACCESS, the KAV$BUS_READ service
increments the address after each read operation, as follows:
e

Whenthe service reads data in byte format, it increments the address by 1

Whenthe service reads data in word format, it increments by 2 bytes.

Whenit reads data in longword format, it increments by 4 bytes.

byte.

Note

Digital recommends that you exchange data by directly accessing the
VMEbusand VSB, rather than by calling the KAV$BUS_READservice.
See Section 5.1.1 for more information.

4-16 KAV30 System Services

KAV$BUS_READ

Ada Call Format

WITH KAVDEF:
KAV_BUSREAD ([STATUS => status,]
DATA_TYPE => data_type,

VIRTUAL_ADDRESS => virtual_address,

BUFFER => buffer,
COUNT => count);

argumentinformation
status :

out

CONDITION_HANDLING.COND_VALUE_
TYPE;

data_type:

INTEGER;

virtual_address:

SYSTEM.ADDRESS;

buffer :

SYSTEM.ADDRESS;

count:

INTEGER;

C Call Format
#include $vaxelnc
#include "eln$:kavdef.h"

int kav$bus_read (status,
data_type,

virtual_adadress,

buffer,
count)

KAV30 System Services 4-17

KAV$BUS_READ
argument information
int

“status;

int

data_type;

void

*virtual_address;

int

“buffer;

int

count;

FORTRAN Call Format
INCLUDE ’ELN$:KAVDEF.FOR’
CALL KAV$BUSREAD

([status],

%VAL(data_type),
virtual_address,
buffer,

%VAL(count))

argument information
INTEGER*4
INTEGER*4
INTEGER*4
INTEGER*4
INTEGER*4

status

data_type
virtual_address

buffer
count

Pascal Call Format
INCLUDE $KAVDEF;
KAV$BUSREAD ([STATUS := status,]
data_type,
virtual_address,
buffer,

count)

4-18 KAV30 System Services

KAV$BUS_READ
argumentinformation
status:

INTEGER;

data_type :

INTEGER;

virtual_address:

SANYTYPE;

buffer:

AANYTYPE;

count:

INTEGER;

Arguments
status

Usage:
VAX Type:
Access:

Longword (unsigned)
cond_value
Write only

Mechanism:

Reference

Receives the completion status.
data_type
Usage:
VAX Type:

Access:
Mechanism:

Longword (unsigned)
longword_unsigned

Read only
Value

Specifies the format of the data you want to read.
Specify one of the following values:
KAV$K_BYTE
KAV$K_LONGWORD
KAV$K_WORD
KAV$M_FIFO_ACCESS

Reads data in byte format
Reads data in longword format
Reads data in word format
Reads data from a FIFO buffer

The VMEbus or VSB device that you want to read from must allow the type of
access you specify.

KAV30 System Services 4-19

KAV$BUS_READ
Note

When you want to read data from a FIFO buffer on another VMEbus
or VSB device, specify the KAV$M_FIFO_ACCESS and KAV$K_
LONGWORDmodifiers.

virtual_address
Usage:
Longword (unsigned)
VAX Type:
longword_unsigned
Access:
Read only
Mechanism:

Value

Specifies the virtual address, in SO space, where you want to begin reading
data. To calculate the address, follow these steps:
1.

Calculate the base address of the VMEbus or VSB device containing the
bits that you want to read from. The KAV$OUT_MAPservice returns
the base VMEbusor VSB address of a device. See the description of the
KAV$OUT_MAPservice for more information.

Calculate the offset, into the device’s address space, that you want to read
from.

Add the base address to the offset.

When you read data from a FIFO buffer on another KAV30, use the following
offsets when calculating the address:
FIFO Buffer

Offset

0
1
2

400016
4010i¢
402016

403016

buffer
Usage:
VAX Type:
Access:

Longword (unsigned)
longword_unsigned
Write only

Mechanism:

Reference

Specifies the addressof a buffer into which the KAV$BUS_READ service places
the data that it reads from the VMEbusor VSB device.

4-20 KAV30 System Services

KAV$BUS_READ
count

Usage:
VAX Type:
Access:

Mechanism:

Longword (unsigned)
longword_unsigned
Read only

Value

Specifies the number of data items (of the type specified by the data_type

argument) that the KAV$BUS_READ service reads from the VMEbus or VSB
device.

Status Values
KAV30$_BAD_PARAM

You did not specify a parameter in the correct
format.

KAV30$_BUS_RD_ERROR
KAV30$_BUS_ARB_ERROR
KAV30$_INVALID_SG_
ENTRY
KAV30$_NO_BUS_RD_RESP
KER$_BAD_COUNT

A VMEbusor VSBreaderror occurred.
A VMEbusor VSBarbitration failure occurred.

You specified an invalid SGM entry.
There was no read response from the device.
You did not specify the correct number of
arguments.

KER$_BAD_VALUE

You did not specify a value in the correct
format.

KER$_NO_ACCESS
KER$_SUCCESS

The services could not access an item.

The operation was successful.

Related Services
KAV$BUS_BITCLR
KAV$BUS_BITSET

KAV$OUT_MAP
KAV$BUS_WRITE

KAV30 System Services 4-21

KAV$BUS_READ

Examples
The following code is an example KAV$BUS_READ call:
vir_address = virtual_address + '3603’X
CALL

HW OG NRO Fe

3020

3030

KAVSBUS_READ

(status,
sVAL (datatype),

‘SVAL(viraddress),

buffer,
SVAL (count) )
IF ( .NOT. status )
TYPE 3030, status
FORMAT(1H, ‘KAVSBUSREAD, status is :’, 24.4 )

The file SYS$SCOMMON:[SYSHLP.EXAMPLES.KAVIKAVMVME.FOR
contains a program that calls the KAV$BUS_READ service

4-22 KAV30 System Services

KAV$BUS_WRITE

KAV$BUS_WRITE
Writes data to a VMEbusor VSB address. The VMEbus or VSB address you
write to must be mapped to the KAV30 system virtual address (SO) space via
the outgoing SGM.
You can write data in byte, word, or longword format. However, ensure that

the VMEbus or VSB device to which you write data allows the type of access
you specify.

When youcall this service to write data to a FIFO or LIFO buffer on another

VMEbusor VSB device, specify the KAV$M_FIFO_ACCESS and KAV$K_
LONGWORDvalues in the data_type argument. This causes the KAV$BUS_
WRITE service to write data to the same VMEbus or VSB address each time.
If you do not specify the KAV$M_FIFO_ACCESSvalue, the KAV$BUS_WRITE
service increments the VMEbus or VSB address after each write operation, as
follows:
e

Whenit writes data in byte format, it increments the address by 1 byte

Whenit writes data in word format, it increments the address by 2 bytes

Whenit writes data in longword format, it increments the address by 4
bytes
Note

Digital recommends that you exchange data by directly accessing the
VMEbusand VSB, rather than by calling the KAV$BUS_WRITEkernel
service. See Section 5.1.1 for more information.

KAV30 System Services 4-23

KAV$BUS_WRITE

Ada Call Format

WITH KAVDEF;
KAV_BUSWRITE ((STATUS => status,]
DATA_TYPE => data_type,
VIRTUAL_ADDRESS => virtual_adadress,
BUFFER => buffer,
COUNT => count);

argumentinformation
status:

out

CONDITION_HANDLING.COND_VALUE_
TYPE;

data_type :

virtual_address:

buffer:

count :

INTEGER;
SYSTEM.ADDRESS;
SYSTEM.ADDRESS;
INTEGER;

C Call Format
#include $vaxelnc
#include "eln$:kavdef.h"

int kav$buswrite ([status],
data_type,

virtual_adaress,

buffer,
count)

4-24 KAV30 System Services

KAV$BUS_WRITE

argumentinformation
int

*status;

int

data_type;

void

*virtual_address;

void

“buffer;

int

count;

FORTRAN Call Format

INCLUDE ’ELN$:KAVDEF.FOR’
CALL KAV$BUSWRITE ((status],

%VAL(data_type),
virtual_address,

buffer,
%VAL(count))

argument information
INTEGER*4
INTEGER*4
INTEGER*4
INTEGER*4
INTEGER*4

status

data_type
virtual_address

buffer
count

Pascal Call Format

INCLUDE $KAVDEF;
KAV$BUSWRITE ([STATUS := status,]
data_type,
virtual_address,
buffer,

count)

KAV30 System Services 4—25

KAV$BUS_WRITE
argument information
status :

INTEGER;

data_type:

INTEGER;

virtual_address:

AANYTYPE;

buffer :

SAANYTYPE;

count:

INTEGER;

Arguments
status

Usage:
VAX Type:
Access:

Mechanism:

Longword (unsigned)
cond_value
Write only
Reference

Receives the completion status.
data_type
Usage:

VAX Type:

Access:
Mechanism:

Longword (unsigned)
longword_unsigned
Read only
Value

Specifies the format of the data you wantto write.

Specify one of the following values:
KAV$K_BYTE

Writes data in byte format

KAV$K_LONGWORD
KAV$K_WORD
KAV$M_FIFO_ACCESS

Writes data in longword format
Writes data in word format
Writes data to a FIFO or LIFO buffer

The VMEbus or VSB device that you want to write to must allow the type of
access you specify.

4-26 KAV30 System Services

KAV$BUS_WRITE
Note
When you want to write data to a FIFO or LIFO buffer on another

VMEbusor VSBdevice, specify the KAV$M_FIFO_ACCESS and
KAV$K_LONGWORDvalues.

virtual_address
Usage:
Longword (unsigned)
VAX Type:
longword_unsigned
Access:
Read only
Mechanism:

Value

Specifies the virtual address, in SO space, where you want to begin writing
data. To calculate the address, follow these steps:
e

Calculate the base address of the VMEbus or VSB device that you want to
write to. The KAV$OUT_MAP service returns the base VMEbus or VSB
address of a device. See the description of the KAV$OUT_MAP service for
more information.

e
e

Calculate the offset, into the device’s address space, that you want to write

to.

Add the address to the offset.

When you write data to a FIFO buffer on another KAV30, use the following
offsets when calculating the address:
FIFO Buffer

Offset

400016

40101¢

402016

403016

KAV30 System Services 4—27

KAV$BUS_WRITE

When you write data to a LIFO buffer on another KAV30, use the following
offsets when calculating the address:
LIFO Buffer

Offset

0)
1
2
3

40401¢
405016
406016
407016

buffer
Usage:
VAX Type:

Longword (unsigned)
longword_unsigned

Access:

Read only

Mechanism:

Reference

Specifies the addressof the buffer of data that the KAV$BUS_WRITEservice
writes to the VMEbus or VSB.
count

Usage:
VAX Type:
Access:

Mechanism:

Longword (unsigned)
longword_unsigned
Read only

Value

Specifies the number of data items (of the type specified by the data_type
argument) that the KAV$BUS_WRITEservice writes to the VMEbusor VSB.

Status Values
KAV30$BADPARAM

You did not specify a parameter in the correct
format.

KAV30$BUSWRTERROR

A VMEbusor a VSBwrite error occurred.

KAV30$BUSARBERROR

A VMEbus or VSB arbitration failure occurred.

KAV30$_INVALID_SG.__
ENTRY

You specified an invalid SGM entry.

KAV30$_NO_BUS_WRT_

There was no write response from the device.

RESP

4-28 KAV30 System Services

KAV$BUS_WRITE
KAV30$_WRPROT_SG_

You tried to write to a write-protected SGM

KER$_BAD_COUNT

You did not specify the correct number of

KER$BADVALUE

You did not specify a value in the correct

KER$NOACCESS

The services could not access an item.

KER$SUCCESS

The operation was successful.

ENTRY

entry.

arguments.

format.

Related Services
KAV$BUS_BITCLR
KAV$BUS_BITSET

KAV$0OUT_MAP
KAV$BUS_READ

Examples
The following code is an example KAV$BUS_WRITEcall:
viraddress
buffer

KAVSBUSWRITE

WH OG NO Fe

CALL

= virtualaddress + '3601'X
= '13'X

1040

(status,
sVAL (datatype),
SVAL(vir address),

buffer,

IF ( .NOT. status }
FORMAT (1H,

$VAL (count) )
TYPE 1040, status

'KAVSBUSWRITE,

status is

:’,

24.4 )

The file SYSSCOMMON:[SYSHLP.EXAMPLES.KAV]KAV_MVME.FOR
contains a program that calls the KAV$BUS_WRITEservice

KAV30 System Services 4-29

KAV$CHECK_BATTERY

KAV$CHECK_BATTERY
Checks the power supply to the battery backed-up RAM andthe calendar/clock.
The power supply to the battery backed-up RAM and calendar/clock can be one
of the following:
e

Sufficient

Whenthe power supply to the relevant devicesis sufficient, the devices
have enough powerto operate normally.
e

Dead

When the power supply to the relevant devices is dead, the devices do
not have enough powerto operate normally. The contents of the relevant
devices are unpredictable.

Ada Call Format

WITH KAVDEF:
KAV_CHECKBATTERY (STATUS =>status);
argumentinformation
status :

4-30

KAV30 System Services

out

CONDITION.HANDLING.COND_VALUE_
TYPE;

KAV$CHECK_BATTERY

C Call Format
#include $vaxelnc
#include "eln$:kavdef.h"

int kav$check_battery (status)

argument information
int

*status;

FORTRANCall Format

INCLUDE ’ELN$:KAVDEF.FOR’
CALL KAV$CHECK_BATTERY (status)
argumentinformation
INTEGER*4

status

Pascal Call Format

INCLUDE $KAVDEF:
KAV$CHECK_BATTERY (STATUS:= status)
argumentinformation
status :

INTEGER;

KAV30 System Services 4-31

KAV$CHECK_BATTERY

Arguments
status

Usage:

VAX Type:
Access:

Mechanism:

Longword (unsigned)

cond_value
Write only
Reference

Receives the completion status.

Status Values
KAV30$_BAD_BATTERY
KAV30$_BAD_PARAM

The KAV30battery is dead.
You did not specify a parameter in the correct

KER$_BAD_COUNT

You did not specify the correct number of

KER$_BAD_VALUE

You did not specify a value in the correct
format.

KER$_SUCCESS

The operation was successful.

format.

arguments.

Examples
e

The file SYS$COMMON:[SYSHLP.EXAMPLES.KAV]JKAV_MVME.FOR
contains a program that calls the KAV$CHECK_BATTERYservice

4-32 KAV30 System Services

KAVS$CHECK_BATTERY

The following code is an example KAV$CHECK_BATTERYcall:
CALL

KAVSCHECK BATTERY (status)

IF ( .NOT. status)

100

FORMAT (1H,

buffer

TYPE 100, status

‘KAVSCHECKBATTERY status is

= '00000000’X

:’,Z4.4 )

setupfunction = KAV$KALLOWVMEIRQ

CALL

1000

KAVSVME_SETUP

(status,

sVAL (setupfunction),
buffer)
IF ( .NOT. status )
TYPE 1000, status
FORMAT (1H, ’KAVSVMESETUP status is :’,24.4 )

KAV30 System Services 4-33

KAV$CLR_AST

KAV$CLR_AST
Clears a device’s AST queue. The service clears all the ASB data structures
and removes any pending ASTs.
This service uses the device code returned by the KAV$DEF_ASTservice to
identify the AST queueto clear.
You can also use this service to remove any ASTs that are pending as a result
of a call to the KAV$SET_ASTservice that specified a repeating AST. See the
description of the KAV$SET_ASTservice for more information.

Ada Call Format
WITH KAVDEF;
KAV_CLR_AST ([STATUS => status,]
DEVICE_CODE => device_code);

argument information
status:

out

device_code:

CONDITION_HANDLING.COND_VALUE_

TYPE;

INTEGER;

C Call Format
#include $vaxelnc
#include "eln$:kavdef.h"

int kav$clr_ast ([status],
device_code)

argumentinformation
int

*status;

int

device_code;

4-34 KAV30 System Services

KAV$CLR_AST

FORTRAN Call Format
INCLUDE ’ELN$:KAVDEF.FOR’

CALL KAV$CLR_AST [status],

%VAL(device_code))

argumentinformation
INTEGER*4

status

INTEGER*4

device_code

Pascal Call Format

INCLUDE $KAVDEF:
KAV$CLR_AST ([STATUS:= status,]
device_code)

argumentinformation
status :

INTEGER;

device_code:

INTEGER;

Arguments
status

Usage:
VAX Type:
Access:

Longword (unsigned)
cond_value
Write only

Mechanism:

Reference

Receives the completion status.

KAV30 System Services 4-35

KAV$CLR_AST
device_code

Usage:
VAX Type:
Access:

Mechanism:

Longword (unsigned)
longword_unsigned
Read only

Value

Specifies a code that identifies the AST queue to clear. Use the code that the
KAV$DEF_ASTservice returned when you defined the AST queue.

Status Values
KAV30$BADPARAM

You did not specify a parameter in the correct
format.

KER$BADCOUNT

You did not specify the correct number of
arguments.

KER$BADVALUE

You did not specify a value in the correct

KER$_SUCCESS

The operation is successful.

format.

Related Services
KAV$DEF_AST
KAV$SET_AST

4-36 KAV30 System Services

KAV$QUE_AST

KAV$DEF_AST

KAV$DEFAST
Creates an AST queue for an event associated with a VMEbus or VSB device.

It allocates the first available AST queue to the device event and returns a
device code.

Whenyou call the KAV$CLR_AST, KAV$QUE_AST, or KAV$SET_ASTservices
in relation to the device event, use the device code to identify the AST queue.
Call this service only once for each device event.

The KAV30 kernel sets up 256 AST queues, 37 of which are reserved for use
by the KAV30. This leaves a total of 219 queues available for VMEbus or VSB
devices.
See Section 3.1 for more information on ASTs.

Ada Call Format
WITH KAVDEF;

KAV_DEFAST ([STATUS => status,]

DEVICE_CODE => device_code);

argumentinformation
status:

out

CONDITION_HANDLING.COND_VALUE_
TYPE;

device_code:

INTEGER;

C Call Format
#include $vaxelnc
#include "eln$:kavdef.h"

int kavédef_ast ([status],
device_code)

KAV30 System Services 4-37

KAV$DEF_AST

argumentinformation
int

*status;

int

*device_code;

FORTRAN Call Format

INCLUDE ’ELN$:KAVDEF.FOR’
CALL KAV$DEFAST ([status],

device_code)

argumentinformation
INTEGER*4
INTEGER*4

status
device_code

Pascal Call Format

INCLUDE $KAVDEF:
KAV$DEF_AST ([STATUS := sfatus,]
device_code)

argumentinformation

4-38

status :

INTEGER;

device_code:

INTEGER;

KAV30 System Services

KAVS$DEF_AST

Arguments
status

Usage:

Longword (unsigned)

VAX Type:
Access:

longword_unsigned
Write only

Mechanism:

Reference

Receives the completion status.
device_code

Usage:
VAX Type:

Longword (unsigned)
longword_unsigned

Access:

Write only

Mechanism:

Reference

Returns a code that identifies the AST queue. Use this code to identify the
queue whencalling the KAV$CLR_AST, KAV$QUE_AST, and KAV$SET_AST
Services.

Status Values
KAV30$_ASBQUOTA

You have reached the maximum numberof

KAV30$_BAD_PARAM

ASBsfor this device code.
You did not specify a parameter in the correct

KER$_BAD_COUNT

You did not specify the correct number of

KER$_BAD_VALUE

You did not specify a value in the correct

KER$_SUCCESS

The operation is successful.

format.

arguments.

format.

KAV30 System Services 4-39

KAV$DEF_AST

Related Services
KAV$CLR_AST
KAV$QUE_AST

KAV$SET_AST

Examples
See the programs listed in Appendix C for examples of KAV$DEF_AST
service calls.

4-40 KAV30 System Services

KAV$FIFO_READ

KAV$FIFO_READ
Reads a specified number of aligned longwords from one of the KAV30 FIFO

buffers.

Whenyou read data from a FIFO buffer on another KAV30, use the following
offsets when calculating the address to read from:
FIFO Buffer

Offset

4000i¢

401016

40201¢

40301¢

See Section 3.4 for information about the KAV30 FIFO buffers.

Ada Call Format
WITH KAVDEF:

KAV_FIFOREAD ([STATUS => status]
FIFO_NUMBER => fifo_number
BUFFER => buffer,
COUNT => count);

argumentinformation
status:

CONDITION_HANDLING.COND_VALUE_
TYPE;

fifo_number:
buffer:

INTEGER;

count :

SYSTEM.ADDRESS;
INTEGER;

KAV30 System Services 4—41

KAV$FIFO_READ

C Call Format
#include $vaxelnc
#include "eln$:kavdef.h"

int kav$fifo_read ([status],

fifo_number,

buffer,
count)

argumentinformation
int

*status;

int

fifo_number;

int

“buffer;

int

count;

FORTRANCall Format
INCLUDE 'ELN$:KAVDEF.FOR’
CALL KAV$FIFO_READ

([status],
%VAL(fifo_number\,
buffer,
%WAL(count))

argumentinformation
INTEGER*4
INTEGER*4

status
fifo_number

INTEGER*4

buffer

INTEGER*4

count

4-42 KAV30 System Services

KAV$FIFO_READ

Pascal Call Format
INCLUDE $KAVDEF;
KAV$FIFO_READ ([STATUS:= status,]
fifo_number,
buffer,

count)

argumentinformation
status :

INTEGER;

fifo_number:
buffer:

INTEGER;
AANYTYPE;

count:

INTEGER;

Arguments
status

Usage:
VAX Type:
Access:

Mechanism:

Longword (unsigned)
cond_value
Write only
Reference

Receives the completion status.
fifo_number
Usage:

VAX Type:

Access:
Mechanism:

Longword (unsigned)
longword_unsigned

Read only

Value

Specifies the FIFO buffer to read from. Specify one of the following values:
KAV$K_FIFO_0
KAV$K_FIFO_1
KAV$KFIFO2
KAV$KFIFO3

Reads data from FIFO number0
Reads data from FIFO number1
Reads data from FIFO number2
Reads data from FIFO number3

KAV30 System Services 4-43

KAV$FIFO_READ
buffer
Usage:
VAX Type:

Longword (unsigned)
longword_unsigned

Access:

Write only

Mechanism:

Reference

Specifies the buffer into which this service places the data (in aligned
longwords) it reads from the FIFO buffers.
count

Usage:
VAX Type:
Access:

Mechanism:

Longword (unsigned)
longword_unsigned
Read only

Value

Specifies the numberof aligned longwords to read from the FIFO buffer.

Status Values
KAV30$_BAD_PARAM

You did not specify a parameter in the correct

KER$BADCOUNT

You did not specify the correct number of
arguments.

KER$BADVALUE

You did not specify a value in the correct

KER$COUNT_OVERFLOW
KER$NO_ACCESS
KER$SUCCESS

There is a FIFO counteroverflow.
The services cannot access an item.
The operation is successful.

format.

Related Services
KAV$FIFO_WRITE
KAV$LIFO_WRITE

4-44 KAV30 System Services

KAV$NOTIFY_FIFO

KAV$FIFO_READ

Examples
See the programslisted in Appendix B for examples of KAV$FIFO_READ
service calls.

KAV30 System Services 4-45

KAV$FIFO_WRITE

KAVS$FIFO_WRITE
Writes a specified number of aligned longwords to one of the KAV30 FIFO
buffers in FIFO mode.
When you write data to a FIFO buffer on another KAV30, use the following
offsets when calculating the address to write to:
FIFO Buffer

Offset

400016

401016

402016

403016

See Section 3.4 for information about the KAV30 FIFO buffers.

Ada Call Format

WITH KAVDEF:
KAV_FIFO_WRITE ((STATUS => status,]
FIFO_NUMBER => fifo_number,
BUFFER => buffer,

COUNT => count);

argumentinformation
status :

out

fifo_number:

INTEGER;

buffer :

SYSTEM.ADDRESS;

count :

INTEGER;

4-46 KAV30 System Services

CONDITION_HANDLING.COND_VALUE._

TYPE;

KAV$FIFO_WRITE

C Call Format
#include $vaxelnc
#include "eln$:kavdef.h"

int kav$fifo_write ([status],

fifo_number,

buffer,
count)

argumentinformation
int

*status;

int

fifo_number;

void

*buffer;

int

count;

FORTRANCall Format
INCLUDE ’ELN$:KAVDEF.FOR’

CALL KAV$FIFOWRITE ([status],
%VAL(fifo_number),
buffer,
%VAL(count))

argument information
INTEGER*4

status

INTEGER*4
INTEGER*4

fifo_number
buffer

INTEGER*4

count

KAV30 System Services 4-47

KAV$FIFO_WRITE

Pascal Call Format

INCLUDE $KAVDEF:
KAV$FIFO_WRITE ([STATUS:= status,]
fifo_number,
buffer,

count)

argument information
status:

INTEGER;

fifo_number:

INTEGER;

buffer:

AANYTYPE;

count:

INTEGER;

Arguments
status

Usage:
VAX Type:
Access:

Longword (unsigned)
cond_value
Write only

Mechanism:

Reference

Receives the completion status.
fifo_number
Usage:
VAX Type:
Access:
Mechanism:

Longword (unsigned)
longword_unsigned
Read only
Value

Specifies the FIFO buffer that you want to write to. Specify one of the following
values:

4-48 KAV30 System Services

KAV$FIFO_WRITE

KAV$KFIFO_0
KAV$K_FIFO_1
KAV$K_FIFO2
KAV$K_FIFO_3

Writes data to FIFO number0
Writes data to FIFO number 1
Writes data to FIFO number2
Writes data to FIFO number 3

buffer
Usage:

Longword (unsigned)

Access:

Read only

Mechanism:

Reference

VAX Type:

longword_unsigned

Specifies the buffer of data that this service writes (in aligned longwords) into
the FIFO buffer.
count

Usage:

Longword (unsigned)

Mechanism:

Value

VAX Type:
Access:

longword_unsigned
Read only

Specifies the numberof aligned longwords that this service writes into the

FIFO buffer.

Status Values
KAV30$_BAD_PARAM

You did not specify a parameter in the correct

KER$BADCOUNT

You did not specify the correct number of
arguments. —

KER$BADVALUE

You did not specify a value in the correct

KER$COUNT_OVERFLOW

Thereis a FIFO counter overflow.

KER$NO_ACCESS

The services cannot access an item.

KER$_SUCCESS

The operation is successful.

format.

KAV30 System Services 4—49

KAV$FIFO_WRITE

Related Services
KAV$FIFO_READ
KAV$LIFO_WRITE

KAV$NOTIFY_FIFO

Examples
See the programslisted in Appendix B for examples of KAV$FIFO_WRITE

service calls.

4-50 KAV30 System Services

KAV$GATHER_KAV_ERRORLOG
KAVS$GATHER_KAV_ERRORLOG
Reads the error log entries from the error-log area of the KAV30 battery
backed-up RAM.
Whencertain error conditions occur in devices on the KAV30, VMEbus, or

VSB, the KAV30 kernel writes an error code to its battery backed-up RAM. See
Section 3.8 for more information.

Ada Call Format

WITH KAVDEF;
KAV_GATHERKAV_ERRORLOG ([STATUS => status,]
ERRORLOG_FUNCTIONS => errorlog_functions,
BUFFER => buffer);
ENTRY_COUNT => entry_count);

argumentinformation
status:

out

CONDITIONHANDLING.COND_VALUE.
TYPE;

errorlog_functions

INTEGER;

buffer:

SYSTEM.ADDRESS;

entry_count:

INTEGER;

C Call Format
#include $vaxelnc
#include "eln$:kavdef.h"

int kav$gather_kav_errorlog [status],
errorlog_functions,
buffer,
entry_count)

KAV30 System Services 4—51

KAV$GATHER_KAV_ERRORLOG

argumentinformation
int

*status;

int

errorlog_functions;

void

*buffer;

int

entry_count;

FORTRAN Call Format
INCLUDE ’ELN$:KAVDEF.FOR’
CALL KAV$GATHER_KAV_ERRORLOG [status],
%NAL(errorlog_functions),
buffer,
%VAL(entry_count))

argumentinformation
INTEGER*4
INTEGER*4
INTEGER*4
INTEGER*4

status

errorlog_functions
buffer
entry_count

Pascal Call Format

INCLUDE $KAVDEF;
KAV$GATHER_KAV_ERRORLOG ([STATUS := stfatus,]
errorlog_functions,
buffer,
entry_count)

4-52 KAV30 System Services

KAV$GATHER_KAV_ERRORLOG

argumentinformation
status:

INTEGER;

errorlog_functions:
buffer :

INTEGER;
AANYTYPE;

entry_count:

INTEGER;

Arguments
status

Usage:
VAX Type:
Access:

Longword (unsigned)
longword_unsigned
Write only

Mechanism:

Reference

Receives the completion status.
errorlogfunctions
Usage:
Longword (unsigned)
VAX Type:
§Longword_unsigned
Access:
Read only
Mechanism:

Value

Specifies the operation that you want to perform. Specify one of the following
values:
KAV$K_CLEARERR
KAV$K_INIT_RD_POINTER

Initializes all the error log data and pointers
Sets the error log read entry pointer to the
value of the error log write entry pointer

KAV$KMASTERERR

Gathers the error log entries that were caused
by the master VMEbus and VSB accesses

KAV$K_SLAVE_ERR
KAV$K_ALLERR

Gathers the error log entries that were caused

by the slave VMEbusaccesses

Gathers the error log entries that were caused

by slave and master accesses

KAV30 System Services 4-53

KAV$GATHER_KAV_ERRORLOG
buffer
Usage:
VAX Type:
Access:

Longword (unsigned)
longword_unsigned
Write only

Mechanism:

Reference

Specifies the address of a buffer to which the service returns the error log

entries. The service returns one 28-byte buffer segment for each error log

entry it returns. The buffer you specify must be long enough to return 28-byte
segments for each error log entry you want to read. The numberof error log
entries you want to read is specified in the entry_count parameter. When the
buffer area is not long enough, the kernel will return an error status.
The contents of the buffer segment detailing an error log entry depend on
whether you read a master error or a slave error. Master errors have the
following layout:
MessageStatus Code
AM

Retry

VMEbus/VSB Address

PSL

Absolute System
Time

4-54 KAV30 System Services

20
24

KAV$GATHER_KAV_ERRORLOG

Slave errors have the following layout:
Message Status Code

Error Status

Error Count

Reservedfor Digital

Absolute System

Time

entry_count

Usage:
VAX Type:
Access:
Mechanism:

Longword (unsigned)
Longword_unsigned
Read only
Value

Specifies the numberof error log entries that you want to read from the battery
backed-up RAM.

Status Values
KAV30$_BAD_PARAM

You did not specify a parameter in the correct

KAV30$_END_OF_
ERRORLOG
KAV30$_ERRORLOG_
EMPTY
KER$_BAD_COUNT

You have reached the end of the KAV30 error
log area.

format.

There is no error of the type that you specified
in the error log area.
You did not specify the correct numberof arguments.

KAV30 System Services 4—55

KAV$GATHER_KAV_ERRORLOG
KER$BADVALUE

You did not specify a value in the correct
format.

KER$NO_ACCESS
KER$_SUCCESS

The services cannot access an item.
The operation is successful.

Examples
The following code is an example program that calls the KAV$6GATHER_

KAV_ERRORLOGservice:
/*
*

Facility:

KAV30 VAXELN System Services programming example.

*
*

Description:

This is an example program demonstrating the calling
procedures for the following KAV System Services:

x
x

1.
2.

KAVSOUTMAP
KAVSBUSREAD

KAVSGATHERKAVERRORLOG

(Map onto VMEbus address)
(Read from VMEbus address)
(Read KAV error log)

*
*

Abstract:

This program induces a KAV error condition, then requests
the error log.

Language:

Vax C; Version 3.1

*
*

Notes:

In the interests of program clarity, no error checking has
been included.

(1)

#include
#include
#include

stdio
Svaxelnc
<elnS:kavdef.h>

KAV30 definitions file.

#define

INVALIDADDRESS Oxddeeff

Non-existent address for error. */

main ()

{

unsigned long
unsigned long’

amcode,

unsigned long
int

buff[4]
entry,

;

/* ...to receive the error report.

viraddr,

devicecode,
phys addr ;

*badaddress ;

status,

pagecount,

mapfunctions ;

4-56 KAV30 System Services

KAV$GATHER_KAV_ERRORLOG
/*
x

Map into the device register region.

pagecount

= 1;

physaddr
am code

= INVALIDADDRESS ;
= KAVSK USER 24 ;

mapfunctions
KAVSOUTMAP(
/*
x

KAVS$MVME+KAVSMMODE0SWAP;

&status, &entry, pagecount,

physaddr, &viraddr,
amcode, mapfunctions);

READ from the VMEbus

(this should induce an error).

KAVSBUSREAD(

éstatus,
KAVSK_BYTE,

viraddr,

buff,

1) ;

/*
*

Request error report

*/
devicecode = KAVSKALLERR ;

KAVSGATHERKAV_ERRORLOG ( &status,
devicecode,

buff ) ;

KAV error code

} /*

end

VME/VSB error code
-program-

(%x hex)/n",

buff[1], buff{[1

Sd (% x hex)/n", buff[2], buff[2
$d (% x hex)/n", buff{3], buff[3

printf("

$d (3x hex)/n", buff[0], buff[0

Error Count
Address of last error

printf("
printf("

printf ("\n\nKAV Error report: /n");

);
);
);
);

KAV30 System Services 4-57

KAVSIN_MAP

KAVS$IN_MAP
Mapsone or more 64K byte pages (aligned on a 64K byte boundary) of the
VMEbusaddress space into KAV30 process (PO) space or into the FIFO buffers
on the KAV30.
This service uses the incoming SGM to perform the mapping. See Section 3.6
for more information.

The programscalling the KAV$IN_MAPservice specify the SGM entry number
for the first page of the VMEbus address space mapped into the KAV30
PO space. These programs subsequently use this numberin a call to the
KAV$UNMAFP service to free pages of KAV30 PO space when mappingis no
longer required. The SGM entry must be in the range 0 to 15 for A24 mode
VMEbusaddresses and in the range 0 to 255 for A32 mode VMEbusaddresses.
A calling program can set a modifier that forces the KAV30 to interrupt the
kernel if any VMEbus device accesses the part of the VMEbus address space
mapped by the incoming SGM map to KAV30 PO space. The kernel then
queues an ASTto the process that called the KAV$IN_MAP service. This
function is called a location monitor. The location monitor also specifies the
interrupt priority level at which the KAV30 kernel delivers the interrupt.
The KAV30 kernel can also set write protection on the pages of PO space to
which the VMEbus address space is mapped. This prevents the VMEbus
devices from accidentally writing the part of the VMEbus address space
mapped to the KAV30 PO space.
The KAV30is a little-endian device, so to exchange data with a big-endian

device, you must translate the data from big-endian formatto little-endian

format. This service can map the address space directly to KAV30 PO space, or
it can specify byte-swapping or word-swapping as part of the mapping. When
a VMEbusdevice subsequently reads or writes the VMEbus address space, the
address space mapped into the KAV30 PO space is transformed according to
the swapping operations specified by this service. See Section 3.6.3 for more
information about data mapping.

4-58 KAV30 System Services

KAVSIN_MAP

Ada Call Format
WITH KAVDEF;

KAV_INMAP ([STATUS =>status]

SGM_ENTRY => sgm_entry,
PAGE_COUNT => page_count,

VIRTUAL_ADDRESS => virtual_address,

[AST_ADDR => ast_adar,]
[AST_PARAM => ast_param,]

MAP_FUNCTIONS => map_functions);

argumentinformation
Status :

out

sgm_entry :

page_count:

virtual_address:
ast_addr:

out
in

ast_param :

map_functions:

CONDITION_HANDLING.COND_VALUE_

TYPE;

INTEGER;
INTEGER;
SYSTEM.ADDRESS;
SYSTEM.ADDRESS;
INTEGER;
INTEGER;

C Call Format
#include $vaxelnc
#include “eln$:kavdef.h"

int kav$in_map

([status],

entry,

page_count,

virtual_address,

[ast_adar),
[ast_paran],
map_functions)

KAV30 System Services 4~59

KAVS$IN_MAP
argumentinformation
int

"status;

int

entry;

int

page_count;

void

**yirtual_address;

void

*ast_addr( );

int

ast_param;

int

map_functions;

FORTRAN Call Format
INCLUDE ’ELN$:KAVDEF.FOR’
CALL KAV$IN_MAP

([status],

%VAL(entry),
%VAL(page_count),
virtual_address,

[ast_addrj,
[%VAL(ast_param)],
%WVAL(map_functions))

argumentinformation
INTEGER*4
INTEGER*4
INTEGER*4
INTEGER*4
INTEGER*4
INTEGER*4
INTEGER*4

4-60 KAV30 System Services

status
entry
page_count

virtual_address
ast_addr
ast_param

map_functions

KAVS$IN_MAP

Pascal Call Format

INCLUDE $KAVDEF;
KAV$INMAP ([STATUS:= status,]
entry,
page_count,
virtual_address,

[AST_ADDR := ast_adar,]
[AST_PARAM := ast_param,]
map_functions)

argumentinformation
status :

INTEGER;

entry :

INTEGER;

page_count:

INTEGER;

virtual_address:

AANYTYPE;

ast_addr:

AANYTYPE;

ast_param :

INTEGER;

map_functions:

INTEGER;

Arguments
status

Usage:
VAX Type:

Longword (unsigned)
cond_value

Access:

Write only

Mechanism:

Reference

Receives the completion status.
entry

Usage:
VAX Type:

Access:
Mechanism:

Longword (unsigned)
longword_unsigned

Read only
Value

KAV30 System Services 4-61

KAVS$IN_MAP

Specifies one of the following:
e
e

The SGM entry numberfor the first page of VMEbusaddress space that
you want to map into KAV30 PO space

The SGM entry numberfor the first page of VMEbus address space that

you want to map into the KAV30 FIFO buffers

page_count
Usage:
VAX Type:
Access:

Mechanism:

Longword (unsigned)
longword_unsigned
Read only

Value

Specifies the number of successive 64K byte pages of data that you want to
map.
virtual_address
Usage:
Longword (unsigned)
VAX Type:
longword_unsigned
Access:
Write only
Mechanism:

Reference

Returns the virtual address in KAV80 PO space that correspondsto the starting
address of the 64K byte page of VMEbus address space. This service does not
return a virtual address if the map_functions argument has the value KAV$M_
CSR.
ast_addr
Usage:

Procedure entry mask

Mechanism:

Reference

VAX Type:
Access:

procedure
Read only

When you enable the location monitor in the map_functions argument, this
argument specifies the address of the AST routine that the KAV30 kernel
executes whenever a device reads to or writes from the pages that you want to
map. See Section 3.1 for more information about ASTs.

ast_param

Usage:
VAX Type:
Access:

Mechanism:

Longword (unsigned)
longword_unsigned
Read only
Value

Specifies the parameter that you want to pass to the AST routine.

4-62 KAV30 System Services

KAVS$IN_MAP
map_functions
Usage:
Longword (unsigned)
VAX Type:
mask_longword
Access:
Read
Mechanism: Value
Specifies the following information that controls the mapping operation:
e

The mapping direction—whether you want to map pages of VMEbus
address space into the KAV30 PO space or into the KAV30 FIFO buffers

The location monitor

The byte swapping mode

The write-protection of a mapped area

Specify one or more of the following modifiers:
KAV$MLOCMON_IPL15

Interrupts at IPL 154¢.

KAV$MLOCMON_IPL16

Interrupts at IPL 16j¢.

KAV$MLOCMON_IPL17

Interrupts at IPL 17 4¢.

KAV$M_CSR

Maps data from the VMEbus address space

into one of the KAV30 FIFO buffers. If you
do not supply this modifier, the KAV30 kernel
maps VMEbus address space into the KAV30
PO space.

KAV$M_MEMORY

Maps the VMEbus address space into the
KAV30 PO space.

KAV$M_MODE_0SWAP
KAV$M_MODE_2_SWAP
KAV$MMODE3SWAP
KAV$M_WRT_PROT

Performs mode 0 swapping.
Performs mode 2 swapping.
Performs mode 3 swapping.
Sets write-protection on the page of the system
RAM that you want to map to the VMEbus.

Ensure that the values you specify do not conflict with each other. For
example, do not specify the KAV$M_MODE_3_SWAP and KAV$M_MODE_0_
SWAP values together.

KAV30 System Services 4—63

KAVSIN_MAP

Status Values
KAV30$_BAD_MODIFIER

You did not specify a modifier in the correct

KAV30$_BAD_PARAM

You did not specify a parameter in the correct

KER$_BAD_COUNT

You did not specify the correct number of

KER$_BADVALUE

You did not specify a value in the correct
format.

KER$_NO_ACCESS
KAV$_NO_MEMORY
KER$_NO_PORT

The service cannot access an item.

KAV$_NO_VIRTUAL
KER$_SUCCESS

Related Services
KAV$UNMAP

4-64 KAV30 System Services

format.
format.

arguments.

There is no physical memory available.
There are no free SGM entry ports. Unmap

one or more SGM entries andretry thecall.

There is no virtual address space available.

The operation is successful.

KAVS$IN_MAP

Examples
The following code is an example program that calls the KAV$IN_MAP
service:

C
C
C
C
C
C
C
C
C
C
C
C
C
C

Description: This is an example program demonstrating the calling
procedures for the following KAV System Services:
1. KAVSINMAP (Map VMEbus address space into PO space)
2. KAVSUNMAP
(Free Scatter Gather Map [SGM])
Abstract:

Maps an area of PQ space, then relinquishes it.

Language:

Vax Fortran; Version 5.5

Notes:

In the interests of program clarity, no error checking
is performed.

(1)

PROGRAM EXMAPPING
IMPLICIT NONE
INCLUDE 'ELNS$:KAVDEF .FOR’
INTEGER*4
INTEGER* 4
INTEGER*4
INTEGER*4
INTEGER*4

status
entry
pagecnt
viraddr
physaddr

INTEGER*4

mapfunctions

INTEGER*4

index

INTEGER*4

amcode

Example of ***
pagecnt
index = 1
entry =1

mapfunctions

INMAP

***

(without AST parameters)

= ]

KAVSMCSR + KAVSMLOCMONIPL17 +KAVSMWRTPROT

Oy OF1 & W NF

CALL

KAVSINMAP (status,
sVAL (entry),
oVAL (pagecnt) ,

viraddr,
I
i

sVAL (mapfunctions) )

KAV30 System Services 4-65

KAVS$IN_MAP

Example of ***

UNMAP

mapfunctions = KAV$MIN
CALL
1
2
3
4
9999

KAVSUNMAP (status,
oVAL (entry),
oVAL (pagecnt) ,
sVAL(viraddr),
sVAL(mapfunctions) )
STOP

END

4-66 KAV30 System Services

***

KAVSINT_VME

KAVSINT_VME
Delivers an IRQ to the VMEbus, reads pending IRQs on the KAV30, or clears

any pending VMEbusinterrupts.

The int_functions argument specifies whether this service delivers, reads, or
clears interrupts. The irg_level argument specifies the IRQ level, and the int_
vector argument specifies the VMEbusinterrupt vector.

The irq_level argumentis a bit mask (only the low-order byte is used). The

bit mask specifies the IRQ level at which you want to generate the IRQ. For

example, the following diagram showsa bit mask that specifies a level 5 IRQ:
7

20 (hexadecimal)

t Reserved, must be zero

The int_vector argumentis a value that uses only the low-order byte of the
argument. This value specifies the interrupt vector that the KAV30 uses to
interrupt the VMEbus. For example, the following diagram shows an interrupt
vector that has the value 34 (hexadecimal):
7

34 (hexadecimal)

t Reserved, must be zero

The KAV30 constructs the vector with which it interrupts the VMEbus module

KAV30 System Services 4—67

KAV$INT_VME
in the following steps:
1.

The KAV30 decodes the IRQ level in the irg_level argumentinto its binary
value and places this value in the 3 low-order bits of the VMEbusvector,
as follows:
7

IRQ Level 5 = 101 (binary)

The KAV380 places the value specified by the int_vector argument in the 5
high-order bits of the VMEbusvector, as follows:

34 (hexadecimal)

Steps 1 and 2 result in the following VMEbusvector:
7

3D (hexadecimal)

To place a particular vector on the VMEbus,follow these steps:
1.
2.
3.

Place the binary representation of the IRQ level in the 3 low-orderbits
Fill in the other 5 bits with the values required to give the specific

interrupt vector

Place these values in the int_lul and int_vector argumentsrespectively.

If the int_functions argumentspecifies the value KAV$K_RD,this service uses
this method to return the IRQ level in the irq_level argument and the interrupt
vector value in the int_vector argument.
The programs that use this service to generate interrupt requests at a

particular level must configure the KAV30 so that incoming VMEbus
interrupts at that level are disabled. See Section 5.4 and the description of
the KAV$VME_SETUPservice for information about configuring the VMEbus.

4-68 KAV30 System Services

KAV$INT_VME

Ada Call Format

WITH KAVDEF:

KAV_INTVME ([STATUS => status]

INTFUNCTIONS => int_functions,
IRQ_LEVEL => irq_level,
INTVECTOR => int_vecton);

argument information
status:

out

CONDITION_HANDLING.COND_VALUE_

int_functions:

INTEGER;

irq_level:

in out

INTEGER;

int_vector:

in out

INTEGER;

TYPE;

C Call Format
#include $vaxelnc
#include "eln$:kavdef.h"
int kav$int_vme

([status,]

int_functions,

irq_level,
int_vector)

argument information
int

*status;

int
int

int_functions;
*irq_level;

int

*int_vector;

KAV30 System Services 4-69

KAVSINT_VME

FORTRANCall Format

INCLUDE 'ELN$:KAVDEF.FOR’
CALL KAVSINTVME ([status],

%VAL(int_functions),
irq_level,
int_vector)

argumentinformation
INTEGER*4

status

INTEGER*4
INTEGER*4

int_functions
irq_level

INTEGER*4

int_vector

Pascal Call Format
INCLUDE $KAVDEF;
KAVSINTVME ([STATUS := status,]
int_functions,

irq_level,

int_vector)

argument information
status:

INTEGER;

int_functions:
irq_level:

INTEGER;
INTEGER;

int_vector:

INTEGER;

4-70 KAV30 System Services

KAVS$INT_VME

Arguments
status
Usage:

Longword (unsigned)

Access:

Write only

Mechanism:

Reference

VAX Type:

cond_value

Receives the completion status.

int_functions
Usage:
Longword (unsigned)
VAX Type:
longword_unsigned
Access:
Read only
Mechanism:

Value

Specifies the function that you want to perform. Specify one of the following
values:
KAV$K_RD

Reads the IRQ currently pending on the
KAV30 and returns the interrupt vector (in
the int_vector argument) and the interrupt
level (in the irg_level argument).

KAV$KVME_INTCLR

Clears the interrupts that are currently
pending on the KAV30.

KAV$K_VME_REQINT

Requests an interrupt at the IRQ level
specified by the irg_level argument.

irqlevel

Usage:
VAX Type:
Access:

Longword (unsigned)
longword_unsigned
Modify

Mechanism:

Reference

If the int_functions argumentspecifies the value KAV$K_VME_REQ_INT,this
argument specifies the VMEbus IRQ level at which you want to generate an
TRQ on the VMEbus.

KAV30 System Services 4-71

KAVS$INT_VME
The irg_level argument is a bit mask. However, this service uses only the
low-order byte of the bit mask. The bit mask specifies the IRQ level at which

you want to generate the IRQ,as follows:
7

=¢6-1

AIALATATATLALATLA
Reserved, must be zero
Generate IRQ at IRQ Level1
Generate IRQ at IRQ Level 2
Generate IRQ at IRQ Level 3

Generate IRQ at IRQ Level 4
Generate IRQ at IRQ Level 5
Generate !RQ at IRQ Level 6
Generate IRQ at IRQ Level 7

If the int_functions argument specifies the KAV$K_RD value, the KAV$INT_
VMEservice returns the IRQ level in this argument.
It is not necessary to specify an IRQ level when clearing an interrupt.

Therefore, if the int_functions argument has the value KAV$K_VME_INT_

CLR, you can omit the irq_level argument.
int_vector
Usage:

Longword (unsigned)

VAX Type:
Access:

longword_unsigned
Modify

Mechanism:

Reference

Specifies the VMEbus vector that the KAV30 writes to the VMEbus when the
KAV30 receives an JACK signal from the VMEbus. The int_vector argument
is a value in which the 3 low-order bits must be 0, and the 5 high-order bits
contain the 5 high-order bits of the VMEbusinterrupt vector.
If the int_functions argument has the value KAV$K_RD, the KAV$INT_VME
service returns the interrupt vector, for the IRQ currently pending on the
KAV30, in the low-order byte of the int_vector argument. However, it is not

possible to decode the 3 low-orderbits.

4-72 KAV30 System Services

KAVSINT_VME

Status Values
KAV30$_BAD_MODIFIER

You did not specify a modifier in the correct

KAV30$_BAD_PARAM

You did not specify a parameter in the correct

KAV30$_VME_INT_PEND
KER$_BAD_COUNT

You did not specify the correct number of

format.

An outgoing VMEbusinterrupt is pending.
arguments.

KER$_BAD_VALUE

You did not specify a value in the correct
format.

KER$_NO_ACCESS
KER$_SUCCESS

The services cannot access an item.

The operation is successful.

Related Services
KAV$VME_SETUP

KAV30 System Services 4-73

KAV$LIFO_WRITE

KAVSLIFO_WRITE
Writes a specified number of aligned longwords to one of the KAV30 FIFO
buffers in LIFO mode.

See Section 3.4 for information about the KAV30 FIFO buffers.

Ada Call Format

WITH KAVDEF;
KAV_LIFO_WRITE ([STATUS => status,]

FIFONUMBER => fifo_number,

BUFFER => buffer,
COUNT => count);

argumentinformation
status:

out

SYSTEM.ADDRESS;

fifo_number:
buffer :

in
in

INTEGER;
SYSTEM.ADDRESS;

count :

INTEGER;

C Call Format
#include $vaxelnc
#include "eln$:kavdef.h"

int kav$lifo_write [status],

fifo_number,

buffer,
count)

4-74 KAV30 System Services

KAV$LIFO_WRITE

argumentinformation
int

*status;

int

fifo_number;

void

"buffer;

int

count;

FORTRANCall Format
INCLUDE ’ELN$:KAVDEF.FOR’

CALL KAV$LIFO_WRITE ([status|,

%VAL(fifo_number\,
buffer,
%VAL(count))

argumentinformation
INTEGER*4
INTEGER*4
INTEGER*4
INTEGER*4

status

fifo_number
buffer
count

Pascal Call Format

INCLUDE $KAVDEF;

KAV$LIFOWRITE ([STATUS := status]
fifo_number,

KAV30 System Services 4-75

KAV$LIFO_WRITE

argument information
status :

INTEGER;

fifo_number:

INTEGER;

buffer :

AANYTYPE;

count:

INTEGER;

Arguments
status

Usage:
VAX Type:
Access:

Longword (unsigned)
cond_value
Write only

Mechanism:

Reference

Receives the completion status.

fifo_number
Usage:
VAX Type:
Access:
Mechanism:

Longword (unsigned)
longword_unsigned

Read only
Value

Specifies the FIFO buffer that you want to write to. Specify one of the following

values:

KAV$K_FIFO_0

Writes data to FIFO number0

KAV$K_FIFO1

Writes data to FIFO number1

KAV$K_FIFO2

Writes data to FIFO number2

KAV$KFIFO3

Writes data to FIFO number3

buffer

Usage:
VAX Type:

Longword (unsigned)
longword_unsigned

Access:

Read only

Mechanism:

Reference

Specifies the buffer of data that this service writes (in aligned longwords) into
the FIFO buffer.

4-76 KAV30 System Services

KAV$LIFO_WRITE

count

Usage:

VAX Type:
Access:

Mechanism:

Longword (unsigned)

longword_unsigned
Read only

Value

Specifies the number of aligned longwords that this service writes into the
FIFO buffer.

Status Values
KAV30$_BADPARAM

You did not specify a parameter in the correct
format.

KER$BADCOUNT

You did not specify the correct numberof
arguments.

KER$BADVALUE

You did not specify a value in the correct
format.

KER$COUNTOVERFLOW

There is a FIFO counter overflow.

KER$NO_ACCESS

The services cannot access an item.

KER$SUCCESS

The operation is successful.

Related Services
KAV$FIFO_READ
KAV$FIFO_WRITE

KAV$NOTIFY_FIFO

KAV30 System Services 4-77

KAV$NOTIFY_FIFO

KAVSNOTIFY_FIFO
Delivers an AST when one of the KAV30 FIFO buffers make one of the

following transitions:
e

From the state not full to the state full

From the state not empty to the state empty

From the state empty to the state not empty

See Section 3.4 for information about KAV30 FIFO buffers.

Ada Call Format

WITH KAVDEF;
KAV_NOTIFYFIFO ({STATUS => status]
FIFO_FUNCTIONS => fifo_functions,
FIFO.NUMBER => fifo_number,
AST_ADDR => ast_ador,

[ASTPARAM => ast_param]);

argumentinformation
status :

out

CONDITION_HANDLING.COND_VALUE._
TYPE;

fifo_functions:
fifo_number:

in
in

INTEGER;
INTEGER;

ast_addr:

SYSTEM.ADDRESS;

ast_param :

INTEGER;

4-78 KAV30 System Services

KAV$NOTIFY_FIFO

C Call Format
#include $vaxelnc
#include "eln$:kavdef.h"

int kav$notify_fifo ([status],

fifo_functions,
fifo_number,
ast_addr,

[ast_param])

argumentinformation
int

*status;

int

fifo_functions;

int

fifo_number;

void

*ast_addr();

int

ast_param;

FORTRAN Call Format

INCLUDE ‘ELN$:KAVDEF.FOR’
CALL KAV$NOTIFY_FIFO

([status},
%NAL(fifo_functions),
%VAL(fifo_numben,
ast_addr,

[%VAL(ast_param)))

KAV30 System Services 4—79

KAV$NOTIFY_FIFO

argumentinformation
INTEGER*4

status

INTEGER*4

fifo_functions

INTEGER*4
INTEGER*4

fifo_number
ast_addr

INTEGER*4

ast_param

Pascal Call Format

INCLUDE $KAVDEF:
KAV$NOTIFYFIFO ([STATUS := status,]
fifo_functions,
fifo_number,
ast_addr,

[AST_PARAM := ast_param))

argument information
status :

INTEGER;

fifo_functions:

INTEGER;

fifo_number:

INTEGER;

ast_addr:

AANYTYPE;

ast_param :

INTEGER;

Arguments
status

Usage:
VAX Type:

Longword (unsigned)
cond_value

Access:

Write only

Mechanism:

Reference

Receives the completion status.

4-80 KAV30 System Services

KAV$NOTIFY_FIFO
fifo_functions
Usage:
Longword (unsigned)
VAX Type:
Longword
Access:
Read only
Mechanism:

Value

Specifies the conditions that determine when the KAV30 delivers the AST.
Specify one or more of the following modifiers:
KAV$M_FIFOEMPTY

KAV$M_FIFOFULL

Delivers the AST when the FIFO buffer makes

the transition from the state not empty to

the state empty. If the FIFO buffer is empty
when you call this service, the KAV30 kernel
delivers the AST immediately.
Delivers the AST when the FIFO buffer makes
the transition from the state not full to the

state full. If the FIFO buffer is full when you

call this service, the KAV30 kernel delivers the

AST immediately.
KAV$M_FIFO_NOT_EMPTY

Delivers the AST when the FIFO buffer makes

the transition from the state empty to the
state not empty. If the FIFO buffer is not

empty when you call this service, the KAV30
kernel delivers the AST immediately.

KAV$M_RESETFIFO

Resets the FIFO buffer.
The service clears the FIFO buffer memory,
pending AST delivery, and FIFO condition
interrupt.

You can specify the following combinations of values:
e

KAV$M_FIFO_FULL and KAV$M_FIFO_EMPTY

KAV$M_FIFO_FULL and KAV$M_FIFO_NOT_EMPTY

fifo_number
Usage:
VAX Type:
Access:
Mechanism:

Longword (unsigned)
longword_unsigned
Read only

Value

Specifies the FIFO buffer that you want to operate on.

KAV30 System Services 4-81

KAV$NOTIFY_FIFO

Specify one of the following values:
KAV$K_FIFO_0

Operates on FIFO buffer 0

KAV$K_FIFO1

Operates on FIFO buffer 1

KAV$K_FIFO2

Operates on FIFO buffer 2

KAV$K_FIFO3

Operates on FIFO buffer 3

ast_addr

Usage:
VAX Type:

Procedure entry mask
procedure

Access:

Read only

Mechanism:

Reference

Specifies the address of the AST routine that you want to execute when the
FIFO buffer meets the conditions specified by the fifo_functions argument.
This argument is optional when the fifo_functions argument specifies the value

KAV$M_RESET_FIFO.

astparam

Usage:
VAX Type:

Access:
Mechanism:

Longword (unsigned)
longword_unsigned

Read only
Value

Specifies the address of a parameter, which this service passes to the AST
routine. See Section 3.1 for more information about ASTs.
This argumentis optional when the fifo_functions argument specifies the value

KAV$M_RESET_FIFO.

Status Values
KAV30$_BADMODIFIER

You did not specify a modifier in the correct
format.

KAV30$BADPARAM

You did not specify a parameter in the correct
format.

KAV30$_FIFOBUSY

4-82 KAV30 System Services

The FIFO buffer you want to operate on is

busy.

KAV$NOTIFY_FIFO

KER$_BAD_COUNT

You did not specify the correct number of

KER$BADVALUE

You did not specify a value in the correct
format.
The service cannot access an item.
The operation is successful.

KER$_NO_ACCESS
KER$_SUCCESS

arguments.

Related Services
KAV$FIFO_READ
KAV$FIFO_WRITE

KAV$LIFO_WRITE

Examples
See the programslisted in Appendix B for examples of KAV$NOTIFY_
FIFO service calls.

KAV30 System Services 4-83

KAV$OUT_MAP

KAV$OUTMAP
Maps one or more 64K byte pages (aligned on a 64K byte boundary) of the
KAV30 system virtual address (SO) space to the VMEbus or VSB address
space.
After you map the address space, use one of the following methodsto accessit:
¢

Call the KAV$BUS_BITCLR, KAV$BUS_BITSET, KAV$BUS_READ, and

KAV$BUS_WRITEservices

Write directly to the address space. See Section 5.1 for more information.

Before you access the VMEbus and VSB address space, configure the VMEbus
and VSB. SeeSection 5.4.1 for more information.

This service uses the outgoing SGM to perform the mapping. See Section 3.6

for more information.

The KAV30is a little-endian device, so to exchange data with a big-endian
device, you must translate the data from thelittle-endian format to big-endian
format. This service can map KAV30 SO address space directly to the VMEbus
or VSB address space, or it can specify byte-swapping or word-swapping as
part of the mapping. When you call the KAV$BUS_READ or KAV$BUS_
WRITEservice, these services read or write the data according to the swapping
operations that you specify using this service. See Section 3.6.3 for more

information about data mapping.

This service returns a virtual address, in KAV30 SO space, that corresponds to
the base VMEbusor VSB address of the address space of the device. To read or

write data at an offset into the VMEbus or VSB address space, add the offset

to the virtual address and read or write that virtual address.

This service also returns the SGM entry number. Programs use this number in
a call to the KAV$UNMAP service to free pages of KAV30 SO space when they
are no longer required to be mapped to the VMEbus or VSB.

4-84 KAV30 System Services

KAV$OUT_MAP

Ada Call Format
WITH KAVDEF;
KAV_OUTMAP ([STATUS => status]
SGM_ENTRY => sgm_entry,
PAGE_COUNT => page_count,

BUSADDRESS => bus_address,

VIRTUAL_ADDRESS=> virtual_adaress,
AMCODE => am_code,
MAP_FUNCTIONS => map_functions);

argumentinformation
status:

out

CONDITION_HANDLING.COND_VALUE_

sgm_entry :

out

INTEGER;

page_count:

INTEGER;

bus_address:

SYSTEM.ADDRESS;

TYPE;

virtual_address:

out

SYSTEM.ADDRESS;

am_code:

INTEGER;

map_functions:

INTEGER;

C Call Format
#include $vaxelnc
#include "eln$:kavdef.h"

int kavSout_map [status],
entry,

page_counit,

bus_address,
virtual_address,
am_code,

map_functions)

KAV30 System Services 4-85

KAV$OUT_MAP
argument information
int

*status;

int

“entry;

int

page_count;

int

bus_address;

void

**irtual_address;

int

am_code;

int

map_functions;

FORTRAN Call Format

INCLUDE ’ELN$:KAVDEF.FOR’
CALL KAV$OUT_MAP ((sfatus],
entry,

%VAL(page_counh),
%\AL(bus_adaress),
virtual_address,

%VAL(am_code),
%VAL(map_functions))

argument information
INTEGER*4

status

INTEGER*4

entry

INTEGER*4

page_count

INTEGER*4

bus_address

INTEGER*4
INTEGER*4
INTEGER*4

virtual_address
am_code
map_functions

4-86 KAV30 System Services

KAV$OUT_MAP

Pascal Call Format

INCLUDE $KAVDEF;
KAV$OUTMAP ([STATUS := status,]
entry,
page_count,
bus_address,
virtual_address,
am_code,

map_functions)

argumentinformation
status :

INTEGER;

entry :

INTEGER;

page_count:

INTEGER;

bus_address:

INTEGER;

virtual_address:

AANYTYPE;

am_code :

INTEGER;

map_functions:

INTEGER;

Arguments
status
Usage:
VAX Type:
Access:

Longword (unsigned)
cond_value
Write only

Mechanism:

Reference

Receives the completion status.

KAV30 System Services

KAV$OUT_MAP
entry

Usage:
VAX Type:
Access:

Longword (unsigned)
longword_unsigned
Write only

Mechanism:

Reference

Returns the SGM entry that correspondsto the first page of the KAV30 SO
space that you want to map to the VMEbusor VSB.

page_count
Usage:
VAX Type:
Access:

Mechanism:

Longword (unsigned)
longword_unsigned
Read only
Value

Specifies the number of successive 64K byte pages of KAV30 SO space that you
want to map to the VMEbusor VSB.
bus_address

Usage:
VAX Type:

Access:
Mechanism:

Longword
longword_unsigned

Read only
Value

Specifies the base physical address of the VMEbus or VSB address space. This
base physical address is the start of the first 64K byte page that this service
maps to the VMEbus or VSB address space.
virtual_address
Usage:
Longword (unsigned)
VAX Type:
longword_unsigned
Access:
Write only
Mechanism:

Reference

Returns the KAV30 SO space virtual address that corresponds to the base
physical address (on the VMEbusor VSB)of the 64K byte page of memory that
this service maps to the VMEbus or VSB.

4-88 KAV30 System Services

KAV$OUT_MAP
am_code

Usage:
VAX Type:
Access:

Mechanism:

Longword (unsigned)
longword_unsigned
Read only

Value

This code specifies the VMEbus or VSB addressing mode. If you are mapping
to the VMEbus, specify one of the following values:
Constant

Value

Explanation

KAV$K_USER_16

2916

KAV$K_USER_24

3916

Uses short addressing (16 addresslines) in
VMEbus user mode
Uses standard addressing (24 address
lines) in VMEbus user mode

KAV$K_USER_32

0916

KAV$K_SUPER_16

2Dig

lines) in VMEbus user mode
Uses short addressing (16 addresslines) in
VMEbus supervisor mode

KAV$K_SUPER_24

3Di¢

Uses standard addressing (24 address

KAV$K_SUPER_32

ODig

Uses extended addressing (32 address
lines) in VMEbus supervisor mode

Uses extended addressing (32 address

lines) in VMEbus supervisor mode

If you are mapping to the VSB, specify one of the following values:
Constant

Value

Explanation

KAV$K_SYS
KAV$K_IO
KAV$K_ALT
KAV$K_VSB_IACK

Uses the SYSTEM address space
Uses the I/O address space
Uses the ALTERNATEaddress space
VSB IACK

1
0

If you want to specify an address modifier code with a value other than one
of these values, pass the value directly in the am_code argument. See the
VMEbus Specification and The VME Subsystem Bus (VSB) Specification for
other values that you can pass in the am_code argument.
The address modifier code that you specify in this argument must be the same
as the address modifier code of the VMEbus or VSB device to which this 64K
byte page of KAV30 SO space is mapped.

KAV30 System Services 4—89

KAV$OUT_MAP
map_functions
Usage:
Longword (unsigned)
VAX Type:
longword_unsigned
Access:
Read only
Mechanism: Value
Specifies the following information that controls the mapping operation:
e

Mapping destination—whether you want to map pages of KAV30 SO space
to the VMEbusor VSB address space

Byte swapping mode

Specify one or more of the following modifiers:
KAV$M_NO_RETRY

When you specify this modifier, the KAV30
performs one retry. When you do not
specify this modifier, the KAV30 performs

29 successive retries. If the access does not

succeed after 29 retries, the KAV30 signals

that an access failure occurred. The bus
arbitration failures and bus timeouts cause
accessesto fail.

KAV$MMODE_0SWAP

Performs mode 0 swapping.

KAV$MMODE2SWAP

Performs mode 2 swapping.

KAV$M_MODE3SWAP
KAV$M_VME

Performs mode 3 operations.
Maps KAV30 SO space to the VMEbus.

KAV$M_VSB

Maps KAV30 SO space to the VSB.

KAV$MWRTPROT

Sets write-protection on the page of system

RAM that you want to map to the VMEbus.

You must ensure that the modifiers you specify do not conflict with each other.
For example, do not specify the KAV$M_MODE_3_SWAP and KAV$M_MODE_
0SWAP modifiers together.

4-90 KAV30 System Services

KAV$OUTMAP

Status Values
KAV30$_BAD_MODIFIER

You did not specify a modifier in the correct
format.

KAV30$_BAD_PARAM

You did not specify a parameter in the correct
format.

KER$_BAD_COUNT

You did not specify the correct number of

KER$_BAD_VALUE

You did not specify a value in the correct

KER$_NO_ACCESS
KAV$_NO_MEMORY
KER$_NO_PORT

The service cannot access an item.

KAV$_NO_VIRTUAL
KER$_SUCCESS

arguments.

format.

There is no physical memory available.
There are no free SGM entry ports. Unmap

one or more SGM entries andretry thecall.
There is no virtual address space available.
The operation is successful.

Related Services
KAV$BUS_BITCLR
KAV$BUS_BITSET
KAV$BUS_READ

KAV$BUS_WRITE
KAV$UNMAP

KAV30 System Services 4-91

KAVSOUT_MAP

Examples
e

See the examples in the descriptions of the KAV$BUS_READ and
KAV$BUS_BITCLRservices

The following code is an example program that calls the KAV$OUT_
MAP service:

MODULE exINTVME ;
Facility:

KAV30 VAXELN System Services programming example.

Description:

This is an example program demonstrating the calling
procedures for the following KAV System Services:

KAVSOUTMAP
KAVSUNMAP
KAVSBUSREAD

(Map KAV addr space to VMEbus)
(Un-map .........
(Read VMEbus address)

Abstract:

This program can be used to test the handling of
VMEbus interrupts. It does this by faking an IACK
cycle on the VMEbus.

Language:

Epascal; Version 4.2

1.
2.
3.

—

OOOO

{++}
{

(1)

Notes:

In the interests of program clarity, no error

checking has been included.

--]

INCLUDE SKAVDEF ;

{

(KAV30 definitions)

TYPE

commregion = RECORD
int_count

: INTEGER;

Signalcount : INTEGER;

buspageptr : “ANYTYPE;
END;
byte = [byte] 0..255;
VAR

Waltcount : INTEGER;
deviceobj : DEVICE;

4-92 KAV30 System Services

}

{ Communications Region }
{ Interrupt Service Rtne}

KAVS$OUT_MAP
{

KKKKKKKKKKKRKKKKEKKEKRKKRKRKEKRKKKKKKKKKKKK

}

{

*xkk

}

{

Interrupt Service Routine

***

KKEKEKKKKKKEKKRKEKKKKKKKKEKKEKKKKKKKKKKKKK

}

INTERRUPTSERVICE vmeintisr( registerptr : “anytype;
regionptr

VAR

: “commregion );

rdintcount
: INTEGER;
rdsignalcount : INTEGER;

value

: byte;

pageptr
status

> “ANYTYPE;
: INTEGER;

tempvalue

: INTEGER;

BEGIN
{ fake an IACK cycle to prevent handling of a vectorized
interrupt }
pageptr
tempvalue

READREGISTER (regionptr*.buspageptr);
:= pageptr :: INTEGER;

pageptr

= tempvalue :: “ANYTYPE;

tempvalue

= tempvalue + %xc;

REPEAT

{
{
{

===
KAVSBUSREAD ( STATUS
DATATYPE

BUSREAD

===

}
}
}

>= status,
= KAVSK_BYTE,

VIRTUALADDRESS := pageptr,
BUFFER

= ADDRESS (value) ,

COUNT

:= 1);

UNTIL ODD (status) ;
SIGNALDEVICE( devicenumber := 0);
END;

{
{

{

xxx

End of Interrupt Service Routine

***

This process is activated by the ISR (see above) when it
services an interrupt.

}

}
}

PROCESSBLOCK serverprocess(regionptr :“commregion);
VAR
rdintcount
textstring

: INTEGER;
: VARYINGSTRING (80) ;

BEGIN
textstring := 'KAV30 example program interrupted’ ;

KAV30 System Services 4-93

KAV$OUT_MAP
REPEAT

WAITANY( deviceobj );

rdintcount := READREGISTER( regionptr*.intcount);

WRITELN( text string )

UNTIL FALSE

—

END;
{

KKKKKKKKKKKKKKKKKKKKKK

}

{

xxx

}

{

Main process

***

KKKKKKKKKKKKKKKKKKKKKK

}

PROGRAM INTVME (INPUT, OUTPUT) ;
VAR

status

>: INTEGER;

: INTEGER;

p_id

rd_intcount
rdsignalcount

irglvl

intvec

vmeintbitmask
regionptr
devicename
temppageptr
sgmentry

: PROCESS;

: INTEGER;
: INTEGER;

: INTEGER;

:
:
:
:

“commregion;
VARYINGSTRING (31);
“ANYTYPE;
INTEGER;

BEGIN

devicename := PROGRAMARGUMENT(4) ; { Get the device name from
{ the EBUILD ’.DAT’ file.

{
{

===

{

KAVSOUTMAP ( STATUS
ENTRY
PAGECOUNT
BUSADDRESS
VIRTUALADDRESS
AMCODE
MAPFUNCTIONS
{

Create Device object

CREATEDEVICE(

SERVICEROUTINE :=

REGION
STATUS

4-94 KAV30 System Services

===

:= status,
:= sgmentry,
= 1,
:= 0,
:= temppageptr,
:= X80,
:= KAVSMMODE3SWAP + KAVSMVME );

}

devicename,
device obj,

INMAP

vmeintisr,

:= regionptr,
status ) ;

KAV$OUT_MAP
WRITEREGISTER( regionptr*.intcount,
0);
WRITEREGISTER( regionptr*.signalcount, 0);

WRITEREGISTER( regionptr*.buspageptr :: INTEGER,
temppageptr :: INTEGER );
{

Create the server process

}

CREATEPROCESS ( p_id,

serverprocess,

regionptr,
STATUS := status);
WAITANY( pid, STATUS := status );

{
{

===

{

KAVSUNMAP ( STATUS

ENTRY

END;

===

}

:= status,

PAGECOUNT
VIRTUALADDRESS
UNMAP_FUNCTIONS
END;

UN-MAP

= sgmentry,

= 1,
:= temppageptr,
= KAVSMOUT );

{

xxx

End of main process

***

{

End of INTVME example program

}
***

}

KAV30 System Services 4-95

KAVSQUE_AST

KAVS$QUE_AST
Queues an AST for delivery to a process.
This service removes an ASB from the AST pending queue! andplaces it on

the AST process? queue.

Before you call this service for a particular device code, call the KAV$DEF_AST
service (to allocate an AST queue for the device code) and the KAV$SET_AST
service to place an ASB for the device code in the AST pending queue.
This service uses the device code that the KAV$DEFASTservice returns to
ensure that it delivers the correct AST for a device code.
See Section 3.1 for more information on ASTs.

Ada Call Format
WITH KAVDEF;

KAV_QUE_AST ([STATUS => status|]

DEVICECODE => device_code);

argument information
status:

out

UNSIGNED_LONGWORD;

device_code:

UNSIGNED_LONGWORD;

C Call Format
#include $vaxelnc
#include "eln$:kavdef.h"

int KAV$QUE_AST

((status],
device_code)

The pending queueis the queue that contains the ASBs that are waiting for an event
that will cause an AST to be delivered.
2 The process queueis the queue of ASTs for which an AST hasbeen delivered, but an
AST routine has not been executed.
4-96 KAV30 System Services

KAV$QUE_AST

argumentinformation
int

*status;

int

device_code;

FORTRANCall Format
INCLUDE ’ELN$:KAVDEF.FOR’
CALL KAV$QUE_AST ([status],
%NAL(device_code))

argument information
INTEGER*4

status

INTEGER*4

device_code

Pascal Call Format

INCLUDE $KAVDEF:
KAV$QUE_AST ([STATUS := status,]
device_code)

argumentinformation
status:

INTEGER;

device_code :

INTEGER;

KAV30 System Services 4-97

KAV$QUE_AST

Arguments
status
Usage:
VAX Type:
Access:

Longword (unsigned)
longword_unsigned
Write only

Mechanism:

Reference

Receives the completion status.
device_code

Usage:
VAX Type:
Access:

Longword (unsigned)
Read only
Value

Mechanism:

None

Specifies the device code that identifies the AST you want to queue. The

KAV$DEF_ASTservice returns the device code when you define the AST.

Status Values
KAV30$_BAD_PARAM

You did not specify a parameter in the correct

KER$BADCOUNT

You did not specify the correct number of
arguments.

KER$_BAD_VALUE

You did not specify a value in the correct

KER$SUCCESS

The operation is successful.

4-98 KAV30 System Services

format.

KAV$QUE_AST

Related Services
KAV$CLR_AST
KAV$DEF_AST

KAV$SET_AST

Examples
See the programslisted in Appendix C for examples of KAV$QUE_AST
service calls.

KAV30 System Services 4-99

KAVS$RTC

KAV$RTC
Performsall the real-time clock functions, using the KAV30 calendar/clock.

This service allows you to configure the following real-time clock functions:
e

Alarm

Periodic alarm

Read and write alarm

Read and write calendar

Read and write real-time clock RAM

Read and write timesave RAM

16-bit timer functions

For more information about these functions, see Section 3.3.

The calendar/clock can operate in either 12-hour mode or 24-hour mode. You
specify the mode when you write calendar information into the calendar/clock.
Use the KAV$M_RTC_12_HOUR modifier to specify 12-hour mode, or use

the KAV$M_RTC_24HOUR modifier to specify 24-hour mode. You must
initialize the calendar/clock to either 12-hour mode or 24-hour mode when you
initialize the system. In 12-hour mode, the most significant bit in the hours
byte indicates whether the time is A.M. or P.M. When you read or write the
calendar, a 0 in this bit indicates an A.M. time while a 1 indicates a PM.time.

The programscalling this service pass a modifier that indicates the function
to be performed by the service. The programsalso pass a buffer that contains
the information required to perform the function. The buffer is a byte-oriented
buffer. Figure 4-1 gives an example of a buffer that passes the date Sunday,
March 17, 1991 and time 10:53:25.39 PM.to the real-time clock.

The year value in the exampleis the offset from the base year. The base year
value is 1990. Therefore, a 00 year value corresponds to the year 1990, a
01 year value corresponds to the year 1991, and so on. The following table
explains the day of week value in the example.

4-100 KAV30 System Services

Value

Day

KAV$RTC

Monday

Friday

NID

©®

Tuesday
Wednesday
Thursday
Saturday
Sunday

You can specify an AST routine that executes when the current time and date
are equal to the alarm time and date, or when a timerinterval expires.
Figure 4-1

Programming the Real-Time Clock

T ww ween nen enn eee 43...------------ 0
3

Hundreds = 39

Seconds = 25

Minutes = 53

Date = 17

Month = 03

Year = 1991

Julian Date = 76

Julian Date (Hundreds) = 0

Day of Week = 7 (Sunday)

Hours = 10 (but MSB =1

for PM Times)

KAV30 System Services 4-101

KAV$RTC

Ada Cail Format
WITH KAVDEF:
KAV_RTC ([STATUS => status,]

RTC_FUNCTIONS => rtc_functions,

BUFFER => buffer,
LENGTH => /ength,
[AST_ADDR => ast_adar,]

[AST_PARAM => ast_param)):

argumentinformation
status:

out

CONDITIONHANDLING.COND_VALUE.
TYPE;

rtc_functions:

INTEGER;

buffer :

SYSTEM.ADDRESS;

length :

INTEGER;

ast_addr:

INTEGER;

ast_param :

INTEGER;

C Call Format
#include $vaxelnc
#include "eln$:kavdef.h"

int kav$rtc ([status],

ric_functions,
buffer,

length,
[ast_adar],
[ast_param))

4-102 KAV30 System Services

KAV$RTC

argumentinformation
int

*status;

int

rtc_functions;

void

“buffer;

int
void

length;
*ast_addr();

int

ast_param;

FORTRANCall Format
INCLUDE ’ELN$:KAVDEF.FOR’
CALL KAV$RTC

([status],
%VAL(rtc_functions),
buffer,
%VAL(length),
[ast_aaadr,]
[%VAL(ast_param)})

argument information
INTEGER*4

status

INTEGER*4

rtc_functions

INTEGER*4

buffer

INTEGER*4
INTEGER*4

length
ast_addr

INTEGER*4

ast_param

KAV30 System Services 4-103

KAVS$RTC

Pascal Call Format
INCLUDE $KAVDEF:
KAV$RTC ([STATUS:= status,]
rtc_functions,

buffer,
length,
[,ast_adar|
[,ast_param)])

argumentinformation
status :

INTEGER;

rtc_functions:

INTEGER;

buffer :

AANYTYPE;

length :

INTEGER;

ast_addr:

AANYTYPE;

ast_param :

INTEGER;

Arguments
status

Usage:
VAX Type:
Access:

Longword (unsigned)
cond_value
Write only

Mechanism:

Reference

Receives the completion status.
rtc_functions

Usage:
VAX Type:

Access:
Mechanism:

Longword (unsigned)
longword_unsigned

Read only
Value

Specifies the function that you want to perform.

4-104 KAV30 System Services

KAV$RTC
You must specify one or more of the following modifiers:
KAV$M_RTC_TMR_0
KAV$M_RTC_TMR_1

Performs a function on timer 0.
Performs a function on timer 1.

Warning
Timer 1 is reserved for the VMEbustimeout timer. It is set up by the
KAV30 kernel when you boot the KAV30. Digital strongly recommends
that you do not change or modify this timer.
KAV$M_LOAD_TMR_CNT

KAV$M_START_TMR

Loads a value into one of the timers. If you

want to load the value into timer 0, also

specify the KAV$M_RTC_TMR_0 modifier. If
you want to load a value into timer 1, also
specify the KAV$M_RTC_TMR_1 modifier.
You must specify the AST routine address
and parameters when you load the timer. The
buffer argument specifies the value that you
want to load into the timer register, along with
the timerresolution.
If you specify the KAV$M_LOAD_TMR_CNT
modifier, you cannot specify the KAV$M_
READ_TMR_CNT modifier.
Starts the timer. The timer starts decrementing the value in the timer register. When the
value in the register reaches zero, the KAV30
software issues an AST.
If you want to start timer 0, also specify the

KAV$M_RTC_TMR_0 modifier. If you want to
start timer 1, also specify the KAV$M_RTC_

TMR_1 modifier.

If you specify this modifier, you cannot also
specify the KAV$M_STOP_TMR modifier.

KAV30 System Services 4-105

KAV$RTC

KAV$M_STOP_TMR

Stops the timer. This service does not issue an

AST when the timer stops—it issues an AST

only when the number in the timer register
reaches 0.
If you want to stop timer 0, also specify the

KAV$M_READ_TMR_CNT

KAV$M_RTC_TMR_0 modifier. If you want to
stop timer 1, also specify the KAV$M_RTC_
TMR_1 modifier.
If you specify this modifier, you cannot also
specify the KAV$M_START_TMR modifier.
Reads the value stored in the timer register.
Read the value in the timerregister only
when you also specify the KAV$M_STOP_
TMR modifier. That is, stop the timer before
reading the value in the register.
To read the value in timer 0,also specify the
KAV$M_RTC_TMR_0 modifier. To read the

value in timer 1, also specify the KAV$M_
RTC_TMR_1 modifier.
If you specify this modifier, you cannot

also specify the KAV$M_LOAD_TMR_CNT

modifier.

KAV$M_RESET_TMR

Resets the calendar/clock.
To reset timer 0, also specify the KAV$M_

RTC_TMR_0O modifier. To reset timer 1, also

KAV$M_PERIODIC
KAV$M_ALARM

KAV$M_READ_ALARM

4-106 KAV30 System Services

specify the KAV$M_RTC_TMR_1 modifier.
Queues an AST repeatedly at the interval
specified by the buffer argument.
Delivers an AST at the time specified by an
rtc_functions argumentspecifying the KAV$M_
WRITE_ALARM modifier.
Reads the alarm setting and returns the value
in the buffer argument.

KAV$RTC

KAV$M_WRITE_ALARM

Sets the alarm time to the value specified in

the buffer argument. When the calendar/clock
time becomes equal to the alarm time, the

KAV30 kernel queues an AST to the AST
pending queue whenyou are writing the
alarm timefor the first time. When you are

not writing for the first time, call this service

again with the KAV$M_ALARM modifier.

KAV$M_READ_CALENDAR
KAV$M_WRITE_CALENDAR
KAV$M_RTC_12_HOUR

Reads the current calendar date and returns

the value in the buffer argument.
Sets the calendar date to the date specified in
the buffer argument.

Sets the calendar/clock to operate in 12-hour
mode. You can specify the KAV$M_RTC_12_
HOUR modifier only when you also specify

the KAV$M_WRITE_CALENDARmodifier. If

you do not specify either the KAV$M_RTC_
12HOUR modifier or the KAV$M_RTC_.

24HOUR modifier, the clock mode remains
unchanged.

KAV$M_RTC_24_HOUR

Sets the calendar/clock to operate in 24-hour

mode. You can specify the KAV$M_RTC_24_

HOUR modifier only when you also specify
the KAV$M_WRITE_CALENDARmodifier. If
you do not specify either the KAV$M_RTC_
12.HOUR modifier or the KAV$M_RTC_
24HOUR modifier, the clock mode remains
unchanged.

KAV$M_READ_TIMESAVE

Reads the value stored in the timesave RAM

KAV$M_WRITE_TIMESAVE

Writes the data specified in the buffer
argument into timesave RAM.

KAV$M_READ_RTCRAM

Reads up to 31 bytes of data from the calendar
/clock battery backed-up RAM and returns the

and returns it in the buffer argument.

data in the buffer argument. The low-order

word of this modifier specifies the number of
bytes to be read. The high-order word specifies
the base address in the battery backed-up
RAM of the data to read.

KAV30 System Services 4-107

KAV$RTC

KAV$M_WRITERTCRAM

Writes up to 31 bytes of data from the buffer
argumentto the calendar/clock battery backedup RAM. The low-order word of this modifier
specifies the numberof bytes to be read. The
high-order word specifies the base address in
the battery backed-up RAM ofthe data to be
read.

KAV$M_RTC_HOLD_TMR

Puts the timer on hold. The timer stops

decrementing, and the value remains in the

timer register.

If you want to hold timer 0, also specify the
KAV$M_RTC_TMR_0 modifier. If you want to
hold timer 1, also specify the KAV$M_RTC_
TMR_1 modifier.

KAV$MRTC_RESTART_
TMR

Restarts the timer after a previous call to this
service had put the timer on hold.
If you want to restart timer 0, also specify the
KAV$M_RTC_TMR_0 modifier. If you want to
restart timer 1, also specify the KAV$M_RTC_

TMR_1 modifier.

buffer
Usage:
VAX Type:
Access:

Longword (unsigned)
longword_unsigned
Modify

Mechanism:

Reference

Specifies the address of a buffer. The address contains the value that you want
to write to or read from the calendar/clock. The value of the buffer argument
depends on the function that you specify in the rtc_functions argument, as
follows:
e

If the value of the rtc_functions argument is KAV$M_LOAD_TMR_COUNT,
the buffer is a longword whose layout is shown in the following diagram:

Reserved

Resolution

Timer Count

The service uses only the first 24 bits, the high-order byte must be zero.

Bits <15..0> contain the value that the service loads into the timerregister.

Bits <23..16> specify the timer resolution.
4-108 KAV30 System Services

KAV$RTC

Specify one of the following values for bits <23..16>:
KAV$K_RTC_100NS
KAV$KRTC_400NS

KAV$K_RTC_93US
KAV$K_RTC_1MS
KAV$K_RTC_10MS
KAV$K_RTC_100MS
KAV$K_RTC_1000MS

Specifies that the timer register
decrements every 100 ns
Specifies that the timer register

decrements every 400 ns
Specifies that the timer register
decrements every 93.5 ps
Specifies that the timer register
decrements every 1 ms

Specifies that the timer register
decrements every 10 ms
Specifies that the timer register
decrements every 100 ms
Specifies that the timer register

decrements every 1000 ms

If the value of the rtc_functions argument is KAV$M_READ_TMR_COUNT,

the buffer argument returns the 16-bit value that the timer register
contains.

If the value of the rtc_functions argument is KAV$M_PERIODIC, specify
one of the following values for the buffer argument:
KAV$K_PER_1MS

Queues an AST every 1 ms

KAV$K_PER_10MS
KAV$KPER_100MSEC
KAV$K_PER_1SEC
KAV$K_PER_10SEC

Queues an AST every 10 ms
Queues an AST every 100 ms
Queues an AST every 1s
Queues an AST every 10s

KAV$K_PER_60SEC

Queues an AST every 60s

To reset the periodic queuing of ASTs, specify 0 in the buffer argument.
Whenthe value of the ritc_functions argument is KAV$M_ALARM,specify
one of the following values for the buffer argument:
KAV$KALRSECOND

Performs an alarm check every 1 second

KAV$K_ALR_MINUTE

Performs an alarm check every 1 min

KAV$KALRHOUR

Performs an alarm check every 1 hour

KAV$KALRDOM

Performs an alarm check on one day every
month

KAV30 System Services 4-109

KAV$RTC

KAV$K_ALR_MONTH
KAV$K_ALR_DOM

Performs an alarm check every month
Performs an alarm check on one day every
week

Before you execute this service you mustfirst use the KAV$M_WRITE_
ALARMservice to set the alarm date and time.
e

If the value of the rtc_functions argument is KAV$M_READ_ALARM or
KAV$M_WRITE_ALARM,the buffer argumentis 6 bytes long and contains
the alarm information in BCD format, as shownin the following diagram.

Seconds(0 to 59)
Minutes (0 to 59)
Hours (1 to 12 or 0 to 23)
Day of Month (1 to 28, 29, 30, or 31)
Month (1 to 12)
Day of Week(1 to 7)

Whenthe calendar/clock time becomes equal to the time that the buffer
argument specifies, the KAV30 kernel queues an AST to the AST pending
queue.
To set up an alarm,follow these steps:

Call this service to write the alarm time.

Call this service with KAV$M_ALARMspecified as an argument.

You cannot combine both actions in oneservice call. To reset the alarm,

specify 0 in the buffer argument.

Ifthe value of the ric_functions argument is KAV$M_READ_CALENDAR

or KAV$M_WRITE_CALENDAR,the buffer argumentis ten bytes long and
it contains the calendar information in BCD format, as shown in the

4-110 KAV30 System Services

KAV$RTC

following diagram:
Hundreds(0 to 99)
Seconds(0 to 59)
Minutes (0 to 59)
Hours (1 to 12 or 0 to 23)
Day of Month (1 to 28, 29, 30, or 31)
Month (1 to 12)
Years (0 to 99)
Julian Date (1 to 99)
Julian Date (0 to 3)
Day of Week(1 to 7)

If the value of the rtc_functions argument is KAV$M_READ_TIMESAVE
or KAV$M_WRITE_TIMESAVE, the buffer argumentis 5 bytes long and

it contains the timesave information in BCD format, as shown in the

following diagram:

Seconds(0 to 59)
Minutes(0 to 59)
Hours (1 to 12 or 0 to 23)
Day of Month (1 to 28, 29, 30, or 31)
Month (1 to 12)

KAV30 System Services 4-111

KAV$RTC
The date and time is automatically written when there is a powerfailure.
You can read this date and time when you boot the system after a power
failure to detect when the powerfailure occurred.
e

Ifthe value of the rtc_functions argument is KAV$M_READ_RTCRAM or

KAV$M_WRITE_RTCRAM,the buffer argument contains the data that you
want to read from or write to the calendar/clock battery backed-up RAM.
The length argument specifies the amount of data to read or write and the
base address in the battery backed-up RAM,asfollows:

Base Byte Address

Length

The base byte address is an offset into the battery backed-up RAM. The
length is the numberof bytes.
Note

If the rtc_functions argumentspecifies the value KAV$M_RTC_12_
HOUR,the high-order bit in the hours byte is the A.M./PM. bit—a zero
indicates A.M. and a one indicates PM.

length
Usage:
VAX Type:
Access:

Mechanism:

Longword (unsigned)
longword_unsigned
Read only
Value

Specifies the length (in bytes) of the buffer whose address you specify in the

buffer argument.
ast_addr
Usage:

Procedure entry mask

Mechanism:

Reference

VAX Type:
Access:

procedure
Read only

Specifies the address of the AST routine, which the service calls when one or
more of the following occur:
-

A timeout

An alarm

4-112 KAV30 System Services

KAV$RTC

A periodic alarm

See Section 3.1 for more information about ASTs.

ast_param

Usage:
VAX Type:
Access:

Mechanism:

Longword (unsigned)
longword_unsigned
Read only
Reference

Specifies a parameter that this service passes to the AST routine.
See Section 3.1 for more information about ASTs.

Status Values
KAV30$_ALR_ACTIVE
KAV30$_BAD_MODIFIER
KAV30$_BAD_PARAM
KAV30$_PER_ACTIVE
KAV30$_TMR_BUSY
KER$_BAD_COUNT

The alarm interrupts are active.

You did not specify a modifier in the correct
format.
You did not specify a parameter in the correct
format.
The periodic interrupts are active.
The timeris busy.
You did not specify the correct numberof
arguments.

KER$_BAD_VALUE

You did not specify a value in the correct
format.

KER$_NO_ACCESS
KER$_SUCCESS
KER$_TIME_NOT_SET

The service cannot access an item.

The operation is successful.
The timer is not set.

KAV30 System Services 4-113

KAV$RTC

Examples
The following code is an example program that calls the KAV$RTC service:
/*
*

Facility:

KAV30 VAXELN System Services programming example.

*
*

Description:

This is an example program demonstrating the calling
procedure for the following KAV System Service:

KAVSRTC

(RealTime Clock functions)

Abstract:

This program reads the RTC calendar. Simple as that.

Language:

Vax C; Version 3.1

Notes:

(1)

In the interests of program clarity, no error checking has

been included.

*/
#include
#include
#include

stdio
Svaxelnc
<eln$:kavdef .h>

#define

BUFFERLENGTH

KAV30 definitions file.

100

Main Program

main ()

{

int

status, 1 ;

unsigned long
rtcfunctions ;
unsigned char
buffer[BUFFERLENGTH] ;
void
astroutine() ;
printf ("\n\nKAV30 Test program for RTC System Service call\n\n")
/*

Read the CALENDAR from RTC

*/
rtc_functions

KAVSRTC

(

KAVSMREADCALENDAR ;

&status,
rtc_functions,
&buffer[0],
10,

éastroutine, 0 ) ;

printf("\n\nEND OF KAV30 Test program for RTC. \n\n") ;
} /*

end

-program-

4-114 KAV30 System Services

KAV$RTC

void astroutine()
{
int i;
i = 1234 ;

Dummy AST routine (NOT USED)

return ;

}

KAV30 System Services 4-115

KAV$RW_BBRAM

KAVSRW_BBRAM
Writes data to or reads data from the KAV30 battery backed-up RAM.
You can write data into the battery backed-up RAM by passing a buffer to this
service. You can read data from the battery backed-up RAM by reading data
from the buffer that this service returns. You specify a modifier when youcall
this service, which indicates whether you want to read from or write to the
battery backed-up RAM.
See Section 3.5 for information about the KAV30 battery backed-up RAM.

Ada Call Format

WITH KAVDEF;
KAV_RW_BBRAM ([STATUS => stfatus,]

BUFFERADDRESS => buffer_adadress,
BUFFERLENGTH => buffer_length,
BBRAMOFFSET => bbram_offset,
BBRAMFUNCTIONS => bbram_functions;

argument information
status:

out

buffer_address:
buffer_length :
bbram_offset :

in
in
in

bbram_functions :

4-116 KAV30 System Services

CONDITION_HANDLING.COND_VALUE_
TYPE;

SYSTEM.ADDRESS:
INTEGER;
INTEGER;
INTEGER;

KAV$RW_BBRAM

C Call Format
#include $vaxelnc
#include "eln$:kavdef.h"

int kav$rw_bbram _([status],

buffer_address,

buffer_length,
bbram_offset,

bbram_functions)

argumentinformation
int

*status;

void

*buffer_address;

int

buffer_length;

int

bbram_offset;

int

bbram_functions;

FORTRANCall Format
INCLUDE ’ELN$:KAVDEF.FOR’
CALL KAV$RW_BBRAM_((status],

buffer_address,

%VAL(buffer_length),
%VAL(bbram_offset),

%VAL(bbram_functions))

KAV30 System Services 4-117

KAV$RW_BBRAM
argument information
INTEGER*4
INTEGER*4
INTEGER*4

status

buffer_address
buffer_length
bbram_offset
bbram_functions

INTEGER*4
INTEGER*4

Pascal Call Format
INCLUDE $KAVDEF;
KAV$RW_BBRAM ([STATUS := STATUS,]
BUFFER_ADDRESS := buffer_address,
BUFFER_LENGTH := buffer_length,
BBRAMOFFSET := bbram_offset,

FUNCTION := bbram_functions)

argumentinformation
status:

INTEGER;

buffer_address:

AANYTYPE;

buffer_length :
bbram_offset :

INTEGER;
INTEGER;

bbram_functions:

INTEGER;

Arguments
status

Usage:

VAX Type:

Access:
Mechanism:

Longword (unsigned)
longword_unsigned
Write only
Reference

Receives the completion status.

4-118 KAV30 System Services

KAVSRW_BBRAM

buffer_address

Usage:
VAX Type:
Access:

Longword (unsigned)
longword_unsigned
Modify

Mechanism:

Reference

Supplies the address of the buffer that this service uses. If the value of the
function argument is KAV$K_BBR_READ, this service reads data from the
battery backed-up RAM andwrites it to the buffer. If the value of the function
argument is KAV$K_BBR_WRITE, this service writes the data in the buffer to
the battery backed-up RAM.
buffer_length
Usage:
Longword (unsigned)
VAX Type:
longword_unsigned
Access:
Mechanism:

Read only
Value

Supplies the length of the buffer whose address is supplied by the buffer_
address argument. The maximum buffer length is 22K bytes.
bbram_offset
Usage:
Longword (unsigned)
VAX Type:
longword_unsigned
Access:
Read only
Mechanism:

Value

Specifies an offset into the 22K byte battery backed-up RAM area.
bbram_functions

Usage:
VAX Type:
Access:

Mechanism:

Longword (unsigned)
longword_unsigned
Read only

Value

Supplies a code that determines whether this service writes the data in the
buffer to the battery backed-up RAM or reads the data from the battery
backed-up RAM andwrites it to the buffer. Specify one of the following values:
KAV$K_BBRREAD

Reads data from the battery backed-up RAM.

KAV$KBBRWRITE

Writes data to the battery backed-up RAM.

KAV30 System Services 4-119

KAV$RW_BBRAM

Status Values
KAV30$_BADPARAM

You did not specify a parameter in the correct

KER$BADCOUNT

You did not specify the correct number of

KER$BADVALUE

You did not specify a value in the correct
format.
The service cannot access an item.
The operation is successful.

format.

arguments.

KER$_NO_ACCESS
KER$_SUCCESS

Examples
The following code is an example program that calls the KAV$RW_BBRAM
service:

/*
*

Facility:

KAV30 VAXELN System Services programming example.

*
*
x

Description:

This is an example program demonstrating the calling
procedure for the following KAV System Service:
KAVSRWBBRAM
(Read/Write BB-Ram)

*
*
*
*
x
*

Abstract:

This program reads and writes to the KAV30's Batterybacked-up RAM.
Firstly; it initializes a buffer with known data which
it writes to the BB-Ram.
Secondly, it reads the BB-Ram and checks the data read
against the data written.

Language:

Vax C; Version 3.1

*
x

Notes:

In the interests of program clarity, no error checking has
been included.

(1)

#include
#include
#include

stdio
Svaxelnc
<elnS:kavdef.h>

#define
#define

BUFFERSIZE
BUFFEROFFSET

32
0

4—120 KAV30 System Services

KAV30 definitions file.

/*
/*

Test buffer size.
Test buffer offset.

*/
*/

KAV$RW_BBRAM
/*

Main Program

main ()

{

int
unsigned char

status, 1 ;
bufferin|[BUFFERSIZE],
bufferout[BUFFERSIZE] ;

printf ("\n\nKAV30 Test program for RWBBRAM System Service call\n\n") ;
/*
*
x

Initialize the test buffer with a simple incrementing sequence, .
and clear out the output buffer.

for (1 = 0; 1 < BUFFERSIZE; itt )

{

bufferin[i]

= itl ;

bufferout[i] =0;

} ;

x
k

WRITE to BB-RAM

KAVSRWBBRAM(

*
x

&status,
&bufferin[0],
BUFFERSIZE,
BUFFEROFFSET,
KAVSKBBRWRITE )

;

READ from BB-RAM

KAVSRW_BBRAM(

&status,

&bufferout[0],

BUFFERSIZE,

BUFFEROFFSET,

KAVSKBBRREAD ) ;

/*
x

Lastly, compare the two buffers - they should be identical.

for (i = 0, status = 0; 1 < BUFFERSIZE; it+ )

{ if (bufferinfi] != bufferout[i]) statust+ ; }

/* Flag an error */

if (status != 0)
{ printf("Total of %d errors found.\n", status ) ; } else
{ printf("No errors found in data read back from BBRAM.\n") ; } ;
if (status '!= 0) { printf("Total of Sd errors found.\n", status ) ; }

else

{ printf("No errors found in data read back.\n") ; } ;

printf ("\n\nEND OF KAV30 Test program for RWBBRAM \n\n") ;
} /*

end

-program-

KAV30 System Services 4-121

KAV$SET_AST
KAV$SET_AST
Places an ASB in the AST pending! queue.
You must call the KAV$DEF_ASTservice before you call this service. The
KAV$DEF_ASTservice returns a device code that associates an AST queue
with a particular device event. This service uses this device code to ensure
that it places the ASB in the correct AST queue.
The KAV30 kernel deletes entries from the queue once it has queued the
entries to a process, unless the ast_functions argument specifies the value

KAV$M_REPEAT.In that case, the KAV30 kernel requeues the AST to the

pending queue, immediately after it has delivered the AST. You can call the
KAV$CLR_ASTservice to cancel the repeating ASTs.
See Section 3.1 for more information on ASTs.

Ada Call Format
WITH KAVDEF;
KAV_SETAST ([STATUS => status,]
AST_ADDR => ast_adar,

[AST_PARAM => ast_param,]
AST_FUNCTIONS => ast_functions,

DEVICECODE => device_code):

argument information
status :

out

CONDITION.HANDLING.COND_VALUE.
TYPE;

ast_addr:

SYSTEM.ADDRESS;

ast_param :

INTEGER;

ast_functions:

INTEGER;

device_code:

INTEGER;

1 The pending queue is the queue of ASBs that is waiting for an event that will cause
an AST to be delivered. The process queue is the queue of ASTs for which an AST
has been delivered, but the AST routine has not yet been executed.
4-122 KAV30 System Services

KAV$SET_AST

C Call Format
#include $vaxelnc
#include "eln$:kavdef.h"

int kav$set_ast ([status],

ast_addr,

[ast_param|,

astfunctions,

device_code)

argumentinformation
int

*status;

void

*ast_addr();

int

ast_param;

int

ast_functions;

int

device_code;

FORTRANCall Format
INCLUDE ’ELN$:KAVDEF.FOR’
CALL KAV$SET_AST

([status],

ast_addr,

[%VAL(ast_param)],
%WAL(ast_functions),
%VAL(device_code))

KAV30 System Services 4—123

KAV$SET_AST
argumentinformation
INTEGER*4

status

INTEGER*4

ast_addr

INTEGER*4

ast_param

INTEGER*4

ast_functions

INTEGER*4

device_code

Pascal Call Format

INCLUDE $KAVDEF;
KAV$SET_AST ([STATUS := status,]
ast_adadr,

[AST_PARAM:= ast_param,]
ast_functions,

device_code)

argumentinformation
status:

INTEGER;

ast_addr:

AANYTYPE;

ast_param :
ast_functions:

INTEGER;
INTEGER;

device_code:

INTEGER;

Arguments
status

Usage:
VAX Type:

Longword (unsigned)
cond_value

Access:

Write only

Mechanism:

Reference

Receives the completion status.

4-124 KAV30 System Services

KAV$SET_AST
ast_addr
Usage:
VAX Type:
Access:

Procedure entry mask
procedure
Read only

Mechanism:

Reference

Specifies the address of the AST routine. The KAV30 software calls the AST
routine at this address when the device code that you specify in the device_code
argument causes an ASTto be issued to the process.

ast_param

Usage:
VAX Type:
Access:

Mechanism:

Longword (unsigned)
longword_unsigned
Read only

Value

Specifies a parameter that this service passes to the AST routine.
astfunctions

Usage:
VAX Type:
Access:

Mechanism:

Longword (unsigned)
longword_unsigned
Read only

Value

Specify the KAV$M_REPEATvaluefor this argument when you want to queue
the AST to the AST pending queue for the device code immediately after the
KAV30 kernel delivers the AST.
device_code
Usage:
Longword (unsigned)
VAX Type:
longword_unsigned
Access:
Read only
Mechanism:

Value

Specifies the device code that identifies the AST that you want to set. The

KAV$DEF_ASTservice returns the device code when you define the AST.

KAV30 System Services 4-125

KAV$SET_AST

Status Values
KAV30$_BAD_PARAM
KER$_BAD_COUNT
KER$_BADVALUE
KER$_SUCCESS

You did not specify a parameter in the correct
format.
You did not specify the correct number of
arguments.

You did not specify a value in the correct
format.
The operation is successful.

Related Services
KAV$CLR_AST
KAV$DEF_AST

KAV$QUE_AST

Examples
See the programslisted in Appendix C for examples of KAV$SET_AST
service calls.

4-126 KAV30 System Services

KAV$SET_CLOCK
KAVSSETCLOCK
Allows you to perform the following actions:
e

Read the value of the KAV30 real-time clock and place it in the VAXELN

Read the value of the VAXELN system time, and place it in the KAV30
real-time clock. You can place the value in the KAV30 real-time clock in
either 12- or 24-hour mode.

system time.

Ada Call Format
WITH KAVDEF;
KAV_SETCLOCK ([STATUS => status,]
CLOCK_FUNCTIONS => clock_functions):

argumentinformation
status:

out

CONDITION_HANDLING.COND_VALUE_
TYPE;

clock_functions:

INTEGER;

C Call Format
#include $vaxelnc
#include "eln$:kavdef.h"

int kav$set_clock ([status,]
clock_functions)

KAV30 System Services 4-127

KAV$SET_CLOCK
argumentinformation
int

*status;

int

clock_functions;

FORTRANCall Format
INCLUDE ’ELN$:KAVDEF.FOR’
CALL KAV$SET_CLOCK

((status,]
%VAL(clock_functions))

argument information
INTEGER*4

status

INTEGER*4

clock_functions

Pascal Call Format

INCLUDE $KAVDEF:
KAV$SETCLOCK ([STATUS := status,]
CLOCK_FUNCTIONS := clock_functions)

argumentinformation
status:

INTEGER;

clock_functions:

INTEGER;

4-128 KAV30 System Services

KAV$SETCLOCK

Arguments
status

Usage:
VAX Type:

Longword (unsigned)
Longword

Access:

Write only

Mechanism:

Reference

Receives the completion status.
clock_functions
Usage:

VAX Type:
Access:

Mechanism:

Longword (unsigned)

Longword_unsigned
Read only

Value

Specifies the function that you want to perform. Specify one of the following
values:
KAV$K_SET_VAX_TIME
KAV$K_SET_RTC_TIME

Reads the value of the KAV30 real-time clock and
places the value in the VAXELN system time.
Readsthe value of the VAXELN system time and
places the value in the KAV30 real-timeclock.

Whenyou specify the KAV$K_SET_RTC_TIMEvalue,also specify one of the
following modifiers:
KAV$M_RTC_12HOUR

Sets the real-time clock value in 12-hour mode.

KAV$M_RTC_24HOUR

Sets the real-time clock value in 24-hour mode.

Status Values
KAV30$_BAD_PARAM

You did not specify a parameter in the correct
format.

KAV30$_INVALIDTIME

The time that the service readsis invalid.

KER$_BAD_COUNT

You did not specify the correct number of
arguments.

KAV30 System Services 4—129

KAV$SET_CLOCK

KER$BADVALUE

You did not specify a value in the correct
format.

KER$SUCCESS

The operation is successful.

KER$TIMENOT_SET

The clock value that the service reads is not
set.

Related Services
KAV$RTC

4~130 KAV30 System Services

KAV$TIMERS

KAVSTIMERS
Performs various timer functions on the timer you specify.

There are five 32-bit timers available for general use. This service allows you
to load, start, stop, and reset these timers. You can also use this service to

read the value in the timer register and to set the timer to repeat mode.

The service arguments specify the timer number and the function that you

want to perform on the timer. If the function is to start the timeror to set
the timer to repeat mode, the KAV30 kernel delivers an AST when the timer
interval expires.
Note

The KAV30 kernel delivers an AST only when the timer interval
expires. It does not deliver an AST if this service stops the timer.

In addition to the five 32-bit timers, there are also two 16-bit timers. One of

these is the watchdog timer, the other is the local bus timeout timer. If the
watchdog timer expires, a KAV30 hardwarereset occurs.
Note

The local bus timeout timer specifies the maximum interval for local
VAX bus accesses. Digital strongly recommends that you do not alter
this value.
The KAV30 kernel does not deliver an AST whenthe local watchdog timer or
the local bus timeout timer expires.
See Section 3.2 for more information about the KAV30 timers. See Section 3.1
for more information about ASTs.

KAV30 System Services 4-131

KAV$TIMERS

Ada Call Format
WITH KAVDEF:
KAV_TIMER ([STATUS => status,]

TIMERFUNCTIONS => timer_functions,
TIMERNUMBER => timer_number,
TIMER_COUNT=> timer_count,

AST_ADDR => ast_addr,
[AST_PARAM => ast_param,]);

argumentinformation
status :

out

timer_functions:

INTEGER;

timer_number:

INTEGER;

timer_count:

in out

INTEGER;

ast_addr:

SYSTEM.ADDRESS;

ast_param :

INTEGER;

C Call Format
#include $vaxelnc
#include "eln$:kavdef.h"

int kav$timers

([status],

timer_functions,
timer_number,
timer_count,
ast_addr,

[ast_param,)

4-132 KAV30 System Services

CONDITIONHANDLING.COND_VALUE.

TYPE;

KAV$TIMERS

argumentinformation
int

*status;

int

timer_functions;

int

timer_number;

int

*timer_count;

void

*ast_addr();

int

ast_param;

FORTRANCall Format
INCLUDE ’ELN$:KAVDEF.FOR’
CALL KAV$TIMERS_ (status,
%VAL(timer_functions),
%VAL(timer_numben),
timer_count,

%VAL(ast_adar',
[%VAL(ast_param)))

argument information
INTEGER*4

status

INTEGER*4
INTEGER*4

timer_functions
timer_number

INTEGER*4

timer_count

INTEGER*4

ast_addr

INTEGER*4

ast_param

KAV30 System Services 4-133

KAV$TIMERS

Pascal Call Format

INCLUDE $KAVDEF:
KAV$TIMERS ({[STATUS:= status,]
timer_functions,
timer_number,
timer_count,
ast_add,

[ASTPARAM := ast_param,)

argumentinformation
status :

INTEGER;

timer_functions:

INTEGER;

timer_number:

INTEGER;

timer_count:

INTEGER;

ast_addr:

AANYTYPE;

ast_param :

INTEGER;

Arguments
status

Usage:
VAX Type:
Access:

Longword (unsigned)
cond_value
Write only

Mechanism:

Reference

Receives the completion status.

timer_functions
Usage:
Longword (unsigned)
VAX Type:
mask_longword
Access:
Read only
Mechanism:

Value

Specifies the function that you want to perform on the timer.

4-134 KAV30 System Services

KAVSTIMERS
Specify one or more of the following modifiers:
KAV$M_LOAD_TMR_CNT

Loads a value into the timerregister.
Specify the value in the timer_count argument.
Also, specify the AST routine address and
parameters when loading the timer.
If you specify the KAV$M_LOAD_TMR_CNT
modifier, you cannot also specify the KAV$M_
READ_TMRCNT modifier.

KAV$M_START_TMR

KAV$M_STOP_TMR

Starts the timer. The timer starts decrementing the value in the timer register. When the
value in the register reaches zero, the KAV30
software issues an AST.
If you specify the KAV$¢M_START_TMR
modifier, you cannot also specify the KAV$M_
STOP_TMR modifier.
Stops the timer. This service does not issue an
AST—it issues an AST only if the numberin
the timer register reaches0.

If you specify the KAV$M_STOP_TMR
modifier, you cannot also specify the KAV$M_
START_TMR modifier.

KAV$M_READ_TMR_CNT

Reads the value stored in the timerregister.
Read the value in the timer register only
when you also specify the KAV$M_STOP_TMR
modifier. That is, stop the timer before you
read the value in its register.

If you specify the KAV$M_READ_TMRCNT
modifier, you cannot also specify the KAV$M_
LOAD_TMR_CNT modifier.

KAV30 System Services 4-135

KAV$TIMERS

KAV$M_REPEAT_TMR

Sets the timer to repeat mode. In this mode
the KAV30 software requeues the AST after it

is delivered, and then reloads and restarts the
timer.

You can specify the KAV$M_REPEAT_TMR
modifier only when you also specify the
KAV$M_LOADTMRmodifier.
KAV$M_RESET_TMR

Resets the specified timer and deletes the
pending ASTs.
If you specify the KAV$M_RESET_TMR
modifier, you cannot specify other modifiers.

timer_number
Usage:
Longword (unsigned)
VAX Type:
longword_unsigned
Access:
Mechanism:

Read only
Value

Specifies the timer on which the KAV30 software performs the functions
specified by the timer_functions argument. Specify one of the following values:
16-bit Timers
KAV$KLCL_TO

KAV$KWDOG

32-bit Timers
KAV$K_CTMRO

KAV$K__CTMRI1

KAV$K_CTMR3

KAV$K_CTMR4

timer_count

Usage:
VAX Type:
Access:

Longword (unsigned)
longword_unsigned
Modify

Mechanism:

Reference

KAV$K_CTMR2

Specifies the value that the KAV30 software loads into the timer register (the
timer is the one specified by the timer_number argument). You can use the
KAV$M_READ_TMRCNT modifier to read the timer register. The value of

the timer_count argument, when multiplied by the clock period for the timer
(400 ns), specifies the time that elapses before the timer issues an AST.

4-136

KAV30 System Services

KAVS$TIMERS

For the 32-bit timers, the value of the timer_count argument must not exceed
(292 — 1). For the watchdog timer and the local bus timeout timer, which are

16-bit timers, the value of the timer_count argument must not exceed (216 — 1).

If the timer_count argument specifies a value greater than the maximum
allowed, the service truncates the value to the maximum value.

The minimum prescaler value is two. This gives a minimum timeof 800 ns.
See Section 3.2 for more information about the KAV30 timers.
ast_addr

Usage:
VAX Type:
Access:

Procedure entry mask
procedure
Read only

Mechanism:

Reference

Specifies the address of the AST routine that this service calls when the timer
interval expires. See Section 3.1 for more information about ASTs.
Specify the ast_addr argument only when the timer_functions argument
specifies the KAV$M_LOADTMRCNT modifier.

ast_param

Usage:
VAX Type:
Access:

Mechanism:

Longword (unsigned)
longword_unsigned
Read only

Value

Specifies a parameter that this service passes to the AST routine that this
service calls when the timer interval expires. See Section 3.1 for more

information about ASTs.

Specify the ast_param argument only when the timer_functions argument
specifies the KAV$M_LOAD_TMR_CNT modifier.

KAV30 System Services 4-137

KAV$TIMERS

Status Values
KAV30$_BAD_MODIFIER

You did not specify a modifier in the correct

KAV30$_BAD_PARAM
KAV30$_TMR_BUSY
KER$_BAD_COUNT

You did not specify a parameter in the correct
format.
The timeris busy.
You did not specify the correct number of

KER$_BAD_VALUE

You did not specify a value in the correct

KER$_NO_ACCESS
KER$_SUCCESS

The service cannot access an item.

format.

arguments.

format.

The operation is successful.

Examples
The following code is an example program that calls the KAV$TIMERS
service:
#module kavtimer

4-138 KAV30 System Services

KAVS$TIMERS

[RR KRRKKKKR KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KK

*
x

* 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 OF ITS *
* SOFTWARE ON EQUIPMENT WHICH IS NOT SUPPLIED BY DIGITAL.
*
*

KKK KKK KK KKK KKK KK KKK KKK KKK KEK KK RK KR KKK KKK KER KR KKK KKK KKK KKK KKK KKK KK EKER /

/*
FACILITY:

KAV system services DTM suite

PURPOSE: This routine uses one of the 32-bit timers to measure the

time between to system services or to generate an AST when
the timer times out.

*/
#include Svaxelnc
#include stdio
#include <elnS:kavdef.h>

#include $get_messagetext
#define CONST

0x10000

void
void

errortext ();
ast_routine();

int

ast_count;

main

()

{
void
int
int

errortext ();
status, ipl;

1, j, value,tick;

unsigned int
unsigned int
int

timercount, timervalue;
highvalue, lowvalue;
minvalue, maxvalue;

/* status for any call */
/*params for KAVSTIMERS*/

KAV30 System Services 4—139

KAV$TIMERS
ipl
astcount

= 22;
= 0;

lowvalue

= 9;

timercount

= highvalue * CONST + lowvalue;

tick
value

= 2;
= 0;

highvalue

= QxFFF;

/* 5 * 400ns = 2us => tick */

printf("start of timer test ..... \n") ;

/*
*

raise IPL to prevent timer IRQ - Kernel mode only !!!

[RRRKKK KR KK KKK KKK KKK KK KKK KK KK KKK KK KKK KKK KKK KKK KKK KKK KKK KK KEK EKER KKK KEK KKKER /

ELNSDISABLE INTERRUPT (ipl) ;

[RRR RRR RRR KKK KERR RR RRR KKK RR RR RAK KR KKK RRR RR KKK RRR KKK RRR KK RK KERR KKK KEKE /

for (i=0; 1<100; i++)

{

/*
*
x

Load and start timer (from here timer can only be read in
conjunction with STOP modifier)
KAVSTIMERS

(&status,

KAVSMSTARTTMR + KAVSMLOADTMRCNT,
KAVSKCTMR1,

&timercount,
astroutine,

NULL) ;

/*
*
*

Time is measured between these routines - any code put in
here will be ‘measured’

the high counter will time out and an AST is generated.

s
x/

if the time value (highvalue * tick) is less then 90us,
7

[RRR RRR KK KR KEK KEK KKK KK KR KK KK KKK KR KK KK KKK KKK KKK KK KKK KKK KKK KKK KKK KKK KK KKK KK KE /

/**x* put your code to ‘measure’ in here ...and see whats happening... ***/

[RRR KKK KKK KK KK KKK KKK KKK KK KK KKK KR KK KK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KK KK KE /

KAVSTIMERS

(&status,

KAVSMSTOPTMR + KAV$MREADTMRCNT,
KAVS$KCTMR1,

&timervalue,
NULL,
NULL) ;

if (! (status & 1))
errortext (status);

4-140 KAV30 System Services

KAV$TIMERS
/*
*
x
x

The timervalue high order word (highcounter) is shifted
to the low order word (disregarding lowcounter value) and
then subtracted from highvalue (highcounter start value).

timer value is then the elapsed time in tick’s. timer value

* is added to value, this cumulates the timervalues for allruns.
*/
timervalue
value
if

else

{
}
{
}

/*
*

=
=

highvalue - (timervalue / CONST);
value + timervalue;

> 0)
if
if

(timervalue < minvalue) minvalue = timervalue;
(timervalue > maxvalue) maxvalue = timervalue;

minvalue
maxvalue

= timervalue;
= timervalue;

In order to run the timers again, they have to be reset

KAVSTIMERS

(&status,

KAVSMRESETTMR,
KAVSK_CTMR1,

&timercount,
NULL,
NULL) ;

if (! (status & 1))
errortext (status);
/*

}

/* continue with loop */
The cumulated value is divided by i (number of runs) and

x
x
*
*

multiplied with tick (low counter time). The first lowcounter
timeout will load the highcounter value and the second (and
every following) lowcounter timeout will decrement the
highcounter, therefore one tick is added to value.
if

(astcount >0)

printf("number of AST’s ocurred: %d \n", astcount);

KAV30 System Services 4-141

KAVSTIMERS

else

{

value
minvalue
max value

= ((value / i) * tick) + tick;
= (minvalue * tick) + tick;
= (maxvalue * tick) + tick;

printf("mean time for %d runs : $d microSeconds \n", i, value);

printf("best case: sd uS - worst case: %d uS\n", minvalue,
maxvalue) ;

}

printf ("Test KAVTIMER completed successfully") ;
exit (1);

}

HHH

[RRR RKKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KK KKK KKK KKK KKK KK KKK KKKKKKKK

Name:

ASTROUTINE()

Abstrcat:

Control is transferred to this routine whenever
the started timer counts to zero

Input:

astparam (if defined in KAVSTIMERS)

Output:

none

Comment:

If the high value is short enough, high counter

will timeout before the STOP+READ service has

executed therefore an AST will occur and control
is transferred to this routine. Since the timeout
will stop the highcounter (lowcounter will
continue decrementing), any read of timervalue
will show the original contents of the

loadregisters. If timers are set to repeated

mode, counters will be reloaded and started again.
Any READ in the ASTROUTINE without the STOP
modifier will then return the TIMERBUSY error.

KKK KKK KKK KKK KKK KK KKK KKK KKK KKK KKK KKK KK KK KKK KR KKK KKK KKK KKK KKK KKK KKK KKK KEK KE /

ast_routine ()

void

{

void
int

errortext ();
status;

int
int
int

timerfunctions;
timernumber;
timervalue;

astcounttt;
return;

4-142 KAV30 System Services

/* status for any call */

KAV$TIMERS

[RRKKRKKRK KK KKK KKK KKK KKK KK KR KKK KKK KKK KKK KKK KK KK KKK KKK KKK KKK KKK KKK KK KKK KKK KK
x

Name:

ERROR_TEXT()

x
:

Abstrcat:

Routine converts kernel error number's to text
and print’s it

Input:

status

Output:

none

Comment:

none

KAR KKK KK RK KK KEK KKK KKK KK KKK RK KK KKK KKK KKK RK KERR KK KKK KKK KEK KERR KKK KKK /

void

{

error text (status)

int status;

int

char

text_mapfunctions; /* parameters for $get_message */

text_buffer[255];

VARYINGSTRING(255) resultstring;

text_mapfunctions = STATUSSALL;
eln$Sget_statustext ( status,
text_mapfunctions,
VARYINGTOCSTRING

&éresultstring) ;

( resultstring,textbuffer) ;

printf( "ss\n", text_buffer) ;
printf ("KAVSXXX Error : %d \n", status);
return;

KAV30 System Services 4-143

KAVS$UNMAP

KAV$UNMAP
Frees the SGM entries that the KAV$IN_MAP and KAV$OUT_MAPservices
allocate.

If the SGM entries were allocated by calls to the KAV$IN_MAP service that

specified a location monitor, the KAV$UNMAP service clears any ASTs that are
pending as a result of attempts by VMEbusdevices to access the KAV30 PO
space.
See Section 3.6 for more information about the SGM.

Ada Call Format
WITH KAVDEF:
KAV_UNMAP

([STATUS => stfatus,]
SGM_ENTRY => sgm_entry,
PAGE_COUNT => page_count,

VIRTUAL_ADDRESS => virtual_adaress,

UNMAP_FUNCTIONS => unmap_functions);

argumentinformation
status:

out

CONDITION_HANDLING.COND_VALUE_
TYPE;

sgm_entry :

INTEGER;

page_count:

INTEGER;

virtual_address:

SYSTEM.ADDRESS;

unmap_functions:

INTEGER;

4-144 KAV30 System Services

KAVSUNMAP

C Call Format
#include $vaxelnc
#include "eln$:kavdef.h"

int kav$unmap ([status,]
entry,

page_count,

virtual_address,

unmap_functions)

argumentinformation
int

*status;

int

entry;

int

page_count;

void

*virtual_address;

int

unmap_functions;

FORTRANCall Format

INCLUDE ’ELN$:KAVDEF.FOR’
CALL KAV$UNMAP_ ([status],
%VAL(entry),
%VAL(page_count),
virtual_adaress,

%VAL(unmap_functions))

KAV30 System Services 4-145

KAVS$UNMAP

argumentinformation
INTEGER*4
INTEGER*4

status
entry

INTEGER*4
INTEGER*4
INTEGER*4

page_count

virtual_address
unmap_functions

Pascal Call Format

INCLUDE $KAVDEF:
KAVSUNMAP

([STATUS := status,]

entry,

page_count,

virtual_address,

unmap_functions)

argumentinformation
status :
entry :
page_count :

virtual_address:
unmap_functions:

4-146 KAV30 System Services

INTEGER;
INTEGER;
INTEGER;
AANYTYPE;

INTEGER;

KAVSUNMAP

Arguments
status

Usage:
VAX Type:
Access:

Longword (unsigned)
cond_value
Write only

Mechanism:

Reference

Receives the completion status.
entry

Usage:
VAX Type:
Access:

Mechanism:

Longword (unsigned)
longword_unsigned
Read only
Value

Specifies the first SGM entry that you want to unmap.

page_count
Usage:
VAX Type:
Access:

Mechanism:

Longword (unsigned)
longword_unsigned
Read only

Value

Specifies the number of successive 64K byte pages that you want to unmap.
virtual_address
Usage:
Longword (unsigned)
VAX Type:
longword_unsigned
Access:
Read only
Mechanism:

Value

Specifies the virtual address at which the KAV30 software starts unmapping
pages.

KAV30 System Services 4-147

KAVS$UNMAP

unmap_functions
Usage:
Longword (unsigned)
VAX Type:
mask_longword
Access:
Read only
Mechanism: Value
Specifies whether the SGM entries that you want to unmap are incoming
(mapping VMEbusaddress space into KAV30 I/O space) or outgoing (mapping
KAV30 I/O space to VMEbus or VSB address space). Specify one of the
following modifiers:
KAV$M_IN
KAV$M_OUT
KAV$M_CSR
KAV$M_MEMORY

Unmapsthe incoming SGM entries
Unmapsthe outgoing SGM entries
Unmaps the SGM entries that map the KAV30
FIFO buffers to the VMEbusaddress space
Unmaps the SGM entries that map the
VMEbus or VSB address space

Status Values
KAV30$_BAD_MODIFIER

You did not specify a modifier in the correct

KAV30$_BAD_PARAM

You did not specify a parameter in thecorrect
format.
The SGM entryis valid but must be invalid.

KAV30$_SGMSETCLR
KAV30$_SGM_INCONS
KER$_BAD_COUNT

format.

The SGM entries are inconsistent.

You did not specify the correct number of
arguments.

KER$_BAD_VALUE

You did not specify a value in the correct
format.

KER$_NO_ACCESS
KER$_SUCCESS

The service cannot access an item.

4-148 KAV30 System Services

The operation is successful.

KAVS$UNMAP

Related Services
KAV$IN_MAP

KAV$OUT_MAP

Examples
See the examples in the description of the KAV$BUS_READ, KAV$IN_
MAP, and KAV$OUT_MAP services.

KAV30 System Services 4—149

KAV$VME_SETUP

KAV$VME_SETUP
Allows you to perform the following VMEbus and VSBconfiguration:
Enable or disable the VMEbus IRQs
Enable or disable the VSB IRQs

Read the VMEbus A24 base address
Set the VMEbus A382 base address
Read the VSB slot number
This service specifies a subset of the configuration information that you

specify when you use the VAXELN System Builder utility to build the system.
However, the values that you specify in a call to this service override the values
that you specify when you use the VAXELN System Builder. See Section 5.4
for more information about using the VAXELN System Builder.
This service allows you to perform the following VMEbus and VSB
configuration:
VMEbus IRQs
The VMEbus can send the IRQs at seven different levels. You can specify

the IRQ levels at which the KAV30 can receive the IRQs. You pass a bit
mask to the service to enable or disable the KAV30 to receive the IRQs at
each IRQ level.

When you enable an IRQ line, you can pass a bit maskto this service to
switch between autovectored IRQs and vectored IRQs on that line. See
Section 5.4.1 for more information.

VSB IRQs
The VSB has one IRQ line, on which the KAV30 can receive autovectored
IRQs from the VSB. You can call this service to enable or disable an IRQ
from the VSB.
VMEbus A24 base address

You can use this service to read the setting of the KAV30 rotary switch.

This switch determines the value of the KAV30 VMEbus A24 base address.

4-150 KAV30 System Services

KAV$VME_SETUP

VMEbus A382 base address
You can use this service to specify the KAV30 VMEbus A32 base address.

VSB slot number

The VSB has upto six slots that accommodate from zero to six VSB
modules. You can use this service to read the VSB slot numberfor the
KAV30. When you do not have a VSB backplane, this service returns the
slot number seven.

Ada Call Format
WITH KAVDEF:
KAVVMESETUP ([STATUS => status,]

SETUP_FUNCTIONS => setup_functions,

BUFFER => buffer);

argumentinformation
status:

out

CONDITION_HANDLING.COND_VALUE_
TYPE;

setup_functions:
buffer :

in
in

INTEGER;
SYSTEM.ADDRESS;

C Call Format
#include $vaxelnc
#include "eln$:kavdef.h"

int kav$vme_setup ([status],
setup_functions,
buffer)

KAV30 System Services 4-151

KAV$VME_SETUP

argumentinformation
int

*status;

int

setup_functions;

int

“buffer;

FORTRAN Call Format
INCLUDE ’ELN$:KAVDEF.FOR’
CALL KAV$VME_SETUP

((status],
%VAL(setup_functions),
buffer)

argument information
INTEGER*4

status

INTEGER*4

setup_functions

INTEGER*4

buffer

Pascal Call Format

INCLUDE $KAVDEF;
KAV$VME_SETUP ([STATUS:= status,]
setup_functions,

buffer)

argument information
status:

INTEGER;

setup_functions:
buffer :

INTEGER;
INTEGER;

4-152 KAV30 System Services

KAV$VME_SETUP

Arguments
status

Usage:

Longword (unsigned)

Access:

Write only

VAX Type:
Mechanism:

cond_value
Reference

Receives the completion status.
setup_functions
Usage:
Longword (unsigned)
VAX Type:
longword_unsigned
Access:
Mechanism:

Read only
Value

Specifies the function that you want this service to perform. Specify one or
more of the following values:
KAV$K_ALLOW_VME_IRQ

Enables or disables the VMEbusinterrupts
according to the bit mask specified by the
buffer argument.

KAV$K_AUTO_VME_IRQ

Switches from vectored to autovectored IRQs
when an IRQ line is enabled. If a bit is clear,

the corresponding IRQ line handles vectored
interrupts. If a bit is set, the corresponding

IRQ line handles autovectored interrupts.

KAV$K_DISABLE_VSB_IRQ
KAV$K_ENABLE_VSB_IRQ
KAV$K_RD_A24_ROTARY

Disables the VSB interrupts.
Enables the VSB interrupts.
Reads the value of the VMEbus A24 mode
base address from the KAV30 rotary switch.
This service returns the value of the switch in
the low-order four bits of the buffer argument.

KAV$K_RD_VSB_SLOT
KAV$K_SET_A32_BASE

Reads the VSB slot numberinto the low-order
3 bits of the buffer argument.
Sets the high-order byte of the VMEbus A32
mode base addressto the value specified in the
buffer argument.

KAV30 System Services 4-153

KAV$VME_SETUP

buffer
Usage:

Longword (unsigned)

Access:
Mechanism:

Modify
Reference

VAX Type:

longword_unsigned

Contains data that this service uses to carry out the function specified by the
setup_functions argument. The following table explains the contents of the
buffer argument for each setup_functions value.
setup_functions Value

Contents of buffer argument

KAV$K_ALLOW_VME_IRQ

The low-order byte contains a bit mask

that controls whether the KAV30 enables
or disables the VMEbus IRQs at each IRQ
level. The KAV30 enables the VMEbus IRQs
at each IRQ level for which a bit is set. The

following diagram showsthe bit mask:

______ Reserved, must be zero
Allow VMEbusIRQ 1
Allow VMEbusIRQ 2
Allow VMEbus IRQ 3
Allow VMEbus IRQ 4
Allow VMEbus IRQ 5

Allow VMEbus IRQ 6
Allow VMEbus IRQ 7

KAV$K_AUTO_VME_IRQ

The low-order byte contains a bit mask

that controls whether the KAV30 switches
an enabled IRQ line from vectored to
autovectored. The KAV30 switches an enabled
IRQ line from vectored to autovectored at each
IRQ level for which a bit is set. The bit mask

has the same layout as the vectored IRQ bit
mask.

4-154 KAV30 System Services

KAV$VME_SETUP
setup_functions Value

Contents of buffer argument

KAV$K_RD_A24_ROTARY

Returns the value of the VMEbus A24 mode
base address from the rotary switch on the

KAV30 in the low-order four bits of the buffer
argument.

KAV$K_RD_VSB_SLOT
KAV$K_SET_A32_BASE

Returns the VSB slot numberin the low-order
three bits of the buffer argument.
The low-order byte contains the VMEbus A32
modebase address.

Status Values
KAV30$_BAD_PARAM

You did not specify a parameter in the correct
format.

KER$_BAD_COUNT

You did not specify the correct number of

KER$_BAD_VALUE

You did not specify a value in the correct
format.

KER$_NO_ACCESS
KER$_SUCCESS

The service cannot access an item.

arguments.

The operation is successful.

Related Services
KAV$INT_VME

Examples
See the examples in the description of the KAV$BUS_BITCLRservice.

KAV30 System Services 4-155

Developing KAV30 Applications
This chapter describes how to develop applications for the KAV30. It gives
information on the following:
e

Design guidelines

Coding guidelines

Compiling and linking KAV30 applications

Building KAV30 system images

Loading and running KAV30 system images

Debugging KAV30 applications

Developing SCSI class drivers

Building a SCSI class driver into an application

5.1 Design Guidelines
This section gives guidelines for designing KAV30 applications. It gives
guidelines for the following actions:
e

Accessing the VMEbus and VSB address space

Writing AST routines

5.1.1 Accessing the VMEbus and VSB Address Space
This section gives guidelines for accessing the VMEbus and VSB address space.
There are two methods of accessing the VMEbus and VSB address space:
e

Directly accessing the address space

Using the KAV$BUS_READ and KAV$BUS_WRITEservices

Developing KAV30 Applications 5—1

Developing KAV30 Applications

5.1.1.1

Directly Accessing the VMEbus and VSB Address Space
Digital recommendsthat you directly access the VMEbus and VSB address
space underthe following circumstances:

When the KAV380is the only bus master and there are no slow devices on
the bus

When you want to migrate existing VMEbus or VSB applications to the
KAV30

Use the virtual addresses that the KAV$OUT_MAPservice returns to access

the address space.

When errors occur during a direct access, the KAV30 kernel generates an
exception condition. If you want your application to handle the exception,
the application must include a condition handler for the exception. In the

process context, when the application does not include a condition handler for

the exception, the system invokes the last chance handler. Invoking the last
chance handler usually deletes the process that causes the exception to occur.
Note

The system fails if an error occurs while you are directly accessing the
VMEbus or VSBfrom an ISR.
If the system fails because an error occurs while you are directly accessing the
VMEbusor VSBfrom an ISR, the stack contains the following data:
e

The numberof arguments

The VAXELN status code

The VMEbus or VSB address that the KAV30 tried to access

The value of the Program Counter (PC) when the error occurred

The value of the processor status longword when the error occurred

A sample stack dumpfollows:
4
00007E3C
00F00000
8000B123
00C80009

5-2

Developing KAV30 Applications

5.1.1.2 Using the KAV$BUS_READ and KAV$BUS_WRITEServices
Digital recommends that you use the KAV$BUS_READ and KAV$BUS_WRITE
services only under the following circumstances:
e

Whenthere is more than one bus master

Whenthere are slow devices on the bus

When you want to communicate with another KAV30

When you want to ensure that the errors due to bus timeouts and

When you are testing systems that are under development

When you are writing an ISR routine (elevated IPL)

arbitration problems do not interfere with the data transfer

5.1.2 Writing Asynchronous System Trap Routines
Use the following guidelines for writing AST routines:
¢

Do not include mutexes

Do not include J/O routines

Do not include signal calls to your own process

When an AST routine contains a mutex or an J/O routine, unpredictable
behavior can result, especially in cases where your application code is not

reentrant. When an AST routine contains a signal call to your own process,

the system can hang.

5.2 Coding Guidelines
This section provides guidelines for coding KAV30 applications in each of the
supported languages. The supported languagesare asfollows:
e

VAX Ada

VAX C

VAX FORTRAN

VAXELN Pascal

Developing KAV30 Applications 5-3

Developing KAV30 Applications

5.2.1 VAX Ada
When you write VAX Ada programsfor the KAV30, follow these guidelines:
e

Include the VAX Ada package for the KAV30 kernel. The nameofthis
package is ELN$:KAVDEF.ADA.

Whenyou call the KAV30 system services, specify their inclusion at the
start of the code. For example:
WITH KAVDEF;
USE KAVDEF;

KAVDEFAST(status, devicecode) ;

If you omit the USE statement, call the system services as follows:
WITH KAVDEF;

KAVDEF .KAVDEFAST(status, devicecode) ;

Whenyou call VAXELN kernel routines, include the following line in the
code:
WITH VAXELNSERVICES;

See the VAXELN Ada User’s Manual and the VAXELN Ada Runtime Library
Reference Manual for more information about writing programs in VAX Ada.
5.2.1.1 Coding Asynchronous System Trap Routines in VAX Ada
When you write AST routines in VAX Ada, declare the routines in a separate
package. For example:
with VAXELNSERVICES;

package ASTROUTINES is
TRIGGEREDEVENT : VAXELNSERVICES.EVENTTYPE;

procedure ASTROUTINE;
pragma EXPORTPROCEDURE (ASTROUTINE) ;
end ASTROUTINES;
package body ASTROUTINES is

procedure ASTROUTINE is

5-4 Developing KAV30 Applications

Developing KAV30 Applications

begin
VAXELNSERVICES.SIGNALEVENT( EVENT => TRIGGEREDEVENT) ;
end ASTROUTINE;
end ASTROUTINES;

When you specify an AST parameterin a call to a KAV30 service, specify
the value of the AST parameter. However, because VAX Ada always passes
arguments by reference, you must use the SYSTEM.TO_INTEGERfunction
to convert the address of the AST parameter into an integer and pass the
integer to the service. Because VAX Ada passes arguments by reference, it
uses the integer as an address. However, because the address contains the
required AST parameter value, the AST routine receives the correct value. The
following example shows how to implement this mechanism in a call to the
KAV$IN_MAP system service.
with ASTROUTINES, VAXELNSERVICES;
package signallertask is
SIGNALLEREVENT : VAXELNSERVICES.EVENTTYPE;
task type signaller is
end signaller;

end signallertask;
package body signallertask is
task body signaller is
begin
VAXELNSERVICES.WAITANY( VALUE1 => ASTROUTINES.TRIGGEREDEVENT) ;
VAXELNSERVICES.CLEAREVENT( EVENT => ASTROUTINES.TRIGGEREDEVENT) ;
VAXELNSERVICES.SIGNALEVENT ( EVENT => ASTROUTINES.TRIGGEREDEVENT) ;
end signaller;

end signallertask;
with ASTROUTINES, TEXTIO, KAVDEF, CONDITIONHANDLING, SYSTEM,
VAXELNSERVICES, SIGNALLERTASK;

procedure ASTTEST is

Developing KAV30 Applications 5-5

Developing KAV30 Applications
STATUS : CONDITIONHANDLING.CONDVALUETYPE;

SGMENTRY : INTEGER;
BUSPAGE : SYSTEM.ADDRESS;
INPAGE : SYSTEM.ADDRESS;
MAPFUNCTIONS : INTEGER;
UNMAPFUNCTIONS : INTEGER;

KAVSERVICEERROR : exception;
package STATUSIO is new

TEXTIO.INTEGERIO(CONDITIONHANDLING.CONDVALUETYPE) ;

signaller : SIGNALLERTASK.SIGNALLER;

begin

MAPFUNCTIONS := KAVDEF.KAVMMEMORY + KAVDEF.KAVMLOCMONIPL17;
VAXELNSERVICES.CREATEEVENT ( EVENT
=>
ASTROUTINES.TRIGGEREDEVENT,
INITIALSTATE => VAXELNSERVICES .CLEARED) ;
VAXELNSERVICES.CREATEEVENT ( EVENT
=>
SIGNALLERTASK.SIGNALLEREVENT,
INITIALSTATE => VAXELNSERVICES .CLEARED) ;

SGMENTRY := 0;
KAVDEF .KAV_INMAP( STATUS
SGMENTRY
PAGECOUNT
VIRTUALADDRESS
ASTADDR
MAPFUNCTIONS

=> STATUS,
=> SGMENTRY,
=> 1,
=> BUSPAGE,
=> ASTROUTINES.ASTROUTINE’ ADDRESS,
=> MAPFUNCTIONS) ;

if not CONDITIONHANDLING. SUCCESS (STATUS)

raise KAVSERVICEERROR;

then

end if;

VAXELNSERVICES.WAITANY( VALUE1 => SIGNALLERTASK.SIGNALLEREVENT) ;
TEXTI0.PUTLINE("After call to WAITANY");
KAVDEF .KAV_UNMAP ( STATUS
=> STATUS,
SGMENTRY
=> SGMENTRY,
PAGE COUNT
=> 1,
VIRTUALADDRESS => BUSPAGE,
UNMAPFUNCTIONS => KAVDEF.KAVMIN);

if not CONDITIONHANDLING. SUCCESS (STATUS)

raise KAVSERVICEERROR;

end if;

exception

5-6

Developing KAV30 Applications

then

Developing KAV30 Applications

when KAVSERVICEERROR =>

TEXTI0.PUT("Error detected: ");
STATUSIO.PUT( ITEM => STATUS, WIDTH => 8,
TEXTIO.NEWLINE;

when others
raise;

BASE => 16);

end ASTTEST;
See Section 3.1 for more information about ASTs and AST parameters. See
the VAX Ada Run-Time Reference Manual for more information about writing
VAXELN Ada programs that involve ASTs.

5.2.2 VAXC
When you write VAX C programsfor the KAV30, follow these guidelines:
e

Use the #include compiler preprocessor directive to include the following
text libraries:
—-

$vaxelnc, which defines the necessary VAXELN constants, data types,

—

eln$:kavdef.h, which defines the KAV30-specific constants, data types,
and procedures

and procedures

Specify all the arguments, required and optional, in system service calls.
Specify optional arguments—that is, arguments for which you want to
use default values—as 0 or NULL. NULLis a constant (defined in the
$vaxelnc library) that allows you to supply the value 0 for an argument,
yet maintain readability.

The default argument passing mechanism in VAX is by value. Use one of
the following methods to pass an argument by reference in VAX C:
—

Prefix the argument with the address-of operator (&). For example:
defineASB()

{

int *status;

kavSdefast (&status,

}
—

devicecode) ;

Create a pointer to the argument, then pass the pointeritself. For

example:

Developing KAV30 Applications 5-7

Developing KAV30 Applications
defineASB()

{

int *statusaddress, status;
statusaddress = éstatus;
kav$defast (statusaddress,
devicecode) ;

}

Digital recommends that you use the address-of operator method, because
using the pointer method increases the numberof variables that you use
and the amount of work the compiler must perform.
The KAV30 system service descriptions prefix arguments that must be
passed by reference with an asterisk (*).
Use a bitwise AND operation (& ) on the status value and 1 to check the
status values, or if you are testing for failure, negate the result, as follows:
if (status & 1)

successstatement; /*

(status & 1))

errorstatement;

success

failure

See the VAXELN C Reference Manual and the VAXELN C Runtime Library
Reference Manual for information about writing VAXELN programs in VAX C.

5.2.3 VAX FORTRAN
When you write VAX FORTRAN programsfor the KAV30, follow these
guidelines:
Include the file ELN$:KAVDEF-.FOR.This file includes the KAV30-specific
constants, data types, and procedures.
Unlike VAX C, where you must provide all the arguments, you can omit
optional arguments in calls to VAX FORTRAN run-timelibrary routines.
For example:
CALL KAVSDEFAST(status, devicecode)

! optional argument included

CALL KAVSDEFAST(,devicecode)

! optional argument omitted

The default argument passing mechanism in VAX FORTRAN is by
reference. Use the %VAL function to pass arguments by value.

The KAV30 system service descriptions use the %VAL function to pass
arguments by value.
See the VAX FORTRAN Language Reference Manual and the VAXELN

FORTRAN Runtime Library Reference Manual for more information about

writing programs in VAX FORTRAN.

5-8 Developing KAV30 Applications

Developing KAV30 Applications

5.2.4 VAXELN Pascal
When you write VAXELN Pascal programs for the KAV30, includethe file
ELN$:KAVDEF-PAS. This file includes the KAV30-specific constants, data
types, and procedures.

See the VAXELN Pascal Language Reference Manual and the VAXELN Pascal
Runtime Library Reference Manual for more information about writing

programs in VAXELN Pascal.

5.2.4.1

Coding AST Routines in VAXELN Pascal
When you write the AST routines in VAXELN Pascal, perform the following
actions:

Declare the routines in a separate compilation module.

In programsthat call system services with an AST routine as an argument,

declare the routines to be external with data type KAV$AST_ROUTINE_
TYPE. For example:
MODULE ast_routine;
VAR

asttriggeredevent :

[EXTERNAL] event;

PROCEDURE astroutine;
BEGIN

SIGNAL(asttriggeredevent);
END;
END;

The following example shows a program called TEST, which includesa call to
the AST routine declared in the module described:
MODULE asttest;
INCLUDE SKAVDEF;
TYPE
byte = [byte] 0..255;

vmebuspage = packed array [0..65535] of byte;
VAR

pid : PROCESS;

asttriggeredevent : EVENT;
signallerevent : EVENT;

astroutine : [EXTERNAL] kavSastroutinetype;
PROCESSBLOCK signaller;

Developing KAV30 Applications 5-9

Developing KAV30 Applications
BEGIN
WAITANY( asttriggeredevent) ;

CLEAREVENT( ast_triggered_event) ;
SIGNAL( signallerevent)

END;
PROGRAM test (input, output);
VAR

status : INTEGER;

entry : INTEGER;

buspage : “vmebuspage;

inpage : “vmebuspage;
mapfunctions : INTEGER;
BEGIN

CREATEEVENT( asttriggeredevent, EVENTSCLEARED, STATUS := status);
IF NOT ODD(status) THEN
BEGIN

WRITELN (‘CREATEEVENT error : ', HEX(status) );
EXIT

END;

CREATEEVENT( signallerevent, EVENTSCLEARED, STATUS := status);
IF NOT ODD(status) THEN
BEGIN
WRITELN (‘CREATEEVENT error :

EXIT

’,

HEX(status));

END;

CREATEPROCESS( pid, signaller, STATUS := status);
IF NOT ODD(status)

THEN

BEGIN
WRITELN (‘CREATEPROCESS error : ', HEX(status));
EXIT

END;

mapfunctions := KAVSMMEMORY + KAVSMLOCMONIPL17;
entry := 0;

KAVSINMAP( STATUS := status,
ENTRY := entry,

PAGECOUNT := 1,

VIRTUALADDRESS := buspage,

ASTADDR := ADDRESS (astroutine),

MAPFUNCTIONS := mapfunctions) ;

5-10 Developing KAV30 Applications

Developing KAV30 Applications

IF NOT ODD(status)
BEGIN

THEN

WRITELN(’ KAVSINMAP error : ', HEX(status));

EXIT
END;

WAITANY( signallerevent,
STATUS := status);
IF NOT ODD(status) THEN
BEGIN

WRITELN(’WAITANY error : ', HEX(status));

EXIT

END;

CLEAREVENT( signallerevent) ;
WRITELN(’After call to WAITANY’);

KAVSUNMAP ( STATUS := status,
ENTRY := entry,
PAGE COUNT := 1,

VIRTUALADDRESS := buspage,

UNMAPFUNCTIONS := KAV$MIN);

IF NOT ODD(status) THEN
BEGIN
WRITELN (’KAVSUNMAP error : ', HEX(status));
EXIT
END;
END.
END;

Because the AST routine is an external reference, you can resolve it at link
time. For example, if the program containing the AST routine is called AST_
ROUTINES.PAS, build it into the system as follows (where TEST.PASis the
name of the main program):
$ LINK TEST + ASTROUTINE + ELNS$:KAVSRTLOBJLIB/LIB + ELN$:RTLSHARE/LIB + -

_$ + RTL/LIB

When the AST routines include calls to the KAV30 system services, follow

these steps:
I.

Include the file ELN$:KAVDEF.PASin the program.

When you compile the program, include the KAV30 object library in the
commandline. For example:
> EPASCAL ASTROUTINE + ELN:KAVSRTLOBJLIB/LIB

Developing KAV30 Applications 5-11

Developing KAV30 Applications
For more information on the ASTs and AST parameters, see Section 3.1. For

more information on writing VAXELN Pascal programs that involve ASTs, see

the VAXELN Pascal Run-Time Language Reference Manual.

5.3 Compiling and Linking KAV30 Applications
For each language supported by the VAXELN Toolkit, there is an optimizing

compiler that generates position-independent object code from the source code.

Use the VMS Linkerto link the object modules with the appropriate run-time
libraries for the language in which your source code is written. For example,
you must link C object modules with the VAXELN C Run-TimeLibrary.
You must link all object modules with the VAXELN Kernel general purpose
run-time library (RTL.OLB), and with the VAXELN Pascal run-time shareable
library (RTLSHARE.OLB).
Linking the object modules with one or more run-timelibraries results in a
single copy of each run-time library being built into the application image,
where it can be shared byall the programs that make up the image.
Table 5—1 lists the commands that compile and link programs written for the
KAV30 in each of the languages supported by VAXELN.
You can add qualifiers to the compiler commandline to control the actions of
the compiler. For example, the /DEBUG qualifier instructs the compiler to
build symbolic debugging information into the application.
For more information about compiling VAXELN programs, see the appropriate
language reference manual. For more information about linking VAXELN

programs with run-timelibraries, see the VAXELN Development Utilities
Guide.

5-12

Table 5-1

Compiling and Linking Commands

Language

Compile Command

VAXELN Ada

S ADA FILENAME. ADA

VAX C

S CC FILENAME.C + ELN$:VAXELNC/LIB

VAX FORTRAN

S FORTRAN FILENAME .FOR

VAXELNPascal

° EPASCAL FILENAME .PAS + ELNS:KAVSRTLOBJLIB/LIB + ELNS : RTLOBJECT/LIB

Developing KAV30 Applications

Language

Link Command

VAXELN Ada

$ ACS LINK UNITNAME + ELN$:KAVSRTL_OBJLIB/LIB + +...

VAX C

S LINK FILENAME + ELNS:KAVSRTL OBJLIB/LIB + -

+ ELNS : CRTLSHARE/LIB + RTLSHARE/LIB + + ELNS:RTL/LIB

VAX FORTRAN

$ LINK FILENAME + ELN$:KAVSRTLOBJLIB/LIB + + ELNS : FRTLOBJECT/LIB + ELNS: RTLSHARE/LIB + + ELNS:RTL/LIB

VAXELN Pascal

> LINK FILENAME + ELNS:KAVSRTLOBJLIB/LIB + + ELNS$ :RTLSHARE/LIB + ELNS:RTL/LIB

5.4 Building KAV30 System Images
The VAXELN System Builder component of the VAXELN Toolkit combines

your application image with the VAXELN-supplied software components to

create a VAXELN system image, which you can load on the KAV30.

The System Builder provides a menu interface through which you enter
information about the system you are building. For example, you can enter
the namesof the files that make up your application image on the Program
Description menu, and you can specify the external device information on the
Device Characteristics menu.
For more information about the System Builder, see the VAXELN Development
Utilities Guide.
To build a system image that runs as a target system on the KAV30, follow
these steps:

Invoke the VAXELN System Builder with the following command:
S$ EBUILD/MAP mydatafile
(The /MAP qualifier generates a system mapfile called MYDATAFILE.MAP,

which contains a listing of the images in the system, the devices and
terminals you specify, and the system characteristics.)

2.
3.

On the Target Processor menu, choose rtVAX 300 for the Target Processor

entry.

Return to the Main Menu and add your program descriptions, device
descriptions, and so on as described in the VAXELN Development Utilities
Guide.

Developing KAV30 Applications 5-13

Developing KAV30 Applications
The Ethernet adapter on the rtVAX 300 is a Second Generation Ethernet
Controller (SGEC), type EZA. Therefore, specify EZA for the Network
device entry on the Network Node Characteristics Menu.
Note

For each 64K byte page of system RAM space mapped to the VMEbus
or VSB bus address space by the KAV$OUT_MAP service, you must
increase the System region size entry in the System Characteristics
menu by 128 pages. This is in addition to the 128 pages of system
space required to support KAV30 internal data structures.
For each 64K byte page of VMEbus address space mapped into KAV30
process address space by the KAV$IN_MAPservice, you must increase
the PO virtual size entry in the System Characteristics menu by 128
pages. You do not have to dothis for calls to the KAV$IN_MAPservice
in which the service maps data from the KAV30 CSRpagesto the
VMEbusaddressspace.
If you are running in kernel mode, increase the kernel stack by at least

two pages.

5.4.1 Configuring the VMEbus and VSB
When you build the KAV30 system with the VAXELN System Builder, you can
specify information that controls how the KAV30 interacts with other devices
on the VMEbus and VSB. You specify this information by setting the contents

of the System Parameter 1 and System Parameter 2 options in the EBUILD
System Characteristics Menu (the System Parameter 3 and System Parameter

4 options are available for use by the customers’ applications).

The following list describes how to set the System Parameter 1 and System
Parameter 2 options.
e

System Parameter 1

—

Enable System Parameter 1 and System Parameter 2 byte

This byte controls whether the System Builder uses System Parameter
1 and System Parameter 2 when building the system. When you do
not use System Parameter 1 and System Parameter 2, you can specify
5-14 Developing KAV30 Applications

Developing KAV30 Applications

parts of the information in programsbycalling the KAV$VME_SETUP
system service. See the description of the KAV$VME_SETUPservice
for more information.
By default this byte contains the value 0. When you want to use the
default configurations, set this byte to FFjg and make sure that System
Parameter 1 and System Parameter 2 contain valid settings. When you
do not want to use the default configurations, set this byte to any value
other than FFg.
—
15

VMEbus vectored interrupt mask byte
14

AIALTATALTATLALATLA
Reserved, must be zero
Allow VMEbusIRQ 1
Allow VMEbus IRQ 2
Allow VMEbusIRQ 3
Allow VMEbus IRQ 4
Allow VMEbus IRQ 5
Allow VMEbus IRQ 6
Allow VMEbus IRQ 7

This byte controls whether the KAV30 enables or disables the VMEbus

IRQs at each [RQ level. The module allows the IRQs at each IRQ level
for which a bit is set (1).

This byte has the following default settings:
Bit

Value

Bit

Value

Developing KAV30 Applications 5-15

Developing KAV30 Applications

—

VMEbus and VSB autovectored interrupt mask byte

AIAI[ATAIATALATLA
___

VSB IRQ (IHV Mode, Autovectored)
VMEbusIRQ 1 (Autovectored)
VMEbus IRQ 2 (Autovectored)
VMEbusIRQ 3 (Autovectored)
VMEbus IRQ 4 (Autovectored)
VMEbus IRQ 5 (Autovectored)
VMEbusIRQ 6 (Autovectored)
VMEbus IRQ 7 (Autovectored)

This byte controls whether the KAV30 enables or disables the
autovectored IRQs at each IRQ level. The module allows the
autovectored IRQs at each IRQ level for which a bit is set (1). The
module allows vectored IRQs at each IRQ level for which a bit is clear

(0). This byte has the following default settings:

5-16

Bit

Value

Bit

Value

Developing KAV30 Applications

—
31

VMEbus and VSBcontrol byte
30

AILATATATATATLA
Enable A24 Slave Mode
Enable A32 Slave Mode
Enable VMEbus/VSB Master Port

Reserved, must be zero
Enable VSB Arbitrator Function
Select VSB Release When Done Request Mode
Action to Take on Detection of the VMEbus SYSFAIL Signal
Set System Clock with Value of Real-Time Clock

This byte controls the interaction of the KAV30 with the VMEbus and
VSB. For example, to set the KAV30 to operate in A32 slave mode, set
bit 25 to 1. This byte has the following default settings:
Bit

Value

Bit

Value

The value of bit 30 determines what action the KAV30 takes when
it detects the assertion of the VMEbus SYSFAIL signal. The KAV30
delivers an asynchronous system trap when bit 30 has the value 0. The
KAV30 calls an interrupt service routine (ISR) at vector 540;gwhen bit
30 has the value 1.

Developing KAV30 Applications 5-17

Developing KAV30 Applications

System Parameter 2

—

VMEbusarbiter selection byte
5

ALAA

K A A M

L—— Select VMEbus Request Level LSB
Select VMEbus Request Level MSB
Select VMEbus Request Release on Request
Select FAIR Mode for VMEbus Requester
Select HIDDEN Mode for VMEbus Requester
Reserved, must be zero
Select VMEbus Arbitration Mode LSB
Select VMEbus Arbitration Mode MSB

This byte specifies the VMEbus arbiter information. The following
table explains the VMEbus request level’s most significant bit (MSB)
and least significant bit (LSB):
MSB

LSB

VMEbus Request Level

BRO

BR1

BR2

BR38

The following table explains the VMEbusarbitration mode’s MSB and
LSB:
MSB

LSB

VMEbus Arbitration Mode

Priority encoded

Round-robin

Reserved for Digital

5-18 Developing KAV30 Applications

Developing KAV30 Applications
This byte has the following default settings:
Bit

Value

Bit

Value

See Section 2.4 for more information about the KAV30 VMEbus arbiter
functionality.

—
15

VMEbus slave mode A382 base address byte
14

ATATATATATATATA
VMEbusSlave AddressBit A<24>
VMEbusSlave Address Bit A<25>
VMEbusSlave Address Bit A<26>
VMEbusSlave Address Bit A<27>
VMEbusSlave Address Bit A<28>
VMEbusSlave Address Bit A<29>
VMEbusSlave Address Bit A<30>
VMEbusSlave AddressBit A<31>

This byte specifies the VMEbus base address for the KAV30 acting as a
slave and using A32 addressing mode.
This byte has the following default settings:
Bit

Value

Bit

Value

Developing KAV30 Applications 5-19

Developing KAV30 Applications

—

Bus access software retry count word

Retry Count

The KAV30 kernel performs software retries of a bus access in addition
to the 29 retries performed by the hardware (you can disable hardware
retries, using the KAV$OUT_MAP kernel service). This word contains
the maximum numberof times that a bus access retries before the
KAV30 kernel returns an error to the application. By default this word
contains the value 10 (decimal). Software retries can be necessary
because of bus arbitration contention or bus timeouts.
The numberof software retries must be between 0 and 65 535.

5.5 Loading and Running KAV30 System Images
Once you have built the KAV30 system image, use one of the following
procedures to load it onto the KAV30:
e

Down-line loading the system image over the Ethernet from the VMS host
system or from another VAXELNtarget system

Boot the system image from the KAV30 ROM,a tape, or a disk

Load the system image from an ULTRIX™system (Digital does not
currently supply a VAXELN Toolkit for an ULTRIX host system)

Boot the system image from a DEC™ SCSI floppy disk or hard disk

For more information about down-line loading VAXELN system images, see the
VAXELN Development Utilities Guide.

5.6 Debugging KAV30 Applications
The VAXELN Debugger enables you to debug your application while it runs on
the target computer (in this case, the KAV30). The Debugger allows you to set
breakpoints, examine variables and addresses, deposit values, and control the
execution of your application.
You can run the Debugger remotely (from a terminal connected to the host
computer) or locally (from the console terminal connected to the KAV30).

5-20 Developing KAV30 Applications

Developing KAV30 Applications
In remote mode, you can view source code and refer to program variables by
their symbolic names. In local mode, those operations that require source-file
or other host information, for example, operations that refer to variables by
name, are unavailable. You choose local or remote mode when you build the
system image.

Choosingremote debugging places only a portion of the Debugger in the system
image; the remainder resides on thehost system, as shown in Figure 5-1.
Figure 5-1 A Remote DebuggingConfiguration

VMSHost System
VAXELN RemoteSymbolic
Debugger Component

VAXELNTarget System
Local Debugger
Component

‘ VMS User|
- Terminal

Ethernet

Choosing local debugging places the entire Debugger in the system image, as
shown in Figure 5-2.
See the VAXELN Development Utilities Guide for more information about using
the VAXELN Debugger.

Developing KAV30 Applications 5-21

Developing KAV30 Applications
Figure 5-2 A Local Debugging Configuration

VMS Host System

VAXELN Target System

Debugger

Mass Storage

Transfer Media

Mass Storage

Transfer Media

Console

Terminal

5.7 Developing SCSI Class Drivers
To develop a SCSIclass driver, follow these steps:
1.

Write the SCSI class driver in one of the supported languages.

Compile the SCSI class driver. For example, to compile the SCSIUSER
class driver in VAX C, enter the following command:
$ CC SCSIUSER + ELNS:VAXELNC/LIBRARY

Modify the SCSI driver startup module (SCDRIVER.C) for the new SCSI
driver.
Compile the SCSI driver startup module. For example, to compile the
startup module in VAX C, enter the following command:
$ CC SCDRIVER + ELNS:VAXELNC/LIBRARY

Link the SCSI class driver and the SCSI driver startup module with the
VAXELN SCSI driver components to produce a new VAXELN SCSI driver
image. For example:

$ LINK/EXE=KRDRIVER SCDRIVER + SCSISNIF + SCSIDISK + SCSIGNRC + _$ SCSIUSER + SCSI53C700 + SCSI53C700SCRIPT + SCSI53C700/OPT + _$ ELN$:CRTLSHARE/LIB + RTLSHARE/LIB + RTL/LIB
This LINK commandlinks the SCSI class driver with the startup module,
the sniffer module, the supplied disk and generic class drivers, and the port
driver. If you modified the startup module so that it does not include the
supplied class drivers, omit those driver modules when linking the driver
imageasfollows:

5-22 Developing KAV30 Applications

Developing KAV30 Applications
$ LINK/EXE=KRDRIVER SCDRIVER + SCSISNIF + SCSIUSER + SCSI53C700 + _$ SCSI53C700SCRIPT + SCSI53C700/OPT + ELN$:CRTLSHARE/LIB + _$ RTLSHARE/LIB + RTL/LIB
6.

Build the image into the VAXELN system. See Section 5.8 for information
about building the SCSI driver into a user application.

See the VAXELN Runtime Facilities Guide for more information about

developing user-defined SCSI class drivers.

5.8 Building a SCSI Class Driver into an Application
Before you use SCSI devices in an application, follow these steps:
1.

Set the KAV30 SCSI ID

See the KAV30 Hardware Installation and User’s Information for more
information.
2.

Connect the SCSI devices to the KAV30

See the KAV30 Hardware Installation and User’s Information for more
information.
3.

Include the KAV30 SCSIclass driver in the system image
Enter the following information at the Add Device Description menu in the
VAXELN System Builder:
VAXELN System Builder Prompt

Information to Enter

Name

DUA

Vector address

%O2520

Interrupt priority

Default file spec

ELN$:KRDRIVER.EXE

Device-dependent parameter

%X00000?71 FF

1@nter the KAV30 SCSI ID instead of the question mark (?).

Do not enter information at the other prompts, use the default selections
for these prompts. Enter the KAV30 SCSI ID instead of the question
mark (?) in the information that you must enter as a response to the
Device-dependent parameter prompt. The Device-dependent parameter
determines the KAV30 SCSI ID when there is no valid SCSI ID in the
KAV30 battery backed-up RAM.

Developing KAV30 Applications 5-23

Developing KAV30 Applications
Figure 5—3 shows the Add Device Description menu in the VAXELN
System Builder when you enter the information and specify seven as the
SCSI ID.
Figure 5-3 Sample Add Device Description Menu
System KAU30A.DAT -

Name

BUA

200000000

Yector address

#025620

Interrupt priority

BI number

Adapter number

Autoload driver

Yes

Editing Device

Default file spec

ELN#: KRORIVER, EXE

Network device

Yes

Default

Device-dependent parameter %XOO0007FFR

FS
4.

eee

Specify the devices for automatic mounting at boot time
List the devices that you want to specify at the Disk/volume names prompt
of the Edit System Characteristics menu in the VAXELN System Builder.

See the VAXELN Development Utilities Guide for information about the
VAXELN System Builder.
While you use SCSI devices in applications, you can perform the following
actions:
e

Access devices on the SCSI bus

Use the device’s unique SCSI device nameto access the device. The device
name consists of the characters DUA followed by the SCSI ID of the device.
For example DUA2.

5-24 Developing KAV30 Applications

Developing KAV30 Applications
Manipulate disks andfiles
Use the VAXELN Command Language Utility (ECL) to manipulate local
disks andfiles. See the VAXELN Development Utilities Guide for more
information.

Whenthe system imageis correctly configured, use DECnet to manipulate
remote disks andfiles. See the following documents for more information
about manipulating remote disks andfiles in each supported language:
—

VAXELN C Reference Manual

—

VAXELN FORTRAN Runtime Library Reference Manual

—

VAXELN Ada User’s Guide

—

VAXELNPascal Language Reference Manual

Use local error logging to disk
See the VAXELN Development Utilities Guide for more information.

Developing KAV30 Applications 5-25

Initial KAV30 Configuration
This appendix describes the initial KAV30 hardware and software
configuration.

A.1 Hardware Configuration
This section describes the initial KAV30 hardware configuration.
The KAV30 does not supply power to the SCSI bus TERMPWRsignal.
The KAV30 responds to the VMEbus RESETsignal.
The KAV30 has 256K bytes of user ROM.
The rtVAX 300 Ethernet controller can assert the KAV30 VAX HALT
signal.

The break key assertions on the devices connected to the auxiliary port do
not assert the KAV30 VAX HALTsignal.
There is no power supply to the battery backed-up RAM and the
calendar/clock.
The KAV30 VMEbusarbiter functionality is disabled.
The break key assertions on the devices connected to theserial line ports
assert the VAX HALTsignal.
The VMEbus ACFAIL signal asserts the KAV30 VAX POWER_FAILsignal.
The KAV30 VMEbus A24 base slave addressis set to zero.

Initial KAV30 Configuration A—1

Initial KAV30 Configuration

A.2 Software Settings
This section describes the initial KAV30 software configuration.
The VSBarbiter functionality is disabled.
The VMEbus A382 base slave addressis set to zero.
The VMEbus master functionality is enabled.
The VSB master functionality is enabled.
All the VMEbus IRQsare disabled.
All the VMEbus autovectored IRQs are disabled.

The VMEbus A24 slave functionality is enabled.
The VMEbus A32 slave functionality is enabled.
The VSB bus requester operates in ROR mode.
The VMEbus bus requester operates in ROR mode.
The VMEbus bus requester uses the VMEbus BR3line.
The VMEbusarbiter operates in priority mode.
The VMEbusarbiter operates in not fair mode.
The VMEbusarbiter operates in not hidden mode.
The FIFO buffers are clear.
All SGM entries are invalid.
The local bus timeout is 25 ys.
The VMEbustimeout is 125 ys.
All counter/timers are reset andclear.
The VAXELN system time contains the value of the KAV30 calendar/clock.
The default SCSI ID is seven.

A-2_

Initial KAV30 Configuration

Example Programs—interprocessor

Communication

This appendix lists a pair of VAX Ada programs that demonstrate
interprocessor communication between two KAV30s. The first program
implements a FIFO producer. The second program implements a FIFO
consumer.

B.1 FIFO Producer
-- FIFOPRODUCER.ADA
-- This program is one of a pair that demonstrates how the KAV30 FIFOs may be
-- used for inter-processor communication
with KAVDEF, CONDITIONHANDLING, SYSTEM, TEXTIO, ERRORHANDLING,
VAXELNSERVICES, ASTROUTINES, SIGNALLERTASK;
-- The ERRORHANDLING package ships with VAXELN ADA to utilize this package
-- from your programs you must enter this package into your ADA program

~- manager library

procedure FIFOPRODUCER is

STATUS : CONDITIONHANDLING.CONDVALUETYPE;
BUSPAGEPTR : SYSTEM.ADDRESS;
INPAGEPTR : SYSTEM.ADDRESS;
OUTGOINGSGMENTRY : INTEGER;
INCOMINGSGMENTRY : INTEGER;
MAPFUNCTIONS : INTEGER;
UNMAPFUNCTIONS : INTEGER;
KAVSERVICEERROR : exception;
VAXELNSERVICEERROR : exception;
BUFFER : INTEGER;
ASTPARAM : INTEGER;
SIGNALLER : SIGNALLERTASK.SIGNALLER;
package INTIO is new TEXTIO.INTEGERIO (INTEGER) ;
begin

Example Programs—lInterprocessor Communication

B-1

Example Programs—tInterprocessor Communication

-- create events for synchronization
VAXELNSERVICES.CREATEEVENT ( EVENT
=> ASTROUTINES.TRIGGEREDEVENT,
INITIALSTATE => VAXELNSERVICES.CLEARED,
STATUS
=> STATUS);
1f not CONDITIONHANDLING. SUCCESS (STATUS)
raise VAXELNSERVICEERROR;
end if;

then

VAXELNSERVICES.CREATEEVENT ( EVENT
=>
SIGNALLERTASK.SIGNALLEREVENT,
INITIALSTATE => VAXELNSERVICES .CLEARED,
STATUS
=> STATUS);
if not CONDITIONHANDLING.SUCCESS (STATUS) then
raise VAXELNSERVICEERROR;
end if;

-- start signaller task
SIGNALLER. START;
-- map CSR page (FIFOs) on other KAV30
MAPFUNCTIONS := KAVDEF.KAVMVME + KAVDEF.KAVMMODE0SWAP;

KAVDEF .KAV_OUTMAP( STATUS
SGMENTRY
PAGECOUNT
BUSADDRESS
VIRTUALADDRESS
AMCODE
MAPFUNCTIONS

=> STATUS,
=> OUTGOINGSGMENTRY,
=> 1,
=> 16#F00000#,
=> BUSPAGEPTR,
=> KAVDEF.KAV_KUSER24,
=> MAPFUNCTIONS );

if not CONDITIONHANDLING. SUCCESS (STATUS)
raise KAVSERVICEERROR;
end if;

then

-- make our CSR page (FIFOs) visible to another KAV30

MAPFUNCTIONS := KAVDEF.KAVMCSR + KAVDEF.KAVMMODE0SWAP;
INCOMINGSGMENTRY := 0;
KAVDEF .KAV_IN MAP( STATUS
a
SGMENTRY
PAGE COUNT
VIRTUALADDRESS
MAPFUNCTIONS

=> STATUS,
=> INCOMINGSGMENTRY,
=> 1,
=> INPAGEPTR,
=> MAPFUNCTIONS );

if not CONDITIONHANDLING. SUCCESS (STATUS)
raise KAV_SERVICEERROR;
end if;

then

-- set virtual address to point to FIFO 0

BUSPAGEPTR := SYSTEM."+"(BUSPAGEPTR, 16#4000#) ;

B-2 Example Programs—lInterprocessor Communication

Example Programs—Interprocessor Communication
declare VALUE : INTEGER;
for VALUE use at BUSPAGEPTR;
begin
-- set up fifo notification on empty to not-empty state
KAVDEF .KAVNOTIFYFIFO( STATUS
FIFO NUMBER

=> STATUS,
=> KAVDEF.KAVKFIFO0,

FIFOFUNCTIONS =>
KAVDEF .KAV M FIFO NOTEMPTY,

ASTADDR
=>
ASTROUTINES.ASTROUTINE’ ADDRESS) ;
if not CONDITIONHANDLING.SUCCESS (STATUS) then

raise KAVSERVICEERROR;

end if;

write a value to the remote KAV30 to start things off
VALUE := 1;
loop

-- wait for FIFO transition from empty to not empty
VAXELNSERVICES.WAITANY( VALUE] => SIGNALLERTASK.SIGNALLEREVENT,
STATUS => STATUS) ;
if not CONDITIONHANDLING.SUCCESS (STATUS)
raise VAXELNSERVICEERROR;
end if;

then

-- clear signaller event
VAXELNSERVICES.CLEAREVENT( EVENT =>
SIGNALLERTASK.SIGNALLEREVENT,
STATUS => STATUS) ;

if not CONDITIONHANDLING.SUCCESS (STATUS) then
raise VAXELNSERVICEERROR;

end if;

-- read 1 longword from FIFO 0

KAVDEF .KAVFIFOREAD( STATUS

=> STATUS,

FIFONUMBER => KAVDEF.KAVKFIFO0,
BUFFER
=> BUFFER’ ADDRESS,

COUNT

=> 1);

if not CONDITIONHANDLING. SUCCESS (STATUS)
raise KAV_SERVICEERROR;

then

end if;

-- re-establish FIFO notification on empty to not-empty transition

Example Programs—lInterprocessor Communication B-3

Example Programs—Interprocessor Communication

KAVDEF .KAVNOTIFYFIFO( STATUS
=> STATUS,
FIFONUMBER
=> KAVDEF.KAVKFIFO0,
FIFOFUNCTIONS =>
KAVDEF .KAV MFIFONOTEMPTY,
ASTADDR
=>
ASTROUTINES.ASTROUTINE’ ADDRESS) ;
if not CONDITIONHANDLING.SUCCESS (STATUS) then
raise KAV_SERVICEERROR;
end if;

-- display message on console

TEXTI0.PUT("Read ");
INTI0.PUT (BUFFER) ;

TEXTIO.PUT(" writing ");
INTI0.PUT(BUFFER+1) ;

TEXTIO.NEWLINE;

-- increment value read from FIFO 0 and write it to the other KAV30
VALUE := BUFFER + 1;
end loop;
end;
exception

when VAXELNSERVICEERROR =>
ERRORHANDLING.DISPLAYERRORMESSAGE ( STATUS) ;

when KAVSERVICEERROR =>
ERRORHANDLING.DISPLAYERRORMESSAGE( STATUS) ;
when others

raise;

end FIFOPRODUCER;

B—4 Example Programs—Interprocessor Communication

Example Programs—tInterprocessor Communication

B.2 FIFO Consumer
~- FIFOCONSUMER.ADA
-- This module forms one half of a pair of programs that demonstrate how the
-- KAV30 FIFOs can be used for inter-processor communication over VMEbus

with KAVDEF, CONDITIONHANDLING, SYSTEM, TEXTIO, ERRORHANDLING,
VAXELNSERVICES, ASTROUTINES, SIGNALLERTASK;
-- The ERRORHANDLING package ships with VAXELN ADA to utilize this package
-- from your programs you must enter the ERRORHANDLING package into your ADA
-- program manager library

procedure FIFOCONSUMER is
STATUS : CONDITIONHANDLING.CONDVALUETYPE;

BUSPAGEPTR : SYSTEM.ADDRESS;
INPAGEPTR : SYSTEM.ADDRESS;
OUTGOINGSGMENTRY

: INTEGER;

INCOMINGSGMENTRY : INTEGER;

MAPFUNCTIONS : INTEGER;
UNMAPFUNCTIONS : INTEGER;

KAVSERVICEERROR : exception;
VAXELNSERVICEERROR : exception;

BUFFER : INTEGER;
ASTPARAM : INTEGER;
SIGNALLER : SIGNALLERTASK.SIGNALLER;
package INTIO is new TEXTIO.INTEGERIO(INTEGER) ;
begin

-- create the event objects that will be used for synchronization
VAXELNSERVICES.CREATEEVENT ( EVENT
=> ASTROUTINES.TRIGGEREDEVENT,
INITIALSTATE => VAXELNSERVICES.CLEARED,
STATUS
=> STATUS) ;
if not CONDITIONHANDLING.SUCCESS (STATUS)
raise VAXELNSERVICEERROR;
end if;

then

VAXELNSERVICES.CREATEEVENT ( EVENT
=>
SIGNALLERTASK.SIGNALLEREVENT,
INITIALSTATE => VAXELNSERVICES .CLEARED,
STATUS
=> STATUS);
if not CONDITIONHANDLING. SUCCESS (STATUS)

raise VAXELNSERVICEERROR;

then

end if;

-- start signaller task

Example Programs—lInterprocessor Communication

B—5

Example Programs—interprocessor Communication

SIGNALLER. START;

-- map CSR page (FIFOs) on second KAV30
MAPFUNCTIONS

:= KAVDEF .KAVMVME + KAVDEF.KAVMMODE0SWAP;

KAVDEF .KAV_OUTMAP( STATUS
SGMENTRY

PAGECOUNT

BUSADDRESS
VIRTUALADDRESS
AMCODE
MAPFUNCTIONS

=> STATUS,
=> OUTGOING SGM ENTRY,
=> 1,

=> 16#E00000#,
=> BUSPAGE PTR,
=> KAVDEF.KAVKUSER24,
=> MAPFUNCTIONS );

if not CONDITIONHANDLING. SUCCESS (STATUS)
raise KAVSERVICEERROR;

then

end if;

-- map CSR page (FIFOs) on this module so that another KAV30 can access it

MAPFUNCTIONS := KAVDEF.KAVMCSR + KAVDEF.KAVMMODE0SWAP;
INCOMINGSGMENTRY := 0;
KAVDEF .KAV_INMAP( STATUS
=> STATUS,
SGMENTRY
=> INCOMINGSGMENTRY,
PAGECOUNT
= 1,
VIRTUALADDRESS => INPAGEPTR,
MAPFUNCTIONS
=> MAPFUNCTIONS );
if not CONDITIONHANDLING.SUCCESS (STATUS) then
raise KAVSERVICEERROR;
end if;
-- set virtual address to access FIFO 0 on the other KAV30

BUSPAGEPTR := SYSTEM."+"(BUSPAGEPTR, 16#4000#) ;
declare VALUE : INTEGER;
for VALUE use at BUSPAGEPTR;

begin
-- set up FIFO notification on empty to not empty transition
KAVDEF .KAVNOTIFYFIFO( STATUS
FIFO NUMBER

=> STATUS,
=> KAVDEF.KAVKFIFO0,

FIFOFUNCTIONS =>
KAVDEF .KAV MFIFONOTEMPTY,

ASTADDR
=>
ASTROUTINES.ASTROUTINE’ ADDRESS) ;
if not CONDITIONHANDLING.SUCCESS (STATUS) then
raise KAVSERVICEERROR;
end if;
loop
-- wait for signaller to signal us

B-6 Example Programs—lInterprocessor Communication

Example Programs—lInterprocessor Communication
VAXELNSERVICES.WAITANY( VALUE1 => SIGNALLERTASK.SIGNALLEREVENT,
STATUS => STATUS) ;
if not CONDITIONHANDLING.SUCCESS (STATUS)
raise VAXELNSERVICEERROR;

then

end if;
-- clear

signallerevent
VAXELNSERVICES.CLEAREVENT( EVENT =>
SIGNALLER TASK.SIGNALLEREVENT,
STATUS =>STATUS);
if not CONDITIONHANDLING.SUCCESS (STATUS) then
raise VAXELNSERVICEERROR;
end if;

-- read 1 longword from FIFO

KAVDEF .KAVFIFOREAD( STATUS
=> STATUS,
FIFONUMBER => KAVDEF.KAVKFIFO0,
BUFFER
=> BUFFER’ ADDRESS,
COUNT
=> 1);
if not CONDITIONHANDLING. SUCCESS (STATUS)
raise KAVSERVICEERROR;

then

end if;

-- re-establish fifo state transition notification

KAVDEF .KAVNOTIFYFIFO( STATUS
=> STATUS,
FIFONUMBER
=> KAVDEF.KAVKFIFO0,
FIFOFUNCTIONS =>
KAVDEF .KAVMFIFONOTEMPTY,
ASTADDR
=>
ASTROUTINES .ASTROUTINE’ ADDRESS) ;
if not CONDITIONHANDLING. SUCCESS (STATUS)

raise KAVSERVICEERROR;

then

end if;

-- write message to console

TEXTIO.PUT("Read ");
INTI0.PUT (BUFFER) ;
TEXTI0.PUT(" writing ");
INTI0.PUT (BUFFER) ;
TEXTIO.NEWLINE;
-- write value read from FIFO back to the other KAV30
VALUE := BUFFER;

end loop;
end;

exception

Example Programs—lInterprocessor Communication

B-7

Example Programs—tinterprocessor Communication
when VAXELNSERVICEERROR =>
ERRORHANDLING.DISPLAYERRORMESSAGE ( STATUS) ;

when KAVSERVICEERROR =>
ERRORHANDLING.DISPLAYERRORMESSAGE ( STATUS) ;
when others
raise;

end FIFOCONSUMER;
-- ASTROUTINES .ADA
-- AST routine for use with FIFOPRODUCER / FIFOCONSUMER example programs
with VAXELNSERVICES;
package ASTROUTINES is
TRIGGEREDEVENT : VAXELNSERVICES .EVENTTYPE;

procedure ASTROUTINE;

pragma EXPORTPROCEDURE (ASTROUTINE) ;
end ASTROUTINES;
package body ASTROUTINES is

procedure ASTROUTINE is
begin
VAXELNSERVICES.SIGNALEVENT( EVENT => TRIGGEREDEVENT) ;

end ASTROUTINE;
end ASTROUTINES;
-- SIGNALLERTASK.ADA
-- This package contains the signaller process used by the FIFOPRODUCER /
-- FIFOCONSUMER example
with SYSTEM, VAXELNSERVICES, ASTROUTINES;
package SIGNALLERTASK is
SIGNALLEREVENT : VAXELNSERVICES.EVENTTYPE;
task type SIGNALLER is
entry START;
end SIGNALLER;

end SIGNALLERTASK;
package body SIGNALLERTASK is

B-8 Example Programs—lInterprocessor Communication

Example Programs—linterprocessor Communication

task body SIGNALLER is
STATUS : CONDITIONHANDLING.CONDVALUETYPE;
begin
accept START;
loop
-- wait for event to be signalled by the ast routine
VAXELNSERVICES.WAITANY( STATUS => STATUS,
VALUE] => ASTROUTINES.TRIGGEREDEVENT) ;
-- clear the event

VAXELNSERVICES.CLEAREVENT( STATUS => STATUS,
EVENT => ASTROUTINES.TRIGGEREDEVENT) ;
-- signal signaller event
VAXELNSERVICES.SIGNALEVENT ( STATUS => STATUS,
EVENT => SIGNALLEREVENT) ;
end loop;
end SIGNALLER;
end SIGNALLERTASK;

CHARACTERISTIC /SHAREDSTATUS /NOFILE /NETDEVICE=EZA /NOSERVER /OBJECTS=512 /EMULATOR=BOTH /DEBUG=BOTH /P0VIRTUALSIZE=4096 /P1VIRTUALSIZE=512 /10_REGION=2048 /TARGET=24
PROGRAM FIFOCONSUMER /WARMDEBUG
DEVICE EZA /VECTOR=%X130 /NETDEF
CHARACTERISTIC /REMOTECLI /REMOTETERM /SHAREDSTATUS /NOFILE /NETDEVICE=EZA /NOSERVER /OBJECTS=512 /EMULATOR=BOTH /DEBUG=BOTH /P0VIRTUALSIZE=4096 /P1VIRTUALSIZE=512 /I0REGION=2048 /TARGET=24
PROGRAM FIFOPRODUCER /WARMDEBUG
DEVICE EZA /VECTOR=%X130 /NETDEF

WN In MN WH OH HO OH WH

$!
$! INTERPROCESSORBUILD.COM
ACS SET LIBRARY USER: [USER.ADALIB]
ADA ERRORHANDLING, ASTROUTINE, SIGNALLER_TASK
ADA/DEBUG FIFOPRODUCER
ADA/DEBUG FIFOCONSUMER
ACS LINK/DEBUG/SYSTEM=VAXELN FIFOPRODUCER ELN$:KAVSRTLOBJLIB/LIB
ACS LINK/DEBUG/SYSTEM=VAXELN FIFOCONSUMER ELN$:KAVSRTLOBJLIB/LIB
EBUILD/NOEDIT FIFOCONSUMER

EBUILD/NOEDIT FIFOPRODUCER

Example Programs—lInterprocessor Communication

B-9

Example Programs—MVME335 Device
Driver
This appendix lists a pair of VAX C programs that implement a device driver
for the MVME335serial line module. The programs use ASTs to allow the ISR
and the driver to communicate with each other. Thefirst program is the device
driver main body. The second program is the driver ISR.
Both programsare part of the KAV30 software kit. See the KAV30 Software
Installation and System Testing Information for more information.

C.1 Device Driver
#module mvme_driverast

THE INFORMATION IN THIS SOFTWARE IS SUBJECT TO CHANGE WITHOUT NOTICE
AND SHOULD NOT BE CONSTRUED AS A COMMITMENT BY DIGITAL EQUIPMENT
CORPORATION.

HF
He He HH OF
He
FF

H
HH
HF
HF
HK
HF
~~

t+ ee

[RRKRKRK KKK KK KKK RK KK KKK KKK KKK KKK KR KKK KKK KKK KK RR KR KKK KKK KR KK RK KK KKK KKK KKK KKK KKK

Example Programs—MVME335 Device Driver C-1

DIGITAL ASSUMES NO RESPONSIBILITY FOR THE USE OR RELIABILITY
SOFTWARE ON EQUIPMENT WHICH IS NOT SUPPLIED BY DIGITAL.

ITS

*
*
x

Example Programs—MVME335 Device Driver

KK KKK KKK KKK KKK KR KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KK KKK KKK KKK KKK KKK KKKK ER /

FACILITY:

Device driver example for KAV30 using mvme335 serial line module

DESCRIPTION:

driver body including initialisation and isr

this version uses 'KAVSQUEAST’ instead of
‘kerSsignaldevice’ t0 communicate from ISR
to driver body (this program).

#include $vaxelnc
#include <eln$:kavdef.h>
#include "mvmedef.h"

/* definition of module reg. */

#include stdio
#include Sget_messagetext
#include $kerneldef
#include $kernelmsg
#include descrip
/*
*

Definitions and global variables for the driver

#define

mvmebase

0x03600

#define MVMEIRQLEV

0x08

#define MVMEPHYSADDR 0x00

/* mvme modul base address */
/* irq level on board = bit3 */

Define the COPYBYTES macro This macro copies the specified number of
bytes from one string to another without
any character interpretation.

#define COPYBYTES (src, dst, cnt)

{

char *s = (src);
char *d = (dst);
int
CC;
for (c=(cnt) ;c;c--)

}
struct

*dt+t+ = *st+t;

mvme$dulregion *mvmeSdulregptr;

C-2 Example Programs—MVME335 Device Driver

OO OO TO OO OO

*
*
*

Example Programs—MVME335 Device Driver
struct

mvmeSpacket

{

int

function;

int

error;

int
char

length;
buffer[];

/x
*

‘outside’ definitions for global use

*/
DEVICE

mvmeSdevice;

PORT

mvme$Sdriverport;

NAME

mvmeSname;

struct
int

mvmeSpacket *mvmeSrequest;
requestsize;

MESSAGE mvmeSmessage;

/x
*

forward references for functions

void

mvmestx_ast

();

void

mvme$rxast

();

void

mvmeSerrortext

(int

BOOLEAN mvme$condhandler

status) ;

();

[RR KKK KKK RK KKK KKK KKK KKK KK KKK KKK KKK KKK KKK KKK KR KKK KAR KKK KKK KK KKK KKK KKK KKK KKK KKK
x

Name:

MVME_DRIVER ()

Abstract:

This is the driver main body

Inputs:

none

Outputs:

none

Comment:

has to run run in kernel mode

KKK KKK KKK KKK KKK RK KKK KK RK KKK KKK KK KR KK KKK KKK KKK KR KK RR KKK KKK KKK KKK KKK KKKKKKKKKKK /

mvmedriver
{

extern

int

()
void
int
int

mvmeSduartlisr
mvme$setupmodule
status;

();
();

mvmeSstatus;

mvmeSipl;

mvmeSvector;

Example Programs—MVME335 Device Driver C-3

Example Programs—MVME335 Device Driver
BOOLEAN done;

VARYINGSTRING(32)
static

static

mvmeSdevice_name;

$DESCRIPTOR(mvmeSportname, "MVMESDRIVERPORT") ;

$DESCRIPTOR(devicename,"");

/*
*/

get the device name from the program argument list

eln$Sprogramargument (&mvmeSdevicename, 1);
devicename.dsc$wlength = mvmeSdevicename.count;
devicename.dsc$apointer = mvmeSdevicename.data;

/*
*/

Create the device object and connect to ISR and communication region
ker$Screatedevice (&status,

/* status */

&devicename,
1,
mvmeSduart1isr,
sizeof(struct mvme$dulregion),

/* device name */
/* relative vector */
/* interrupt service routine */
/* size of communications region */

&mvmeSvector,

/* pointer to vector */

MAXCHANNELS,

/* number of devices to create */

&émvme$dulregptr,
NULL,
NULL,
&mvmeSipl,
&émvmeSdevice,

/* address of communications region */
/* register pointer */
/* adapter pointer */

/* interrupt priority */
/* pointer to device variable */

NULL) ;
if (status != KER$SUCCESS)
mvmeSerrortext (status);

/* power fail isr (not needed) */

/* return ker$createdevice status */

/*
*/

establish condition handler

VAXCSESTABLISH

(mvme$Scondhandler) ;

status =
mvmeSsetupmodule();
if (! (status & 1))

/* setup MVME335 module */

mvmeSerrortext (status);

ker$jobport (&status,

émvmeSdriverport);

if (! (status & 1))
mvmeSerrortext (status);

C-4 Example Programs—MVME335 Device Driver

Example Programs—MVME335 Device Driver

kerScreatename (&status,
&mvmeSname,
émvmeSportname,

émvmeSdriverport,

if (!

/x
*

NAMESLOCAL) ;

(status & 1))

mvmeSerrortext (status);
Set up the AST queue’s for Send and Receive

KAVSDEFAST (&status,
if (!

émvme$dulregptr->txdev);

(status & 1))

mvmeSerrortext (status);

KAVSDEFAST (&status,
if (!

&émvmeSdulregptr->rxdev);

(status & 1))

mvmeSerrortext (status) ;

Initialization complete - inform the kernel.
ker$Sinitializationdone (NULL) ;

[BRAK KERR KKK KR EK KKK KKK KKK KKK KK KKK KKK KKK KR KKK KKK KKK KK KKK KKK KKK KKK KK KKK KKK KKK KKK

Driver main routine - we stay here forever the main tasks are:
- wait for any caller and connect on request
- wait for a request package, perform the request
- disconnect on request
This version of the driver uses AST’s for communication

between ISR and driver instead of SIGNALDEVICE,
the ISR to be used is MVMEDRIVERISRTIMEAST.C

EHH

KARR KEK KKK KKK KR KKK KKK KKK KR KKK KEK KEK KKK KKK KR KKK KKK KR KKK KKK KKK KKK KKK KK KKK KKK KKK KE /

Example Programs—MVME335 Device Driver C-—5

Example Programs—MVME335 Device Driver

/*
x

for (77)
{
Connect on request

kerSacceptcircuit (&status,
&émvme$driverport,
NULL,
TRUE,

NULL,
if (!

(status & 1))

NULL) ;

mvmeSerrortext (status);
for (done = FALSE;

/*
*

{

!done;)

Wait for request package and receive it

ker$waitany (&status,
NULL,
NULL,

if (!

&émvmeSdriverport);

(status & 1))

mvmeSerrortext (status);

kerSreceive (&status,
&émvmeSmessage,

émvmesSrequest,
&requestsize,

émvme$driverport,

NULL,
if (!

/*
*

NULL) ;

(status € 1))

mvmeserrortext (status);

Case on requested operation.

switch (mvmeSrequest->function)
case RDBLOCKFUNC:

/*
*

/* perform the READBLOCKFUNCTION */
set up AST in pending queue (rxdevice)

C-6 Example Programs—MVME335 Device Driver

Example Programs—MVME335 Device Driver
KAVSSETAST (&status,

mvme$rxast,
NULL,

NULL,
if (!

mvme$dulregptr->rxdev);

(status & 1))

mvmeSerrortext (status) ;

/*
*/

Initialize com. region at deviceipl (this disables irq’s)
ELNSDISABLEINTERRUPT (mvme$ip1) ;

mvme$dulregptr->read_count
mvme$dul reg ptr->rxbufptr

mvme$request->length;

mvme$dulregptr->error

mvmeSdulregptr->read_inprogr

= FALSE;

= TRUE;

mvme$dul reg ptr->dul irqmask.rxa_ready = ENAB;

/*
*/

ELNSENABLEINTERRUPT();

Enable receiver irg - since rx is enabled, we will see it imediately!
writeregister (mvme$dulregptr->dul_irqmask,

mvme$dulregptr->adul_w_imr);

/*
x

Error checking and informing the caller about completion

is done in the AST routine (mvme$tx_ast) - so nothing to do here..
break;
case WRBLOCKFUNC:

/* perform the WRITEBLOCKFUNCTION */
COPYBYTES (mvmeSrequest->buffer,

mvmeSdulregptr->writebuffer,
mvmeSrequest->length) ;

mvme$dulregptr->writecount= mvme$request->length;

mvme$dulregptr->txbufptr

= 0;

set up AST in pending queue (txdevice)

Example Programs—MVME335 Device Driver C-—7

Example Programs—MVME335 Device Driver
KAVSSETAST (&status,

mvme$txast,
NULL,
NULL,

mvme$dulregptr->txdev);
if (! (status & 1))
mvmeSerrortext (status);
/x
*

Initialize com. region at deviceipl (this disables irq’s)
ELNSDISABLEINTERRUPT (mvmeSip1) ;

mvmeSdulregptr->writeinprogr

= TRUE;

mvme$dulregptr->dul_irqmask.txaready = ENAB;
mvme$dul_regptr->dul_irqmask.rxaready = ENAB;
/*
*
x

ELNSENABLEINTERRUPT () ;

Enable transmitter irg - since tx is enabled, we will see it imediately!
Enable receiver in order to get control char’s

writeregister (mvme$dulregptr->dul_irqmask,
mvme$dulregptr->adulwimr);
/*
*

Error checking and informing the caller about completion

is done in the AST routine (mvmeStxast) - so nothing to do here..
break;

case DONEFUNC:
mvmeSrequest->error = 0;
ker$send( &status,
mvmeSmessage,
requestsize,
émvmeSdriverport,
if (!
done

NULL,
FALSE) ;
(status & 1))

mvmeSerrortext (status) ;
= TRUE;

} /* end of switch block */
} /* end of forloop (done = FALSE) */
/*
x

Wait for disconnect message and disconnect

C-8 Example Programs—MVME335 Device Driver

Example Programs—MVME335 Device Driver
kerSwait_any(&status,
NULL,
NULL,

if (!

&émvmeSdriverport);

(status & 1))

mvmeSerrortext (status) ;

ker$disconnectcircuit (&status,
if (!

(status & 1))

&émvmeSdriverport);

mvmeSerrortext (status) ;

} /* and of for’ever’ loop */

} /* end of driver main body */
[RRR KER KKK RRR ERK KKK KKK KKK KKK KK KK KR KK KKK KKK KK EK KKK KK KKK KEK KKK KKK KER KK KK KKK
x

Name:

Abstract:

x
*
k

MVMESSETUPMODULE ()

This function will setup the initial register

values needed by the module (on VMEbus). First
the VME register addresses are mapped to S0.

Inputs:

None

Outputs:

Status

Comment:

On any exception the condition handler

*
*

‘mvmeScondhandler’ is called

KKK KKK KK KKK KKK KKK KKK KKK KKK KKK KK KK KKK KKK KKK KK KKK KKK KK KKK KKK KKK KK KKK KKKEKKKEKKKER /

int mvmeSsetupmodule ()
{

int

status;

struct
struct
struct
struct
struct
struct
struct
struct
struct
struct

mvmestatus
mvmemodeone
mvme_command
mvme_auxcontrol
mvmeclock
mvme_irqmask
mvme_irqstatus
mvmeirqvector
mvme_txbuf
mvme_rxbuf

int setupfunction, buffer;

int entry, pagecnt;

int physical addr, vir addr;

*adul_rsra;
*adulmria;
*adulwcra;
*a_dulw_acr;
xadulw_csra;
*adulwimr;
*adulrisr;
*adulirv;
*adulwtxa;
xadulrrxa;
/* parameters for 5VMESETUP */
/* parameters for SOUTMAP */

int amcode, “mapfunctions;

Example Progranms—MVME335 Device Driver C-9

Example Programs—MVME335 Device Driver
/*
x

Enable VMEirq level 3

buffer
setupfunction

KAVSVMESETUP
if

= 0x08;
= KAVSKALLOWVMEIRQ;

/* VME irg 3 !! */

(&status,

setupfunction,
&buffer) ;
(!
(status & 1))
mvmeSerrortext (status) ;

/*
*

map mvme335 register space (on vme-bus) to SQ space
pagecnt

physicaladdr
am code

mapfunctions

= 1;

= 0x00000000;
= KAVSKUSER16;

/* phys address at page bound.*/

/* ‘short user mode 0x29’ */

= KAVSMVME+KAVSMMODE0SWAP;

KAVSOUTMAP (&status,

sentry,
pagecnt,

physicaladdr,

&viraddr,
amcode,

mapfunctions) ;
(!
(status & 1))
mvmeSerrortext (status) ;

/*
* set up mvme register address (virtual) using <viraddr> as base

adulrsra =
adulwimr =
adulwcra =
adulmrla =
adulwacr =
adulwcsra=
adulwtxa =
adulrrxa =
adulrisr =
adulirv
=

viraddr + mvmebase + dulrsra; /* status register a
*/
viraddr + mvmebase + dulwimr; /* irg mask register a&b*/
viraddr + mvmebase + dulwcra; /* command register a_
*/
viraddr + mvmebase + dulmrla; /* mode register a one */
viraddr + mvmebase + dulwacr; /* aux. command reg. a */
viraddr + mvmebase + dulwcsra; /* clock select reg. a */
viraddr + mvmebase + dulwtxa; /* transmitter buffer a */
viraddr + mvmebase + dulrrxba; /* receiver buffer a
*/
viraddr + mvmebase + dulrisr; /* irg status duartl
x/
/* irg vector duartl
viraddr + mvmebase + dulirv;
*/

/*
*

copy register address to com.region

C-10

Example Programs—MVME335 Device Driver

Example Programs—MVME335 Device Driver
mvme$Sdulregptr->adulrsra
mvme$dulregptr->a_dul_wimr
mvme$dulregptr->a_ dul w cra
mvme$dulregptr->adulmrla
mvme$dulregptr->adulw acr
mvme$dulregptr->adulwcsra
mvme$dulregptr->a_dulw_txa
mvme$Sdulregptr->a_dulrrxa

mvmeSdulregptr->adul_risr
mvme$Sdulregptr->a_dulirv

a dul rsra;
adulw_imr;
adulwcra;
a_
dul_mria;
adul
_Wacr;
adul|
_W_csra;
adul
_W_txa;
adulr_YXa;
adulr isr;

adulirv;

* initialize registers on mvme335 duartl channel a only with the following
* parameters: 9.6 kBaud, 8bits, no parity
all default parameters can be found in mvmedef.h

/* initialize duartl irq mask register [dul_wimr]: no irg */
writeregister
(dul_irgmask, adulwimr);
/* perform bit set on channel a command register [dulwcra] reset mrla ptr */

writeregister

(dulacommand, adulwcra);

/* write channel a mode register one [dulmrla] ptr -> mode register two */

writeregister

(dula_modeone, adulmrla);

/* write channel a mode register two [dulmrla] */
writeregister
(dulamodetwo, adulmrila);
/* write channel a command register [dul_w_cra]: reset rx, flush FIFO

dulacommand.misc
writeregister

= RESETRX;
(dulacommand, adulwcra);

/* write channel a command register [dulwcra]: reset tx */
dulacommand.misc
= RESETTX;
writeregister
(dula_command, adulwcra);
/* write channel a command register [dulw_cra]: reset error status */
dulacommand.misc
= RESETERR;
writeregister
(dula_command, adulwcra);

/* write channel a auxiliary control register [dul_wacr] */
writeregister

(dul_acr, a_dulwacr);

/* write channel a clock register [dulwcsra]: 9600 baud both */
writeregister
(dula_clock, a_dulw_csra);
/* initialize duartl vector register [dul_irv]
dulirqvec.irgvector= 0x02;

writeregister

(default = 0x00) */

(dul_irqvec, a_dulirv);

/* enable transmitter and receiver [dula_command] * /

mvme$dulregptr->dula_comm.enatx
= ENAB;
mvme$dulregptr->dula_comm.ena rx
= ENAB;
writeregister
(mvme$dul_regptr->dula_comm, adulwcra);

Example Programs—MVME335 Device Driver C-—11

Example Programs—MVME335 Device Driver

return

(status);

/* end of SETUPMODULE */

}

[RRR KKK KKK KR KKK KKK KKK KK KKK KKK KKK KKK KKK KK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK
*

Name:

RXAST

Abstract:

ast routine for rx events

Inputs:

None

Outputs:

None

Comment :

This routine is called every time the ISR delivers

an AST for the rxdevice.

KKK KKK KKK KK KKK KK KKK KKK KKK KKK KKK KKK KR KKK KKK KKK KKK KKK KKK KKK RK KK KKK KKK KKKKKKKKKE /

void

{

mvme$rxast
int

()

status;

/*
*

check for error and correct length

if (mvme$dulregptr->error)
{
mvmeSrequest->error = -1;
mvme$Srequest->length = mvme$dulregptr->rxbufptr;
else

}

mvmeSrequest->error = 0;

/*
x

copy buffer
COPYBYTES (mvme$dul_regptr->readbuffer,
mvme$request->buffer,

mvmeSrequest->length) ;

/*
*

send message to caller and return

C-12 Example Programs—MVME335 Device Driver

Example Programs—MVME335 Device Driver
kerSsend( &status,

mvmeSmessage,

requestsize,
&émvmeSdriverport,

NULL,

FALSE) ;

if (! (status & 1))

mvmeSerrortext (status) ;

return;
[RRR KKK KKK KR KKK KKK RK KEK KKK KK KK KKK KKK RK RK KK KK KKK RK KKK KKK KK KKK KKK KKK KKK KKK KK
x

Name:

TX_AST

Abstract:

ast routine for tx events

Inputs:

None

Outputs:

None

Comment:

this routine is called every time the ISR delivers

an AST for the txdevice

KKK KKK KK IKK KK KKK KKK KK IK KKK KK KKK KR KKK KK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KK /

void

mvmeStxast

()

{
/*
x

reset error and send message to caller

mvmeSrequest->error = 0;
kerSsend( NULL,
mvmeSmessage,
requestsize,

amvme$driverport,
NULL,

FALSE) ;

Exampte Programs—MVME335 Device Driver C—13

Example Programs—MVME335 Device Driver

return;
[RR RRR KKK KKK KKK KKK KR KKK KKK KKK KK KKK KKK KK KK RK KKK KKK KKK KKK KKK KKK KK KKK KKK KKKKKK KKK
x

Name:

MVMESCONDHANDLER (signalptr,mechanismptr)

Abstract:

condition handler invoked by any exception

Inputs:

None

Outputs:

status = l

Comment :

handler will not terminate the programm,

the condition is not really handled here...!

KKK KKK KKK KKK KK KKK KKK KKK KK KKK KKK KK KK RK KK KKK KKK KK KKK KKK KKK KKK KKK KKK KKK KKKKKKKK /

BOOLEAN mvme$Scondhandler (signalptr,mechanismptr)

struct

chf$signalarray

{

int chf$l_sigargs;
int chf$l_signame;
int chf$l_sigargl;

struct
struct

{

chf$signalarray *signalptr;
chf$mech_array *mechanism_ptr;

void
static

mvmeSerrortext (int status);
int status, address;

printf ("Condition handler:");
status = signalptr->chf$l_signame;
mvmeSerrortext (status);
address = signalptr->chf$l_sigargl;
printf ("at VME address %x \n", address);
exit (1);

C-14 Example Programs—MVME335 Device Driver

/* show error text

Example Programs—MVME335 Device Driver

[RR RK KR KKK KKK KKK RR KKK KKK KKK RK KKK KKK KKK KKK KKK KKK KKK KK KAR KK KKK KKK KKK KKK KKK KKK KKK
x

Name:

MVMESERROR_TEXT()

x
*

Abstract:

Routine converts kernel error number’s to text
and print’s it

Inputs:

status

Outputs:

none

Comment:

none

KHER KKK KKK KKK KKK KK KKK KEK KR KKK KKK KKK KKK KKK KKK KKK KR KKK KK KKK KKK KKK KKK KKK KKK KKEKKRK /

void

{

mvmeSerrortext (int status)

/* send error message to console*/

text_flags;

/* parameters for Sget_message */

int

char

text buffer[255];

VARYINGSTRING(255) resultstring;
textflags

= STATUSSALL;

eln$Sget_statustext ( status,
textflags,
&éresultstring);
VARYINGTOCSTRING ( result_string,textbuffer);

printf(

"%ss\n", textbuffer) ;

printf ("KAVSXXX Error : $d \n", status);
return;

Example Programs—MVME335 Device Driver C—15

Example Programs—MVME335 Device Driver

C.2 Interrupt Service Routine
#module mvme_israst

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 WHICH IS NOT SUPPLIED BY DIGITAL.

ITS

FF Hee

HOH

HHH

FH HH HF FF HF H

[RR RKKKKKK KKK KKK KKK KK KKK KKK KKK KK KKK KKK KKK KKK KKK KK RK KKK KKK KKK RK KKK KKK KKK RK KKK

KK KKK KKK KK KKK KR KKK RK KK KKK KKK KKK KKK KR KK KKK KK KK KKK KKK KKK KKK KKK KKK KKK KKK KEKKKK /

#include $vaxelnc
#include <eln$:kavdef.h>
#include "mvmedef.h"

/* definition of module reg. */

#include stdio
#include Skerneldef
[RRKKRKKK KKK KKK KK KERR KR KKK KKK RK KKK KKK KKK KKK KR KKK KR KKK KKK KKK KKK RK KEK KKK KKK KKK KKK KKK
x

Name:

MVMESDUART1_ISR()

Abstract:

This is the ISR for duartl

Inputs:

*registerptr

Outputs:

none

Comment:

this routine is invoked by an irg on the VMEbus,
it executes in kernel mode.

x
*

= ptr to register (not used)

*mvme$dulregptr= ptr to comm. region

Every acces to the VMEbus has to use the

KAVSBUSREAD or KAVSBUSWRITE system service.

*
k

KA KKK KKK KKK KKK KKK KKK KK KKK KKK KKK KKK KR KR KK KKK RK RK KK KK RR KR KKK KKK KK KKK KK KKK KKKKE /

void
struct

struct

mvmeSduartlisr (registerptr, mvmesdulptr)
registerdef

*registerptr;

mvmeSdulregion *mvme$dulptr;

/* has to be there! */

C-16 Example Programs—MVME335 Device Driver

Example Programs—MVME335 Device Driver
{
int

status, datatype, count, charnum, i;

char

controlbuf[3];

count

= 1;

= 0;

charnum

= 0;

datatype

= KAVSKBYTE;

/*
x

Determine source of irg - get irqreg and check bit’s
KAVSBUSREAD (&status,
datatype,

mvme$dulptr->a_dulrisr,
émvme$dulptr->dul_irqstat,
count) ;

[RRR KK KKK KKK KEK KKK KKK KK KKK KKK KKK KKK KKK KKK KER KR KKK KKK KKK KKK KR KK KKKKE KK

If irq is for tx channela - process it

KK KKK KKK KKK KR KKK KKK KKK KKK KKK KKK KKK RR KR KR KK KKK KKK RK KKK KKK KKK KKK /

if (mvme$dulptr->dulirqstat.txa_ready)

/x
*

{

If the driver is waiting for output, output

characters to the mvme-module until done.
if (mvme$dul_ptr->writeinprogr)

if (mvmeSdulptr->writecount > mvmeS$dul_ptr->txbufptr)
KAVSBUSWRITE (&status,

datatype,

mvme$dul_ptr->a_dulwtxa,
émvme$dulptr->writebuffer

[mvme$dulptr->txbuf_ptrtt],

count) ;

/x
x

else
All done, reset tx & rx irqmask bit

mvmeSdul_ptr->writeinprogr
= FALSE;
mvmeSdulptr->dulirqmask.rxaready = 0;
mvmeSdulptr->dulirqmask.txaready = 0;

Example Programs—MVME335 Device Driver C-—17

Example Programs—MVME335 Device Driver

KAVSBUSWRITE (&status,

datatype,

mvmeSdulptr->a_dulwimr,
émvme$dulptr->dul_irqmask,
count);

/*
*

Copy error status to comm.reg and signal device

mvme$dulptr->status

= status;

KAVSQUEAST (&status,
mvme$dul_ptr->txdev);

}

[RR KKK KKK KKK KKK KK KKK KKK KKK KK KKK KKK KK KKK KKK KKK RK KKK KKK KKK KKK KKK KK KKK

If irq is for rx channela - process it

KKK KK KKK KKK KKK KKK KKK KKK KK KK KKK KKK KKK KKK KR KKK KK KKK KKK KK KKK KKK KKK KEKE /

if (mvme$dulptr->dul_irgstat.rxa_ready)
/*
*

{
First check status reg. for any error (not implemented)
KAVSBUSREAD (&status,
datatype,

mvme$dul_ptr->a_dulrsra,
&mvme$dulptr->dulastat,
count) ;

/*
*
*

If the driver is waiting for input, read
characters from the mvme-module until done.

C-18 Example Programs—MVME335 Device Driver

Example Programs—MVME335 Device Driver
if (mvme$dul_ptr->read_inprogr)
{

if (mvme$dulptr->readcount > mvme$dulptr->rxbuf_ptr)

{

KAVSBUSREAD (&status,
datatype,

mvmeSdulptr->adulrrxa,
&émvme$dulptr->readbuffer
[mvme$dulptr->rxbufptr],
count) ;

check for carriage control and stop if ...
if

/*
*/

(mvme$dulptr->read_buffer[mvme$dulptr->rxbufptr] == CR)

{

CR received -> all done, reset rx irqmask bit

mvme$dulptr->error

= TRUE;

mvme$dulptr->read_inprogr
= FALSE;
mvme$dulptr->dul_irqmask.rxaready = 0;
KAVSBUSWRITE (&status,
data_type,

mvmeSdulptr->a_dulwimr,
émvmeSdulptr->dulirqmask,
count) ;

/*
*/

Copy error status to comm.reg and signal device

mvme$dulptr->status

= status;

KAVSQUEAST (&status,

}

mvme$dul_ptr->rxdev);

mvmeSdulptr->rxbufptrtt+;
}

/*
*/

else

Buffer ful, all done, reset rx irgmask bit
mvmeSdulptr->read_inprogr

mvme$dulptr->dulirgqmask.rxaready

FALSE;

e
7

KAVSBUSWRITE (&status,
datatype,

mvmeSdulptr->a_dulwimr,

émvme$dulptr->dul_irqmask,
/*

count) ;

Copy error status to comm.reg and signal device

Example Programs—MVME335 Device Driver C-—19

Example Programs—MVME335 Device Driver
mvme$dulptr->status

= status;

KAVSQUEAST (&status,

}

mvme$dulptr->rx_dev);

}

No read_inprogr, is it a control char for writeinprogr ?

else

{

if (mvmeSdulptr->writeinprogr)

while

{

(mvme$dul_ptr->dula_stat.rxready)

KAVSBUSREAD (&status,

datatype,

mvme$dulptr->adulrrxa,

écontrolbuf[charnum],
count) ;

/*
*/

check status again if there is more than one char
KAVSBUSREAD (&status,
datatype,

myvme$dul_ptr->adul_rsra,

charnum+t;

&mvme$dulptr->dula_stat,
count) ;

}

while

/*
*/

{

(1 < charnum)

If XOFF, disable transmitter
if

(controlbuf[i] == XOFF)

{
mvme$dulptr->dula_comm.enatx
KAVSBUSWRITE (&status,

datatype,

= DISAB;

mvmeSdul_ptr->a_dulwcra,
émvmeSdulptr->dula_comm,
/*
*/

}

count) ;

If XON, enable transmitter

C-20 Example Programs—MVME335 Device Driver

Example Programs—MVME335 Device Driver
else

(controlbuf[1] == XON)

{

mvme$dulptr->dula_comm.enatx
KAVSBUSWRITE (&status,
data type,

= ENAB;

mvme$dul_ptr->a_dulwcra,

émvme$dul_ptr->dula_comm,
|

1tt;

}

/*
)
*k

count);

}

If it’s an unexepected char, disregard it

}
/*
‘)

If irg is not expected here, disregard

Example Programs—MVME335 Device Driver C—21

Example Programs—VDAD Device Driver
This appendix lists the following files:
A VAX C program that implements a device driver for the VDAD (I/O)
module
A definitions file for the VDAD I/O module device driver
A VAX C program that tests the VDAD I/O module device driver
A build file for the VDAD I/O module device driver and test program
A VAXELN System Builder data file for the VDAD I/O module device
driver test program
All the files are part of the KAV30 software kit. See the KAV30 Software

Installation and System Testing Information for more information.

D.1 Device Driver

He
HH
+

FACILITY:
VAXELN Run Time System
ABSTRACT:
This module contains an ELN Driver for a VMEbus device.

+
+
+

#module VDADdriver

VERSION:
V1.04

13-Mar-1991

Field Test Release.

Example Programs—VDAD Device Driver D-1

Example Programs—VDADDevice Driver

*
*
*
*
x

*
x
*
*
*
x

*
*

NOTES:
This is an example of a driver for a VMEbus device - the PEP VDAD
module. This device offers ADC, DAC, Timers and Digital I/0, although
only Analaog-to-Digital conversion is provided here.
The program illustrates the most important Driver functions, namely:
ELN Driver interface,
interrupt handling,
VMEbus device access,
user calling interface

It does NOT provide access to the full functionality of this module

- it merely demonstrates the methods required in order to access the

x
*

board under ELN driver philosophy.
*x*x It provides basic ADC sampling only

Similarly, error handling and parameter checking are incomplete.

***

*/
#include stdio
#include $get_messagetext
#include types
#include chfdef
#include in
#include descrip
#include $Smutex
#include Skernelmsg
#include Svaxelnc
#include <eln$:kavdef .h>
#include "vdaddriver.h"
/*

/* descriptor definitions */
/* mutex */
/* kernel messages */
/* KAV300
"
/* VDAD definitions

KKKEKKKKKKEKRKKKKEKKEKKKKKR KK KEKE KK KKKEKRKKKKKKKKKKKKE

*xx

Global variables for Driver routines

***

KRKKKKKKKKKKEKKKRKKRKKKRK KKK KEKE KRKKRKKRKRKKKKKKKKKKKR

int
unsigned long

vdadSstatus ;
vdadSkav setup ;

unsigned long

vdadSentry ;

unsigned long
unsigned long

unsigned long

vdadSkav_data ;

vdad$viraddrMO ;

vdad$viraddrM3 ;

VARYINGSTRING (32) vdad$controllername;
int

*/
*/

vdad$ipl ;

D-2 Example Programs—VDAD Device Driver

/* Global status variable.
/* for SVMESETUP

*/
*/

/* addr mode: Byte/Word swapping.*/

/* addr mode: NO swapping.

/* device priority level

/* device name for controller

Example Programs—VDADDevice Driver

[* ptr to region for ISR comms. */
/* initialization sync event
*/
*/
vdadSdevice [MAXCHANNELS] ; /* device objects for signalling
vdadSmutex[MAXCHANNELS] ; /* controller ownership mutex’s
*/
vdad$channels [MAXCHANNELS]; /* Array of process (channel) id’s */
x/
vdadSinterruptsenabled ;
/* Polling or Interrupt ops.
*/
vdad$vector ;
/* Interrupt vector.
x/
vdadSmonitoring ;
/* Statistics-gathering off/on.
x/
vdad$conditions,
/* ...for statistics-gathering.
x/
vdadS$setups,
/* (see ‘monitoring’).
x/
vdad$Sreads ;
/* (see ‘monitoring’).

vdadregiontype *vdad$region

EVENT

vdadSeventinit;

DEVICE

MUTEX
int
BOOLEAN
int

BOOLEAN
unsigned long

;

/*
* Forward References for functions
*/
void
vdadSerrortext ();
BOOLEAN
vdad$cond_handler ();
/*
*

Pointers to VDAD registers.

*/
unsigned short
unsigned char

*padcreadconv_addr ;
*p portA data dirreg,

*pportAcontrolreg,

/* (WORD-addressable register)

/* (BYTE-addressable registers)

*pportAdatareg,
*pportgencontrolreg,
*pportservicereqreg,
*pportintvecreg,
*pportstatusreg,
xpintlevelreg ;

Example Programs—VDADDevice Driver D-3

Example Programs—VDADDevice Driver
/*
*

Useful macros.

#define
/x

ERRORDETECTED

(! (status & 1))

/* .,.for error-testing... */

KKKEKKEKKKKK KK KK KKK KKKKK KKK KEK KKKKKKES

***

VDAD-DRIVER main routine code

***

KKKKKKKEKEKK KEK KRKKKEKKRE KKK KKKKKRKKKKRKKKEKKKKKER

* This is the main routine for the PEP VDAD driver.
* It first initialises the ELN Device control structures, then
* the VMEbus-specific structures.
*

* This is a ONCE-ONLY routine - it must NOT be called more than once.
k

* Note that we have to drop into Kernel mode in order to execute the
* KERSCREATEDEVICE call. Otherwise, we remain in User mode (or whatever
* mode we were in).
*

int
{

vdadSinit()

int
status ;
int
initialise() ;
struct { int argcount, *status ; }

argblock = { 1, 0};

Initialise the VDAD Device into ELN.

kerSenterkernelcontext

( &status,

initialise,
gargblock ) ;
if ERRORDETECTED vdadSerrortext (status) ;

/*
*

Initialise the VME-bus mapping, etc..

status = VMEbusinit();
if ERRORDETECTED vdadSerrortext (status) ;

return( status )

}

;

D-4 Example Programs—VDAD Device Driver

OO
ee

kAK
6ITNITIALISE-—
***
KK KKK KKK RK KIRA KR AKKRAKKKE RARER KK
This routine must execute in KERNEL MODE

!!!

KKKKKKKKRKEKKKKKKKKKKKKKKKEKKKKKKK

Example Programs—VDADDevice Driver

int

{

initialise()
void

vdad_isr();

int
static

status, channel ;
$DESCRIPTOR(devicename,"");

void

channelprocess ();

vdadSsetups

= 0;

Number of times SETUP has been called.

Get the device name from the program argument list
(NB: Program Argument number FOUR ! [params 1,2 & 3 are required

for Vax-C I/0])

eln$Sprogramargument (&vdad$controllername, 4);

devicename.dsc$apointer

= vdad§$controllername.data;

devicename.dsc$wlength

= vdad$controllername.count;

Create the device object

ker$createdevice(
&status,

/* Status

&devicename,

/* Device name

RELATIVEVECTOR,

/* Relative vector

x/
(NEVER ZERO !)

vdad_isr,

/* Interrupt service routine

&vdadSregion,

/* Address of communications region */

sizeof (vdad$region) ,

NULL,
NULL,

/* Size of communications region

/* Register pointer
/* Adapter pointer

x/
x/

&vdad$vector,
/* Pointer to vector
&vdad$Sipl,
/* Interrupt priority
&vdad$device[0],
/* ptr to receive device variable
MAXCHANNELS,
/* Number of devices to create
NULL) ;
/* Power fail isr (not needed)
*/
if ERRORDETECTED vdadSerrortext (status) ;

*/
x/
*/
x/

Create the controller protection mutex’s (one per channel).

for (channel = 0; channel < MAXCHANNELS; channel+t+)

{

ELNSCREATEMUTEX( vdadSmutex[channel] , &status);
if ERRORDETECTED
vdadSerrortext (status) ;

Example Programs—VDAD Device Driver D-5

Example Programs—VDADDevice Driver
return( status )

}

;

KEKKKKKKKKKKKKKKKRK KKK KKK KKK KKKKKKKEKKKKKEKKKKKKKEKK

TNITIALIZE

VME-bus_

KEKKKKKKKKKKKEKKEKKKKKKKKRKKKRKKRKEKKKKKRKKKEKKEKKRKEKKKKKE

* This routine is called to initialise the VMEbus mapping, and also
* internal pointers into the VDAD’s registers.
x

* Returns: status
*
*k

*/
int

{

Inputs:

none

VMEbusinit ()

unsigned long
unsigned long
int

phyaddr, addrmode;
pagecnt;
status, KAVflags;

vdad$kav_data
vdadSkav_setup

/* address ptrs for quick ref

= 0x00000000;
= KAVSKALLOWVMEIRQ;

KAVSVMESETUP( &status,

vdads$kav_setup,

&vdadSkav_data );

if ERRORDETECTED

vdad$errortext (status) ;

D-6 Example Programs—VDAD Device Driver

/* No IRQ allowed */
/* (initially, at least) */

Example Programs—VDADDevice Driver
1;

/* No. of 64K pages */

KAVSKUSER24 ;

/* Standard User Mode */

pagecnt
phyaddr

VDADPHYSADDR ;

KAVer
flags

KAVSMVME+KAVSMMODE0SWAP;

addrmode

No te

regarding byte/word swapping:

/* Byte Swapping */

Since most of the VDAD registers are byte accessed,

and the VDAD itself is a "big endian", then we MUST

set up for byte-swapping.
HOWEVER, one register - where the 12-bit sampled data
is read - is put onto the bus UN-BYTE-SWAPPED. If we
attempt to access it in byte/word swapping mode, then
the two bytes (containing the 12-bit sample) will be
erroneously swapped, necessitating byte-swapping here
in the Driver. Since this introduces an unacceptable
overhead (ie. byte-swapping EACH sample), we must use
another method.

The solution is to create TWO ‘OUTMAP’s - one with

byte-swapping, the other without.

KAVSOUT_MAP(

&status,

&vdadsentry,
pagecnt,
phyaddr,

&vdadSviraddrM0,

addrmode,
KAV flags);

if ERRORDETECTED vdadSerrortext (status);
KAV1
flags = KAVSMVME+KAVSMMODE3SWAP;
*
*

/* NO Byte Swapping */

Now map with NO byte-swapping. We use this when accessing
WORD registers on VDAD.

*/
KAVSOUT_MAP(

&status,

&vdadSentry,
pagecnt,
phyaddr,
&vdad$vir_addrM3,
addrmode,
KAV flags);

if ERROR_DETECTED vdadSerrortext (status);

Example Programs—VDAD Device Driver D-7

Example Programs—VDADDevice Driver
/*

Setup the VDAD register pointers (virtual)

pportAdatadirreg = vdad$vir_addrM0 + VDADBASE + -

+ OFFSETportadata_dirreg;
pporta_control_reg= vdad$vir_addrMO+VDAD BASE+OFFSETportAcontrolreg;

pportAdatareg = vdad$viraddr MO+ VDADBASE + OFFSETportAdatareg;

pportgen_control_reg = vdad$vir_addrM0 + VDAD_BASE + + OFFSET_port_gen_control_reg;
pportservicereqreg = vdad$vir_addrMO + VDADBASE + + OFFSETportservicereqreg;
pportintvecreg = vdad$vir|addr M0 + VDAD BASE + OFFSETportintvecreg;
p_port_status_reg = vdadSvir_addr MO + VDAD_BASE + OFFSETport_status_reg;
pint level_reg = vdad§vir addr MO + VDAD_BASE + OFFSETint_level_reg;

padcread conv addr = vdad$viraddrM3 +VDADBASE + + OFFSETadc_read_conv_addr;

/*
*
x

Copy the device registers into the comms region, so that the
Interrupt Service rtne (vdad_isr) can access the VDAD registers.

vdadSregion->pportAdatadirreg
vdadSregion->pportAcontrolreg

vdad$region->pportAdatareg

vdadSregion->pportgencontrolreg
vdadSregion->pportservicereqreg
vdad$region->pportintvecreg
vdad$region->pportstatusreg
vdad$region->pint levelreg
vdadSregion->padcread_conv_addr
return( status )

} /*

end

;

initialisecontroller

D-8 Example Programs—VDAD Device Driver

pportAdata dirreg ;
pportA_control_reg ;
p_portAdatareg ;
pportgen_controlreg ;
pportserviceregreg ;
pportintvecreg ;
pportstatus_reg ;

pintlevelreg ;
p_adcreadconvaddr ;

Example Programs—VDADDevice Driver

/* ~ eee ee x /

/*
*

setup controller

* This routine is called to perform the controller setup.
x

* Returns: int

status

* Inputs:
*
x

gain,

int

(see .H file for definitions)

inputconfig,
channelmode,

*
*

triggertype,

interrupthandling,
conditionhandling,

*
*
*

monitorswitch
Note: Any of the above params may be NULLed, in which case the ‘current’
default is used. This means that it is possible to, say, change

*
*

ONLY the GAIN whilst the device is operating.
|

*/
int

vdad§$setup( gain, inputconfig, channelmode, triggertype,
interrupthandling, conditionhandling, monitorswitch )

int

gain,
inputconfig,

channelmode,
triggertype,

interrupthandling,

conditionhandling,
monitorswitch ;

{

int
unsigned char
union {

status ;
temp ;

portAdatareg

bits ;

(for access to bits)

portAcontrolreg
unsigned char
} controlreg ;

bits ;
byte ;

/*
/*

(for access to bits)
*/
(BYTE access to entire register) */

unsigned char
} setupreg ;
union {

vdadSconditions = 0 ;
vdadS$reads
= 0;
vdadSsetupst+ ;

byte ;

(BYTE access to entire register) */

/*
Zero this out (a driver global).
x/
[Keene
,
*/
/*
Log this SETUP call (a driver global). */

if ( conditionhandling == VDADSSETUPCONDHANDLINGDRIVER)

VAXCSESTABLISH (vdad$condhandler); /* Establish the DRIVER’s Handler */

Example Programs—VDAD Device Driver D-9

Example Programs—VDADDevice Driver
/*

Device Initialization

ee ee

*
x
*

We first have to read the register contents to access the ‘current’
defaults, in the case where the user has NULL’ed one or more of
the input parameters.

kavsbusread(&status, KAV$KBYTE, pportAdatareg, &setupreg, 1);
if ERRORDETECTED

{ vdadSerrortext(status); exit(-1);

}

kav$Sbusread(&status, KAVSKBYTE, pportAcontrolreg, &controlreg, 1);
if ERRORDETECTED { vdadSerrortext (status); exit(-1); }
Switch

( gain )

case VDADSSETUPGAIN1 :

setupreg.bits.gain

case VDADSSETUPGAIN10 :
case VDADSSETUPGAIN100 :
default: break ;

} 7

switch

end CASE

setupreg.bits.gain
setupreg.bits.gain

switch

GAIN

>>>

0 ; break ;

---=
=

1; break ;
2; break ;

( inputconfig )

case VDADSSETUP_INPCONFIG1
break ;
case VDADSSETUPINPCONFIG2
break ;
case VDADSSETUPINPCONFIG3
break ;
case VDADSSETUP_INPCONFIG4
break ;
default: break ;

} ;

<<<

<<< INPUT CONFIGURATION

>>>

: setupreg.bits.inputconfig

= ;

: setupreg.bits.inputconfig

= ;

: setupreg.bits.inputconfig

= ;

: setup_reg.bits.inputconfig

= 3 ;

wennnnnnnnnna---=-

/* end CASE */

( channelmode )

<<< SINGLE/MULTI-CHANNEL MODE

case VDADSSETUPCHANNELMODESINGLE:

>>>

setupreg.bits.channelmode

break ;
case VDADSSETUP_CHANNELMODEMULTIPLE: setupreg.bits.channelmode
break ;
default: break ;

} ;

/* end CASE */

D-10 Example Programs—VDAD Device Driver

= 0 ;

= ;

Example Programs—VDADDevice Driver

switch

{

( triggertype )

case VDADSSETUP_TRIGGERSOFTWARE

break ;

<<< TRIGGER

*/
*/

>>>

setupreg.bits.triggertype

case VDADS$SETUPTRIGGEREXTERN

setupreg.bits.triggertype

break ;

case VDADSSETUP_TRIGGERTIMER
setupreg.bits.triggertype
break ;
case VDADSSETUPTRIGGEREXTERNANDTIMER: setupreg.bits.triggertype
break ;
default:

} ;

switch

{

break ;

end CASE

( interrupthandling )

case VDADSSETUP_INTDISABLE
case VDADSSETUPINTENABLE
default:

} ;

switch

{

} ;

break ;

end CASE

<<< INTERRUPTS or POLLING

control reg.bits.EOC ien

>>>

*/
*/

vdad$interruptsenabled = FALSE ;

break ;

control reg.bits.EOC ien -1:’

vdad$interruptsenabled = TRUE ;

*/
/*

<<<

Statistics-gathering

vdad$monitoring = FALSE ; break t
vdadSmonitoring
TRUE ; break ;

case VDAD$SETUP_MONITORINGOFF :
case VDADSSETUP_MONITORINGON
default: break ;

end CASE

break ;

( monitorswitch )

>>>

/*
*

if (vdadSinterruptsenabled)

{

<<<

(Interrupt Request Level)

/*
temp = VDAD IRQL;

Setup for INTERRUPTS

>>>

kavSbuswrite (&status, KAV$KBYTE, pintlevelreg, &temp, 1);
if ERRORDETECTED { vdadSerrortext (status); exit(-1); }

temp = VDADIRQV;

/* (Interrupt Vector Number)
kavSbuswrite (&status, KAVSK BYTE, pportintvec reg, &temp, 1);
if ERRORDETECTED

*/
*/
*/
*/
*/

{ vdadSerrortext (status); exit(-1); }

temp = VDAD PGCR INIT;

(Port Gen Control reg)

kav$bus write(&status, KAVSKBYTE, pportgencontrolreg, &temp, 1);
if ERRORDETECTED { vdadSerrortext (status); exit(-1); }

Example Programs—VDAD Device Driver D-11

Example Programs—VDADDevice Driver

temp = VDADPSRRINIT ;

(Port Service Request reg)

(Port Control reg)

kavSbuswrite (&status, KAVSKBYTE, pportservicereqreg, &temp, 1);
if ERRORDETECTED { vdadSerrortext (status); exit(-1); }

control_reg.bits.fixed

=1;

Set submode for A/D register.

/*
/*

(Port Data Direction reg)
(Set up for A/D mode)

controlreg.bits.EOC ien = 1; /* Enable interrupts.
x/
kavSbus_write(&status, KAVSKBYTE,pportAcontrolreg,&controlreg,1);
if ERROR|DETECTED { vdadSerrortext (status) ; exit(-1); }

temp = VDADPADDRINIT ;

kavSbuswrite(&status, KAV$K_ BYTE, pportAdata dirreg, &temp, 1);
if ERROR_DETECTED { vdadSerror_text (status) ; exit(-1); }

*/
x/

kav$buswrite(&status, KAVSK BYTE, pportAdatareg, &setupreg, 1);
if ERROR_DETECTED

/*
*

{ vdadSerror_text (status); exit(-1);

}

Finally, we must set up the KAV to allow interrupts.

*/
vdadSkav_data

vdadSkav setup

KAVSVMESETUP(

= 0x00000002;

= KAVSKALLOW VMEIRQ;

IRQ 1 allowed.

&status, vdadSkavsetup, &vdad$kavdata );

if ERRORDETECTED

vdadSerror_text (status) ;

} else

[*
/*
/*

{

temp = VDADPADDRINIT ;

<<<

Setup for POLLING

>>>

Port-A Data Dir Reg init value. */
(Set up for A/D mode)

kavSbuswrite (&status, KAVSKBYTE, pportAdatadirreg, &temp, 1);
if ERRORDETECTED

*/
x/
*/
*/

{ vdadSerrortext(status); exit(-1); }

controlreg.bits.fixed

=1;

Set submode for A/D register.

kav$buswrite (&status, KAVSKBYTE,pportAcontrol_reg,&controlreg,1);
if ERRORDETECTED { vdad$errortext (status); exit(-1); }
kavSbuswrite (&status, KAVSK BYTE, pportAdatareg, &setupreg, 1);
if ERROR_DETECTED { vdad$error_text (status) ; exit(-1); }
return( status )

} /*

end

;

-VDADSSETUP-

D-12 Example Programs—VDAD Device Driver

KREEKKKKEKEKKKKKKKKEKKKKEKKKKKKEKKKKKKKKE

**e

READ

CHANNEL.

***

KKKKKKKKKKKEKKEKEKKEKKKKKKKKKKKKKKEKKKKK

This routine is called to read a block of data from a selected channel.

Returns:

int

status

Inputs:

int

(see .H file for definitions)

channel,
timeout,
*buffer,
numsamples,

(A/D channel: 0..15)
(buffer to receive the data)
(number of samples requested)

*numsamplesread (actual number ....received)

Notes:
(1)
On return to the caller, "numsamples" should always equal
"numsamplesread". In the case of timeout on a single conversion,
the latter will reflect the number of successful samples up to the

HHH

—

Example Programs—VDADDevice Driver

(2)

point of the timeout.

The "ADC Read/Convert" register is DANGEROUS !!
ie. do NOT access it unless the EOC bit has signalled a successful

conversion.

*/
int

vdad$Sread( channel, timeout, buffer, numsamples, numsamplesread )

int
long

unsigned short
int

{

int

channel ;
timeout ;

*buffer ;
numsamples, *numsamplesread ;
status, temp ;

DEVICE

dev ;

unsigned short

*psample ;

*numsamplesread = 0;

This is purely for quick reference

Zero this out (user’s data).

status

SUCCESS ;

dev

vdadSdevice[channel] ;

p_sample

if (vdad$monitoring)

,,.ditto...

x/
*/

&( vdadSregion->value[channel] ) ;
{ vdad$readst++ ;

} /* Count calls to this rtne. */

Example Programs—VDAD Device Driver D-13

Example Programs—VDADDevice Driver
switch (vdadSinterruptsenabled)
{
case TRUE :

/*
[RO

Poll or use interrupts ?
mmr nnn nn nnn nnn nnn nm

*/
*/

KKKKKKKKKKEKKKKKKKKKK

KKKKKKKKKKKKKKKKKKKE

**k

INTERRUPTS

***

for (1 = 0; 1 < numsamples; itt, buffert+ )

{

/*
* Write in the requested channel, starting the conversion.

*padcreadconvaddr
/*

= channel ;

* Now wait for our ISR to do the read under interrupt control.

ker$Swaitany( &status, NULL, NULL, dev ) ;
if ERRORDETECTED { vdadSerrortext (status); exit(-1); }
/*
* Copy data back to the user buffer.

*/
*buffer = *psample ;
bj
break ;
case FALSE

/* end -forend -case-

KKKKKKEKKKEKKKRKKKKKKKE

kkk

kxkx

KREKEKKKKKKKKKKKKKEKKKE

POLLING

for (1 = 0; 1 < numsamples; i++, buffer+t )

{

/*
* Write in the requested channel, starting the conversion.

*padcreadconvaddr

= channel ;

while (((*pportAdatareg) & 0x80)

{

/* ADC conversion complete. Copy the sampled data, */
/* ignoring bits 12-15 (ie. the channel).
x/
/* [we should really check the channel here]
*/
*buffer

}

break ;

bo;

default:

!= 0x80);

end -while-

end -for-

end -case-

end

-switch-

break ;

= (*padcreadconv_addr & Ox0FFF) ;

*numsamplesread = i;

*/
x/

/* Return successful reads to user.

D-—14 Example Programs—VDAD Device Driver

Example Programs—VDADDevice Driver
return( status })

}

xxx

;

end

vdadread

***

/* ——-—--— x /

/*
*k

KEKKKKKEKKKRKEKKRKKK KKK KEK KEK KKK KKK KK KRKKKKKEKKRKKRKKKKK

KKKKK

KEKKKRKKEKKKKEKKKRKKK KKK RK KKK KK KKKKKKRKKRKKKKKKKKKKKK

EXCEPTION

HANDLER

KKKKK

* This routine is called AUTOMATICALLY when ELN raises an exception.
*k

* Returns:

int

status

(see .H file for definitions)

Notes:

BOOLEAN vdad$condhandler(signalptr, mechanismptr)

struct chf$signalarray *signalptr;
struct chf$mecharray

{

*mechanismptr;

void vdadSerrortext (int status);
static int status;

if (vdadSmonitoring)

{

printf ("\nVDAD-Driver: Condition Handled (number %d) - ",
vdadSconditions++) ;
} else

{

printf ("\nVDAD-Driver: Condition Handled - " );

status = signalptr->chf$l_signame;
vdadserrortext (status) ;

}

exit (1);

void

{

vdadserrortext( int error )

int textflags;
char textbuffer[255];
VARYINGSTRING(255) resultstring;
text_flags = STATUSSALL;

eln$get_statustext(error, textflags, &resultstring);
VARYINGTO CSTRING (result_string, text_buffer);
printf ("\n$s\n", text_buffer) ;

Example Programs—VDAD Device Driver D-15

Example Programs—VDADDevice Driver

}

return;

VDAD ist
This is the device interrupt status routine. It is called by the kernel

when a device interrupt occurs.
It reads the sampled data, strips off the 4-bit channel id (bits 12..15),
and stores the result into the Comms Region.

It then signals the waiting process. The Channel number indicates which

Device Object is signalled.

Returns:

The sampled data is copied into the Device Comms
Region.

Inputs:
registerptr = pointer to device registers
regionptr = pointer to driver communications region
Notes:

vol d

vdadisr(registerptr, vdad$region )

char

*registerptr;

vdadregiontype *vdad$region

{

unsigned short

;

reset_irg = VDADEOCIRQ ;

static short

channel ;

int

status ;

/*
*

Read the data

(a word)

*/
kav$busread( &status,

from VDAD.

KAVSK WORD,

vdad$region->padcreadconvaddr,
& (vdad$region->reg.word) ,
1);

/*
*

Extract the channel (top 4 bits) and sampled value (bottom 12 bits).

*/
channel

vdad$Sregion->value[channel]

= vdadSregion->reg.ADCregister.channel ;
= vdad$Sregion->reg.ADCregister.value ;

/*
*

Reset the device for further interrupts.

kav$Sbusbitset(

éstatus,
KAVSKBYTE,

vdad$region->pportstatusreg,
resetirq) ;

D-16 Example Programs—VDAD Device Driver

Example Programs—VDADDevice Driver
/*
*

Signal the device (indexed by ‘channel’).

*/
ker$signaldevice(NULL, channel );

}

/* --- end of VDAD ISR ---

D.2 Definitions File
/x

¢ Definitions file for:-

x
x

KEKKEKRKKEKRKKRKKKKRKRK KKK KEK KEK KKK KKK KE KKKERKKKKKKKKKKKKK

xxx

PEP VDAD Digital-Analog-Digital Converter

***

KKKEKKKKKKEKKEKKEK KR KKK KKK RK KEK KKK KEKKKKKKKRKKKKKKKKKKK

#define

VDADBASE

0x0e00

/*Check the rotary switch on the
/*KAV - they should agree.

*/
*/

#define
VDADPHYSADDR Oxfe0000
/* #define
VDADPHYSADDR 0x0000

/*24-bit access.
*/
$/*16-bit access.

#define
#define
#define
#define

VDAD_IRQV
0x04
VDADPADDRINIT 0x7F
VDADPGCRINIT 0x11
VDAD PSRR INIT 0x18

/*Interrupt Vector number.
x/
/*Port-A Data Dir Reg init value. */
/*Port Gen Cntrl Reg init value. */
/*Port Service Reg Reg init value.*/

#define

VDADPACRINITPOLL 0x80

#define
#define

#define

VDADEOCIRQ
VDAD_IRQL

0x01
0x01

VDADPACRINITINT 0x82

/*Interrupt Reset value.
/xInterrupt Request Level.

*/
*/

*/
x/

/*Port-A Cntrl Reg init val (INTER) .*/
/*Port-A Cntrl Reg init val (POLL) .*/

/x
*

x
*/

This next assignment is IMPORTANT !!!

#define

/*
*

It should NEVER be zero, and it

should NOT be changed. The "Createdevice" call needs it.
|
RELATIVEVECTOR 0x01

/* (NEVER ZERO !!!)

Maximum 16 single-ended, 8 differential channels per board.

#define MAXCHANNELS

Example Programs—VDADDevice Driver D-17

Example Programs—VDADDevice Driver
/*
*

Status return values

#define
#define
#define
#define

SUCCESS
ERROR
DEVOFFLINE
ILLIOFUNC

1
-1
0x84
OxF4

#define
#define
/*

NOSUCHDEV
TIMEOUT

0x908
0x22C

VDAD Setup options

#define
#define

IVADDR
IVBUFLEN

0x134
0x34C

*
*
x

Note: None of these can have the value zero, since the user may NULL
one or more of the parameters in a VDAD call.

/*
/*

Interrupts or Polling.

#define

VDADSSETUPINTDISABLE

#define

VDADSSETUPGAIN1

#define

#define
#define
/*

VDADSSETUPINTENABLE

VDADSSETUPGAIN10
VDADSSETUPGAIN100

Disable interrupts.

Three options for GAIN value.

2
3

Input channel configuration :-

#define

VDADSSETUPINPCONFIG1 1

#define
#define

VDADSSETUPINPCONFIG3 3
VDADSSETUPINPCONFIG4 4

/*
/*

#define

/*
/*

#define

#define
/*
/*

VDAD$SETUPINPCONFIG2 2

VDADSSETUP_CHANNELMODESINGLE

VDADSSETUPCHANNELMODEMULTIPLE

Single-ended

Differential

..16

n/a

*/
*/
*/
*/

eee
0..5,

+--+ --

8..13

0..3, 8..11
n/a
1

Trigger types.

VDADSSETUP_TRIGGERSOFTWARE

#define

VDADSSETUPTRIGGERTIMER

#define
#define

VDADSSETUPCONDHANDLINGDRIVER
VDADS$SETUPCONDHANDLINGUSER

#define

VDAD$SSETUP_MONITORINGON

#define

VDADSSETUP_MONITORINGOFF

#define

6,7

4..7
0..7

Sampling mode

#define

Enable interrupts.

VDAD$SETUPTRIGGEREXTERN

VDADSSETUPTRIGGEREXTERNANDTIMER 4
/* Use Driver’s

/* Single-channel.

/* Multi-......... eee.

D-18 Example Programs—VDADDevice Driver

1
2

(statistics) on/off.
1

*/
*/
*/
*/

*/
*/
/* ...by software.
*/
/* ...by external stim. */
/* ...by Timer.
*/
/* ...by extern & Timer. */

or User’s Condition Handler.*/

/* Turn ‘monitoring’

*/
*/

Example Programs—VDADDevice Driver
/*
VDAD Register offsets

*
*k

*/
#define
#define
#define
#define
#define
#define
#define
#define
#define
/*

OFFSETportgencontrolreg
OFFSETportservicereqreg

0x01
0x03

OFFSETportint vecreg
OFFSETportA_control_reg
OFFSETportAdatareg
OFFSETportstatusreg

0x0b
0x0d
0x11
Oxlb

OFFSETporta|datadir_reg

0x05

OFFSETadcreadconvaddr
OFFSETintlevelreg

0x40
Oxff

There are more registers on this module, but we do not require
access to them in this version.

/*
*

KKKEKKKKKKKKKKKRKKKKRKKKEKKKKKKKKKKKKKKKKKKKKK

*kk

VDAD Device register definitions

***

KREKKKKKKKKKKRKEKRKKKKKKKKKKKEKKKKKKKKEKKKEKKKKK

typedef struct

{

unsign ed
unsign ed
unsign ed
unsign ed
unsigned

}

gain

inputconfig
channelmode
triggertype
unused

portAdatareg ;

/*
/*

2;
1 ;
2;
1 ;
/*

unsign ed EOCIRQ
unsign ed edge
unsigned HI1H2enable
unsigned H3H4 enable
unsigned fixed
} portgencontrol“reg ;

1 ;

{

unsigned

unusedl

unsigned
unsigned

unused2
fixed

unsigned
unsigned
' unsigned

}

EOCien
H2ien
H2transition

portAcontrolreg ;

x/
x/

typedef struct

<<< Port-A Data Register >>>

3 ;
1 ;
1 ;

/*
/*

<<< Port General Control Register >>> */

(always zero)

<<< Port-A Control Register >>>

x/
x/

1 ;

1 ;
1 ;
3;
1 ;

2 j

Example Programs—VDADDevice Driver D-19

Example Programs—VDADDevice Driver
typedef struct
{
unsigned H1234levels

/*
<<< Port Status Register >>>
/*
4; /* Current levels at HI-H4 pins */

unsigned H432Sstatus

;

unsigned EOCstatus
} port_statusreg ;

3; /* H4S, H3S, H2S status pins

1; /* EOC status bit.

x/
*/

*/
*/

/x
x

Driver-specific structures.

*/
typedef struct

{

unsigned

/*
*

}

value

channel

AD RC reg ;

> 12

<<< A/D Read/Convert Address Register >>> */
;

;

#=(/*

12-bit converted value (HI NIBBLE) .*/

Channel number.

Note that when you WRITE to this register, you write the channel number
into bits 0-3. However, when you READ this, VDAD puts the channel into

bits 12-15.

/*
*
*

This is the data stucture which allows the Interrupt Service Routine

to pass data to/from the rest of the Driver.

This is the only method, since an ELN ISR executes in a different context
from the 'owning’ process.

typedef struct

{

union {

<<< Communications Region for Interrupt Service >>> */

ADRCreg
ADCregister ; /* 'bare’ contents of register */
unsigned short word;
/* (WORD access to register) */

} reg ;

}

unsigned short

value[MAXCHANNELS] ; /*ADC value only (per channel) */

unsigned char

*pportAdatadirreg,/* VDAD register pointers.
*pportAcontrolreg,

unsigned short

*pportAdatareg,
*pportgencontrolreg,
*pportservicereqreg,
*pportintvecreg,
*pportstatusreg,
*pintlevelreg ;
*padcreadconvaddr ;

vdadregiontype ;

D-20 Example Programs—VDADDevice Driver

Example Programs—VDADDevice Driver

D.3 Test Program
FACILITY:
VAXELN Run Time System
ABSTRACT:
This program demonstrates how to access the VDAD Driver.
VERSION:
V1.00

13-Mar-1991

Field Test Release.

NOTES:
This is a simple example of how to access the VDAD Driver.
/
.
/*
*
*k

Include Files

#include stdio
#include $vaxelnc
#include $dda_utility
#include $mutex
#include chfdef
#include descrip
#include <eln$:kavdef.h>
#include $get_messagetext
#include types

/* VDAD Driver definitions

#include "vdaddriver.h"

#define SIZEOFDATABUFFER 1024
unsigned short

unsigned short

samplebuffer[SIZEOFDATABUFFER] ;
*pbuf

;

main ()

{

void errortext();

void displaybuffer() ;
BOOLEAN displaysamples ;
char beep{2] =" "j;
int
status, temp, chan, useinterrupts ;

long int numbuffers, blockcount, numsamplesread ;

pbuf

= &samplebuffer[0]

;

blockcount = 0 ;
printf ("VDAD test process started\n");
printf ("Setting up the VDAD Device...\n");

Example Programs—VDAD Device Driver D-21

Example Programs—VDADDevice Driver
/*
x

Initialise the VDAD Driver (this is a once-only call).

status = vdadSinit( )

;

if (!(status & 1)) { errortext (status); exit(-1); }
/*
*

Ask for number of iterations.

printf("\nHow many iterations (1 Kbyte per iteration)
scanf("%sd", é&numbuffers );

? : ");

/*
x

Ask for ADC Channel number.

get_chan:
printf("\nWhich ADC channel [0-15] ?: ");
scanf("Sd", &chan );
if ( (chan > 15) || (chan < 0)

)

printf("\nInvalid channel number. Re-enter correctly.");
goto getchan ;
b
/*
x

Ask for "Interrupts or Polling".

*/
printf("\nDo you wish to use Interrupts [1=Yes, 0=No] ?: ");
scanf("sd", &temp );

if ( temp == 1 )

useinterrupts = VDADSSETUPINTENABLE ;

} else

{

printf ("\nInterrupts in use ! \n");

useinterrupts = VDADSSETUPINTDISABLE ;

printf ("\nPolling (ie. NO interrupts) \n");

/*
*

Does the user want a "sample-dump" ?

printf("\nDo you wish to see the sampled buffer [l=Yes, 0=No] ? : ");
scanf("sd", &temp );
if ( temp == 1) { displaysamples = TRUE;} else { displaysamples = FALSE; };

D-22 Example Programs—VDADDevice Driver

Example Programs—VDADDevice Driver
/*
*

Set up the VDAD Driver (this can be called at any time).

status = vdadSsetup(

VDADSSETUPGAIN1,

VDADSSETUPINPCONFIG1,

VDADSSETUPCHANNELMODESINGLE,
VDAD$SSETUPTRIGGERSOFTWARE ,

useinterrupts,

VDAD$SETUP_CONDHANDLINGDRIVER,
VDADSSETUPMONITORINGOFF
) ;

if (!(status & 1)) { errortext(status); exit(-1); }

printf ("\nVDAD Set up OK. Commencing sampling with block size of %d.",

SIZEOFDATABUFFER) ;

printf("\nNote that each ’.’ represents ONE BLOCK successfully sampled.");
printf£("\nA total of %d blocks will be sampled.", numbuffers) ;

printf ("\n[have you switched the console terminal into AUTO-WRAP ?]\n\n");
printf("\nHit a character, then <RETURN> to start sampling : ");
scanf("ss", &temp);

printf ("\nSampling commencing...\n");
printf (beep) ;
blockcount = 0 ;

while (blockcountt++ < numbuffers )

{

/*
*
*

Request the VDAD Driver to fill in the buffer with the requested
number of samples.

status = vdadSread( chan,
NULL,
&(samplebuffer[0]),

SIZEOFDATABUFFER,

if (!(status & 1))
printf("." ) ;

&énumsamplesread ) ;

{ errortext (status); exit(-1);

if (displaysamples==TRUE)

}

end -while-

{ displaybuffer()

;

}

} ;

printf (beep) ;
printf ("\n\nVDAD Test process finito !\n");

void errortext (status)
int status;
int text flags;

char textbuffer[255];

VARYINGSTRING(255) result_string;

Example Programs—VDAD Device Driver D-—23

Example Programs—VDADDevice Driver
textflags = STATUSSALL;
eln$get_statustext (status, textflags, &result_string);
VARYINGTOCSTRING(resultstring, textbuffer);
printf ("ss\n", textbuffer) ;

}

return;

void

displaybuffer ()

{

xxkkk

Dump of sample buffer (16 samples per line)

****\n")

for (i=0; i < SIZEOFDATABUFFER; )
{
for (j=0; (j < 16) &&(j+i < SIZEOFDATABUFFER); j++ )
{
printf ("%s3x,", samplebuffer[itj]) ;

samplebuffer[1i+j] = SIZEOFDATABUFFER - (i+}j) ;

}

1=i+16;

}
}

printf("\n") ;

return;

/k ----------------~-----------------------------------------------~+------ x /

D-—24 Example Programs—VDAD Device Driver

Example Programs—VDADDevice Driver

D.4 Build File
9!
S$!

Command Procedure to compile, link and EBUILD the VDAD test program.

> cc /NOOPTIMIZE testvdad.c +telnS:vaxelnc /library

$ cc /NOOPTIMIZE vdaddriver.c teln$:vaxelnc /library
9!

S If "’'’FSSearch("VDAD.OLB")’" .EQS. "" Then LIBRARY/Create VDAD.OLB
S$ LIBRARY/REPLACE VDAD.OLB test_vdad.OBJ
S$ LIBRARY/REPLACE VDAD.OLB VDADDRIVER.OBJ

S DEFINE CSLIBRARY ELNS$:VAXELNC.TLB

S DEFINE LNKSLIBRARY ELNS:CRTLSHARE

$ DEFINE LNKSLIBRARY1 ELN$:RTLSHARE
9 DEFINE LNKSLIBRARY2 ELNS:RTL

$ DEFINE LNKSLIBRARY3 ELN$:KAVSRTLOBJLIB

9 LINK /EXE=test_vdad vdad.olb/library/include=(testvdad) /nosyslib/nosysshr
9!
$ EBUILD /noedi testvdad
9!
Sexit

D.5 Data File
characteristic /nofile /netdevice=EZA /nodeaddress=63.740 /noserver /objects=512 /debug=none /ioregion=1024 -

/target=24 /image_list=(IPCSHR, AUXCSHR, ICSSHR)
program TESTVDAD.EXE /kernelstack=64 /userstack=10 /jobpriority=10 /argument=("",

MMIDApUN)

device EZA /vector=%X130 /net_def

device VDAD /vector=%X810 /noautoload

Example Programs—VDAD Device Driver D-25

Glossary
The glossary defines some of the important terms used in this guide.
application program
A program that performs an end-usertask.
ASB
Asynchronous system block. The ASB contains information about the AST
routine for a particular event.
AST
Asynchronous system trap. A procedure that the operating system calls when
a particular event occurs.
autovectored interrupt
An interrupt for which the interrupt handler provides the interrupt vector
address.
backup process
The process of making copies of the data stored on the disk, so that you can
recover that data after an accidental loss. You make backup copies on RX33
diskettes, TK50 tape cartridges, or over a network.

backup copy
A copy of the data stored on the disk.
BCD
Binary coded decimal. Pertaining to a numberrepresentation system in which
each decimal digit is represented by a unique arrangementof binary digits.
big-endian device
A device based on the 68000® family of processors.

Glossary-1

BR line
Bus request line. A signal line on which a device issues a bus request signal.
CPU
Central processing unit. The main unit of a computer that containsthe circuits
that control the interpretation and execution of instructions. The CPU holds
the main storage, arithmetic unit, and special registers.
CSRbit
Control and status register bit. The CSR bits consist of input bits and output
bits. The CSR input bits report on the status of the KAV30 hardware, while
the CSR output bits control the KAV30 hardware.
DAL bus
Data and address lines bus. A 32-bit multiplexed bus. The rtVAX 300 is the
source of the DAL bus.
DMA
Direct memory access. A method of accessing a device’s memory without
interacting with the device’s CPU.
FIFO
First-in/first-out. The order in which processing is performed. For example, a
FIFO queue processes data on a first-come,first-served basis.
FIFO buffer
A hardware area in which devices can store and retrieve data.

host system
The primary or controlling computer in a multiple computer network.
IACK
Interrupt-acknowledge signal. A signal, issued by an interrupt handler device,
which indicates that the device will handle an interrupt request.
interrupt
A break in the usual flow of a program to process an external request.
interrupt handler
A device that executes interrupt service routines for interrupt requesters. The
device receives interrupt requests from the bus.
Glossary—2

IPL
Interrupt priority level. The interrupt level at which an interrupt is generated.
There are 31 possible interrupt priority levels: IPL 1 is the lowest, 31 is the
highest. The levels arbitrate contention for processor service.
interrupt requester
A device that requests the execution of an interrupt service routine. The device
sends an interrupt request on the bus, which an interrupt handler respondsto.
interrupt vector address
An indirect address that points to the starting address of an interrupt service
routine.

IRQ
Interrupt-request signal. A signal, issued by a device, to execute an interrupt
service routine.

ISR
Interrupt service routine. The software that processes interrupt requests.
LIFO
Last-in/first-out. The order in which processing is performed. For example, a

LIFO queue processes data on a last-come,first-served basis.
little-endian device
A device based on the Intel™ family of processors.
RAM
Random-access memory. A read/write memory device.
ROM

Read-only memory. A memory in which information is permanently stored at
the time of production andis not alterable by computer instructions.
ROR
Release-on-request. When a VMEbus requester operates in ROR mode,it gives
up the data transfer bus when another VMEbus module requests the bus.
RWD
Release-when-done. When a VMEbus requester operates in RWD mode,it
gives up the data transfer bus only whenit finishes using the bus.
Glossary-3

SCB
System control block. The data structure in system space that containsall the
interrupt and exception vectors known to the system.

SsCsl
Small computer systems interface. An interface designed for connecting disks
and other peripheral devices to computer systems. SCSI is defined by an
American National Standards Institute (ANSI) standard.
SGM
Scatter-gather map. A meansof allowing either of the following types of data
transfer:
e

From pages in memory that are not contiguous to contiguous blocks on a
bus

From contiguous blocks on a bus to pages in memory that are not
contiguous

target system
A system in which a task executes.
vectored interrupts
An interrupt for which the interrupt requester provides the interrupt vector
address.
VSB
VME subsystem bus.

Glossary—4

Index
A
A16 addressing, 2—1, 2-2, 3-13

A24 addressing, 2-1
4—150, 5-17

A32 addressing, 2-1, 2—2, 3-12, 3-15,

4—150, 5-17, 5-19

ACFAIL signal, 2-5, 2-14, A-1

Asynchronous context block
See ASB
Asynchronous System Trap
See AST
Autovectored interrupts
VMEbus, 5-16, A-2
VSB, 5-16
Autovectored Interrupts, 3-2

ALTERNATE, 2-3, 4-89
Arbiter, 1-2

Auxiliary port,

priority mode, A-2
VMEbus, 2-3 to 2—4, 5-18
VSB, 2-4, 5-17
Arbitration
prioritized, 2-3
round-robin, 2-3
ASB, 1-5, 3-1, 3-2, 4-34, 4-96, 4-122
ASB$K_ASBFREE, 3-3
ASB$K_ASBPEND, 3-3
AST, 1-5, 1-6, 2-5, 3-1 to 3-4, 4-34 to
4-36, 4-58, 4-131
coding in VAX Ada, 5-4 to 5—7
coding in VAXELN Pascal, 5-9 to 5-12

Battery,

fair mode, A-2
hidden mode, A-2

data structures, 3-3

defining, 4-37 to 4—40

parameters, 3-2

queuing, 4—96 to 4-99

1-2, A—1

1-5, 3-7

checking, 4—30 to 4-33

Battery backed-up RAM,

1-2, 1-5, 1-6,

3-10, 4-30, 4-51, 4-116 to 4-121, A-1
Battery backed-up random-access memory
See Battery backed-up RAM

Big-endian, 3-18, 4-58, 4-84
BR lines, 2—1
Break command, 2-14

Break key, A-1
Bus request, 1-2

ROR mode, A-2

VMEbus, 5-18
VSB, 5-17
Bus Requestlines
See BR lines

routines, 3-2

setting, 4-122 to 4-126

writing, 5—3

AST queues"
clearing, 4—34 to 4-36

Index—1

C
Calendar/clock,

1-2, 1-5, 1-6, 3-6 to 3-8,

4-30, 4-100 to 4-115, 5-17, A-1, A—2
Clock period, 3-5
Compiling
KAV80 applications, 5-12

ELN$GET_STATUS_TEXT, 3-26
ERR signal, 2-9
Error logging, 3—24 to 3-29
Ethernet, 2-14

Example programs

FIFO consumer, B-—5 to B-9

Condition handler, 5-2

FIFO producer, B-—1 to B-4
interprocessor communication, B-—l1to
B-9

Configuration
KAV30, A-—1 to A-2
Console port, 1-2

MVME3835 device driver, C—1 to C—21
VDAD device driver, D-1 to D-25

Consumer, 3-9

Control and status register bits
See CSR bits
Control and status register page
See CSR page
Counter/timers, 1-2, 1-5, A-2
CSR bits, 2-14
CSR page, 5-14
CVAX microprocessor, 1-1

Exception handling, 5-2
F

Fair mode, 2—2, A—2
FIFO buffers, 1-1, 1-5, 1-6, 2-2, 3-9, 3-23,

4-16, 4-19, 4-20, 4-23, 4-27, 441,
4-46, 4-58, 4-74, 4-78, A-2

consumer, 3-9
errors, 2-14, 2-15

D
D08 transfers, 2—2
D16 transfers, 2-2
D32 transfers, 2-2
DAL bus, 2-38, 2—4, 3-6
master, 2-5
timeout period, 2-5
timeouts, 2-5
Data and addresslines bus
See DAL bus
Data and Address Lines bus
See DAL bus

producer, 3-9

FIFO modes, 4—46

First-in/first-out buffers
See FIFO buffers

H
HALTsignal, A-1

Hidden mode, 2-2, A-2
Host system, 1-1, 1-3

Debugging KAV30 applications, 5-20 to
5-21
Device drivers, 3-2
Direct memory access
See DMA, 2-3
DMA, 2-3

index—2

TV/O, 2-3, 4-89

routines, 5-3

TACK, 3-2
cycle, 2-6, 2-9
Input/Output routines
See I/O routines
Interrupt handler
VMEbus, 2-6 to 2-10

Interrupt handler (cont'd)
VSB, 2-12
Interrupt priority level
See IPL
Interrupt requester

VMEbus, 2-10 to 2-12

Interrupt service routines
See ISR
Interrupt-acknowledge cycle
See IACKcycle

Interrupts, 1-2, 1-6, 4-67 to 4-73
autovectored, 2-6, 2-8 to 2-10, 3-2
KAV30 source codes, 2—7

pins, 2-13
priority scheme, 2-12 to 2—15

vectored, 2-6 to 2-8

VMEbus, A-2

VMEbusautovectored, 5-16
VMEbus vectored, 5-15
VSB autovectored, 5-16

IPL, 2-12, 3-2
IRQ, 3-2, 4-67
ISR, 2-5, 2-8, 2-9, 3-2
accessing an, 95-2

K
KAV$BUS_BITCLR, 1-5, 4—2 to 4-9, 4-15,
4-21, 4-29, 4-84, 4-91
KAV$BUS_BITSET, 1-5, 4-7, 4-10 to 4-15,
4-21, 4-29, 4-84, 4-91
KAV$BUS_READ, 1-5, 4-7, 4-15, 4-16 to
4-22, 4-23 to 4-29, 4-84, 4-91, 5-3
KAV$BUS_WRITE, 1-5, 3-23, 4-7, 4-15,
4-21, 4-23, 4-28, 4-84, 4-91, 5-3
KAV$CHECK_BATTERY, 1-5, 4-30 to 4-33
KAV$CLR_AST, 1-5, 3-2, 3-3, 4-34 to
4-36, 4-37, 4-40, 4-99, 4-126
KAV$DEF_AST, 1-5, 3-2, 4-34, 4-36, 4-37
to 4-40, 4-96, 4-99, 4-122, 4-126
KAV$FIFO_READ, 1-5, 3-9, 3-23, 4-41 to
4-45, 4-50, 4-77, 4-83
KAV$FIFO_WRITE, 1-5, 3-9, 4-44, 4-46 to
4-50, 4-77, 4-83

KAV$GATHER_KAV_ERRORLOG, 1-5,
4-51 to 4-57
KAV$INT_VME, 1-6, 4-67 to 4-73, 4-155
KAV$IN_MAP, 1-5, 3-14, 4-58 to 4-66,
4-149, 5-14
KAV$K_ALLOW_VME_IRQ, 4—153, 4-154
KAV$K_ALL_ERR, 4-53
KAV$K_ALR_DOM, 4-109, 4110
KAV$K_ALR_HOUR, 4—109
KAV$K_ALR_MINUTE, 4-109
KAV$K_ALRMONTH, 4-110
KAV$K_ALR_SECOND, 4-109
KAV$K_AUTO_VME_IRQ, 4-153, 4-154
KAV$K_BBR_READ, 4-119
KAV$K_BBR_WRITE, 4-119
KAV$K_BYTE, 4-5, 4-13, 4-19, 4-26
KAV$K_CLEAR_ERR, 4-53
KAV$K_CTMRO, 4-136
KAV$K_CTMR1, 4-136
KAV$K_CTMR2, 4-136
KAV$K_CTMR3, 4-136
KAV$K_CTMR4, 4-136
KAV$K_DISABLE_VSB_IRQ, 4—153
KAV$K_ENABLE_VSB_IRQ, 4-153
KAV$K_FIFO_0, 449, 4~76, 4-82
KAV$K_FIFO_1, 4—49, 4—76, 4-82
KAV$K_FIFO_2, 449, 4-76, 4-82
KAV$K_FIFO_3, 4-49, 4—76, 4-82
KAV$K_INIT_RD_POINTER, 4-53
KAV$K_LCL_TO, 4-136
KAV$K_LONGWORD, 4-5, 4-13, 4-16,
4-19, 4-20, 4-23, 4-26, 4-27
KAV$K_MASTER_ERR, 4-53
KAV$K_PER_100MS, 4-109
KAV$K_PER_10MS, 4-109
KAV$K_PER_10SEC, 4—109
KAV$K_PER_1MS, 4-109
KAV$K_PER_1SEC, 4-109
KAV$K_PER_60SEC, 4—109
KAV$K_RD, 4-68, 4-71, 4—72
KAV$K_RD_A24ROTARY, 4-153, 4-155
KAV$K_RD_VSB_SLOT, 4-153, 4-155
KAV$K_RTC_1000MS, 4—109
KAV$K_RTC_100MS, 4-109

Index—3

KAV$K_RTC_100NS, 4-109
KAV$K_RTC_10MS, 4-109
KAV$K_RTC_1MS, 4-109
KAV$K_RTC_400NS, 4-109
KAV$K_RTC_93US, 4-109
KAV$K_SET_A32_BASE, 4-153, 4-155
KAV$K_SET_RTC_TIME, 4-129
KAV$K_SET_VAX_TIME, 4-129
KAV$K_SLAVE_ERR, 4-53
KAV$K_SUPER_16, 4-89
KAV$K_SUPER_24, 4-89
KAV$K_SUPER_32, 4-89
KAV$K_USER_16, 4-89
KAV$K_USER_24, 4-89
KAV$K_USER_32, 4-89
KAV$K_VME_INT_CLR, 4-71, 4-72
KAV$K_VME_REQ_INT, 4-71
KAV$K_VME_SYSFAIL, 2-5
KAV$K_WDOG, 4-136
KAV$K_WORD, 4-5, 4-13, 4-19, 4-26
KAV$LIFO_WIRTE, 1-6
KAV$LIFO_WRITE, 3-9, 4-44, 4-50, 4-74
to 4-77, 4-83
KAV$M_ALARM, 4-106
KAV$M_CSR, 4-62, 4-63, 4-148
KAV$M_FIFO_ACCESS, 3-23, 4-16, 4-19,
4—20, 4-23, 4-26, 4-27
KAV$M_FIFO_EMPTY, 4-81
KAV$M_FIFO_FULL, 4-81
KAV$M_FIFO_NOT_EMPTY, 4-81
KAV$M_IN, 4-148
KAV$M_LOAD_TMR_CNT, 4-105, 4-135
KAV$M_LOCMON_IPLI15, 4-63
KAV$M_LOCMON_IPL16, 4-63
KAV$M_LOCMON_IPL17, 4-63
KAV$M_MEMORY, 4-63, 4-148
KAV$M_MODE_0_SWAP, 4-63, 4-90
KAV$M_MODE_2_SWAP, 4-63, 4-90
KAV$M_MODE_3_SWAP, 4-63, 4-90
KAV$M_NO_RETRY, 4-2, 4-10, 4-90
KAV$M_OUT, 4-148
KAV$M_PERIODIC, 4-106
KAV$M_READ_ALARM, 4-106
KAV$M_READ_CALENDAR, 4-107

index—4

KAV$M_READRTCRAM, 4-107
KAV$M_READTMR_CNT, 4-106, 4-135
KAV$M_REPEAT, 4-122, 4-125
KAV$M_REPEAT_TMR, 4—136
KAV$M_RESETFIFO, 4-81
KAV$M_RESET_TMR, 4-106, 4-136
KAV$M_RTC_12HOUR, 4—100, 4-107,
4-129
KAV$M_RTC_24HOUR, 4-100, 4-107,
4-129
KAV$M_RTC_HOLD_TMR, 4—108
KAV$M_RTC_READTIMESAVE, 4—107
KAV$M_RTC_RESTARTTMR, 4-108
KAV$M_RTC_TMR_0, 4-105
KAV$M_RTC_TMR_1, 4-105
KAV$M_STARTTMR, 4-105, 4~135
KAV$M_STOP_TMR, 4-106
KAV$M_VME, 4-90
KAV$M_VSB, 4-90
KAV$M_WRITE_ALARM, 4-107
KAV$M_WRITE_CALENDAR, 4-107
KAV$M_WRITE_RTCRAM, 4-108
KAV$M_WRITE_TIMESAVE, 4-107
KAV$M_WRT_PROT, 4-63, 4-90
KAV$NOTIFY_FIFO, 1-6, 4~44, 4-50, 4-77,
4-78 to 4-83
KAV$OUT_MAP, 1-6, 3-11, 4-5, 4-13,
4-21, 4-29, 4-84 to 4-95, 4-149, 5-2,
5-14, 5-20
KAV$QUE_AST, 1-6, 3-2, 4-36, 4-37, 440,
4-96 to 4-99, 4-126
KAV$RTC, 1-6, 3-7, 4-130
KAV$RW_BBRAM, 1-6, 3-10, 4-116 to
4-121
KAV$SET_AST, 1-6, 2-5, 3-2, 3-3, 4-34,
4-36, 4-37, 4-40, 4-96, 4-99, 4-122 to
4-126
KAV$SET_CLOCK, 1-6, 4-127 to 4-130
KAV$TIMERS, 1-6, 2-5, 3-5, 3-6, 4-131 to
4-143
KAV$UNMAP, 1-6, 4-58, 4-64, 4-84, 4-91,
4-144 to 4-149
KAV$VME_SETUP, 1-6, 3-16, 4-68, 4-73,
4-150 to 4-155, 5-15

KAV30
initial configuration, A—1 to A—2
KAV30 applications
coding, 5-3 to 5-12
compiling, 5-12
debugging, 5-20 to 5-21
designing, 5—1 to 5-3
developing, 5-1 to 5-25
including SCSI devices, 5-23 to 5-25
linking, 5-12

Mode 2 swapping, 3-21
Mode 3 swapping, 3-21
Modes
kernel, 3-2
user, 3-2
Mutex, 5-3

KAV30 hardware,

1-1 to 1-2

Not fair mode, 2—2
Not hidden mode, 2-2

KAV30 software,

1-1, 1—4 to 1-6

configuration, A-—1l

configuration, A-—2
KAV30 system image
building, 5-13 to 5-14
loading, 5-20
running, 5-20

Kernel, 1-4
Kernel mode, 3-2

L
Last chance handler, 5-2
Last-in/first-out buffers
See LIFO buffers
LIFO buffers, 1-6, 3-9, 4-23, 4-27, 4-28
LIFO mode, 4—74

Linking
KAV30 applications, 5—12

Little-endian, 3—18, 4—58, 4-84
Local bus
timeout, A-—2
Local bus timer, 3-—5, 3-6, 4-131
Location monitor, 4-58, 4-62
LOCK, 2-3

Master, 2-5, 3-10

VMEbus, 2-1 to 2-2, 5-17
VSB, 2-3, 5-17
Mode 0 swapping, 3-19
Mode 1 swapping, 3-19

Parity errors, 2-6

PC, 5-2
PCB, 3-4
PCB$A_ASTBLK, 3-4
PCB$A_ASTFLK, 3-4
Ports
auxiliary, 1-2, A-1
console, 1-2
serial line, 1-2, 2-14, A-1
POWER_FAILsignal, A-1
Prescaler, 3—5
Prioritized arbitration, 2-3

Priority mode, A-2

Process Control Block
See PCB
Producer, 3-9

Program Counter
See PC

R
Read-modify-write, 2-2, 2—3

Read-modify-write cycles, 4—2, 4-10
Real-time clock, 4—127 to 4-130
Release-on-request
See ROR
Release-on-request mode
ROR mode
Release-when-done
See RWD

Index—5

RESETsignal, A-1

Reset/halt switch, 2—14

Retry count, 5—20
ROR, 2-2

ROR mode, A-2
Round-robin arbitration, 2-3

RTC/begin, 4—100
RTC/end, 4—115

rtVAX 300, 1-1, 5-14

Ethernet controller, A—1
timer, 2-15

RWD, 2-2

S
SO space, 4-2, 4-5, 4-10, 4-13, 4-16, 4-23,
427
Scatter-gather map
See SGM
SCB, 2-8, 2-9, 3-2
SCSI bus, A-1
SCSIclass driver
building, 5-23 to 5-25
SCSI class drivers
developing, 5-22 to 5-23
SCSI controller, 1-2, 2-5
SCSI ID, 5-23, A-2
Second Generation Ethernet Controller
See SGEC
Serial line ports, 1-2, 2-14
SGEC, 5-14
SGM, 1-1, 3-10 to 3-21, 4-2, 4-10, 4-16,
4-23, 4-58, 4-84, 4-144 to 4-149, A-2
byte swapping, 3-18 to 3-21
incoming, 3-14 to 3-18

outgoing, 3-10 to 3-13
Shared memory pages, 3-21
Signal calls, 5-3
Slave, 3-10
VMEbus, 2-2 to 2-38, 2-4, 5-19
Small computer systems interface controller
See SCSI controller
Stack, 5-2

Index—6

SYSFAIL signal, 2-5
SYSRESETsignal, 2-4
SYSTEM, 2-3, 4-89
System clock, 5-17
System Control Block
See SCB
System failure, 5-2
System image, 5-13
System Parameter 1, 5—14 to 5-17

System Parameter 2, 5-14, 5-18 to 5-20

System RAM, 1-1, 2-2
parity errors, 2-6
System random-access memory
See System RAM
System services, 1-5 to 1-6
System virtual address space
See SO space

7
Target system, 1-1, 1-3
TERMPWRsignal, A-1
Timer
interval, 3-5
Timers, 3—5 to 3-6

prescaler, 3-5
Trigger boot, 2-14

U
User mode, 3-2

User read-only memory
See User ROM
User ROM, 1-1, A-1

V
VAX
ERR signal, 2-9
HALTsignal, A-1
POWER_FAIL signal, A-1
VAX Ada, 1-4
coding guidelines, 5—4 to 5-7

VAX C, 1-2
coding guidelines, 5—7 to 5-8
VAX FORTRAN, 1-2
coding guidelines, 5-8
VAXELN
status code, 5-2
system time, A-—2

VMEbus(cont'd)
interrupt requester, 2-10 to 2-12
interrupts, 1-6, A-2
master, 2-1 to 2—2, 5-17, A-2

reading from, 4—16 to 4-22

reset register, 2—2

RESETsignal, A-1

VAXELN Ada, 1-2
VAXELN applications
building, 1-1
debugging, 1-1
developing, 1-1
down-line loading, 1-1

retry count, 5—20
slave, 2-2 to 2—3, 2-4, 5-19

VAXELN Debugger, 1-2, 5-20
VAXELN kernel, 1-2

utility bus signals, 2-4 to 2-5
vectored interrupts, 5-15
writing to, 4-2 to 4-9, 4-10 to 4-15, 4-23

running,

standby power supply, 3-7
SYSFAIL signal, 2-5
SYSRESETsignal, 2-4
system clock, 2—4

timeout, A-—2

1-1

VAXELN Pascal,

1-2

coding guidelines, 5—9 to 5-12

VAXELN System Builder,

1—2, 5-13, 5-14

invoking, 5-13
VAXELN system time, 4-127 to 4-130
VAXELN Toolkit, 1-1, 1-2 to 1-4
VDAD device driver, D-1

Vectored interrupts
VMEbus, 5-15
VMEsubsystem bus
See VSB
VMEbus, 1-1, 1-5

VMS linker, 5-12

VSB, 1-1, 1-5

accessing, 5-1 to 5-3

address spaces, 2-3
ALTERNATE, 2-3, 4-89
arbiter, 1-2, 2—4, 5-17
autovectored interrupts, 5-16

A24 base slave address, A-1
A24 slave, 5-17, A-2
A382 base slave address, A-2

A382 slave, 5-17, 5-19, A-2

accessing, 5-1 to 5—3
ACFAIL signal, 2-5, 2-14, A-1

arbiter, 1-2, 2-3 to 2-4, 5-18, A-1, A-2
autovectored interrupts, 5-16, A-2

BR lines, 2-1
BR3 line, A-2

bus request,

1-2, 5-17, A-2

configuring, 4—150, 5-14 to 5-20
I/O, 2-3, 4-89

interrupt handler, 1-2, 2-12
interrupt request, 1-2
interrupts, 1-6

LOCKsignal, 2-3

master, 2-3, 5-17, A-2

reading from, 4—16 to 4—22
retry count, 5-20

bus request, 1-2, A-2
Bus Request lines, 2-1
configuring, 4-150, 5-14 to 5—20
deadlock, 2-4
global reset register, 2-5
interrupt handler, 1—2, 2-6 to 2-10
interrupt request,

to 4—29

VMEbusbus request, 5-18
VMEbusinterrupt requester, 4—150
VMEbusinterrupts, 1-2

SYSTEM, 2-3, 4-89

writing to, 4-2 to 4-9, 4-10 to 4-15, 4-23

to 4-29
VSB interrupt requester, 4—150
VSB interrupts, 1-2

1-2

Index—7

W
Watchdog timer, 1-2, 3-5, 3-6, 4-131

index-—8

Reader’s Comments

KAV30 Programmer’s Reference Information
AA-PEYCA-TE

Please use this postage-paid form to comment on this manual. If you require a written
reply to a software problem andare eligible to receive one under Software Performance
Report (SPR) service, submit your comments on an SPR form.
Thank you for your assistance.

I rate this manual’s:

Excellent

Good

Fair

Poor

Accuracy (software works as manual says)
Completeness (enough information)
Clarity (easy to understand)
Organization (structure of subject matter)
Figures (useful)

{J
LI
CJ
LJ
CI

L
LJ
LJ
LJ

O
CJ
O
LJ
C]

CL]
UJ
CO
LI
LC]

Index (ability to find topic)
Page layout (easy to find information)

LJ
LI

LJ
L

LJ
CO

J
C

Examples(useful)

I would like to see more/less
WhatI like best about this manual is
WhatI like least about this manualis

I found the following errors in this manual:
Page
Description

Additional comments or suggestions to improve this manual:

I am using Version
Name/Title

of the software this manual describes.
Dept.

Company

Date

Mailing Address
Phone

—-—-——

Do Not Tear - Fold Here and Tape

—-—-—--—-—-------3--- 7-3-3 Or”

TM
Au 1-1X

STAMP
HERE

DIGITAL EQUIPMENT CORPORATION
Corporate User Information Products
ZKO1-—3/J35
110 SPIT BROOK RD
NASHUA, NH 03062-9987

—-—-—-—

DoNot Tear - Fold Here

——-—--—--—-—-----~----3-3- 3-3-3 3-3-3- eee

Reader’s Comments

KAV30 Programmer’s Reference Information
AA-PEYCA-TE

Please use this postage-paid form to comment on this manual. If you require a written
reply to a software problem andareeligible to receive one under Software Performance
Report (SPR) service, submit your comments on an SPR form.
Thank you for your assistance.

I rate this manual’s:
Accuracy (software works as manual says)
Completeness (enough information)
Clarity (easy to understand)
Organization (structure of subject matter)
Figures (useful)
Examples (useful)
Index (ability to find topic)
Page layout (easy to find information)

Excellent

Good

Fair

Poor

LJ
O
LJ
LI
LI
LJ
L
LO

LJ
OO
LJ
LJ
LJ
LJ
LI
LI

LJ
LJ
OO
LJ
LJ
LJ
LJ
LJ

LJ
LJ
CI
LJ
LJ
L
LJ
LJ

I would like to see more/less
WhatI like best about this manual is
WhatI like least about this manual is

I found the following errors in this manual:
Page
Description

Additional comments or suggestions to improve this manual:

I am using Version
Name/Title

of the software this manual describes.
Dept.

Company

——
Date

Mailing Address
Phone

—-—--—--—

Do Not Tear - Fold Here and Tape

—-—--—----------3-3- 3-3-3 - +

-_---

T™
AFFIX
STAMP
HERE

;

DIGITAL EQUIPMENT CORPORATION
Corporate User Information Products
ZKO1-3/J35
110 SPIT BROOK RD
NASHUA, NH 03062-9987

—--—--—-—

Do Not Tear - Fold Here

-—--—-—-—-—---3- 3-33-33 rrr rrr

fifo}i}tla]!