GE Fanuc VMIVME-5576 User Manual

Download

Page 1

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

Page 2

2 VMIVME-5576 Driver User Manual - 2 VLT-MAN-ESO-15400-1375

Page 3

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: Uniﬁed User Manual for VMIVME-

5576 and PMC-5565 Reﬂective Memory board.

Page 4

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.

Page 5

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

Page 6

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

Page 7

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 conﬁgure 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 Reﬂective Memory Board Driver

• rfm2g - PMC-5565 Reﬂective Memory 2nd Generation Driver

Page 8

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 Reﬂective 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 Reﬂective Memory Board Driver Speciﬁcation

VLT-SPE-ESO-15400-1374, Issue 1.0, 25/08/1997

[2] Local Control Unit Software Speciﬁcation

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 Reﬂective 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/Conﬁguration 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.

Page 9

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

Page 10

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, ﬁlenames, preﬁxes/sufﬁxes 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 Conﬁguration 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.

Page 11

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>

-----------------------------------------------------------------------------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. >>>>> >>>>>

==============================================================================

Page 12

12 VMIVME-5576 Driver User Manual - 2 VLT-MAN-ESO-15400-1375

Page 13

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.

Page 14

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

Page 15

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 ﬁles

• "rmnErrors.h" which deﬁnes literals of rmn errors, as returned by driver calls.

• "rmnCommands.h" which deﬁnes 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 ﬁle includes everything required to use the procedures described in the previous section.

• The needed VxWorks header ﬁles

• "rfm2gErrors.h" which deﬁnes literals of rmn errors, as returned by driver calls.

• "rfm2gCommands.h" which deﬁnes literals of the rmn Driver commands and the data structures for multiple argument commands as used with the ioctl function.

Page 16

16 VMIVME-5576 Driver User Manual - 2 VLT-MAN-ESO-15400-1375

Page 17

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 ﬁrst interrupt source (64..252)

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.

Page 18

18 VMIVME-5576 Driver User Manual - 2 VLT-MAN-ESO-15400-1375

f. the interrupt-level number (1..7)

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 speciﬁed.

• Check that the memory option is correctly speciﬁed.

• 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 reﬂective memory board is present at that address, perform a test of the board’s memory.

• Initialize the device-speciﬁc data structures, add the device to VxWorks, and allocate the access protection semaphore.

*** from here on the device is installed under VxWorks ***

• Conﬁgure 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

autoconﬁguration. If the CPU supports autoconﬁguration, 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.

Page 19

VMIVME-5576 Driver User Manual - 2 VLT-MAN-ESO-15400-1375 19

3.3 Tool Functions

The following tool functions are provided by the rmn driver:

• rmnVersion to print the version of the loaded driver module to the LCU console;

• rmnDevShow to print a list of all installed devices with their respective installation parameters to the LCU console;

• rmnDevDump(<device>) to print the content of the board’s registers in a convenient format to the LCU console;

• rmnMemDump(<device>) to print the content of the board’s register in hexadecimal format to the LCU console;

• rmnDevDescrDump(<device>) to print the content of the device descriptor data structure to the LCU console;

• rmnTestBoard(<device>) to perform a test of the board and of the optical link; it is the toolfunction implementation of the corresponding ioctl-command “Test Board and Link” (see §

4.3).

The following tool functions are provided by the rfm2g driver:

• rfm2gVersion to print the version of the loaded driver module to the LCU console;

• rfm2gDevShow to print a list of all installed devices with their respective installation parameters to the LCU console;

• rfm2gDevDescrDump(<device>) to print the content of the device descriptor data structure to the LCU console;

• rfm2gTestBoard(<device>) to perform a test of the board and of the optical link; it is the toolfunction implementation of the corresponding ioctl-command “Test Board and Link” (see §

4.3).

• rfm2gDrvRemove(<device>): To remove the driver from the vxWorks IO system.

3.4 Device Access Functions

The standard VxWorks functions as described in [4] and [5] are used to request and release access to a rmn or rfm2g device. Driver-specific functions are connected to these calls upon driver installation:

1. open to get access to a device. It takes the arguments:

a. device-name

b. open-mode

c. pointer to an error-code (integer) to be returned

It returns a ﬁle-descriptor (positive integer) or ERROR.

2. close to release access to a device. It takes as argument the ﬁle-descriptor.

3. ioctl to send commands to and query values from a device. It takes the arguments:

a. the ﬁle-descriptor as returned by open

b. the ioctl-command, an integer value as described in section 4

c. a pointer to an argument value, whereby values can also be returned

It returns an error-code (integer).

4. read and write - as well as other standard VxWorks driver functions - are not necessary and not supported.

Page 20

20 VMIVME-5576 Driver User Manual - 2 VLT-MAN-ESO-15400-1375

These functions are described in the following sections with respect to their special meaning in the rmn context.

See also the man-pages of the internally used device-specific routines in the Reference chapter 9 for detailed information, especially for an exact error reference. For more general information see the “VxWorks Programmers Guide”.

Page 21

VMIVME-5576 Driver User Manual - 2 VLT-MAN-ESO-15400-1375 21

3.4.1 open

NAME

open - open a channel to a rmn device

SYNOPSIS

#include "rmn.h" int open (char *deviceName, int openMode, int *status)

DESCRIPTION

This operation opens the device corresponding to deviceName in readonly mode or in one of the read/write modes described below. The read access is granted in all open modes. The argument status receives the completion status of the routine.

* deviceName specifies the device (e.g. "/rmn0") * openMode can be:

-lcudrvOPEN_READONLY Read only mode.

-lcudrvOPEN_SHARED Shareable read and write mode. Write access is granted to a

defined number of tasks to use this open mode. Exceeding this number or requesting this mode for a device already opened in Exclusive mode returns an error.

-lcudrvOPEN_EXCLUSIVE Exclusive read write mode. Write access is granted to the task

using this open mode. Requesting this mode for a device already opened in Exclusive or Shared mode returns an error.

-lcudrvOPEN_TEST Test read and write open mode. Write access is granted to the task

using this option mode regardless of the status of the device. Requesting this mode for a device already opened in Test mode returns an error.

*status is a pointer to the error-code to be returned. If it is NULL, then nothing is returned. Note that this value is only valid when the function’s return-value actually indicates an error.

RETURN VALUES

* A positive file descriptor number, which must be used for subsequent

close and ioctl operations.

* A value of -1 signals a general error. The specific error reason is

1. Note that the third parameter is declared as (int) in VxWorks. A cast with (int) will therefore always be necessary when this function is called.

Page 22

22 VMIVME-5576 Driver User Manual - 2 VLT-MAN-ESO-15400-1375

provided in the argument status, as stated in the man-pages of the rmnOpen device-specific routine § 9.5.

* The zero value is never returned.

EXAMPLE

int fd, status;

......

fd = open ("/rmn0", lcudrvOPEN_READONLY, (int)&status);

if (fd <= 0) { /* error processing */

......

}

else { /* normal processing */

......

}

CAUTIONS

* Device names shall not be longer than 15 characters. They are defined

by use of the function rmnDevCreate at startup.

* This function is not queued by the driver, it always returns immedi-

ately with the file descriptor or an error code. * The returned file descriptor can be shared by several applications. * Applications can have the same device opened several times, using

different file descriptors and with different open modes. * As only one task can open a device for Exclusive mode at any one

time, and the number of channels is limited, applications should

issue a close call if no more action on the device has to be per-

formed.

VxWorks

* The VxWorks include file "configAll.h" contains two literals used by

iosInit function: NUM_DRIVERS which defines the maximum number of

drivers allowed, and NUM_FILES, the maximum number of simultaneously

open files. * The VxWorks command "iosDrvShow" shows all drivers of the system and

their basic I/O function entry-points. The command "iosFdShow" shows

all currently used file descriptors, and "iosDevShow" (or "devs")

all installed devices.

Page 23

VMIVME-5576 Driver User Manual - 2 VLT-MAN-ESO-15400-1375 23

3.4.2 close

NAME

close - close a channel to a rmn device

SYNOPSIS

#include "rmn.h" int close (int fileDescriptor)

DESCRIPTION

This operation closes a channel to an opened device and frees the file descriptor. fileDescriptor must correspond to one of those obtained previously be an open call.

RETURN VALUES

* lcudrvOK if successfully done. * Other error codes as stated in the man-page of the rmnClose device-

specific routine § 9.1.

EXAMPLE

int fd, status; int closeError; fd = open ("/rmn0", lcudrvOPEN_TEST, (int)&status);

......

closeError = close (fd);

