NRAO Home  >  Green Bank  |  Wiki Topic:    GB > Software > PlanOfRecordC32007 > ModificationRequest1C307

Changes | Index | Contents | Search | Statistics | Go

Port Holography Backend Software

Modification Request #1 (C3, 2007)

• 1. Introduction
• 2. Background
• 3. Requirements
• 4. Design
  • 4.1 Hardware Architecture
  • 4.2 Software Architecture
  • 4.3 Software Code Modules
    • 4.3.1 Hardware Abstraction Class
    • 4.3.2 The FITS Writer Class
    • 4.3.3 Classes Removed
  • 4.4 Supporting Software Environment
• 5. Documents and Specifications
• 6. Deployment Checklist
• 7. Test Plan
  • 7.1 Internal Testing
    • 7.1.1 Original Configuration Testing
    • 7.1.2 Testing Ported Holography Software
  • 7.2 Sponsor Testing
  • 7.3 Integration/Regression Tests
• Signatures
• CCC Discussion Area

1. Introduction

2. Background

3. Requirements

• 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 the existing SIB card accessed via the MCB bus.
• Data rates
  • 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

The Holography backend manager will be ported and the MCB interface retained. Porting will be accomplished in a series of stages; however, only the final product will be released. The port will involve a redesign to abstract the hardware interface, a merging of the FITS writing server (HoloServer) into a local FITS writer class, and a refactoring to replace the VxWorks task control and synchronization primitives with pthread or RTAI based replacements.

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 write call to the specific hardware via its abstracted interface. The MCB interface uses a busy-wait poll while waiting for data.

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

4.2 Software Architecture

Software Architecture

Figure 1

A number of items in the current code require rework, to bring into line with current M&C manager practices and design. These 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

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

Typical manager-hardware interface class will be as follows:

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

4.3.2 The FITS Writer Class

There has been some discussion about the addition of a few new data table columns. The addition should have minimal or no impact on the implementation.

The class interface consists of the following methods:

set_periods_per_integration(int)

Sets the value for the NCYCLE header keyword.

set_period_length(double)

Sets the value for the DURATION keyword.

set_integration_time(double)

Sets the value for the CYCLETIME keyword.

set_start_time(TimeStamp const &)

Sets the start-time. This method must be called prior to the open() method, as the value is used for the file name.

set_scan_number(int)

Sets the value for the SCAN keyword.

set_project_id(String const &)

Sets the value for the PROJID header keyword. This method must becalled prior to the open() method, as the value is used for the file name.

set_scan_id(String const &)

Sets the value for the OBSID keyword.

set_source_id(String const &)

Sets the value for the OBJECT keyword.

set_test_attenuation(int)

Sets the value for the TESTATTN keyword. The value is in db of attenuation.

set_ref_attenuation(int)

Sets the value for the REFATTN keyword. The value is in db of attenuation.

open()

Causes the writer to open a new file based on the current settings of starttime, and project_id.

write(HolographyData &)

This method queues a row of data to be written to the FITS file. If the file is not currently open, the data is ignored.

close()

Closes an open FITS file.

Typical manager-FITS writer interactions will be:

1. Construct the HolographyFits object.
2. In each parameter's check method, if the check passes, call the corresponding set method. For the manager base class parameters, call the set method from the associated activate method. (e.g. activateStartTime(), activateProjectId(), activateScanLength(), activateSource activateNextScanNumber() and so on.)
3. Call the method open() from the manager's doActivate() method, after the call to the Manager::doActivate(). Note: open() should be called only if the starttime is non-zero, this indicates a scan is starting.
4. Call write() when data is available to write to the file.
5. Call close() from the doComplete() method.
6. Repeat steps 2-5 for every scan.
7. Destruct the HolographyFits object. This will automatically call the close() method if a file is open.

4.3.3 Classes Removed

4.4 Supporting Software Environment

5. Documents and Specifications

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

• 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

7.1 Internal Testing

7.1.1 Original Configuration Testing

Because the original MCB interface card has been modified, then had those modifications removed, our initial test will require reassembling and testing the original configuration in a lab. Holography backend with MCB interface card, interfaced to a VxWorks computer executing the current Holography manager (release 7.2 of M&C software), with a test data card activated in the Holography backend to emulate a data stream. This configuration will be used with the M&C and Sparrow software testbed, and tested to verify that test data is received from the backend, and that full control of the backend is available via the CLEO Holography screen.

7.1.2 Testing Ported Holography Software

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

• Visibility to control software
  • Holography Manager should be visible as a TaskMaster process via TaskMaster status reports, and discovered automatically by the CLEO TaskMaster application.
• 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

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 - 24 July 2007
Approved by Sponsor	- JohnFord - 07 Aug 2007
Approved by CCC	- RonMaddalena - 10 Aug 2007
Tested with hardware	- StevenWhite - 20 Sep 2007
Accepted/Delivered by Sponsor	- ToddHunter - 20 Sep 2007

Symbols:

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

CCC Discussion Area

-- JohnFord - 30 Mar 2007

Attachment:	Action:	Size:	Date:	Who:	Comment:
Holography_Diagrams_PortedDesign_TopLevel_r1.jpg	action	57373	23 Jul 2007 - 15:37	RonGrider
CorrelatorREVA.xls	action	23552	24 Jul 2007 - 20:36	RonGrider