March 31, 2004

Overview

Version 0.5.0 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: Expanded streams capability.

• LightParser: Added support for transmit channels.

• LightParser: Implemented host-to-host parsing.

• LightParser: Implemented grooming feature.

• LightParser: Added support for raw (unframed) E1 channels.

• LightParser: Increased maximum channel buffer sizes.

• DPL3: Added support for bulk and raw data for E3 and DS3 configurations.

• DPL3: Added support for E3 G.832 format.

• DPL3: Added frame-sync detection for Comet framers.

• DPL3: Implemented handling of Framer Status queue interrupts.

• DPL3: Added support for application notification of Comet and L3 Framer Interrupts.

• API: Added bulk and raw channel types.

• API: Added channel reset function.

• API: Added SDH parser configuration functions.

• API: Other changes to the API.

• Device Driver: Modified interrupt handling methods.

• Device Driver: Improved handling of channel read timeouts.

• Device Driver: bigphysarea is now used for the interrupt queue memory.

• New and modified utility programs.

• Modified diagnostic programs.

• New and modified demonstration programs.

• Changes to FPGA configurations.

• Component versions for this release.

Note: 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 hardware and software development continues to meet design requirements and usability issues.

LightParser: Expanded Streams Capability

The LightParser is now able to provide various combinations up to 128 E1 and/or 8 E3 and/or 2 E4 or STM1 streams in both the receive and transmit direction. Channels may be received from two ports at the same time using two banks of streams. Any of the LightParser's I/O ports may be chosen as the signal source for each stream bank. In addition, one stream bank may be sourced from the host-to-host connection described below. For STM1 inputs, the structure to be parsed for each incoming signal is specified separately.

The stream banks provide a logical separation between the streams corresponding to the two selected ports. For each stream level (i.e. E1, E3, E4 / STM1) the lower half of the stream numbers correspond to Bank 0 and the upper half to Bank 1. For example, if the Optical port is chosen as the receive port for Bank 0 and the Quad-E3 port for Bank 1, the corresponding stream numbers would be:

Port	E1 Streams	E3 Streams	STM1 Stream
Optical	0 - 63	0 - 3	0
Quad-E3	64 - 127	4 - 7	n/a

If, on the other hand, the CMI port (with E4) is chosen as the receive port for Bank 0 and the Optical port for Bank 1, the corresponding stream numbers would be:

Port	E1 Streams	E3 Streams	STM1 or E4 Stream
CMI	0 - 63	0 - 3	0
Optical	64 - 127	4 - 7	1

Current limitations:

• The SDH parser is currently capable of parsing a single input signal. This means that only one STM1 signal containing an SDH structure can be processed at a time. There is however, a separate STM1->E4 extractor for the CMI port that allows an E4 encapsulated in a STM1 to be processed in one receive bank at the same time an SDH structure from the Optical port is being processed for the other receive bank.

• Limitations on the bandwidth between the parser engine (Virtex FPGA) and Host interface (Spartan FPGA) preclude operating with all possible streams at the same time. See the "LightParser Hardware Reference Manual" for details.

LightParser: Added Support for Transmit Channels

Sending channelized data from the host and PDH multiplexing (E1s up to E3 and E4) is now implemented for LightParser. Similar to the receive streams, two banks of transmit streams are available. The signal structure for each bank is specified separately and directed to separate output ports.

For example, outgoing E1 streams 0 - 63 can be built up to an E4, inserted in a STM1 structure and transmitted out the Optical or CMI port while E1 streams 64 - 127 can be built up into 4 E3 streams for transmission out the Quad-E3 port.

In addition, STM1, E4 or E3 streams sent from the host may be sent to the host-to-host connection described below.

Incoming E1 streams may be selected and mapped into outgoing signal structures directed to output ports using the grooming feature described below.

Current limitations:

• Only E1 streams from the host can be multiplexed into higher-level PDH structures.

• There is no provision for building general SDH structures from outgoing streams. Transmit signals can consist of E3 streams for the Quad-E3, E4 or E4 encapsulated in a STM1 for the CMI port and E4 encapsulated in a STM1 for the Optical port. Note that there is only one E4-to-STM1 inserter which may be used to transmit out the Optical or CMI port.

