PICDRIVER

From ICE Enterprises
Jump to navigation Jump to search

Peripheral Interconnect Component driver routines

<function>	Function to perform (RESET,ACQUIRE,PLAY, ...)
<device name>   PIC alias in HW file (i.e. PIC, PIC1, PIC2, MOD1A, TUN2B ...)
<addr/file/key>	Address for READ,WRITE, File for ACQUIRE,PLAY,LOAD*, KeyName for SET,GET
<value/result>	Value for WRITE,SET,MAP,OVSR,... result name for READ,GET,TDEC,TFREQ,...
<tuner port>	Tuner port mask
<tuner dec>	Tuner Decimation 
<tuner freq>	Tuner center freq in Hz (or normalized by 1/Nyquist if TFREQ|TUNER func)
<tuner gain>	Tuner gain in dB (-100 to 100)
<tuner form>	Tuner output Format (SB,CB,SI,CI,SL,CL)

This primitive is a high-level interface to the ICE-PIC card.  It can be
used to perform data acquisition/playback into/from a Midas file, load user
programs into the SHARC, or for test and debug purposes.

The valid functions are:
	SNIFF	- query state of PCI interface
	RESET	- reset the card (optional IOC code override)
	ACQUIRE	- acquire data into a file
	PLAY	- play back data from a file
	START	- starts a SPIN mode test transfer
	STOP	- stops a SPIN or LOOPBACK mode transfer
	HALT	- shutdown card and release any hung locks
	LOOP	- loops active alternate input module to this output module
	LOOPIO	- loops input module-1 to output module-2 (feedthrough)
	SET	- set a keyed variable (see HELP on SETKEY)
	GET	- get a keyed variable (see HELP on GETKEY)
	JOIN	- join a multicast group specified in <addr> (ex 224.1.2.3)
	LEAVE	- leave a multicast group specified in <addr> (ex 224.1.2.3)
	SEND	- send a file of data to a processing module (value=byteOffset)
	RECV	- receive a file of data from a processing module (value=byteOffset)
	LOADIOC	- load special (non-default) Altera code into the I/O Controller

Configuration functions for tuners:
	OVSR	- set the tuner input OVerSampling Ratio (valid until next RESET)
	LOADFC  - load filter coefficients from a Midas file into the tuner
		  Use /PORT=CORE<n> to load a file into the special filter cores

Configuration functions for application specific processing include:
	LOADPM  - load Xilinx code into a Processor Module
	LOADPPC - load application specific code into Virtex PowerPC
	LOADSHARC - load application specific code into SHARC
	LOADSTRATIX - reprogram Stratix part on a 5+ series card I/O Module from <file>
	LOADVIRTEX - reprogram Virtex part on a 5+ series card from <file>

Maintanance functions not to be called by applications include:
	TEST	- suite of operational readiness tests
	DMAC	- display DMA Channel Parameters <addr..> = DMA Channel 
	DUMP    - dump a buffer of data in ice card memory to a Midas file 
	SPEC	- spec the PCI bus for max speed and latencies
	NVREAD	- read the PCI NVRAM configuration registers
	READ	- read a register from PCI or SHARC/PPC
	WRITE	- write a register to PCI or SHARC/PPC (this can crash a machine!)
	MAP	- attempts to map physical PCI space (to test user quotas)
	TCGEN	- generates SDN timecode in a ramdisk file
	LOADFLASH - reprogram PCI EPROM on a 5+ series card from <file>
	UNLOADFLASH - verify PCI EPROM on a 5+ series card to <file>

Deprecated functions not to be called by applications include:
	TUNER	- setup the on-board tuner chips (use SET) 
	TIMER	- sets the IOC internal clock dividers (use SET)
	TDEC	- get closest tuner decimation to <tuner dec> (use GET NDEC)
	TFREQ	- get closest normalized tuner frequency to <tuner freq> (use GET NFREQ)

The RESET function should be performed by an application when it gains access to
the card to make sure its is properly configured.  Other applications may have
downloaded non-standard software configurations.  When <function>=RESET, the 
<address/file> argument, if specified, overrides the default IOC code module.  
The standard IOC configurations are:

	II - two input modules with separate clocks
	IIX - two input modules with the same muxed clock (see MUXCLK flag)
	IIR - two input modules with muxed clock and internally generated ramp
	IO - input on module1, output on module2
	OO - two output modules (outputs always use muxed clock)
	T1 - module2 out internally looped back to module1/tuner1 in 
	T2 - module1 out internally looped back to module2/tuner2 in

