LCBC.c File Reference

Implementation of the LCB command list and command item utility routines. More...

#include <LCBD/LCBC.h>
#include <LCBD/LCB_cr.h>
#include <stdio.h>

Functions

unsigned int LCBC_process (const LCB_ci *ci, const LCB_ci *end, LCBC_processor rtn, void *prm)

Executes the user specified handler for each command item in the range ci to end.

static unsigned int show (void *prm, const LCB_ci *ci)

Shows (prints) a single command item.

void LCBC_show (unsigned int options, const LCB_ci *beg, const LCB_ci *end)

Dumps the result items to stdout.

static LCB_ci * fill_simple (LCB_ci_simple *simple, unsigned short int stall, unsigned int header)

Constructs a simple LCB command. A simple LCB command consists of only a header word, containing the command length and an opcode, plus a stall word.

static LCB_ci * fill_reg (LCB_ci_reg *reg, unsigned int field_select, unsigned int value, unsigned short int stall, unsigned int header)

Constructs a LCB register access command.

static LCB_ci * fill_cmd (LCB_ci_cmd *cmd, const LCB_ci_cmd_payload *payload, unsigned short int stall_timeout, unsigned int header)

Constructs transmit command, with or without a response.

LCB_ci * LCBC_cmd_xmit_fill (LCB_ci_cmd *ci, const LCB_ci_cmd_payload *payload, unsigned short int stall)

Constructs transmit command, without a response.

LCB_ci * LCBC_cmdr_xmit_fill (LCB_ci_cmdr *ci, const LCB_ci_cmd_payload *payload, unsigned short int timeout)

Constructs transmit command, with a response.

LCB_ci * LCBC_mark_time_fill (LCB_ci_mark_time *ci, unsigned short int stall)

Constructs a mark time LCB command.

LCB_ci * LCBC_lat_reset_fill (LCB_ci_lat_reset *ci, unsigned short int stall)

Constructs a LAT reset LCB command.

LCB_ci * LCBC_csr_access_fill (LCB_ci_csr *ci, unsigned int value, unsigned int field_select, unsigned short int stall)

Constructs a LCB CSR register access command.

LCB_ci * LCBC_faults_access_fill (LCB_ci_faults *ci, unsigned int value, unsigned int field_select, unsigned short int stall)

Constructs a LCB FIFO FAULTS register access command.

LCB_ci * LCBC_rxstats_access_fill (LCB_ci_rxstats *ci, unsigned int value, unsigned int field_select, unsigned short int stall)

Constructs a LCB RECEIVE STATISTICS/STATUS register access command.

unsigned int LCBC_cmd_xmit (LCBD lcb, const LCB_ci_cmd_payload *payload, unsigned short int stall)

Utility routine to compose and submit a command with no response command (department of redundancy department?).

unsigned int LCBC_mark_time (LCBD lcb, unsigned short int stall)

Utility routine to compose and execute an LCB mark time command.

unsigned int LCBC_lat_reset (LCBD lcb, unsigned short int stall)

Utility routine to compose and execute an LCB LAT reset command.

unsigned int LCBC_cmdr_xmit (LCBD lcb, const LCB_ci_cmd_payload *ci_payload, unsigned short int timeout, LCB_ri_cmd_payload *ri_payload)

Utility routine to compose and submit a command with response command (department of redundancy department?).

unsigned int LCBC_csr_access (LCBD lcb, unsigned int value, unsigned int field_select, unsigned short int stall, unsigned int *old_val, unsigned int *cur_val)

Utility routine to compose and execute an access command to LCB's CSR register.

unsigned int LCBC_faults_access (LCBD lcb, unsigned int value, unsigned int field_select, unsigned short int stall, unsigned int *old_val, unsigned int *cur_val)

Utility routine to compose and execute an access command to LCB's FIFO FAULTS register.

unsigned int LCBC_rxstats_access (LCBD lcb, unsigned int value, unsigned int field_select, unsigned short int stall, unsigned int *old_val, unsigned int *cur_val)

Utility routine to compose and execute an access command to LCB's RECEIVE STATISTICS/STATS register.

Detailed Description

Implementation of the LCB command list and command item utility routines.

Author:

JJRussell -- russell@slac.stanford.edu

  CVS $Id

Function Documentation

