Help: ICE_ICELIB_PIC_TC

Returns the timecode for a given sample

Function 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.