$Id$


		  Libcombo: User interface to Combo6 hardware
		  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Data types
~~~~~~~~~~

	The library defines several data types to hide implementation
	details from the user.

cs_target_t

	Enumeration type used to denote various address spaces ('targets')
	on the card. Currently, the following are recongnized:

		CS_SPACE_FPGA
		CS_SPACE_PLX
		CS_SPACE_CPLD

cs_size_t
cs_addr_t

	Unsigned integer data types suitable to represent bus address
	and size. At least 32bits wide.

cs_device_t

	Opaque structure representing one Combo6 device. Only pointers
	to this type may be used. Allocated by cs_attach(), freed by
	cs_detach().

cs_space_t

	Opaque structure representing a mapping of address space region
	(for possible regions see cs_target_t above). Only pointers to
	this type may be used. See cs_space_map(), cs_space_unmap().


Macros, constants
~~~~~~~~~~~~~~~~~

CS_PATH_DEV(n)

	Determine path to n-th Combo6 device file at compile time (this
	differs between NetBSD and Linux).

CS_MAP_ALL

	Special value for cs_space_map() to make whole address space
	of given type accessible.

Initialization functions
~~~~~~~~~~~~~~~~~~~~~~~~

int
cs_attach(cs_device_t **dev, char *path)

	Initialize device abstraction structure, opening device file
	given by 'path' for exclusive access. Returs zero on success,
	nonzero upon failure.

void
cs_detach(cs_device_t **dev)

	Close the device and invalidate any resources allocated.

void
cs_children_attach(cs_device_t *dev)

	Force the driver to scan for known design (such as io_buf_v2)
	that has a driver itself. Currently, the driver never scans
	for 'subdevices' on its own to preserve clean testing environment.
	This call always succeeds.

void
cs_children_detach(cs_device_t *dev)

	Force the driver to detach all 'subdevice' drivers. This call always
	succeeds (even if no subdevices are present).

Device address space access
~~~~~~~~~~~~~~~~~~~~~~~~~~~

	Upon agreement with the hardware team, only 32bit and properly
	aligned access is currently supported.

int
cs_space_map(cs_device_t *dev, cs_space_t **space, cs_target_t type, \
    cs_size_t size, cs_addr_t offs, int flag)

	Map portion of device address space denoted by 'type' (see above)
	beginning at offset 'offs' covering 'size' bytes. If the size
	argument equals CS_MAP_ALL, whole address space beginning at given
	offset is mapped. Returns zero on success. The 'flags' argument
	may be a bitwise or of:

	CS_MAP_INDIRECT
		The region will be accessed using ioctl() syscall. By default,
		regions are accessed using direct memory mapping, if possible,
		which is significantly faster.

	If 'flags' is zero, default options are used.

void
cs_space_unmap(cs_device_t *dev, cs_space_t **space)

	Invalidate the space abstraction object and release any associated
	resources. Always succeeds provided valid arguments.

void
cs_space_write_4(cs_device_t *dev, cs_space_t *space, cs_addr_t offs, \
    u_int32_t value)

	Write 'value' at offset 'offs' relative to beginning of 'space'
	region with a single 32bit bus cycle. Offset must be aligned at
	32bits. Provided valid arguments, this function always succeeds.

u_int32_t
cs_space_read_4(cs_device_t *dev, cs_space_t *space, cs_addr_t offs)

	Read a single 32bit value from offset 'offs' relative to 'space'
	address space region. Provided valid arguments, this function
	always succeeds.

void
cs_space_write_multi_4(cs_device_t *dev, cs_space_t *space, cs_addr_t offs, \
    cs_size_t count, u_int32_t *buf)

	Write 'count' 32bit values from 'buf' to address space region
	'space' beginning at offset 'offs'. Provided valid arguments
	this function always succeeds.

void
cs_space_read_multi_4(cs_device_t *dev, cs_space_t *space, cs_addr_t offs, \
    cs_size_t count, u_int32_t *buf)

	Read 'count' 32bit values from address space region 'space'
	beginning at offset 'offs' and store them to 'buf'. Provided valid
	arguments this function always succeeds.

Utility functions
~~~~~~~~~~~~~~~~~

const char *
cs_space_name(cs_target_t type)

	Return textual description of address space 'type'. Returned pointer
	is allocated statically and must not be freed.


		      Content-Addressable-Memory interface
		      ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

	The library provides convenience infrastructure for CAM (which
	is essential part of Combo6 card design) loading and reading.
	From user point of view, CAM is considered an array of logical
	cells (each of them being a fixed width bitfield).

Macros, constants, data types
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

CAM_CELL_BITS

	Bits per CAM logical cell.

CAM_CELL_BYTES

	Bytes per CAM logical cell.

CAM_PCELL_BITS

	Bits per physical CAM cell.

CAM_SIZE_BITS

	Total CAM size in bits.

CAM_CELL_COUNT

	Total number of logical cells in CAM.

CAM_PCELLS_PER_LCELL

	Number of physical cells occupied by one logical cell.

cs_cam_cell_t

	Structure describing contents of one CAM logical cell. Has the
	following public member:

		u_int8_t byte[CAM_CELL_BYTES];

	where byte[0] is LSB.

cs_cam_match_t

	Structure describing registers in unified header to be matched
	against CAM. Has one public member:

		u_int16_t list[CAM_LIST_LEN];

	The constant CAM_LIST_LEN is also defined in combosix.h

Access functions
~~~~~~~~~~~~~~~~

int
cs_cam_load(cs_device_t *dev, cs_component_t *cam,
	    cs_cam_cell_t *cells, cs_cam_cell_t *masks,
	    uint32_t offs, uint32_t count)

	Load 'count' CAM cells beginning at 'offs' with data from 'cells'
	and mask from 'masks'. Note that 'cells' and 'masks' are arrays
	of (at least) count members. Cell offs+x is loaded with data from
	'cells[offs+x]' and mask 'masks[offs+x]'.
	The argument 'cells' XOR 'masks' may be null (in that case, "only
	what is provided is done"). Returns zero on success.

int
cs_cam_dump(cs_device_t *dev, cs_component_t *cam,
	    cs_cam_cell_t *cells, cs_cam_cell_t *masks,
	    uint32_t offs, uint32_t num)

	Read 'count' CAM cells beginning at 'offs', store cell data to
	'cells[i]' (if 'cells' is not null) and mask to 'masks[i]' (if
	'masks' is not null). User must provide storage for read data.
	Returns zero on success.

Utility functions
~~~~~~~~~~~~~~~~~

void
cs_print_cell(cs_cam_cell_t *cell)

	Print cell contents to standard output in hexadecimal format
	(LSB going leftmost).

int
cs_scan_cell(cs_cam_cell_t *cell, char *str)

	Fill cell from a string representation. The format is the same
	as output from cs_print_cell().

	BUG: the string must be exactly CAM_CELL_BYTES*2 bytes long
