September 15, 2004

Overview

The following changes are introduced in this release:

Items Specific to LightParser:

• Support for mixed payload SDH structures.

• Modified stream ID numbering method.

• Support for bulk C-11, C-12, C-3 and C-4 container streams.

• New API functions for reading receive stream status.

• Hardware timeout and freeze problems fixed.

Items Specific to DPL3:

• Support for DS3 with C-bit framing.

• Improved handling of E3 and DS3 loss of sync.

General Items:

• Implemented software-generated time stamps for receive channels.

• Implemented channel notification as part of device driver reset.

• Linux device driver uses bigphysarea patch by default.

• Reduced stack usage in Linux device driver.

• New and modified utility programs.

• Modified diagnostic programs.

• New and modified demonstration programs.

• Changes to FPGA configurations.

• Component versions for this release.

• Known problems.

Notes:

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

Version 0.6.0 is a beta release of the Channelization API for DPL3 and LightParser Boards. This release 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: Support for Mixed Payload SDH Structures

The SDH parser is now capable of being configured to handle mixed payloads. For example STM-1 signals structured to include a combination of VC3 and VC-12 containers or a combination of VC-3, VC-11 and VC-12 containers which could contain combinations of E3, E1, DS3 and DS1 payloads. Note, however, that the extraction DS1 payloads or framed DS3 payloads is not yet supported.

The support for mixed payloads required a number of changes both in the logic of Virtex FPGA and the API functions for configuring the parser.

The old low-level functions (from prior releases) for configuring the SDH parser have been renamed or replaced. These functions are:

Old Name	New Name	Note
cac_parse_au4_c4	cac_parse_one_au4_c4
cac_parse_au4_tug3	cac_parse_au4_all_tug3	function arguments differ
cac_parse_au4_vc3	cac_parse_au4_all_vc3	function arguments differ
cac_parse_au3_c3	cac_parse_one_au3_c3
cac_parse_vc3_c3	cac_parse_one_vc3_c3
cac_parse_tug3_vc12	cac_parse_tug3_all_vc12_list
cac_parse_au3_vc12	cac_parse_au3_all_vc12_list
cac_parse_lovc_e4	cac_parse_lovc_one_e4
cac_parse_lovc_e3	cac_parse_lovc_one_e3	function arguments differ
cac_parse_lovc_e1	cac_parse_lovc_one_e1
cac_parse_lovc_ds3	cac_parse_lovc_one_ds3	function arguments differ

The old high-level functions for configuring homogeneous parsing structures have not changed except in their actual implementation. These functions are:

cac_parse_sdh_cfg_au3e1s	cac_parse_sdh_cfg_au3e3s
cac_parse_sdh_cfg_au4e1s	cac_parse_sdh_cfg_au4e3s
cac_parse_sdh_cfg_au4e4

A group of new API functions are added to configure specific containers and branches for mixed payload structures and to improve control over the various parser modules. The list of functions described is not yet be complete; development is continuing.

Parser module initialization:
	cac_parse_all_au4_init		cac_parse_one_au4_init
	cac_parse_all_au3_init		cac_parse_one_au3_init
	cac_parse_all_tug3_init		cac_parse_one_tug3_init
	cac_parse_all_vc3_init		cac_parse_one_vc3_init
	cac_parse_all_lovc_init		cac_parse_one_lovc_init
Single container / payload extraction:
	cac_parse_one_au4_c4		cac_parse_au4_one_tug3
	cac_parse_au4_one_vc3		cac_parse_one_au3_c3
	cac_parse_au3_one_tug2_vc12		cac_parse_tug3_one_tug2_vc12
	cac_parse_one_vc3_c3		cac_parse_lovc_one_c4
	cac_parse_lovc_one_c3		cac_parse_lovc_one_e4
	cac_parse_lovc_one_e3		cac_parse_lovc_one_e1
	cac_parse_lovc_one_ds3
Complete container / payload extraction:
	cac_parse_all_au4_c4		cac_parse_au4_all_vc3
	cac_parse_au4_all_tug3		cac_parse_all_au3_c3
	cac_parse_all_vc3_c3		cac_parse_tug3_all_vc12
	cac_parse_au3_all_vc12		cac_parse_lovc_all_c4
	cac_parse_lovc_all_c3		cac_parse_lovc_all_e4
	cac_parse_lovc_all_e3		cac_parse_lovc_all_e1
	cac_parse_lovc_all_ds3