LightParser: Implemented Host-To-Host Parsing

Host-to-Host parsing is the ability to send STM1, E4 or E3 data from the host to the LightParser, feed it through the parsing engine and receive data from the parsed streams. This feature provides for file-to-file capability that allows, for example, E1 streams to be extracted and recorded from a pre-recorded STM1 data file.

The host-to-host operation for a STM1 or E4 stream can be performed at rates from 1 to 2 times real-time, depending on the number of streams to be extracted. The rates can go even higher for E3 streams.

LightParser: Implemented Grooming Feature

The LightParser's "grooming" feature provides the mechanism to map as many as 128 incoming E1 streams from the two incoming banks to as many as 128 outgoing E1 streams (64 per bank). The incoming and outgoing banks may be connected to different I/O ports with different signal structures.

An interactive program, dplp_groom, is provided for configuring the grooming map. API functions are also provided for downloading the grooming map and checking it for errors (e.g. attempting to connect two different incoming E1 streams to the same outgoing E1 stream).

The incoming E1 streams being mapped are also available to the host as receive channels. However, use of the grooming capability cannot be used at the same time as sending streams from the host.

Current limitations:

• Similar to the restrictions on transmitting from host channels, there is no provision for building SDH structures from "groomed" output streams. Transmit signals can consist of E3 streams for the Quad-E3, E4 or E4 encapsulated in a STM1 for the CMI port and E4 encapsulated in a STM1 for the Optical port. Note that there is only one E4-to-STM1 inserter which may be used to transmit out the Optical or CMI port.

LightParser: Added Support for Raw (Unframed) E1 Channels

E1 streams may now be accessed as Raw data. In this mode, the data from an E1 stream can be received whether or not frame sync is detected.

The raw or framed mode can be individually selected for each available E1 stream. Channels may be initially opened in either mode by specifying stream type CAC_CHAN_MODE_E1 or CAC_CHAN_MODE_E1_RAW. The channel open functions are modified to set the appropriate stream mode in the Virtex. The mode may also be changed at any time using the cac_parse_set_e1_mode API function. Note that the mode is set for the stream, not an individual channel. When multiple channels are open from the same stream, all of them receive in the same mode.

LightParser: Increased Maximum Channel Buffer Sizes

The maximum size of an individual channel buffer has been increased from 16 megabytes to 32 megabytes. The total amount of memory for channel buffers per board has been increased from 64 megabytes to 128 megabytes.

The boot parameters for Linux systems configured to use the bigphysarea patch should be modified to provide the additional memory, if required. (See also interrupt queue memory).

DPL3: Added Support for Bulk and Raw Data for E3 and DS3 Configurations

DPL3 FGPA Expansion FPGA configurations for L3 payloads now provide bulk payload and raw data channels as well as channels for the embedded payloads (e.g. E1 or DS1 streams). The following macros are used for the modes argument to the channel open functions:

CAC_CHAN_MODE_E3	to specify a raw E3 channel
CAC_CHAN_MODE_E3_BULK	to specify a bulk E3 channel

Either bulk payload data or raw data may be received. Only Bulk payload data may be transmitted.

DPL3: Added Support for E3 G.832 Format

A New DPL3 FGPA configuration provides support for receiving and transmitting G.832 E3 format. Currently, only Raw and Bulk payloads are supported.

Configuring the DPL3 boards for E3 G.832 payloads requires loading the specific Expansion FPGA configuration. Use the dpl_flashup program specifying the g832bulk payload type. For example:

dpl_flashup -L3 g832bulk dpl0

DPL3: Added Frame-Sync Detection for Comet Framers

Logic added to the DPL3 Main FPGA configuration to detect frame-sync in the incoming signals from the Comet framers. This includes E1 mode basic framing in slot 0 and framing in both D5 and ESF T1 modes.

When frame sync is not detected, no data is provided to open receive channels on the host. This will occur if the Comet framers lose frame sync or signal. During periods of no frame sync, attempts to read data from channels on the affected framers will result in timeout errors or, if the new framer status queue interrupts are enabled, the error code will indicate lack of framer sync.

