October 27, 2008

Overview

The following changes are introduced in this release:

Items Specific to LightParser2:

• Added loop-through and arbitrary rate support for optical ports.
• Modified optical port configuration and status programs and functions.
• Updates for SDH parser configuration.
• Updates to SDH groomer functions and program.
• Updated FPGA configurations.

Items Specific to LightParser:

• Bug fixes for the HDLC processing FPGA.

Items Specific to DPL3:

• Bug fix for the E3 / E1 demultiplexing FPGA.

General Items:

• Support for Solaris 10 and AMD64 Architecture in the Solaris device driver.
• Other updates for the Solaris device driver.
• Fixes and updates for the Linux device driver.
• New compiler option for software configuration and installation.
• Updates to the API library functions.
• Modified utility programs.
• Modified diagnostic programs.
• Modified demonstration programs.
• Component versions for this release.
• Known problems.

Note:

This release includes new FPGA configurations for DPL3, LightParser and LightParser2 boards. Run the dpl_flashup, dplp_flashup and/or lp2_flashup programs to update the appropriate FPGA configurations.

LightParser2: Added Loop-Through and Arbitrary Rate Support for Optical Ports

An incoming optical signal can now be directly re-transmitted without modification using a configuration mode called "direct optical loop-through". The configuration locks the transmit rate to the receive rate using the PWM module to control the VXCO oscillator frequency. A single incoming signal can be re-transmitted on one or both optical port outputs. The incoming signal can, at the same time, be used for other processing in the SDH groomer, parser or received directly on the host.

Optical loop-through mode can be enabled with the lp2_portcfg program using new parameters for the -x option:

-xd		This first form requires that a single port be specified with the -p option. It will retransmit that port's input to the same port's output.
-xda or -xdb		These forms specify which port's input (Optical A or Optical B) is to be retransmitted. It is possible to have one optical port's input retransmitted on the output of both optical ports, but it is only possible to transmit a single rate on both outputs.

These modes can also be configured using API functions calls: cac_if_set_rx_mode or cac_if_set_rx_mode_rate to set the receive port, cac_if_set_tx_mode to select the VCXO oscillator for the transmit reference clock, cac_if_tx_source to choose the optical input as the source for transmit data, and cac_if_pwm_control to select the appropriate dynamic mode for the PWM module.

Note: Optical loop-through is not yet supported by the packet processing FPGA configuration.

The API function library and port configuration programs now support setting arbitrary optical ports rates for the transmit and receive reference clocks. Arbitrary rates can be configured with the lp2_portcfg program using new parameters to the -r and -t options. These options specify receive and transmit modes (respectively) and have the following new parameters for the selection of reference clock rates:

Fvalue		Specify the frequency for the receive or transmit reference clock. The value maybe be a floating point number followed by a magnitude modifier, such as m for Megahertz or g for Gigahertz. By default, if a signal type is specified (such as STM-16), the common rate for that signal is used. For the receive mode (-r) a value of 1 may be specified to use the measured incoming signal rate as the rate for the reference clock. The F parameter and its value should be the last parameter includes in the list of the -r or -t option.
T & V		These specify that the reference clock should use the TCXO or VCXO oscillator for the receive or transmit reference clock. By default the TCXO is used for SDH signal types, the VCXO is used for other signals such as GIGE and SFPDP, and for arbitrary rates, the first available oscillator is chosen. In some cases it might be desirable to specify which oscillator to use, for example to configure one port without affecting the reference clock of one already in use.

Specifying arbitrary rates is implemented in the API library with a pair of new functions: cac_if_set_rx_mode_rate and cac_if_set_tx_mode_rate. These are extensions of the cac_if_set_rx_mode and cac_if_set_tx_mode functions with added arguments to specify the desired rate and, if desired, report the actual rate that can be configured closest to the requested rate.

