November 4, 2005

Overview

This release is primarily to support the new LightParser2 board.
It does not include any new functionality for LightParser or DPL3.
However, it does include some software features and bug fixes that apply to those products as well.

The following changes are introduced in this release:

Items Specific to LightParser2:

• Initial support for LightParser2.

Items Specific to LightParser:

• New SDH transmit FPGA configuration type.

Items Specific to DPL3:

None

General Items:

• New hardware support version identifiers.
• Additional software version compatibility checking.
• Updates to the API headers and function library.
• Modified utility programs.
• Modified diagnostic programs.
• New update for the bigphysarea patch for Linux kernel.
• Modifications for 64-bit compatibility.
• Component versions for this release.
• Known problems.

LightParser2: Initial Support LightParser2 Boards

This release includes the initial software support and FPGA configurations for LightParser2 boards. The current, phase I, implementation provides the following capabilities:
• Receive and transmit STM-1, STM-4 or STM-16 signals with the two optical ports.

• SDH grooming down to the STM-0 level between the two optical ports.

• Receive selected SDH data streams on the host. The data channelized to the host can be sixteen STM-1 streams, four STM-4 streams, a single STM-16 stream or any combination of STM-1 and STM-4 streams totaling up to one STM-16 worth of bandwidth.

• Data to the host can be streamed into a circular DMA buffer in host memory (as is done with the DPL3 and LightParser) or snapshots can be captured in a host DMA buffer.

The API library, device drivers and application programs are configured and built separately for LightParser2. The option for the configure script for configure the software for LightParser2 is --enable-dplp2.

The standard support programs have been modified to support the LightParser2 including lp2_init, lp2_info, lp2_flashup, etc. In addition, the new lp2_portcfg, lp2_portstat, and lp2_sdhgroom programs have been written specifically to support LightParser2. The diagnostic programs have been also modified to support LightParser2 including the ability to record snap-shots to disk with the lp2_recv program.

There is an example program for LightParser2 called lp2_stm1rec that selects up to sixteen STM-1 streams from the two optical inputs for recording. (The systems it has been tested on are actually only able to record up to four STM-1 channels simultaneously). The program's source code demonstrates how to to use API functions to configure the optical ports, the SDH groomer and channelization accumulator as well as open channels and record the data using threads.

The basic operations of opening channels and the control resource on LightParser2 are the same as for LightParser and there are currently no simple demonstration / example programs for those API functions specifically for LightParser2.

A hardware reference manual for LightParser2 is available on the CDROM distribution and at http://www.cacdsp.com/manuals. Updated software API and utilities reference manuals for LightParser2 will be available soon. The HTML format API reference manual generated from the source code comments is updated and available on the CDROM and a http://www.cacdsp.com/software.t

For software configuration and installation, please see the "Installation Instructions" available on the CDROM or at http://www.cacdsp.com/software.

LightParser: New SDH Transmit FPGA Configuration Type

A new virtex configuration under development will provide the capability of transmitting streams multiplexed into various SDH structures. A separate Virtex FPGA configuration is required for this capability because the required logic would not fit in the FPGA along with all of the capabilities of the standard FPGA design.

The new configuration type is called sdhtx and the FPGA configuration files will be named dplp-virtex-sdhtx-version.bin.

New Hardware Support Version Identifiers

When new features or other changes made to one board type require an update to software it would be necessary to rebuild the FPGA configurations for all board types just to bring their version numbers up to date, even if there are no functional changes. Now that the software code base supports three different type of hardware, it is no longer practical to identify compatibility between software and hardware versions using a single version for the API library.

New version identifiers are added to the API to identify the compatibility between the software (API and device driver) and hardware (FPGA configurations). There are called Board Support Versions and they identify the compatibility between the software and the FPGA configurations for each board type and each sub-type of configuration.

Each board type has a generic board support version and versions for various sub-types. The generic version number pertains, in general, to the primary host interface aspects of the board. The sub-type versions have to do with the L3 payload types for DPL3 boards, the parser capabilities in the Virtex FPGA for LightParser, and as yet undetermined type differences for LightParser2 boards.

