August 5, 2003

Overview

Version 0.4.0 is a beta release of the Channelization API for DPL3 and LightParser Boards. Not all of the functionality is implemented in this release.

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:

• Reduced memory mapping in the API and device driver.

• New memory access functions in the API library.

• Enhanced support for LightParser configuration scripts.

• New API functions for LightParser input and channelization stream selection.

• Enhanced support for LightParser Quad E3 port.

• Changes in the API library.

• Changes to utility and diagnostic programs.

• Changes to Solaris and Linux device drivers.

• New and modified demonstration programs.

• Changes to FPGA configurations.

• Component versions for this release.

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

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

Reduced Memory Mapping in the API and Device Driver

The amount of I/O memory mapped into both the device drivers and applications has been substantially reduced for both DPL3 and LightParser boards.

The device driver now maps in only the portion of SDRAM required to access channel descriptors and the host page table - 2 MB for each DPL3 board and 3 MB for each LightParser board. It also maps in only the register space required to access the primary board control registers - 4 Kbytes for each DPL3 and LightParser board.

The API has been modified to map in smaller regions of the boards' memory space rather than mapping in two large regions. The following memory regions are defined in the API for DPL3 and LightParser boards. Note that not all of the regions apply to both boards and that the actual size mapped is adjusted to be a multiple of the host system's page size (4K or 8K).

Region	DPL3   Size	LightParser   Size	mapped
SDRAM	2 MB	3 MB	default
All SDRAM	16 MB	64 MB	optional
Control Registers	2 KB	4 KB	default
Virtex Regs/Mem	n/a	8 MB	default
Flash Memory	n/a	8 MB	optional
Framer Registers	12 KB	n/a	default
DMA Buffer	1 KB	1 KB	optional

The regions marked default under the mapped column are those mapped in by default for normal application usage. New options for the cacopen_with_flags function, discussed below, allow applications to map in optional regions.

The organization of data in SDRAM is modified to facilitate reduced SDRAM mapping. This is implemented in changes to the DPL3 Main FPGA and LightParser Spartan FPGA configurations. It is therefore imperative that the FPGA configurations be updated on the boards when using the new API and device driver.

New Memory Access Functions in the API Library

New API functions for accessing DPL3 and LightParser memory are included as part of the new memory mapping scheme and reduced complexity in the API code. Old functions such as pci_peek32 and pci_poke32 are replaced by cac_read32 and cac_write32. The following table lists the old function names and their new replacements. The arguments for the replacement remain the same.

Operation	Old Function(s)	New Function
Read a 32-bit value	pci_peek32 cac_up_i32b	cac_read32
Read array of 32-bit values	pci_peek32a cac_up_a32b	cac_read32a
Write a 32-bit value	pci_poke32 cac_dl_i32b	cac_write32
Write array of 32-bit values	pci_poke32a cac_dl_a32b	cac_write32a
Read-Modify-Write a 32-bit value	cac_rmw_mem32	cac_rmw32
Atomically Read-Modify-Write   a 32-bit value	cac_reg_rmw	cac_rmw32_atomic

The cac_rmw32_atomic function uses a device driver ioctl (as did cac_reg_rmw). It may only be used to access the portion of SDRAM and the primary control registers that are mapped and accessible by the device driver.

The 8-bit and 16-bit read and write operations are not currently required or supported. The following old functions have no replacements:

pci_peek8, pci_peek8a, pci_poke8, pci_poke8a, cac_dl_i8b, cac_dl_a8b, cac_up_i8b, cac_up_a8b, pci_peek16, pci_peek16a, pci_poke16, pci_poke16a, cac_up_i16b, cac_up_a16b, cac_dl_i16b, cac_dl_a16b

Many other memory and register I/O functions, such as the EEROM and Virtex access functions are written in terms of the lower-level functions. Although they were modified to use the new functions, their usage has not changed.

Many of the DPL3 and LightParser support and diagnostic programs are modified to use the new memory access functions and memory mapping options (where required).

Some of the demonstration programs used the old memory access functions to enable or disable channelization simulation modes. Those programs are modified to replace that code with the use of new API library functions that handle the simulation modes. User programs based on the old demonstration programs will require similar modifications if the code for simulation modes was included.

Enhanced Support for LightParser Configuration Scripts

An API function and utility program are added for executing parser scripts. The script files generated by the API now include comments with the versions of the API and Spartan and Virtex FPGA configurations that were installed when the script was created.

The API function for setting the parser configuration functions into script generation mode is renamed from cac_parse_do_script to cac_parser_gen_script and it now requires a CAC_HANDLE argument for the open LightParser board resource which is needed to obtain the version information.