static LCB_ci * fill_cmd	(	LCB_ci_cmd *	cmd,
		const LCB_ci_cmd_payload *	payload,
		unsigned short int	stall_timeout,
		unsigned int	header
	)			`[static]`

Constructs transmit command, with or without a response.

Returns:: Pointer to the next command item to be filled

Parameters:

	cmd	The command item to be filled.
	payload	The transmit command's payload. This consists of a LATp header plus a highly encoded bit pattern which determines further routing and the action to be taken at the destination
	stall_timeout	The stall or timeout period, in units of 20MHz clock ticks
	header	The header plus op code

References _LCB_ci_cmd::header, _LCB_ci_cmd::payload, and _LCB_ci_cmd::stall.

Referenced by LCBC_cmd_xmit_fill(), and LCBC_cmdr_xmit_fill().

static LCB_ci * fill_reg	(	LCB_ci_reg *	reg,
		unsigned int	field_select,
		unsigned int	value,
		unsigned short int	stall,
		unsigned int	header
	)			`[static]`

Constructs a LCB register access command.

Returns:: Pointer to the next command item to be filled

Parameters:

	reg	The command item to be filled
	field_select	A word indicating the bits from value that will be written. For example, if 0, then no bits will be written, if -1, then all bits will be written.
	value	The value to be written
	stall	The stall time, in units of 20MHz clock ticks
	header	The header word, opcode + command length

LCB Register Access Commands

A LCB register access command consists of the header word, containing the command length and the opcode, plus two command specific parameters, the value to write to the register and a word indicating which bits of the value to write, plus a stall parameter. There are three such registers on the LCB

CSR
FIFO FAULTS
RECEIVE STATISTICS/STATUS

References _LCB_ci_reg::field_select, _LCB_ci_reg::header, _LCB_ci_reg::stall, and _LCB_ci_reg::value.

Referenced by LCBC_csr_access_fill(), LCBC_faults_access_fill(), and LCBC_rxstats_access_fill().

static LCB_ci * fill_simple	(	LCB_ci_simple *	simple,
		unsigned short int	stall,
		unsigned int	header
	)			`[static]`

Constructs a simple LCB command. A simple LCB command consists of only a header word, containing the command length and an opcode, plus a stall word.

Returns:: Pointer to the next command item to be filled

Parameters:

	simple	The command item to be filled.
	stall	The stall time, in units of 20MHz clock ticks
	header	The header plus op code

Simple commands

The set of LCB simple commands consist of

Mark Time
LAT Reset

References _LCB_ci_simple::header, and _LCB_ci_simple::stall.

Referenced by LCBC_lat_reset_fill(), and LCBC_mark_time_fill().

unsigned int LCBC_cmd_xmit	(	LCBD	lcb,
		const LCB_ci_cmd_payload *	payload,
		unsigned short int	stall
	)

Utility routine to compose and submit a command with no response command (department of redundancy department?).

Returns:: Status

Parameters:

	lcb	The LCB driver handle
	payload	The payload of the command access command. The format of this beast is dependent on the target (PDU, TEM, GTFE) and is non-trivial. However, this routine does not concern itself with the formatting, deferring that as someone else's problem.
	stall	The stall time, in units of 20Mhz clock ticks

References _LCB_ci_cmd::header, _LCB_rl::item, _LCB_cl_cmd::item, LCB_CI_HDR_CMD, LCBD_OK, LCBD_qioW(), LCBD_rst_rcv_err_map(), _LCB_ci_cmd::payload, _LCBD_rl::rl, and _LCB_ci_cmd::stall.

LCB_ci * LCBC_cmd_xmit_fill	(	LCB_ci_cmd *	ci,
		const LCB_ci_cmd_payload *	payload,
		unsigned short int	stall
	)

Constructs transmit command, without a response.

Returns:: Pointer to the next command item to be filled

Parameters:

	ci	The command item to be filled.
	payload	The transmit command's payload. This consists of a LATp header plus a highly encoded bit pattern which determines further routing and the action to be taken at the destination
	stall	The stall time, in units of 20MHz clock ticks

References fill_cmd(), and LCB_CI_HDR_CMD.

unsigned int LCBC_cmdr_xmit	(	LCBD	lcb,
		const LCB_ci_cmd_payload *	ci_payload,
		unsigned short int	timeout,
		LCB_ri_cmd_payload *	ri_payload
	)

Utility routine to compose and submit a command with response command (department of redundancy department?).