if (closeError != lcudrvOK) { /* error processing */

......

}

else { /* normal processing */

......

}

CAUTIONS

* This function is not queued by the driver, it always returns one of

the above status codes immediately.

Page 24

24 VMIVME-5576 Driver User Manual - 2 VLT-MAN-ESO-15400-1375

3.4.3 ioctl

NAME

ioctl - send a control command to a rmn device

SYNOPSIS

#include "rmn.h" int ioctl (int fileDescriptor, int command, void *argument)

DESCRIPTION

This function commands the driver to perform the specified operation on the device. The commands are divided into read and write commands. Read commands are allowed in each open mode while write commands will be rejected if the channel was not previously opened in Shared, Exclusive or Test mode.

* fileDescriptor must correspond to one of those obtained previously

by an open operation.

* command is a number, identifying the operation to be performed by the

driver. Literals of all commands are provided in rmnCommands.h. and described in chapter 4.

* argument is the address of the command argument, or NULL if no argu-

ment is used. For commands, needing multiple arguments it is the address of a data structure which contains those. All argument data structures are defined in the include file rmnCommands.h.

RETURN VALUES

* lcudrvOK if the command is successfully transmitted and performed by

the device.

* errors as stated in the man-pages of the rmnIoctl device-specific

routine and in each command’s description in chapter 4.

EXAMPLE

int fd, status; int arg; int ioctlError; fd = open ("/rmn0", lcudrvOPEN_TEST, (int)&status);

......

arg = 30; ioctlError = ioctl (fd, rmnCMD_SET_TIMEOUT, (int)&arg);

1. Note that the third parameter is declared as (int) in VxWorks. A cast with (int) will therefore always be necessary when this function is called.

Page 25

VMIVME-5576 Driver User Manual - 2 VLT-MAN-ESO-15400-1375 25

if (ioctlError != lcudrvOK) { /* error processing */

......

}

else { /* normal processing */

......

}

CAUTIONS

* This function is protected by a semaphore, and commands are queued

by application priorities rather than by First-in First-out.

Page 26

26 VMIVME-5576 Driver User Manual - 2 VLT-MAN-ESO-15400-1375

Page 27

VMIVME-5576 Driver User Manual - 2 VLT-MAN-ESO-15400-1375 27

4 DRIVER IOCTL COMMANDS

This section describes all control commands which can be invoked by use of the VxWorks ioctl function. The parameter command specifies which operation has to be performed by the driver while the parameter argument passes the address of an argument to the command handler. In cases where multiple arguments are needed the address of a structure which contains those is passed.

All command literals and argument data structures are defined in the include files rmnCommands.h and rfm2gCommands.h.

A pointer to the argument is passed in the ioctl call, never the argument value itself. The ioctl function returns values through this pointer.

All ioctl calls return lcudrvOK on successful completion, otherwise one of the stated error-codes.

The next sections will describe the available ioctl-commands.

4.1 Access to the User Memory

The board’s User Memory, which is the DPRAM available to the user to store data, can be directly accessed via VME R/W cycles (VMIVME-5576) or via PCI-bus access (PMC-5565), but only after getting from the device driver the corresponding memory address (addresses of the first and the last byte location) as seen from the CPU, e.g. in the CPU local address space.

Two commands are available to get the base and the top addresses of the user memory. The user is responsible not to exceed the address space defined within the two boundaries during a direct R/ W, otherwise a VME bus error will probably occur.

• Get User Memory Base Address

Description - Returns the base address (CPU local address-space) of the user memory area; for the VMIVME-5576 it is equal to the <board base address> + 0x40.

Literals: rmnCMD_ADDR_GET_USER_MEM_BASE, rfm2gCMD_ADDR_GET_USER_MEM_BASE

Argument: pointer to a generic address (void *) Return Value: user memory base-address Errors: none (always lcudrvOK)

• Get User Memory Top Address

Description - Returns the top address (CPU local address-space) of the user memory, that is the address of the last byte of the user memory area. For the rmn driver, the actual value returned depends on the memory option of the board, according to the following table:

For the rfm2g driver, the size of the onboard memory is either 64MB or 128MB, depending on the model. rfm2gCMD_GET_USER_MEM_TOP will therefore return the value of rfm2gCMD_ADDR_GET_USER_MEM_BASE + 0x8000000 (or 0x4000000 for the 64MB model).

Literals: rmnCMD_ADDR_GET_USER_MEM_TOP, rfm2gCMD_ADDR_GET_USER_MEM_TOP

memory option top address

256 KB <board base address> + 0x03FFFF 512 KB <board base address> + 0x07FFFF

1 MB <board base address> + 0x0FFFFF

Page 28

28 VMIVME-5576 Driver User Manual - 2 VLT-MAN-ESO-15400-1375

Argument: pointer to a generic address (void *) Return Value: user memory top-address Errors: none (always lcudrvOK)

Normally the user should not be interested in getting the base address of the board, which is also the base address of the Register Memory. Only for engineering purposes the following command is provided:

• Get Register Memory Base Address

Description - Returns the base address (CPU local address-space) of the register memory area; it is equal to the <board base address>.

Literals: rmnCMD_ADDR_GET_REGS_MEM_BASE, rfm2gCMD_ADDR_GET_REGS_MEM_BASE

Argument: pointer to a generic address (void *) Return Value: register memory base-address Errors: none (always lcudrvOK)

4.2 Access to the Register Memory

No direct user access is foreseen to the board’s Register Memory. All accesses to this area shall be handled within the driver.

4.2.1 Board Control and Status

The user can access the Control and Status Register (CSR) or one of its bit by calling the commands described below.

• Get Control and Status Register

Description - Reads the CSR register (8/32 bits). Literals: rmnCMD_GET_STATUS,

rfm2gCMD_GET_STATUS

Argument: VMIVME-5576: pointer to a byte (unsigned char), PMC-5565: pointer to a INT32 Return Value: VMIVME-5576: CSR value (unsigned char), PMC-5565: Control and Status Register 1 (INT32) Errors: none (always lcudrvOK)

• Set Control and Status Register

Description - Sets the CSR register (only the user-writable bits: failLED, badData, ownData)1. Literals: rmnCMD_SET_STATUS,

rfm2gCMD_SET_STATUS

Argument: pointer to a byte (unsigned char), which contains the CSR value Return Value: Errors: none (always lcudrvOK) Notes: This command is NOT supported on the PMC-5565, and will return lcudrvERROR. All

bits in this registers can be modiﬁed via IOCTL calls. There should not be the need to directly access this register.

• Get Fail LED Bit

Description - Reads the Fail LED bit of the CSR (VMIVME-5576: bit 7, PMC-5565: bit 31). The bit

1. See Driver Specification document [1] for a description of the CSR bits.

Page 29

VMIVME-5576 Driver User Manual - 2 VLT-MAN-ESO-15400-1375 29

value corresponds to the status of the LED on the board’s front panel (0=’OFF’, 1=’ON’).

Literal: rmnCMD_GET_FAIL_LED, rfm2gCMD_GET_FAIL_LED

Argument: pointer to an integer (int) Return Value: Fail LED bit value (int) Errors: none (always lcudrvOK)

• Set Fail LED Bit

Description - Sets the Fail LED bit of the CSR (0=’switch OFF’, 1=’switch ON’). Literal: rmnCMD_SET_FAIL_LED,

rfm2gCMD_SET_FAIL_LED

Argument: pointer to an integer (int), which contains the Fail LED bit value Return Value: Errors: none (always lcudrvOK)

4.2.2 Node Identification

The user can access the Node ID Register by calling the command described below.

• Get Node ID Register

Description - Reads the Node ID register, which contains the node number associated to the board within the reflective memory network. The value (must be in the range [0..255]) depends on the Board Node ID Field jumpers J9 configuration (VMIVME-5576) or via the switches S1 and S2 (PMC-5565).

Literals: rmnCMD_GET_NODE_ID, rfm2gCMD_GET_NODE_ID

Argument: pointer to an integer (int) Return Value: board’s node ID (int) Errors: none (always lcudrvOK)

4.2.3 Interrupt Commands

The user can access the four Interrupt Control Registers (ICRs), the three Interrupt Sender ID registers (VMIVME-5576)/four Interrupt Sender ID registers (PMC-5565) and the Interrupt Command Register by calling the commands described below.

• Enable Interrupt Source

Description - Enables an interrupt source by setting the Interrupt Enable bit (bit 4 of the ICR). At the completion of this routine, every interrupt of the selected source will be detected and served, e.g. the associated ISR will be called, if attached. For the rfm2g, a user function is attached as a callback to this interrupt event.