Additional Software Version Compatibility Checking

The API functions used to access the control resource of DPL3, LightParser and LightParser2 boards now check the library and device driver versions for compatibility. The cacopen() and cacopen_with_flags() functions will return an error if the two versions do not match in the fist two, major and minor, components of the version numbers. The value of errno will be set to CAC_ERR_SW_VERS_MISMATCH.

This version check was added to avoid problems that can occur if application programs are linked with a version of the library that is not compatible with the version of the device driver loaded on the system. Note that applications linked with libraries prior to version 0.8.0 will not perform this additional check.

It is possible to disable the version check by using cacopen_with_flags instead of cacopen and including the new flag macro, CAC_OPEN_IGNORE_VERS, in the flags argument. Another new macro available for cacopen_with_flags is CAC_OPEN_REPORT_VERS. Using this flag will have the function report the API library and device driver versions with a message written to stdout.

Updates to the API Headers and Function Library

Bug Fixed in Channel Open Functions:
The channel open functions now initialize a new channel descriptor to the open / inactive state. The previous intialization of the state to 0, could cause the board to stop processing other channels using the same framer or stream id.

New Channel Status Library Function:

A new library function is added to the API (along with a new data structure type and an ioctl request in the device drivers) for obtaining various channel status information from the device driver. It is primarily intended for diagnostic purposes.

The function prototype is:

    int
    cac_chan_stat(CAC_CHANNEL *chan, cac_channel_stat_t *chanstat)

The contents of the cac_channel_stat_t structure are:

    int      chan_swid   /* software ID of channel */
    int      chan_hwid   /* hardware ID of channel */
    uint32_t chan_modes  /* mode and type flags */
    uint32_t chan_state  /* current state and condition flags */
    uint32_t buf_head    /* channel buffer head (byte offset) */
    uint32_t buf_tail    /* channel buffer tail (byte offset) */
    uint32_t buf_bytes   /* number of bytes left / available in the buffer */

New Channel Snap-shot Library Function:

A new library function, cac_chan_snapshot, is added to the API. This function activates a channel to receive one buffer full of data, a snap-shot. It is only supported for Receive channels on LightParser2 boards.

This is similar to the cac_chan_enable function except the board automatically disables the channel after filling the channel buffer in the host. It is used to avoid buffer overflow in situations when the host processing would not be able to keep up with high-bandwidth data such as STM-16 or multiple STM-4 channels. The application can call the function multiple times, after processing the data, to capture additional snap-shots.

The function prototype is:

    int
    cac_chan_snapshot(CAC_CHANNEL *chan)

Modified Argument Data Types for LightParser Port Control Functions:

The port argument to the cac_if_ functions is changed from uint32_t to int. The dir argument to cac_if_reset is changed from uint8_t to int. The mode argument to cac_if_set_refclk is changed from uint32_t to int.

New Error Codes:

Error codes are values assigned to the errno global variable to describe the reason for a failure or error status returned from a function. The CAC software API defines some unique codes to provide more specific error diagnostic information. Several new error codes are added to the API wiht this release:

CAC_ERR_SW_VERS_MISMATCH	-	API and device driver versions are not compatible.
CAC_ERR_INVAL_TIMESLOT	-	This code applies to invalid E1 or T1 slots when opening channels on DPL3 or LightParser boards and invalid accumulator time slots when configuring the LightParser2 SDH data accumulator.
CAC_ERR_INVAL_GROOM_PORT	-	An invalid groomer port or STM-16 index specified when configuring the LightParser2 groomer.
CAC_ERR_INVAL_GROOM_INDEX	-	An invalid STM-4, STM-1 or STM-0 index specified when configuring the LightParser2 groomer.
CAC_ERR_INVAL_STREAMTYPE	-	An invalid stream type (not STM-16, STM-4, STM-1 or STM-0) specified when configuring the LightParser2 groomer. (This may also be applied to channel types or parser stream types in the future.)
CAC_ERR_EE_WRITE_PROT	-	An attempt to write data to the EEROM on a LightParser2 failed because the EEROM is write-protected (or writing is disabled).
CAC_ERR_CHECKSUM	-	A cecksum error is detected while reading information for the optical SFP on LightParser or LightParser2 boards. (This could be used for other checksum errors in the future.)
CAC_ERR_NO_MMC	-	Attempt to access the MMC on a LightParser2 failed because the MMC card is not installed.
CAC_ERR_MMC_INVAL_MAGIC	-	The "magic number" is invalid LightParser2 MMC header, directory or FPGA data area. This usually occurs if an uninitialized MMC is installed.
CAC_ERR_MMC_DATA	-	A mismatch is detected while verifying FPGA configuration data on a LightParser2 MMC.
CAC_ERR_MMC_SPACE	-	No space available or an invalid location is specified in a LightParser2 MMC.
CAC_ERR_MMC_SERIAL_MISMATCH	-	The serial number in an MMC does not match the LightParser2 board serial number. This error will be used when storing board-specific data in an MMC is implemented.

Reorganization of Header File Contents:

Some function prototypes and macros that are specific to board types or features have been moved out of the general chan_util.h header file into new or existing header files. These changes are mostly informational as they do not affect typical applications' use of the header files. The general header file will automatically include whatever other header files are required based on the software configuration.

For DPL3 software, the prototypes for functions that operate on the Comet framers are now in chan_l1.h. Prototypes for functions that operate on the L3 framer and other components are now in chan_l3.h.

For LightParser software, the prototypes for functions that operate on the actual parser logic are now in chan_parser.h. Prototypes for functions that operate on the I/O ports and related devices and logic are now in a new header file named chan_lpio.h. Macros that are specific to the I/O ports and related devices are moved from chan_parser.h and chan_util.h into chan_lpio.h.

Function prototypes and macros for LightParser2 I/O operations are in the new chan_lp2io.h header file.

In addition to those header files, several common macros and definitions shared by the device drivers and the API are moved from chan_util.h and from the separate device driver header files into the chan_ioctl.h header file.

Modified Utility Programs

Aside from the changes and new functionality to support LightParser2 boards, this release includes the following changes to utility programs:

The dpl_init and dplp_init programs are modified to use the new hardware version checking identifiers. The Main and Spartan FPGA versions are compared with the API's generic board support version. The Expansion and Virtex FPGA versions are compared with the appropriate API sub-type version.

The dplp_init program now resets the Quad-E3/DS3 port and device.

The _init programs are also modified to allow multiple board names to be specified on the command line.

The dpl_flashup, dplp_flashup and lp2_flashup programs now invoke the appropriate _init program after any FPGA configuration updates that require board initialization. This automatic initialization may be defeated with the new -i option.

The _flashup programs are also modified to use the -r command line option to specify that FGPAs not be reconfigured after updating configuration data and/or information. This is primarily useful for saving time when updating FPGAs on multiple boards. The former use of the -r option, to "reload current versions", was redundant with the -f option to "force reloading of the current configuration data".

The dpl_info, dplp_info and lp2_info programs will now display the API software and board support versions even if a board could not be opened. Also, version numbers are now displayed with dots instead of dashes as separators (i.e. 1.2.3 instead of 1-2-3).

The dplp_sfputil and lp2_sfputil programs have a new -i option to display only the vendor information then exit (non-interactively). These programs also have a few minor bug fixes.

The dplp_multi_rec program is fixed so that it "joins" threads that were active but whose channels have already been closed.

Modified Diagnostic Programs

Aside from the changes and new functionality to support LightParser2 boards, this release includes the following changes to diagnostic programs:

The dpl_debug, dplp_debug and lp2_debug programs are modified to accept multiple commands per prompt, separated by semicolons. The programs also are modified to allow a "0x" prefix for addresses, set the initial region is now bar 1, the FPGA registers. They also include bug fixes for crashing at the end of the "source" command and accessing EEROM.

New Updates for the Bigphysarea Patch for Linux Kernel

