Tektronix 5312B User manual

Software

Model 5312B

Software Developer’ s Guide V1.0

80370 Rev. B / 7-98

WARRANTY

Hardware

Keithley Instruments, Inc. warrants that, for a period of one (1) year from the date of shipment (3 years for Models 2000, 2001, 2002, and 2010), the Keithley
Hardware product will be free from defects in materials or workmanship. This warranty will be honored provided the defect has not been caused by use of the
Keithley Hardware not in accordance with the instructions for the product. This warranty shall be null and void upon: (1) any modification of Keithley Hard­ware that is made by other than Keithley and not approved in writing by Keithley or (2) operation of the Keithley Hardware outside of the environmental speci­fications therefore.

Upon receiving notification of a defect in the Keithley Hardware during the warranty period, Keithley will, at its option, either repair or replace such Keithley
Hardware. During the first ninety days of the warranty period, Keithley will, at its option, supply the necessary on site labor to return the product to the condi­tion prior to the notification of a defect. Failure to notify Keithley of a defect during the warranty shall relieve Keithley of its obligations and liabilities under
this warranty.

Other Hardware

The portion of the product that is not manufactured by Keithley (Other Hardware) shall not be covered by this w arranty, and Keithley shall have no duty of obli­gation to enforce any manufacturers' warranties on behalf of the customer. On those other manufacturers’ products that Keithley purchases for resale, Keithley
shall have no duty of obligation to enforce any manufacturers’ warranties on behalf of the customer.

Software

Keithley warrants that for a period of one (1) year from date of shipment, the Keithle y produced portion of the software or firmw are (Keithley Software) will con­form in all material respects with the published specifications provided such Keithley Software is used on the product for which it is intended and otherwise in
accordance with the instructions therefore. Keithley does not warrant that operation of the Keithley Softw are will be uninterrupted or error-free and/or that the
Keithley Software will be adequate for the customer's intended application and/or use. This warranty shall be null and v oid upon an y modification of the K eithle y
Software that is made by other than Keithley and not approved in writing by Keithley.

If Keithley receiv es notification of a K eithle y Software nonconformity that is co v ered by this warranty during the w arranty period, K eithle y will review the con­ditions described in such notice. Such notice must state the published specification(s) to which the Keithley Software fails to conform and the manner in which
the Keithley Software fails to conform to such published specification(s) with sufficient specificity to permit K eithle y to correct such nonconformity. If Keithley
determines that the Keithley Software does not conform with the published specifications, Keithley will, at its option, provide either the programming services
necessary to correct such nonconformity or develop a program change to bypass such nonconformity in the Keithley Software. Failure to notify Keithley of a
nonconformity during the warranty shall relieve Keithley of its obligations and liabilities under this warranty.

Other Software

OEM software that is not produced by Keithley (Other Software) shall not be covered by this w arranty, and Keithley shall have no duty or obligation to enforce
any OEM's warranties on behalf of the customer.

Other Items

Keithley warrants the following items for 90 days from the date of shipment: probes, cables, rechar geable batteries, diskettes, and documentation.

Items not Covered under Warranty

This warranty does not apply to fuses, non-rechargeable batteries, damage from battery leakage, or problems arising from normal wear or failure to follow
instructions.

Limitation of Warranty

This warranty does not apply to defects resulting from product modification made by Purchaser without Keithley's express written consent, or by misuse of any
product or part.

Disclaimer of Warranties

EXCEPT FOR THE EXPRESS WARRANTIES ABOVE KEITHLEY DISCLAIMS ALL OTHER WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
WITHOUT LIMIT ATION, ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. KEITHLEY DIS­CLAIMS ALL WARRANTIES WITH RESPECT TO THE OTHER HARDWARE AND OTHER SOFTWARE.

Limitation of Liability

KEITHLEY INSTRUMENTS SHALL IN NO EVENT, REGARDLESS OF CAUSE, ASSUME RESPONSIBILITY FOR OR BE LIABLE FOR: (1) ECO­NOMICAL, INCIDENTAL, CONSEQUENTIAL, INDIRECT, SPECIAL, PUNITIVE OR EXEMPLARY DAMAGES, WHETHER CLAIMED UNDER
CONTRACT, TORT OR ANY OTHER LEGAL THEORY, (2) LOSS OF OR DAMAGE TO THE CUSTOMER'S DATA OR PROGRAMMING, OR (3) PEN­AL TIES OR PENALTY CLAUSES OF ANY DESCRIPTION OR INDEMNIFICA TION OF THE CUST OMER OR OTHERS FOR COSTS, DAMAGES, OR
EXPENSES RELATED TO THE GOODS OR SERVICES PROVIDED UNDER THIS WARRANTY.