DPL3: Implemented Handling of Framer Status Queue Interrupts

Framer status queue entries, like channel data queue entries, are entries written by the board to the interrupt queue. However, rather than indicating data transfers for an open channel, they indicate framer synchronization status. The synchronization status is determined by the board's logic that detects basic frame sync from the Comet framers and E1 or T1 streams embedded in an E3 or DS3 signal.

Generation of framer status entries is not enabled by default (after board start-up or running dpl_init). The following API functions are added to control the generation of framer status entries.

cac_queue_status_mode()	Enable or disable queue status entries with an open queue resource
cac_queue_status_mode_name()	Enable or disable queue status entries for a named DPL3 board
cac_queue_status_mode_num()	Enable or disable queue status entries for a given DPL3 board number

The boards framer status mask must also be enabled for each framer being used. This is handled automatically by the channel open functions.

Without queue status entries enabled, reading from channels whose framers are out of sync results in timeout errors, as before. When queue status entries are enabled, the board writes a set of queue entries anytime the status changes for a framer in use. The device driver uses framer status entries in the queue to maintain framer synchronization status for each open receive channel.

Details of the implementation and handling of loss of sync conditions are described in the API documentation. In general, the first time a read operation (e.g. cac_chan_read) encounters a loss of sync condition it will return immediately with the error code (errno) of CAC_ERR_NO_SYNC. Subsequent read operations, while the loss of syc condition persists, will return the CAC_ERR_NO_SYNC error after the normal channel timeout period.

DPL3: Added Support for Application Notification of Comet and L3 Framer Interrupts

Application programs can request notification of interrupts from the Comet and L3 interface chips on the DPl3 board.

Notification is in the form of a software signal delivered to the application by the device driver when the interrupt is serviced. To utilize this feature an application must perform the following operations:

1. Include and "install" a signal-handler function for servicing the software signal. This function will need to access the Comet or L3 interface registers to determine the cause of the interrupt and take steps to clear the condition. The function is "installed" as a handler for the signal using one of the standard system calls provided by the C library such as sigaction or signal.

2. Prepare the interrupt mask registers of the Comet or L3 framer (XRT72L50) to generate an interrupt for the desired conditions.

3. Enable the interrupt notification using the cac_comet_irq_enable function for Comet interrupts or the cac_l3_irq_enable function for L3 framer interrupts.

   When the signal is delivered to the application interrupts are not automatically re-enabled. The cac_comet_irq_enable and / or cac_l3_irq_enable must be called again after servicing the interrupt. This may be done as part of the application's signal handler function.

See the API documentation for details.

API: Added Bulk and Raw Channel Types

The notion of Framed or Bulk versus Raw mode is introduced for some stream types.

For E1 and DS1 streams, the default mode is framed, which can be accessed as a full stream or as separate or grouped time slots. The Raw mode for E1 and DS1 streams means an unframed stream of bits.

For higher level streams, E3 and E4, the default mode is Raw, meaning the stream includes all of the overhead and framing data. Bulk mode for these stream types provides the framed and extracted data without the overhead and framing data. STM1 streams are always in Raw mode.

New macros for channel types are added to be used in the modes argument to the channel open function, along with the CAC_CHAN_MODE_RCV and CAC_CHAN_MODE_XMT macros to specify the channel I/O direction. The table below shows the macros, their meaning and implementation status for DPL3 and LightParser boards.

Channel Type Macro	Stream Type
CAC_CHAN_MODE_E1	Framed E1
CAC_CHAN_MODE_E1_RAW	Raw, Unframed E1
CAC_CHAN_MODE_DS1	Framed DS1
CAC_CHAN_MODE_DS1_RAW	Raw, Unframed DS1
CAC_CHAN_MODE_E3	Raw E3 with overhead
CAC_CHAN_MODE_E3_BULK	Bulk E3 without overhead
CAC_CHAN_MODE_DS3	Raw E3 with overhead
CAC_CHAN_MODE_DS3_BULK	Bulk E3 without overhead
CAC_CHAN_MODE_E4	Raw E4 with overhead
CAC_CHAN_MODE_E4_BULK	Bulk E4 without overhead
CAC_CHAN_MODE_STM1	Raw STM1 with overhead

