July 8, 2009

Overview

The following changes are introduced in this release:

Items Specific to LightParser2:

• Support for HDLC packets from STM-1 and de-multiplexed SDH streams.
• Additional and updated status reporting for packet processing.
• Fixed handling of unannounced pointer changes in the SDH parser.
• Fixed bug in framer initialization for the SDH/PDH parser.
• Added STM-1 pass-through capability for SDH parser.
• Added buffer conflict detection for SDH parser streams.
• Separated MGT powerdown controls for receive and transmit paths.
• Updates to optical port configuration and status programs and functions.
• Preliminary support for new LightParser2e board.

Items Specific to LightParser:

• Added option to skip I/O port initialization in the dplp_init program.

Items Specific to DPL3:

• None

General Items:

• Fixes and updates for the Linux device driver.
• Modified utility programs.
• Modified diagnostic programs.
• Modified demonstration programs.
• Component versions for this release.
• Known issues.

Note: This release includes new FPGA configurations for LightParser2 boards. Run the lp2_flashup program to update the appropriate FPGA configurations.

LightParser2: Support for HDLC Packets from STM-1 and De-Multiplexed SDH Streams

The packet processing FPGA configuration for LightParser2 is now able to process HDLC (POS and LAPS) packets from STM-1 optical input signals and from STM-1 and STM-4 streams de-multiplexed from STM-16 or STM-4 input signals.

The API function, cac_packet_config_rcv, is used for configuring the board to process HDLC packets directly from the optical inputs. It now allows a value of DPLP2_IFMODE_RX_STM1 for the sigtype argument to process packets from a STM-1 input signal.

Configuring the board to process HDLC packets from de-multiplexed SDH streams requires additional parameters to specify the stream demuliplexing and mapping to the packet buffers. A new function, cac_packet_map_sdh, is added to the API library for specifying the de-multiplex and mapping configuration. It is called once for each packet stream to be configured instead of the cac_packet_config_rcv function. Some of the arguments to the new function specify the signal and stream parameters: which optical port's input to use, the incoming signal type, the type and index of stream to de-multiplex from the input signal. The remaining function arguments specify which packet processing buffer to use and the packet type and modes.

Up to four de-multiplexed streams can be processed at the same time and the POS / LAPS packets processed from these streams are routed to the host channelizer using the same four packet buffers that are used for packets processed directly for the four I/O ports (POS, LAPS GIGE or SFPDP from optical ports A and B, and GIGE packets from eternet ports A and B). There are new macros for identifying the packet buffers when specified to the cac_packet_map_sdh function. They are CAC_PACKET_BUFFER_0, CAC_PACKET_BUFFER_1, CAC_PACKET_BUFFER_2 and CAC_PACKET_BUFFER_3. There is also a macro, CAC_PACKET_BUFFER, which may be used with an integer offset to specify one of the numbered buffers.

The new packet buffer macros are also used when calling the cac_packet_chanopen function to specify the source of packets for the channel being opened. The port argument for this function is renamed source to better reflect it's expanded role. The I/O port macros, DPLP2_IF_OPT_A, DPLP2_IF_OPT_B, DPLP2_IF_ETH_A and DPLP2_IF_ETH_B are still used when opening the packet channels that were configured with the cac_packet_config_rcv function. The new packet buffer macros should be used to open channels that were configured with the new cac_packet_map_sdh function.

It is possible to process packets from a combination of mapped SDH streams and GIGE and SFPDP streams at the same time. However, there are restrictions on the usage of the packet buffers. Packet streams configured with the cac_packet_config_rcv function will always use the packet buffer associated with the input port being configured. The buffers used for direct-signal packet processing from optical port A, optical port B, ethernet port A and ethernet port B correspond to the the numbered packet buffers, 0, 1, 2 and 3, respectively.

A new function, cac_packet_buffer_enable, is added to the API library. It's initial purpose was to centralize the buffer enable and disable operations for the cac_packet_config_rcv and cac_packet_map_sdh functions. But it can also be used directly by applications as a more convenient way to perform this operation.

