OCM/OC192 Library

---

Detailed Description

The functions in lib_ocm.c are meant to simplify the sometimes confusing task of setting up and resetting DMA channels on the OCM and OC192 mezzanine boards (and future boards which also do framed SONET input).

The goal is to be able to say "I want data at this rate on this channel" without worrying about the details; if that isn't possible there will be an error return.

There are two board-specific sets of functions (edt_ocm_xxx, edt_oc192_xxx) and a general set of edt_ocx_xxx. If a particular task is identical for both mezzanine cards, there will only be the edt_ocx_xxx version. Otherwise, the edt_ocx_xxx function will either call other edt_ocx_xxx functions or will call the board-specific version.

The initialization functions are separated into the following sequence of stages. It is possible to return to functions in the sequence for full or partial reinitialization a channel. At each stage in the sequence there will be different diagnostic functions available.

The definition of the target channel state is carried in the EdtOCConfig structure passed as a pointer to most of the library functions. This includes the target line rate, framing parameters, and any non-default bitfiles desired. The baseboard and channel are associated with the EdtDev * pointer passed to all of the functions.

Stage 1: edt_ocx_base_init()

First, to start with the base board in an unknown state, call edt_ocx_base_init. This will make sure that at least a default baseboard and mezzanine bitfile(s) are loaded so the mezzanine board can be identified, and the PLLs between baseboard and mezzanine are in synch (checking both SYS_LOCK and LOCAL_SYS_LOCK).

This function will abort any dma on the other channel on the OCM card.

At this point the mezzanine card can be identified, and the SFP or XFP modules can be queried for their status.

Normally this function need only be called once after poweron, unless a different baseboard interface bitfile is requested.

Stage 2: edt_ocx_channel_set_rate()

The rate setting step makes sure that the correct mezzanine bitfile is loaded for the target line rate, and the correct clock source is selected. If an improper rate for the channel is requested, there will be a non-zero error return.

Stage 3: edt_ocx_channel_setup()

This sets the framing parameters, descrambling, enables memory, etc.

Stage 4: edt_ocx_channel_lock_frontend()

This starts the framer and resets the frontend PLLs. The channel fifo is flushed. Failure to see the SIG_DET bit or if the LOL bit is set will cause a non-zero error return.

At this point framing errors can be checked by calling edt_ocx_get_framing_errors().

Stage 5: edt_ocx_channel_start()

This assumes that ring-buffers have been configured. It starts the ring-buffer acquisition, then turns on the channel enable bit to start DMA. If framing is enabled, it will wait for frame and return an error if framing times out.

Steps 1 through 4 can be executed at once using the function edt_ocx_configure(), which will run each step and return an error code if any step fails for some reason.

Modules
	OCM Mezzanine Access Functions
	Setup and diagnostic functions specific to OCM mezzanine channels.
	OC192 Mezzanine Access Functions
	Setup and diagnostic functions specific to OC192 mezzanine channels.
	OC192 LIU Access Functions
	OC192 Mezzanine LIU Serial Access Functions The oc192_mdio functions are for reading and writing the LIU chip through its serial protocol.
Data Structures
struct	EdtOCConfig
	Structure used to pass configuration parameters to the edt_ocx_xxx routines. More...
struct	EdtOCConfig
	Structure used to pass configuration parameters to the edt_ocx_xxx routines. More...
struct	EdtOCXFrameErrors
	Structure used by function edt_ocx_get_framing_errors() for returning various framing errors from the framer registers. More...
struct	EdtOCXFrameErrors
	Structure used by function edt_ocx_get_framing_errors() for returning various framing errors from the framer registers. More...
Defines
#define	EDT_OCX_BYTE_SWAP   0x1
	Flags for edt_ocx_configure.
#define	EDT_OCX_DESCRAMBLE   0x10
	Turn on descrambler.
#define	EDT_OCX_ENABLE_MEM   0x20
	Turn on mezzanine memory.
#define	EDT_OCX_FORCE_LOAD   0x20000
#define	EDT_OCX_FRAMED   0x8
	Turn on framing.
#define	EDT_OCX_FULL_INIT   0x800
	Initialize baseboard as well as mezzanine.
#define	EDT_OCX_INVERT   0x4000
	Invert data when checking.
#define	EDT_OCX_LOOPBACK   0x2000
	Enable loop back through LIU.