A higher level API function is added for configuring the SDH parser by specifying a parse path and a list (array) of branch indexes. The function is named cac_parse_rcv_path_config.

Several macros are defined in the API for specifying the parse path. The examples below are those for extracting E1 streams:

PATH_STM1_E4_E3_E2_E1	Parse STM-1 to VC-4 to 64 E1s
PATH_STM1_TUG3_E3_E2_E1	Parse STM-1 to VC-4 to 3 TUG-3s to 48 E1s
PATH_STM1_TUG3_TUG2_E1	Parse STM-1 to VC-4 to 3 TUG-3s to 7 TUG-2s to 63 E1s
PATH_STM1_VC3_E3_E2_E1	Parse STM-1 to 3 VC-3s to 3 E3s to 48 E1s
PATH_STM1_VC3_TUG2_E1	Parse STM-1 to 3 VC-3s to 7 TUG-2s to 63 E1s
PATH_E4_E3_E2_E1	Parse an E4 signal from the CMI port to 64 E1s
PATH_E3_E2_E1	Parse an E3 signal from the Quad-E3 port to 16 E1s

The array of indexes specifies which of the branches at each level of the path, ordered from high level to low level. A special index value of -1 may be specified to have the function configure extraction of all the branches below that point in the path.

The method for numbering stream IDs, particularly for E1, E3, C3, DS3 and, eventually DS1, streams has been re-worked to handle cases where stream numbers could overlap for streams derived from different parse paths. This is discussed in the following section.

LightParser: Modified Stream ID Numbering Method

Stream IDs are the stream numbers used to specify which stream of a particular stream level is to be accessed by a channel when channels are opened.

The issue of stream ID overlapping arising from the support of mixed payload structures is resolved by inserting gaps between E1 or DS1 stream IDs coming from parse paths that could have conflicts.

A simple example is the case where VC-3 containers are configured to be extracted through different paths, the first extracting 21 E1 streams from a TUG-2 stream and the second extracting 16 E1 streams from a C3 container. The natural ordering of the streams from the second VC-3 would number the E1 streams starting at 16 which would conflict the stream number from the first VC-3 which are numbered from 0 to 20. The gapping method moves the 16 E1 streams from the second VC-3 so that their stream IDs start at 32, leaving room for the 21 E1 streams or even 28 DS1 streams from the first VC-3.

Two functions are included in the API to determine stream IDs based on a parse path and branch indices or based on a payload type and the natural stream number of the payload. The functions are:

cac_parse_path_to_streamid	Determine stream ID for a stream based on parse path and branch indexes
cac_parse_payload_to_streamid	Determine stream ID for a stream based on payload type and stream number

For both functions, either one of the parse path types or one of the payload types may be specified. Macros for payload types are defined in the API.

The stream IDs are used as the stream or framer value passed to the channel open functions. They are also used when generating grooming maps and can be used to extract valid status bits from the results of the new stream status function (described below).

Note that the maximum stream ID for level 1 streams has increased to 192 (96 per bank) to allow for the gaps.

For now the stream IDs are still sequential for the VC-4 to E4 SDH path and the purely PDH paths from the electrical E4 input and Quad E3 inputs.

LightParser: Support for Bulk C-11, C-12, C-3 and C-4 Container Streams

C-11, C-12, C-3 and C-4 bulk container streams

Channel types CAC_CHAN_MODE_C11, CAC_CHAN_MODE_C12, CAC_CHAN_MODE_C3 and CAC_CHAN_MODE_C4

Support for these channel types is added to the dplp_chantest, dplp_recv and dplp_alloctest diagnostic programs.

LightParser: New API Functions for Reading Receive Stream Status

A new API function, cac_parse_rcv_stream_status, retrieves the sync status of various container types for receive streams. It reads the relevant sync status registers for a specified container type and stream bank and stores the results in an array of bytes provided by the calling program.

The function provides arguments to retrieve and store both current and latched status information, although the latched status information is not yet supported by the hardware.

All of the available status bits for the container type and bank are stored in the array. For level-1 streams, such as E1, the array must be large enough to store 96 bits (12 bytes). The locations of the status for specific streams are based on the stream ID for the current parse path or payload type. The stream ID may be determined using the stream ID functions mentioned above. For example, the byte and bit location for a specific stream number of a specific payload type are determined by the stream ID in the following way:

      uint8_t status_array[12];
      int stream_id;
      int stream_stat;

      cac_parse_rcv_stream_status(CAC_HANDLE *, STREAM_STAT_E1,
          bank, status_array, NULL);
      stream_id = cac_parse_payload_to_streamid (
          payload_type, bank, 0, stream_number );
      
      stream_stat = status_array [ stream_id / 8 ] >> ( stream_id % 8 );
      /* If stream_stat is 1, the stream is in sync */