Literals: rmnCMD_ENABLE_INTERRUPT, rfm2gCMD_ENABLE_INTERRUPT

Argument: pointer to an integer, which contains the interrupt source number. VMIVME-5576: [0..3], PMC-5565: [1..4]

Return Value: Errors: wrong parameter-value: lcudrvERROR_INVALID_ARGUMENT

• Disable Interrupt Source

Description - Disables an interrupt source by resetting the Interrupt Enable bit. At the completion of this routine, every interrupt received will not be detected by the driver (it will

Page 30

30 VMIVME-5576 Driver User Manual - 2 VLT-MAN-ESO-15400-1375

actually be stored in the Interrupt FIFO of the board).

Literals: rmnCMD_DISABLE_INTERRUPT, rfm2gCMD_DISABLE_INTERRUPT

Argument: pointer to an integer, which contains the interrupt source number. VMIVME-5576: [0..3], PMC-5565: [1..4]

Return Value: Errors: wrong parameter-value: lcudrvERROR_INVALID_ARGUMENT

• Enable Interrupt Autoclear

Description - Enables the interrupt-autoclear feature of the board by setting the Interrupt Autoclear bit (bit 3 of the ICR), so that the selected interrupt source will be automatically

disabled, after every interrupt detection. Then an explicit call to the interrupt enabling routine must be performed in order to receive the next interrupt.

Literals: rmnCMD_ENABLE_INT_AUTOCLEAR, rfm2gCMD_ENABLE_INT_AUTOCLEAR

Argument: pointer to an integer, which contains the interrupt source number [0..3] Return Value: Errors: wrong parameter-value: lcudrvERROR_INVALID_ARGUMENT Notes: Due to the different philosophy of attaching user callbacks to remote interrupt events,

the autoclear feature is not available on the rfm2g driver, and will return lcudrvERROR. Actually, the autoclear feature is not available on HW level.

• Disable Interrupt Autoclear

Description - Disables the interrupt-autoclear feature of the board by resetting the Interrupt Autoclear bit. Literals: rmnCMD_DISABLE_INT_AUTOCLEAR,

rfm2gCMD_DISABLE_INT_AUTOCLEAR

the autoclear feature is not available on the rfm2g driver, and will return lcudrvERROR. Actually, the autoclear feature is not available on HW level.

• Clean Interrupt FIFO

Description - Cleans the network interrupt receiving FIFO by writing any data to the Interrupt Sender ID register. All the interrupt previously stored and blocked in the FIFO will be

cancelled.

This command is valid only for network interrupt sources [VMIVME-5576: INT1-3,

PMC-5565: INT1-4].

Literals: rmnCMD_CLEAN_INT_FIFO, rfm2gCMD_CLEAN_INT_FIFO

Argument: pointer to an integer, which contains the interrupt source number [VMIVME-5576:

1..3, PMC-5565: 1..4]

Return Value: Errors: wrong parameter-value: lcudrvERROR_INVALID_ARGUMENT

• Configure Interrupt Source

Description - Sets the configuration of an interrupt source and enables it. For the VMIVME-5576, rhere are 2 possible ways of configuring an interrupt source:

1.providing the address of a user-defined ISR, which will be called at interrupt-level when the interrupt occurs;

Page 31

VMIVME-5576 Driver User Manual - 2 VLT-MAN-ESO-15400-1375 31

2.obtaining the ID of the interrupt synchronization semaphore, which will be “given” when the interrupt occurs; in this case the user defined ISR will run in a normal task context and has to “take” the interrupt synchronization semaphore in order to remain blocked until the interrupt occurs.

An interrupt source is considered successfully configured when it is enabled and a user-provided ISR is attached or the synchronization semaphore ID has been returned to the configuring task. For the PMC-5565, the philosophy is different: A user-defined callback function is attached to a remote interrupt “event”, and called, whenever this event occurs.

Literals: rmnCMD_CONFIG_INTERRUPT,

rfm2gCMD_CONFIG_INTERRUPT

Argument: VMIVME-5576: pointer to the rmnINT_CONFIG_DATA structure, which contains:

source - interrupt source number [0..3] mode - interrupt configuration mode [rmnISR_CONTEXT

or rmnTASK_CONTEXT] userISR - pointer to a user-defined ISR (used only if mode is rmnISR_CONTEXT) userArg - pointer to user-provided data (used only if mode is rmnISR_CONTEXT) semID - pointer to the synchronization semaphore (return value only) autoClear - enable interrupt autoclear cleanFIFO - clean interrupt FIFO (used only if source is in the range [1..3])

PMC-5565: pointer to the rfm2gINT_CONFIG_DATA structure, which contains: source - interrupt source number [1..4] userFunc - pointer to a user function with the following signature:

void rfm2gCallback( RFM2GHANDLE rh, RFM2GEVENTINFO evt )

Return Value: VMIVME-5576: the rmnINT_CONFIG_DATA data structure, with the interrupt synchronization semaphore pointer (meaningful only if mode is rmnTASK_CONTEXT) PMC-5565: The status value. Errors: wrong parameter-value: lcudrvERROR_INVALID_ARGUMENT

the interrupt was already configured: rmnERROR_INTERRUPT_CONFIGURED

• Get Interrupt Configuration

Description - Gets the current configuration of an interrupt source. Literals: rmnCMD_GET_INT_CONFIG,

rfm2gCMD_GET_INT_CONFIG

Argument: VMIVME-5576: pointer to the rmnINT_GET_CONFIG_DATA structure, with the input argument:

source - interrupt source number [0..3]

PMC-5565: pointer to the rfm2gINT_GET_CONFIG_DATA structure, with the input argument:

source - interrupt source number [1..4]

Return Value: VMIVME-5576: the updated rmnINT_GET_CONFIG_DATA structure, which contains:

source - as above used - interrupt is configured [1=YES / 0=NO] enable - enable bit state [1=enabled/0=disabled] autoClear - autoClear bit state [1=enabled/0=disabled] mode - interrupt configuration mode [rmnISR_CONTEXT

or rmnTASK_CONTEXT]

Page 32

32 VMIVME-5576 Driver User Manual - 2 VLT-MAN-ESO-15400-1375

userISR - pointer to a user-defined ISR (only if mode is rmnISR_CONTEXT) userArg - pointer to user-provided data (only if mode is rmnISR_CONTEXT) semID - pointer to the synchronization semaphore n_Sent - number of interrupt sent by this source n_Served - number of interrupt served by this source n_SemGive - number of semaphore given by the internal ISR of this source

n_UserISR - number of calls to the user provided ISR by this source

PMC-5565: The updated rfm2gINT_GET_CONFIG_DATA structure, with the following information:

source - as above used - callback is configured (0 = NO/1 = Yes) userFunc - Pointer to user-defined callback function

Errors: wrong parameter-value: lcudrvERROR_INVALID_ARGUMENT

• Send Interrupt

Description - Sends an interrupt to the selected remote node or to every node (broadcast interrupt) through the reflective memory board and the fiber-optic reflective memory network. This command is valid only for network interrupt sources [VMIVME-5576: INT1-3, PMC5565:

1..4].

Literals: rmnCMD_SEND_INTERRUPT, rfm2gCMD_SEND_INTERRUPT

Argument: VMIVME-5576: pointer to the rmnINT_SEND_DATA structure, PMC-5565: pointer to the rfm2gINT_SEND_DATA structure, which contain:

source - interrupt source number [VMIVME-5576: 1..3, PMC-5565: 1..4] targetID - node ID of the target node [0..255 or rmnINT_BROADCAST]

Return Value: Errors: wrong parameter-value: lcudrvERROR_INVALID_ARGUMENT

• Reset Interrupt Source

Description - Resets an interrupt source. VMIVME-5576: the user-defined ISR will be detached (if configured) (PMC-5565: The callback will be detached), the interrupt autoclear will be disabled (VMIVME-5576 only), the interrupt FIFO will be cleaned (in case of network interrupt source [VMIVME-5576: 1..3, PMC-5565: 1..4]) and the interrupt source will be disabled. This routine must be called before re-configuring an interrupt source.

Literals: rmnCMD_RESET_INTERRUPT, rfm2gCMD_RESET_INTERRUPT

Argument: pointer to an integer, which contains the interrupt source number [VMIVME-5576:

0..3, PMC-5565: 1..4]

Return Value: Errors: wrong parameter-value: lcudrvERROR_INVALID_ARGUMENT

4.3 Test Commands

The board and the network can be tested using the following commands.

• Test Board and Link