Although arbitrary receive and transmit rates can now be configured for the optical interfaces, applications or this are somewhat limited in the current FPGA designs. An arbitrary receive rate can be used for receiving on the host, directly from the optical ports and for re-transmitting using optical loop-through. However, the SDH payload aligner, groomer and parser can only operate with STM-1, STM-4 and STM-16 signals at or near nominal sign rates (with approximately 20 to 30 ppm tolerance). The direct transmit modes (transmitting fro the host to the optical outputs currently only function for nominal STM-1 and STM-4 rates (based on the local clock for the board).

LightParser2: Modified Optical Port Configuration and Status Programs and Functions

In addition to the changes for supporting loop-through and arbitrary rates, the following changes and additions are made to library of API functions for optical port configuration and monitoring:
• The cac_if_get_cdr_rate function includes a work-around for a problem reading the precise rates from the CDR modules. The values are read multiple times until it obtains the same value (within 25 ppm) twice in a row. It makes up to 20 reading before giving up and returning an error with errno set to EAGAIN.

• A bug in the cac_get_ber and cac_get_faserr functions has been fixed so that the reported error rates are based on the proper frame rate for the incoming signal.

• The cac_if_get_modes function is fixed to properly report transmit settings for GIGE and SFPDP modes.

• The cac_if_rx_oversamp function is modified to set errno to CAC_ERR_INVAL_RATE instead of EINVAL when the requests sample rate is not valid.

• The pointer arguments to cac_if_rate_params for reporting the FracN and over-sample value may now be NULL if those values are not required.

• The cac_chan_source function is modified to clear direct-optical source modes for betting new modes to properly restart the logic that handles direct optical modes.

• New functions, cac_if_set_rx_mode_rate and cac_if_set_tx_mode_rate are used to configure the optical port interfaces with arbitrary signal rates.

• New functions are added for configuring and checking status of the PWM module. The cac_if_pwm_control function sets the mode and resets the PWM. The supported modes are using a static (or fixed) duty cycle or dynamic control based on the depth of optical port A's or optical port B's transmit FIFO. The PWM module provides static (fixed) or dynamic control over the frequency of VCXO oscillator. The dynamic modes are currently used for re-transmitting an incoming optical signal directly on an optical output. This function is also used to reset the PWM logic and the FIFO selected for dynamic control.

  The cac_if_pwm_status function is used to report the current and average depths, and the high and low water marks for the FIFO selected for dynamic control of the PWM.

• A new function, cac_if_osc_sel reports which oscillator would be selected by the cac_if_set_rx_mode and/or cac_if_set_tx_mode functions for a given set of port options and modes. It is intended for use in checking or planning proposed configuration combinations.

The lp2_portcfg program also has additional checking for valid configuration modes and configuration conflicts.

The configuration modes displayed by both the lp2_portcfg and lp2_portstat programs (when given the -c option) is modified to show the configured transmit and receive rates as well as the signal type configured for the transceivers and framers. In addition, with verbose mode set (-v option) the programs will also display:

• the host channel stream level for ports configured to receive or transmit directly to or from the host.
• the configuration of the clock synthesizers and over-sampling modes which are the basis for the receive and transmit rate settings.

The status displayed by the lp2_portstat program now includes the measured signal rates (as reported by the CDRs) as well as the the signal types commonly associated with the rates.

The following command line options are added to the lp2_portstat program:

-r & -t		Limit reports to just receive or transmit status and configuration.
-P		Display status of the PWM module. The -l and -L options also control the resetting of the PWM status when -P is used.
-v		Verbose mode, currently adds reporting of clock synthesizer and channel stream level configuration (as described above) and retries of reading CDR rates if the option is repeated.

LightParser2: Updates for SDH Parser Configuration

Configuring C-11 and C-12 paths (from VC-4 and VC-3 structures) is added to the lp2_parsercfg program. This program also has new -q and -v options. The -q option has the program run in quiet mode, disabling the parser status report and messages about the configuration and programming. The -v option (for verbose) adds traces about the bank size and gapping settings.

The cac_parse_chan_source API function is corrected to make the proper control settings for DS-3 streams. This resolves the problem with configuring DS-3 streams in the lp2_streams program.

Resetting of the STM-1 framer is added to the cac_parse_reset API function.

LightParser2: Updates to SDH Groomer Functions and Program

In the previous release, the groomer configuration functions, cac_sdhgroomer_map, cac_sdhgroomer_map_pat and cac_sdhgroomer_getmap were modified to compensate for the shifted connections between the groomer and the SDH parser in the Parser variant of the FPGA configuration.

New functions are added in the release to perform those operations without the adjustments in order to provide a consistent programming interface for alternative FPGA designs that connect to the fourth groomer port without shifted connections. The new functions are named, cac_sdhgroomer_map_noadj, cac_sdhgroomer_map_pat_noadj and cac_sdhgroomer_getmap_noadj.

The lp2_sdhgroom is updated to make use of the new functions. It has a new -a command line option that, when specified, uses the _noadj variants. The "parser adjust" mode may also be controlled by a new command in the program. The new command is adjust, abbreviated as ad. This command may be used to report the current adjustment mode or to change it to "on" or "off".

LightParser2: Updated FPGA Configurations

New versions of the "STD" and "Parser" FPGA configurations are included in this release. The changes include:
• Enhanced handling of interrupt queue overflow to disabling DMA transfers and interrupt queue entries. This resolves problems when the system load is so high that the interrupt queue could continue overflowing and over-write the overflow indicator. DMA transfer are disabled to help control system load.
• Various updates in the optical interface to support new features and incorporate enhancements from related projects.
• Re-worked the way the test interrupt status is set and cleared so it can be used with the actual interrupt handling of the device driver.
• Improvements in the logic design for timing and routing.

The interrupt queue overflow isuse is primarily a concern when using the SDH parser FPGA with many open channels.

LightParser: Bug Fixes for the HDLC Processing FPGA

Two problems have been resolved in the HDLC processing variation of the Virtex FPGA configuration.
• Corrected a pipelining logic error that was causing mis-identification and mixing of level-1 HDLC streams to the host.

• The threshold for HDLC link detection is raised to three consecutive flags. This avoids situations where some repetitive
  test patterns might be falsely identified as HDLC frames.

DPL3: Bug Fix for the E3 / E1 Demultiplexing FPGA

A problem was fixed in the expansion FPGA configuration that demultiplexes E3 traffic and extracts E1 streams. Errors in handling the framing status were causing erroneous status reports and enabling of E1 streams when only some of the multiplexed streams contained E1 framing. The affected FPGA configuration is the E3 G.751 variation, named dpl3b-e3g751e1.

Support for Solaris 10 and AMD64 Architecture in the Solaris Device Driver

DMA memory allocation is fixed for Solaris 10 (and presumably for higher versions, as well) by using a proper value for the scatter-gather length DMA attribute. Sparc platforms with Virtual DMA memory mapping were not affected by the problem. Earlier versions of Solaris require the previous value so the configuration script has been updated to substitute the appropriate value.

The device driver configuration script and Makefile are updated to include support for the amd64 architecture for both GCC and SunStudio compilers. Note that "amd64" is term used by Solaris for 64-bit Intel and AMD platforms (equivalent to the "x86_64" architecture term used by Linux).

Other Updates for the Solaris Device Driver

Added restarting DMA transfers and interrupt queue entries when a queue overflow is detected. New versions of the LightParser2 FPGA automatically disable these to avoid multiple queue overflows. Setting the restart register bits does not do any harm in FPGA designs that have not implemented the automatic queue and DMA disabling.

Modified channel I/O routines to treat an error condition in the interrupt queue as the highest priority error to ensure that applications will be notified of queue error conditions.

In addition to changes for DMA attributes to work with Solaris 10, the DMA attributes are also modified to set the maximum transfer sizes appropriate for the board's channel buffer and interrupt queue size.

Fixes and Updates for the Linux Device Driver

Resolved problems with 2.6 kernel crashes when the device driver is loaded and/or unloaded. The problems were induced by changes in the implementation of the device driver registration and initialization routines in the Linux kernel. The primary cause of trouble was leaving partial device driver registrations in cases when a driver was loaded for a board type that was not installed. The device driver now handles device driver registration an un-registration more directly for 2.6 kernel versions.

A work-around is added for a problem in the device driver that was sometimes causing channel resources and DMA memory to not be released when a program is terminated by a signal that is not handled by the program and channels are closed automatically by the operating system. This situation typically arises when a program "crashes" due to a segmentation fault or is otherwise unexpectedly terminated. This problem seems to be caused by a race condition in the kernel's handling of signal flags which can cause the down_interruptible kernel function to return early. The work-around has the device driver retry getting a necessary mutex if the down_interruptible function returns with a "interrupt" status. The number of retries is limited to avoid "stuck" processes.

Enabled the device drivers to be used with XEN-enabled kernels by fixing the memory mapping routines for registers and memory on the board to use the io_remap_page_range and io_remap_pfn_range functions instead of the remap_page_range and remap_pfn_range functions.

Added restarting DMA transfers and interrupt queue entries when a queue overflow is detected. New versions of the LightParser2 FPGA automatically disable these to avoid multiple queue overflows. Setting the restart register bits does not do any harm in FPGA designs that have not implemented the automatic queue and DMA disabling.

Modified channel I/O routines to treat an error condition in the interrupt queue as the highest priority error to ensure that applications will be notified of queue error conditions.

New Compiler Option for Software Configuration and Installation

A new option is added to the software configuration script: --with-cflags=flags. It is used to specify non-default compiler flags, that may be required in special situations, for compiling the API function library and support and diagnostic programs. This option does not affect compiling of the device driver.

Examples of such situations are 1) compiling the API and programs for 32-bit code on Linux platforms that support 64-bit code by default:

      --with-cflags=-m32