LightParser: Hardware Timeout and Freeze Problems Fixed

Timing problems that were the cause of three error conditions have been resolved.
1. Bit errors in received data have been resolved by improving the design and timing of the logic for the receive stream data buffers in the Virtex and Spartan FPGAs.
2. I/O timeouts while receiving raw STM-1 channels or data from the File-to-File interface have been resolved by improving clock-domain interfaces and fixing logic bugs in the Virtex FPGA.
3. Other timeout errors and possible system freezes could occur when setting the clock reference. These have been resolved by fixing problems with the SDRAM control logic in the Spartan FPGA and by modifying the cac_if_set_refclk API function to disable SDRAM accesses during the operation of changing the clock reference.

DPL3: Support for DS3 with C-bit Framing

The new expansion FPGA configuration for DS3 format supports both M13 and C-bit framing format. The framing format is controlled with a register setting controlled by the host system.

The new FPGA configuration file name is dpl3b-ds3t1-version (where version is 0-6-0 or similar). The FPGA configuration for DS3 M13-only format is no longer supported. The dpl_flashup program for DPL3 is modified to automatically substitute the new DS3T1 FPGA configuration type when updating boards that are configured for the old DS3M13T1 type.

The dpl_init program initializes the L3 framer for M13 framing when initializing boards with the DS3T1 L3 payload FPGA configuration.

The dpl_framercfg for DPL3 is modified to accept either the M13 or C-bit framing format option for boards with the new DS3T1 L3 format expansion FPGA configuration and to use the current framing format set in the L3 framer if the framing format is not specified on the command line.

Note that DS1 extraction from DS3 input (C-Bit or M13) currently supports only D4 framing. Support for DS1 ESF framing will be included in a future version of the FGPA configuration.

DPL3: Improved Handling of E3 and DS3 Loss of Sync

The new DPL3 Expansion FPGA configurations are modified to suppress data delivered to the host for bulk E3 and DS3 channels when the L3 framer reports an out of frame (RxOOF) or loss of signal (RxLOS) condition. For raw, unframed E3 and DS3 channels, data delivery is suppressed only for a loss of signal condition.

Loss of sync/signal errors are still provided when framer status interrupt queue entries are enabled. If framer status entries are not enabled, the suppression of data delivery will cause I/O timeout errors.

Implemented Software-Generated Time Stamps for Receive Channels

A mechanism to determine and report the time at which incoming data is received has been added to the device driver and API for LightParser and DPl3 boards.

The device driver gathers the time information based on when interrupts are received from the board, which is the closest known time of data delivery. (The hardware has no concept of "wall time"). The device driver can also extrapolate the time difference between the amount of data available in each channel buffer and the amount of data used for each I/O performed by the application.

Time stamps are reported using the standard timeval structure, used by the standard C-library function, gettimeofday, with a values for seconds and microseconds since 00:00:00, January 1, 1970, UTC. The precision of the time stamps is in microseconds, however, their accuracy is influenced by several factors including interrupt latency and the actual data rate of incoming signal.

The following functions for controlling and reporting time stamps are added to the LightParser and DPL3 API:

cac_chan_timestamp_mode	Enable, disable and set time stamp modes.
cac_chan_iotime	Report time stamp for previous I/O operation
cac_chan_read_ts	Read data from channel and report time stamp
cac_chan_io_ts	Determine available receive data and report time stamp

Details of the time stamp mechanism and the API functions are available in the Software Reference Manual.

Implemented Channel Notification as Part of Device Driver Reset

The device driver for both LightParser and DPL3 will now notify processes with open channels when the driver reset operation is invoked. The driver reset is invoked by the dplp_init and dpl_init programs.

The default notification is the delivery of the SIGKILL software signal. That signal cannot be caught or ignored and causes the processes to terminate which, in turn, will relinquish the open channel resource and free any memory resources used by the channel. Hence, the action is sometimes referred to as "purging".

