September 3, 2003

Overview

Version 0.4.1 is a beta release of the Channelization API for DPL3 and LightParser Boards. Not all of the functionality is implemented in this release.

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:

• Fixed a bug in the LightParser's parser reset function.

• Re-worked the DPL3's Comet configuration functions.

• Added interrupt queue overflow detection.

• Added support for deferred queue interrupts.

• Added API function to modify channel timeout interval.

• New diagnostic program to report interrupt queue statistics.

• Changes to utility and diagnostic programs.

• Modified demonstration program.

• Changes to FPGA configurations.

• Component versions for this release.

Note: Normally software releases with the same major and minor version numbers are meant to be compatible. However, chanapi version 0.4.1 includes modifications to the interface between the API and device driver that are not compatible with version 0.4.0. Both the API and device driver must be updated for proper software operation.

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.

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.

Fixed a Bug in the LightParser's Parser Reset Function

The cac_parse_reset is fixed to leave time slot 0 of E1 streams enabled.

Re-worked the DPL3's Comet Configuration Functions

The API functions for initializing and configuring the Quad-Comet (E1 and T1 interface) have been modified to provide a better programming interface.

The cac_comet_init function now takes separate arguments for the modes of each of the four framers instead of one global mode argument and an array of four local modes. The global setting (E1 or T1 mode) for each of the four framers must match.

A new function, cac_comet_config is provided to allow certain modes of individual comets to be modified after they are initialized using cac_comet_init.

Details of the comet configuration API functions are currently documented in the HTML version of the API reference, found on the CD-ROM and available as a separate download from the software distribution.

Added Interrupt Queue Overflow Detection

The new version of the DPL3 main FPGA and LightParser Spartan FPGA includes logic to detect overflow of the interrupt queue and generate and special interrupt queue entry when this occurs.

The Linux and Solaris device drivers include code to handle this special queue entry and handle it by flagging a "Queue Sync" error for every channel that is open at the time it occurs. This error is passed back from calls to cac_chan_read, cac_chan_write and cac_chan_io in the form of a return value of EOF and errno set to CAC_ERR_QUEUESYNC.

It is highly unlikely that the interrupt queue would ever overflow during normal usage. In fact, testing the overflow detection required temporarily disabling interrupts from the board.

Added Support for Deferred Queue Interrupts

Interrupt deferral is a method of improving overall system performance by limiting the number of hardware interrupts the board will generate within short intervals of time.

It is most effective in cases when many channels are open that have similar latencies. For example, assume that 50 receive channels are open with their latency set such that new data is expected to become available every 50 milliseconds. Data may become available for each channel at very short, staggered intervals which would cause a hardware interrupt to occur for each channel. By deferring the hardware interrupts by 10 milliseconds, yet still allowing the interrupt queue entries to accumulate, the device driver is able to handle multiple queue entries for each interrupt and the system overhead of handling individual interrupts is reduced.

The API functions, cac_queue_enable, cac_queue_enable_name and cac_queue_enable_num are modified to use their enable argument to specify the interrupt deferral time. If enable is 1, the queue handler is enabled with no interrupt deferral, as in previous versions. If enable is greater than 1 it specifies the interrupt deferral time in microseconds.

The deferral time is actually stored in increments of 500 microseconds up to a maximum of 31500. For example:

enable value	resulting interrupt deferral time
0	queue handler disabled
1	0 microseconds
2 - 999	500 microseconds
1000 - 1499	1000 microseconds
1500 - 1999	1500 microseconds
2000 - 2499	2000 microseconds
. . .	. . .
31000 - 31499	31000 microseconds
31500 - 31501	31500 microseconds
> 31501	invalid

Added API Function to Modify Channel Timeout Interval

The timeout interval for a channel is initially set by the device driver when a channel is opened. It's value is determined based on the latency value and the presumed rate at which data would normally received or transmitted for the channel and is set to 4 times the expected latency time. This interval is used to unblock a process waiting for channel I/O and return an error of ETIMEDOUT if not queue entries have been processed for the channel.

There may be situations, such as for asynchronous data channels, when an application is willing to wait longer for an I/O operation to complete.

The new cac_chan_timeout function allows an application to modify the timeout interval after a channel is opened. Its prototype is:

    int cac_chan_timeout(
       CAC_CHANNEL *chan,      /* handle for the open channel */
       int          timeout)   /* new timeout value or 0 */

If timeout is 0 the function returns the value of the current timeout interval for the channel in milliseconds. Otherwise it specifies the new timeout interval in milliseconds and the function returns the previous timeout interval value.

New Diagnostic Program to Report Interrupt Queue Statistics

The new program, dpl_queuestats for DPL3 or dplp_queuestats for LightParser, reports information about the device driver's interrupt queue handling. It displays a list of how often the device driver handles various numbers of queu entries per interrupt. It is primarily provided for analyzing the queue handler and system performance.

The device driver does not collect the statistics by default. To enable this feature the value of the QUEUE_STATS macro must be changed from 0 to 1 in the cacdrv_options.h file in the device driver build directory.

Changes to Utility and Diagnostic Programs

The dpl_init and dplp_init programs are modified to enable the host transfer mechanisms in the FPGA registers during the initialization procedure. This operation is now removed from the API functions for opening channels, cac_chanopen_stream, cac_chanopen_list and cac_chanopen_mask.

The dpl_init program is fixed to properly check for the expansion FPGA population on DPL3 boards.

The dpl_chantest and dplp_chantest diagnostic programs now use 64-bit byte counters to allow for reporting much larger amounts of data before wrapping. Their -qd option now allows for an interrupt delay value to be specified for testing queue interrupt deferral. They are also modified to search for the ITU patterns in a limited number of bytes in each buffer to avoid channel overflow errors when trying to sync to ITU patterns.

The dpl_comet program is enhanced to provide more control of the Comet configuration.

Modified Demonstration Program

The LightParser demo program, dplp_stm1raw is fixed to no longer use the fflush function for each buffer of data written to the file.

Changes to FPGA Configurations

The Main FPGA configuration for DPL3 boards is modified to support queue overflow detection and deferred queue interrupts. It also fixes the data alignment for T1 transmit to the Comet framers.

The Spartan FPGA configuration for LightParser boards is modified to support queue overflow detection and deferred queue interrupts.

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 components and their versions for DPL3 and LightParser Software Release 0.4.1 are:

Component:	Version:
API Library and Programs	0.4.2
Solaris Device Driver	0.4.2
Linux Device Driver	0.4.2
DPL3 Main FPGA Configuration (all variations)	0.4.2
DPL3 Expansion FPGA Configuration	0.4.0
Light Parser Spartan Configuration	0.4.2
Light Parser Virtex Configuration	0.4.1