The new function for executing scripts is called cac_parse_exec_script. Its prototype is:

    int cac_parse_exec_script(
       CAC_HANDLE *dev,       /* handle for parser resource to configure */
       FILE       *script,    /* handle for script file open for reading */
       int         checkver ) /* non-zero if version info should be checked */

Applications calling this function must open the board's parser resource and the script file to be read and executed. Handles for the open resource and file are passed to the function along with a boolean value specifying whether or not the version information should be checked. If the checkver argument is non-zero the function will compare the versions listed in the script with those of the current API and FPGA configurations. If the versions do not match (in their major and minor numbers) the function will return with a failure.

The new utility program for executing scripts is named dplp_execscript. It requires the name of the LightParser board to be configured and the name of the script file to be executed. It also has a command line option to reset the parser configuration prior to executing the script and a command line option to check the version information. See the "Channelization API Utility and Diagnostic Programs" manual for details.

New API Functions for LightParser Input and Channelization Stream Selection

The function, cac_parse_parser_source, configures the parser's input selection registers to the specified input port. Its prototype is:

    int cac_parse_parser_source(
       CAC_HANDLE *dev,       /* handle for parser resource to configure */
       int         source )   /* input source specifier */

Macros for the source argument are:

Macro	Input selection
PARSE_SOURCE_OPT	Optical port
PARSE_SOURCE_CMI	Electrical port
PARSE_SOURCE_VRDI	VRDI port
PARSE_SOURCE_QUADE3	Quad E3 port

Data from the optical, electrical or VRDI port, when selected, is fed into the SDH portion of the parser tree. Data from the Quad E3 port, when selected, is def into the PDH portion of the parser tree.

The function, cac_parse_chan_source, configures the parser's extraction registers to extract the specified stream type for host channelization. Its prototype is:

    int cac_parse_chan_source(
       CAC_HANDLE *dev,       /* handle for parser resource to configure */
       int         source )   /* channelization source specifier */

Macros for the source argument are:

Macro	Channelization stream type
CHAN_SOURCE_E1	E1 streams
CHAN_SOURCE_E3	E3 streams
CHAN_SOURCE_E4	E4 stream
CHAN_SOURCE_RAW_OPT	Raw data from the optical port
CHAN_SOURCE_RAW_CMI	Raw data from the electrical port

It is the application's responsibility to ensure that the parser is configured with an algorithm that provides the selected stream type.

Enhanced Support for LightParser Quad E3 Port

The dplp_portcfg program now supports configuration of the Quad E3 port. See the "Channelization API Utility and Diagnostic Programs" manual for details.

New and modified API functions for configuring the Quad E3 port provide more control of the Quad E3 operation. The channel selection and modes for the cac_quade3_init and cac_quade3_loopback have been separated into two arguments. A new cac_quade3_status function has been added to the API.

The cac_quade3_init function initializes and configures the Quad E3 port. Its prototype is:

    int cac_quade3_init(
       CAC_HANDLE *dev,      /* handle for board to configure */
       uint32_t    chans,    /* channel bit mask */
       uint32_t    modes )   /* configuration modes */

Macros for the chans argument are:

Macro	Channel selection
QUADE3_CHAN_0	Channel 0 of the Quad E3
QUADE3_CHAN_1	Channel 1 of the Quad E3
QUADE3_CHAN_2	Channel 2 of the Quad E3
QUADE3_CHAN_3	Channel 3 of the Quad E3
QUADE3_CHAN_ALL	All four channels of Quad E3

The value passed may be any bit-wise OR combination of the single channels or QUADE3_CHAN_ALL may be used to configure all four channels. When all channels are selected the Quad E3 interface chip is reset prior to configuration.

Macros for the modes argument are:

Macro	Mode
QUADE3_RX_MODE	Enable receive
QUADE3_TX_MODE	Enable transmit
QUADE3_DS3_MODE	Configure for DS3 mode
QUADE3_JAT_RX16	Set jitter attenuator for 16-bit FIFO on Rx side
QUADE3_JAT_RX32	Set jitter attenuator for 32-bit FIFO on Rx side
QUADE3_JAT_TX16	Set jitter attenuator for 16-bit FIFO on Tx side
QUADE3_JAT_TX32	Set jitter attenuator for 32-bit FIFO on Tx side
QUADE3_JAT_DFSL	Disable the jitter attenuator's fast locking mode

Any bit-wise OR combination of these options may be specified except that the jitter attenuator may configured for just one FIFO size and only in one of the Rx or Tx directions.

The cac_quade3_loopback function configures the loopback mode for the Quad E3 port. Its prototype is:

    int cac_quade3_loopback(
       CAC_HANDLE *dev,      /* handle for board to configure */
       uint32_t    chans,    /* channel bit mask */
       uint32_t    mode )    /* loopback mode */

Macros and usage for the chans argument are the same as for cac_quade3_init.

Macros for the mode argument are:

Macro	Mode
QUADE3_NO_LOOPBACK	Outgoing data from the parser
QUADE3_REMOTE_LOOPBACK	Received signal looped back internally by the Quad E3 chip
QUADE3_VIRTEX_LOOPBACK	Received signal is sent back out by the Virtex

The cac_quade3_status function reads the alarm status register for the specified channel of the Quad E3 port. Its prototype is:

    int cac_quade3_status(
       CAC_HANDLE *dev,      /* handle for board to configure */
       uint32_t    chan,     /* channel selection */
       uint32_t   *pstat )   /* pointer to application's storage for status */

Macros for the chans argument are the same as for cac_quade3_init except that only a single channel may be specified per call.

The alarm status register for the selected channel is read and the results stored at the local pointed to by pstat.

Changes in the API Library

In addition to new functions and changes already mentioned, the following modifications to the API are included in this release.

The cac_if_set_refclk function is modified to safely switch between clock reference sources. This includes resetting the SDRAM chips which may have become unstable during a clock switch operation.

New functions, cac_chan_sim_set and cac_chan_sim_clr, provide control of channelization simulation modes for utility and diagnostic programs.

The cac_hwdata_path function has an added argument to allow specifying the directory to look for the file in. This change primarily affects other API functions and utility and diagnostic programs.

The cac_versions_get function now retrieves the LightParser Virtex FPGA version stored in EEROM whether or not the board has Flash memory.

New cac_hwdata_highest_exp function and changes to the cac_version_convert_string add support for experimental FPGA configuration version numbers and file names.

Changes to Utility and Diagnostic Programs

The dpl_init and dplp_init programs no longer clear the raw receive and transmit data in SDRAM. This is primarily to avoid having to map in the additional memory space. Should it later be required, this operation will be reimplemented in the programs.

The dplp_init program is fixed to properly configure the Virtex for LightParser boards with no flash memory.

The dpl_flashup and dplp_flashup programs have new options to specify a file to load for each FPGA device (in lieu of searching for the highest version files) and an option to have them search for experimental version files. The -s option has been removed from there programs and they now display the current and file versions of FPGA configurations by default. See the "Channelization API Utility and Diagnostic Programs" manual for details.

The dplp_info program now reports the version of the Virtex FPGA stored in EEROM. It reports it as the "flash" version for boards with flash memory or as "eerom" version for boards without flash memory.

The dpl_chantest and dplp_chantest diagnostic programs have a new option to test with an 11-bit ITU pattern. They also attempt to disable simulation modes before terminating.

The dpl_memtest and dplp_memtest diagnostic programs have an added test mode using pseudo random numbers and will also disable channelization activity that might interfere with the memory being tested. They also have new command line options to only run the self-address, complement-address or random-number test.

The dpl_debug and dplp_debug programs have new "bar" values corresponding to the new memory regions defined in the API. The commands for 8-bit and 16-bit operations have been removed.

Changes to Solaris and Linux Device Drivers

In addition to the reduced memory mapping, described previously, the following modifications to the API are included in this release.

Code for tracking the number of channels open on each board is fixed. Although tracking the number of open channels is not currently used, it may be required for features in future versions.

The Linux device driver is fixed to properly handle flags for resources to be opened exclusively.

New and Modified Demonstration Programs

The channel I/O demonstration programs are modified to make use of the new cac_parse_chan_source function to select the appropriate stream type. Those that provided simulation modes are modified to make use of the new simulation control functions in the API.

A new program, dplp_stm1raw demonstrates how to configure a LightParser to record raw STM1 data from the optical or electrical port.

A new program, dplp_multirec, demonstrations how to configure a LightParser to record E1, E3 or E4 streams from the optical, electrical or quad-E3 port.

See the "Readme.demos" file and the source code in the demo directory of the distribution for more information.

Changes to FPGA Configurations

The Main FPGA configuration for DPL3 boards is modified for the new SDRAM organization, which includes less space for individual channel descriptors.

The Spartan FPGA configuration for LightParser boards is modified for the new SDRAM organization and to fix a timing problem in writing Virtex registers. The latter changed solved the problem in setting the tributary type in the Virtex's lovcrx parser module.

The Virtex FPGA configuration for LightParser boards is modified to support reading raw data streams from the optical and electrical ports and to provide clock valid status registers for the reference clock selection and the ability to reset the 39MHz clock DCM.

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 components and their versions for DPL3 and LightParser Software Release 0.4.0 are:

Component:	Version:
API Library and Programs	0.4.0
Solaris Device Driver	0.4.0
Linux Device Driver	0.4.0
DPL3 Main FPGA Configuration (all variations)	0.4.0
DPL3 Expansion FPGA Configuration	0.4.0
Light Parser Spartan Configuration	0.4.0
Light Parser Virtex Configuration	0.4.1