A new API function, cac_chan_signal, may be used to modify the signal to be delivered or have no signal delivered at all. After a driver reset operation, active I/O operations on channels are terminated with an error condition and the value of errno is set to CAC_ERR_PURGED and the default notification of delivering SIGKILL is reinstated.

Linux Device Driver Uses Bigphysarea Patch by Default

The configuration of the Linux device driver will automatically use the bigphysarea patch if it finds the header file for it in the source directory for the currently running Kernel.

It is no longer necessary to specify --enable-bigphys on the command line for the conifgure program. There is a new option, --disable-bigphys that may be used in case the patch is installed but you do not want the device driver to use it.

Reduced Stack Usage in Linux Device Driver

Changes are made to the Linux device driver to reduce the amount of stack space consumed by some of the functions, especially in the ioctl routine and functions for allocating channel resources.

This was done to prevent stack over flow warnings that started occurring when run with Red Hat Enterprise Linux 3.0 and/or Linux Kernel version 2.4.21.

New and 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 use new hardware status reset control in the FPGAs for DPL3 and LightParser. For LightParser, dplp_init now only checks for CLK39 being present, not if it is locked, because the Spartan FPGA no longer has a DLL for the CLK39 signal.

The dplp_portcfg program for LightParser is modified to allow separate invocations to configure transmit and receive modes.

The new dplp_portstat program for LightParser reads and reports status of the LighParser ports and clock sources.

The dplp_streams program for LightParser is modified to include:

• A new -S option to specify the source of receive streams for streams other than those from the SDH and PDH parser.
• A new -D option to descramble and align received raw STM-1 data.
• Support for DS3 streams.

The dplp_groom program for LightParser is modified to allow for stream ID values up to 192.

The dplp_clock program for LightParser now includes support for default DS1, DS2 and DS3 rates.

Bug fixes in the dpl_framercfg program for DPL3 include:

• The display of the LCV and ZND status now shows them as being interrupt status rather than steady-state values by naming them "LCVi" and "ZNDi".
• The Comet framer initialization routine is no longer called if no configuration options other than loop-back modes are specified.
• Fixed to not turn off loop-back modes on all Comet framers if only one of the framers is being configured with loop-back off.

The dplp_info, dplp_find, dpl_info and dpl_find programs have a new -i option to identify the board or boards by blinking LEDs on the front panel and top edge of each board.

The dplp_info program for LightParser is also modified to display the CLK77 status as "OK" if it is both present and locked. The display of CLK39 status of "OK" means it is present, there is no longer a "locked" status for CLK39.

Modified Diagnostic Programs

The dpl_chantest and dplp_chantest programs include the following new features:
• Expanded the parameters to the -f option for LightParser to allow payload-oriented stream numbers to be specified, as opposed to stream ID numbers.
• Fixed the code for checking received ITU test patterns to properly detect single bit errors and modified the messages displayed when ITU pattern errors are detected.
• Added new E status code, indicating a data error was detected, for display modes 5, 6 and 7, and added the -E option to suppress the display of data error details.
• Modifications for use in test scripts include a new -Q option to suppress informational messages, a run-time specification appended to the -dt option, modified the methods for accumulating error counts and added tallying error counts to determine exit status of the program.
• Added -X option to specify and test handling of "purged" channels.
• The page table verification performed when the -V option is used now checks the page table index in each channel descriptor as well as the page table entries.

The dmatest and memtest programs for DPL3 and LightParser are modified to be more useful in test scripts:

• A new -Q option suppresses most of the informational messages.
• A new -i option for dmatest specifies the number of test iterations to perform (the memtest program already had this option).
• Changes to ensure the programs' exit status reflected whether or not errors occurred; 0 indicates no errors.

The dpl_framermon program includes the following modifications:

• Changes to support shared FPGA configuration for M13 and C-bit DS3 framing.
• Added -d and -D options to report DS3 overhead bit information.
• Fixed code that looks for changes in the FPGA's framer status registers so that it only considers status bits for the framers being monitored.
• Fixed the order in which L2 stream status is displayed.

New and Modified Demonstration Programs

The software configuration and build procedure now configures and builds the demonstration programs automatically. If the software is built in a separate build directory, the demo programs will be built in a new subdirectory named, "demo". Otherwise they are built in place as are the "bin" and "diag" programs. The software distribution still includes separate example Makefiles (Makefile.dpl3 and Makefile.dplp) that may be used to compile the demo programs using the installed library and header files.

