Add DIO interface to Linux Holography Backend Software

Modification Request #12 (C5, 2007)

1. Introduction

The holography backend was originally deployed years ago on a VxWorks system with an MCB interface. The system was limited to 200 ms dumps due to the combination of the VxWorks OS and the MCB interface. We need the backend to dump much faster in order to properly map the GBT's panels.

2. Background

Back in the day, the Holography backend was connected to gbtaio1, a 68040 VxWorks single-board. This worked fairly well for slow dumps, but was the limiting factor in trying to do holography on the telescope panels. We are in the process of replacing this MCB interface with a parallel interface based on an off-the-shelf parallel interface card. The card will allow the backend to dump in less than 20 milliseconds, providing the order of magnitude increase in speed needed. The parallel card will be plugged into a Linux box co-located in the receiver room shielded rack with the backend.

This MR depends on the successful completion of ModificationRequest1C307.

3. Requirements

Requirements for this MR are fairly straightforward. A new host platform and operating system is required, and a new interface to the data stream and the command stream will be created. No new manager parameters or sampler values will be needed, that is, the external interface to the M&C system will remain unchanged, except for the volume of data recorded, and the legal command values for integration time. It is not a requirement to maintain compatability with the vxWorks platform.

Platform
- The system will be hosted on a standard RTAI-Linux platform of latest vintage. The system will be a shoebox computer.
- The interface card will be a DIO-48 digital I/O PCI card. A driver for this card has been written for general purpose use, and will be modified by Tim Weadon for use in this manager.
- The electronics division will provide a guide which describes the mappings between registers on the I/O card and functions in the holography backend. The document shall include specifications for any critical timing elements (e.g. strobe pulses must be x microseconds wide etc.).
Data rates
- The system will be configured to support dumping the memory at a 1 KHz rate. This is a small amount of data, and should pose no problems. The actual dump rates will probably not be this high, but the software design should allow for it.
- Commands will be passed to the backend only during the standard M&C states when parameters can be activated, and so should not be a factor.

Initial time-line requirement for completion of this MR is 01 August 2007.

4. Design

In ModificationRequest1C307, the manager was ported to Linux and the MCB interface retained. The final configuration, as delivered by this MR, shall use a digital I/O card. A hardware abstraction layer/class will define logical/functional methods for the manager to interact with, independent from the actual hardware interface. For example, setAttenuatorLevel(x) will be implemented by the hardware abstraction as a MCB write call or a write to the digital I/O card. The MCB interface uses a busy-wait poll while waiting for data, in contrast the parallel digital I/O setup will allow an interrupt driven approach. The hardware abstraction will appear as being event-driven, that is it will appear to be interrupt driven in all cases.

The data flow out of the backend will be managed by the hardware abstraction. When new data is available, the software will read the data through the MCB or PIO port and timestamp the data. A callback will be made to the manager, to indicate new data is available. The manager will then determine if the data is to be written, and if so the data will be sent to the FITS writer class for writing into a FITS file.

4.1 Hardware Architecture

The existing MCB interface will be replaced by a design which uses 32 bits of a 48-bit digital I/O card. 16 bits will be used for data, and 8 bits for address. The remaining bits will be used for device control. Interrupts will be generated by the digital I/O card indicating when either data is available or an urgent condition exists. An unofficial block diagram is shown below.

Hardware Architecture

Figure 1

4.2 Software Architecture

The software architecture will be similar in nature to other M&C managers. Device functionality is encapsulated by the HolographyDevice class, which employs a "has-a" relationship with a device interface class such as the SIB or DIO driver (Modelled after the adapter/bridge patterns). The encapsulation should include a mechanism for simulation. Backend data is recorded by the HolographyFits writer class. At the core is the Holography manager, which ties everything together and provides an implementation of the device's parameter set.

Software Architecture

Figure 2

I've noted a number of items which exist in the current code, and should be addressed. The items include:

Eliminate calls to getParameter() outside of parameter check methods. The manager should use cached versions of the activated values instead.
There is no longer a requirement for a host-based FITS server/writer. (The original reason was due to the lack of a FITS writing library on vxWorks.) The Holography manager application should use a local FITS writer based on the current FitsIO library.
Data acquisition is performed in-line with the sequencer task. This should be separated out.
The vxWorks style task and semaphore calls should be replaced by the more modern Mutex (mutual exclusion), TCondition (inter-thread synchronization), and McCondition (time-synchronized semaphore) objects.
The code base has many #if-defs for the purposes of running in simulation mode. The code should partition simulation inside the device interface libraries.

4.3 Software Code Modules

4.3.1 Hardware Abstraction Class

The hardware interface class (HolographyDevice) defines the following logical methods for interacting with the hardware. The implementation of the hardware interface will be controlled by values in a configuration file.

set_starttime(TimeStamp &)
reset()
init_data_callback()
init_error_callback()
set_integration_time(float)
set_cycles_per_integration(int)
set_attenuator_level()
set_reference_attenuator_level(int)

Each of these methods is described below:

set_starttime(TimeStamp&): This method informs the hardware interface that data acquisition should begin at the time specified. If the specified time is zero, then the data acquisition should begin as soon as practicable.
reset(): This method will end data acquisition, and reset the hardware to a known quiescent state.
init_data_callback(): This method is used to setup the callback to a manager method, which will handle the incoming data. The manager method callback should take a single HolographyData parameter. Note that this method once registered will be called even after the scan stop-time is reached, until a reset() is called.
init_error_callback(): This method is used to setup the callback to a manager method, which will handle the errors from the Holography backend. The manager method callback should take a single HolographyError parameter.
set_integration_time(float): This method sets the hardware integration time in seconds. The value must be in multiples of TBD. If a value cannot be exactly set, the value will be rounded to the nearest possible value.
set_cycles_per_integration(int): This method set the number of integrations to be accumulated in the hardware before being read.
set_attenuator_level(float): This method sets the attenuator level for the main signal (also designated as the 'test' signal). Possible values are: TBD If an intermediate value is given, the value will be rounded to the nearest legal value.
set_reference_attenuator_level(float): This method sets the attenuator level for the reference signal. Possible values are TBD. If an intermediate value is given, the value will be rounded to the nearest legal value.

These methods will be tailored specifically for the parallel DIO card. Specific information about the required calls to make within the PDIO instance of the HolographyDevice, to interface with the parallel DIO card will be determined in consultation with TimWeadon.

Typical manager-hardware interface class will be as follows:

Construct the HolographyDevice
Setup data and error callbacks by calling init_data_callback() and init_error_callback()
From the manager parameter activate methods, set the corresponding values. (e.g. set_cycles_per_integration() .)
From the manager's doActivate() method, call set_starttime() with the activated starttime.
Handle data callbacks as data arrives.
Handle error conditions when the error callback occurs.
Call reset() to end data acquisition.
Repeat 3-7 as necessary.
Destruct HolographyDevice Object. (This will call reset() prior to deletion.)

5. Documents and Specifications

The documents required for this modification are found in the drawing archive in the directory /home/doc/drawings/archive/gbtelec/35205. Project 35205 is the Holography project. The schematic for the interface is 35205S008. Documentation on the Holography backend can be found in the document http://www.gb.nrao.edu/GBT/memos/memo101.html. A simple writeup in MS-Word format can be found in d006.doc in the 35205 directory. The author of this document is not declared, it was written in 1997 at the time of the new interface card implementation. A more detailed document, in MS-Excel format, can be found in the 35205 directory named CorrelatorREVA?.xls. This document was originally written by Steve White then later updated by Tim Weadon in May 2007. This document provides layout of the command registers and data registers. The memo gives you detailed information about each register.

Within the SDD documentation set, GBT Software Project Note GBT/SPN/009 descrbing the Holography FITS data file format and content will be restored or created, and updated to reflect data pedigree.

6. Deployment Checklist

What has to get done to integrate this completely into the system. This checklist must be completed before Cycle Integration Testing begins.