Returns:: Status

Parameters:

	lcb	The LCB driver handle
	ci_payload	The payload of the command access command. The format of this beast is dependent on the target (PDU, TEM, GTFE) and is non-trivial. However, this routine does not concern itself with the formatting, deferring that as someone else's problem.
	timeout	The LCB timeout period, in units of 20MHz clock ticks to wait for a response to be returned.
	ri_payload	The resulting (returned) payload. As is in the case of the command item payload, ci_payload, the format of this payload is highly dependent on the target. However, this routine merely returns the payload results to the user, again adopting the philosopy of not my problem,

References _LCB_ci_cmdr::header, _LCB_rl::item, _LCB_cl_cmdr::item, LCB_CI_HDR_CMDR, LCBD_qioW(), LCBD_rst_rcv_err_map(), _LCB_ci_cmdr::payload, _LCBD_rl::rl, and _LCB_ci_cmdr::timeout.

LCB_ci * LCBC_cmdr_xmit_fill	(	LCB_ci_cmdr *	ci,
		const LCB_ci_cmd_payload *	payload,
		unsigned short int	timeout
	)

Constructs transmit command, with a response.

Returns:: Pointer to the next command item to be filled

Parameters:

	ci	The command item to be filled.
	payload	The transmit command's payload. This consists of a LATp header plus a highly encoded bit pattern which determines further routing and the action to be taken at the destination
	timeout	The timeout period, in units of 20MHz clock ticks

References fill_cmd(), and LCB_CI_HDR_CMDR.

unsigned int LCBC_csr_access	(	LCBD	lcb,
		unsigned int	value,
		unsigned int	field_select,
		unsigned short int	stall,
		unsigned int *	old_val,
		unsigned int *	cur_val
	)

Utility routine to compose and execute an access command to LCB's CSR register.

Returns:: Status

Parameters:

	lcb	The LCB driver handle
	value	The value to write. Only bits matching those in the field_select parameter will actually be written.
	field_select	Pattern of those bits in value to write
	stall	The stall time, in units of 20MHz clock ticks, for the LCB to wait for completion.
	old_val	Pointer to receive the value of the register before modification. This may be NULL.
	cur_val	Pointer to receive the value of the register after modification. This may be NULL.

References LCB_CI_HDR_CSR.

Referenced by lcbd_csr_access().

LCB_ci * LCBC_csr_access_fill	(	LCB_ci_csr *	ci,
		unsigned int	field_select,
		unsigned int	value,
		unsigned short int	stall
	)

Constructs a LCB CSR register access command.

Returns:: Pointer to the next command item to be filled

Parameters:

	ci	The command item to be filled
	field_select	A word indicating the bits from value that will be written. For example, if 0, then no bits will be written, if -1, then all bits will be written.
	value	The value to be written
	stall	The stall time, in units of 20MHz clock ticks

References fill_reg(), and LCB_CI_HDR_CSR.

unsigned int LCBC_faults_access	(	LCBD	lcb,
		unsigned int	value,
		unsigned int	field_select,
		unsigned short int	stall,
		unsigned int *	old_val,
		unsigned int *	cur_val
	)

Utility routine to compose and execute an access command to LCB's FIFO FAULTS register.

Returns:: Status

Parameters:

	lcb	The LCB driver handle
	value	The value to write. Only bits matching those in the field_select parameter will actually be written.
	field_select	Pattern of those bits in value to write
	stall	The stall time, in units of 20MHz clock ticks, for the LCB to wait for completion.
	old_val	Pointer to receive the value of the register before modification. This may be NULL.
	cur_val	Pointer to receive the value of the register after modification. This may be NULL.

References LCB_CI_HDR_FAULTS.

Referenced by lcbd_faults_access().

LCB_ci * LCBC_faults_access_fill	(	LCB_ci_faults *	ci,
		unsigned int	field_select,
		unsigned int	value,
		unsigned short int	stall
	)

Constructs a LCB FIFO FAULTS register access command.

Returns:: Pointer to the next command item to be filled

Parameters:

	ci	The command item to be filled
	field_select	A word indicating the bits from value that will be written. For example, if 0, then no bits will be written, if -1, then all bits will be written.
	value	The value to be written
	stall	The stall time in units of 20MHz clock ticks

References fill_reg(), and LCB_CI_HDR_FAULTS.