New demo programs for DPL3 and LightParser, dpl3_timestamps and dplp_timestamps demonstrate how to use the new time stamp facility and related API functions. Both programs are compiled from a shared source file, dpl_timestamps.c.

New demo program for LightParser, dplp_streamstat, demonstrates how to use the new receive stream status function in conjunction with the payload stream ID function to read and display stream status for various signal structures.

The various parser configuration demo programs for LightParser are modified to use new API functions.

New demo programs for LightParser, dplp_cfg_au3_ds3s, dplp_cfg_au3_c3s and dplp_cfg_au4_c4, demonstrate how to configure the parser to extract DS3 streams and raw C-3 and C-4 container streams.

New demo program for LightParser, dplp_cfg_au3_mixed, demonstrates a simple example of configuring the parser for a mixed payload.

New demo program for LightParser, dplp_cfg_interactive, is an interactive parser configuration tool.

The dplp_stm1raw program has a new -D option to have it record descrambled data.

The dplp_multirec LightParser demo is fixed to work for E4 input from the electrical (CMI) port by using the CHAN_SOURCE_RAW_CMI macro when selecting the channelization source.

Changes to FPGA Configurations

The LightParser Spartan FPGA includes the following changes:
• The SDRAM controller logic is modified such that resetting the controller is done synchronously to avoid glitches on the control signals to the SDRAM.
• Modified sampling of data from the Virtex interface to use the rising clock edge.
• Page table error checking is added for transmit channels.
• Modifications to the clock error and status logic.
• A new interrupt status and mask bit to provide notification of certain error conditions on the board. The error conditions include DMA, page table entry, internal channelization queue, and clock loss errors.
• Modified logic for configuring Virtex FPGA from flash to handle larger configuration data size.

The LightParser Virtex FPGA includes the following changes:

• Extensive changes to support mixed-payload parsing and expanded stream ID range.
• Bug fixes to resolve timing problems for receive data streams.
• Bug fixes to resolve timeouts in raw STM-1 and File-to-File streams.

The DPL3 Main FPGA includes the following changes:

• The SDRAM controller logic is modified such that resetting the controller is done synchronously to avoid glitches on the control signals to the SDRAM.
• Page table error checking is added for transmit channels.
• Added soft reset controls to comet interface using existing reset registers.

The DPL3 Expansion FPGA for DS3 payloads includes the following changes:

• It now supports both M13 and C-bit framing with a register bit to select the operating mode.
• Added logic to disable Raw and or Bulk DS3 receive data during RxLOS and RxOOF conditions.
• Fixed the extracted DS1 sync status so that they indicate no sync when the related DS2 framers lose sync.
• The name of the configuration file is now dpl3b-ds3t1-version.

The DPL3 Expansion FPGAs for E3 payloads include the following changes:

• Added logic to disable Raw and or Bulk E3 receive data during RxLOS and RxOOF conditions.
• Fixed to disable Raw E3 transmit when not in serial loop-back mode.
• Fixed bug in extracting bulk E3 receive streams.

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

Component:	Version:
API Library and Programs	0.6.0
Solaris Device Driver	0.6.0
Linux Device Driver	0.6.0
LightParser Spartan FPGA Configuration	0.6.1
LightParser Virtex FPGA Configuration	0.6.0
DPL3 Main FPGA Configuration	0.6.0
DPL3 Expansion FPGA Configurations
E3 G751 E1 variation	0.6.0
E3 G832 Bulk variation	0.6.0
DS3 T1 variation	0.6.0
Generic variation	0.6.0

Known Problems

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

  Provisions for handling the higher number of level 3 stream IDs has not been completely implemented. When the SDH parser is configured for signal structures requiring gapped level 3 stream IDs, stream IDs may overlap with streams from a different port configured for bank 1.

  The function cac_parse_rcv_path_config does not work correctly with the path argument PATH_STM1_TUG3_C3. All other supported paths have been tested for a limited range of source, bank, and index arguments.

  The functions cac_parse_au3_one_tug2_vc12 and cac_parse_tug3_one_tug2_vc12 are not fully tested.

• DPL3:

  A problem in the Main FPGA configuration occasionally leaves the board in state which causes transmit channels to timeout on one or or more framers. This situation occurs primarily when the board is initialized and primarily affects the virtual L1 transmit streams. The only work-around is to reinitialize the board using the dpl_init program with its -M option.

  ESF framing is not yet supported for DS1 extraction from DS3 input.