Keithley Instruments, Inc. • 28775 Aurora Road • Cleveland, OH 44139 • 440-248-0400 • Fax: [phone] • http://www.keithley.com

CHINA: Keithley Instruments China • Yuan Chen Xin Building, Room 705 • 12 Yumin Road, Dewai, Madian • Beijing 100029 • 8610-62022886 • Fax: [phone]
FRANCE: Keithley Instruments SARL • BP 60 • 3 Allée des Garays • 91122 Palaiseau Cédex • 33-1-60-11-51-55 • Fax: [phone]
GERMANY: Keithley Instruments GmbH • Landsberger Strasse 65 • D-82110 Germering, Munich • 49-89-8493070 • Fax: [phone]
GREAT BRITAIN: Keithley Instruments, Ltd. • The Minster • 58 Portman Road • Reading, Berkshire RG30 1EA • 44-1189-596469 • Fax: [phone]
ITALY: Keithley Instruments SRL • Viale S. Gimignano 38 • 20146 Milano • 39-2-48303008 • Fax: [phone]
NETHERLANDS: Keithley Instruments BV • Avelingen West 49 • 4202 MS Gorinchem • 31-(0)183-635333 • Fax: [phone]
SWITZERLAND: Keithley Instruments SA • Kriesbachstrasse 4 • 8600 Dübendorf • 41-1-8219444 • Fax: [phone]
TAIWAN: Keithley Instruments Taiwan • 1FL., 85 Po Ai Street • Hsinchu, Taiwan • 886-3-572-9077 • Fax: [phone]

Model 5312B

V1

Software Developer’s Guide

0

.

©1996, Keithley Instruments, Inc.

All rights reserved.

Cleveland, Ohio, U.S.A.

Second Printing, July 1998

Document Number: 80370 Rev. B

Manual Print History

The print history shown below lists the printing dates of all Revisions and Addenda created for this manual. The Revision
Level letter increases alphabetically as the manual undergoes subsequent updates. Addenda, which are released between Revi­sions, contain important change information that the user should incorporate immediately into the manual. Addenda are num­bered sequentially. When a new Revision is created, all Addenda associated with the previous Revision of the manual are
incorporated into the new Revision of the manual. Each new Revision includes a revised copy of this print history page.

Revision A (Document Number 80370)...............................................................................................August 1996

Revision B (Document Number 80370)....................................................................................................July 1998

All Keithley product names are trademarks or registered trademarks of Keithley Instruments, Inc.
Other brand and product names are trademarks or registered trademarks of their respective holders.

About this manual

Quality control

Keithley Instruments manufactures quality and versatile products, and we want our documenta­tion to reflect that same quality. We take great pains to publish manuals that are informative and
well organized. We also strive to make our documentation easy to understand for the novice as
well as the expert.

If you have comments or suggestions about how to mak e this (or other) manuals easier to under­stand, or if you find an error or an omission, please fill out and mail the reader response card at
the end of this manual (postage is prepaid).

Conventions

Procedural

Keithley Instruments uses various conventions throughout this manual. You should become
familiar with these conventions as they are used to draw attention to items of importance and
items that will generally assist you in understanding a particular area.

WARNING

CAUTION

NOTE

When referring to pin numbering, pin 1 is always associated with a square solder pad on the
actual component footprint.

A warning is used to indicate that an action must be done with great
care. Otherwise, personal injury may result.

A caution is used to indicate that an action may cause minor equip­ment damage or the loss of data if not performed carefully.

A note is used to indicate important information needed to perform an
action or information that is nice-to-know.

Notational

A forward slash (/) preceding a signal name denotes an active LOW signal. This is a standard
Intel convention.

Caret brackets (<>) denote keystrokes. For instance <Enter> represents carriage-return-with­line-feed keystroke, and <Esc> represents an escape keystroke.

Driver routine declarations are shown for C and BASIC (where applicable).
Hungarian notation is used for software parameters. In other words, the parameter type is

denoted by a one or two letter lower case prefix:

c character, signed or unsigned
s short integer, signed

w short integer, unsigned

l long integer, signed

dw long integer, unsigned

For example, wBoardAddr would be an unsigned short integer parameter.

An additional p prefix before the type prefix indicates that the parameter is being passed by ref­erence instead of by value. (A pointer to the variable is being passed instead of the variable
itself).

