April 30, 2004

Overview

Version 0.5.1 is a beta release of the Channelization API for DPL3 and LightParser Boards.

The "Channelization API Reference Manual", "DPL3 Hardware Reference Manual" and "Light Parser Hardware Reference Manual" describe details of the currently supported and unsupported features in the API and hardware.

The following changes are introduced in this release:

• LightParser: Bug fixes for STM-1 File-to-File processing.

• LightParser: Bug fixes for grooming configuration.

• LightParser: Bug fixes for the dplp_portcfg program.

• LightParser: Modified Quad-E3 interface initialization.

• LightParser: Fixed bug in raw STM-1 receive.

• DPL3: New API function to wait for framer sync.

• DPL3: Implemented handling of E3 framer status queue interrupts.

• API: New channel buffer mapping function replaces MAPBUF mode flag.

• Device Driver: Improved handling of channel overflow.

• Device Driver: Added initialization of framer status queue interrupt mode.

• Modified utility programs.

• Modified diagnostic programs.

• New and modified demonstration programs.

• Changes to FPGA configurations.

• Component versions for this release.

Notes:

This release includes new FPGA configurations for LightParser and DPL3 boards. Run the dplp_flashup or dpl_flashup program to update the FPGAs on the boards.

Normally software releases with the same major and minor version numbers are meant to be compatible. However, for LightParser, version 0.5.1 includes modifications to Virtex FPGA and API functions for E4 and STM-1 extraction that are not compatible with those in version 0.5.0.

This release is intended for evaluation purposes and does not represent the intended final production release. Some aspects of the application program interface (API) are subject to change as the software development continues to meet design requirements and usability issues.

LightParser: Bug Fixes for STM-1 File-to-File Processing

The API functions supporting file-to-file configuration and the dplp_streams program include bug fixes for configuring STM-1 host transmit streams for file-to-file processing.

LightParser: Bug Fixes for Grooming Configuration

The API functions for grooming is fixed to properly read grooming maps.

The dplp_groom program includes bug fixes and improved reporting of error and status information.

LightParser: Bug Fixes for the dplp_portcfg Program

The dplp_portcfg program is modified to not assume transmit or receive modes for Quad-E3 port configuration.

A bug is fixed in the dplp_portcfg program for configuring extraction of E4 streams embedded in STM-1 signals from the optical and CMI ports.

LightParser: Modified Quad-E3 Interface Initialization

The Quad-E3 interface initialization performed by the cac_quade3_init API function now enables to "Mute on LOS" mode for the Quad-E3 channels being initialized. This causes raw E3 receive channels to read all zeros instead of garbage data if a valid incoming signal is not present.

LightParser: Fixed Bug in Raw STM-1 Receive

Modifications to the Virtex FPGA configuration solve timing problems that was corrupting received data from raw STM1 extraction for the optical and CMI ports.

The changes in the FPGA design required some register address and bit assignments that forced modifications to the API functions that configure level 4 (STM-1 and E4) signal extraction. Therefore, the version 0.5.1 of the Virtex FGPA and the API are not compatible with version 0.5.0.

DPL3: New API Function to Wait for Framer Sync

The new function, cac_chan_waitsync, is provided for applications to delay reading from receive channels until the channel's framer is in sync or to simply determine the current status of the framer's sync state.

This function is useful prior to starting read operations as well as a way of handling the occurrence of loss of sync.

Arguments to the function include a length of time to wait for the framer to be in sync and an amount of data to wait for and discard to make sure the framer is in stable sync. See the API documentation for details.

DPL3: Implemented Handling of E3 Framer Status Queue Interrupts

Framer status entries in the interrupt queue indicating the L3 framer's RxLOS (loss of signal) and RxOOF (out of frame) status are now handled by the device driver (for both Linux and Solaris). These events provide loss of sync status for raw and bulk E3 and DS3 receive channels.

The API is modified to enable RxLOS events for raw E3 or DS3 channels and to enable both RxLOS and RxOOF events for bulk E3 or DS3 channels.

Currently, the hardware continues to feed data to E3 or DS3 receive channels regardless of the RxLOS or RxOOF status. A future revision will stop received data under these conditions. In the meantime, the cac_chan_waitsync may be used to avoid reading the incoming data and channel overflow that might occur.

API: New Channel Buffer Mapping Function Replaces MAPBUF Mode Flag

The new cac_chan_mapbuf function is provided for applications that need to map the channel buffers into the application's memory space. Examples of such applications are those that use the cac_chan_io function to access channel data directly, without using the cac_chan_read and cac_chan_write functions to copy data between the channel buffers and the applications data buffers.

This function replaces the CAC_CHAN_MODE_MAPBUF flag that was included in the modes argument to the channel open functions. Applications using mapped channel buffers will have to remove this flag and call the cac_chan_mapbuf function after successfully opening the channel.