Description - This command performs the most comprehensive test of the board and the link, computing also the link round trip time, that is the time spent by a data item (1, 2 or 4 bytes) to travel through all the nodes of the reﬂective memory network. The detailed test procedure is as below:

1.set (switch on) the Fail LED to show on the front panel that the board is under test

Page 33

VMIVME-5576 Driver User Manual - 2 VLT-MAN-ESO-15400-1375 33

2.veriﬁes that the board is properly installed at the given VME address (VMIVME-5576) or on

the PCI-bus (PMC-5565), by reading and checking the value of the Board ID register

3.tests the user memory, by writing and reading back to/from a set of memory locations all over the user memory area

4.checks the optical link’s integrity, verifying the receiving back of the data originated by the local node itself within a certain timeout

5.if no errors, reset (switch off) the Fail LED on the front panel to give a visual feedback that the device has been tested successfully

6.iVMIVME-5576: f all the previous steps succeeded, computes and returns the link round trip time,

Literals: rmnCMD_TEST_BOARD, rfm2gCMD_TEST_BOARD

Argument: VMIVME-5576: pointer to an unsigned long Return Value: VMIVME-5576: link round trip time (unsigned long) in nanoseconds

PMC-5565: The status value Errors: no reflective memory board found at the specified VME address (Board ID register val-

ue not valid) or on the PCI-bus: rmnERROR_INVALID_BOARD_ID (VMIVME-5576 only) no HW found at the specified VME address:

rmnERROR_INVALID_VME_ADDR

test of the board’s user memory failed: rmnERROR_BAD_DATA test of the link integrity failed: rmnERROR_LINK_BROKEN

• Test Link

Description - This command performs only the test of the link integrity.

Literals: rmnCMD_TEST_LINK,

rfm2gCMD_TEST_LINK

Argument: Return Value: Errors: test of the link integrity failed: rmnERROR_LINK_BROKEN

4.4 Reset Command

The device can be reset by using the following command:

• Reset Device

Description - This routine reset all the network interrupt sources and resets the writable bits of the CSR register (badData, ownData and failLED).

Literals: rmnCMD_RESET_DEVICE, rfm2gCMD_RESET_DEVICE

Argument: Return Value: Errors: none (always lcudrvOK)

4.5 Driver-Related Commands

The following ioctl-commands are handled completely within the driver and not forwarded to the board.

• Get Driver Version

Description - Returns an integer value derived from the module’s version. Bits 31..16 contain the major version number, bits 15..0 contain the minor version number.

Page 34

34 VMIVME-5576 Driver User Manual - 2 VLT-MAN-ESO-15400-1375

Literals: rmnCMD_GET_DRIVER_VERSION,

rfm2gCMD_GET_DRIVER_VERSION

Argument: pointer to an integer (int) Return Value: version (integer) Errors: none (always lcudrvOK)

• Set Timeout Value

Description - Modifies the timeout-value to be used for device access semaphore-waits. Literal: rmnCMD_SET_TIMEOUT,

rfm2gCMD_SET_TIMEOUT

Argument: pointer to an integer, which contains the timeout value in ticks Return Value: Errors: timeout value is not valid: lcudrvERROR_INVALID_ARGUMENT

• Get Timeout Value

Description - Reads the timeout-value of the device access semaphore-waits. Literal: rmnCMD_GET_TIMEOUT,

rfm2gCMD_GET_TIMEOUT

Argument: pointer to an integer Return Value: timeout value in ticks Errors: none (always lcudrvOK)

• Free Device

Description - Forces a close of a channel opened in exclusive mode. Literal: rmnCMD_FREE_DEVICE,

rfm2gCMD_FREE_DEVICE

Argument: Return Value: Errors: there is no channel in exclusive mode: rmnERROR_NO_EXCLUSIVE:

4.6 Simulation Modes

VMIVME-5576: The simulation mode allows to run the driver without the reflective memory board. The device can be created in simulation mode by specifying 0xffffffff as the base address in the rmnDevCreate call. In this case the driver maps in the CPU RAM the register and the user memory of the reflective memory board. The usage of ioctl commands result simply in changes to the content of the simulated board’s registers.

There is no simular simulation mode for the PMC-5565, as the 128MB buffer would use too much memory. If the device is not found during boot time, the /rfm2g<x> device is simply not installed.

Page 35

VMIVME-5576 Driver User Manual - 2 VLT-MAN-ESO-15400-1375 35

5 ERROR MESSAGES AND RECOVERY

All driver functions make use of the errors defined in the common driver library lcudrv as described in [7]. Driver-specific errors have been added.

The driver performs a number of checks that the correct conditions are fulfilled and reports an error if this is not the case.

Checks for installation functions include the points already mentioned in section 3.2, and tests for insufficient memory or other system resources.

No checks are done for tool functions of section 3.3, except those that are already included in other driver calls.

Checks for the open and close calls use the common driver library lcudrv as defined in [7]. This results in the following behavior:

• An open request in exclusive read/write mode is rejected if the device is open to any other process in exclusive or shared read/write mode.

• An open request in shared read/write mode is rejected if the device is open to any other process in exclusive read/write mode.

• An open request in test read/write mode is rejected if the device is open to any other process in test read/write mode.

Checks for the ioctl call also make use of the common driver library lcudrv as defined in [7] for validation of the channel-number and access-rights. Errors which are specific to each ioctl-command are described in the respective sections of chapter 4.

Access-rights for the respective ioctl-commands are assigned as follows:

• Read commands are permitted in all open-modes.

• Write commands are inhibited in READONLY open-mode, but permitted in all others.

Semaphore protection of the device is performed for all ioctl-commands. An ioctl call exits with an lcudrvERROR_TIMEOUT error when the executing task is blocked for longer than the current driver-timeout-value for semaphore-waits, as defined with the driver installation or with the rmnCMD_SET_TIMEOUT command.

The summary of all driver error codes in alphabetical order follows below:

rmnERROR_ Description

NOT_EXCLUSIVE

There is no channel opened in exclusive mode. The rmnCMD_FREE_DEVICE/rfm2gCMD_FREE_DEVICE commands have no effect.

INVALID_BOARD_ID

No rmn board was found at the speciﬁed VME address (VMIVME-5576) or on the PCI-bus (PMC-5565).

INVALID_VME_ADDR

No VME board was found at the speciﬁed VME address. This error code is not used on the rfm2g driver.

LINK_BROKEN

The reﬂective memory network is not working, some links are open.

BAD_DATA

The test of the board’s user memory failed.

Page 36

36 VMIVME-5576 Driver User Manual - 2 VLT-MAN-ESO-15400-1375

NO_INT_HANDLER

The rmn interrupt handler (VMIVME-5576) or user callback function (PMC-5565) cannot be connected to VxWorks.

INTERRUPT_CONFIGURED

The interrupt source was already conﬁgured. The rmnCMD_CONFIG_INTERRUPT/rfm2gCMD_CONFIG_INTERRUPT commands cannot be executed. The commands rmnCMD_RESET_INTERRUPT/rfm2gCMD_RESET_INTERRUPT must be used before reconﬁguring the interrupt.

rmnERROR_ Description

Page 37

VMIVME-5576 Driver User Manual - 1.1 VLT-MAN-ESO-15400-1375 37

6 CODE EXAMPLES

6.1 Reflective Memory Access

The following code shows how to use to reflective memory. The first step is to retrieve the base address of the user memory. After that the reflective memory can be accessed directly, by means of simple R/W operations. It might be useful to map C-language data structures onto the reflective memory in order to make the implementation of the code independent from the hardware addresses. In the example below, a user defined data structure is mapped onto the reflective memory starting from an offset with respect the base address.

#define DATA_STRUCT_OFFSET 0x100 typedef struct

{ int a; float b;

} DATA_STRUCT; DATA_STRUCT *dataStruct; int status; int fd; void *baseAddr; float c;

/* Open a channel */ fd = open(“/rmn0”,lcudrvOPEN_SHARED,(int)&status); if (fd < 0) { /* error handling */ }

/* Get the user memory base address */ status = ioctl(fd,rmnCMD_ADDR_GET_USER_MEM_BASE,(int)&baseAddr); if (status != lcudrvOK) { /* error handling */ }

/* Use the reflective memory. The data written will be * immediately transferred to all the other nodes in the * reflective memory network */ dataStruct = (DATA_STRUCT *)(baseAddr+DATA_STRUCT_OFFSET); dataStruct->a = 10; /* <=== VME write on the refl. memory */ c = dataStruct->b; /* <=== VME read from the refl. memory */

/* some more code */

/* Close the channel */ close(fd);