For example, pwErr would be an unsigned short integer parameter passed by reference.
This notation is also used in BASIC although no distinction between signed and unsigned vari-

ables exists.
In BASIC, all parameters also have a type suffix:

$ character, signed or unsigned
% integer, signed or unsigned
& long integer, signed or unsigned

Routine names are printed in bold font when they appear outside of function declarations, e.g.,
ReadStatus.

Parameter names are printed in italics when they appear outside of function declarations, e.g.
sControls.

Constants are defined with all caps, e.g., ALL_AXES. Underscores {_} must be replaced by
periods {.} for use with BASIC.

Combinational logic and hexadecimal notation is in C convention in many cases. For example,
the hexadecimal number 7Ch is shown as 0x7C.

C relational operators for OR and AND functions — “| |” and “&&” — are used to minimize the
confusion associated with grammar.

Table of Contents

1 Programming Overview

Installing the 5312 software ............................................................................................................................... 1-2

Compiling and linking ....................................................................................................................................... 1-2

Microsoft C or Microsoft QuickC .............................................................................................................. 1-2

Borland or Turbo C/C++ ............................................................................................................................ 1-3

Microsoft QuickBASIC ............................................................................................................................. 1-3

Borland Turbo Pascal ................................................................................................................................. 1-4

Programming fundamentals ............................................................................................................................... 1-4

2 Example Programs

Program in C ...................................................................................................................................................... 2-2

Program in BASIC ............................................................................................................................................. 2-4

Program in Pascal ............................................................................................................................................... 2-5

3 Interrupt Handling

Introduction ........................................................................................................................................................ 3-2

Enabling interrupts ..................................................................................................................................... 3-2

Interrupts in C or Pascal ..................................................................................................................................... 3-2

Interrupts in BASIC ........................................................................................................................................... 3-2

General notes on using interrupts ....................................................................................................................... 3-3

4 Alphabetical Routine Summary

Introduction ........................................................................................................................................................ 4-2

Routines ............................................................................................................................................................. 4-2

i

A Driver Routine Descriptions

Notational conventions ...................................................................................................................................... A-3

te5312DisableIRQ ............................................................................................................................................. A-3

Disable interrupt request ............................................................................................................................ A-3

te5312EnableIRQ .............................................................................................................................................. A-4

Enable interrupt request ............................................................................................................................. A-4

te5312IndexAlertOff ......................................................................................................................................... A-4

Disable index interrupt .............................................................................................................................. A-4

te5312IndexAlertOn .......................................................................................................................................... A-5

Enable index interrupt ............................................................................................................................... A-5

te5312InitBoard ................................................................................................................................................. A-5

Initialize board ........................................................................................................................................... A-5

te5312InitEncoder ............................................................................................................................................. A-6

Initialize encoder ....................................................................................................................................... A-6

te5312InitSw ...................................................................................................................................................... A-8

Initialize software ...................................................................................................................................... A-8

te5312InterruptHooks ........................................................................................................................................ A-8

Install interrupt hooks ................................................................................................................................ A-8

te5312LoadCntr ................................................................................................................................................. A-9

Load counter .............................................................................................................................................. A-9

te5312LoadPr .................................................................................................................................................... A-9

Load preset register ................................................................................................................................... A-9

te5312ReadCntr ............................................................................................................................................... A-10

Read counter ............................................................................................................................................ A-10

te5312ReadOL ................................................................................................................................................. A-10

Read output latch ..................................................................................................................................... A-10

te5312ReadSts ................................................................................................................................................. A-10

Read status ............................................................................................................................................... A-10

te5312WrapAroundAlertOff ........................................................................................................................... A-11

Disable borrow/carry interrupt ................................................................................................................ A-11

te5312WrapAroundAlertOn ............................................................................................................................ A-12

Enable borrow/carry interrupt ................................................................................................................. A-12

te5312WriteCmd ............................................................................................................................................. A-12

Write command ....................................................................................................................................... A-12

B Demonstration Program
C Visual BASIC Demonstration Program

Overview ........................................................................................................................................................... C-2

Software installation .......................................................................................................................................... C-2

Windows 3.1 .............................................................................................................................................. C-2

Windows 95 ............................................................................................................................................... C-2

User’s guide ....................................................................................................................................................... C-3

Demo modes .............................................................................................................................................. C-4

Developer’s guide .............................................................................................................................................. C-5

Form modules ............................................................................................................................................ C-6

Code modules ............................................................................................................................................ C-7

D LSI Chip Applications Note