#define	EDT_OCX_LSB_FIRST   0x4
#define	EDT_OCX_NO_SIG_DET   0x40000
#define	EDT_OCX_ORDER_MASK   0x7
	mask for lower three order bits
#define	EDT_OCX_OVHD_ONLY   0x40
	Filter out overhead only.
#define	EDT_OCX_PRBS_EN   0x200
	Turn on PRBS pattern generator in LIU.
#define	EDT_OCX_REMOTE_LPBK   0x10000
	Enable remote loopback from LIU.
#define	EDT_OCX_RESYNCH   0x10000
#define	EDT_OCX_SCRAMBLE   0x1000
	Scramble data going out.
#define	EDT_OCX_SET_DEMUX   0x8000
	set the demux array
#define	EDT_OCX_SHORT_SWAP   0x2
#define	EDT_OCX_SKIP_LOAD   0x400
	Disable loading correct bitfile - fail instead.
#define	EDT_OCX_SWAP   (EDT_OCX_BYTE_SWAP | EDT_OCX_SHORT_SWAP)
	Both swaps give network order on x86 architecture.
#define	EDT_OCX_TAGGED_DATA   0x80000
	turn on OC192 data tagging
Enumerations
enum	EdtLineRate
	line rate constants
Functions
int	edt_ocx_base_init (EdtDev *edt_p, EdtOCConfig *cfg)
	Parameters: edt_p  pointer to device structure
int	edt_ocx_channel_set_rate (EdtDev *edt_p, EdtOCConfig *cfg)
	Parameters: edt_p  pointer to device structure
int	edt_ocx_channel_setup (EdtDev *edt_p, EdtOCConfig *cfg)
	Parameters: edt_p  pointer to device structure
int	edt_ocx_channel_signal_detect (EdtDev *edt_p)
	checks SIG_DET bit
int	edt_ocx_channel_start (EdtDev *edt_p)
	Parameters: edt_p  pointer to device structure
int	edt_ocx_check_interface (EdtDev *edt_p, char *target_file, int force_load)
	Parameters: edt_p  pointer to device structure
int	edt_ocx_check_mezz_bitfile (EdtDev *edt_p, EdtOCConfig *cfg)
	Parameters: edt_p  pointer to device structure
int	edt_ocx_configure (EdtDev *edt_p, EdtOCConfig *cfg)
	Parameters: edt_p  pointer to device structure
char *	edt_ocx_default_bitfile (int mezz_id)
	Parameters: mezz.id  Either MEZZ_OCM or MEZZ_OC192 (filled in by edt_get_board_description)
int	edt_ocx_demux_chan_enable (EdtDev *edt_p, int channel, u_char state)
	Parameters: edt_p  pointer to device structure
int	edt_ocx_demux_get (EdtDev *edt_p, EdtLineRate line_rate, u_char *onoff)
	Parameters: edt_p  pointer to device structure
int	edt_ocx_demux_get_chan_enabled (EdtDev *edt_p, int channel)
	Parameters: edt_p  pointer to device structure
int	edt_ocx_demux_set (EdtDev *edt_p, EdtLineRate line_rate, u_char *onoff)
	Parameters: edt_p  pointer to device structure
void	edt_ocx_enable_framing_errors (EdtDev *edt_p, int state)
	Parameters: edt_p  pointer to device structure
int	edt_ocx_get_framing_errors (EdtDev *edt_p, EdtOCXFrameErrors *err_p)
	Parameters: edt_p  pointer to device structure
int	edt_ocx_has_mezz_bitfile (EdtDev *edt_p, char *bitfile_name)
	Parameters: edt_p  pointer to device structure
int	edt_ocx_load_default_mezzanine (EdtDev *edt_p, EdtLineRate line_rate, char *mezz_0, char *mezz_1)
	Parameters: edt_p  pointer to device structure
int	edt_ocx_lock_channel_clock (EdtDev *edt_p, int channel, int timeout)
	Parameters: edt_p  pointer to device structure
int	edt_ocx_lock_clocks (EdtDev *edt_p, int timeout)
	Parameters: edt_p  pointer to device structure
int	edt_ocx_lock_local_clock (EdtDev *edt_p, int timeout)
	Parameters: edt_p  pointer to device structure