Currently the LightParser supports framed and raw E1 channels and only raw mode for higher level streams. The DPL3 supports only framed E1 and D1 and both raw and bulk mode for E3 and DS3 streams.

API: Added Channel Reset Function

The new cac_chan_reset API function provides the means of resetting the buffer pointers for a channel to be used in the event of timeouts or loss of sync.

Resetting the channel combines disabling the channel, waiting for channel activity to stop and clearing the board's as well as the device driver's buffer pointers for the channel. The channel remains disabled, leaving it up to the application program to re-enable it using the cac_chan_enable function.

See the API documentation for details.

API: Added SDH Parser Configuration Functions

The following new functions are added for LightParser to configure SDH parser algorithms to extract streams from common STM1 signal structures. They all require a CAC_HANDLE * argument obtained from the cacopen function.

cac_parse_sdh_cfg_au3e1s	Extracts 63 E1 streams from 3 AU3 streams containing 63 VC12 streams.
cac_parse_sdh_cfg_au3e3s	Extracts 3 E3 and 48 E1 streams from 3 AU3 streams.
cac_parse_sdh_cfg_au4e1s	Extracts 63 E1 streams from an AU4 stream containing 3 TUG3 streams with 63 VC12 streams.
cac_parse_sdh_cfg_au4e3s	Extracts 3 E3 and 48 E1 streams from an AU4 stream containing 3 TUG3 streams which contain an E3 stream.
cac_parse_sdh_cfg_au4e4	Extracts an E4, 4 E3 and 64 E1 streams from an AU4 stream containing an E4

API: Other Changes to the API

Macros are added to use for specifying a framer or stream number in the framer argument to chanopen functions.

DPL3_COMET_FRAMER(comet)	The comet framer number 0, 1, 2 or 3, is converted to the corresponding DPL3 framer number 28, 29, 30 or 31.
DPLP_STREAM_BANK0 DPLP_STREAM_BANK1	These are bitwise OR-ed with the stream number to offset the value into the specified stream bank.

The following new error codes have been added. These are returned as the value of errno when an API function returns with an error.

CAC_ERR_BUFFERSIZE	- Requested channel buffer size exceeds maximum.
CAC_ERR_IO_INVAL	- Invalid framer configuration for DPL3 or invalid port configuration for LightParser.
CAC_ERR_NO_SYNC	- Framer is not in sync or lost sync (DPL3 only).

The CAC_OPEN_NOMAP_VIRTEX macro for the flags argument to cacopen_with_flags() has been renamed to CAC_OPEN_MAP_NOVIRTEX and a new macro, CAC_OPEN_MAP_MINVIRTEX, has been added.

The cac_framer_init function for DPL3 has been removed from the API in favor of the separate functions for configuring the Comet framers and the L3 interface components.

The LightParser port configuration function, cac_if_set_refclk is modified to force the CMI port to STM1 mode if it is chosen as the clock reference.

The LightParser cac_parse_parser_source function has a new argument to specify the stream bank and new macros to differentiate between STM1, E4 and File-to-file sources.

Extra register read operations are added to the low-level I2C access macros as a delay mechanism to solve timing problems in the LightParser EEROM functions on systems that perform very fast PCI read operations.

Device Driver: Modified Interrupt Handling Methods

The method for handling interrupts on both DPL3 and LightParser boards is changed in two ways.

The first involves both the Solaris and Linux device drivers which are modified to use a new method of temporarily disabling the board's IRQ output while servicing an interrupt. This involves a new bit in the board's mask register that disables interrupts without having to modify the active interrupt mask bits. The interrupt disable bit is controlled only by the interrupt handling and initialization procedures in the device driver.