and 2) compiling the API and programs for 64-bit code with Solaris on an AMD64 (or Intel x86-64) platform using GCC:

      --with-cflags=-m64

or using Sun Studio CC:

      --with-cflags=-xarch=amd64

Additional information can be found in the recent version of the "CAC Channelization API Software Installation Instructions".

Updates to the API Library Functions

In addition to the changes and enhancements to the API previously mentioned, the following, general modifications are made to the API functions:

The functions for computing channel latencies now return a value of 0 and set errno to CAC_ERR_INVAL_MODE if the channel type indicated by the modes argument is not supported. These functions are cac_latency_ms2bytes, cac_latency_ms2p2bytes, cac_latency_bytes2ms, cac_latency_adj_bytes, cac_latency_adj_p2bytes, cac_latency_min_bytes, and cac_latency_max_bytes. Previously they would return a value based on the data rate for an E1 stream by default.

The functions that search for FPGA configuration files are modified to not search in the development directory for files with "release" versions names unless a specif version is requested. This is done to keep the lp2_flashup, dplp_flashup and dpl_flashup from prematurely installing release version FPGA configurations that are still being tested on boards in production.

Modified Utility Programs

The lp2_init program is modified to skip the name-based FPGA version check when loading a custom FPGA configuration and to reset packet processing logic for custom or special variations of the "packet" FPGA type.