A bug is fixed in the bigphysarea kernel patch to avoid integer overflow while checking for free space available. The bigphysarea patch for the Linux kernel is required for 2.4 kernels if more than 10 or 12 MB of channel buffer memory is required. The patch is not required for 2.6 kernels but may be used if desired. The patch is not included in the ChanAPI software distribution archive but is available on the ChanAPI CD-ROM and via FTP at:

ftp://ftp.cacdsp.com/pub/misc/bigphys_rh.tar.gz

The first set of changes fixes a problem with the way the patch marks the memory it grabs as a busy resource. The original version uses the virtual address of the memory when requesting the resource instead of the physical address. It also sets the end address of the requested resource one byte past the actual end of the space it is given. On some systems the incorrect memory range will overlap the address of other required resources. These errors have been corrected to resolve this problem.

The second set of changes is for support of the 2.6 Linux kernel and Red Hat Enterprise Linux version 4. Minor additions to the actual code for the patch are included and a new set of installation instructions for Red Hat Enterprise Linux version 4 are included in the package provided by CAC. Note that, as of RH EL4, Red Hat provides much less support for modifying, configuring and building the actual kernel. Therefore the process of adding the bigphysarea patch is a little more involved than for earlier Red Hat distributions.

Modifications for 64-bit Compatibility and Suse Configuration

The code for the API, applications and Linux device driver includes several changes to successfully compile on 64-bit architectures. The changes include using appropriate data types, type casts and conversion formats for printf and sprintf.

Various changes in the configuration scripts and configurable files are included in this release to work with Suse Linux distributions. In particular, changes are made to work with Suse 9 as installed on SGI Altix computers.

The goal is to provide compatibility and software port for Itanium platforms (specifically the SGI Altix 350) and Intel 'x86 EMT platforms. The current configuration scripts do not properly recognize the 'x86 EMT platform and problems with the Linux Kernel on the Altix 350 prevent complete compatibility at this time. Work will continue to support these platforms in the near future.

Component Versions for This Release

The Channelization API software release includes several components of software and hardware FPGA configurations. The "HW Support" versions 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 "HW 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.8.0 are:

Software Components	Version
API Library and Programs	0.8.0
Solaris Device Driver	0.8.0
Linux Device Driver	0.8.0
Hardware Components	FPGA Version		Support Version
LightParser Spartan FPGA Configuration	0.7.1		0.7.1
LightParser Virtex FPGA Configurations
Standard SDH/PDH variation	0.7.0		0.7.0
ATM variation	0.7.3		0.7.3
SDH/PDH Transmit variation	n/a		n/a
LightParser2 Virtex FPGA Configurations
Standard SDH variation	0.1.0		0.1.0
LightParser2 Boot FPGA Configuration	0.0.1		0.0.1
DPL3 Main FPGA Configuration	0.7.3		0.7.3
DPL3 Expansion FPGA Configurations
E3 G751 E1 variation	0.7.2		0.7.2
DS3 T1 variation	0.7.2		0.7.2
E3 G832 Bulk variation	0.7.0		0.7.0
Generic variation	0.7.1		0.7.3

Known Problems

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

  NDFs, announced and unannounced, are not properly handled in TU-12s. 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
      

  Data corruption has been reported when recording raw, descrambled STM-1 signals that include AU3s.

  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 DS3 streams from SDH streams. A work-around is to route the raw DS3 streams from SDH input through the Quad-T3 port, loop the signal back in and frame the DS3s 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 framer status bits (Out of Frame and Loss of Frame) and the payload aligner status bits (Pointer, Alignment, B1 and B2 errors) are not correctly implemented in the FPGA registers.

  Burst writes to SDRAM and the MMC data buffer are not reliable. The support programs and API do not perform burst write to the MMC buffer and the SDRAM is currently only accessed for test purposes.

• DPL3:

  ESF framing is not yet supported for transmitting DS1 streams multiplexed to the output DS3 signal.

  Possible failure of framing logic for embedded E1 or DS1 streams after configuration of Expansion FPGA. See the discussion of this topic for details.