Note that the inclusion of multiple de-multiplexed SDH packet streams required extensive reorganization of control registers in the FPGA. Therefore, it is necessary to update both the FPGA and the software at same time.

LightParser2: Additional and Updated Status Reporting for Packet Processing

The packet processing FPGA configuration for LightParser2 now supports detection and reporting of B1, B2, FAS and pointer errors and concatenation status in the incoming optical signals. The B1, B2 and FAS reporting includes cumulative counts as well as indicators that errors have been detected. All of the reporting mechanisms are similar to those in the basic and SDH parser FPGA configurations and are compatible with the related API functions and the lp2_portstat program. The lp2_portstat program includes modifications to handle the differences between the two primary FPGA configurations (described later).

A new program, lp2_packetstat, and several API functions are added to the software for reporting packet processing modes and status. The program wmorks similar to the lp2_portstat program but provides reporting specifically for packet processing status including:

• Configuration of the SDH de-multiplexing and packet buffer mapping.
• HDLC packet type and detection
• Various packet processing statistics for HDLC, GIGE and SFPDP streams.

The following API functions, used by the program, are also available for use by custom applications:

cac_packet_get_modes		Report configuration modes for a packet processing buffer.
cac_packet_get_status		Read and report packet processing status information (currently only supports POS and LAPS mode).
cac_packet_clr_status		Clear latched status information.
cac_packet_stat_count		Read and (optionally) reset packet statistics counters.

LightParser2: Fixed Handling of Unannounced Pointer Changes in the SDH Parser

The pointer processing logic for the SDH parser is fixed to better handle unannounced pointer changes. Such pointer changes may occur in real-world signals but are often inadvertently induced when the SDH groomer map is modified or optical signals are reconnected to the ports.

The corrected logic in this release supersedes the temporary and partial fix for this problem that was made available as an experimental FPGA design in June, 2008.

One side effect of the pointer error was a possible mis-identification of AU-3s as an AU-4. Part of the initial fix to the problem was the addition of an "AU mode" control to set the tributary type (AU3 or AU4) to be extracted from the STM-1 signal. This additional setting remains a part of the SDH parser configuration. A new low-level function, cac_parse_set_au_mode, is added to the API for setting this mode. It is called from various higher-level parser configuration functions.

The fix to the pointer processing applies to all pointer processing, TU-3 and TU-11 and TU-12 pointers as well as the AU-3 and AU-4 pointers. However, symptoms of the problem occurring in the lower level pointers have not been reported.

LightParser2: Fixed Bug in Framer Initialization for the SDH/PDH Parser

A logic bug is fixed that could cause the framer at one or more stream levels to get stuck in the initialization mode. This mode is invoked when calling the -R option with the lp2_parsercfg program and when calling the cac_parse_reset function in the API library.

The symptom of this problem occurring was a failure to report good sync status for streams below a certain level in the parser. Reconfiguring the parser with a reset (call or command option) would cure the condition in most cases.

LightParser2: Added STM-1 Pass-Through Capability for SDH Parser

The SDH parser now includes the capability to pass STM-1 inputs to the channelizer using what is called STM-1 pass-through mode. When this mode is activated the four STM-1 streams mapped from the SDH groomer to the parser become available as the level-4 streams that can be enabled for host channels. They replace the other level-4 streams (e.g. C-4 or E4) that could be extracted by the parser. Note that this mode globally affects the level-4 streams from all four STM-1 parsers.

The lp2_streams program includes a new -p argument that enables STM-1 pass-through when used in conjunction with the -Rstm1 option. The program will disable STM-1 pass-through mode with any other modification to level-4 streams.

LightParser2: Added Buffer Conflict Detection for SDH Parser Streams

The data buffers used for streams extracted by the SDH parser in LightParser2 are shared for the various stream levels. This can lead to conflicts, overlapping use of buffer space, when streams of different levels are enabled at the same time. As a simple example, enabling the STM-1 stream from the first STM-1 parser input will conflict with E1 streams extracted from the same STM-1.