Introduction ....................................................................................................................................................... D-2

Problem definition ..................................................................................................................................... D-2

Problem solution ........................................................................................................................................ D-2

ii

List of Illustrations

A Driver Routine Descriptions

Figure A-1 Read status .............................................................................................................................................. A-11

B Demonstration Program

Figure B-1 Input parameters screen ............................................................................................................................. B-2

Figure B-2 Help screen ................................................................................................................................................ B-3

C Visual BASIC Demonstration Program

Figure C-1 Main user menu ......................................................................................................................................... C-3

Figure C-2 Main user menu with demo modes pulled down ...................................................................................... C-4

Figure C-3 Quadrature mode dialogue box ................................................................................................................. C-5

Figure C-4 Primary form module ................................................................................................................................ C-6

Figure C-5 Template for form modules enabling demo-mode dialogue boxes ........................................................... C-7

D LSI Chip Application Note

Figure D-1 LSI chipset counter problem ..................................................................................................................... D-2

iii

List of Tables

4 Alphabetical Routine Summary

Table 4-1 Notational conventions .............................................................................................................................. 4-2

v

1

Programming Overview

1-2 Programming Overview Model 5312B Software Developer’s Guide

Installing the 5312 software

The 5312 driver includes the batch file, INSTALL.BAT, to install the software. The batch file
takes one argument, which is the path where you will install the software. For e xample, to install
the software on the C drive into a subdirectory called 5312, enter on the command line:

install c:\5312

Use the same path for the installation of all drivers. This puts all include files, examples, etc.,
together. This is especially important when using QuickB ASIC, where you will ha ve to combine
many libraries into a quick library.

A BASIC subdirectory, a C subdirectory, and a Pascal subdirectory will be created off of the
directory you specify, and you may delete any unneeded subdirectories to save disk space.

Compiling and linking

The following paragraphs describe how to compile a program using the 5312 dri v er with the v ar ­ious supported compilers. It is assumed the source file is named DEMO.C for C, DEMO.BAS
for BASIC, and DEMO.PAS for Pascal.

Microsoft C or Microsoft QuickC

To compile and link on the command line, enter the following:

cl /Ax /Gs demo.c te5312x.lib
qcl /Ax /Gs demo.c te5312x.lib

where x is:

s small model,
m medium model,
c compact model,
l large model

Turn stack checking off with the /Gs switch (option) if you use interrupts. For CodeView com­patibility, include the /Zi switch.

To use the 5312 driver in the QuickC environment, perform the following steps:

1. In the Make menu, select the Set Program List option.

2. After naming the Make file, select Edit Program List, and enter the names of the source file
(DEMO.C) and the appropriate library (e.g. te5312s.lib for small model).

3. In the Options/Make menu, select the Compiler Flags option and set the appropriate memory
model (this model must match the library in the make list). If you use interrupts, turn stack­checking off.

(C)
(QuickC)

Model 5312B Software Developer’s Guide Programming Overview 1-3

Borland or T urbo C/C++

To compile and link on the command line, enter the following:

tcc -m
bcc -m

where x is:

s small model
m medium model
c compact model

l large model
For Turbo Debugger compatibility, include the -v option.
To use the 5312 driver in the Borland environment, perform the following steps:

1. In the Project/Open Project menu, type in the name of the project file you want to create.

2. In the Project/Add Item menu, enter the names of the source file (DEMO.C) and the appro-

priate library (e.g. te5312s.lib for small model).

3. In the Options/Compiler/Code Generation menu, set the appropriate memory model (this

model must match the library in the Make list). If you use interrupts, turn stack-checking off.

x

demo.c te5312

x

demo.c te5312

Microsoft QuickBASIC

If you use compiled BASIC exclusively and never program in the QuickBASIC environment,
you can link the library te5312b.lib into your application.

bc demo.bas;

link demo.obj,,,te5312b.lib

x

.lib

x

.lib

(Turbo C)
(Borland C)

To compile and link for CodeView compatibility, enter the following:

bc /Zi demo.bas;

link /CO demo.obj,,,te5312b.lib

If you use the QuickBASIC environment, you first have to run the batch file QLB5312.BAT.
This batch file will need modification, depending on which QuickBASIC version you use. The
necessary modifications are explained by the remarks in the batch file itself.

The batch file creates two files: te5312qb.qlb and te5312qb.lib. Library te5312qb.qlb is a quick
library for use in the QuickBASIC environment and te5312qb.lib is the command line equiva­lent. Therefore, you will develop your program with te5312qb.qlb and then in the final compila­tion, link with te5312qb.lib.

