Help: ICE_ICELIB_PIC_OPEN

Open a connection to an ICE-PIC device

Function 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