Driver Documentation
psi_ms_daq.h
Go to the documentation of this file.
1 /*############################################################################
2 # Copyright (c) 2019 by Paul Scherrer Institute, Switzerland
3 # All rights reserved.
4 # Authors: Oliver Bruendler
5 ############################################################################*/
6 
7 #pragma once
8 
9 #ifdef __cplusplus
10 extern "C" {
11 #endif
12 
13 //*******************************************************************************
14 // Documentation
15 //*******************************************************************************
134 //*******************************************************************************
135 // Includes
136 //*******************************************************************************
137 #include <stdint.h>
138 #include <stdbool.h>
139 #include <string.h>
140 
141 //*******************************************************************************
142 // Constants
143 //*******************************************************************************
144 
146 //ACQCONF Registers - General
147 #define PSI_MS_DAQ_REG_GCFG 0x000
148 #define PSI_MS_DAQ_REG_GCFG_BIT_ENA (1 << 0)
149 #define PSI_MS_DAQ_REG_GCFG_BIT_IRQENA (1 << 8)
150 #define PSI_MS_DAQ_REG_GSTAT 0x004
151 #define PSI_MS_DAQ_REG_IRQVEC 0x010
152 #define PSI_MS_DAQ_REG_IRQENA 0x014
153 #define PSI_MS_DAQ_REG_STRENA 0x020
154 //ACQCONF Registers - Per Stream
155 #define PSI_MS_DAQ_REG_MAXLVL(n) (0x200+0x10*(n))
156 #define PSI_MS_DAQ_REG_POSTTRIG(n) (0x204+0x10*(n))
157 #define PSI_MS_DAQ_REG_MODE(n) (0x208+0x10*(n))
158 #define PSI_MS_DAQ_REG_MODE_LSB_RECM 0
159 #define PSI_MS_DAQ_REG_MODE_MSB_RECM 1
160 #define PSI_MS_DAQ_REG_MODE_BIT_ARM (1 << 8)
161 #define PSI_MS_DAQ_REG_MODE_BIT_REC (1 << 16)
162 #define PSI_MS_DAQ_REG_LASTWIN(n) (0x20C+0x10*(n))
163 //CTXMEM for Stream n
164 #define PSI_MS_DAQ_CTX_SCFG(n) (0x1000+0x20*(n))
165 #define PSI_MS_DAQ_CTX_SCFG_BIT_RINGBUF (1 << 0)
166 #define PSI_MS_DAQ_CTX_SCFG_BIT_OVERWRITE (1 << 8)
167 #define PSI_MS_DAQ_CTX_SCFG_LSB_WINCNT 16
168 #define PSI_MS_DAQ_CTX_SCFG_MSB_WINCNT 20
169 #define PSI_MS_DAQ_CTX_SCFG_LSB_WINCUR 24
170 #define PSI_MS_DAQ_CTX_SCFG_MSB_WINCUR 28
171 #define PSI_MS_DAQ_CTX_BUFSTART(n) (0x1004+0x20*(n))
172 #define PSI_MS_DAQ_CTX_WINSIZE(n) (0x1008+0x20*(n))
173 #define PSI_MS_DAQ_CTX_PTR(n) (0x100C+0x20*(n))
174 #define PSI_MS_DAQ_CTX_WINEND(n) (0x1010+0x20*(n))
175 //WNDW Window w for Stream n
176 #define PSI_MS_DAQ_WIN_WINCNT(n, w, so) (0x4000+(so)*(n)+0x10*(w))
177 #define PSI_MS_DAQ_WIN_WINCNT_LSB_CNT 0
178 #define PSI_MS_DAQ_WIN_WINCNT_MSB_CNT 30
179 #define PSI_MS_DAQ_WIN_WINCNT_BIT_ISTRIG (1 << 31)
180 #define PSI_MS_DAQ_WIN_LAST(n, w, so) (0x4004+(so)*(n)+0x10*(w))
181 #define PSI_MS_DAQ_WIN_TSLO(n, w, so) (0x4008+(so)*(n)+0x10*(w))
182 #define PSI_MS_DAQ_WIN_TSHI(n, w, so) (0x400C+(so)*(n)+0x10*(w))
183 
185 //*******************************************************************************
186 // Types
187 //*******************************************************************************
188 
189 //*** Handles ***
190 typedef void* PsiMsDaq_IpHandle;
191 typedef void* PsiMsDaq_StrHandle;
192 
193 //*** Functions for access to data of the IP core ***
201 typedef void PsiMsDaq_DataCopy_f(void* dst, void* src, size_t n);
202 
209 typedef void PsiMsDaq_RegWrite_f(const uint32_t addr, const uint32_t value);
210 
217 typedef uint32_t PsiMsDaq_RegRead_f(const uint32_t addr);
218 
224 typedef struct {
225  uint8_t winNr;
229 
239 typedef void PsiMsDaqn_WinIrq_f(PsiMsDaq_WinInfo_t winInfo, void* arg);
240 
250 typedef void PsiMsDaqn_StrIrq_f(PsiMsDaq_StrHandle strHandle, void* arg);
251 
255 typedef enum {
261 
265 typedef struct {
266  uint32_t postTrigSamples;
270  uint8_t winCnt;
271  uint32_t bufStartAddr;
272  uint32_t winSize;
273  uint16_t streamWidthBits;
275 
279 typedef struct {
284 
288 typedef enum {
302 
303 //*******************************************************************************
304 // IP Wide Functions
305 //*******************************************************************************
306 
316 PsiMsDaq_IpHandle PsiMsDaq_Init( const uint32_t baseAddr,
317  const uint8_t maxStreams,
318  const uint8_t maxWindows,
319  const PsiMsDaq_AccessFct_t* const accessFct_p);
320 
321 
331  const uint8_t streamNr,
332  PsiMsDaq_StrHandle* const strHndl_p);
333 
334 
336 
337 
338 
339 //*******************************************************************************
340 // Stream Related Functions
341 //*******************************************************************************
342 
353  PsiMsDaq_StrConfig_t* const config_p);
354 
363  const bool enable);
364 
379  PsiMsDaqn_WinIrq_f* irqCb,
380  void* arg_p);
381 
397  PsiMsDaqn_StrIrq_f* irqCb,
398  void* arg_p);
399 
408  const bool irqEna);
409 
417 
418 
427  uint32_t* const maxLvl_p);
428 
441  uint8_t* const freeWindows_p);
442 
455  uint8_t* const usedWindows_p);
456 
465  uint8_t* const windows_p);
466 
475  PsiMsDaq_IpHandle* ipHandle_p);
476 
485  uint8_t* strNr_p);
486 
487 
488 //*******************************************************************************
489 // Window Related Functions
490 //*******************************************************************************
491 
500  uint32_t* const noOfBytes_p);
501 
510  uint32_t* const noOfSamples_p);
511 
520  uint32_t* const preTrigSamples_p);
521 
530  uint64_t* const timestamp_p);
531 
545  const uint32_t preTrigSamples,
546  const uint32_t postTrigSamples, //including trigger
547  void* const buffer_p,
548  const size_t bufferSize);
549 
557 
566  uint32_t* const lastSplAddr_p);
567 
568 //*******************************************************************************
569 // Advanced Functions (only required for close control)
570 //*******************************************************************************
571 
580  bool* const isRecording_p);
581 
590  uint8_t* const currentWin_p);
591 
600  uint32_t* const currentPtr_p);
601 
610  uint8_t* const lastWrittenWin_p);
611 
624  const uint32_t addr,
625  const uint32_t value);
626 
636  const uint32_t addr,
637  uint32_t* const value_p);
638 
653  const uint32_t addr,
654  const uint8_t lsb,
655  const uint8_t msb,
656  const uint32_t value);
657 
669  const uint32_t addr,
670  const uint8_t lsb,
671  const uint8_t msb,
672  uint32_t* const value_p);
673 
687  const uint32_t addr,
688  const uint32_t mask,
689  const bool value);
690 
701  const uint32_t addr,
702  const uint32_t mask,
703  bool* const value_p);
704 
705 #ifdef __cplusplus
706 }
707 #endif
708 
709 
710 
711 
712 
Illegal steram width selected.
Definition: psi_ms_daq.h:291
PsiMsDaq_RetCode_t PsiMsDaq_StrWin_GetDataUnwrapped(PsiMsDaq_WinInfo_t winInfo, const uint32_t preTrigSamples, const uint32_t postTrigSamples, void *const buffer_p, const size_t bufferSize)
Get unwrapped copy of the data in a window.
PsiMsDaq_IpHandle ipHandle
Handle of the IP the window belongs to.
Definition: psi_ms_daq.h:226
PsiMsDaq_DataCopy_f * dataCopy
Data copy function to use.
Definition: psi_ms_daq.h:280
PsiMsDaq_RegWrite_f * regWrite
Register write function to use.
Definition: psi_ms_daq.h:281
void * PsiMsDaq_StrHandle
Handle to a specific stream of the driver.
Definition: psi_ms_daq.h:191
PsiMsDaq_RetCode_t PsiMsDaq_RegWrite(PsiMsDaq_IpHandle ipHandle, const uint32_t addr, const uint32_t value)
Write to a register.
uint32_t winSize
Size of the windows.
Definition: psi_ms_daq.h:272
PsiMsDaq_RecMode_t recMode
Recording mode.
Definition: psi_ms_daq.h:267
PsiMsDaq_RetCode_t PsiMsDaq_Str_SetIrqEnable(PsiMsDaq_StrHandle strHndl, const bool irqEna)
Enable/Disable IRQ for a stream.
PsiMsDaq_RetCode_t PsiMsDaq_Str_Arm(PsiMsDaq_StrHandle strHndl)
Arm the recorder for a given stream.
bool winAsRingbuf
Use individual windows as ring-buffers (true=ringbuffer mode, false=linear mode)
Definition: psi_ms_daq.h:268
Window definition struct, used for more compact passing of common parameters.
Definition: psi_ms_daq.h:224
PsiMsDaq_RetCode_t PsiMsDaq_Str_GetIpHandle(PsiMsDaq_StrHandle strHndl, PsiMsDaq_IpHandle *ipHandle_p)
Get the IP Handle of the IP a stream belongs to.
PsiMsDaq_RecMode_t
Recorder mode (see documentation)
Definition: psi_ms_daq.h:255
uint32_t bufStartAddr
Start address of the buffer for this stream.
Definition: psi_ms_daq.h:271
PsiMsDaq_RetCode_t PsiMsDaq_RegSetBit(PsiMsDaq_IpHandle ipHandle, const uint32_t addr, const uint32_t mask, const bool value)
Set a bit in a register (RMW)
PsiMsDaq_RetCode_t PsiMsDaq_Str_SetIrqCallbackStr(PsiMsDaq_StrHandle strHndl, PsiMsDaqn_StrIrq_f *irqCb, void *arg_p)
Set stream based interrupt callback function for a stream to be called whenever a new windows is reco...
void * PsiMsDaq_IpHandle
Handle to an instance of the driver for a complete IP.
Definition: psi_ms_daq.h:190
PsiMsDaq_RetCode_t PsiMsDaq_RegGetField(PsiMsDaq_IpHandle ipHandle, const uint32_t addr, const uint8_t lsb, const uint8_t msb, uint32_t *const value_p)
Read a field from a register.
PsiMsDaq_RetCode_t PsiMsDaq_Str_CurrentWin(PsiMsDaq_StrHandle strHndl, uint8_t *const currentWin_p)
Get the currently used recorder window.
More post trigger data requested than configured to be recorded.
Definition: psi_ms_daq.h:297
void PsiMsDaq_RegWrite_f(const uint32_t addr, const uint32_t value)
Write an IP-register.
Definition: psi_ms_daq.h:209
Illegal window number passed.
Definition: psi_ms_daq.h:294
uint32_t PsiMsDaq_RegRead_f(const uint32_t addr)
Read an IP-register.
Definition: psi_ms_daq.h:217
void PsiMsDaqn_WinIrq_f(PsiMsDaq_WinInfo_t winInfo, void *arg)
Interrupt callback function for the window based IRQ scheme. In this IRQ scheme, one callback functio...
Definition: psi_ms_daq.h:239
This function is only allowed if the stream is disbled but it was enabled.
Definition: psi_ms_daq.h:292
PsiMsDaq_RegRead_f * regRead
Register read function to use.
Definition: psi_ms_daq.h:282
void PsiMsDaq_DataCopy_f(void *dst, void *src, size_t n)
Copy used to copy data recorded to other memory locations in PsiMsDaq_StrWin_GetDataUnwrapped() ...
Definition: psi_ms_daq.h:201
Memory access functions struct.
Definition: psi_ms_daq.h:279
PsiMsDaq_RetCode_t PsiMsDaq_Str_GetLastWrittenWin(PsiMsDaq_StrHandle strHndl, uint8_t *const lastWrittenWin_p)
Get the number of the last window that was written to memory completely.
Only record pre-trigger after PsiMsDaq_Str_Arm() was called and stop recording after one trigger...
Definition: psi_ms_daq.h:258
PsiMsDaq_RetCode_t PsiMsDaq_Str_CurrentPtr(PsiMsDaq_StrHandle strHndl, uint32_t *const currentPtr_p)
Get the current write pointer of the recording logic.
PsiMsDaq_RetCode_t PsiMsDaq_StrWin_GetNoOfBytes(PsiMsDaq_WinInfo_t winInfo, uint32_t *const noOfBytes_p)
Get number of valid and unacknowledged bytes in a window.
No error, everything OK.
Definition: psi_ms_daq.h:289
PsiMsDaq_RetCode_t PsiMsDaq_StrWin_GetPreTrigSamples(PsiMsDaq_WinInfo_t winInfo, uint32_t *const preTrigSamples_p)
Get the number of pre-trigger samples in a window (post trigger samples are known by config) ...
PsiMsDaq_RetCode_t PsiMsDaq_RegGetBit(PsiMsDaq_IpHandle ipHandle, const uint32_t addr, const uint32_t mask, bool *const value_p)
Read a bit from a register.
Window size must be a multiple of the sample size.
Definition: psi_ms_daq.h:299
void PsiMsDaqn_StrIrq_f(PsiMsDaq_StrHandle strHandle, void *arg)
Interrupt callback function for the stream based IRQ scheme. In this IRQ scheme, one callback functio...
Definition: psi_ms_daq.h:250
Only one IRQ scheme (...Str or ...Win) can be used.
Definition: psi_ms_daq.h:300
More pre-trigger data requested than available.
Definition: psi_ms_daq.h:298
This window does not contain a trigger as required for this function call.
Definition: psi_ms_daq.h:295
PsiMsDaq_RetCode_t PsiMsDaq_Str_SetEnable(PsiMsDaq_StrHandle strHndl, const bool enable)
Enable/Disable a stream.
void PsiMsDaq_HandleIrq(PsiMsDaq_IpHandle inst_p)
PsiMsDaq_RetCode_t
Return codes.
Definition: psi_ms_daq.h:288
PsiMsDaq_RetCode_t PsiMsDaq_Str_Configure(PsiMsDaq_StrHandle strHndl, PsiMsDaq_StrConfig_t *const config_p)
Configure stream.
PsiMsDaq_RetCode_t PsiMsDaq_Str_GetStrNr(PsiMsDaq_StrHandle strHndl, uint8_t *strNr_p)
Get the stream number from a stream handle.
PsiMsDaq_RetCode_t PsiMsDaq_Str_GetMaxLvl(PsiMsDaq_StrHandle strHndl, uint32_t *const maxLvl_p)
Get maximum input buffer fill level.
PsiMsDaq_RetCode_t PsiMsDaq_StrWin_GetLastSplAddr(PsiMsDaq_WinInfo_t winInfo, uint32_t *const lastSplAddr_p)
Get the address of the last sample (not byte) written into a window.
Stream configuration struct.
Definition: psi_ms_daq.h:265
PsiMsDaq_RetCode_t PsiMsDaq_RegSetField(PsiMsDaq_IpHandle ipHandle, const uint32_t addr, const uint8_t lsb, const uint8_t msb, const uint32_t value)
Set a field in a register (RMW)
PsiMsDaq_RetCode_t PsiMsDaq_Str_GetFreeWindows(PsiMsDaq_StrHandle strHndl, uint8_t *const freeWindows_p)
Get the number of free windows.
PsiMsDaq_RetCode_t PsiMsDaq_GetStrHandle(PsiMsDaq_IpHandle ipHandle, const uint8_t streamNr, PsiMsDaq_StrHandle *const strHndl_p)
Get a handle to a specific stream number.
PsiMsDaq_StrHandle strHandle
Handle of the stream the window belongs to.
Definition: psi_ms_daq.h:227
PsiMsDaq_RetCode_t PsiMsDaq_Str_GetTotalWindows(PsiMsDaq_StrHandle strHndl, uint8_t *const windows_p)
Get the number of windows configured to be used for a given stream.
PsiMsDaq_RetCode_t PsiMsDaq_StrWin_GetNoOfSamples(PsiMsDaq_WinInfo_t winInfo, uint32_t *const noOfSamples_p)
Get number of valid and unacknowledged samples in a window.
PsiMsDaq_RetCode_t PsiMsDaq_Str_SetIrqCallbackWin(PsiMsDaq_StrHandle strHndl, PsiMsDaqn_WinIrq_f *irqCb, void *arg_p)
Set window based interrupt callback function for a stream to be called whenever a new windows is reco...
PsiMsDaq_RetCode_t PsiMsDaq_Str_GetUsedWindows(PsiMsDaq_StrHandle strHndl, uint8_t *const usedWindows_p)
Get the number of used (non-free) windows.
Illegal stream number passed.
Definition: psi_ms_daq.h:290
uint16_t streamWidthBits
Width od the stream in bits (must be a multiple of 8)
Definition: psi_ms_daq.h:273
PsiMsDaq_IpHandle PsiMsDaq_Init(const uint32_t baseAddr, const uint8_t maxStreams, const uint8_t maxWindows, const PsiMsDaq_AccessFct_t *const accessFct_p)
Initialize the psi_ms_daq IP-Core.
uint8_t winCnt
Number of windows to use.
Definition: psi_ms_daq.h:270
Continuously record pre-trigger data but only detect triggers after PsiMsDaq_Str_Arm() was called...
Definition: psi_ms_daq.h:257
Manaully control the recording by setting and clearing the arm bit.
Definition: psi_ms_daq.h:259
bool winOverwrite
If true, windows are overwritten even if they contain data. Usually set false here.
Definition: psi_ms_daq.h:269
The buffer passed is too small to contain all data.
Definition: psi_ms_daq.h:296
PsiMsDaq_RetCode_t PsiMsDaq_RegRead(PsiMsDaq_IpHandle ipHandle, const uint32_t addr, uint32_t *const value_p)
Read a register.
PsiMsDaq_RetCode_t PsiMsDaq_Str_IsRecording(PsiMsDaq_StrHandle strHndl, bool *const isRecording_p)
Check if the recorder of a given stream is currently recording data.
Continuous recording.
Definition: psi_ms_daq.h:256
Illegal window count passed.
Definition: psi_ms_daq.h:293
uint32_t postTrigSamples
Number of post trigger samples (incl. Trigger sample)
Definition: psi_ms_daq.h:266
uint8_t winNr
Window number.
Definition: psi_ms_daq.h:225
PsiMsDaq_RetCode_t PsiMsDaq_StrWin_MarkAsFree(PsiMsDaq_WinInfo_t winInfo)
Mark a window as free so it can receive new data. This function must be called after the window data ...
PsiMsDaq_RetCode_t PsiMsDaq_StrWin_GetTimestamp(PsiMsDaq_WinInfo_t winInfo, uint64_t *const timestamp_p)
Get the timestamp of a window.