To use the 5312 driver in the QuickBASIC environment, enter the following:

qb demo.bas /lte5312qb.qlb

To compile on the command line:

bc demo.bas;

link demo.obj,,,te5312qb.lib

To compile and link for CodeView compatibility:

bc /Zi demo.bas;

link /CO demo.obj,,,te5312qb.lib

1-4 Programming Overview Model 5312B Software Developer’s Guide

The libraries te5312b.lib and te5312qb.lib are similar but not identical. Library te5312b.lib calls
two routines not contained in the library itself: te5312IndexAlert and te5312WrapAroundAlert.
These two routines must be included in your source code if you need to link te5312b.lib into
application program. The file INTR5312.BAS contains stub versions of these routines that you
can use as a guide, or you can compile and link the file itself into the application. Since
te5312b.lib has unresolved references, it cannot be converted into a quick library.

The library te5312qb.lib is created by the batch file by compiling INTR5312.BAS and linking
the resulting object file with te5312b.lib. It has no unresolved references and can be converted
into the quick library te5312qb.qlb. A program developed in the QuickBASIC environment
using te5312qb.qlb can be compiled on the command line and linked with te5312qb.lib without
modifying the source code. See the information on using interrupts with BASIC.

Borland T urbo Pascal

To compile and link on the command line, enter the following:

tpc /$S- demo

If you use interrupts, be sure to turn stack-checking off. Turn off stack-checking by including
/$S on the command line as shown or by including the line {$S-} in the program source code.

To compile for Turbo Debugger compatibility, include the /v option.
To use the 5312 driver in the Turbo Pascal environment, enter the following:

turbo demo

The source file must include the line: uses te5312p;. If you use interrupts, be sure to turn stack
checking off. Turn off stack-checking through the Options/Compiler menu or by including the
line {$S-} in the program.

Programming fundamentals

To quickly write simple applications for the 5312, follow the structure of the example programs
provided in section 2. For C, include the file te5312.h. For B ASIC, include the TE5312.B AS file.
For Pascal, always specify the te5312p unit.

Call te5312InitSw first to initialize the software. Then call te5312InitBoard once for ev ery 5312
board in the system. To use the other driver routines, you must be familiar with the concept of
board, axis, and global numbers.

Each board in the system will be sequentially assigned a number from 0 to 5, called the board
number, used to identify the board in calls to other routines. Each time te5312InitBoard is
called, another board number is assigned. If only one board is installed in the system, calling
te5312InitBoard once assigns a board number of zero.

Likewise, each axis in the system will be sequentially assigned an axis number from 0 to 23,
used to identify a particular axis in calls to other routines. Each time te5312InitBoard is called,
three more axis numbers are assigned.

Each board is also assigned a global number from –1 down to a possible –6. Global numbers can
be used in place of axis numbers in routines that write to an encoder. In these cases all the encod­ers on the corresponding board will be written at the same time.

2

Example Programs

2-2 Example Programs Model 5312B Software Developer’s Guide

Program in C

#include "te5312.h"
#include <stdio.h>
#include <conio.h>

#define BOARD 0
#define AXIS_A 0
#define AXIS_B 1
#define GLOBAL -1

// interrupt hook prototypes
static void te5312IndexAlert(short *psAxisNum);
static void te5312WrapAroundAlert(short *psAxisNum);

// interrupt counters
static unsigned short wCarryA, wCarryB;
static unsigned short wIndexA, wIndexB;

void main()
{
unsigned short wBoardAddr;
long lCntA, lCntB;
short sStatA, sStatB;
short sIRQNum;

// get the address
printf("\nEnter the base address the 5312 is strapped "
"at in hexadecimal - ");
scanf("%x", &wBoardAddr);

// get the IRQ number
do{
printf("\nEnter the interrupt request line used (2 to 7) - ");
scanf("%u", &sIRQNum);
}while((sIRQNum < 2) || (sIRQNum > 7));

// initialize the software
te5312InitSw();

// initialize the board (assume the board has at least two axes)
te5312InitBoard(wBoardAddr, 2);

// zero the counters
te5312LoadCntr(GLOBAL, 0L);

// initialize interrupts
te5312InterruptHooks(te5312WrapAroundAlert, te5312IndexAlert);
te5312EnableIRQ(BOARD, sIRQNum);
te5312IndexAlertOn(GLOBAL);
te5312WrapAroundAlertOn(GLOBAL);

// print column headers
printf("\nPress any key to exit\n\n"
" Axis A "