The second change only involves the device driver for Linux. The Linux device driver is modified to use kernel thread processes (one per board) to service interrupts. This method replaces the use of a Linux tasklet to service interrupts and allows the interrupt servicing operations to use semaphores to synchronize with operations performed by the user-level I/O operations in the device driver. The synchronization provides race-condition avoidance for operations involving registers on the board as well as status and buffer-related variables in the device driver's data structures.

The interrupt service threads become processes in the system which are named for the board instances. Examples of the process names are dpl0intr and dpl1intr for DPL3 boards or dplp0intr and dplp1intr for LightParser boards. These processes are spawned when the device driver is loaded and are terminated when it is unloaded.

The tasklet method is still supported, for the time being, as a compile-time option in case problems arise that may be due to the kernel threads. The tasklet method can be enabled by editing the cacdrv_options.h file and changing the line defining CAC_INTR_THREAD to read:

    #define CAC_INTR_THREAD 0

Once the kernel thread method has proved reliable, this macro and the code implementing the tasklet method will be removed.

Device Driver: Improved Handling of Channel Read Timeouts

Channel read operations requesting amounts larger than the channel's latency amount are broken into chunks equal to or less than the latency. In this way, the device driver can spend time copying data to the application's memory space while new data is arriving.

In previous versions of the device driver if a timeout error occurs while waiting for new data to arrive the error condition was returned immediately to the user, discarding any data that had been available prior to the timeout.

In the new version the timeout error (or a loss of sync error detected after a timeout) is returned only if no data was available. If some amount of data was available the error is deferred and the read operation will return a value indicating the the number of bytes that were available.

Device Driver: Bigphysarea is Now Used for the Interrupt Queue Memory

The interrupt queue memory is now allocated from bigphysarea memory on Linux systems configured to use the bigphysarea patch.

The bigphysarea boot parameters for such systems (in grub.conf or lilo.conf) should be modified to include an additional page of memory per board.

New and Modified Utility Programs

The first list of changes affect both DPL3 and LightParser boards:

The Xilinx XSVF configuration files for the DPL3 and LightParser (Spartan FPGA) now include commands to verify the configuration after downloading. The status of download operation indicates a failure if the verification does not succeed. The dpl_flashup and dplp_flashup programs are modified to retry the download up to three times.

The following changes are for LightParser boards, only:

The dplp_init program is modified to set the board's clock reference to the local clock source and reset the clock DLL in the Spartan FPGA. This avoids "clock not present" errors after reconfiguring the Virtex.

The dplp_portcfg program is modified to support new capabilities of the board. The -P option is removed and replaced with a -S used to specify which stream bank, if any, should be sourced by incoming data from the selected port. It is also modified to provide addition options for selecting the source of data to be transmitted out the selected port.

The new dplp_streams program configures the stream connections between the host and parser engine for receive and transmit channels.

The new dplp_groom program provides interative configuration of the grooming map.

The new dplp_clock program sets the E1, E2, E3 and E4 rates for outgoing signals (transmit channels).

The following changes are for DPL3 boards, only:

The dpl_init program now clears both framer status mask registers. Previously only Framer Stat 1 Mask was cleared.

The dpl_flashup program is modified to use the L3 payload type for determining the name of the Expansion FPGA configuration file and to use the name, "generic", for Main FPGA configuration file names.

The dpl_framercfg program is modified so that it will configure the Comet framers if any Comet configuration option os specified and/or configure the L3 interface if any L3 configuration option is specified. It also chooses default modes for the Comet framers based on the current primary mode (E1 or T1) and chooses default modes for the L3 interface based on the currently loaded L3 payload FPGA configuration. The status options (-s for Comet status and -S for L3 interface status) are now implemented.

The dpl_clock program has been renamed dpl_pll.

The dpl_liu and dpl_jat programs are no longer supported and are removed from the distribution. They are replaced by the dpl_framercfg utility program.

Modified Diagnostic Programs

The Makefile for the diagnostic program is modified to include -D_REENTRANT in the compiler options. This option is required to include thread-safe code for the use of the global variable, errno provided by the system.

The DPL3 program, dpl_comet, is no longer supported and is removed from the distribution. Its function has been replaced by the dpl_framercfg utility program.