It is possible for multiple stream levels to operate simultaneously if care is taken to avoid buffer conflicts. In general, and in the simple cases, there is not a problem when only streams of the same level are enabled at any one time or if the parser bank size is set to 64 and care is taken not enable different level streams from the same STM-1 at the same time. But the rules become more complicated in other situations. For example, the default buffer gapping for level 1 streams allows for up to 84 DS-1 streams per STM-1 and extends the use of the buffer space for level 1 streams beyond the per-STM-1 boundary, into the buffer space that the level 4 and level 3 streams from the next STM-1 would occupy.

To assist in managing buffer usage, conflict detection and avoidance has been added to the lp2_streams program. The program will now check for buffer conflicts when enabling streams. By default it will report conflicts and will not enable new streams that would cause conflicts. If a new, -c, option is specified, the program will not only report conflicts, it will also clear existing stream enables to make way for the new streams being enabled.

In a related change, a new -F option is added to the lp2_streams program for disabling a list of streams specified in a parameter similar to the parameter used for enabling streams with the -f option.

The conflict checking and clearing capability for lp2_streams is implemented using a new API function, cac_parse_check_buffer_conflicts. Another, related function added to the API is cac_parse_get_rx_stream_enable which reports whether or not a stream, specified by level and index, is currently enabled. Both of these functions are available for use by custom applications.

LightParser2: Separated MGT Powerdown Controls for Receive and Transmit Paths

The LightParser2 uses separate transceivers (MGTs) for the receive and transmit paths of each optical port. Up until now, however, the power-down controls for the receive and transmit MGTs of each port were tied to a common control line (one for Optical port A and one for Optical port B).

The new versions of the "standard", "sdh parser" and "packet processing" FPGA configurations have separate control bits for the power-down control of the receive and transmit MGTs. This makes it possible to perform a proper resest of the receive or transmit MGT without affecting activity in the other direction.

LightParser2: Updates to Optical Port Configuration and Status Programs and Functions

The following changes and additions are made to library of API functions for optical port configuration and monitoring. Most of the changes involve improving support for the packet processing FPGA configuration.
• The cac_if_reset function will now reset packet processing controls and the optical MAC and PHY as well as Ethernet port controls if the packet processing FPGA is loaded. It also now uses the separate Rx and Tx MGT power-down controls so that the receive or transmit direction may be reset without affecting the other direction.

• The cac_if_set_tx_mode and cac_if_set_tx_mode_rate functions will make sure that the Tx MGT power-down control is not asserted if the Tx inhibit mode is not specified. Similarly, the cac_if_set_rx_mode and cac_if_set_rx_mode_rate functions make sure that the Rx MGT power-down control is not asserted. Note that it is not a normal circumstance for the power-down controls to be left asserted.

• A new mode flag macro, DPLP2_IFMODE_RX_D43DSC, is added for the cac_if_set_rx_mode and cac_if_set_rx_mode_rate functions. This mode enables the delta-43 payload descramble for HDLC packet processing. The cac_if_get_modes function is modified to report this new mode as well as the DPLP2_IFMODE_RX_DSCRAM mode for the packet processing FPGA.

• Fixed the cac_if_gigectl_read function to use the proper register control value to perform a read operation.

• A new error code, CAC_ERR_MAC_TIMEOUT, is used by the cac_if_gigectl_write and cac_if_gigectl_read functions to distinguish between errors accessing the MAC and PHY devices. If a timeout occurs accessing the PHY, errno is set to CAC_ERR_MDIO_TIMEOUT. If a timeout occurs accessing the MAC or STATS resource, errno is set to CAC_ERR_MAC_TIMEOUT.

• A new function, cac_if_check_for_mac, is added to the library. It reads a special status bit added to the packet processing FPGA to report whether or not the MAC is implemented for a specified I/O port. This function is used to avoid trying to access the MAC interface if it is not implemented, as may be the case for some special purpose FPGA builds.