The lp2_info program now reports the version of the SDH parser module included in "parser" FPGA builds.

Some minor fixes to status and error reporting in the dpl_flashup, dplp_flashup and lp2_flashup programs. These programs no longer search the FPGA development directory for release FPGA versions by default (see discussion of API function changes).

Modified Diagnostic Programs

The lp2_recv, dplp_recv and dpl_recv programs are modified to hold off on displaying the computed data rate until after a few channel reads are completed to avoid displaying exaggerated rates that can result from an initial burst of available data. Other quirks in the status display were cleaned up. These programs also now check the result of latency computations for unsupported channel types and report unsupported types as an error.

The lp2_send, dplp_send and dpl_send programs have a new -R option to display average transmit data rates. These programs also now check the result of latency computations for unsupported channel types and report unsupported types as an error.

The lp2_chantest and dplp_chantest programs have a new SDH frame patterns for checking receive channels and sending on transmit channels. These are enabled by specifying the pattern mode option as -x10:n. Where n is 1 for STM-1 frame pattern, 4 for STM-4 frame pattern, or 16 for STM-16 frame pattern. If just -x10 is specified, a STM-1 frame pattern is used.

All of the _chantest programs now support testing with a 15-bit LFSR (IUT) test pattern. The -x2 option for setting the 9-bit ITU pattern is extended to allow specifying the length of the LFSR. The options, -x2:9, -x2:11, and -x2:15, select 9-bit, 11-bit and 15-bit LFSR patterns, respectively. The -x9 option (without a length) selects the 9-bit LFSR. The -x3 option for selecting the 11-bit LFSR pattern is still support but no longer advertised.