For the rfm2g, the above code is identical. The device name must however be exchanged with “/rfm2g0”.

6.2 Sending and Receiving Interrupts

VMIVME-5576: The following code shows how to use the remote-interrupt feature of the reflective memory. The user application must first configure the selected interrupt source on the receiving node, attaching a user-provided ISR or getting back the interrupt synchronization semaphore pointer. After that the sending node can start sending interrupts, which will be immediately detected and served by the receiving node.

Page 38

38 VMIVME-5576 Driver User Manual - 1.1 VLT-MAN-ESO-15400-1375

In the first example below the interrupt source 1 will be configured: the user-provided ISR will run in the interrupt context, the autoClear flag will be disabled and the interrupt FIFO will be cleaned.

/*------------------------------------------------------------------------* Code for ISR and interrupt configuration (ISR context) on receiving node *--------------------------------------------------------------------------*/ void myUserISR(void *userArg, int senderID) { /* User-provided ISR code */ /* The number of the sending node “senderID” will be * identified and passed to this routine by the rmn driver */ }

int status; int fd; static int myUserArg = 1234;

rmnINT_CONFIG_DATA intrConfigData;

/* Open a channel */ fd = open(“/rmn0”,lcudrvOPEN_SHARED,(int)&status); if (fd < 0) { /* error handling */ }

/* Configure an interrupt source */ intrConfigData.source = 1; intrConfigData.userISR = myUserISR; intrConfigData.userArg = (void *)myUserArg; intrConfigData.autoClear = 0; intrConfigData.cleanFIFO = 1; intrConfigData.mode = rmnISR_CONTEXT;

status = ioctl(fd,rmnCMD_CONFIG_INTERRUPT,(int)&intrConfigData); if (status != lcudrvOK) { /* error handling */ }

/* From now on any interrupt of source 1 sent from other nodes to * this one will be detected and the attached ISR will run. */

/* Close the channel */ close(fd);

/*----------------------------------------------------------* Code for sending an interrupt on the sending node *--------------------------------------------------------------*/ rmnINT_SEND_DATA intrData;

/* Open a channel */ fd = open(“/rmn0”,lcudrvOPEN_SHARED,(int)&status); if (fd < 0) { /* error handling */ }

/* Send an interrupt of source 1 to the target node 0 */ intrData.source = 1; intrData.targetID = 0; status = ioctl(fd,rmnCMD_SEND_INTERRUPT,(int)&intrData); if (status != lcudrvOK) { /* error handling */ }

/* Close the channel */

Page 39

VMIVME-5576 Driver User Manual - 1.1 VLT-MAN-ESO-15400-1375 39

close(fd);

This second example shows how to configure an ISR which runs in the task-context, that is getting activated by means of the interrupt synchronization semaphore.

/*-----------------------------------------------------------------* Code for interrupt configuration (task context) on receiving node *-------------------------------------------------------------------*/ int status; int fd; SEM_ID syncSem; rmnINT_CONFIG_DATA intrConfigData;

/* Open a channel */ fd = open(“/rmn0”,lcudrvOPEN_SHARED,(int)&status); if (fd < 0) { /* error handling */ }

/* Configure an interrupt source */ intrConfigData.source = 1; intrConfigData.autoClear = 0; intrConfigData.cleanFIFO = 1; intrConfigData.mode = rmnTASK_CONTEXT;

status = ioctl(fd,rmnCMD_CONFIG_INTERRUPT,(int)&intrConfigData); if (status != lcudrvOK) { /* error handling */ }

/* From now on any interrupt of source 1 sent from other nodes to * this one will be detected and the semaphore will be given */

/* Get the synchronization semaphore from the interrupt * configuration data structure. */ syncSem = intrConfigData.semID;

/* Wait for the interrupt; when the interrupt is detected by the * rmn driver, the semaphore will be given by the driver itself */ status = semTake(syncSem,WAIT_FOREVER);

/* Run the code to serve the interrupt */

/* Close the channel */ close(fd);

PMC-5565: Instead of interrupt service routines, a user-defined callback function must be used. Therefore, no “mode” can be selected by the user:

/*------------------------------------------------------------------------* Code for user callback on receiving node *--------------------------------------------------------------------------*/ void myUserCB(RFM2GHANDLE hnd, RFM2GEVENTINFO evt){ /* User-provided callback */ }

Page 40

40 VMIVME-5576 Driver User Manual - 1.1 VLT-MAN-ESO-15400-1375

int status; int fd; static int myUserArg = 1234;

rfm2gINT_CONFIG_DATA intrConfigData;

/* Open a channel */ fd = open(“/rfm2g0”,lcudrvOPEN_SHARED,(int)&status); if (fd < 0) { /* error handling */ }

/* Configure an interrupt source */ intrConfigData.source = 1; intrConfigData.userFunc = myUserCB;

status = ioctl(fd,rfm2gCMD_CONFIG_INTERRUPT,(int)&intrConfigData); if (status != lcudrvOK) { /* error handling */ } /* From now on any interrupt of source 1 sent from other nodes to * this one will be detected and the attached callback will run */ /* Close the channel */ close(fd);

/* Open a channel */ fd = open(“/rfm2g0”,lcudrvOPEN_SHARED,(int)&status); if (fd < 0) { /* error handling */ } /* Send an interrupt of source 1 to the target node 0 */ intrData.source = 1; intrData.targetID = 0; status = ioctl(fd,rfm2gCMD_SEND_INTERRUPT,(int)&intrData); if (status != lcudrvOK) { /* error handling */ } /* Close the channel */ close(fd);

Page 41

VMIVME-5576 Driver User Manual - 2 VLT-MAN-ESO-15400-1375 41

7 DIAGNOSTICS

This chapter describes the diagnostics facilities of the driver under the VxWorks shell.

7.1 rmnVersion, rfm2gVersion

This function prints the version of the rmn driver:

lte71->rmnVersion

@(#) rmn $Revision: 1.0 $

7.2 rmnDevShow, rfm2gDevShow

This function shows a brief list of all installed devices:

lte71->rmnDevShow Device Add Space Base Add Memory(KB) Int Vectors Int Level NodeID

------- --------- ---------- ---------- ----------- --------- -----/rmn0 A32 0x02000000 256 [208 - 211] 4 0 /rmn1 A32 -SIMULA- 256 [212 - 215] 4 0 total number of RMN devices: 2

7.3 rmnDevDump (not available for the rfm2g driver)

This function shows the content of the device registers in a formatted way:

lte71->rmnDevShow(“/rmn0”)

Device: /rmn0, board address 0x02000000 =========================================

0x00000001 boardID : 0x18 0x00000004 nodeID : 0x00 = 0

0x00000005 CSR - Board Control and Status Register

------------------------------------------------| | rcv | tx | tx | bad | own | | | | led | half| half|empty| data| data| mask| fast| | | full| full| | | | | |

------------------------------------------------| 0 | 1 | 1 | 0 | 0 | 1 | 0 | 1 |

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

0x00000007 cmdNode : 0x00 = 0

0x00000023 ICR - Interrupt 0 Control Register

------------------------------------| | flag|vect | int | int | int | | flag| auto|0=int|enabl| auto|level| | |clear|1=ext| |clear|[0-7]|

------------------------------------| 0 | 0 | 0 | 0 | 0 | 4 |

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

Page 42

42 VMIVME-5576 Driver User Manual - 2 VLT-MAN-ESO-15400-1375

0x00000027 ICR - Interrupt 1 Control Register

------------------------------------| | flag|vect | int | int | int | | flag| auto|0=int|enabl| auto|level| | |clear|1=ext| |clear|[0-7]|

------------------------------------| 0 | 0 | 0 | 1 | 0 | 4 |

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

0x00000026 Interrupt 1 SenderID : 0x00 = 0

0x0000002b ICR - Interrupt 2 Control Register

------------------------------------| | flag|vect | int | int | int | | flag| auto|0=int|enabl| auto|level| | |clear|1=ext| |clear|[0-7]|

------------------------------------| 0 | 0 | 0 | 0 | 0 | 4 |

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

0x0000002a Interrupt 2 SenderID : 0x00 = 0

0x0000002f ICR - Interrupt 3 Control Register

------------------------------------| | flag|vect | int | int | int | | flag| auto|0=int|enabl| auto|level| | |clear|1=ext| |clear|[0-7]|

------------------------------------| 0 | 0 | 0 | 0 | 0 | 4 |

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

0x0000002e Interrupt 3 SenderID : 0x00 = 0

0x00000033 IVR - Interrupt 0 Vector Register : 0xd0 0x00000037 IVR - Interrupt 1 Vector Register : 0xd1 0x0000003b IVR - Interrupt 2 Vector Register : 0xd2 0x0000003f IVR - Interrupt 3 Vector Register : 0xd3

7.4 rmnMemDump (not available for the rfm2g driver)

This function shows the complete content in hexadecimal format of the register memory from the board’s base address to the last byte before the user memory (0x40 bytes in total):

lte71->rmnMemDump(“/rmn0”)

|0 |1 |2 |3 |4 |5 |6 |7 |8 |9 |a |b |c |d |e |f | |--|--|--|--|--|--|--|--|--|--|--|--|--|--|--|--|

02000000: ff 18 ff ff 00 65 ff 00 71 4c 7d 91 80 24 0a 19 *.....e..qL}..$..*