char *	edt_ocx_mezz_filename (EdtDev *edt_p, EdtLineRate line_rate)
	Parameters: edt_p  pointer to device structure
void	edt_ocx_reset_sys_en (EdtDev *edt_p, int channel)
	Parameters: edt_p  pointer to device structure
void	edt_ocx_set_channel_direction (EdtDev *edt_p, int channel, int do_write)
void	edt_ocx_set_channel_enable (EdtDev *edt_p, int channel, int state)
	Parameters: edt_p  pointer to device structure
int	edt_ocx_set_clock_select (EdtDev *edt_p, EdtLineRate line_rate)
	Parameters: edt_p  pointer to device structure
void	edt_ocx_set_lsbfirst (EdtDev *edt_p, int channel, int state)
	Parameters: edt_p  pointer to device structure
int	edt_ocx_speed_capable (EdtDev *edt_p, EdtLineRate line_rate)
	Parameters: edt_p  pointer to device structure
int	edt_ocx_wait_for_frame (EdtDev *edt_p, int timeout)
	Parameters: edt_p  pointer to device structure
int	edt_reg_set_bitmask (EdtDev *edt_p, u_int reg, u_int mask, int state)

---

Function Documentation

int edt_ocx_base_init	(	EdtDev *	edt_p,
		EdtOCConfig *	cfg
	)

Parameters:

edt_p

pointer to device structure

Parameters:

cfg

uses flags and intfc Flags referred to : EDT_OCX_SKIP_LOAD won't load bitfile even if incorrect EDT_OCX_SWAP turns on BYTE_SWAP/SHORT_SWAP

Returns:

0 on success, -1 on failure

Loads the correct interface bitfile and default mezzanine bitfiles. Clears channel enables and locks the SYS_LOCK and LOCAL_SYS_LOCK plls.

Definition at line 2287 of file lib_ocm.c.

int edt_ocx_channel_set_rate	(	EdtDev *	edt_p,
		EdtOCConfig *	cfg
	)

Parameters:

edt_p

pointer to device structure

Parameters:

cfg

Configuration parameters

Returns:

0 on success 1 on failure

Sets the channel to the speed defined by cfg->line_rate

Definition at line 2723 of file lib_ocm.c.

int edt_ocx_channel_setup	(	EdtDev *	edt_p,
		EdtOCConfig *	cfg
	)

Parameters:

edt_p

pointer to device structure

Parameters:

cfg

Configuration parameters

Returns:

0 on success, -1 on failure

Definition at line 2840 of file lib_ocm.c.

int edt_ocx_channel_signal_detect

(

EdtDev *

edt_p

)

checks SIG_DET bit

Parameters:

edt_p

pointer to device structure

Returns:

1 if SIG_DET bit is set, 0 otherwise

Simple function which returns the state of the SIG_DET bit.

Note - as of 2/28/07, this bit isn't available on OC192 channel 0 yet, so it always returns 1;

Definition at line 2660 of file lib_ocm.c.

int edt_ocx_channel_start

(

EdtDev *

edt_p

)

Parameters:

edt_p

pointer to device structure

Returns:

0 on success, -1 on framing timeout

Starts the dma by calling edt_start_buffers, then turning on the channel enable bit.

Definition at line 2991 of file lib_ocm.c.

int edt_ocx_check_interface	(	EdtDev *	edt_p,
		char *	target_file,
		int	force_load
	)

Parameters:

edt_p

pointer to device structure

Parameters:

	target_file	file name of bitfile desired
	force_load	Allow loading the correct bitfile in place of current one.

Returns:

0 if correct bitfile loaded, -1 otherwise.

Check the UI interface bitfile, load with target_file if necessary.

Definition at line 2139 of file lib_ocm.c.

int edt_ocx_check_mezz_bitfile	(	EdtDev *	edt_p,
		EdtOCConfig *	cfg
	)

Parameters:

edt_p

pointer to device structure

Parameters:

cfg

Configuration parameters

Returns:

0 on success, -1 on failure

Makes sure the correct mezzanine bitfile is loaded.

Definition at line 2496 of file lib_ocm.c.

int edt_ocx_configure	(	EdtDev *	edt_p,
		EdtOCConfig *	cfg
	)

Parameters:

edt_p

pointer to device structure

Parameters:

cfg

EdtOCConfig configuration parameters

Returns:

0 on success, -1 on failure