The following changes are also included in all of the _chantest programs:

• The display option, -d has a new r parameter to include average data rate for receive channels and the time window in which the rate is compared. For example, -dr10 will compute the average rate and check every 10 seconds if it has changed by more that 8%, starting a new display line if it has.
• The display option, -d also has a new g parameter to specify the number of channels to be grouped for combined status. The grouped channels share a common marker on the status line which indicates the worst condition for the group. This is useful for fitting status of many channels in the width of the terminal window. For example, status can be combined for groups of 8 channels by specifying the option, -dg8.
• A new -i option specifies a number channel reads to ignore following the occurrence of a timeout on a channel. This is useful to avoid high tCPU usage when the program tries to recover pattern sync after such an error.
• Interrupt queue errors and now handled by resetting all open channels and indicated by momentarily displaying a Q for the status markers.
• Channels that fail to open are indicated with an inactive channel marker, N instead of being dropped in the status display.

The dplp_memtest and dpl3_memtest programs now test the page table and channel descriptor regions as separate regions even though they currently reside within the SDRAM memory region. These regions can be specified as individual regions to test, avoiding unused areas of the SDRAM.

The lp2_debug, dplp_debug and dpl_debug programs are fixed to indicate the currently open board name in the command prompt, avoid attempting to display memory map information by the bar command if the is no open board, and to display the reason when an EEPROM write operation fails.

New and Modified Demonstration Programs

Use of application-level ring buffers is added to the packet recording demonstration programs for LightParser2, lp2_packetrec and lp2_analightrec. The implementation uses separate threads to handle reading channel data from the board and writing the data to disks on the host. This methodology serves as a model for applications that need to handle disk I/O latency for high-bandwidth recordings.

These two programs also include the following changes:

• Fixed the display_time functions to properly display the microsecond differences between two time values. A mode to display in hundredths of a second was also added.

• Added checking for erroneous values from the gettimeofday system function and retrying to get correct times. This is a work-around for a problem in which the time value can be reported as some 4,000 or so seconds higher than it should be. This seems to occur on some multi-processor systems and seems to be dependent on the host platform and/or Linux kernel version.

• Only use the lower 8 bits of the FPGA configuration type code when checking for the "packet" FPGA type to allow for special variations of the FPGA configuration.

Component Versions for This Release

The Channelization API software release includes several components of software and hardware FPGA configurations. The "Support Version" for hardware components are the version numbers for the software support of the particular board or FPGA configuration type.

The API and device driver components have the same major and minor version numbers. Similarly, the "Hardware Support" versions have the same major and minor version numbers as the corresponding FPGA or FPGA type. 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 Software Release 0.9.3 are:

Software Components	Version
API Library and Programs	0.9.5
Linux Device Driver	0.9.5
Solaris Device Driver	0.9.5
Hardware Components	FPGA Version		Support Version
LightParser Spartan FPGA Configuration	0.8.2		0.8.2
LightParser Virtex FPGA Configurations
Standard SDH/PDH variation	0.7.0		0.7.0
ATM variation	0.7.3		0.7.3
HDLC variation	0.9.2		0.9.2
SDH/PDH Transmit variation	n/a		n/a
LightParser2 Virtex FPGA Configurations
Standard SDH variation	0.4.6		0.4.6
SDH Parser variation	0.4.2		0.4.2
Packet Processing variation	0.4.6		0.4.6
LightParser2 Boot FPGA Configuration	0.0.1		0.0.1
DPL3 Main FPGA Configuration	0.9.1		0.9.1
DPL3 Expansion FPGA Configurations
E3 G751 E1 variation	0.9.1		0.9.1
DS-3 T1 variation	0.9.0		0.9.0
E3 G832 Bulk variation	0.9.0		0.9.0
Generic variation	0.9.0		0.9.1