The complimentary function, cac_chan_unmapbuf, is also provided for applications that want to temporarily map a channel buffer. However, the buffer will be unmapped automatically when a channel is closed.

Device Driver: Improved Handling of Channel Overflow

The device driver queue handler (both Linux and Solaris) used to handle receive channel overflows by adjusting the buffer pointers to leave a full buffer of data available. This tended to perpetuate an overflow condition once one had occurred.

The device drivers are now modified to handle overflows for receive channels by setting the buffer pointers and available data counts such that no data is available in the buffer. This essentially erases any data currently in the buffer, which may have been corrupted by the overflow, and allows the application a chance to catch up and read fresh data as it becomes available.

Device Driver: Added Initialization of Framer Status Queue Interrupt Mode

The device driver for both Linux and Solaris is modified to ensure that framer status queue interrupts are disabled when the driver is loaded and when the board is initialized by the CAC_RESET ioctl request which is invoked by the dpl_init and dplp_init programs.

Note that these status queue interrupts are not currently implemented for LightParser.

Modified Utility Programs

In addition to the utility program changes described above, the following changes to programs are included:

The dplp_init and dpl_init programs are modified to report when the LightParser Virtex FPGA or DPL3 expansion FPGA is reconfigured by the -R option.

The dpl_init and dpl_flashup programs (for DPL3) are modified to not display warnings about not finding configuration files for the expansion FPGA for boards that do not have the expansion FPGA populated.

The dpl_find program is modified to report the PCIbus VIO voltage and note if the host and FPGA VIO values do not match.

Modified Diagnostic Programs

The dpl_chantest and dplp_chantest programs include the following new features:
• The -x option can now be given a negative number for its parameter which indicates that receive channels should not actually test for the pattern. This is for removing processing overhead to test purely for data throughput. The -x option is now referred to as the "pattern mode" rather than "transmit mode" because it also affects the pattern checking for receive channels.
• New -n option to test non-blocking mode channels.
• The DPL3 version now uses the cac_chan_waitsync when loss of framer sync is detected. New -Y option is used to specify parameters for the function.

The dmatest, alloctest and chantest programs for DPL3 and LightParser are modified to use the new cac_chan_mapbuf function.

New and Modified Demonstration Programs

A new DPL3 program, dpl3_multirec is included to demonstrate how to open multiple receive channels of various types (E1 and/or E3) and handle each in its own thread.

Minor changes in the status display are made to the dpl3_e1rec and dpl3_slotrec DPL3 programs.

A trace message is removed from the dpl3_e3rec DPL3 program.

The dplp_multirec LightParser program includes the following changes:

• The program is fixed to properly set the local clock reference during the port configuration procedure and the properly configure the CMI port to E4 mode when that configuration is requested.
• When setting the receive modes for the optical or CMI port fails, a number of retires are performed to handle cases where the clock settings require time to stabilize.
• The -S option for specifying a parser script to load is replaced with use of the -P option followed by the script file instead of a numeric parser algorithm selection.
• The program is modified to select a new thread to display the byte count as the threads close.

The dplp_file2file LightParser program includes the following changes:

• It now includes code to configure the streams, clocking and the SDH parser for STM-1 input so the program can be used as a stand-along application without having to configure the board before running it.
• Some of the command line options have been changed: The -P option is added to specify SDH parser algorithm for STM-1 input. The -F option is now used to specify the input file name. The -f option is now used to specify the base names for the output files and the -m option is now used to specify the maximum recorded file size.
Note: A known problem in the clock gapping sequence generation can result in slightly different clock rates than specified. The errors are detected and reported as a failure by the cac_parse_set_clock function. The dplp_file2file program currently issues a warning when such errors are detected but otherwise ignores them.

The dplp_stm1raw LightParser program has a new -f option to specify the amount of data to be recorded.

Changes to FPGA Configurations

New versions of the DPL3 Main FPGA and LightParser Spartan FPGA configurations solve a problem that was causing certain systems to hang. The problem occurred on some systems that would abandon an incomplete PCI read transaction (while it was being retried) and replace it with an access to a different address on the same board.

The LightParser's Virtex FPGA configuration is modified to solve timing problems for raw STM-1 reception from the optical and CMI ports.

Component Versions for This Release

The Channelization API software release includes several components of software and hardware FPGA configurations. All the components have the same major and minor version numbers. However the update version number of each component may vary depending on the number of changes and iterations each component has gone through between general distribution releases.

The component versions for DPL3 and LightParser Software Release 0.5.1 are:

Component:	Version:
API Library and Programs	0.5.1
Solaris Device Driver	0.5.1
Linux Device Driver	0.5.1
Light Parser Spartan Configuration	0.5.3
Light Parser Virtex Configuration	0.5.1
DPL3 Main FPGA Configuration	0.5.3
DPL3 Expansion FPGA Configurations
E3 G751 E1 variation	0.5.2
E3 G832 Bulk variation	0.5.2
DS3 M13 T1 variation	0.5.2