ICE Help ICELIB

From ICE Enterprises
Jump to navigation Jump to search
↑ Go to the full list of ICE Help pages.

Summary: High level control software for ICE-DSP cards

This library contains routines to communicate with the ICE family of DSP boards. This includes PIC, MBT, and SLIC varieties. All routines return an int status unless otherwise noted (by the last element in the argument list with the same name as the function). Successful status are >= 0. Errors are signaled by a status < 0.

Arguments that are structures or arrays are passed by reference. All others are pass by value, unless otherwise noted.

Fortran wrappers are provided by preceding the routine name with m$ . All arguments to the wrappers are pass by reference.

Contents

PIC_DETECT - Query the current system for ICE cards

int flags 0=normal 1=quiet

Searches the system for ICE cards and returns the number of cards found. A configuration summary is printed to the screen if quiet flag is not set.

PIC_OPEN - Open a connection to an ICE-PIC device

PIC p Handle to Device (this is NOT thread safe)
string config Text string with device configuration information
int *pbreak Pointer to break flag (or NULL to disable)
int flags Optional run-time behavior modifiers

Opens a connection to an ICE device by first parsing a configuration string for information specifying the device type, device interface, device name, IO Module configuration, and default IO port of interest. The PICSTRUCT handle must be allocated by the application. It is initialized by this routine. This structure may NOT be used by more than one thread at a time.

If the pbreak parameter is non-null, it must point to a static integer that is 0 when running normally and non-zero to interrupt the library routines. This is useful in single threaded environments to respond to signals (like control-C) in a graceful manner.

There are two device specification formats: The first, format A, is preferred as it is OS independent. 

"DEVTYPE,DEVNO=X,,IOM=MODTYPE,,,"

where X is from 0 to N-1, N being the number of cards in the system. The library code produces the standard device name on the current platform. For example: /dev/icepicX on Unix, IcepicX on Windows, ICA0-ICZ0 on VMS.

The parameters are order independent, comma separated, with a trailing comma. From ICE290 and on the DEVTYPE can be ICEPIC even for ICEMBTs. The distinction is no longer important in the configuration string.

If both modules are the same, use IOM=xxx to specify the module types. If they are different, use IOM1=xxx and IOM2=xxx. If you install a user crystal CCLK on the motherboard other than the default frequency, you should also specify a CCLK=FreqInHertz parameter for use by the libraries.

Here is a typical example:

For a system with three cards, one ICEPIC with two E2D modules with inverted MSBs, one ICEPIC with an A2D and T2D, and one ICEMBT with A2Ds and a user specified crystal: 

Config for 1st ICEPIC = "ICEPIC,DEVNO=0,IOM=E2D,MSBI,"
Config for 2nd ICEPIC = "ICEPIC,DEVNO=1,IOM1=A2D,IOM2=T2D,"
Config for 3rd ICEMBT = "ICEPIC,DEVNO=2,IOM=A2D,CCLK=62000000,"

To bypass the auto-devicename feature, use format B shown below: 

"DEVTYPE,DEVINTERFACE,DEVNAME,IOM=MODTYPE,,"

The first 3 must be in this order; all others are order independent. For a VMS system with two cards, one with two E2D modules with inverted MSBs, and one with an A2D and T2D: 

Config for 1st ICEPIC = "ICEPIC,PCI-DEV,ICA0:,IOM=E2D,MSBI,"
Config for 2nd ICEPIC = "ICEPIC,PCI-DEV,ICB0:,IOM1=A2D,IOM2=T2D,"

On a Unix system this would look like: 

Config for 1st ICEPIC = "ICEPIC,PCI-DEV,/dev/icepic0,IOM=E2D,MSBI,"
Config for 2nd ICEPIC = "ICEPIC,PCI-DEV,/dev/icepic1,IOM1=A2D,IOM2=T2D,"

On Linux, using the optional memory mapped interface: 

Config for 1st ICEPIC = "ICEPIC,PCI-MEM,0xFEDFFC00,IOM=E2D,MSBI,"
Config for 2nd ICEPIC = "ICEPIC,PCI-MEM,0xFEDFF800,IOM1=A2D,IOM2=T2D,"

On a Windows system this would look like: 

Config for 1st ICEPIC = "ICEPIC,PCI-DEV,Icepic0,IOM=E2D,MSBI,"
Config for 2nd ICEPIC = "ICEPIC,PCI-DEV,Icepic1,IOM1=A2D,IOM2=T2D,"

On a Linux system with one ICEPIC and one ICEMBT: 

Config for 1st card = "ICEPIC,PCI-DEV,/dev/icepic0,IOM=E2D,MSBI,"
Config for 2nd card = "ICEMBT,PCI-DEV,/dev/icepic1,IOM1=A2D,IOM2=T2D,"

The ICE-PIC, ICE-MBT, and ICE-SLimpIC all look the same to the driver. The distinction is made in the hardware configuration file to help ensure correct card identification in systems with a mix of cards. If the card type does not match the hardware revision, pic_open() returns an error.

These strings point to the entire ICEPIC device, which is useful for testing, status, rebooting, etc. A pic_reset issued to this device will reboot and reset the entire card, and acquisitions will by default come from internal Processor memory buffers.

NOTE: Specifying the correct module type is VERY important. The libraries may cause multiple chips to drive the same bus if the module attached to the port is different from that specified in the configuration.

To talk to an I/O PORT on the device, the string should include a PORT=xxx entry. This causes the library routines to default to the specified port without having to modify the code calling the libraries. This is convenient when application code only deals with one PORT per ICEPIC handle.

For example: 

"ICEPIC,DEVNO=0,IOM=E2D,MSBI,PORT=MODULE1,"

refers to the ECL module on port 1. Now issuing a pic_reset will only reset the specified port, not the entire card. Also, an acquisition or playback will by default access MODULE1.

If the port resource resides on a Processor Module, the PM index can be specified with the PMI=n flag or by prefacing the port name. For example: 

"ICEPIC,DEVNO=0,IOM=E2D,PMI=2,PORT=CORE1,"

or 

"ICEPIC,DEVNO=0,IOM=E2D,PORT=PM2CORE1,"

access the 1st core on processor module 2, and: 

"ICEPIC,DEVNO=0,IOM=E2D,PORT=PM0TUNER2,"

accesses the 2nd tuner on the main board, even though TUNER2 would default to the first processor module.

See help on PIC_IOPORT for details on port specification.

A card with SDDS network IO modules will require extra configuration parameters to set the IP and VLAN addresses. For example: 