Known Problems

The following problems are known to exist in this release:
• LightParser:

  NDFs, announced and unannounced, are not properly handled for TU-11 and TU-12 pointers. This problem is resolved in an experimental, pre-release FPGA configuration, version f.28, included in the distribution. To load this configuration run the dplp_flashup program as shown below:

              dplp_flashup -uv -xf dplp0
      

  Some unannounced TU-3 pointer changes are not handle correctly which causes the tributaries fro the affected pointers to go out of sync.

  Data corruption has been reported when recording raw, descrambled STM-1 signals that include AU3s. This condition can normally be cleared up by resetting and reconfiguring the parser.

  Using the clock extracted from the electrical (CMI) port in STM-1 mode causes some data corruption. Work-around is to use the local clock reference when receiving electrical STM-1.

  The ATM version of the Virtex is not able to frame DS-3 streams from SDH streams. A work-around is to route the raw DS-3 streams from SDH input through the Quad-T3 port, loop the signal back in and frame the DS-3 signals from the Quad-T3 input.

  Detection of ATM client channel overflow (pointers to the bulk ATM buffer that are no longer valid) is not yet implemented in the ATM service of the device driver.

• LightParser2:

  The Linux device driver contains a bug which breaks the processing of channel flush entries in the interrupt queue. The channel flush mechanism is only supported by LightParser2 FPGAs, is primarily used by packet processing applications, and is activated using the API functions, cac_packet_chanflush and cac_autoflush_interval. This problem was discovered after the current software was released and will be fixed in the next release. In the meantime, if your application is using this mechanism, contact CAC for more information about a patch that is being made available.

  The SDH parser does not handle some unannounced pointer changes correctly. A side affect of this is possible mis-identification of AU-3s as an AU-4. This condition can normally be cleared up by resetting and reconfiguring the parser. There is a pre-release FPGA configuration with a temporary work-around for the AU-4 case. Contact CAC for more information if your application is experiencing intermittent problems with AU-4 parsing. A solution for the pointer change handling is being tested.

  In the SDH parser, DS-3 streams from the fourth STM-1 cannot be framed or extracted using their default stream IDs.

  The lp2_parsercfg program selects the wrong bits from the array of stream status information when formatting the E1 status for the STM1->TUG3->E3->E2->E1 structure. The raw status display (with the -r option) does show the correct status.

  Optical port transmit in the STD and Parser FPGA designs is limited to transmitting SDH signals at nominal rates based on the board's local clock or using direct re-transmission (loop-through) from an optical input. Although the optical transmitters can be configured to send arbitrary rates, there is not a way to use such rates for moving data.

  Handling of extended packet lengths in the packet processing FPGA is not yet complete. Continuation "chunks" for HDLC (POS and LAPS) packets larger than 3072 bytes are implemented but packets that are aborted after one or more chunks are not terminated properly. Jumbo Ethernet packets from the electrical or optical ports are not yet supported.

  Support for packet status and statistics is not yet implemented in the API.

• DPL3:

  Raw E3 or DS-3 streams cannot be transmitted from the host because there is not a way to bypass the L3 framer.

  Bulk E3 or DS-3 payload content cannot be transmitted in alignment with the E3 or DS-3 frame sync. Bulk payloads that require such alignment, such as PDH structures cannot be transmitted from the host.

• Linux 2.6 Device Driver Issues:

  Memory suitable for DMA allocation may become unavailable over time. When this occurs, applications may not be able to open channels requiring large DMA buffers. Currently, the only work-around is to apply the bigphysarea patch to the 2.6 kernel.

  When using the 64-bit variant of the Linux kernel included with Red Hat Enterprise 4, DMA buffer allocation is limited to about 12 MB. This problem has been found in all RHEL4 updates up to and including RHEL 4.7. This problem has not appeared in Red Hat Enterprise 5, which has been tested up to RHEL5.2.