• A new function, cac_get_stm1stat, is added to the library. It is similar to the cac_get_stm0stat but is designed to report status for pointer processing only down to the STM-1 level. This is the more appropriate function to use for the packet processing FPGA.

• The DPLP2_PKT_MODE_RXBADCRC macro (used as a mode flag for the cac_packet_config_rcv function) has been replaced with DPLP2_PKT_MODE_RXCRCIGN. This more accurately reflects the operations being controlled for both HDCL and SFPDP packet processing.

The lp2_init program includes function calls to reset the Ethernet port controls for the packet processing FPGA.

The lp2_portcfg now sets the D43 payload descrambling mode for packet processing FPGA types along with the input descrambling mode. They are either both enabled or both disabled. The two descrambling modes cannot be set independently with this program.

For both lp2_portcfg and lp2_portstat, the display of the current optical port configuration, is modified to replace the framer enable mode with the D43 payload descrambling mode setting for packet processing FPGA types and, for all FPGA types, neither the descrambling or framer enable modes are reported when the MGT is configured for GIGE or SFPDP mode.

The lp2_portstat program can now display SDH pointer and payload aligner status. This is displayed when given the -P option. This report is similar to that shown by the "stm0stat" command in the lp2_sdhgroom program but includes both optical ports and only shows the pointer and C2 byte status down to the STM-1 level for the packet processing FPGA. PWM status, previously shown with -P, is now included with the -W option.

The lp2_portstat program eliminates the report of framer and payload aligner status for non-SDH modes and eliminates status information that is not relevant to or supported by yh packet processing FPGA (e.g. aligner errors). BER and FAS error counts are now supported by the packet processing FPGA, and when displayed, with the -b or -B option, decimal format is used instead of hexadecimal format.

LightParser2: Preliminary Support for New LightParser2e Board

This software release includes some changes in the device driver and API library to support handling differences between the LightParser2 and a new LightParser2e board. Although this version is not fully aware of LightParser2e, some of the infrastructure required to handle the differences is in place to support preliminary development.

LightParser2e is a PCI-express version of the LightParser2 board that is currently in development. Availability is is planned for the third quarter of 2009. The board and software are being designed to provide, at a minimum, equal capabilities with the LightParser2 but with a newer (Virtex 5) FPGA and some other updated components. It will operate using the the same device driver and API as LightParser2. The API and support programs will be able to handle any operational differences at run time.

LightParser: Added Option to Skip I/O Port Initialization in the dplp_init Program

The dplp_init program now supports the -P option, to specify not to initialize the I/O ports. This serves the same purpose as the -P option for lp2_init and the -F option for dpl_init.

Fixes and Updates for the Linux Device Driver

A bug in the interrupt queue processing routine that affected channel flush queue entries used with packet processing for LightParser2 boards is fixed. The patch, which had been made available for the previous release, is no longer required once the driver has been updated with the new version.

A bug in the CAC_CHANRES_OP ioctl is fixed. This bug caused resources for channels with active processes to be released even if the "force" option was specified.

Added module description text for the LightParser2 build of the device driver.

Support for MSI interrupts is added to the Linux device driver. Currently the only device that supports MSI interrupts is the LightParser2e that is under development.

The initialization script run during system boot is modified to check for boards being installed before attempting to load the device driver. The lspci program is used to list the installed devices and the list is searched for the board's device IDs. This change had been available in a patch for previous releases.

Modified Utility Programs

The dpl_serial, dplp_serial and lp2_serial programs have new -R and -S options for changing or setting the PCB/Assembly revision and serial number on the command line without interactive prompts and responses.

The lp2_info and lp2_find programs now report the calibration value for the VCXO/PWM as well as for the TCXO.

Modified Diagnostic Programs