Communication with Computing group needed
- A new Linux host will be added to the receiver room Ethernet switch
What documentation needs to be updated?
- The Holography system drawings and manuals need to be updated. This will be accomplished by Electronics.
Training Needed? Is this being released to staff astronomers or everyone right now?
- This is a test system, and will not be released for general use. PTCS scientists are the customers.
Notification Needed?
- No

7. Test Plan

We will set up the system in the lab for testing. A simulator for the parallel interface should be developed to allow testing apart from the backend hardware to avoid linking the hardware and software modifications more than necessary. A full system test will include dumping simulated data through the simulated parallel port, and writing it to disk.

7.1 Internal Testing

The modified system should be throughly tested both using a simulated data stream, and the actual backend. The following tests should be completed at a minimum:

Simulated command processing
- The system should be commanded using Device Explorer and the existing command set, with the new integration time limits installed. The simulated commands should be correctly passed through the manager to the simulated parallel interface port registers.
Simulated data collection
- The data collection process should be simulated using a RTAI-linux task to generate test data and interrupts. The data should be collected and sent through the M&C system and written to FITS files. The timestamps on the data must be verified as well as the data values themselves
- The timestamp statistics for the data need to be analyzed to tell us how much jitter in the sampling we should expect.

An RTAI-linux based machine is identified for use in testing, hostname cetus.

7.2 Sponsor Testing

Test commanding the system with Astrid and/or Cleo
Hardware in the loop testing
- The above tests should be repeated using the holography backend and some artificial signal inputs to the backend's IF ports. These signals will be defined and provided later by the RF engineers in charge of the project.
- Timestamp testing should be done with an oscilloscope on the interrupt pin to find out the actual frequencies, latencies, and jitter on the data collection process.

7.3 Integration/Regression Tests

Confirm that the Astrid/Cleo/FITS writers are all cooperating

SPECIAL: Design Review Links

These links are to documents requested for Design Review meeting to be help 24 March 2008.

Signatures

APPROVED: I acknowledge that my request is mostly contained in this MR, and if the SDD delivers exactly what I specified, I might be happy.

ACCEPTED: I acknowledge that I have validated the completed code according to the acceptance tests, and I am happy with the results.

Written	- RonGrider - 24 July 2007
Checked	- TimWeadon - date
Approved by Sponsor	- JohnFord - 10 Aug 2007
Approved by CCC	- RonMaddalena - 31 Oct 2007
Accepted/Delivered by Sponsor	symbol - name - date

Symbols:

Use %X% if MR is not complete (will display )
Use %Y% if MR iscomplete (will display )

CCC Discussion Area

-- RonGrider - 19 Jul 2007

Attachment:	Action:	Size:	Date:	Who:
holohwarch.png	action	5372	23 Jul 2007 - 19:52	RonGrider
Holography_Diagrams_PortedDesign_TopLevel_r2.jpg	action	165674	23 Jul 2007 - 20:01	RonGrider
HolographyMR12C507_UML_DesignDiagrams.vsd	action	363008	21 Mar 2008 - 00:45	RonGrider
HolographyMR12C507_UML_ClassDiagram.jpg	action	51089	21 Mar 2008 - 00:45	RonGrider
HolographyMR12C507_UML_SequenceDiagram.jpg	action	147198	21 Mar 2008 - 00:46	RonGrider
Component_Diagram_for_RT_in_Holography_Manager.ppt	action	62464	21 Mar 2008 - 00:49	RonGrider
Component_Diagram_for_RT_in_Holography_Manager.pdf	action	90505	21 Mar 2008 - 00:49	RonGrider

Topic ModificationRequest12C507 . { Edit | Attach | Ref-By | Printable | Diffs | r1.7 | > | r1.6 | > | r1.5 | More }

Revision r1.7 - 21 Mar 2008 - 00:57 GMT - RonGrider Parents: PlanOfRecordC52007	Content copyright © 1999-2007 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.


NRAO Home > Green Bank \| Wiki Topic: GB > Software > PlanOfRecordC52007 > ModificationRequest12C507

Changes \| Index \| Contents \| Search \| Statistics \| Go