July 1, 2005

Overview

The following changes are introduced in this release:

Items Specific to LightParser:

• The streamstat and multirec demos promoted to support applications.

• Various utilities updated.

• Fixed checking for Virtex FPGA type when opening channels.

• New error code for missing optical module.

• New low-level parser configuration functions.

Items Specific to DPL3:

• Fixed the 66MHz capability status in the FPGA.

• Board fails initialization if VIO voltage is wrong.

General Items:

• Device driver support for Linux 2.6 kernel.

• Other device driver updates.

• Updates for bigphysarea patch for Linux kernel.

• Modified diagnostic programs.

• New and modified demonstration programs.

• Component versions for this release.

• Known problems.

Notes:

This release includes a new FPGA configuration for DPL3 boards. Run the dpl_flashup program to update the FPGA configurations.

Version 0.7.4 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.

DPL3: Fixed the 66MHz Capability Status in the FPGA

The Main FPGA configuration for 3.3 volt VIO is modified to set the 66 MHz capability status bit in the PCI configuration space status register. This allows the PCI clock to run at 66 MHz in systems where the PCI subsystem actually uses that setting to control its PCI clock.

Although no change is made to the 5 volt VIO FPGA configuration, there is a new configuration file with the updated version number.

DPL3: Board Fails Initialization if VIO Voltage is Wrong

The dpl_init program is modified to not complete for a board whose FPGA configuration is for the wrong PCI bus VIO voltage. This is done to avoid possible damage to a board if used with the wrong VIO voltage for an extended period of time. The FPGA configuration must be changed for proper VIO voltage using the dpl_flashup program.

LightParser: Streamstat and Multirec Demos Promoted to Support Applications

The dplp_streamstat and dplp_multirec demonstration programs are promoted to support applications. They are now located in the bin directory of the software distribution and installed (by "make install") in the $CAC/bin directory.

dplp_multirec includes several modifications including:

• support for large files sizes (over 2GB)
• raw (unframed) E1
• extraction of time slots from framed E1 streams
• new -c option tells the program perform port and parser configuration which are no longer done by default.

The dplp_streamstat program includes a minor change to re-order the parser configurations for DS1 paths.

LightParser: Various Utilities Updated

Several LightParser utility programs have new features or bug fixes.

The dplp_streams program now supports unframed mode for E1 transmit. With this mode, data for time-slot 0 from the host is passed through to the transmitted stream. The program is also modified to correct the display of stream types in the detailed tributary dump.

The dplp_portcfg program is fixed so that it does not modify the stream bank offset in the PDH merge logic.

The dplp_groom program is fixed to use the same global absolute size limit as the grooming functions in the API. The map size specified by the user is now passed to the library functions instead of the global limit.

The dplp_clock program now supports byte rate settings for bulk C-3 and C-4 streams types.

The dplp_info and dplp_find programs now display the virtext configuration type of the currently loaded Virtex FPGA as well as the configuration type stored in the Flash or specified in EEROM.

LightParser: Fixed Checking for Virtex FPGA Type When Opening Channels

The test for having a valid Virtex FPGA configuration for the requested channel type is fixed to read the type information from the loaded Virtex register rather than the type for the configuration in Flash or specified in the EEROM. This affects calls to cac_chanopen_stream, cac_chanopen_mask, cac_chanopen_list and cac_atm_client_channel.

The loaded Virtex configuration type is obtained using a new API function called cac_get_virtex_loaded_type.

LightParser: New Error Code for Missing Optical Module

A new error code, CAC_ERR_NO_SFP, is defined to report that the optical port SFP is requested but not installed or not detected.

The global errno variable is set to the value of CAC_ERR_NO_SFP by the functions cac_if_reset, cac_if_set_rx_mode, cac_if_set_tx_mode, cac_if_set_refclk when the optical port is specified but not found. The cac_if_check_for_sfp also sets this value if the SFP is not found.

The string returned or printed by the cac_strerror, cac_strerrno and cac_perror for this error code is "sfp optical module not present".

LightParser: New Low-Level Parser Configuration Functions

Two new functions, cac_parse_lovc_one_c12 and cac_parse_lovc_all_c12 are added to configure C-12 streams from the SDH parser.

Another new function, cac_parse_end_script is added to turn off the "script generating mode" which is turned on using the cac_parse_gen_script function.

Device Driver Support for Linux 2.6 Kernel

The Linux device driver for DPL3 and LightParser now supports the latest 2.6 series of the Linux kernel, and therefore, Red Hat Enterprise Linux version 4. Red Hat EL4 (and kernel version 2.6.9) is currently the only distribution for which the 2.6 build and installation has been tested but it should work for any generic 2.6 kernel installation as long as changes to future kernel releases do not require device driver changes.