02000010: 46 08 6a 8b 14 0a 0d 02 b0 0f 75 8b c8 e3 d3 4b *F.j.......u....K*

02000020: ff ff ff 04 ff ff 00 14 ff ff 00 04 ff ff 00 04 *................*

02000030: ff ff ff d0 ff ff 00 d1 ff ff 00 d2 ff ff 00 d3 *................*

7.5 rmnDevDescrDump, rfm2gDevDescrDump

This function shows the content of the device descriptor:

Page 43

VMIVME-5576 Driver User Manual - 2 VLT-MAN-ESO-15400-1375 43

lte71->rmnDevDescrDump(“/rmn0”)

rmnDEVICE_DESCRIPTOR of /rmn0 device ======================================

lcudrvDEVICE_HEADER header: DEV_HDR header: DL_NODE node: DL_NODE *next = 0x004c0f4a DL_NODE *previous = 0x0069a5ec short drvNum = 11; char *name = /rmn0; BOOL used = TRUE; int accessMode = 0x0 = NOT OPEN; int numShared = 0; char name[15] = /rmn0;

int addrSpace = A32; void *baseAddr = 0x02000000; int memOption = 256 KB; int intrNumber = 208; int intrLevel = 4; void *localAddr = 0x02000000;

SEM_ID semAccess = 0x004c0cd0 (CREATED);

rmnINT_REGS_PTRS intrRegPtrs[4]: [0]uint8_t *ctrlRegPtr = 0x02000023; [0]uint8_t *senderIDRegPtr = 0x02000000; [0]uint8_t *vectRegPtr = 0x02000033; [1]uint8_t *ctrlRegPtr = 0x02000027; [1]uint8_t *senderIDRegPtr = 0x02000026; [1]uint8_t *vectRegPtr = 0x02000037; [2]uint8_t *ctrlRegPtr = 0x0200002b; [2]uint8_t *senderIDRegPtr = 0x0200002a; [2]uint8_t *vectRegPtr = 0x0200003b; [3]uint8_t *ctrlRegPtr = 0x0200002f; [3]uint8_t *senderIDRegPtr = 0x0200002e; [3]uint8_t *vectRegPtr = 0x0200003f;

rmnINT_DATA intrData[4]: [0]BOOL used = FALSE; [0]rmnUSER_ISR *userISR = 0x00000000 (NOT ATTACHED); [0]void *userArg = 0x00000000; [0]SEM_ID semID = CREATED; [0]uint32_t n_Sent = 0; [0]uint32_t n_Served = 0; [0]uint32_t n_SemGive = 0; [0]uint32_t n_UserISR = 0; [1]BOOL used = TRUE; [1]rmnUSER_ISR *userISR = 0x0046d9c4 (ATTACHED); [1]void *userArg = 0x007acb5c; [1]SEM_ID semID = CREATED; [1]uint32_t n_Sent = 0; [1]uint32_t n_Served = 0; [1]uint32_t n_SemGive = 0; [1]uint32_t n_UserISR = 0; [2]BOOL used = FALSE; [2]rmnUSER_ISR *userISR = 0x00000000 (NOT ATTACHED); [2]void *userArg = 0x00000000; [2]SEM_ID semID = CREATED; [2]uint32_t n_Sent = 0; [2]uint32_t n_Served = 0;

Page 44

44 VMIVME-5576 Driver User Manual - 2 VLT-MAN-ESO-15400-1375

[2]uint32_t n_SemGive = 0; [2]uint32_t n_UserISR = 0; [3]BOOL used = FALSE; [3]rmnUSER_ISR *userISR = 0x00000000 (NOT ATTACHED); [3]void *userArg = 0x00000000; [3]SEM_ID semID = CREATED; [3]uint32_t n_Sent = 0; [3]uint32_t n_Served = 0; [3]uint32_t n_SemGive = 0; [3]uint32_t n_UserISR = 0; int nodeID = 0; BOOL maskError = FALSE; BOOL fastMode = TRUE;

7.6 rmnTestBoard, rfm2gTestBoard

This function performs the test of the user memory and of the reflective memory network, on the VMIVME-5576 computing also the loopback time, that is the time needed to distribute a data item (1, 2 or 4 bytes) to all the nodes in the network ring (in the example below the network consists of 3 nodes):

lte71->rmnTestBoard(“/rmn0”) Device /rmn0: test board and link 0x79414c (tShell): WARN: rmnCmdTestBoard: Device at 0x02000000

--- loopback time = 7100 nsec ---

7.7 rmnPrintError, rfm2gPrintError

This function prints a verbose explanation of the selected error code:

lte71->rmnPrintError(-206) rmnERROR_INTERRUPT_CONFIGURED: the interrupt source was already configured!

7.8 rmnPrintCommand, rfm2gPrintCommand

This function prints a verbose explanation of the selected ioctl-command code:

lte71->rmnPrintCommand(106) rmnCMD_CONFIG_INTERRUPT: configure an interrupt source.

7.9 Troubleshooting

• VME BERR

The basic way to use the reﬂective memory is to perform direct R/W operations, after getting the information about the user memory base address. A R/W access to a wrong VME address results in a bus error, which will stop the user application:

Access Fault Program Counter: 0x00071a42 Status Register: 0x3000 Access Address : 0x01ffffff Special Status : 0x0485

5a320 _vxTaskEntry +10 : _shell (1, 0, 0, 0, 0, 0, 0, 0, 0, 0)

Page 45

VMIVME-5576 Driver User Manual - 2 VLT-MAN-ESO-15400-1375 45

444ca _shell +12e: 444e8 ([1, 0, 3, 7f, 0])

44666 _shell +2ca: _execute ([79406e, 1, 0, &_ioGlobalStdSet, eeee2a61]) 44784 _execute +a6 : _yyparse ([0, 1, 0, 79406e, 0]) 73b30 _yyparse +b98: 7195e ([4708c4, 4708e4, 0, f, f]) shell restarted.

The user is responsible not to exceed the address space corresponding to the board’s user memory. The boundaries of the user memory must be retrieved by using the two ioctl commands: rmnCMD_ADDR_GET_USER_MEM_BASE and rmnCMD_ADDR_GET_USER_MEM_TOP.

• Reﬂective memory network ring is open

Before using the reﬂective memory, the ioctl command rmnCMD_TEST_BOARD should be issued in order to check the optical link integrity. A broken link event cannot be detected during a normal R/W access. The only possibility is to monitor the bit 2 of the Control and Status Register (own data bit), but this results to be too heavy, if it is implemented for every memory access. The suggested solution is to create a separate monitoring task which checks periodically the link integrity, by using the ioctl command rmnCMD_TEST_LINK.

• PMC-5565: The board is autoconﬁgured on CPUs that support that feature (MVME-6100). However, new versions of VLTSW modules are required to use this type of conﬁguration: vltVXWORKS kernels AND bootroms 3.23.1.4. or higher, lcudrv 1.36. or higher. For the MVME-2700/2604, a PCI memory window must be conﬁgured in the vxWorks kernel. This also requires vltVXWORKS 3.23.1.4. or higher.

Page 46

46 VMIVME-5576 Driver User Manual - 2 VLT-MAN-ESO-15400-1375

Page 47

VMIVME-5576 Driver User Manual - 1.1 VLT-MAN-ESO-15400-1375 47

8 INSTALLATION

The installation of the rmn driver is done at system start-up time by script files and shall not be changed at run-time. It is composed by the installation of the driver code, the installation of the devices for that driver and the connection of the device to the driver.

8.1 Installation Prerequisites

The following hardware and software prerequisities must be fulfilled for a successful installation of the driver.

8.1.1 Hardware Requirements

The following hardware environment is required to install the driver:

• a VMEbus chassis with bus backplane and power supply

• at least one PMC-5565 or VMIVME-5576 Reﬂective Memory Board board