unsigned int LCBC_lat_reset	(	LCBD	lcb,
		unsigned short int	stall
	)

Utility routine to compose and execute an LCB LAT reset command.

Returns:: Status

Parameters:

	lcb	The LCB driver handle
	stall	The stall time, in units of 20Mhz clock ticks

: To be used only with great discretion; i.e. in case of emergency break glass.

References LCB_CI_HDR_LAT_RESET.

LCBC_ci LCBC_lat_reset_fill	(	LCB_ci_lat_reset *	ci,
		unsigned short int	stall
	)

Constructs a LAT reset LCB command.

Returns:: Pointer to the next command item to be filled

Parameters:

	ci	The command item to be filled.
	stall	The stall time, in units of 20MHz clock ticks

References fill_simple(), and LCB_CI_HDR_LAT_RESET.

unsigned int LCBC_mark_time	(	LCBD	lcb,
		unsigned short int	stall
	)

Utility routine to compose and execute an LCB mark time command.

Returns:: Status

Parameters:

	lcb	The LCB driver handle
	stall	The stall time, in units of 20Mhz clock ticks

: The utility of a bare mark time command, outside the context of command list, is dubious, but is provided for completeness. With a minimal stall time, one could use effectively as a NOP.

References LCB_CI_HDR_MARK_TIME.

LCB_ci * LCBC_mark_time_fill	(	LCB_ci_mark_time *	ci,
		unsigned short int	stall
	)

Constructs a mark time LCB command.

Returns:: Pointer to the next command item to be filled

Parameters:

	ci	The command item to be filled.
	stall	The stall time, in units of 20MHz clock ticks

References fill_simple(), and LCB_CI_HDR_MARK_TIME.

unsigned int LCBC_process	(	const LCB_ci *	ci,
		const LCB_ci *	end,
		LCBC_processor	rtn,
		void *	prm
	)

Executes the user specified handler for each command item in the range ci to end.

Returns:: The status of the last processing call

Parameters:

	ci	The first command item to process
	end	One past the last command item to process
	rtn	User provided callback routine to process one item
	prm	User provided parameter passed to rtn

References LCBC__next().

Referenced by LCBC_show().

unsigned int LCBC_rxstats_access	(	LCBD	lcb,
		unsigned int	value,
		unsigned int	field_select,
		unsigned short int	stall,
		unsigned int *	old_val,
		unsigned int *	cur_val
	)

Utility routine to compose and execute an access command to LCB's RECEIVE STATISTICS/STATS register.

Returns:: Status

Parameters:

	lcb	The LCB driver handle
	value	The value to write. Only bits matching those in the field_select parameter will actually be written.
	field_select	Pattern of those bits in value to write
	stall	The stall time, in units of 20MHz clock ticks, for the LCB to wait for completion.
	old_val	Pointer to receive the value of the register before modification. This may be NULL.
	cur_val	Pointer to receive the value of the register after modification. This may be NULL.

References LCB_CI_HDR_RXSTATS.

LCB_ci * LCBC_rxstats_access_fill	(	LCB_ci_rxstats *	ci,
		unsigned int	field_select,
		unsigned int	value,
		unsigned short int	stall
	)

Constructs a LCB RECEIVE STATISTICS/STATUS register access command.

Returns:: Pointer to the next command item to be filled

Parameters:

	ci	The command item to be filled
	field_select	A word indicating the bits from value that will be written. For example, if 0, then no bits will be written, if -1, then all bits will be written.
	value	The value to be written
	stall	The stall time, in units of 20MHz clock ticks

References fill_reg(), and LCB_CI_HDR_RXSTATS.

void LCBC_show	(	unsigned int	options,
		const LCB_ci *	beg,
		const LCB_ci *	end
	)

Dumps the result items to stdout.

Parameters:

	options	Show options
	beg	Pointer to the first result descriptor to show
	end	Pointer to one past the lst result descriptor to show

Returns:: void

References LCBC_process(), and show().

static unsigned int show	(	void *	prm,
		const LCB_ci *	ci
	)			`[static]`

Shows (prints) a single command item.

Parameters:

	prm	Arbitrary user parameter, unused
	ci	Pointer to command item

Returns:: 0 Useful when passed to LCBC_process () to print all result items.