Calls initialization routines necessary up to edt_ocx_channel_lock_frontend(). Passes the cfg structure to these functions in sequence:

1. edt_ocx_base_init() is called if cfg->flags has the EDT_OCX_FULL_INIT bit set. Otherwise, edt_get_board_description() is called to make sure we've characterized the board.
2. edt_ocx_channel_set_rate()
3. edt_ocx_channel_setup()
4. edt_ocx_channel_lock_frontend()

On completion and a return value of 0, the board is ready to start DMA on this channel.

Definition at line 2886 of file lib_ocm.c.

char* edt_ocx_default_bitfile

(

int

mezz_id

)

Parameters:

mezz.id

Either MEZZ_OCM or MEZZ_OC192 (filled in by edt_get_board_description)

Returns:

standard base board interface file name

Definition at line 2097 of file lib_ocm.c.

int edt_ocx_demux_chan_enable	(	EdtDev *	edt_p,
		int	channel,
		u_char	enable
	)

Parameters:

edt_p

pointer to device structure

Parameters:

	channel	which channel to enable/disable
	enable	A value of 0 or 1 to indicate whether to enable this column in the input. 0 means off, 1 means enabled (this is the inverse of the actual bit state).

Sets a bit in the demux registers to enable/disable a particular column in the input.

Definition at line 3530 of file lib_ocm.c.

int edt_ocx_demux_get	(	EdtDev *	edt_p,
		EdtLineRate	line_rate,
		u_char *	onoff
	)

Parameters:

edt_p

pointer to device structure

Parameters:

	line_rate	Line Rate constant - This parameter determines the length of the onoff array. (Currently must OC48_RATE or STM16_RATE for the OCM board.)
	onoff	An array of 0 or 1 to indicate whether column is active. (In the register the bits are actually the inverse of this.) The length of the array should be the equivalent OC number - 3 for OC3, 12 for OC12, etc.

Returns:

0 on success, -1 on parameter error

Gets the bits in the demux registers that enable/disable a particular column in the input.

Definition at line 3501 of file lib_ocm.c.

int edt_ocx_demux_get_chan_enabled	(	EdtDev *	edt_p,
		int	channel
	)

Parameters:

edt_p

pointer to device structure

Parameters:

channel

which channel to return the enabled status

Returns:

0 if not enabled, 1 if enabled

Gets the bit in the demux registers that indicate whether a particular column in the input is enabled.

Definition at line 3559 of file lib_ocm.c.

int edt_ocx_demux_set	(	EdtDev *	edt_p,
		EdtLineRate	line_rate,
		u_char *	onoff
	)

Parameters:

edt_p

pointer to device structure

Parameters:

	line_rate	Line Rate constant -this is used to determine the length of the array.
	onoff	An array of bytes set to 0 or 1 to indicate whether column is active. (In the register the bits are actually the inverse of this.) The length of the array should correspond to the OC line rate - 12 for OC12, 48 for OC48, etc. (STM rates should be multiplied by 3).

Returns:

0 on success, -1 on framing timeout

Sets the bits in the demux registers to enable/disable a particular column in the input.

Definition at line 3466 of file lib_ocm.c.

void edt_ocx_enable_framing_errors	(	EdtDev *	edt_p,
		int	state
	)

Parameters:

edt_p

pointer to device structure

Parameters:

state

Sets the error count enable bit to state (on/off).

Definition at line 191 of file lib_ocm.c.

int edt_ocx_get_framing_errors	(	EdtDev *	edt_p,
		EdtOCXFrameErrors *	err_p
	)

Parameters:

edt_p

pointer to device structure

Parameters:

err_p

Returns:

0 on success

Fills in the error structure in err_p. Call this rather than checking individual registers because it will latch the values correctly using the OCM_ERROR_COUNT_HOLD bit.

Definition at line 221 of file lib_ocm.c.

int edt_ocx_has_mezz_bitfile	(	EdtDev *	edt_p,
		char *	bitfile_name
	)

Parameters:

edt_p

pointer to device structure

Parameters:

bitfile_name

Returns:

0 on success, -1 on failure

Checks the loaded bitfile against bitfile_name, returns true or false.

Definition at line 2424 of file lib_ocm.c.

int edt_ocx_load_default_mezzanine	(	EdtDev *	edt_p,
		EdtLineRate	line_rate,
		char *	mezz_0,
		char *	mezz_1
	)

