SOURCEPIC
Manage ICEPIC acquisition into a Midas file/pipe.
SOURCEPIC - Manage ICEPIC acquisition into a Midas file/pipe
<input file> Name of the RAMDISK or RAM template file
<output file> Name of the output file/pipe
<device name> Name of PIC device PORT alias in the HWCONFIG file
<decimation> Tuner Decimation or Frame Thinning factor
<tunerfreq> Tuner Center Frequency in Hz (0 to nyquist)
<tunergain> Tuner Gain in dB (-100 to 100)
This routine reads data from a RAMDISK file or an in-memory buffer that is
acquiring data through an ICE-PIC card. The <device name> is required to
specify the card and which port on the card is to perform the acquisition.
See explain PICDRIVER for more details on HW alias specifications.
Currently, RAMDISK files are only supported on Linux. In all other cases,
the <input file> serves as a template for an in-memory buffer, the contents
of which will not be altered.
The <input file> normally describes the input data format, sample rate, and
circular buffer size AFTER tuning and/or decimation. For non-tuner ports,
decimation is performed on a frame basis, where the frame length is defined
by the input file's type 2000 subsize. By default, tuner decimation is
performed on the card, and frame decimation in the host. This allows all
of the raw (or non-tuner) data to reside in the rambuffer for archiving,
while slices of data are piped to spectral displays for monitoring. To
perform the frame decimation in the card to cut PCI bandwidth, use /HOST=N.
In /HOST=N mode, the frame length must be a power of 2 between 256 and 1M.
To apply framed decimation after the tuner or core decimation step, use
the /SKIP=N switch. This copies only every Nth frame of data to the output.
The /REPLAY controls the startup mode of the routine as follows:
/REPLAY=-1 File - plays buffer once and quits (default file2file)
/REPLAY=0 Stopped - waits at top of buffer
/REPLAY=1 Oneshot - plays buffer once and waits at the top again
/REPLAY=2 Continuous - plays buffer continuously (default piped)
/REPLAY=3 StopTop - stop PIC at next top of buffer
/REPLAY=4 StopNow - stop PIC now (does not restart where it left off !!)
/REPLAY=5 Spin - run PIC but do not read data off of the RAMDISK
/REPLAY=6 Archive - stop PIC and read one buffer from the RAMDISK
/REPLAY=7 ReStart - restart continuous acq (resync tuner/timecode)
/REPLAY=8 Abort - abort processing and close output pipe/file
/REPLAY=9 Reconnect - reconnect to device now pointed to by result in <device name>
/REPLAY=11 Reconnect - reconnect to current device (only when ports are stopped)
In NeXtMidas, the /REPLAY=values can be specified by the item number or name.
File mode is the default in file-2-file mode. In a piped macro, Continuous
is the default. Oneshot mode is used if REPLAY appears as a state switch
(no "=" after the switch). All modes can be interrupted by sending controls
while they are in progress (i.e. through the XPIPE window). The options are
accessed through the REPLAY MODE control item under SOURCEPIC primitive menu.
The /REPLAY=0 switch will start the routine stopped at the top of the buffer
waiting for a control to replay the buffer. This will be a menu item in XPIPE.
The /SYNC=label switch can be used to specify a results label to be set at
the top of each cycle through the file. The result receives the number of
seconds since midnight at which the sync occurred.
The /LOST=label switch can be used to keep track of the number of buffers that
SOURCEPIC has fallen behind if it can't keep up.
Master/slave relationships between multiple invocations of SOURCEPIC in the
same macro are handled with the /MASTER=wid and /SLAVE switches. The /MASTER
switch points to the SYNC MODE widget of another SOURCEPIC. Whenever the
master SOURCEPIC starts or stops its acquisition, it will signal the slave
to start or stop accordingly. The REPLAY widget of the slave should NOT be
set by the user. It is synchronized and changed by the SOURCEPIC master.
SOURCEPIC/WB=1/MASTER=2002 RAMFILE1 _CB1 MOD1A
SOURCEPIC/WB=2/SLAVE RAMFILE2 _CB2 MOD1B
The master/slave relationships may be cascaded to allow multiple slaves.
For example, the following shows one master and 2 slaves. The second slave
is on a seperate card. To be synchronized to the sample, the cards must
have their external sync SMBs connected with jumper J2 closed.
SOURCEPIC/WB=1/MASTER=2002/FLAGS=XSOE RAMFILE1 _CB1 MOD1A
SOURCEPIC/WB=2/SLAVE/MASTER=3002/FLAGS=XSOE RAMFILE2 _CB2 MOD1B
SOURCEPIC/WB=3/SLAVE=XT RAMFILE3 _CB3 MOD2A
In NeXtMidas, the /MASTER=value must be the slaved Command ID, not
the slaved WidgetID as in XMidas. For example:
SOURCEPIC/ID=SPM/MASTER=SPS/FLAGS=XSOE ramfile1 _cb1 MOD1A
SOURCEPIC/ID=SPS/SLAVE/MASTER=SPT/FLAGS=XSOE ramfile2 _cb2 MOD1B
SOURCEPIC/ID=SPT/SLAVE=XT ramfile3 _cb3 MOD2A
A /FLAGS= switch along with a string in the hwconfig file are used to modify
the default behavior of the device for special purposes. See the PICDRIVER
explain file for details.
The /PACKET switch turns on packet mode. Each transfer length of data is
preceded by a 64 byte header with the format defined in packet.inc or packet.h.
If /TC is specified, this packet will contain the timecode evaluated for each
packet (this may be interpolated from a previous packet in some cases).
If /PACKET=_pipename is used, the packet header will be written to its own
pipe. The data can be read from the regular output pipe or directly mapped
using information in the packet headers. This is useful for high speed
applications where memory-to-memory copies are too costly.
If /APACKET is used, packets of /ARCHTL=n size are written to the archive output.
If /APACKET=suffix is used, the suffix is appended to the current archive file
name and the packet headers are written to a separate file.
In NeXtMidas, the /PACKET=pmss and /APACKET=pmss switches are parsed as PACKET
formats native to the framework. The default Packet Mode Switch String is ICE.
This is written to the files PACKET keyword for the framework libraries to use.
Other supported options are:
ICE/DET - to detach the headers into a separate file named <filename>.pkt
ICET - to include time delta fields in ICE packet. Also ICET/DET.
SDDS/ICE - to present SDDS headers with ICE address extension. Also SDDS/ICE/DET.
The /MULTI=n can be used to control multiple channels from the same instance
of SOURCEPIC. Tuner channels share decimation and rate, but have independent
freq and gain which must be changed through a message (the ID field is the
channel number). Channel 1 is what <device> references (this may actually be
TUNER5 or LINK2, etc.). The next n-1 channels are the next ports of the same
type as <device>. If /AUTOSS is specified, all ports will be on the same side
of the card. For instance (TUNER9,TUNER11,TUNER13,TUNER15). They are all
started and stopped by the same REPLAY widget. This is intended to be used
in conjunction with /PACKET so the headers can be used to separate the blocks
of channel data at some later time. See %TESTMULTI in the MCR area and PICFUNC
for more details.
The /ALG=name may be applied to select an algorithm to be performed by the
SHARC before the data is copied to the host. If this is an INTERNAL port,
the /FEED=n switch selects the dma channel to get the data from, otherwise
the data is processed in place. In this case the input and output rates from
the algorithm must be identical. Each algorithm can have up to 4 arguments.
The /NARG=n switch defines how many arguments are used by the algorithm.
The argument's initial values are set via switches /ARG1=xx /ARG2=xx ...
The default for an arg is zero. A real-time widget is created for the
algorithm number and each argument. For DEMOD algorithms, the demod value
is in the imaginary part of the complex output samples. The real part
contains the rough amplitude measurement to be used for gain control.
If the RESAMP flag is applied, the tuner resampler will be enable with a fixed
fractional or integer ratio set by /RATIO=x. The resampler filters must first
be loaded with a PICD LOADFC command.
In Nextmidas, the status results are available through the class methods like
getLost(), getSeqErr(), etc. They are typically accessed in a macro using
the REG.SOURCEPIC.LOST, REG.SP.SEQERR, etc. syntax.
Switches:
/FLAGS=flgs Add specific flags to config string (see PIC HELP FLAGS)
/REPLAY=N Controls the startup replay mode of the routine
/MASTER=wid Widget id of synch mode of slave sink/sourcepic to control (X-Midas)
/MASTER=rid Registry ID of slave sink/sourcepic to control (NeXtMidas)
/SLAVE Run port in slave mode and use cue from master (uses SGO)
/SLAVE=SS Run port in slave mode from master on same side (uses RGO)
/SLAVE=XT Run port in slave mode from external trigger (uses XGO|TGO)
/SYNCDATA Ensure master/slave pairs output same number of samples (X-Midas)
/WAIT=sec Seconds to wait after M$SYNC or autorestart before starting
/POLL=sec Seconds to pause polling the card for new data
/AUTORS Automatically restarts (REPLAY=7) if Master/Slave output pipes become
misaligned by more than one buffer or if timecode is activated and the
time slips by more than /TCTOLR or the tuner decimation is changed
/AUTORS=2 AutoRestart with wait for all channels on input
/AUTORS=3 If input channels do not respond, bury them anyway before restart
/AUTORS=4 Stop on auto restart criteria
/AUTORS=8 Abort on auto restart criteria
/AUTORS=-2 Implement continuous mode using oneshot with autorestarts
/TIMEOUT=n Seconds to wait before no data flowing causes restart
/MAXOUT=n Maximum number of samples in output file (file-to-file autostop)
/PORT=port Use the specified input port (see HELP PIC_OPEN)
/BITS=n Override number of bits per word in file
/SRATE=n Override samplerate in file
/RATIO=x Set tuner resampler ratio (x = resampOut/tunerOut and can be fractional)
/DMAC=n Override default DMA channel (see PICDRIVER)
/HOST=Y|N Override default processor
MODULE Default = decimation in host (/HOST=yes)
TUNER Default = tune/decimation in tuner (/HOST=no)
CORE Default = decimation in core (/HOST=no)
/SKIP=n Write only every Nth frame of data to the output pipe. Archiving is not affected.
/TC=mode Enable time code processing (SDN#, SMS#, SDDS). See HELP PIC_TC for syntax.
/TCOFF=ysec The beginning of year in J1950 seconds to be added to
timecode values (default=current year)
/TCPP=N Evaluate timecode every Nth packet (default is per ram buffer)
/TCPS=N Evaluate N timecodes per second (more natural form of TCPP)
/TCTOLR=sec TimeCode tolerance in seconds
/TCSTAT=res Result name to hold last time code or TC error status (X-Midas only)
(NeXtMidas uses REG.SourcePicID.TC timecode object reference)
/SYNC=label Result label to be set at top of each buffer (X-Midas)
/LOST=label Result label to be set with number of buffers lost (X-Midas)
/PFULL=label Result label to be set with percentage full of buffer (X-Midas)
/SEQERR=label Result label to be set with number of SDDS sequence errors (X-Midas)
/SEQFILL=labl Result label to be set with number of SDDS sequence fills (X-Midas)
/NTPOFF=label Result label to be set with the current NTP offset in seconds (X-Midas)
/MULTI=nport Multichannel mode
/RENUM=begin Renumber packet channel numbers from <begin> to <begin+nport-1>
instead of using the actual port numbers
/RTFILE Update ramdisk file header fields to allow reading with SOURCEFILE/RTFILE
/AUTOSS Force multi-channel ports to be on the same side (A or B input)
/DFREQ=freq Frequency delta between multiple channels (if uniform spacing)
/NCHN=N Number of channels in TunerBank mode
/ARCH=name Filename for continuous archiving to disk (w/o sending messages)
/ARCHTL=n Transfer length for archive file writes
/ARCHSF Archive each buffer to Separate File (archname_XXXXX count)
/ARCHTO=n Archive TimeOut in seconds for multi-file auto closeout (NeXtMidas only)
/FLUSH Flush all data and header information to disk at the bottom of each buffer
/ALG=name Algorithm name to perform (AM,FM,PM...)
/NARG=N Number of arguments to the algorithm
/ARGx=value Initial value for arg x (i.e. /ARG1=10 /ARG2=1k)
/STATS=N Show buffer status at top of every Nth buffer (if X-Midas N=1 only)
/VERBOSE=n Where n = 0:off, 1:on, 2:timecode (adds widget in X-Midas)
/QUIET Suppress all informational text output
/MONITOR=mode Output pipe monitor mode (Off,Async,Info,Full)
X-Midas Packet Switches:
/PKTMODE=type Packet Mode Options 0=BufferOffsets, 1=TimeDelta/Start, 2=Rate/Freq
Defines which data fields will use the last 16 bytes of packet the header
/PACKET Packet Mode (headers and data interleaved in <output>)
/PACKET=hfile Packet Header Mode (headers to hfile, data to <output>)
/APACKET Archive Packet Mode (headers and data interleaved in <output>)
/APACKET=suff Archive Packet Header Mode (headers to <name><suff>, data to <output>)
where name is from /ARCH=name switch or an ARCHIVE message.
NeXtMidas Packet Switches:
/PACKET=pmss Packet Header Mode (apply Packet Mode Switch String)
/APACKET=pmss Packet Mode for the archive output file
(Note: /APACKET=.PKT in XMidas is the same as /APACKET=ICE/DET in NeXtMidas)
Control Widgets: (X-Midas)
1. M:REPLAY MODE (=99 if startup err)
2. M:SYNC MODE
3. D:SAMPLE RATE (Hz)
4. L:TUNER DEC or REDUCTION
5. D:TUNER FREQ (Hz) - overwritten by SOURCEPIC with actual frequency
6. L:TUNER GAIN (db) - 1dB resolution
7. L:NCYCLE
8. L:LOST (Host buffer fall behind count)
9. L:MISS (Card buffer fall behind count)
[+1]. D:RESAMPLER ratio if enabled (optional)
[+1]. L:ALG Algorithm number (optional)
[+1]. L:ALGARG Algorithm args (optional)
[+1]. L:VERBOSE Verbose Mode (optional)
Messages: (X-Midas)
MGO info:replaymode D:time where time is M$NOW time to take action
returns =MGO with D:time where time is M$NOW time of event
(if INFO=0, messages will be blocked until current acquisition
completes at which time an =MGO will be returned. If acquisition is
not currently in a naturally stopping mode, mgo will be set to 4 = stop now )
RATE D:samplerate
FREQ D:tunerfreq
DEC D:decimation
GAIN D:tunergain
RFDG D:samplerate D:tunerfreq D:decimation D:tunergain
This is a synchronous change of all 4 values. The RATE,FREQ,DEC,GAIN, and
RFDG messages only execute if the value has changed. To force execution
for other reasons (i.e. OVSR changes), set the message info field to 1
NFREQ info:channel D:freq Returns the actual frequency available nearest to <freq>
=NFREQ info:channel D:afreq The actual frequency available nearest to <freq>. If this
is a TunerBank, returns the freq of specified channel when the entire bank is
tuned to <freq>. The channel number is one based.
JOIN info:ipvlan S[16]:ipaddr
LEAVE info:ipvlan S[16]:ipaddr
TC D:sample offset in output file to calc timecode at, except:
sample=-1 uses the latest output sample
sample=-2 returns TC measured at the last acquisition start
returns an "=TC" message
=TC D:sample offset in output file actually interpolated to
D:X-Midas timecode at beginning of sample (whole seconds)
D:X-Midas timecode at beginning of sample (fractional seconds)
STATUS INFO=widget number, or 0 for all widgets
=STATUS INFO=widget number, or 0 for all widgets
D:specific widget, if INFO!=0 else
D:replay D:sunc D:rate D:dec D:freq D:gain D:ncycle
DEVICE if INFO>0 select tuner number <INFO> on current card
else S[40]: New device name to connect to
ARCHIVE S[80]:filename D:start D:duration
This message causes an archive file to be written of length
<duration> seconds starting at <start> in M$NOW seconds.
The current transfer is not interrupted and decimation is
ignored. When received, an =ARCHIVE message is returned with
info: 1=OK -1=notReady, -2=tooBig, -3=notInBuf, -4=fileOpenErr
When write is completed, an ARCHDONE message is returned.
If <start> <= 0, it is relative to the current position
If <duration> = -1, archive is continuous
=ARCHIVE info field as described above followed by three doubles
D:sample offset in archive file where timecode was evaluated
D:X-Midas timecode at beginning of sample (whole seconds)
D:X-Midas timecode at beginning of sample (fractional seconds)
ARCHSTOP Stops the current Archive and returns an ARCHDONE message