Support for the 2.6 kernel required minor changes to the actual device driver code. More substantial changes were necessary for the configuration script and Makefile to support the new module building process. The Makefile and boot scripts configured for 2.4 and 2.6 kernels are not compatible. If you are maintaining installations for both 2.4 and 2.6 kernels, be sure to maintain separate software build directories.

The bigphysarea memory allocation patch is not required for the 2.6 kernel. Improvements in memory management in the 2.6 kernel allow the DMA memory allocation to provide sufficient memory for the ChanAPI device driver. However, the bigphysarea allocation facility may still be useful as way to reserve memory for channel buffers and will be used by the driver if it is installed. Updates for the bigphysarea patch and its installation instructions are available if desired (see below).

Other Device Driver Updates

The Linux device driver includes the following changes:
• New options to the software configuration script enable compiling the Linux device driver for a kernel version target different than the version currently running. The use of the new options and limitations are described in the software installation instructions.
• Bug fixes for rolling back resource allocation in the event the driver module or board initialization fails.
• Initial changes are made to support Linux running on the Intel IA64 platform used by SGI Altix servers. This project does not yet have a scheduled completion date.

The Solaris device driver includes the following changes:

• Fixed the CAC_PCI_LOCATION ioctl to properly parse the string value for PCI device information provided by the kernel.

Both the Linux and Solaris device drivers include the following changes:

• The code for channel read operations using the cac_chan_read function is fixed to return the amount of data that was available prior to a timeout or loss of sync error.
• Modified the CAC_PCI_LOCATION ioctl to use the location for bridge device of boards that use a bridge device as their interface to the system PCI bus.
• Added code to save and restore PCI configuration space information of the PCI bridge for future boards that use a bridge device as their interface to the system PCI bus.

Updates for Bigphysarea Patch for Linux Kernel

Two changes for the bigphysarea kernel patch are 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.

Modified Diagnostic Programs

The dpl_recv, dpl_send, dplp_recv and dplp_send programs are modified to support large file sizes. The changes include setting the FILE_OFFSET_BITS macro to allow files larger than 2 GB on Linux and using uint64_t variables to specify and track file sizes larger than 4 GB on Linux and Solaris. The command line argument to dpl_recv and dplp_recv for file size now allows "g" modifier to specify giga-bytes.

The dpl_dumpcfg and dplp_dumpcfg programs have new command line options, -b and -s, to display raw configuration space registers as bytes or shorts. They also have a new -p option to dump the information for the parent device for boards that use a PCI bridge device as their interface to the system PCI bus.

The dpl_dmatest and dplp_dmatest programs include display of the transfer times and rates. There is a new -r option to specify the number of times a DMA buffer should be repeated before asserting the DMA-complete interrupt. This is used to reduce the significance of the interrupt and signal overhead when computing transfer rates. However it is not yet supported by the DPL3 and LightParser boards.

New and Modified Demonstration Programs

New programs, dpl3_e1play and dplp_e1play, demonstrate how to use transmit channels and write applications for sending data from the host on DPL3 and LightParser boards.

The dpl3_e1rec program is modified to demonstrate multi-threaded programming by allowing more than one receive channel to used at the same time. The previous, single threaded version of this program is renamed dpl3_e1single.

The single-threaded dplp_e1rec program is renamed dplp_e1single and the multi-threaded dplp_e1multi program is renamed dplp_e1rec.

The following programs are modified to handle large file sizes: dpl3_e1rec, dpl3_e3rec, dpl3_multirec, dplp_e1rec, dplp_e3rec and dplp_stm1raw. The changes include setting the FILE_OFFSET_BITS macro to allow files larger than 2 GB on Linux and using uint64_t variables to specify and track file sizes larger than 4 GB on Linux and Solaris. The command line argument for file size now allows "g" modifier to specify giga-bytes and a floating point value.

As described above, the dplp_streamstat and dplp_multirec programs are now located in the bin directory and are installed as support applications.

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

Component:	Version:
API Library and Programs	0.7.4
Solaris Device Driver	0.7.3
Linux Device Driver	0.7.3
LightParser Spartan FPGA Configuration	0.7.1
LightParser Virtex FPGA Configurations
Standard SDH/PDH variation	0.7.0
ATM variation	0.7.3
Experimental SDH/PDH variation w/ E1 XMT rate adjust	R.9
DPL3 Main FPGA Configuration	0.7.3
DPL3 Expansion FPGA Configurations
E3 G751 E1 variation	0.7.2
DS3 T1 variation	0.7.2
E3 G832 Bulk variation	0.7.0
Generic variation	0.7.1

Known Problems

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

  NDFs, announced and unannounced, are not properly handled in TU-12s.

  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.

• 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 in previous notes for details.