Parameters:

edt_p

pointer to device structure

Parameters:

	line_rate	rate constant for the channel. If 0 use default
	mezz_0	Optional alternate mezzanine bitfile name
	mezz_1	Optional alternate mezzanine bitfile name

Returns:

0 on success

Loads defaults in ch 0, (and ch 1 for OCM), unless overriden by parameters. Equivalent to the command line "ocmload" for OCM and "otuload" for OC192

Returns:

0 on success, -1 if load fails or not correct board type

Definition at line 2245 of file lib_ocm.c.

int edt_ocx_lock_channel_clock	(	EdtDev *	edt_p,
		int	channel,
		int	timeout
	)

Parameters:

edt_p

pointer to device structure

Parameters:

	channel	Which DMA channel
	timeout	in ms

Returns:

0 on success,

This waits until the SYS_LOCK bit is set for channel. If timeout is non-zero it returns -1 if the bit isn't set within timeout ms.

Definition at line 304 of file lib_ocm.c.

int edt_ocx_lock_clocks	(	EdtDev *	edt_p,
		int	timeout
	)

Parameters:

edt_p

pointer to device structure

Parameters:

timeout

timeout in ms

Returns:

0 on success, -1 on timeout

Calls appropriate function to lock pll clocks between main board and mezzanine

Definition at line 2204 of file lib_ocm.c.

int edt_ocx_lock_local_clock	(	EdtDev *	edt_p,
		int	timeout
	)

Parameters:

edt_p

pointer to device structure

Parameters:

timeout

Returns:

0 on success, -1 on failure

This waits until the LOCAL_SYS_LOCK bit is set. If timeout is non-zero it returns -1 if the bit isn't set within timeout ms.

Definition at line 271 of file lib_ocm.c.

char* edt_ocx_mezz_filename	(	EdtDev *	edt_p,
		EdtLineRate	line_rate
	)

Parameters:

edt_p

pointer to device structure

Parameters:

line_rate

Rate constant

Returns:

correct bitfile name for a line rate and board type

Definition at line 2465 of file lib_ocm.c.

void edt_ocx_reset_sys_en	(	EdtDev *	edt_p,
		int	channel
	)

Parameters:

edt_p

pointer to device structure

Parameters:

channel

DMA channel

Toggles the state of the SYS_EN bit for channel.

Definition at line 2697 of file lib_ocm.c.

void edt_ocx_set_channel_enable	(	EdtDev *	edt_p,
		int	channel,
		int	state
	)

Parameters:

edt_p

pointer to device structure

Parameters:

	channel	DMA channel
	state	Sets the channel enable bit to state channel may not be the one in edt_p->channel_no, so multiple channels can be initialized using a single edt_p

Definition at line 2601 of file lib_ocm.c.

int edt_ocx_set_clock_select	(	EdtDev *	edt_p,
		EdtLineRate	line_rate
	)

Parameters:

edt_p

pointer to device structure

Parameters:

line_rate

Rate constant

Returns:

Calls the correct clock select for the mezzanine board type.

Definition at line 2571 of file lib_ocm.c.

void edt_ocx_set_lsbfirst	(	EdtDev *	edt_p,
		int	channel,
		int	state
	)

Parameters:

edt_p

pointer to device structure

Parameters:

	channel
	state	Sets the lsbfirst bit to state. channel may not be the one in edt_p->channel_no, so multiple channels can be initialized using a single edt_p

Definition at line 2635 of file lib_ocm.c.

int edt_ocx_speed_capable	(	EdtDev *	edt_p,
		EdtLineRate	line_rate
	)

Parameters:

edt_p

pointer to device structure

Parameters:

line_rate

Rate constant

Returns:

0 if capable of designated rate, -1 if not

Returns whether this channel is capable of this line rate. Selects based on edt_p->mezz.id.

Definition at line 2385 of file lib_ocm.c.

int edt_ocx_wait_for_frame	(	EdtDev *	edt_p,
		int	timeout
	)

Parameters:

edt_p

pointer to device structure

Parameters:

timeout

Returns:

0 on success, -1 on timeout

Calls the correct wait_for_frame function for OCM or OC192, returning once the channel is framed correctly.

Definition at line 2964 of file lib_ocm.c.

---