Minor bugs are fixed in the dpl_memtest, dplp_memtest, dpl_dmatest and dplp_dmatest programs.

Options to specify raw and bulk channel modes are added to the dpl_chantest, dplp_chantest, dpl_alloctest, dplp_alloctest, dpl_recv, dpl_recv, dpl_send and dplp_send programs. Note that it is possible to specify raw and bulk channel modes that are not yet supported.

The dpl_chantest and dplp_chantest programs include the following new features:

• A new queue mode option, -qs, enables framer status interrupt queue options (currently for DPL3 only).
• A new display mode option, -d6 shows receive channel sync status, similar to -d5 but will start a new display line when "significant" status changes occur.
• The Sync Status display modes (-d5 or -d6 option) includes new codes to indicate timeouts, framer sync status and inactive channels. A list of the codes and their meanings is displayed when the program is started with this display mode option.
• A -dt option is added to include display of elapsed time in the program's status display and a -dc option is added to compress the status display. These options may be included as part of the display mode option (e.g. -d5t) but the 'c' or 't' must appear after the display mode number.

The dpl_send and dplp_send programs have a new -D option to specify a startup-delay.

New and Modified Demonstration Programs

The Makefile.dplp and Makefile.dpl3 files for the demonstration program are modified to include -D_REENTRANT in the compiler options. This option is required to include thread-safe code for the use of the global variable, errno provided by the system. It is recommended that customers' applications be compiled with this flag, as well.

The dpl3_e1rec and dpl3_slotrec programs are modified to enable or disable framer status interrupt queue entries controlled with a new -Q command line option.

The dpl3_e3rec program is modified to support bulk or raw mode controlled by new -B and -R command line options.

The dplp_multirec program is modified to use the new SDH parser configuration functions in the API, to use the new _STM1 specific PARSE_SOURCE_ macros and add the bank argument for the call to cac_parse_parser_source() and to support multiple, simultaneous, stream types.

The dplp_stm1raw program and the LightParser programs demonstrating parser configuration are modified to use the new _STM1 specific PARSE_SOURCE_ macros and add the bank argument for the call to cac_parse_parser_source().

The new dplp_file2file program demonstrates various capabilities of, and provides an example method for using, the LightParser's host-to-host channelization feature. It currently requires that the board be configured using the dplp_streams program.

Changes to FPGA Configurations

The DPL3 logic is re-partitioned to use the Expansion FPGA for E3 and DS3 payload processing. The additional FPGA resources allow for providing bulk and raw L3 streams with the same configuration that extracts and inserts E1 or T1 streams in the L3 signal. The resources made available in the Main FPGA are used for added functionality and make future enhancements possible.

Functionality added in the DPL3 Main FPGA includes:

• host interrupt disable logic used by the device driver
• host interrupt mask and status for Comet and L3 framer interrupts
• frame sync detection for the Comet framer signals
• frame sync status and mask registers for the Comet signals
• Comet framer status queue interrupt entries

A new Expansion FPGA configuration is included to provide bulk and raw G.832 E3 streams.

Some of the architecture on the LightParser has been re-partitioned to move logic for high-level raw data buffering and stream separation from the Spartan FPGA to the Virtex. This was necessary to provide the higher bandwidth and increased buffering required to handle multiple, simultaneous stream types.

Other functionality added in the LightParser Spartan FPGA includes:

• host interrupt disable logic used by the device driver
• increased host page table size to double the total amount of usable channel buffer memory (to 128 MB)
• doubled the maximum size for an individual channel's host buffer (to 32 MB)

The LightParser's Virtex FPGA has new logic to implement:

• transmit channels from the host
• enhanced signal routing between host channels, parser modules and I/O ports
• host-to-host processing
• grooming and re-transmit
• receiving raw E1 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.5.0 are:

Component:	Version:
API Library and Programs	0.5.0
Solaris Device Driver	0.5.0
Linux Device Driver	0.5.0
Light Parser Spartan Configuration	0.5.2
Light Parser Virtex Configuration	0.5.0
DPL3 Main FPGA Configuration	0.5.2
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