fdelay_lib.h 5.66 KB
Newer Older
1 2 3 4 5 6 7 8 9
#ifndef __FD_LIB_H
#define __FD_LIB_H

#include <stdint.h>

/* Number of fractional bits in the timestamps/time definitions. Must be consistent with the HDL bitstream.  */
#define FDELAY_FRAC_BITS 12


10 11
/* fdelay_get_timing_status() return values: */

12
#define FDELAY_FREE_RUNNING	  0x10		/* local oscillator is free running */
13 14 15 16
#define FDELAY_WR_OFFLINE	  0x8		/* attached WR core is offline */
#define FDELAY_WR_READY 	  0x1		/* attached WR core is synchronized, we can sync the fine delay core anytime */
#define FDELAY_WR_SYNCING 	  0x2		/* local oscillator is being synchronized with WR clock */
#define FDELAY_WR_SYNCED   	  0x4		/* we are synced. */
17
#define FDELAY_WR_NOT_PRESENT	  0x20		/* No WR Core present */
18 19 20 21 22 23

/* fdelay_configure_sync() flags */

#define FDELAY_SYNC_LOCAL 	 0x1  	 	/* use local oscillator */
#define FDELAY_SYNC_WR	 	 0x2		/* use White Rabbit */

24 25 26 27
/* fdelay_init() flags */
#define FDELAY_RAW_READOUT 	0x1
#define FDELAY_PERFORM_LONG_TESTS 0x2

28 29 30
/* Hardware "handle" structure */
typedef struct fdelay_device
{
31
  /* Base address of the FD core (relative to the beginning of local writel/readl address spaces) */
32 33 34 35 36 37 38 39 40 41 42
  uint32_t base_addr; 

  /* Bus-specific readl/writel functions - so the same library can be used both with
     RawRabbit, VME and Etherbone backends */
  void (*writel)(void *priv, uint32_t data, uint32_t addr);
  uint32_t (*readl)(void *priv, uint32_t addr);
  
  void *priv_fd; /* pointer to Fine Delay library private data */
  void *priv_io; /* pointer to the I/O routines private data */
} fdelay_device_t;

43 44 45 46 47 48
typedef struct {
  int64_t utc, utc_sh;
  int32_t coarse, coarse_sh;
  int32_t start_offset;
  int32_t subcycle_offset;
  int32_t frac;
49
  uint32_t tsbcr;
50 51
} fdelay_raw_time_t;

52 53
typedef struct 
{
54
  int64_t utc; /* TAI seconds */ /* FIXME: replace all UTCs with TAIs or seconds for clarity */
55 56 57
  int32_t coarse; /* 125 MHz counter cycles */
  int32_t frac; /* Fractional part (<8ns) */
  uint16_t seq_id; /* Sequence ID to detect missed timestamps */
58 59

  fdelay_raw_time_t raw;
60 61 62 63 64 65 66 67
} fdelay_time_t;

/* 
--------------------
PUBLIC API 
--------------------
*/

68

69
fdelay_device_t *fdelay_create();
70

71 72 73 74 75
/* Creates a local instance of Fine Delay Core at address base_addr on the SPEC at bus/devfn. Returns 0 on success, negative on error. */
int spec_fdelay_create_bd(fdelay_device_t *dev, int bus, int dev_fn, uint32_t base);

/* A shortcut for test program, parsing the card base/location from command line args */
int spec_fdelay_create(fdelay_device_t *dev, int argc, char *argv[]);
76

77
/* Helper functions - converting FD timestamp format from/to plain picoseconds */
78 79 80
fdelay_time_t fdelay_from_picos(const uint64_t ps);
int64_t fdelay_to_picos(const fdelay_time_t t);

81 82 83
/* Enables/disables raw timestamp readout mode (debugging only) */
int fdelay_raw_readout(fdelay_device_t *dev, int raw_moide);

84
/* Initializes and calibrates the device. 0 = success, negative = error */
85
int fdelay_init(fdelay_device_t *dev, int init_flags);
86 87

/* Disables and releases the resources for a given FD Card */
88
int fdelay_release(fdelay_device_t *dev);
89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108

/* Returns an explaination of the last error occured on device dev (TBI) */
char *fdelay_strerror(fdelay_device_t *dev);

/* Sets the timing reference for the card (ref source). Currently there are two choices:
- FDELAY_SYNC_LOCAL 	- use local oscillator 
- FDELAY_SYNC_WR	- use White Rabbit */
int fdelay_set_timing_reference(fdelay_device_t *dev, int ref_source);

/* Polls the current status of the timing source. Returns a combination of 
   .... SYNCED flags. wait_mask can enable/disable waiting for a change of 
   a particular flag or set of flags. For example, calling

   fdelay_get_timing_status(dev, FDELAY_WR_SYNCED) will wait until a change of
   FDELAY_WR_SYNCED bit. */
int fdelay_get_timing_status(fdelay_device_t *dev, int wait_mask);

/* Configures the trigger input (TDC/Delay modes). enable enables the input,
   termination switches on/off the built-in 50 Ohm termination resistor */
   
109
int fdelay_configure_trigger(fdelay_device_t *dev, int enable, int termination);
110 111 112 113 114 115 116 117 118 119 120

/* Configures timestamp buffer capture: enable = TS buffer enabled, channel mask: 
   channels to time tag (bit 0 = TDC, bits 1..4 = outputs 1..4) */

int fdelay_configure_capture (fdelay_device_t *dev, int enable, int channel_mask);

/* Reads how_many timestamps from the buffer. Blocking */
/* TODO: non-blocking version? */
int fdelay_read (fdelay_device_t *dev, fdelay_time_t *timestamps, int how_many);


121
int fdelay_configure_output(fdelay_device_t *dev, int channel, int enable, int64_t delay_ps, int64_t width_ps, int64_t delta_ps, int rep_count)   ;
122 123 124 125 126 127 128 129 130 131
/* (delay mode only) Configures output(s) selected in channel_mask to work in delay mode. Delta_ps = spacing between
the rising edges of subsequent pulses. */
int fdelay_configure_delay (fdelay_device_t *dev, int channel_mask, int enable, int64_t delay_ps, int64_t width_ps, int64_t delta_ps, int repeat_count);

/* (pulse mode only)  Configures output(s) selected in channel_mask to produce pulse(s) starting at (start) with appropriate width/spacing/repeat_count */
int fdelay_configure_pulse_gen(fdelay_device_t *dev, int channel_mask, int enable, fdelay_time_t start, int64_t width_ps, int64_t delta_ps, int repeat_count);


/* (pulse mode only) Returns non-0 when all of the channels in channel mask have produced their programmed pulses */
int fdelay_outputs_triggered(fdelay_device_t *dev, int channel_mask, int blocking);
132

133 134 135 136
void fdelay_set_user_offset(fdelay_device_t *dev,int input, int64_t offset);

int fdelay_get_time(fdelay_device_t *dev, fdelay_time_t *t);
int fdelay_set_time(fdelay_device_t *dev, const fdelay_time_t t);
137

138
int fdelay_dmtd_calibration(fdelay_device_t *dev, double *offsets);
139
float fdelay_get_board_temperature(fdelay_device_t *dev);
140

141
#endif