• one Motorola MVME167 or MVME2604 CPU board (VMIVME-5576), or MVME-2604/2700 or MVME-6100 CPU board (PMC-5565), any version

• Ethernet network

• LCU console (terminal attached to the serial line of the VMEbus CPU)

In order to use effectively the reflective memory network, the required hardware configuration consists of at least two LCUs, as stated in § 1.2.

8.1.2 Software Requirements

The following software environment is required to install the driver:

• 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

• the rmn and rfm2g modules installed on a host machine

8.2 Building the Software

The make procedure follows VLT standards, as described in [6] and [9]. In short:

1. Move to rmn src directory (cd ./rmn/src)

2. Type ‘make clean all man install’

3. Do the same for the /rfm2g/src directory

The loadable binary file rmn will be stored in “$INTROOT/vw/bin/MC68040” (if defined) respectively “$VLTROOT/vw/bin/MC68040”. The rfm2g driver is only supported on PPC boards, and will therefore be located in $INTROOT/vw/bin/PPC604 or PPC603 (or $VLTROOT, if it was installed by vltmgr).

Page 48

48 VMIVME-5576 Driver User Manual - 1.1 VLT-MAN-ESO-15400-1375

8.3 Installation Procedure

This section shows an example to install the rmn driver and the first device. The utility vltMan can be used to access man-page informations for the rmn-functions.

1. Load the rmn driver code to the target system:

-> ld < root-path/vw/bin/MC68040/rmn

2. Install the driver:

-> rmnDrv(2, 10, 100)

3. Install the ﬁrst device:

-> rmnDevCreate(“/rmn0”,32,0x02000000,256,0xd0,4)

For the rfm2g driver, the procedure is simular. It is recommended to place a copy of the rfm2g.boot file into the working environment, and edit it according to your needs:

#****************************************************************************** # E.S.O. - VLT project # # "@(#) $Id: rfm2g.boot,v 0.10 2007/07/13 09:12:05 vltsccm Exp $" # # VxWorks script for automatic installation of driver and devices # # who when what # -------- -------- ---------------------------------------------# rfrahm 30/05/07 created

# # NOTE: # ===== # On Single and Dual CPU Systems, based on MVME2600, # RFM2G seen at 0x60000000 # One RFM2G board needs 128MB memory + 0x2000 register space # On Single and Dual CPU Systems, based on MVME6100, # RFM2G uses autoconfiguration. Use rfm2gDevShow to show memory mapping # # This file MUST be accordingly modified locally in the environment directory. # # check if "/rfm2gX" is present in the system and register it: # A32 autoconfiguration for MVME-6100 CPUs rfm2gN = lcubootAutoDevRegister("/rfm2g0",0x80,0x0,0,0x114A5565,0x280) rfm2gN = lcubootAutoDevRegister("/rfm2g1",0x80,0x0,1,0x114A5565,0x280)

# install the driver if any devices were found: # Note: On autoconfig BSPs, the last parameter (address) is ignored. lcubootAutoDrvInstall("rfm2g",100,"rfm2gDrv","rfm2gDevCreate",2,30,100,0x60000000)

# install device "/rmnX" if present: # A32 configuration # !!! MAXIMUM are 2 boards per CPU (for MVME-6100 CPUs) !!! lcubootAutoDevCreate("/rfm2g0") lcubootAutoDevCreate("/rfm2g1")

8.4 Installation Verification

Functions performed during installation phase always log OK or ERROR messages to the console.

The tools described in a previous section can be used to test that the driver and the device have been

Page 49

VMIVME-5576 Driver User Manual - 1.1 VLT-MAN-ESO-15400-1375 49

installed correctly. From the VxWorks shell issue the following commands:

• rmnVersion/rfm2gVersion should print the expected version number on the console.

• rmnDevShow/rfm2gDevShow should print the table of installed rmn devices.

• VMIVME-5576 only: rmnDevDump “/rmn0” should print the contents of the board’s registers in a formatted way.

• VMIVME-5576 only: rmnDevDescr “/rmn0” should print the contents of the device descriptor.

• rmnTestBoard “/rmn0” (VMIVME-5576)

rfm2gTestBoard “/rfm2g0”

should test the board, link, and print the network loopback time (VMIVME-5576 only).

Page 50

50 VMIVME-5576 Driver User Manual - 1.1 VLT-MAN-ESO-15400-1375

Page 51

VMIVME-5576 Driver User Manual - 1.1 VLT-MAN-ESO-15400-1375 51

9 REFERENCE

Man-pages of all public driver functions for “rmn” in alphabetical order.

For rfm2g, the man pages are extremely similar and therefore not repeated.

Page 52

52 VMIVME-5576 Driver User Manual - 1.1 VLT-MAN-ESO-15400-1375

9.1 rmnClose(3)

NAME

rmnClose - Close a channel to a RMN device

SYNOPSIS

#include "rmnPrivate.h" int rmnClose ( int channel => <IN> channel to be closed )

DESCRIPTION

This routine is called when a channel of a RMN device shall be closed. It represents an interface routine between the special RMN driver routines and the general lcudrv driver routines.

RETURN VALUES

lcudrvOK : successful completion lcudrvERROR_INVALID_ARGUMENT : invalid channel number lcudrvERROR_NO_CHANNEL : channel was not open

SEE ALSO

rmnOpen(3), rmnIoctl(3), lcudrvClose(3), open(2), close(2), ioctl(2)

- - - - - Last change: 02/07/98-18:05

Page 53

VMIVME-5576 Driver User Manual - 1.1 VLT-MAN-ESO-15400-1375 53

9.2 rmnDevCreate(3)

NAME

rmnDevCreate - Add a device to the RMN driver

SYNOPSIS

#include "rmn.h" int rmnDevCreate ( char *devName, => <IN> device name int addrSpace, => <IN> address space selection void *baseAddr, => <IN> VMEbus base address of the board int memOption, => <IN> board's memory option (rmnMEM_256KB or rmnMEM_512KB or rmnMEM_1MB) int intrNumber, => <IN> interrupt-vector-number of the first device interrupt source int intrLevel => <IN> level of the device interrupt )

DESCRIPTION

This function is called at startup once for each device to be installed. It adds a device to the driver, making it available for subsequent open operations. The successful completion of the function is shown by the switching off of the led on the board's front panel.

devName: <IN> is the device name, consisting of the prefix "rmn" and a number: must be "/rmnX" X>=0, e.g. "/rmn0". addrSpace: <IN> selects the board's address space, rmnVME_ADD_A24 | rmnVME_ADD_A32, according to the setting of the jumper 10. baseAddr: <IN> is the VMEbus base address of the board in the A24 or A32 standard address space. If the board is configured in the A24 address space, the upper 8 address-bits are ignored. The special address 0xffffffff means that the board register space is mapped into main memory for simulation. memOption: <IN> selects the amount of memory actually installed on the board: rmnMEM_256KB | rmnMEM_512KB | rmnMEM_1MB. intrNumber: <IN> is interrupt-vector-number of the first device interrupt source. The RMN device has 4 possible interrupt sources, then this function will reserve 4 interrupt vectors in the CPU vector table, from <intrNumber> to <intrNumber>+3. <intrNumber> will be connected to an internal handler, which serves the local interrupt source INT0 (see board's documentation and rmn.doc). The other three vectors <intrNumber>+1 .. <intrNumber>+3 can be attached to user provided interrupt handler serving the remote interrupt sources (INT1-INT3). intrLevel: <IN> is the level of the device interrupt. It is the same for all the 4 interrupt sources.

RETURN VALUES

lcudrvOK : successful completion lcudrvERROR_INVALID_ARGUMENT : one of the arguments is not valid lcudrvERROR_NO_DRIVER : RMN driver not installed lcudrvERROR_INVALID_DEVICE : invalid device name or device number lcudrvERROR_DEVICE_EXISTS : device already installed rmnERROR_INVALID_BOARD_ID : no RMN board found at the specified VME address rmnERROR_INVALID_VME_ADDR : no HW found at the specified

Page 54

54 VMIVME-5576 Driver User Manual - 1.1 VLT-MAN-ESO-15400-1375

VME address rmnERROR_BAD_DATA : test of the board's user memory failed rmnERROR_LINK_BROKEN : test of the link integrity failed lcudrvERROR_NO_SEMAPHORE : failed to create semaphore lcudrvERROR_NO_MEMORY : failed to create object in memory lcudrvERROR_TIMEOUT : failed to take semaphore before timeout

CAUTIONS

This function must be called by at CPU startup time, normally by a single task configuring sequentially all the supported RMN devices. No protection is implemented on the driver global variables. Any call to the open, close and ioctl functions must be done only after having succesfully completed the installation of all the RMN devices supported by the CPU.