References _LATP_cell_hdr::bf, _LATP_cell_hdr_bf::dst, _LCB_ci::hdr, LCBC_TYPE_BY_OPCODE, LCBC_TYPE_COMMAND, LCBC_TYPE_EVENT, LCBC_TYPE_REGISTER, LCBC_TYPE_SIMPLE, _LCB_ci_hdr_bf::opcode, _LATP_cell_hdr_bf::proto, _LATP_cell_hdr_bf::rsp, and _LATP_cell_hdr::us.

Referenced by LCBC_show(), and LCBR_show().


Functions
unsigned int	LCBC_process (const LCB_ci ci, const LCB_ci end, LCBC_processor rtn, void *prm)
	Executes the user specified handler for each command item in the range ci to end.
static unsigned int	show (void prm, const LCB_ci ci)
	Shows (prints) a single command item.
void	LCBC_show (unsigned int options, const LCB_ci beg, const LCB_ci end)
	Dumps the result items to stdout.
static LCB_ci *	fill_simple (LCB_ci_simple *simple, unsigned short int stall, unsigned int header)
	Constructs a simple LCB command. A simple LCB command consists of only a header word, containing the command length and an opcode, plus a stall word.
static LCB_ci *	fill_reg (LCB_ci_reg *reg, unsigned int field_select, unsigned int value, unsigned short int stall, unsigned int header)
	Constructs a LCB register access command.
static LCB_ci *	fill_cmd (LCB_ci_cmd cmd, const LCB_ci_cmd_payload payload, unsigned short int stall_timeout, unsigned int header)
	Constructs transmit command, with or without a response.
LCB_ci *	LCBC_cmd_xmit_fill (LCB_ci_cmd ci, const LCB_ci_cmd_payload payload, unsigned short int stall)
	Constructs transmit command, without a response.
LCB_ci *	LCBC_cmdr_xmit_fill (LCB_ci_cmdr ci, const LCB_ci_cmd_payload payload, unsigned short int timeout)
	Constructs transmit command, with a response.
LCB_ci *	LCBC_mark_time_fill (LCB_ci_mark_time *ci, unsigned short int stall)
	Constructs a mark time LCB command.
LCB_ci *	LCBC_lat_reset_fill (LCB_ci_lat_reset *ci, unsigned short int stall)
	Constructs a LAT reset LCB command.
LCB_ci *	LCBC_csr_access_fill (LCB_ci_csr *ci, unsigned int value, unsigned int field_select, unsigned short int stall)
	Constructs a LCB CSR register access command.
LCB_ci *	LCBC_faults_access_fill (LCB_ci_faults *ci, unsigned int value, unsigned int field_select, unsigned short int stall)
	Constructs a LCB FIFO FAULTS register access command.
LCB_ci *	LCBC_rxstats_access_fill (LCB_ci_rxstats *ci, unsigned int value, unsigned int field_select, unsigned short int stall)
	Constructs a LCB RECEIVE STATISTICS/STATUS register access command.
unsigned int	LCBC_cmd_xmit (LCBD lcb, const LCB_ci_cmd_payload *payload, unsigned short int stall)
	Utility routine to compose and submit a command with no response command (department of redundancy department?).
unsigned int	LCBC_mark_time (LCBD lcb, unsigned short int stall)
	Utility routine to compose and execute an LCB mark time command.
unsigned int	LCBC_lat_reset (LCBD lcb, unsigned short int stall)
	Utility routine to compose and execute an LCB LAT reset command.
unsigned int	LCBC_cmdr_xmit (LCBD lcb, const LCB_ci_cmd_payload ci_payload, unsigned short int timeout, LCB_ri_cmd_payload ri_payload)
	Utility routine to compose and submit a command with response command (department of redundancy department?).
unsigned int	LCBC_csr_access (LCBD lcb, unsigned int value, unsigned int field_select, unsigned short int stall, unsigned int old_val, unsigned int cur_val)
	Utility routine to compose and execute an access command to LCB's CSR register.
unsigned int	LCBC_faults_access (LCBD lcb, unsigned int value, unsigned int field_select, unsigned short int stall, unsigned int old_val, unsigned int cur_val)
	Utility routine to compose and execute an access command to LCB's FIFO FAULTS register.
unsigned int	LCBC_rxstats_access (LCBD lcb, unsigned int value, unsigned int field_select, unsigned short int stall, unsigned int old_val, unsigned int cur_val)
	Utility routine to compose and execute an access command to LCB's RECEIVE STATISTICS/STATS register.