E U R O P E A N S O U T H E R N O B S E R V A T O R Y
Organisation Européenne pour des Recherches Astronomiques dans l’Hémisphère Austral
Europäische Organisation für astronomische Forschung in der südlichen Hemisphäre
VERY LARGE TELESCOPE
Prepared.....................................................................................................
Name Date Signature
Approved...................................................................................................
Name Date Signature
Released .....................................................................................................
Name Date Signature
Doc.No. VLT-MAN-ESO-15400-1375
Issue 2
Date 2007/08/14
VLT PROGRAMME * TELEPHONE: +49 89 32006-0 * FAX: +49 89 320 2362
VLTI Software
---
VMIVME-5576 Reflective Memory Driver
User Manual
M. Peron
B.Gustafsson 10.03.2001
G. Chiozzi
2 VMIVME-5576 Driver User Manual - 2 VLT-MAN-ESO-15400-1375
VMIVME-5576 Driver User Manual - 2 VLT-MAN-ESO-15400-1375 3
Change Record
Issue/Rev. Date Section/Page affected Reason/Initiation/Document/Remarks
1.0 08.07.1998 All First Issue
1.1 10.03.2001 Page 7,45 Added MVME2604 CPU
2 2007/08/14 All R. Frahm: Unified User Manual for VMIVME-
5576 and PMC-5565 Reflective Memory board.
4 VMIVME-5576 Driver User Manual - 2 VLT-MAN-ESO-15400-1375
The information contained in this manual is intended to be used in the ESO
VLT project by ESO and authorized external contractors only.
While every precaution has been taken in the development of the software
and in the preparation of this documentation, ESO assumes no responsibil-
ity for errors or omissions, or for damage resulting from the use of the soft-
ware or of the information contained herein.
VMIVME-5576 Driver User Manual - 1.1 VLT-MAN-ESO-15400-1375 5
T A B L E O F C O N T E N T S
1 INTRODUCTION 7
1.1 Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
1.2 Scope . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
1.3 Applicable Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
1.4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .Reference Documents8
1.5 Abbreviations and Acronyms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
1.6 Usage of Terms. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
1.7 Stylistic Conventions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
1.8 Naming Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
1.9 Problem Reporting/Change Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
2 OVERVIEW 13
2.1 The Hardware . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
2.2 The Drivers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
2.3 The Devices. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
2.4 Device Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
2.5 Interrupts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
2.6 Special Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
2.7 Include files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
3 DRIVER FUNCTIONS 17
3.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
3.2 Driver and Device Installation Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
3.3 Tool Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
3.4 Device Access Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
3.4.1 open . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
3.4.2 close . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
3.4.3 ioctl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
4 DRIVER IOCTL COMMANDS 27
4.1 Access to the User Memory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
4.2 Access to the Register Memory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
4.2.1 Board Control and Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
4.2.2 Node Identification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
4.2.3 Interrupt Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
4.3 Test Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
4.4 Reset Command. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
4.5 Driver-Related Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
4.6 Simulation Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
5 ERROR MESSAGES AND RECOVERY 35
6 CODE EXAMPLES 37
6 VMIVME-5576 Driver User Manual - 1.1 VLT-MAN-ESO-15400-1375
6.1 Reflective Memory Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
6.2 Sending and Receiving Interrupts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
7 DIAGNOSTICS 41
7.1 rmnVersion, rfm2gVersion. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
7.2 rmnDevShow, rfm2gDevShow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
7.3 rmnDevDump (not available for the rfm2g driver) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .41
7.4 rmnMemDump (not available for the rfm2g driver) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
7.5 rmnDevDescrDump, rfm2gDevDescrDump. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
7.6 rmnTestBoard, rfm2gTestBoard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
7.7 rmnPrintError, rfm2gPrintError . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
7.8 rmnPrintCommand, rfm2gPrintCommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
7.9 Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
8 INSTALLATION 47
8.1 Installation Prerequisites. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
8.1.1 Hardware Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
8.1.2 Software Requirements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
8.2 Building the Software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
8.3 Installation Procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
8.4 Installation Verification. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .48
9 REFERENCE 51
9.1 rmnClose(3). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
9.2 rmnDevCreate(3) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
9.3 rmnDrv(3) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
9.4 rmnIoctl(3). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
9.5 rmnOpen(3). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
9.6 rmnTools(1). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .58
VMIVME-5576 Driver User Manual - 2 VLT-MAN-ESO-15400-1375 7
1 INTRODUCTION
1.1 Purpose
This document is the User Manual for the drivers of the VME based VMIVME-5576 and the PMC
based PMC-5565 Reflective Memory boards. Both cards are produced by GE Fanuc Embedded Systems. and have been standardized by ESO for high-speed low-latency data communication among
LCUs, particularly for the VLTI Fast Link, used within the fringe tracking control loop [10].
Please note that the VMIVME-5576 board is no longer available from the manufacturer, nor recommended for new designs. The manufacturer recommends as a replacement the PMC-5565 RMN
board, which is just the successor of the old VME-5576, however with a PMC form factor, using the
PCI bus instead of VME.
For backwards compatibility, two different drivers are provided for the two boards. They differ
slightly in functionality and type of parameters.
The VMIVME-5576 driver (‘rmn”) consists of a module that belongs to the CCS-LCU package. It
contains the interface to be used by higher level software to access the VMIVME-5576 Reflective
Memory Board. The driver name for the PMC-5565 board is called “rfm2g”. They can coexist on one
LCU, allowing the user to integrate both boards into one LCU.
The module name of the VMIVME-5576 driver is rmn (reflective memory network).
The module name of the PMC-5565 driver is rfm2g (reflective memory 2nd generation).
This document provides all the necessary information for the development of applications using either of the two drivers.
The manual assumes that the reader has a good knowledge of UNIX, C-language, the VxWorks operating system and is familiar with VxWorks development environment.
In addition to the Introduction section, this manual contains the following sections:
• User’s Guide - Consists of the chapters 2, 3 and 4. It gives an overview of the driver and
describes its functions and ioctl-commands in detail.
• Error Messages and Recovery - Provides a list of error and diagnostic messages and possible
recovery actions.
• Code Examples - Provides some code templates which show the way to use the driver.
• Diagnostics - Shows the diagnostics facilities of the driver.
• Installation - Describes how to install and configure the driver and how to verify a successfull
installation.
• Reference - Describes all the functions available as man-pages.
1.2 Scope
This manual describes the software module rmn in its version 1.14 and the module rfm2g in version 0.10..
• rmn - VMIVME-5576 Reflective Memory Board Driver
• rfm2g - PMC-5565 Reflective Memory 2nd Generation Driver
8 VMIVME-5576 Driver User Manual - 2 VLT-MAN-ESO-15400-1375
The following hardware and software environment is required to run the software described:
• 2 VMEbus chassis with bus backplanes1 and power supplies
• at least 2 PMC-5565 or VMIVME-5576 Reflective Memory Boards, one inside each chassis
• 2 Motorola MVME167 (VMIVME-5576 only), MVME2604 or MVME-6100 CPU boards, any
version, one inside each chassis
• VxWorks version 5.4 operating system or higher
• software module lculog for internal logging, version 1.11 or later
• software module lcudrv for common driver functions, version 1.36 or later
1.3 Applicable Documents
The following documents, of the exact issue shown, form a part of this document to the extent specified herein. In the event of conflict between the documents referenced herein and the contents of
this document, the contents of this document shall be considered as a superseding requirement.
[1] VLTI Software - VMIVME-5576 Reflective Memory Board Driver Specification
VLT-SPE-ESO-15400-1374, Issue 1.0, 25/08/1997
[2] Local Control Unit Software Specification
VLT-SPE-ESO-17210-0002, Issue 2.2, 26/10/1993
1.4 Reference Documents
The following documents contain additional information and are referenced in the text.
[3] VMIVME-5576 Reflective Memory Board - Instruction Manual
500-005576-000 E, 4/11/1993
VME Microsystems International Corporation
[4] VxWorks Version 5.2 Programmer’s Guide
Part #:DOC-10802-ZD-01, March 1995
Wind River Systems
[5] VxWorks Version 5.2 Reference Manual
Part #:DOC-10870-ND-00, March 1995
Wind River Systems, Mar. 1995
[6] VLT Software Programming Standards
VLT-PRO-ESO-10000-0228, Issue 1.0, 10/03/1993
[7] VLT Software - CCS-LCU/Driver Development Guide and User Manual
VLT-MAN-ESO-17210-0375, Issue 2.2, 11/06/1996
[8] VLT Software - CCS-LCU/Configuration of VLT Standard VME Boards
VLT-MAN-ESO-17210-1358, Issue 1.0, 05/05/1997
[9] VLT Common Software - Installation Manual
VLT-MAN-ESO-17200-0642, Issue 1.8, 31/05/1997
[10] VLTI Fast Link - Technical Report
VLT-TRE-ESO-15400-1373, Issue 1.0, 25/07/1997
[11] PMC-5565 PIORC Product Manual, GE Fanuc Embedded Systems, Revision A, 2006
1. Only P1/J1 backplane, if the board is configured in the A24 address space; both P1/J1 and P2/J2 backplanes if
the board is configured in the A32 address space.
VMIVME-5576 Driver User Manual - 2 VLT-MAN-ESO-15400-1375 9
1.5 Abbreviations and Acronyms
6U VME double height board
A16 VME Short I/O address mode
A24 VME Standard address mode
A32 VME Extended address mode
BERR Bus Error
CCS Central Control Software
CPU Central Processing Unit
CSR Control and Status Register
D08(O) VME 8-bit data transfer at odd addresses
D08(EO) VME 8-bit data transfer at even or odd addresses
D16 VME 16-bit data transfer
D32 VME 32-bit data transfer
DPRAM Dual Port RAM
FIFO First-In First-Out
HW Hardware
ICR Interrupt Control Register
INT Interrupt
ISR Interrupt Service Routine
LCU Local Control Unit
LED Light Emitting Diode
PMC PCI Mezzanine Module
RAM Random Access (read/write) Memory
R/W Read/Write
SW Software
VLT Very Large Telescope
VLTI VLT Interferometer
VLTICS VLTI Control Software
VME Versa Module Eurocard
1.6 Usage of Terms
byte 8 bits value
word 16 bits value
long word 32 bits value
integer 32 bits signed integer value
double 64 bits floating-point value according to IEEE-754
10 VMIVME-5576 Driver User Manual - 2 VLT-MAN-ESO-15400-1375
1.7 Stylistic Conventions
The following styles are used:
bold
in the text, for commands, filenames, prefixes/suffixes as they have to be typed.
italic
in the text, for parts that have to be substituted with the real content before typing.
teletype
for examples.
<name>
in the examples, for parts that have to be substituted with the real content before typing.
bold and italic are also used to highlight words.
1.8 Naming Conventions
This implementation follows the naming conventions as outlined in the VLT Programming Standards [6].
1.9 Problem Reporting/Change Request
In order to:
• report a problem/error encountered using the software and/or the documentation,
• suggest changes in the software or documentation
fill an SPR-form (shown in the following page) and send it with any other additional material that
you think could be helpful, to ESO:
• by mail or fax for the attention of:
VLT/ELE- SOFTWARE GROUP/Software Configuration Control Manager
• by e-mail to: vltsccm@eso.org
Your request will be checked-in the SPR data base and processed according to ESO change control
procedure. The registration number will be communicated to you for further reference and you will
be kept informed of the outcome of your SPR.
VMIVME-5576 Driver User Manual - 2 VLT-MAN-ESO-15400-1375 11
==============================================================================
E. S. O. ---- VERY LARGE TELESCOPE PROJECT ----
-----------------------------------------------------------------------------SOFTWARE PROBLEM REPORT/CHANGE REQUEST FORM DATE: <dd/mm/yy>
-----------------------------------------------------------------------------From:
<contract number>
<consortium name>
<institute name/company name>
<address>
<name of the submitter with its e-mail adress/fax number/phone number>
-----------------------------------------------------------------------------Subject: < module name / document title + version number >
Title: < problem short description >
----------------------------------------------------------------------------- Please mark one of the following categories
_ software error
_ error in the documentation
_ change request
-----------------------------------------------------------------------------Description:
>>>>> Please delete these lines and provide:
>>>>> for software errors:
>>>>> - the description of the anomaly, uncluding outputs,
>>>>> - how to reproduce it,
>>>>> - if existing, the temporary solution,
>>>>> - if known, the reference to where it was specified correctly
>>>>> - if known, the way to fix it.
>>>>>
>>>>> for errors in the documentation:
>>>>> - the exact location of the error (DocNr, issue, page, etc.)
>>>>> - the text that is wrong
>>>>> - if known, to what should it be changed.
>>>>>
>>>>> for change request
>>>>> - the description of what you would like to have
>>>>> - if available, possible implementation hints.
>>>>>
>>>>>
==============================================================================
12 VMIVME-5576 Driver User Manual - 2 VLT-MAN-ESO-15400-1375
VMIVME-5576 Driver User Manual - 2 VLT-MAN-ESO-15400-1375 13
2 OVERVIEW
This manual covers the device-specific part for the PMC-5565 and VMIVME-5576 Reflective Memory Boards. For a general overview about drivers and devices, refer to the Driver Development
Guide [7].
2.1 The Hardware
The PMC-5565 and VMIVME-5576 Reflective Memory Boards provides dual-port memory
(DPRAM) which is replicated and automatically updated in each board connected to the reflective
memory network. The board’s memory can be accessed through standard VME R/W cycles from
the local backplane (VMIVME-5575) or via the PMC connectors on the CPU boards (PMC-5565).
The boards allow also to generate remote interrupts to one or more nodes (network interrupts). These
interrupt signal is used to synchronize two nodes. It may act as a trigger to start a task on a remote
node, or it may implement a protocol for data transfer between two nodes. In this last case the interrupt can be sent to inform the remote node that some data have been updated in the reflective
memory and are ready to be used.
For the VMIVME-5576, the board’s Dual-Port RAM can be accessed either in the VMEbus A24 standard or in the A32 extended address-space, depending on the setting of one on-board jumper, and
supports D8, D16 and D32 data transfer. Depending on the size of the user memory installed on the
board, it spans 256 KB, 512 KB or 1 MB of the VME address space (the first 64 bytes are reserved for
the register memory).
For the PMC-5565, the size of the onboard RAM is either 64MB or 128MB, which is always mapped
into the CPUs A32 space. Since this board is a PMC module, the interface to the Dual-Port RAM via
the PCI-bus is faster compared to the other board.
See the hardware manuals for details [3], [11], or the man pages (man rmn, man rfm2g).
2.2 The Drivers
The drivers implement the functionality of the PMC-5565 and VMIVME-5576 Reflective Memory
Boards, that is it gives the same functionality as the board and does not combine elementary functions to more complex functions. This is left by purpose to the software using the driver in order to
achieve the maximum flexibility.
The driver concept of VxWorks is described in [4].
The rfm2g driver offers the same command set as the rmn driver, but due to hardware changes on
the board some commands have no meaning or require different data types.
2.3 The Devices
The whole board is regarded as one device. As recommended in [7], the device-names are derived
from the module-name “rmn”, i.e. the devices must be named “/rmn0”, “/rmn1”, etc.
For the rfm2g, the devices are called “/rfm2g0”, “/rfm2g1”. Currently, only up to two boards are
supported per CPU. This is due to the fact that only two PMC slots are available on the MVME-6100
CPUs, and only one slot on the MVME-2700 CPUs.
14 VMIVME-5576 Driver User Manual - 2 VLT-MAN-ESO-15400-1375
The driver can control several devices simultaneously, where each device consists of the same type
of hardware, using the same code but with different sets of data for each device. The set of data defining the device and containing the status of the device is called device descriptor table.
2.4 Device Access
The driver conforms to the LCU software specification [2], particularly in the following respects:
• The driver conforms to the VxWorks driver concept, that is it supports the functions open,
close, and ioctl. It also provides the recommended installation functions (see section 4 of this
manual).
• The driver controls the access of the device, provided by the open/close calls giving the
possibilities:
• READONLY
• SHARED
• EXCLUSIVE
• TEST
• There is a possibility to force the release of a channel opened in EXCLUSIVE mode (Free Device
command).
• The driver calls are mutually exclusive, that is the device accessed by a task is protected from
access from any other authorized task until the executing driver call has terminated. They will
be blocked and put on a queue. There is one queue for each device and the processes on the
queue will be scheduled according to their priority. The implementation of the driver uses the
VxWorks mutex semaphore for this functionality and to provide priority inheritance, see reference
[4].
• A task blocked for access of a device has a timeout. An error will be returned upon exceeding
the timeout.
Ioctl commands directly accessing a register do not have any protection from simultaneous access as
the command is executed by an immediate action, that is in one non-interruptable instruction. In
this case there is no need for any protection as no other process can interfere during the action.
2.5 Interrupts
The VMIVME-5576 Reflective Memory Board occupies 4 interrupt-vectors (INT0-3) and can be assigned to one out of seven interrupt-levels. The interrupt-vectors should be chosen in such a way
that they will not conflict with the configuration of the other VLT standard VME boards [8].
The local interrupt INT0 is dedicated to generate an interrupt in the event that the board’s data
transfer capacity is going to be overloaded or a transmission error occurs. If this interrupt is enabled,
every time the reflective memory is written from the local VME backplane and the transmit FIFO is
over half-full or a corrupt transfer occurs, the INT0 will be generated. The information related to the
situation of half-full transmit FIFO is also available by monitoring the bit 5 of the Control and Status
Register (CSR). When the transmit FIFO becomes full, a BERR will be generated if a new write is attempted. The application shall avoid that this situation will never occur.
The three network interrupts INT1-3 are available for remote signalling between CPUs. These interrupt signals may be used to synchronize processes distributed on two or more CPUs, or to inform
about the availability of some computed data which have to be shared. A network interrupt can be
VMIVME-5576 Driver User Manual - 2 VLT-MAN-ESO-15400-1375 15
either sent to a specific node or broadcast to all the nodes in the reflective memory network.
All 4 interrupts can be served by a user-provided ISR, if configured and enabled. Each interrupt
source can be configured to run the ISR at interrupt level, by passing the pointer of the user-provided routine, or in the normal task context, by “taking” a synchronization semaphore, that is automatically “given” by the driver when the interrupt occurs.
When the local interrupt INT0 is detected, even though there is not user-provided ISR configured,
the driver sets (on) the Fail LED on the board front panel and logs the error into the VxWorks logging system.
For the PMC-5565, the interrupt handling is different. All local INT<x> interrupts are serviced on
the CPU by the single PCI interrupt line INTA#. Only the “remote” interrupts INT1-4 (the board
supports one remote interrupt more than the VMIVME-5576) are supported by the driver. Instead
of the two options to run an interrupt service routine at task or interrupt level, the PMC-5565 requires to register a user functions as a “callback”. The function is called whenever a network interrupt INT<x> is triggered by a different RFM2G node.
2.6 Special Features
The PMC-5565 and VMIVME-5576 Reflective Memory Boards can be operated in a redundant
transfer mode (VMIVME-5576: jumper Fast Field J5, PMC-5565: Switch S1 position 1) in which each
transfer is transmitted twice. In this mode the data transfer rate is reduced from 6.2 MBytes/s to 3.2
MBytes/s, so that the probability of both transfers containing an error is negligible. When the board
is used in redundant mode the transmission error detection should be masked off (jumper Mask
Field J3), so that the INT0 can be generated only by an over-half-full transmit FIFO and the possible
ISR does not need to monitor the bit 5 of the CSR.
2.7 Include files
Applications using the rmn must include rmn.h. The rmn.h include file includes everything required to use the procedures described in the previous section.
• The needed VxWorks header files
• "rmnErrors.h" which defines literals of rmn errors, as returned by driver calls.
• "rmnCommands.h" which defines literals of the rmn Driver commands and the data structures
for multiple argument commands as used with the ioctl function.
Applications using rfm2g must include rfm2g.h. The rfm2g.h include file includes everything
required to use the procedures described in the previous section.
• The needed VxWorks header files
• "rfm2gErrors.h" which defines literals of rmn errors, as returned by driver calls.
• "rfm2gCommands.h" which defines literals of the rmn Driver commands and the data
structures for multiple argument commands as used with the ioctl function.
16 VMIVME-5576 Driver User Manual - 2 VLT-MAN-ESO-15400-1375
VMIVME-5576 Driver User Manual - 2 VLT-MAN-ESO-15400-1375 17
3 DRIVER FUNCTIONS
3.1 Introduction
This chapter provides a detailed description of the rmn driver module interface to the user, namely
functions, commands, include files and tools.
The functions are described in UNIX man-page format and are organized in a functional order. Below is an index of the routines of the rmn driver in the same order.
• rmnDrv to install the rmn driver
• rmnDevCreate to add a rmn device to the driver
• open to open a channel to a device
• close to close a channel
• ioctl to issue a control command
For the rfm2g driver, only the first two functions differ:
• rfm2gDrv to install the rfm2g driver
• rfm2gDevCreate to add a rfm2g device to the drive
Each of these calls returns a status code which signals the success of the call. A zero value always
means "successful completion" while a negative value indicates an error. The value -1 stands for
"general error" and origins in VxWorks while other values signal a specific error reason and are returned by the driver itself. Literals of all error codes can be found in the include file rmnErrors.h/
rfm2gErrors.h and in [7].
3.2 Driver and Device Installation Functions
The installation of the rmn and rfm2g drivers is according to the VxWorks driver concept described
in and [4] and [5]. Two functions are provided.
For the rmn driver:
1. rmnDrv to install the driver, which takes the arguments:
a. the maximum number of supported devices
b. the maximum number of supported channels to devices
c. a timeout value for semaphore waits
2. rmnDevCreate to install a device, which takes the arguments:
a. the device-name (which must be /rmn<number>, with <number> starting from zero)
b. the base-address of the board in the VMEbus A24 or A32 address-space. The value
0xffffffff will create the device in simulation mode1.
c. the address-space selection (rmnVME_ADD_A24 or rmnVME_ADD_A32)
d. the memory option (rmnMEM_256KB, rmnMEM_512KB or rmnMEM_1MB)
e. the interrupt-vector number of the first interrupt source (64..252)
2
1. See § 4.6 for more details about simulation.
2. The interrupt-vector is defined only for the first interrupt source. The remaining 3 interrupt sources will be
connected to progressively increasing interrupt-vectors.
18 VMIVME-5576 Driver User Manual - 2 VLT-MAN-ESO-15400-1375
f. the interrupt-level number (1..7)
1
The parameters b., c. and d. must be chosen according to the jumper settings made on the board and
to the actual amount of memory installed. Standardized base addresses, interrupt vectors and interrupt level are defined in the VLT standard VME boards configuration [8]. All the arguments are
stored in the device-descriptor.
The driver performs the following steps at device installation during rmnDevCreate() and report any
error or exceptional situation to the caller:
• Check that the address-space is correctly specified.
• Check that the memory option is correctly specified.
• Check that the interrupt vector is in the proper range.
• Check that the interrupt level is in the proper range.
• Check if the driver has been installed.
• Validate the given device-name.
• Get the base address of the board in the CPU address space (CPU local address).
• In case of simulation mode, allocate the required memory.
• Verify if the base-address is correct, check if the reflective memory board is present at that
address, perform a test of the board’s memory.
• Initialize the device-specific data structures, add the device to VxWorks, and allocate the access
protection semaphore.
*** from here on the device is installed under VxWorks ***
• Configure and initialize the interrupt sources (interrupt vectors, interrupt level, internal hooks
and data structures for user-provided ISRs).
• Reset (switch off) the Fail LED on the front panel to give a visual feedback that the device has
been created and initialized successfully
After an OK return, the device is correctly installed under VxWorks and ready to accept open calls.
For the rfm2g driver:
3. rfm2gDrv to install the driver, which takes the arguments:
a. the maximum number of supported devices
b. the maximum number of supported channels to devices
c. a timeout value for semaphore waits
d. the base address of the board’s onboard memory for CPUs that do NOT support
autoconfiguration. If the CPU supports autoconfiguration, that last parameter is ignored.
4. rfm2gDevCreate to install a device, which takes the arguments:
a. the device-name (which must be /rfm2g<number>, with <number> starting from zero)
Instead of trying to probe the board on the VME-bus, the rfm2g driver tries to find the RFM2G device on the PCI bus. All other checks are similar to the rmn driver.
1. The same interrupt level is assigned to all the 4 interrupt sources.
Loading...