SEE ALSO

rmnDrv(3), rmnOpen(3), rmnClose(3), rmnIoctl(3), iosLib(1), iosDevAdd(2), open(2), close(2), ioctl(2) rmnBoard(4)

- - - - - Last change: 02/07/98-18:05

Page 55

VMIVME-5576 Driver User Manual - 1.1 VLT-MAN-ESO-15400-1375 55

9.3 rmnDrv(3)

NAME

rmnDrv - Install the Reflective Memory Network driver (RMN)

SYNOPSIS

#include "rmn.h" int rmnDrv ( int devices, => <IN> maximum number of supported devices by the driver (> 0) int channels, => <IN> maximum number of channels that can be simultaneously opened (> 0) int timeout => <IN> access timeout value in ticks (> 0) or NO_WAIT or WAIT_FOREVER )

DESCRIPTION

This function installs the RMN device driver. It is called only once at startup. It hooks up the various I/O service calls to the driver's functions, assigns the driver number, and adds the driver to the driver table. The timeout parameter is valid for all the devices configured for this driver and determines the maximum waiting time when accessing a RMN device (time to wait when taking the device access semaphore).

RETURN VALUES

lcudrvOK : driver successfully installed lcudrvERROR_DRIVER_EXISTS : the driver is already installed lcudrvERROR_NO_MEMORY : there is not enough memory for dynamic data structures lcudrvERROR_INVALID_ARGUMENT : the value of one of the parameters is out of range

CAUTIONS

This function must be called only once, at CPU startup time, before any call to rmnDevCreate(). No protection is implemented on the driver global variables.

SEE ALSO

rmnDevCreate(3), rmnOpen(3), rmnClose(3), rmnIoctl(3), lcudrvInitDCT(3), iosLib(1), iosDrvInstall(2), open(2), close(2), ioctl(2)

- - - - - Last change: 02/07/98-18:05

Page 56

56 VMIVME-5576 Driver User Manual - 1.1 VLT-MAN-ESO-15400-1375

9.4 rmnIoctl(3)

NAME

rmnIoctl - Send a control command to a RMN device

SYNOPSIS

#include "rmnPrivate.h" int rmnIoctl ( int channel, => <IN> channel number int command, => <IN> number identifying the operation to be performed by the driver (as defined in 'rmnCommands.h') void *argument => <IN> address of the command argument or NULL if no argument is used. )

DESCRIPTION

This routine is called when a control command is sent to a RMN device via ioctl(). It validates the command request, performs a semaphore protection, if required, and calls the command procedure to be executed.

RETURN VALUES

lcudrvOK : successful completion lcudrvERROR_INVALID_ARGUMENT : invalid channel number lcudrvERROR_CHANNEL_NOT_OPEN : channel was not open lcudrvERROR_INVALID_COMMAND : command code invalid lcudrvERROR_ACCESS_CONFLICT : insufficient access rights lcudrvERROR_TIMEOUT : failed to take semaphore before timeout

SEE ALSO

rmnOpen(3), rmnClose(3) lcudrvCheckChannel(3), open(2), close(2), ioctl(2)

- - - - - Last change: 02/07/98-18:05

Page 57

VMIVME-5576 Driver User Manual - 1.1 VLT-MAN-ESO-15400-1375 57

9.5 rmnOpen(3)

NAME

rmnOpen - Open a channel to a RMN device

SYNOPSIS

#include "rmnPrivate.h" int rmnOpen ( void *device, => <IN> pointer to the device descriptor char *remainder, => <IN> remainder of the device name int mode, => <IN> open mode int *status => <OUT> pointer to the returned status value (NULL: not returned) )

DESCRIPTION

This function is installed in the I/O-system of VxWorks and is called via open() when a channel to a RMN device shall be opened. It represents an interface routine between the RMN driver routines and the general lcudrv driver routines.

RETURN VALUES

channel number (>= 0) : successful completion lcudrvERROR : error (detailed in <*status>)

In <*status>: lcudrvERROR_INVALID_DEVICE - remainder not blank/invalid name lcudrvERROR_ACCESS_CONFLICT - open mode not consistent lcudrvERROR_NO_CHANNEL - no more channel available lcudrvERROR_INVALID_OPEN_MODE - unknown open mode

SEE ALSO

rmnClose(3), rmnIoctl(3), lcudrvOpen(3), open(2), close(2), ioctl(2)

- - - - - Last change: 02/07/98-18:05

Page 58

58 VMIVME-5576 Driver User Manual - 1.1 VLT-MAN-ESO-15400-1375

9.6 rmnTools(1)

NAME

rmnVersion, rmnDevShow, rmnDevDump, rmnMemDump, rmnDevDescrDump, rmnTestBoard, rmnDevDelete, rmnDevDeleteAll, rmnDrvRemove, rmnPrintError, rmnPrintCommand - Support functions of the RMN driver

SYNOPSIS

#include "rmn.h" void rmnVersion(void)

int rmnDevShow(void)

int rmnDevDump ( char *name => <IN> device name ("/rmnX") )

int rmnMemDump ( char *name => <IN> device name ("/rmnX") )

int rmnDevDescrDump ( char *name => <IN> device name ("/rmnX") )

int rmnTestBoard ( char *name => <IN> device name ("/rmnX") )

int rmnDevDelete ( char *name => <IN> device name ("/rmnX") )

int rmnDevDeleteAll(void)

int rmnDrvRemove(void)

int rmnPrintError(int errorCode)

int rmnPrintCommand(int cmdCode)

DESCRIPTION

rmnVersion - Prints the version of the RMN driver to the LCU console rmnDevShow - Prints a list of installed RMN devices to the LCU console rmnDevDump - Prints the device registers in a formatted way

Page 59

VMIVME-5576 Driver User Manual - 1.1 VLT-MAN-ESO-15400-1375 59

rmnMemDump - Prints the device registers in hexadecimal rmnDevDescrDump - Prints information on the device descriptor rmnTestBoard - Test the board and prints the link loopback time rmnDevDelete - Deletes the device from the I/O system rmnDevDeleteAll - Deletes all the RMN devices from the I/O system rmnDrvRemove - Removes the RMN driver from the driver table, forcing the closure of all the open channels. It deletes also all the RMN devices, if not already done. rmnPrintError - Prints an error string corresponding to the given error code rmnPrintCommand - Prints a command string corresponding to the given command number

RETURN VALUES

rmnVersion N/A

rmnDevShow OK : successful completion lcudrvERROR_NO_DRIVER : the driver is not installed.

rmnDevDump OK : successful completion lcudrvERROR_NO_DRIVER : the driver is not installed. lcudrvERROR_INVALID_DEVICE : the device name was not found in the RMN device table.

rmnMemDump OK : successful completion lcudrvERROR_NO_DRIVER : the driver is not installed. lcudrvERROR_INVALID_DEVICE : the device name was not found in the RMN device table.

rmnDevDescrDump OK : successful completion lcudrvERROR_NO_DRIVER : the driver is not installed. lcudrvERROR_INVALID_DEVICE : the device name was not found in the RMN device table.

rmnTestBoard OK : successful completion Error codes from rmnOpen and rmnCmdTestBoard functions.

rmnDevDelete OK : successful completion lcudrvERROR_NO_DRIVER : the driver is not installed. lcudrvERROR_INVALID_DEVICE : the device name was not found in the RMN device table. lcudrvERROR_TIMEOUT : timeout while accessing the device (waiting time was longer than the driver timeout parameter) rmnERROR_INVALID_SEMAPHORE_ID : semaphore deletion failed rmnERROR_OPEN_CHANNELS : open channels found

rmnDevDeleteAll Same return values as from rmnDevDelete.

rmnDrvRemove OK : successful completion lcudrvERROR_NO_DRIVER : the driver is not installed. Error codes from rmnDevDelete

Page 60

60 VMIVME-5576 Driver User Manual - 1.1 VLT-MAN-ESO-15400-1375

rmnPrintError lcudrvOK : successful completion lcudrvERROR: invalid error code

rmnPrintCommand lcudrvOK : successful completion lcudrvERROR: invalid command number

CAUTIONS

Before calling rmnDevDelete and rmnDevDeleteAll, all the file descriptors open on a RMN device must be closed, otherwise the call will fail. rmnDrvRemove guarantees the closure of open channels before removing the driver and deleting the devices.

SEE ALSO

iosDevDelete(2), iosDrvRemove(2)

- - - - - Last change: 02/07/98-18:05

___oOo___