The lp2_recv, dplp_recv and dpl_recv programs can now use ring buffers, a circular list of memory buffers providing elastic storage, to avoid channel overflow during short periods when the disk is inaccessible. Ring buffer usage is specified with a new -r option. These programs are also modified to remove existing files that would be over-written for split-file or snap-shot modes before the recording begins to avoid delays caused by removing large files during a recording. A new -x option is added to disable this feature, if desired. Additionally, the channel parameters (buffer size, slot mask and the requested and adjusted latency) are no longer displayed unless verbose mode is set.

The lp2_send, dplp_send and dpl_send programs are modified to only display channel parameters (buffer size, slot mask and the requested and adjusted latency) if verbose mode is set. These programs also now report the number of times the input file is repeated when the continuous play option is used.

The lp2_chantest, dplp_chantest and dpl_chantest programs have a new status display parameter, -ds#, to insert a spacer between groups of # channels.

Some of the status and other messages displayed by the lp2_chantest, dplp_chantest and dpl_chantest programs are modified for the benefit of test scripts to avoid capturing extraneous information in log files. These programs are also modified to automatically limit the channel status display grouping to the number of active transmit or receive channels.

The lp2_dmatest, dplp_dmatest, dpl3_dmatest, lp2_vtmon and dplp_vtmon programs are modified to only send the final status display to stdout. Intermediate status is sent to stderr. This was done for the benefit of test scripts to avoid capturing extraneous information in log files. the _dmatest programs are also fixed to discontinue multiple iterations if errors occur and the "stop-on-error" mode was specified.

The lp2_debug, dplp_debug and dpl_debug programs have a new -f option to not attempt the configuration space fixup operation when opening a board. The lp2_debug and dplp_debug programs are fixed to avoid using the parser parameters if they have not been initialized.

The lp2_dumpcfg, dplp_dumpcfg and dpl_dumpcfg programs now include display of the PCI capabilities list in configuration space. This primarily benefits new boards for PCI-express or that support MSI interrupts.

Modified Demonstration Programs

Support for processing POS and LAPS packets from STM-1 inputs and for configuring de-multiplexed SDH mapping for POS and LAPS packets is added to the lp2_packetrec program. A new -M option is used to specify the parameters for mapping packet processing from de-multiplexed SDH. Also, the default output mode is changed to "no file".

The lp2_analightrec program includes a special, interrupt-driven, snap shot capture mode and monitoring of interrupts that indicate optical I/O errors.

The following changes apply to both the lp2_packetrec and lp2_analightrec programs:

• removal of existing files that would be over-written for split-file or snap-shot modes before the recording begins to avoid delays caused by removing large files during a recording. A new -x option is added to disable this feature, if desired.
• a new -Tc option, actually a variant of the "timed" recording option, to request a continuous recording mode.
• replaced the use colons for parameter delimiters with commas, except for time parameters.
• fixed bugs affecting split file recording mode (different bug in each program).
• replaced the use of cac_packet_config_rcv with the new cac_packet_buffer_enable function for operations that only enable or disable the packet processing buffer.

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.4 are:

Software Components	Version
API Library and Programs	0.9.6
Linux Device Driver	0.9.6
Solaris Device Driver	0.9.6
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.5.0		0.5.0
SDH Parser variation	0.5.0		0.5.0
Packet Processing variation	0.5.0		0.5.0
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.1		0.9.1

Known Issues

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:

  Under certain circumstances, bit errors have been seen in one or two E1 streams demultiplexed from an E3 contained in a TUG-3 from an AU-4 in the first STM-1 (signal structure: STM-1->AU-4->TUG-3->VC-3->E3->E2->E1). The errors have not been observed in other STM-1s with this structure or with other signal structures. The problem has also not been observed if the gapping for the STM-1 is set to the minimum of 48 using the -m or -g48 command-line option to the lp2_parsercfg program.

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

  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.

  The statistics counters for optical and electrical GIGE packets cannot be cleared execpt by reloading the FPGA configuration.

  Support for comprehensive GIGE interface status 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. Currently, the only work-around is to apply the bigphysarea patch to the 2.6 kernel. This problem has not appeared in Red Hat Enterprise 5, which has been tested up to RHEL5.2.