Config for SDDS ICEPIC = "ICEPIC,DEVNO=0,IOM=SDDSXD,IPVLAN=201,IPADDR1=192.168.1.101,IPADDR2=192.168.1.102,"

The card's standard behavior can be modified by adding a list of flags to the config string. See help on FLAGS for a complete list.

These can also be specified by combining the integer bitmasks in the icelib.inc or icelib.h files and specifying them in the "flags" argument. For example: 

config = "ICEPIC,DEVNO=0,IOM=E2D,";
status = pic_open (p, config, &brkflag, FLG_MSBI|FLG_VERBOSE);

opens the device (from C) with the MSB inverted and verbose turned on so that a debug line will print to the terminal as the libraries access the card.

Note: FLG_xxx is defined in icelib.h or icelib.inc

PIC_CLOSE - Close a connection to an ICE-PIC device

PIC p Handle to Device

Closes a connection to an ICE device. This includes cleaning up after any unclosed DMA channels or files, and releasing any device locks.

PIC_RESET - Reset a device or device IO port

PIC p Handle to Device
int flags Reset flags (FLG_BOOT=Hard, 0=Soft)

Resets the ICE-PIC card or one of its IO ports.

If a PORT=xxx assignment appears in the pic_open() call that opened the device, only that port will be reset. Other ports will not be affected.

If no PORT=xxx appears in the pic_open() call or if the FLG_BOOT flag is present in the flags argument, a full reset of the card is performed. The full reset includes Processor reboot, code download and FPGA configuration.

A full reset should be performed at least once after the host computer is rebooted. It can also be performed in the beginning of an application if ports are not being shared by different applications. In X-Midas, this is performed by the command PICDRIVER RESET <PIC NAME>.

Note: FLG_BOOT is defined in icelib.h or icelib.inc

PIC_TEST - Run a series of diagnostic tests

PIC p Handle to Device
int mode Test number (or 0 for all tests)
int flags Options (bit0=verbose/quiet, bitN=unused)

Performs a number of diagnostic tests:

  1. RESET test
  2. PCI Mailbox/Register test
  3. Processor Memory test
  4. FIFO test
  5. Serial port test
  6. IOC register test
  7. Processor DMA test
  8. PCI DMA test

The function returns the number of errors encountered.

PIC_SNIFF - Display contents of the device PCI/Processor registers

PIC p Handle to Device
int mode 0=Normal, -1=All

Prints the contents of the PCI Interface registers and optionally some of the Processor registers useful for analyzing the current state.

PIC_READ - Read from a PCI or Processor address

PIC p Handle to Device
int offset Register Offset
int *data Data word (by reference)

Read a register on the PCI Interface or Processor. The Offsets to various registers are defined in ice21062.h for the SHARC and ice5933.h for the PCI interface. This routine also returns *data as the function status.

PIC_WRITE - Write to a PCI or Processor address

PIC p Handle to Device
int offset Register Offset
int *data Data word (by reference)

Write a register on the PCI Interface or Processor. The Offsets to various registers are defined in ice21062.h for the SHARC and ice5933.h for the PCI interface. This routine returns *data as the function status.

PIC_WRITEM - Write to a PCI or Processor address with a mask

PIC p Handle to Device
int offset Register Offset
int *data Data word (by reference)

Write a register on the PCI Interface or Processor with a mask to enable specific bits. The current register is first read into a scratch word. The bits enabled by mask are transferred from *data into the scratch word, and the scratch word is written back to the register. The Offsets to various registers are defined in ice21062.h for the SHARC and ice5933.h for the PCI interface. This routine returns the final register word as the function status.

PIC_RFIFO - Read a block of data from the PCI FIFO

PIC p Handle to Device
int data[] Array of words to receive FIFO data
int bytes Number of bytes to read
int flags 0=Normal, FLG_NOWAIT only reads what is currently available

Reads a block of data from the PCI Interface FIFO register. This is used to transfer non-DMA blocks of data from the Processor.

PIC_WFIFO - Write a block of data to the PCI FIFO

PIC p Handle to Device
int data[] Array of data words to write into FIFO
int bytes Number of bytes to write
int flags 0=Normal, FLG_NOWAIT only writes while space is available

Writes a block of data to the PCI Interface FIFO register. This is used to transfer non-DMA blocks of data into the Processor.

PIC_RPM - Reads internal address space of a port/processor module

PIC p Handle to Device
int node Port/Processor module node ID (-1=useDefault)
int addr Address in module
int *data Pointer to data
int bytes Number of bytes to read
int flags FLG_PPC_MEM)

Reads data from a processor module's PPC address space. See PIC_MSG for node IDs.

The base address for each of the cores on the mainboard or processor module are defined in iceppc.h as: 

PPC_CORE1_CTL or PPC_CORA_CTL
PPC_CORE2_CTL or PPC_CORB_CTL
PPC_CORE3_CTL or PPC_TUNA_CTL
PPC_CORE4_CTL or PPC_TUNB_CTL

PIC_WPM - Writes internal address space of a port/processor module

PIC p Handle to Device
int node Port/Processor module node ID (-1=useDefault)
int addr Address in module
int *data Pointer to data
int bytes Number of bytes to write
int flags FLG_PPC_MEM)

Writes data to a processor module's PPC address space. See PIC_MSG for node IDs.

The base address for each of the cores on the mainboard or processor module are defined in iceppc.h as: 

PPC_CORE1_CTL or PPC_CORA_CTL
PPC_CORE2_CTL or PPC_CORB_CTL
PPC_CORE3_CTL or PPC_TUNA_CTL
PPC_CORE4_CTL or PPC_TUNB_CTL

PIC_SEND - Send a packet to a port/processor module

PIC p Handle to Device
int node Port/Processor Module node ID (-1=useDefault)
int *head Pointer to packet header for RMIF packets
int *data Pointer to packet data
int bytes Number of bytes to write
int flags 0=Normal, PKT_RMIF for RMIF packets, PKT_ACMD for command packets

Sends a packet to a processor module input socket. If flags indicate there is a packet header involved (i.e. PKT_RMIF), the packet header is read from *head. The <bytes> parameter does not include the header length. Both the RMIF and ACMD headers are 8 bytes.

The ACMD header consists of two int_4 words. The first is the command type, PKTF_BUS_WR, or PKTF_MEM_WR, etc. The second is the address. The data is in *data, and the number of bytes of data to send is <bytes>. For PKTF_BUS_RD and PKTF_MEM_RD, the size to read is ORed in with the command type. It must be less than 64K.

The supported packet ACMD functions are: 