See PIC HELP IOC for other configurations.
Acquisition/Playback can occur through the following device ports:

  MODULE[1-2] - the I/O Modules
  TUNER[1-32] - the tuner chips
  TBANK[1-3]  - the tuner banks
  CORE[1-2]   - the FPGA processing cores

See PIC HELP IOPORT for other configurations.
The port is usually specified in the hardware config <device> alias, 
for example:

  PIC1==ICEPIC,PCI-MEM,0xFDFFFC00,,,IOM=A2D,
  MOD1A==ALIAS=PIC1,PORT=MODULE1,
  MOD1B==ALIAS=PIC1,PORT=MODULE2,
  MOD1AB==ALIAS=PIC1,PORT=MODULE3,
  TUN1A==ALIAS=PIC1,PORT=TUNER1,
  TUN1B==ALIAS=PIC1,PORT=TUNER2,

The port can also be specified as a switch (/PORT=port) if no port is 
specified in the <device>s hardware config string.  Each port is assigned 
to a DMA channel, some of which are shared.  A DMA channel can NOT support 
more than one port at a time.  The user must insure this condition is met.  
See HELP CARDS PIC ICE for more details.

The <input file> describes the input data format, sample rate, and
circular buffer size AFTER tuning and/or decimation, because the TUNE and
DECIMATE steps are performed on the ICE-PIC.

The TUNE and DECIMATE functions are not supported in the data playback modes.

The /REPLAY=n switch is used to control circular buffer processing as:

 /REPLAY=-N  File mode  - plays buffer N times and quits (default = -1)
 /REPLAY=1   Oneshot    - plays buffer once and quits
 /REPLAY=2   Continuous - plays buffer continuously
 /REPLAY=3   Stop Top   - stops at top of buffer
 /REPLAY=4   Load       - loads card buffer once - wait for START command
 /REPLAY=5   Spin       - loads one card buffer then regurgitates to output 

Example 1: 8-bit oneshot acquisition through the B-side module

  X-Midas> PIC CREATE RAMFILE SB 8M 10e6
  X-Midas> PICD ACQUIRE MOD1B RAMFILE

Example 2: 16-bit oneshot acquisition through the A-side tuner (decimation=256)

  X-Midas> PIC CREATE RAMFILE SI 8M/256 10e6/256
  X-Midas> PICD ACQUIRE TUN1A RAMFILE ,,, 256 2.5e6 

Example 3: 16-bit continuous playback through the A-side module using an
	   internally generated 10Mhz clock

  X-Midas> RAMP RAMFILE SI 64K ,,,, 1e-7
  X-Midas> PICD/REPLAY=2/FLAGS=INTCLK PLAY MOD1A RAMFILE

The "flags" switch along with a string in the hwconfig file are used to modify
the default behavior of the device for special purposes.  The flags in the 
/FLAGS=(flg1,flg2,...) or /FLAGS=flg1|flg2|... switch are logically ORed 
with the flags in the HW config file.  See HELP FLAGS for a complete list.

The GET (or query) function allows macros to get configuration information from
the card/port into results parameters.  See the help on KEYS for a list of the 
supported key names.  

The syntax is PICD GET <alias> <name> <result label>

For the special keys NFREQ, NDEC, and NRATIO, the result label should be preset 
to the desired value, and the function writes back into the result the nearest 
available value.

Switches:

  /FLAGS=flgs   Add specific flags to config string (see PIC HELP FLAGS)
  /PORT=port	Specifies the port to use if not part of the device alias
  /DMAC=n	DMA Channel number (1-8) [-1]
  /REPLAY=N	Acq/play replay mode, see above
  /TC=mode	Enable time code processing (SDN#F?, SMS#F?), see HELP PIC_TC
  /TCOFF=ysec	The beginning of year in J1950 seconds (default=current)
  /BITS=1|4|8|16 Overrides number of bits per word in file
  /ALL		Include SHARC side info in SNIFF function
  /STAT=label	Return status of command in the named results label
  /SRATE=freq	Overrides the samplerate in the file
  /ARATE=label	Returns actual sample rate based on wall clock time
  /TRIGGER=resname Poll for non-zero result value after setting up transfer
		  (for loosely synchronizing multiple transfers using /BG)
  /WAIT=sec	Pause sec seconds after setting up before starting transfer
  /BLOCK=n	Pseudo SHARC side buffer size (in words) for SPEC function
  /START=n	Start address for DUMP function (in bytes)
  /SIZE=n	Size for DUMP function (in words)
  /MASK=n	Mask of which bits to actually change in a WRITE function
  /NCFIR	LOADFC filter into the NCFIR, the default is PFIR
  /DIR=1|-1	Direction of port transfer for STOP/START if needed (PIC5 bidir port)

Widgets: 
	1) SPEC BlockSize for SPEC function