PKTF_BUS_RD  
PKTF_BUS_WR
PKTF_MEM_RD
PKTF_MEM_WR
PKTF_MEM_TEST  for internal bootup 
PKTF_INIT      not used yet
PKTF_MODIFY    data[] is the argument to modifyAlgorithm(), usually an array of integers
PKTF_RUN       head[1] is 1-toStart or 0-toStop
PKTF_RESET     not used yet

All packet transfers are rounded up to 8-byte boundaries. Make sure the data buffer supports a read through the last 8-byte aligned field. This is to avoid extra memory copies in support of high-speed transfers.

See PIC_MSG for node IDs.

Returns the number of bytes sent.

PIC_RECV - Receives a packet from a port/processor module

PIC p Handle to Device
int node Port/Processor Module node ID (-1=useDefault)
int *head Pointer to packet header for RMIF packets
int *data Pointer to packet data
int bytes Number of bytes to write
int flags 0=Normal, PKT_RMIF for RMIF packets, PKT_ACMD for command packets

Receives a packet from a processor module output socket. If flags indicate there is a packet header involved (i.e. PKT_RMIF), the packet header is read into *head. The <bytes> parameter is the maximum length of the transfer into the *data buffer.

For ACMD commands, this follows a PKTF_BUS_RD, or PKTF_MEM_RD. The header values should be the values from the send() command. The data will be returned in *data.

All packet transfers are rounded up to 8-byte boundaries. Make sure the data buffer supports a read through the last 8-byte aligned field. This is to avoid extra memory copies in support of high-speed transfers.

See PIC_MSG for node IDs.

Returns the number of bytes read or -1 if nothing is available.

PIC_SENDRECV - Send a packet to a port/processor module and receive response with timeout

PIC p Handle to Device
int node Port/Processor Module node ID (-1=useDefault)
int *head Pointer to packet header for RMIF packets
int *data Pointer to packet data
int bytes Number of bytes to write
int maxbytes Number of bytes maximum to read
int flags 0=Normal, PKT_RMIF for RMIF packets, PKT_ACMD for command packets
int timeout Number of seconds to wait for response

This routine calls PIC_SEND followed by PIC_RECV with a desired timeout. See PIC_MSG for node IDs.

PIC_MSG - Send a PKT_ACMD to a Port/Processor Module with optional response and timeout

PIC p Handle to Device
int node Port/Processor Module node ID (-1=useDefault)
int func Function to call (PKTF_BUS_WR,PKTF_MEM_RD,etc.)
int address Address for function
int *data Pointer to packet data (for write and read)
int sbytes Number of bytes to write
int rbytes Number of bytes to read
int timeout Number of seconds to wait for response

This routine forms an PKT_ACMD and calls PIC_SENDRECV with a desired timeout.

The Node IDs are: 

0 - Base card
1 - I/O Module 1
2 - I/O Module 2
7 - Processor Module 1
8 - Processor Module 2

The Function IDs are: 

PKTF_BUS_RD
PKTF_BUS_WR
PKTF_MEM_RD
PKTF_MEM_WR
PKTF_MEM_TEST
PKTF_INIT
PKTF_MODIFY
PKTF_RUN
PKTF_STOP

This routine is typically called by internal libraries to configure and start modules.

PIC_IOPORT - Set up an I/O Port for DMA transfer

PIC p Handle to Device
int ptype Type of IO Port to use (-1=useDefault from pic_open)
int pindex Index of port to use (-1=useDefault from pic_open)
int dmac DMA Channel (0=noDMA, -1=useDefault)
int dir Transfer direction (1=output/playback, -1=input/acquisition)
int bits Number of bits per data sample (1,8,16,32) (negate for complex)
int rate Internal clock rate in Hertz
double fcyn Tuner frequency/nyquist
int dec Tuner decimation
int gain Tuner gain in dB
int flags Run-time modifiers

Sets up an IO port for data acquisition/playback.

This routine branches on the ptype parameter to call the appropriate port setup routine. It allows generic data acquisition/playback routines to be written without regard to the actual type of port being used.

If the port and module types are specified in the parameter list to pic_open() the ptype and pindex parameters can be defaulted by entering -1.

The port types are defined in icelib.inc or icelib.h. The port index refers to the channel number of the port. The following are available: 

IOPT_NONE	- no port defined (access entire board)
IOPT_MODULE	- IO Module Site (1-2 or 3)
IOPT_TUNER	- On-board Tuner (1-32)
IOPT_TBANK	- On-board Bank of Tuners (1-2 or 3)
IOPT_CORE     - FPGA Single Channel Core algorithm (1-2, 11-12, 21-22)
IOPT_MCORE    - FPGA Multi Channel Core algorithm (1-32, 33-64)
IOPT_INTERNAL	- Internal Application algorithm (1-8)

Resources that reside on processor modules (TUNERS,CORES,MCORES) may be addressed by module and local index, or the global card index. If the index is not in the range of a global, it will be placed on the default processor module. If no processor modules exist, it will default to the main board. 

Tuners 1-2 are on processor module N 
Cores 1-2 are on processor module N 
Cores 11-12 are on processor module 1
Cores 21-22 are on processor module 2
MCores  1-32 are on processor module N
MCores 33-64 are on processor module 2

where N is the default processor module, and N=0 is the main board.

If a parameter is not used by a given port type, it will be ignored. To specify complex data, negate the number of bits per I and Q data elements. Example: for 16 bit complex tuner output, set bits = -16.

The function returns the DMA channel assigned, or 0 for no DMA, -1 for error. This channel number is then used by other functions such as PIC_DMAFUNC, PIC_SETKEY and PIC_GETKEY.

Tuner Banks need a call to setkey() on KEY_PKTLEN, KEY_DFREQ, and KEY_CHNS before the call to IOPORT to allow proper mapping. The number of channels in each tuner bank depends on the processor module and the FTTM=mode setting. See the help on the FTTM flag. The FRAME size is the number of consecutive bytes from each channel to write into the DMA buffer. The frames are written for channels 1 through N and then repeated. To individually set a parameter for one of the channels in a tuner bank, use setkey() on KEY_CHAN before the call to setkey() on the item.

PIC_TUNER_FREQ - Returns the nearest supported down conversion freq

PIC p Handle to Device
double fcyn Tuner frequency/nyquist desired
int flags Run-time modifiers

Returns:

double PIC_TUNER_FREQ Actual (33bit rounded) frequency

The Harris HSP50016 DDC has a 33 bit phase accumulator resulting in a tuning resolution of (input freq)/(2**33).

The Graychip GC4014/4016 has a 32 bit phase accumulator resulting in a tuning resolution of (input freq)/(2**32).

The Xilinx FPGA Tuner Core has a 32 bit phase accumulator resulting in a tuning resolution of (input freq)/(2**32).

The input frequency is rounded to the nearest legal value. This routine returns what PIC_TUNER will actually apply so that application code can easily find the actual tuned frequency.

If this function is not called on the tuners active handle, (i.e. PICD GET <device> NFREQ fcny), then the flags must contain any parameters that will affect the rounding. Namely: 

OVSR=n    if not 1
RATIO=x   if PRESAMP is being used (don't use for RESAMP)
FTTM=2|3  if FTT modes are being exercised

PIC_TUNER_DEC - Returns the nearest supported decimation

PIC p Handle to Device
int dec Tuner decimation desired
int port Index of port to use
int flags Run-time modifiers

Returns:

int PIC_TUNER_DEC Actual supported decimation

This routine returns the nearest possible decimation supported by the specified device. Each chip has different limitations. 

HSP50016	ICEPIC2
AD6620	ICEPIC3
GC4014	ICEMBT2/ICEMBT3/ICESLIC3
GC4016	ICEPIC4/ICEMBT4/ICEMBT5
FPGA		ICEPIC5

The Harris HSP50016 DDC decimation is 36 to 32768 in steps of 2.

The Graychip GC4014 in CPC=4 mode is 32 to 32768 in steps of 2. The Graychip GC4014 in CPC<4 mode is 16 to 32768 in steps of 2. These limitations are from using the GC's link port output mode.

The Graychip GC4016 in CPC=4 mode is 16 to 4096 in steps of 2. The Graychip GC4016 in CPC=2 mode is 8 to 2048 in steps of 2. The Graychip GC4016 in CPC=1 mode is 4 to 2048 in steps of 2.

The FPGA Core is 2 to 4096 in steps of 2. On main board, the FPGA core also supports decimate by 1. On processor module, the FPGA core minimum decimation is 4.

The Analog Devices AD6620 decimation is 1 to 16384 in steps supported by the cascaded filters described below.

The Analog Devices AD6620 has a 2 stage decimator where the 1st stage can decimate from 1 to 16 and the second from 1 to 32. The final FIR filter stage can also decimate by 1,2,4,8 or 16 to support the higher decimations. Default filters for each FIR decimation are supplied. This routine implements the algorithm to find the nearest possible decimation resulting from the cascaded filter stages.

The AD6620 FIR filter can only process one complex output tap per system clock. At input sample rates < 16MHz, oversampling will be set to OVSR=1, switching the system clock to the 65MHz on-board crystal oscillator.

PIC_TUNER_OVSR - Sets the inputs over-sampling ratio (zero insertion)

PIC p Handle to Device
int ovsr Tuner oversampling desired (0->255)
int side Index of side to use (-1=default, 1,2, or 3 for both)
int flags Run-time modifiers

Returns:

int PIC_TUNER_OVSR Actual supported oversampling

Sets the up-front tuner zero insertion to relax the lower end of the decimation limits. The PIC_TUNER interface takes into account the amount of oversampling being applied at the input to set the actual tuner frequency, gain, and decimation to realize a lower decimation than would normally be allowed.

The maximum oversampled rate after zero insertion is: 

PIC3		16MHz
MBT2/MBT3	40MHz
PIC4T/MBT4	100MHz
PIC5/6	125MHz

An error will be reported at runtime if this spec is not met.

PIC_FILE - Deprecated use PIC_MAPFILE

PIC p Handle to Device
HEADER hcb Header Control Block of a Midas file
int *paddr Physical PCI Address of DMA buffer (returned)
int *bytes Number of bytes in DMA buffer (returned)
int mode Access mode (1=allocate, -1=deallocate)

Prepares a Midas file for DMA transfers. It the file is on a RAMDISK the start and count map to the actual disk address. If not, a memory buffer matching the file size is allocated and mapped to DMA address space. If memory is not mappable (or mode=2,-2) paddr is set to zero and a virtual buffer is allocated but not mapped. This buffer is usable for non-DMA access which limits speeds to ~10Mby/sec.

The start and count pointers are inputs to the PIC_DMA routine. These numbers are checked by the driver to ensure the addresses are valid before the DMA is started.

PIC_MAPFILE - Prepares a Midas file/buffer for DMA transfers

PIC p Handle to Device
DMAMAP map DMAMAP structure to contain virtual and physical pointers
HEADER hcb Header Control Block of a Midas file
int mode Access mode (1=allocate, -1=deallocate)

Prepares a Midas file for DMA transfers. It the file is on a RAMDISK the start and count map to the actual disk address. If not, a memory buffer matching the file size is allocated and mapped to DMA address space. If memory is not mappable (or mode=2,-2) paddr is set to zero and a virtual buffer is allocated but not mapped. This buffer is usable for non-DMA access which limits speeds to ~10Mby/sec.

The map structure is inputs to the PIC_DMASETUP routine. These numbers are checked by the driver to ensure the addresses are valid before the DMA is started.

PIC_MAP - Deprecated, use PIC_MAPMEM

PIC p Handle to Device
int **vaddr User buffer virtual address (buffers pointer by reference)
int *paddr The physical PCI address of DMA buffer (phys addr by reference)
int bytes Number of bytes in the user buffer
int mode 1 = alloc/map, -1 = unmap/dealloc, 2 = map, -2 = unmap

If mode = 1, this routine prepares a user memory buffer for DMA transfers.

It first allocates a buffer of the requested size. Depending on the machine architecture, this is either mmap'ed to reserved physical pages (Linux PC) or mapped through hardware bus mapping registers (DEC Alpha) to the PCI bus. The user buffer's virtual address and the physical start address for the DMA are returned.

If the memory is not allocatable, start is set to zero and a -1 is returned.

The start and count pointers are inputs to the PIC_DMA routine. These numbers are checked by the driver to ensure the addresses are valid before the DMA is started.

If mode = -1, this routine unmaps and unlocks the memory associated with this DMA buffer address.

Syntax EXAMPLE from C: 

int_4	buffer[], phys_addr, bytes;
status = pic_map (p, &buffer, &phys_addr, bytes, 1)

Syntax EXAMPLE from FORTRAN: 

integer*4  buffer(*), phys_addr, bytes;
pointer	(pbuffer,buffer)
status = m$pic_map (p, pbuffer, phys_addr, bytes, p1)

If you have trouble with the pass by reference, remember that the phys_addr is not really a pointer, it is a 4-byte integer. The routine will be writing to both buffer (or pbuffer in FORTRAN) and phys_addr.

If <mode> is 2 or -2, instead of 1 and -1, the virtual buffer alloc and free are not performed in pic_map and must be handled by external code. This has been added to allow acquisition into buffers that are mmapped to other processes by user code. This mode is currently only supported on VMS.

PIC_MAPMEM - Handles allocating/mapping a buffer for DMA transfers

PIC p Handle to Device
DMAMAP map DMAMAP structure to contain virtual and physical pointers
int bytes Number of bytes in the user buffer (or 4Kby pages if < 0)
int mode 1 = alloc/map, -1 = unmap/dealloc, 2 = map, -2 = unmap

If mode = 1, this routine prepares a user memory buffer for DMA transfers.

It first allocates a buffer of the requested size. Depending on the machine architecture, this is either mmap'ed to reserved physical pages (Linux PC) or mapped through hardware bus mapping registers (DEC Alpha) to the PCI bus. The user buffer's virtual address and the physical start address for the DMA are returned.

If the memory is not allocatable, start is set to zero and a -1 is returned.

To allocate >= 2Gbytes, the size may be specified in 4Kby pages by negating the size parameter.

The map structure is inputs to the PIC_DMASETUP routine. These numbers are checked by the driver to ensure the addresses are valid before the DMA is started.

If mode = -1, this routine unmaps and unlocks the memory associated with this DMA buffer address.

Syntax EXAMPLE from C: 

DMAMAP map;
int_4	buffer[], bytes;
status = pic_mapmem (p, &map, bytes, 1)
buffer = (int_4 *)map.vaddr

or 

DMAMAP map;
int_4	buffer[], pages;
pages = size / 4096;
status = pic_mapmem (p, &map, -pages, 1)
buffer = (int_4 *)map.vaddr

Syntax EXAMPLE from FORTRAN: 

record /DMAMAP/ map
integer*4  buffer(*), bytes;
pointer	(pbuffer,buffer)
status = m$pic_mapmem (p, map, bytes, 1)
pbuffer = map.vaddr

If <mode> is 2 or -2, instead of 1 and -1, the virtual buffer alloc and free are not performed in pic_mapmem and must be handled by external code. This has been added to allow acquisition into buffers that are mmapped to other processes by user code. This mode is currently only supported on VMS.

PIC_DMASETUP - Sets up HOST DMA handler

PIC p Handle to Device
int dmac DMA Channel - usually returned from PIC_IOPORT
int dir Transfer direction (1=output/playback, -1=input/acquisition)
DMAMAP map DMAMAP structure from PIC_MAPMEM or PIC_MAPFILE
int block DMA transfer size in bytes (-1 for internal default)
int flags Run-time modifiers

Prepares a DMA channel for HOST<->Processor transfers to/from DMA addresses obtained through PIC_FILE or PIC_MAPBUF calls. This downloads DMA parameter blocks to the Processor and adds the block to a list of active DMA channels for the Processor interrupt handler to service. The DMA is initiated by a call to PIC_DMAFUNC.

By default, PCI transfers are 4 kbytes in length. For tighter host response with low data rates, this can be lowered at the expense of more overhead. The minimum transfer length is 64 bytes.

PIC_DMA - Deprecated, use PIC_DMASETUP

PIC p Handle to Device
int dmac DMA Channel - usually returned from PIC_IOPORT
int dir Transfer direction (1=output/playback, -1=input/acquisition)
int *buffer DMA buffer virtual address (from PIC_MAP or PIC_FILE)
int paddr DMA buffer physical PCI address (from PIC_MAP or PIC_FILE)
int bytes DMA buffer size in bytes
int block DMA transfer size in bytes (-1 for internal default)
int flags Run-time modifiers

Prepares a DMA channel for HOST<->Processor transfers to/from DMA addresses obtained through PIC_FILE or PIC_MAPBUF calls. This downloads DMA parameter blocks to the Processor and adds the block to a list of active DMA channels for the Processor interrupt handler to service. The DMA is initiated by a call to PIC_DMAFUNC.

By default, PCI transfers are 4 kbytes in length. For tighter host response with low data rates, this can be lowered at the expense of more overhead. The minimum transfer length is 64 bytes.

PIC_DMAFUNC - Starts, Stops, Polls, or Waits on a DMA transfer

PIC p Handle to Device
int dmac DMA Channel - usually returned from PIC_IOPORT
int mode Action to perform (ONESHOT,CONTINUOUS,STOP,WAIT,STATUS,CANCEL,MISS)

Utility functions for DMA's set up by PIC_DMA. The mode field supports the following function identifiers (defined in ICELIB.INC/H): 

DMA_ONESHOT	- Starts a once-through DMA to the user buffer and quits.
DMA_CONTINUOUS- Starts a continuous circular DMA to the user buffer.
DMA_STATUS	- Returns the current buffer read/write byte index (0 based)
DMA_CYCLE	- Returns the current cycle through the host buffer (0 based)
DMA_POLL	- Returns 1 if DMA is active, 0 if DMA is completed.
DMA_WAIT	- Waits for the DMA to complete.
DMA_RESHOT	- ReStarts a once-through DMA to the user buffer and quits.
DMA_STOP	- Stops the current DMA immediately.
DMA_RESET	- Resets DMA buffer pointers after a DMA_STOP.
DMA_CANCEL	- Removes the DMA control block from the active list.
DMA_LOST	- Reports number of Processor buffers missed.
DMA_ACTIVE	- Reports number of channels active on this dmac's input module

The DMA_ONESHOT and DMA_CONTINUOUS options are used to start a DMA. The DMA_STATUS option is used to track the current DMA pointer.

For data snapshots, the user code should use DMA_ONESHOT followed by a DMA_WAIT, and finally issue a DMA_CANCEL before closing the device. The DMA_WAIT return status is 0 for normal completion, -1 for timed out, and -2 if buffers were dropped in this transfer (DMA_MISS returns how many). If the routine is cancelled by McBreak or a card error, a -3 is returned.

To perform multiple ONESHOTs, use an initial DMA_ONESHOT/DMA_WAIT pair followed by any number of DMA_RESHOT/DMA_WAIT pairs. This allows output streams to flush output fifos in a contiguous manner.

To perform multiple DMA_CONTINUOUS or non-contiguous DMA_ONESHOT transfers, each transfer must be followed by a DMA_STOP and DMA_RESET to prepare the resources for a clean restart.

For continuous acquisition/playback, use DMA_CONTINUOUS followed by a polling loop that uses DMA_STATUS to monitor the current read/write pointer. Acquisition programs must read data out of the DMA buffer before the write pointer wraps around to overwrite the old data. Playback programs will need to feed the data buffer close behind the read pointer to ensure the read pointer always has fresh data. User programs can typically be 'swapped' out for 1-10 msec at times. The DMA buffer needs to be large enough to cover any latencies caused by the system scheduler or the program itself.

The DMA_STATUS function returns an integer containing the offset from the top of the circular buffer (in bytes) of the current DMA read/write pointer. At the start of an acquisition/playback, the status will be 0, and increment through the number of bytes in the buffer minus one DMA transfer length, (typically 1Kbyte) before returning to zero.

If separate calls are made to DMA_INDEX and DMA_CYCLE to find the current data sample number, the index may wrap around between the two calls giving erroneous results. If you do not wish to monitor the index pointer for this situation, use pic_dmastat(). It is a bit slower, but easier to use.

PIC_DMASTAT - Returns the current DMA index, cycle, and status

PIC p Handle to Device
int dmac DMA Channel - usually returned from PIC_IOPORT
int *index Current DMA index is returned (zero based)
int *cycle Current DMA cycle is returned (zero based)
int PIC_DMASTAT Current DMA port status (0=stopped, 1=running)

This routine is useful for obtaining the current DMA host buffer index, host buffer cycle number and DMA port status.

The index value is guaranteed to be from the current cycle.

PIC_DMAXFER - Transfers next available data to/from the host circular buffer

PIC p Handle to Device
int dmac DMA Channel - usually returned from PIC_IOPORT
int *buffer Pointer to transfer buffer
int bytes Number of bytes in transfer buffer
int flags Operational modifiers (FLG_NOWAIT=nonblocking)
int PIC_DMAXFER Number of bytes transferred

This routine handles the book-keeping for transferring data into or out of the DMA channel's circular buffer on the host. The host buffer should be a multiple of the transfer length. The routine polls the status registers on the card and transfers data when a full transfer is possible.

This routine returns the number of bytes transferred, 0 if no data is transferred and the FLG_NOWAIT is specified, -1 when the DMA function is completed, and -2 for an error.

Note: If a timeout TO=N flag is specified in the open string, and no data is transfered within N seconds, the routine will return with status=0.

PIC_DMAXPTR - Returns pointer to buffer with the next available DMA data

PIC p Handle to Device
int dmac DMA Channel - usually returned from PIC_IOPORT
int **buffer Pointer to pointer to transfer buffer
int bytes Number of bytes in transfer buffer
int flags Operational modifiers (FLG_NOWAIT=nonblocking)
int PIC_DMAXPTR Number of bytes transferred

This routine is similar to PIC_DMAXFER except that the actual transfer is left to the user. It waits for the next transfer to be available and returns a pointer to the spot in the circular buffer where the data is located.

This routine returns the number of bytes ready to transfer, 0 if no data is available and the FLG_NOWAIT is specified, -1 when the DMA function is completed, and -2 for an error.

Note: If FLG_NOWAIT is specified and the return status == 0 indicating no data available, the user should add a usleep of roughly one buffers length or 10 mSec, whichever is greater, for efficient use of the PCI bus. Over-polling can cause data fall-behinds.

Note: If a timeout TO=N flag is specified in the open string, and no data is transfered within N seconds, the routine will return with status=0.

PIC_DMACHAIN - Set up a DMA chain table entry

PIC p Handle to Device
int dmac DMA Channel - usually returned from PIC_IOPORT
int index Index of this chain entry (1-256)
DMAMAP map DMAMAP structure from PIC_MAPMEM or PIC_MAPFILE
int todo Number of times to execute this chain (-2 for indefinite)
int next Index of the next chain entry (1-256)

This routine is useful for setting up a chain of buffers for continuous seamless acquisition or playback of multiple host buffers. Index=1 is automatically linked to the the parent dmac channel. The last entry should set next=0. Index counts by 1, 2, 3, ... The actual address of each chain is determined by the libraries. See pic_dmadump() for the actual values.

PIC_LOADFILE - Loads code from file onto SHARC, PPC, IOC, etc.

PIC p Handle to Device
string filename Name of file in the ICE DAT subdirectory
int flags Run-time modifiers (FLG_SHARC, FLG_IOC, FLG_MOD, etc.)

Loads a program from a file into one of the chips on the card, according to the flags argument: 

FLG_SHARC  -  the SHARC DSP code
FLG_PPC    -  the PowerPC DSP code
FLG_JVM    -  the FPGA JVM code
FLG_IOC    -  the Altera IOC controller code
FLG_MOD    -  the Altera code on an I/O Module
FLG_PM     -  the Xilinx code on a Processor Module
FLG_FC     -  the filter coefficients on a tuner chip

It must be a Midas file in the DAT subdirectory of the ICE tree. A * in the filename is replaced by the card name. For example: 

pic_loadfile (p, "*", FLG_SHARC);

loads the file $ICEROOT/dat/icepic3.prm into the SHARC chip if "p" is opened to an ICEPIC3 card. 

pic_loadfile (p, "*_t1", FLG_IOC);

loads the file $ICEROOT/dat/icembt3_t1.prm into the IOC chip if "p" is opened to an ICEMBT3 card. 

pic_loadfile (p, "icecxd", FLG_MOD|0x2);

loads the file $ICEROOT/dat/icecxd.prm into the 2nd I/O Module's chip. 

pic_loadfile (p, "fc_damps", FLG_FC|0x5);

loads the filter file $ICEROOT/dat/fc_damps.prm onto tuner #5.

This function ends up calling PIC_LOADSHARC, PIC_LOADPPC, PIC_LOADIOC, PIC_LOADMOD, or PIC_LOADFC. See the help on these routines for more specific information.

PIC_LOADSHARC - Deprecated, use PIC_LOADFILE

PIC p Handle to Device
byte prog[] Array of bytes containing the SHARC load file
int nprog Number of 48 bit words in prog[]
int flags Run-time modifiers

Loads a program into the SHARC and begins execution if flags=1.

The SHARC has two register banks. In the ICE-PIC architecture, the 1st bank is used for user programs and the 2nd bank is used for the interrupt handlers. This allows for very low overhead interrupt service routines to manage the ongoing DMA requests. User programs have full access to the DMA control blocks and any of the IO port control registers. They can be written in C or SHARC assembler.

PIC_LOADPPC - Deprecated, use PIC_LOADFILE

PIC p Handle to Device
byte prog[] Array of bytes containing the PowerPC load file
int nprog Number of 32 bit words in prog[]
int flags Run-time modifiers

Loads a program into the PowerPC and begins execution if flags=1.

PIC_LOADIOC - Deprecated, use PIC_LOADFILE

PIC p Handle to Device
byte prog[] Array of bytes containing the IOC load file
int nprog Number of 8 bit words in prog[]
int flags Run-time modifiers

Loads a program into the IOC and begins execution if flags=1. This is used to download programs into the IOC FPGA. On a 5 series card, this just sets the operational flags that accompany a specific IOC signature.

PIC_LOADMOD - Deprecated, use PIC_LOADFILE

PIC p Handle to Device
int port I/O module number
byte prog[] Array of bytes containing the IOC load file
int nprog Number of 8 bit words in prog[]
int flags Run-time modifiers

Loads a program onto the I/O Module.

PIC_LOADFC - Loads filter coefficients (FC's) from memory buffer onto tuner chip

PIC p Handle to Device
int port Tuner port number
short data[] Array of shorts containing the filter coefficients
int ndata Number of 16 bit words in data[]
int flags Run-time modifiers

Loads filter coefficients into the tuner port. If the filter has non-unity gain, the user must reset the GAIN after loading the coefficients. Use PIC_SETKEY with KEY_GAIN. If the card will be using a non-default CPC value, make sure to set the CPC=x flag to the same value while loading filters as while running to ensure that ganged channels are setup properly.

Note: The CFIR and PFIR tuner filters will normally be half band (or less) because the filters decimate by two in the output stage. However, when using CPC=1 with a graychip 4016, the PFIR output is not decimated so the filter should be based on the actual output rate. See the graychip datasheet for more info.

PIC_TIMER - Deprecated, use PIC_SETKEY with KEY_ICLK

PIC p Handle to Device
int port Module Number (1-2)
int freq Frequency in Hertz

This routine has been DEPRECATED - Use PIC_SETKEY with KEY_ICLK

Sets the internal clock frequency for each module port. This can be used for the ICE-A2D input or ICE output modules if no external clock is supplied. It is a simple divider on the cards 40MHz crystal which is by no means a precision frequency reference. It may be acceptable for applications involving audio or other low rate signals.

PIC_NVRAM - Reads/Writes/Converts NVRAM code for PCI-IF chip

PIC p Handle to Device
string name File name
int mode Mode (-1=READ, 1=WRITE, 0=CONVERT)

This routine is for development only and is not supported on many systems. It can be used to tune the PCI Interface parameters for optimal DMA performance. Please consult the developer before using this routine.

PIC_TC - Returns the timecode for a given sample

PIC p Handle to Device
int dmac DMA Channel
double *offset Sample offset (in/out)
double *tdelta Time delta per sample (in/out)
double *soy Seconds of year (out)
double *fsoy Fractional seconds of year (out)
int flags Function flags (FLG_TCINTERP,FLG_TCDELTA)

Returns:

int PIC_TC Status (2=oknc, 1=ok, -1=inActive, -2=badParam, -3=noBits

-4=noBarker, -5=BCDerr, -6=NaN, -7=noClock, -8=badStart, -9=NTPerr)

This routine returns the value of the most recent timecode along with the sample offset, or this value interpolated to the specified sample offset. The return status are defined in icelib.h as TC_OK, TC_INACTIVE ...

Timecode processing is enabled by the presence of the TC=mode flag in the pic_open() configuration string. In Midas, the value of the /TC=mode switch is inserted into the flags string by the SOURCEPIC and PICDRIVER primitives.

Currently, CPU, ZTC, IRB, SDDS, SDN, SMS, and DTL (Datolite) modes are supported.

The IOC gate array continuously looks for the Barker code (in serial formats), time code valid bits (in SDDS packets), or 1PPS trigger (in A2Ds) and stores the last two timecodes in gate array memory along with the input sample number where the time code was found. When called, the last timecode is retrieved from the gate array, processed, and optionally extrapolated to the sample at 'offset' using the 'tdelta' argument. If the FLG_TCINTERP is not present 'offset' will contain the sample offset that the last timecode references. This offset is a zero based output sample number since the start of the acquisition.

If the acquisition is from a tuner port, the filter delays and decimation are compensated for in this routine. The interface is in terms of the tuner output. This means that the <offset> sample where the timecode was found will probably be a fractional number.

The CPU mode will tag the input samples as accurately as possible with the system clock as the reference. This is typically accurate to 10-50 msec.

On PIC4 and later cards, CPUPX and CPUP0 will use a 1PPS signal on the eXternal SMB or bit 0 to refine the system CPU to one input sample. This assumes the system CPU is locked to the 1 PPS to within 100ms by a GPS time server or equivalent. NOTE: On startup this will return -3 until the first valid 1PPS is registered. This could be up to 1 second.

NOTE: When using CPUPX, jumper J2 must be closed on the pic card to route the 1PPS signal from the eXternal SMB.

NOTE: CPU0P and CPUXP are an alternate syntax for CPUP0 and CPUPX

The ZTC mode is a Zero based Time Code that will tag the samples based on the 1st input sample being time=0. When used with the /TCOFF=n switch on SOURCEPIC and PICDRIVER, this allows a file on disk that may no longer have timecode in the data to be played through the tuners and behave as if normal timecode were present. The /TC=ZTC should be placed on the tuner's input primitive allowing the libraries to add the proper delay through the tuners. If /TCOFF=0, the TC will be the delay from the 1st input sample to the 1st output sample. See EXP PICTUNER for an example.

The mode string for the bit-serial embedded formats have the form: 

Mode = SDN, SMS, DTL, SDN#, SMS#, DTL#, SDN#X, SDN#F?, SMS#F?, DTL#F?
where # = bit position, ? is fill value, X is extended prec.

The default <mode> is SDN. The default bit position is 4 for SDN and 0 for SMS, where the least significant bit is 0. If the 4th character in the mode string is specified, this overrides the default bit position.

By default the SDN/DTL extended precision is ignored. Many systems do not terminate the valid timecode with fill bits all of the time, making auto detection suspect. To use the extended precision (if necessary) add an "X" anywhere after the 4th character of the mode string.

The IRB mode defaults to getting the digital IRIG-B signal on the external sync port X, or IRBX. This signal may also be presented on bit0 of the A port by specifying IRB0. An optional 1PPS signal can be applied to refine the position of the IRIG-B marker. To use this, add a P as in IRBXP0 or IRB0PX. In IRB0PX, the 1PPS is then taken from the external sync pin. NOTE: On startup, this will return -3 until the first valid 1 sec time hack is registered. This could be up to 2 seconds for the IRIG mode.

NOTE: IRB0 and IRB0P are not supported on PIC5+ cards, only IRBX and IRBXP0. NOTE: for IRBX, jumpers J2 and J3 on the main board should be closed, J1 open.

The default fill value is 1 for SDN and 0 for SMS. If an "F" is found in the mode string, the next character specifies the fill value (0 or 1). NOTE: The fill value is only necessary for output which is not supported yet.

For example, the mode string 'SDN3XF0' specifies an SDN type timecode on bit 3 of the input stream with a zero for the fill bit using eXtended Very Fine Time. An example device string for this case might be: 

devstr = "ICEPIC,DEVNO=0,IOM=E2D,TC=SDN3XF0,PORT=MODULE1,"

The SDDS mode is used for modules that support SDDS packets. This option allows applications to use the standard timecode processing mechanism even when receiving packetized SDDS data. The cards also support processing SDN timecode embedded with the SDDS packet payload. See PIC HELP TIMECODE for more information on this.

NOTE: The IOC has a clock loss circuit for input data rates > 200kHz. If no clocks are detected over a 5 usec period, it is assumed that the clock, even if it recovers, may have had glitches that would render the timecode values invalid. If this occurs, PIC_TC will return a -7 status until the acquisition is restarted. The OKNC flag turns this status into a TC_OKNC status which recognizes the timecode as good, assuming the noClock is bogus.

PIC_TIMECODE - Deprecated, use PIC_TC

PIC p Handle to Device
int dmac DMA Channel
string mode Mode (SDN, SMS, SDN#, SMS#, SDN#F?, SMS#F?)

where # = bit position, ? is fill value, X is extended prec

double offset Sample offset
double tdelta Time delta per sample
int dec Current decimation
int bits Bits per sample in buffer
int_2 *buf Host DMA buffer (only used for 16 bit raw data)
double *soy Seconds of year (returned)
double *fsoy Fractional seconds of year (returned)

This routine has been DEPRECATED - Use PIC_TC

PIC_GETINTFLAG - Gets an integer valued flag from the configuration string

PIC p Handle to Device
char *name Name of flag (DEVNO,INP,PMI, ...)

Gets the named FLAG as an integer and returns this as the status. If the flag is not found -1 is returned. If the flag is found without an = value, 1 is returned.

PIC_GETDBLFLAG - Gets an double valued flag from the configuration string

PIC p Handle to Device
char *name Name of flag (RFFREQ,RFBW, ...)

Gets the named FLAG as a floating point double and returns this as the status. If the flag is not found -1 is returned. If the flag is found without an = value, 1 is returned.

PIC_STR2IP - Translates string name into a binary IP address

PIC p Handle to Device
string name String form of IP address (eg 224.1.2.3)
int PIC_STR2IP Binary IP address

This routine translates an IP address in string form into a binary integer. The return value is useful for calls to setkey on KEY_IPCONN, KEY_IPDISC, etc.


Single properties should be accessed through the SET/GET KEY routines:

PIC_NAME2KEY - Translates string name into a key ID

PIC p Handle to Device
string name Key name
int PIC_NAME2KEY Key Identifier

This routine translates a string name into a key identifier. This can be used by user interface code to make a generic interface to the getkey/setkey functions. Returns the key identifier for use in the SETKEY and GETKEY functions.

Unless noted all keys are int_4 data types. See HELP on KEYS for a list of supported key names.

PIC_SETKEY - Sets a parameter by key/value pair

PIC p Handle to Device
int index Resource index (usually DMA channel number from PIC_IOPORT)
int key Key Identifier
void *value Buffer of data
int len Length of data item in bytes

Sets the named KEY to the value specified. See help on KEYS for a list of key names.

If a DMA channel number is not available or appropriate, use the negative of the port number in the index field.

The include file names are formed by prepending KEY_. For example: 

status = pic_setkey (p,dmac,KEY_FREQ,&freq);	! C call
status = m$pic_setkey (p,dmac,KEY_FREQ,freq);	! Fortran call

PIC_SETKEYL - Sets a 4 byte integer parameter by key/value pair

PIC p Handle to Device
int index Resource index (usually DMA channel number from PIC_IOPORT)
int key Key Identifier
int value Data value

Sets the named KEY to the value specified. See help on KEYS for a list of key names.

PIC_SETKEYD - Sets a double parameter by key/value pair

PIC p Handle to Device
int index Resource index (usually DMA channel number from PIC_IOPORT)
int key Key Identifier
double value Data value

Sets the named KEY to the value specified. See help on KEYS for a list of key names.

PIC_GETKEY - Gets a parameter by key/value pair

PIC p Handle to Device
int index Resource index (usually DMA channel number from PIC_IOPORT)
int key Key Identifier
void *value Buffer for data
int len Length of data item in bytes

Gets the named KEY into the value buffer. See help on KEYS for a list of key names.

If a DMA channel number is not available or appropriate, use the negative of the port number in the index field.

The include file names are formed by prepending KEY_. For example: 

status = pic_getkey (p,dmac,KEY_FREQ,&freq,8);	! C call
status = m$pic_getkey (p,dmac,KEY_FREQ,freq,8);	! Fortran call

PIC_GETKEYL - Gets a 4-byte integer parameter by key/value pair

PIC p Handle to Device
int index Resource index (usually DMA channel number from PIC_IOPORT)
int key Key Identifier
int PIC_GETKEYL Returns Key value

Gets the named KEY into the function return value. See help on KEYS for a list of key names.

PIC_GETKEYD - Gets a double parameter by key/value pair

PIC p Handle to Device
int index Resource index (usually DMA channel number from PIC_IOPORT)
int key Key Identifier
double PIC_GETKEYD Returns Key value

Gets the named KEY into the function return value. See help on KEYS for a list of key names.

PIC_GETKEYV - Returns whether the specified key is valid for this port

PIC p Handle to Device
int index Resource index (usually DMA channel or IO port number)
int key Key Identifier
int PIC_GETKEYV Returns 1 if Key is valid for this port

Checks the ICEROOT/tbl/iom/* tables for valid keys. Not all available keys are meaningful for a specific module. This function allows a user to test a key for validity before attempting to get or set it. See help on KEYS for a list of key names.


Valid Keys Include: RATE,FREQ,DEC,GAIN,OVSR,FRAME,CHAIN,MOD,IOC,APP,IPADDR See PIC HELP KEYS for a full list of keyed parameters.

All routines return a status that is 1 for success and -1 for failure unless otherwise noted.

All routines have a FORTRAN callable wrapper. The wrapper name is formed by prepending an M$ and the arguments are all passed by reference. Both C and FORTRAN routines are lowercase.

Retrieved from "https://wiki.ice-online.com/index.php?title=ICE_Help_ICELIB&oldid=683"