199
199
#define PCILIB_IRQ_SOURCE_DEFAULT 0
200
200
#define PCILIB_MODEL_DETECT NULL
203
* Callback function called when pcilib wants to log a new message
204
* @param[in,out] arg - logging context provided with pcilib_set_logger() call
205
* @param[in] file - source file generating the message
206
* @param[in] line - source line generating the message
207
* @param[in] prio - the message priority (messages with priority bellow the currently set loglevel are already filtered)
208
* @param[in] msg - message or printf-style formating string
209
* @param[in] va - vairable parameters defined by formating string
203
211
typedef void (*pcilib_logger_t)(void *arg, const char *file, int line, pcilib_log_priority_t prio, const char *msg, va_list va);
206
214
* Callback function called when new data is read by DMA streaming function
207
* @ctx - DMA Engine context
209
* @bufsize - size of data in bytes
212
* <0 - error, stop streaming (the value is negative error code)
213
* 0 - stop streaming (PCILIB_STREAMING_STOP)
214
* 1 - wait DMA timeout and return gracefuly if no data (PCILIB_STREAMING_CONTINUE)
215
* 2 - wait the specified timeout and return gracefuly if no data (PCILIB_STREAMING_WAIT)
216
* 3 - check if more data is available without waiting, return gracefuly if not (PCILIB_STREAMING_CHECK)
217
* 5 - wait DMA timeout and fail if no data (PCILIB_STREAMING_REQ_FRAGMENT)
218
* 6 - wait the specified timeout and fail if no data (PCILIB_STREAMING_REQ_PACKET)
215
* @param[in,out] ctx - DMA Engine context
216
* @param[in] flags - DMA Flags
217
* @param[in] bufsize - size of data in bytes
218
* @param[in] buf - data
219
* @return - #pcilib_streaming_action_t instructing how the streaming should continue or a negative error code in the case of error
220
221
typedef int (*pcilib_dma_callback_t)(void *ctx, pcilib_dma_flags_t flags, size_t bufsize, void *buf);
221
typedef int (*pcilib_event_callback_t)(pcilib_event_id_t event_id, pcilib_event_info_t *info, void *user);
222
typedef int (*pcilib_event_rawdata_callback_t)(pcilib_event_id_t event_id, pcilib_event_info_t *info, pcilib_event_flags_t flags, size_t size, void *data, void *user);
224
* Callback function called when new event is generated by event engine
225
* @param[in] event_id - event id
226
* @param[in] info - event description (depending on event engine may provide additional fields on top of #pcilib_event_info_t)
227
* @param[in,out] user - User-specific data provided in pcilib_stream() call
228
* @return - #pcilib_streaming_action_t instructing how the streaming should continue or a negative error code in the case of error
230
typedef int (*pcilib_event_callback_t)(pcilib_event_id_t event_id, const pcilib_event_info_t *info, void *user);
233
* Callback function called when new portion of raw data is read by event engine
234
* @param[in] event_id - id of the event this data will be associated with if processing is successful
235
* @param[in] info - event description (depending on event engine may provide additional fields on top of #pcilib_event_info_t)
236
* @param[in] flags - may indicate if it is the last portion of data for current event
237
* @param[in] size - size of data in bytes
238
* @param[in,out] data - data (the callback may modify the data, but the size should be kept of course)
239
* @param[in,out] user - User-specific data provided in pcilib_stream() call
240
* @return - #pcilib_streaming_action_t instructing how the streaming should continue or a negative error code in the case of error
242
typedef int (*pcilib_event_rawdata_callback_t)(pcilib_event_id_t event_id, const pcilib_event_info_t *info, pcilib_event_flags_t flags, size_t size, void *data, void *user);
224
244
#ifdef __cplusplus
248
/***********************************************************************************************************//**
249
* \defgroup public_api_global Global Public API (logging, etc.)
250
* Global functions which does not require existing pcilib context
255
* Replaces default logging function.
256
* @param min_prio - messages with priority below \a min_prio will be ignored
257
* @param logger - configures a new logging function or restores the default one if NULL is passed
258
* @param arg - logging context, this parameter will be passed through to the \a logger
259
* @return - error code or 0 on success
230
261
int pcilib_set_logger(pcilib_log_priority_t min_prio, pcilib_logger_t logger, void *arg);
263
/** public_api_global
268
/***********************************************************************************************************//**
269
* \defgroup public_api Public API
270
* Base pcilib functions which does not belong to the specific APIs
275
* Initializes pcilib context, detects model configuration, and populates model-specific registers.
276
* Event and DMA engines will not be started automatically, but calls to pcilib_start() / pcilib_start_dma()
277
* are provided for this purpose. In the end, the context should be cleaned using pcilib_stop().
278
* @param[in] device - path to the device file [/dev/fpga0]
279
* @param[in] model - specifies the model of hardware, autodetected if NULL is passed
280
* @return - initialized context or NULL in the case of error
232
282
pcilib_t *pcilib_open(const char *device, const char *model);
285
* Destroy pcilib context and all memory associated with it. The function will stop event engine if necessary,
286
* but DMA engine stay running if it was already running before pcilib_open() was called
287
* @param[in,out] ctx - pcilib context
233
289
void pcilib_close(pcilib_t *ctx);
292
* Should reset the hardware and software in default state. It is implementation-specific, but is not actively
293
* used in existing implementations because the hardware is initialized from bash scripts which are often
294
* changed by Michele and his band. On the software side, it probably should reset all software registers
295
* to default value and may be additionaly re-start and clear DMA. However, this is not implemented yet.
296
* @param[in,out] ctx - pcilib context
297
* @return - error code or 0 on success
300
int pcilib_reset(pcilib_t *ctx);
307
/***********************************************************************************************************//**
308
* \defgroup public_api_pci Public PCI API (MMIO)
309
* API for manipulation with memory-mapped PCI BAR space
314
* Resolves the phisycal PCI address to a virtual address in the process address space.
315
* The required BAR will be mapped if necessary.
316
* @param[in,out] ctx - pcilib context
317
* @param[in] bar - specifies the BAR address belong to, use PCILIB_BAR_DETECT for autodetection
318
* @param[in] addr - specifies the physical address on the PCI bus or offset in the BAR if \a bar is specified
319
* @return - the virtual address in the process address space or NULL in case of error
321
char *pcilib_resolve_bar_address(pcilib_t *ctx, pcilib_bar_t bar, uintptr_t addr);
324
* Performs PIO read from the PCI BAR. The BAR will be automatically mapped and unmapped if necessary.
325
* @param[in,out] ctx - pcilib context
326
* @param[in] bar - the BAR to read, use PCILIB_BAR_DETECT to detect bar by the specified physical address
327
* @param[in] addr - absolute physical address to read or the offset in the specified bar
328
* @param[in] size - number of bytes to read
329
* @param[out] buf - the read data will be placed in this buffer
330
* @return - error code or 0 on success
332
int pcilib_read(pcilib_t *ctx, pcilib_bar_t bar, uintptr_t addr, size_t size, void *buf);
335
* Performs PIO write to the PCI BAR. The BAR will be automatically mapped and unmapped if necessary.
336
* @param[in,out] ctx - pcilib context
337
* @param[in] bar - the BAR to write, use PCILIB_BAR_DETECT to detect bar by the specified physical address
338
* @param[in] addr - absolute physical address to write or the offset in the specified bar
339
* @param[in] size - number of bytes to write
340
* @param[out] buf - the pointer to the data to be written
341
* @return - error code or 0 on success
343
int pcilib_write(pcilib_t *ctx, pcilib_bar_t bar, uintptr_t addr, size_t size, void *buf);
346
* Performs PIO read from the PCI BAR. The specified address is treated as FIFO and will be read
347
* \a n times. The BAR will be automatically mapped and unmapped if necessary.
348
* @param[in,out] ctx - pcilib context
349
* @param[in] bar - the BAR to read, use PCILIB_BAR_DETECT to detect bar by the specified physical address
350
* @param[in] addr - absolute physical address to read or the offset in the specified bar
351
* @param[in] access - the size of FIFO register in bytes (i.e. if `access = 4`, the 32-bit reads from FIFO will be performed)
352
* @param[in] n - specifies how many times the data should be read from FIFO
353
* @param[out] buf - the data will be placed in this buffer which should be at least `n * access` bytes long
354
* @return - error code or 0 on success
356
int pcilib_read_fifo(pcilib_t *ctx, pcilib_bar_t bar, uintptr_t addr, uint8_t access, size_t n, void *buf);
359
* Performs PIO write to the PCI BAR. The specified address is treated as FIFO and will be written
360
* \a n times. The BAR will be automatically mapped and unmapped if necessary.
361
* @param[in,out] ctx - pcilib context
362
* @param[in] bar - the BAR to write, use PCILIB_BAR_DETECT to detect bar by the specified physical address
363
* @param[in] addr - absolute physical address to write or the offset in the specified bar
364
* @param[in] access - the size of FIFO register in bytes (i.e. if `access = 4`, the 32-bit writes to FIFO will be performed)
365
* @param[in] n - specifies how many times the data should be written to FIFO
366
* @param[out] buf - buffer to write which should be at least `n * access` bytes long
367
* @return - error code or 0 on success
369
int pcilib_write_fifo(pcilib_t *ctx, pcilib_bar_t bar, uintptr_t addr, uint8_t access, size_t n, void *buf);
376
/***********************************************************************************************************//**
377
* \defgroup public_api_register Public Register API
378
* API for register manipulations
383
* Returns the list of registers provided by the hardware model.
384
* @param[in,out] ctx - pcilib context
385
* @param[in] bank - if set, only register within the specified bank will be returned
386
* @param[in] flags - currently ignored
387
* @return - the list of the register which should be cleaned with pcilib_free_register_info() or NULL in the case of error
389
pcilib_register_info_t *pcilib_get_register_list(pcilib_t *ctx, const char *bank, pcilib_list_flags_t flags);
392
* Returns the information about the specified register
393
* @param[in,out] ctx - pcilib context
394
* @param[in] bank - indicates the bank where to look for register, autodetected if NULL is passed
395
* @param[in] reg - the name of the register
396
* @param[in] flags - currently ignored
397
* @return - information about the specified register which should be cleaned with pcilib_free_register_info() or NULL in the case of error
399
pcilib_register_info_t *pcilib_get_register_info(pcilib_t *ctx, const char *bank, const char *reg, pcilib_list_flags_t flags);
402
* Cleans up the memory occupied by register list returned from the pcilib_get_register_list() and pcilib_get_register_info() calls
403
* @param[in,out] ctx - pcilib context
404
* @param[in,out] info - buffer to clean
406
void pcilib_free_register_info(pcilib_t *ctx, pcilib_register_info_t *info);
409
* Finds register id corresponding to the specified bank and register names. It is faster
410
* to access registers by id instead of names. Therefore, in long running applications it
411
* is preferred to resolve names of all required registers during initialization and access
412
* them using ids only.
413
* @param[in,out] ctx - pcilib context
414
* @param[in] bank - should specify the bank name if register with the same name may occur in multiple banks, NULL otherwise
415
* @param[in] reg - the name of the register
416
* @return - register id or PCILIB_REGISTER_INVALID if register is not found
418
pcilib_register_t pcilib_find_register(pcilib_t *ctx, const char *bank, const char *reg);
421
* Extracts additional information about the specified register. The additional information
422
* is model-specific and are provided as extra XML attributes in XML-described registers.
423
* The available attributes are only restricted by used XSD schema.
424
* @param[in,out] ctx - pcilib context
425
* @param[in] reg - register id
426
* @param[in] attr - requested attribute name
427
* @param[in,out] val - the value of attribute is returned here (see \ref public_api_value),
428
* pcilib_clean_value() will be executed if \a val contains data. Therefore it should be always initialized to 0 before first use
429
* @return - error code or 0 on success
431
int pcilib_get_register_attr_by_id(pcilib_t *ctx, pcilib_register_t reg, const char *attr, pcilib_value_t *val);
434
* Extracts additional information about the specified register.
435
* Equivalent to the pcilib_get_register_attr_by_id(), but first resolves register id using the specified bank and name.
436
* @param[in,out] ctx - pcilib context
437
* @param[in] bank - should specify the bank name if register with the same name may occur in multiple banks, NULL otherwise
438
* @param[in] regname - register name
439
* @param[in] attr - requested attribute name
440
* @param[in,out] val - the value of attribute is returned here (see \ref public_api_value),
441
* pcilib_clean_value() will be executed if \a val contains data. Therefore it should be always initialized to 0 before first use
442
* @return - error code or 0 on success
444
int pcilib_get_register_attr(pcilib_t *ctx, const char *bank, const char *regname, const char *attr, pcilib_value_t *val);
447
* Reads one or multiple sequential registers from the specified register bank. This function may provide access
448
* to the undefined registers in the bank. In other cases, the pcilib_read_register() / pcilib_read_register_by_id()
449
* calls are preferred.
450
* @param[in,out] ctx - pcilib context
451
* @param[in] bank - the bank to read (should be specified, no autodetection)
452
* @param[in] addr - the register address within the bank, addresses are counted in bytes not registers (i.e. it is offset in bytes from the start of register bank)
453
* @param[in] n - number of registers to read; i.e. `n * register_size` bytes will be read, where \a register_size is defined in the bank configuration (see #pcilib_register_bank_description_t)
454
* @param[out] buf - the buffer of `n * register_size` bytes long where the data will be stored
455
* @return - error code or 0 on success
457
int pcilib_read_register_space(pcilib_t *ctx, const char *bank, pcilib_register_addr_t addr, size_t n, pcilib_register_value_t *buf);
460
* Writes one or multiple sequential registers from the specified register bank. This function may provide access
461
* to the undefined registers in the bank. In other cases, the pcilib_write_register() / pcilib_write_register_by_id()
462
* calls are preferred.
463
* @param[in,out] ctx - pcilib context
464
* @param[in] bank - the bank to write (should be specified, no autodetection)
465
* @param[in] addr - the register address within the bank, addresses are counted in bytes not registers (i.e. it is offset in bytes from the start of register bank)
466
* @param[in] n - number of registers to write; i.e. `n * register_size` bytes will be written, where \a register_size is defined in the bank configuration (see #pcilib_register_bank_description_t)
467
* @param[in] buf - the buffer of `n * register_size` bytes long with the data
468
* @return - error code or 0 on success
470
int pcilib_write_register_space(pcilib_t *ctx, const char *bank, pcilib_register_addr_t addr, size_t n, const pcilib_register_value_t *buf);
473
* Reads the specified register.
474
* @param[in,out] ctx - pcilib context
475
* @param[in] reg - register id
476
* @param[out] value - the register value is returned here
477
* @return - error code or 0 on success
479
int pcilib_read_register_by_id(pcilib_t *ctx, pcilib_register_t reg, pcilib_register_value_t *value);
482
* Writes to the specified register.
483
* @param[in,out] ctx - pcilib context
484
* @param[in] reg - register id
485
* @param[in] value - the register value to write
486
* @return - error code or 0 on success
488
int pcilib_write_register_by_id(pcilib_t *ctx, pcilib_register_t reg, pcilib_register_value_t value);
491
* Reads the specified register.
492
* Equivalent to the pcilib_read_register_by_id(), but first resolves register id using the specified bank and name.
493
* @param[in,out] ctx - pcilib context
494
* @param[in] bank - should specify the bank name if register with the same name may occur in multiple banks, NULL otherwise
495
* @param[in] regname - the name of the register
496
* @param[out] value - the register value is returned here
497
* @return - error code or 0 on success
499
int pcilib_read_register(pcilib_t *ctx, const char *bank, const char *regname, pcilib_register_value_t *value);
502
* Writes to the specified register.
503
* Equivalent to the pcilib_write_register_by_id(), but first resolves register id using the specified bank and name.
504
* @param[in,out] ctx - pcilib context
505
* @param[in] bank - should specify the bank name if register with the same name may occur in multiple banks, NULL otherwise
506
* @param[in] regname - the name of the register
507
* @param[in] value - the register value to write
508
* @return - error code or 0 on success
510
int pcilib_write_register(pcilib_t *ctx, const char *bank, const char *regname, pcilib_register_value_t value);
514
* Reads a view of the specified register. The views allow to convert values to standard units
515
* or get self-explanatory names associated with the values (enums).
516
* @param[in,out] ctx - pcilib context
517
* @param[in] reg - register id
518
* @param[in] view - specifies the name of the view associated with register or desired units
519
* @param[out] value - the register value is returned here (see \ref public_api_value),
520
* pcilib_clean_value() will be executed if \a val contains data. Therefore it should be always initialized to 0 before first use.
521
* @return - error code or 0 on success
523
int pcilib_read_register_view_by_id(pcilib_t *ctx, pcilib_register_t reg, const char *view, pcilib_value_t *value);
526
* Writes the specified register using value represented in the specified view. The views allow to convert values from standard units
527
* or self-explanatory names associated with the values (enums).
528
* @param[in,out] ctx - pcilib context
529
* @param[in] reg - register id
530
* @param[in] view - specifies the name of the view associated with register or the used units
531
* @param[in] value - the register value in the specified view (see \ref public_api_value)
532
* @return - error code or 0 on success
534
int pcilib_write_register_view_by_id(pcilib_t *ctx, pcilib_register_t reg, const char *view, const pcilib_value_t *value);
537
* Reads a view of the specified register. The views allow to convert values to standard units
538
* or get self-explanatory names associated with the values (enums).
539
* Equivalent to the pcilib_read_register_view_by_id(), but first resolves register id using the specified bank and name.
540
* @param[in,out] ctx - pcilib context
541
* @param[in] bank - should specify the bank name if register with the same name may occur in multiple banks, NULL otherwise
542
* @param[in] regname - the name of the register
543
* @param[in] view - specifies the name of the view associated with register or desired units
544
* @param[out] value - the register value is returned here (see \ref public_api_value),
545
* pcilib_clean_value() will be executed if \a val contains data. Therefore it should be always initialized to 0 before first use
546
* @return - error code or 0 on success
548
int pcilib_read_register_view(pcilib_t *ctx, const char *bank, const char *regname, const char *view, pcilib_value_t *value);
552
* Writes the specified register using value represented in the specified view. The views allow to convert values from standard units
553
* or self-explanatory names associated with the values (enums).
554
* Equivalent to the pcilib_write_register_view_by_id(), but first resolves register id using the specified bank and name.
555
* @param[in,out] ctx - pcilib context
556
* @param[in] bank - should specify the bank name if register with the same name may occur in multiple banks, NULL otherwise
557
* @param[in] regname - the name of the register
558
* @param[in] view - specifies the name of the view associated with register or the used units
559
* @param[in] value - the register value in the specified view (see \ref public_api_value)
560
* @return - error code or 0 on success
562
int pcilib_write_register_view(pcilib_t *ctx, const char *bank, const char *regname, const char *view, const pcilib_value_t *value);
564
/** public_api_register
568
/***********************************************************************************************************//**
569
* \defgroup public_api_property Public Property API
570
* Properties is another abstraction on top of registers allowing arbitrary data types and computed registers
575
* Returns the list of properties available under the specified path
576
* @param[in,out] ctx - pcilib context
577
* @param[in] branch - path or NULL to return the top-level properties
578
* @param[in] flags - not used at the moment
579
* @return - the list of the properties which should be cleaned with pcilib_free_property_info() or NULL in the case of error
235
581
pcilib_property_info_t *pcilib_get_property_list(pcilib_t *ctx, const char *branch, pcilib_list_flags_t flags);
584
* Cleans up the memory occupied by property list returned from the pcilib_get_property_list() call
585
* @param[in,out] ctx - pcilib context
586
* @param[in,out] info - buffer to clean
236
588
void pcilib_free_property_info(pcilib_t *ctx, pcilib_property_info_t *info);
237
pcilib_register_info_t *pcilib_get_register_list(pcilib_t *ctx, const char *bank, pcilib_list_flags_t flags);
238
pcilib_register_info_t *pcilib_get_register_info(pcilib_t *ctx, const char *req_bank_name, const char *req_reg_name, pcilib_list_flags_t flags);
239
void pcilib_free_register_info(pcilib_t *ctx, pcilib_register_info_t *info);
591
* Extracts additional information about the specified register.
592
* Equivalent to the pcilib_get_register_attr_by_id(), but first resolves register id using the specified bank and name.
593
* @param[in,out] ctx - pcilib context
594
* @param[in] prop - property name (full name including path)
595
* @param[in] attr - requested attribute name
596
* @param[in,out] val - the value of attribute is returned here (see \ref public_api_value),
597
* pcilib_clean_value() will be executed if \a val contains data. Therefore it should be always initialized to 0 before first use
598
* @return - error code or 0 on success
600
int pcilib_get_property_attr(pcilib_t *ctx, const char *prop, const char *attr, pcilib_value_t *val);
603
* Reads / computes the property value.
604
* @param[in,out] ctx - pcilib context
605
* @param[in] prop - property name (full name including path)
606
* @param[out] val - the register value is returned here (see \ref public_api_value),
607
* pcilib_clean_value() will be executed if \a val contains data. Therefore it should be always initialized to 0 before first use
608
* @return - error code or 0 on success
610
int pcilib_get_property(pcilib_t *ctx, const char *prop, pcilib_value_t *val);
613
* Writes the property value or executes the code associated with property
614
* @param[in,out] ctx - pcilib context
615
* @param[in] prop - property name (full name including path)
616
* @param[out] val - the property value (see \ref public_api_value),
617
* @return - error code or 0 on success
619
int pcilib_set_property(pcilib_t *ctx, const char *prop, const pcilib_value_t *val);
621
/** public_api_property
625
/***********************************************************************************************************//**
626
* \defgroup public_api_dma Public DMA API
627
* High speed interface for reading and writting unstructured data
632
* This function resolves the ID of DMA engine from its address and direction.
633
* It is a bit confusing, but addresses should be able to represent bi-directional
634
* DMA engines. Unfortunatelly, implementation often is limited to uni-directional
635
* engines. In this case, two DMA engines with different IDs can be virtually
636
* combined in a DMA engine with the uniq address. This will allow user to specify
637
* the same engine address in all types of accesses and we will resolve the appropriate
638
* engine ID depending on the requested direction.
639
* @param[in,out] ctx - pcilib context
640
* @param[in] direction - DMA direction (to/from device)
641
* @param[in] dma - address of DMA engine
642
* @return - ID of DMA engine or PCILIB_DMA_INVALID if the specified engine does not exist
644
pcilib_dma_engine_t pcilib_find_dma_by_addr(pcilib_t *ctx, pcilib_dma_direction_t direction, pcilib_dma_engine_addr_t dma);
647
* Starts DMA engine. This call will allocate DMA buffers and pass their bus addresses to the hardware.
648
* - During the call, the C2S engine may start writting data. The written buffers are marked as
649
* ready and can be read-out using pcilib_stream_dma() and pcilib_read_dma() calls. If no empty
650
* buffers left, the C2S DMA engine will stall until some buffers are read out.
651
* - The S2C engine waits until the data is pushed with pcilib_push_data() call
653
* After pcilib_start_dma() call, the pcilib_stop_dma() function should be necessarily called. However,
654
* it will clean up the process memory, but only in some cases actually stop the DMA engine.
655
* This depends on \a flags passed to both pcilib_start_dma() and pcilib_stop_dma() calls.
656
* if PCILIB_DMA_FLAG_PERSISTENT flag is passed to the pcilib_start_dma(), the DMA engine
657
* will remain running unless the same flag is also passed to the pcilib_stop_dma() call.
658
* The allocated DMA buffers will stay intact and the hardware may continue reading / writting
659
* data while there is space/data left. However, the other functions of DMA API should not
660
* be called after pcilib_stop_dma() until new pcilib_start_dma() call is issued.
662
* The process- and thread-safety is implementation depedent. However, currently the process-
663
* safety is ensured while accessing the kernel memory (todo: this may get complicated if we
664
* provide a way to perform DMA directly to the user-supplied pages).
665
* The thread-safety is not provided by currently implemented DMA engines. The DMA functions
666
* may be called from multiple threads, but it is user responsibility to ensure that only a
667
* single DMA-related call is running. On other hand, the DMA and register APIs may be used
670
* @param[in,out] ctx - pcilib context
671
* @param[in] dma - ID of DMA engine, the ID should first be resolved using pcilib_find_dma_by_addr()
672
* @param[in] flags - PCILIB_DMA_FLAG_PERSISTENT indicates that engine should be kept running after pcilib_stop_dma() call
673
* @return - error code or 0 on success
242
675
int pcilib_start_dma(pcilib_t *ctx, pcilib_dma_engine_t dma, pcilib_dma_flags_t flags);
678
* Stops DMA engine or just cleans up the process-specific memory buffers (see
679
* pcilib_start_dma() for details). No DMA API calls allowed after this point
680
* until pcilib_start_dma() is called anew.
682
* @param[in,out] ctx - pcilib context
683
* @param[in] dma - ID of DMA engine, the ID should first be resolved using pcilib_find_dma_by_addr()
684
* @param[in] flags - PCILIB_DMA_FLAG_PERSISTENT indicates that engine should be actually stopped independent of the flags passed to pcilib_start_dma() call
685
* @return - error code or 0 on success
243
687
int pcilib_stop_dma(pcilib_t *ctx, pcilib_dma_engine_t dma, pcilib_dma_flags_t flags);
245
// Interrupt API is preliminary and can be significantly changed in future
690
* Tries to drop all pending data in the DMA channel. It will drop not only data currently in the DMA buffers,
691
* but will allow hardware to write more and will drop the newly written data as well. The standard DMA timeout
692
* is allowed to receive new data. If hardware continuously writes data, after #PCILIB_DMA_SKIP_TIMEOUT
693
* microseconds the function will exit with #PCILIB_ERROR_TIMEOUT error.
695
* @param[in,out] ctx - pcilib context
696
* @param[in] dma - ID of DMA engine, the ID should first be resolved using pcilib_find_dma_by_addr()
697
* @return - error code or 0 on success
699
int pcilib_skip_dma(pcilib_t *ctx, pcilib_dma_engine_t dma);
702
* Reads data from DMA buffers and pass it to the specified callback function. The return code of the callback
703
* function determines if streaming should continue and how much to wait for next data to arrive before
704
* triggering timeout.
705
* The function is process- and thread-safe. The PCILIB_ERROR_BUSY will be returned immediately if DMA is used
706
* by another thread or process.
708
* The function waits the specified \a timeout microseconds for the first data. Afterwards, the waiting time
709
* for next portion of data depends on the last return code \a (ret) from callback function.
710
* If `ret & PCILIB_STREAMING_TIMEOUT_MASK` is
711
* - PCILIB_STREAMING_STOP - the streaming stops
712
* - PCILIB_STREAMING_CONTINUE - the standard DMA timeout will be used to wait for a new data
713
* - PCILIB_STREAMING_WAIT - the timeout specified in the function arguments will be used to wait for a new data
714
* - PCILIB_STREAMING_CHECK - the function will return if new data is not available immediately
715
* The function return code depends on the return code from the callback as well. If no data received within the specified
716
* timeout and no callback is called, the PCILIB_ERROR_TIMEOUT is returned. Otherwise, success is returned unless
717
* PCILIB_STREAMING_FAIL flag has been set in the callback return code before the timeout was triggered.
719
* @param[in,out] ctx - pcilib context
720
* @param[in] dma - ID of DMA engine, the ID should first be resolved using pcilib_find_dma_by_addr()
721
* @param[in] addr - instructs DMA to start reading at the specified address (not supported by existing DMA engines)
722
* @param[in] size - instructs DMA to read only \a size bytes (not supported by existing DMA engines)
723
* @param[in] flags - not used by existing DMA engines
724
* @param[in] timeout - specifies number of microseconds to wait before reporting timeout, special values #PCILIB_TIMEOUT_IMMEDIATE and #PCILIB_TIMEOUT_INFINITE are supported.
725
* @param[in] cb - callback function to call
726
* @param[in,out] cbattr - passed through as the first parameter of callback function
727
* @return - error code or 0 on success
729
int pcilib_stream_dma(pcilib_t *ctx, pcilib_dma_engine_t dma, uintptr_t addr, size_t size, pcilib_dma_flags_t flags, pcilib_timeout_t timeout, pcilib_dma_callback_t cb, void *cbattr);
732
* Reads data from DMA until timeout is hit, a full DMA packet is read, or the specified number of bytes are read.
733
* The function is process- and thread-safe. The #PCILIB_ERROR_BUSY will be returned immediately if DMA is used
734
* by another thread or process.
736
* We can't read arbitrary number of bytes from DMA. A full DMA packet is always read. The DMA packet is not equal
737
* to DMA buffer, but may consist of multiple buffers and the size may vary during run time. This may cause problems
738
* if not treated properly. While the number of actually read bytes is bellow the specified size, the function may
739
* continue to read the data. But as the new packet is started, it should fit completely in the provided buffer space
740
* or PCILIB_ERROR_TOOBIG error will be returned. Therefore, it is a good practice to read only a single packet at
741
* once and provide buffer capable to store the larges possible packet.
743
* Unless #PCILIB_DMA_FLAG_MULTIPACKET flag is specified, the function will stop after the first full packet is read.
744
* Otherwise, the reading will continue until all `size` bytes are read or timeout is hit. The stanard DMA timeout
745
* should be met while reading DMA buffers belonging to the same packet. Otherwise, PCILIB_ERROR_TIMEOUT is returned
746
* and number of bytes read so far is returned in the `rdsize`.
747
* If #PCILIB_DMA_FLAG_WAIT flag is specified, the number of microseconds specified in the `timeout` parameter are
748
* allowed for a new packet to come. If no new data arrived in the specified timeout, the function returns successfuly
749
* and number of read bytes is returned in the `rdsize`.
751
* We can't put the read data back into the DMA. Therefore, even in the case of error some data may be returned. The
752
* number of actually read bytes is always reported in `rdsize` and the specified amount of data is always written
753
* to the provided buffer.
755
* @param[in,out] ctx - pcilib context
756
* @param[in] dma - ID of DMA engine, the ID should first be resolved using pcilib_find_dma_by_addr()
757
* @param[in] addr - instructs DMA to start reading at the specified address (not supported by existing DMA engines)
758
* @param[in] size - specifies how many bytes should be read
759
* @param[in] flags - Various flags controlling the function behavior
760
* - #PCILIB_DMA_FLAG_MULTIPACKET indicates that multiple DMA packets will be read (not recommended, use pcilib_stream_dma() in this case)
761
* - #PCILIB_DMA_FLAG_WAIT indicates that we need to wait the specified timeout between consequitive DMA packets (default DMA timeout is used otherwise)
762
* @param[in] timeout - specifies number of microseconds to wait before reporting timeout, special values #PCILIB_TIMEOUT_IMMEDIATE and #PCILIB_TIMEOUT_INFINITE are supported.
763
* This parameter specifies timeout between consequtive DMA packets, the standard DMA timeout is expected between buffers belonging to the same DMA packet.
764
* @param[out] buf - the buffer of \a size bytes long to store the data
765
* @param[out] rdsize - number of bytes which were actually read. The correct value will be reported in both case if function has finished successfully or if error has happened.
766
* @return - error code or 0 on success. In both cases some data may be returned in the buffer, check `rdsize`.
768
int pcilib_read_dma_custom(pcilib_t *ctx, pcilib_dma_engine_t dma, uintptr_t addr, size_t size, pcilib_dma_flags_t flags, pcilib_timeout_t timeout, void *buf, size_t *rdsize);
771
* Reads data from DMA until timeout is hit, a full DMA packet is read, or the specified number of bytes are read.
772
* Please, check detailed explanation when reading is stopped in the description of pcilib_read_dma_custom().
773
* The function is process- and thread-safe. The #PCILIB_ERROR_BUSY will be returned immediately if DMA is used
774
* by another thread or process.
776
* The function actually executes the pcilib_read_dma_custom() without special flags and with default DMA timeout
778
* @param[in,out] ctx - pcilib context
779
* @param[in] dma - ID of DMA engine, the ID should first be resolved using pcilib_find_dma_by_addr()
780
* @param[in] addr - instructs DMA to start reading at the specified address (not supported by existing DMA engines)
781
* @param[in] size - specifies how many bytes should be read
782
* @param[out] buf - the buffer of \a size bytes long to store the data
783
* @param[out] rdsize - number of bytes which were actually read. The correct value will be reported in both case if function has finished successfully or if error has happened.
784
* @return - error code or 0 on success. In both cases some data may be returned in the buffer, check `rdsize`.
786
int pcilib_read_dma(pcilib_t *ctx, pcilib_dma_engine_t dma, uintptr_t addr, size_t size, void *buf, size_t *rdsize);
789
* Pushes new data to the DMA engine. The actual behavior is implementation dependent. The successful exit does not mean
790
* what all data have reached hardware, but only guarantees that it is stored in DMA buffers and the hardware is instructed
791
* to start reading buffers. The function may return #PCILIB_ERROR_TIMEOUT is all DMA buffers are occupied and no buffers is
792
* read by the hardware within the specified timeout. Even if an error is returned, part of the data may be already send to
793
* DMA and can't be revoked back. Number of actually written bytes is always returned in the `wrsize`.
795
* The function is process- and thread-safe. The #PCILIB_ERROR_BUSY will be returned immediately if DMA is used
796
* by another thread or process.
798
* @param[in,out] ctx - pcilib context
799
* @param[in] dma - ID of DMA engine, the ID should first be resolved using pcilib_find_dma_by_addr()
800
* @param[in] addr - instructs DMA to start writting at the specified address (not supported by existing DMA engines)
801
* @param[in] size - specifies how many bytes should be written
802
* @param[in] flags - Various flags controlling the function behavior
803
* - #PCILIB_DMA_FLAG_EOP indicates that this is the last data in the DMA packet
804
* - #PCILIB_DMA_FLAG_WAIT requires function to block until the data actually reach hardware. #PCILIB_ERROR_TIMEOUT may be returned if it takes longer when the specified timeout.
805
* @param[in] timeout - specifies number of microseconds to wait before reporting timeout, special values #PCILIB_TIMEOUT_IMMEDIATE and #PCILIB_TIMEOUT_INFINITE are supported.
806
* @param[out] buf - the buffer with the data
807
* @param[out] wrsize - number of bytes which were actually written. The correct value will be reported in both case if function has finished successfully or if error has happened.
808
* @return - error code or 0 on success. In both cases some data may be written to the DMA, check `wrsize`.
810
int pcilib_push_dma(pcilib_t *ctx, pcilib_dma_engine_t dma, uintptr_t addr, size_t size, pcilib_dma_flags_t flags, pcilib_timeout_t timeout, void *buf, size_t *wrsize);
814
* Pushes new data to the DMA engine and blocks until hardware gets it all. Even if an error has occured, a
815
* part of the data may be already had send to DMA and can't be revoked back. Number of actually written bytes
816
* is always returned in the `wrsize`.
818
* The function is process- and thread-safe. The #PCILIB_ERROR_BUSY will be returned immediately if DMA is used
819
* by another thread or process.
821
* The function actually executes the pcilib_push_dma() with #PCILIB_DMA_FLAG_EOP and #PCILIB_DMA_FLAG_WAIT flags set and
822
* the default DMA timeout.
824
* @param[in,out] ctx - pcilib context
825
* @param[in] dma - ID of DMA engine, the ID should first be resolved using pcilib_find_dma_by_addr()
826
* @param[in] addr - instructs DMA to start writting at the specified address (not supported by existing DMA engines)
827
* @param[in] size - specifies how many bytes should be written
828
* @param[out] buf - the buffer with the data
829
* @param[out] wrsize - number of bytes which were actually written. The correct value will be reported in both case if function has finished successfully or if error has happened.
830
* @return - error code or 0 on success. In both cases some data may be written to the DMA, check `wrsize`.
832
int pcilib_write_dma(pcilib_t *ctx, pcilib_dma_engine_t dma, uintptr_t addr, size_t size, void *buf, size_t *wrsize);
835
* Benchmarks the DMA implementation. The reported performance may be significantly affected by several environmental variables.
836
* - PCILIB_BENCHMARK_HARDWARE - if set will not copy the data out, but immediately drop as it lended in DMA buffers. This allows to remove influence of memcpy performance.
837
* - PCILIB_BENCHMARK_STREAMING - if set will not re-initialized the DMA on each iteration. If DMA is properly implemented this should have only marginal influence on performance
839
* The function is process- and thread-safe. The #PCILIB_ERROR_BUSY will be returned immediately if DMA is used
840
* by another thread or process.
842
* @param[in,out] ctx - pcilib context
843
* @param[in] dma - Address of DMA engine
844
* @param[in] addr - Benchmark will read and write data at the specified address (ignored by existing DMA engines)
845
* @param[in] size - specifies how many bytes should be read and written at each iteration
846
* @param[in] iterations - number of iterations to execute
847
* @param[in] direction - Specifies if DMA reading or writting should be benchmarked, bi-directional benchmark is possible as well
848
* @return - bandwidth in MiB/s (Mebibytes per second)
850
double pcilib_benchmark_dma(pcilib_t *ctx, pcilib_dma_engine_addr_t dma, uintptr_t addr, size_t size, size_t iterations, pcilib_dma_direction_t direction);
856
/***********************************************************************************************************//**
857
* \defgroup public_api_irq Public IRQ API
858
* This is actually part of DMA API. IRQ handling is currently provided by DMA engine.
859
* However, the IRQs are barely used so far. Therefore, the API can be significantly changed when confronted with harsh reallity.
246
863
int pcilib_enable_irq(pcilib_t *ctx, pcilib_irq_type_t irq_type, pcilib_dma_flags_t flags);
247
int pcilib_acknowledge_irq(pcilib_t *ctx, pcilib_irq_type_t irq_type, pcilib_irq_source_t irq_source);
248
864
int pcilib_disable_irq(pcilib_t *ctx, pcilib_dma_flags_t flags);
250
865
int pcilib_wait_irq(pcilib_t *ctx, pcilib_irq_hw_source_t source, pcilib_timeout_t timeout, size_t *count);
866
int pcilib_acknowledge_irq(pcilib_t *ctx, pcilib_irq_type_t irq_type, pcilib_irq_source_t irq_source);
251
867
int pcilib_clear_irq(pcilib_t *ctx, pcilib_irq_hw_source_t source);
253
void *pcilib_map_bar(pcilib_t *ctx, pcilib_bar_t bar);
254
void pcilib_unmap_bar(pcilib_t *ctx, pcilib_bar_t bar, void *data);
255
char *pcilib_resolve_register_address(pcilib_t *ctx, pcilib_bar_t bar, uintptr_t addr); // addr is offset if bar is specified
256
char *pcilib_resolve_data_space(pcilib_t *ctx, uintptr_t addr, size_t *size);
258
pcilib_register_t pcilib_find_register(pcilib_t *ctx, const char *bank, const char *reg);
873
/***********************************************************************************************************//**
874
* \defgroup public_api_event Public Event API
875
* High level API for reading the structured data from hardware
880
* Provides access to the context of event engine. This may be required to call implementation-specific
881
* functions of event engine.
882
* @param [in,out] ctx - pcilib context
883
* @return - context of event engine or NULL in the case of error. Depending on the implementation can be extension of pcilib_contex_t, it should be safe to type cast if you are running the correct engine.
885
pcilib_context_t *pcilib_get_event_engine(pcilib_t *ctx);
888
* Resolves the event ID based on its name.
889
* @param [in,out] ctx - pcilib context
890
* @param [in] event - the event name
891
* @return - the event ID or PCILIB_EVENT_INVALID if event is not found
259
893
pcilib_event_t pcilib_find_event(pcilib_t *ctx, const char *event);
897
* Analyzes current configuration, allocates necessary buffers and spawns required data processing threads.
898
* Depending on the implementation and the current configuration, the actual event grabbing may start already
899
* here. In this case, the preprocessed events will be storred in the temporary buffers and may be lost if
900
* pcilib_stop() is called before reading them out. Alternatively, the actual grabbing may only commend when
901
* the pcilib_stream() or pcilib_get_next_event() functions are executed.
902
* The function is non-blocking and will return immediately after allocating required memory and spawning
903
* of the preprocessing threads. It is important to call pcilib_stop() in the end.
905
* The grabbing will stop automatically if conditions defined using pcilib_configure_autostop() function
906
* are met. It also possible to stop grabbing using pcilib_stop() call at any moment.
908
* The process- and thread-safety is implementation depedent. However, normally the event engine will depend
909
* on DMA and if DMA engine is process-safe it will ensure the process-safety for event engine as well.
910
* The thread-safety is not directly ensured by currently implemented Event engines. The functions of Event
911
* engine may be called from multiple threads, but it is the user responsibility to ensure that only a single
912
* function of Event engine is running at each moment. On other hand, the Event and register APIs may be used
915
* @param[in,out] ctx - pcilib context
916
* @param[in] ev_mask - specifies events to listen for, use #PCILIB_EVENTS_ALL to grab all events
917
* @param[in] flags - various implementation-specific flags controlling operation of event engine
918
* - #PCILIB_EVENT_FLAG_PREPROCESS - requires event preprocessing (i.e. event data is decoded before it is requested, this is often required for multi-threaded processing)
919
* - #PCILIB_EVENT_FLAG_RAW_DATA_ONLY - disables data processing at all, only raw data will be provided in this case
920
* @return - error code or 0 on success
922
int pcilib_start(pcilib_t *ctx, pcilib_event_t ev_mask, pcilib_event_flags_t flags);
926
* Stops event grabbing and optionally cleans up the used memory.
927
* This function operates in two modes. If #PCILIB_EVENT_FLAG_STOP_ONLY flag is specified, the
928
* event grabbing is stopped, but all memory structures are kept intact. This also forces the
929
* blocked pcilib_stream() and pcilib_get_next_event() to return after a short while.
931
* Unlike DMA engine, the event engine is not persistent and is always completely stopped when
932
* application is finished. Therefore, later the pcilib_stop() should be necessarily called
933
* again without #PCILIB_EVENT_FLAG_STOP_ONLY flag to commend full clean up and release all
934
* used memory. Such call may only be issued when no threads are using Event engine any more.
935
* There should be no functions waiting for next event to appear and all of the obtained event
936
* data should be already returned back to the system.
938
* pcilib_stop executed with #PCILIB_EVENT_FLAG_STOP_ONLY is thread safe. The full version of
939
* the function is not and should be never called in parallel with any other action of the
940
* event engine. Actually, it is thread safe in the case of ipecamera, but this is not
941
* guaranteed for other event engines.
943
* @param[in,out] ctx - pcilib context
944
* @param[in] flags - flags specifying operation mode
945
* - #PCILIB_EVENT_FLAG_STOP_ONLY - instructs library to keep all the data structures intact and to onlystop the data grabbing
946
* @return - error code or 0 on success
948
int pcilib_stop(pcilib_t *ctx, pcilib_event_flags_t flags);
951
* Streams the incomming events to the provided callback function. If Event engine is not started
952
* yet, it will be started and terminated upon the completion of the call. The streaming will
953
* continue while Event engine is started and the callback function does not return an error (negative)
954
* or #PCILIB_STREAMING_STOP.
956
* The callback is called only when all the data associated with the event is received from hardware.
957
* So, the raw data is necessarily present, but availability of alternative data formats is
958
* optional. Depending on the implementation and current configuration, the data decoding can be
959
* performed beforehand, in parallel with callback execution, or only them the data is
960
* requested with pcilib_get_data() or pcilib_copy_data() calls.
962
* The function is thread-safe. The multiple requests to pcilib_stream() and pcilib_get_next_event()
963
* will be automatically serialized by the event engine. The pcilib_stream() is running in the
964
* single thread and no new calls to callback are issued until currently executed callback
965
* returns. The client application may get hold on the data from multiple events simultaneously.
966
* However, the data could be overwritten meanwhile by the hardware. The pcilib_return_data()
967
* will inform if it has happened by returning #PCILIB_ERROR_OVERWRITTEN.
969
* @param[in,out] ctx - pcilib context
970
* @param[in] callback - callback function to call for each event, the streaming is stopped if it return #PCILIB_STREAMING_STOP or negative value indicating the error
971
* @param[in,out] user - used data is passed through as the last parameter of callback function
972
* @return - error code or 0 on success
974
int pcilib_stream(pcilib_t *ctx, pcilib_event_callback_t callback, void *user);
977
* Waits until the next event is available.
978
* The event is only returned when all the data associated with the event is received from hardware.
979
* So, the raw data is necessarily present, but availability of alternative data formats is
980
* optional. Depending on the implementation and current configuration, the data decoding can be
981
* performed beforehand, in parallel, or only them the data is requested with pcilib_get_data()
982
* or pcilib_copy_data() calls.
984
* The function is thread-safe. The multiple requests to pcilib_stream() and pcilib_get_next_event()
985
* will be automatically serialized by the event engine. The client application may get hold on
986
* the data from multiple events simultaneously. However, the data could be overwritten meanwhile
987
* by the hardware. The pcilib_return_data() will inform if it has happened by returning
988
* #PCILIB_ERROR_OVERWRITTEN.
990
* @param[in,out] ctx - pcilib context
991
* @param[in] timeout - specifies number of microseconds to wait for next event before reporting timeout, special values #PCILIB_TIMEOUT_IMMEDIATE and #PCILIB_TIMEOUT_INFINITE are supported.
992
* @param[out] evid - the event ID is returned in this parameter
993
* @param[in] info_size - the size of the passed event info structure (the implementation of event engine may extend the standad #pcilib_event_info_t definition and provide extra information about the event.
994
If big enough info buffer is provided, this additional information will be copied as well. Otherwise only standard information is provided.
995
* @param[out] info - The information about the recorded event is written to `info`
996
* @return - error code or 0 on success
998
int pcilib_get_next_event(pcilib_t *ctx, pcilib_timeout_t timeout, pcilib_event_id_t *evid, size_t info_size, pcilib_event_info_t *info);
1001
* Requests the streaming the rawdata from the event engine. The callback will be called
1002
* each time new DMA packet is received. It is the fastest way to acuqire data.
1003
* No memory copies performed and DMA buffers are directly passed to the specified callback.
1004
* However, to prevent data loss, no long processing is allowed is only expected to copy data
1005
* into the appropriate place and return control to the event engine.
1007
* This function should be exectued before the grabbing is started with pcilib_start().
1008
* The performance can be boosted further by disabling any data processing within the event
1009
* engine. This is achieved by passing the #PCILIB_EVENT_FLAG_RAW_DATA_ONLY flag to pcilib_start()
1010
* function while starting the grabbing.
1012
* @param[in,out] ctx - pcilib context
1013
* @param[in] callback - callback function to call for each event, the streaming is stopped if it return #PCILIB_STREAMING_STOP or negative value indicating the error
1014
* @param[in,out] user - used data is passed through as the last parameter of callback function
1015
* @return - error code or 0 on success
1017
int pcilib_configure_rawdata_callback(pcilib_t *ctx, pcilib_event_rawdata_callback_t callback, void *user);
1020
* Configures conditions when the grabbing will be stopped automatically. The recording of new events may be
1021
* stopped after reaching max_events records or when the specified amount of time is elapsed whatever happens
1022
* first. However, the pcilib_stop() function still must be called afterwards.
1024
* This function should be exectued before the grabbing is started with pcilib_start().
1025
* NOTE that this options might not be respected if grabbing is started with the
1026
* #PCILIB_EVENT_FLAG_RAW_DATA_ONLY flag specified.
1028
* @param[in,out] ctx - pcilib context
1029
* @param[in] max_events - specifies number of events after which the grabbing is stopped
1030
* @param[in] duration - specifies number of microseconds to run the grabbing, special values #PCILIB_TIMEOUT_IMMEDIATE and #PCILIB_TIMEOUT_INFINITE are supported.
1031
* @return - error code or 0 on success
1033
int pcilib_configure_autostop(pcilib_t *ctx, size_t max_events, pcilib_timeout_t duration);
1036
* Request the auto-triggering while grabbing. The software triggering is currently not supported (but planned).
1037
* Therefore it is fully relied on hardware support. If no hardware support is available, #PCILIB_ERROR_NOTSUPPORTED
1040
* This function should be exectued before the grabbing is started with pcilib_start().
1042
* @param[in,out] ctx - pcilib context
1043
* @param[in] interval - instructs hardware that each `interval` microseconds a new trigger should be issued
1044
* @param[in] event - specifies ID of the event which will be triggered
1045
* @param[in] trigger_size - specifies the size of `trigger` buffer
1046
* @param[in] trigger_data - this implementation-specific buffer which will be passed through to the Event engine
1047
* @return - error code or 0 on success
1049
int pcilib_configure_autotrigger(pcilib_t *ctx, pcilib_timeout_t interval, pcilib_event_t event, size_t trigger_size, void *trigger_data);
1052
* Issues a single software trigger for the specified event. No hardware support is required. The function
1053
* is fully thread safe and can be called while other thread is blocked in the pcilib_stream() or pcilib_get_next_event()
1056
* @param[in,out] ctx - pcilib context
1057
* @param[in] event - specifies ID of the event to trigger
1058
* @param[in] trigger_size - specifies the size of `trigger` buffer
1059
* @param[in] trigger_data - this implementation-specific buffer which will be passed through to the Event engine
1060
* @return - error code or 0 on success
1062
int pcilib_trigger(pcilib_t *ctx, pcilib_event_t event, size_t trigger_size, void *trigger_data);
1064
/** public_api_event
1068
/***********************************************************************************************************//**
1069
* \defgroup public_api_event_data Public Event Data API
1070
* A part of Event API actually providing access to the data
1075
* Resolves the data type based on its name.
1076
* @param[in,out] ctx - pcilib context
1077
* @param[in] event - the ID of the event producing the data
1078
* @param[in] data_type - the name of data type
1079
* @return - the data type or PCILIB_EVENT_DATA_TYPE_INVALID if the specified type is not found
260
1081
pcilib_event_data_type_t pcilib_find_event_data_type(pcilib_t *ctx, pcilib_event_t event, const char *data_type);
261
pcilib_dma_engine_t pcilib_find_dma_by_addr(pcilib_t *ctx, pcilib_dma_direction_t direction, pcilib_dma_engine_addr_t dma);
263
int pcilib_read(pcilib_t *ctx, pcilib_bar_t bar, uintptr_t addr, size_t size, void *buf);
264
int pcilib_write(pcilib_t *ctx, pcilib_bar_t bar, uintptr_t addr, size_t size, void *buf);
265
int pcilib_write_fifo(pcilib_t *ctx, pcilib_bar_t bar, uintptr_t addr, uint8_t fifo_size, size_t n, void *buf);
266
int pcilib_read_fifo(pcilib_t *ctx, pcilib_bar_t bar, uintptr_t addr, uint8_t fifo_size, size_t n, void *buf);
268
int pcilib_skip_dma(pcilib_t *ctx, pcilib_dma_engine_t dma);
269
int pcilib_stream_dma(pcilib_t *ctx, pcilib_dma_engine_t dma, uintptr_t addr, size_t size, pcilib_dma_flags_t flags, pcilib_timeout_t timeout, pcilib_dma_callback_t cb, void *cbattr);
270
int pcilib_push_dma(pcilib_t *ctx, pcilib_dma_engine_t dma, uintptr_t addr, size_t size, pcilib_dma_flags_t flags, pcilib_timeout_t timeout, void *buf, size_t *written_bytes);
271
int pcilib_read_dma(pcilib_t *ctx, pcilib_dma_engine_t dma, uintptr_t addr, size_t size, void *buf, size_t *read_bytes);
272
int pcilib_read_dma_custom(pcilib_t *ctx, pcilib_dma_engine_t dma, uintptr_t addr, size_t size, pcilib_dma_flags_t flags, pcilib_timeout_t timeout, void *buf, size_t *read_bytes);
273
int pcilib_write_dma(pcilib_t *ctx, pcilib_dma_engine_t dma, uintptr_t addr, size_t size, void *buf, size_t *written_bytes);
274
double pcilib_benchmark_dma(pcilib_t *ctx, pcilib_dma_engine_addr_t dma, uintptr_t addr, size_t size, size_t iterations, pcilib_dma_direction_t direction);
276
int pcilib_read_register_space(pcilib_t *ctx, const char *bank, pcilib_register_addr_t addr, size_t n, pcilib_register_value_t *buf);
277
int pcilib_write_register_space(pcilib_t *ctx, const char *bank, pcilib_register_addr_t addr, size_t n, pcilib_register_value_t *buf);
278
int pcilib_read_register_by_id(pcilib_t *ctx, pcilib_register_t reg, pcilib_register_value_t *value);
279
int pcilib_write_register_by_id(pcilib_t *ctx, pcilib_register_t reg, pcilib_register_value_t value);
280
int pcilib_read_register(pcilib_t *ctx, const char *bank, const char *regname, pcilib_register_value_t *value);
281
int pcilib_write_register(pcilib_t *ctx, const char *bank, const char *regname, pcilib_register_value_t value);
282
int pcilib_read_register_view(pcilib_t *ctx, const char *bank, const char *regname, const char *unit, pcilib_value_t *value);
283
int pcilib_write_register_view(pcilib_t *ctx, const char *bank, const char *regname, const char *unit, const pcilib_value_t *value);
284
int pcilib_read_register_view_by_id(pcilib_t *ctx, pcilib_register_t reg, const char *view, pcilib_value_t *val);
285
int pcilib_write_register_view_by_id(pcilib_t *ctx, pcilib_register_t reg, const char *view, const pcilib_value_t *valarg);
286
int pcilib_get_property(pcilib_t *ctx, const char *prop, pcilib_value_t *val);
287
int pcilib_set_property(pcilib_t *ctx, const char *prop, const pcilib_value_t *val);
1084
* This is a simples way to grab the data from the event engine. The event engine is started, a software trigger
1085
* for the specified event is issued if `timeout` is equal to PCILIB_TIMEOUT_IMMEDIATE, event is grabbed and the
1086
* default data is copied into the user buffer. Then, the grabbing is stopped.
1087
* @param[in,out] ctx - pcilib context
1088
* @param[in] event - the event to trigger and/or event mask to grab
1089
* @param[in,out] size - specifies the size of the provided buffer (if user supplies the buffer), the amount of data actually written is returned in this paramter
1090
* @param[in,out] data - Either contains a pointer to user-supplied buffer where the data will be written or pointer to NULL otherwise.
1091
In the later case, the pointer to newly allocated buffer will be returned in case of success. It is responsibility of the user to free the memory in this case.
1092
In case of failure, the content of data is undefined.
1093
* @param[in] timeout - either is equal to #PCILIB_TIMEOUT_IMMEDIATE for immediate software trigger or specifies number of microseconds to wait for event triggered by hardware
1094
* @return - error code or 0 on success
1096
int pcilib_grab(pcilib_t *ctx, pcilib_event_t event, size_t *size, void **data, pcilib_timeout_t timeout);
1099
* Copies the data of the specified type associated with the specified event into the provided buffer. May return #PCILIB_ERROR_OVERWRITTEN
1100
* if the data was overwritten during the call.
1102
* @param[in,out] ctx - pcilib context
1103
* @param[in] event_id - specifies the ID of event to get data from
1104
* @param[in] data_type - specifies the desired type of data
1105
- PCILIB_EVENT_DATA will request the default data type
1106
- PCILIB_EVENT_RAW_DATA will request the raw data
1107
- The other types of data may be defined by event engine
1108
* @param[in] size - specifies the size of provided buffer in bytes
1109
* @param[out] buf - the data will be copied in this buffer if it is big enough, otherwise #PCILIB_ERROR_TOOBIG will be returned
1110
* @param[out] retsize - the number of actually written bytes will be returned in this parameter
1111
* @return - error code or 0 on success
1113
int pcilib_copy_data(pcilib_t *ctx, pcilib_event_id_t event_id, pcilib_event_data_type_t data_type, size_t size, void *buf, size_t *retsize);
1116
* Copies the data of the specified type associated with the specified event into the provided buffer. May return #PCILIB_ERROR_OVERWRITTEN
1117
* if the data was overwritten during the call. This is very similar to pcilib_copy_data(), but allows to specify implementation specific
1118
* argument explaining the requested data format.
1120
* @param[in,out] ctx - pcilib context
1121
* @param[in] event_id - specifies the ID of event to get data from
1122
* @param[in] data_type - specifies the desired type of data
1123
- PCILIB_EVENT_DATA will request the default data type
1124
- PCILIB_EVENT_RAW_DATA will request the raw data
1125
- The other types of data may be defined by event engine
1126
* @param[in] arg_size - specifies the size of `arg` in bytes
1127
* @param[in] arg - implementation-specific argument expalining the requested data format
1128
* @param[in] size - specifies the size of provided buffer in bytes
1129
* @param[out] buf - the data will be copied in this buffer if it is big enough, otherwise #PCILIB_ERROR_TOOBIG will be returned
1130
* @param[out] retsize - the number of actually written bytes will be returned in this parameter
1131
* @return - error code or 0 on success
1133
int pcilib_copy_data_with_argument(pcilib_t *ctx, pcilib_event_id_t event_id, pcilib_event_data_type_t data_type, size_t arg_size, void *arg, size_t size, void *buf, size_t *retsize);
1137
* Returns pointer to the data of the specified type associated with the specified event. The data should be returned back to the
1138
* Event engine using pcilib_return_data() call. WARNING: Current implementation may overwrite the data before the pcilib_return_data()
1139
* call is executed. In this case the #PCILIB_ERROR_OVERWRITTEN error will be returned by pcilib_return_data() call. I guess this is
1140
* a bad idea and have to be changed. Meanwhile, for the ipecamera implementation the image data will be never overwritten. However,
1141
* the raw data may get overwritten and the error code of pcilib_return_data() has to be consulted.
1143
* @param[in,out] ctx - pcilib context
1144
* @param[in] event_id - specifies the ID of event to get data from
1145
* @param[in] data_type - specifies the desired type of data
1146
- PCILIB_EVENT_DATA will request the default data type
1147
- PCILIB_EVENT_RAW_DATA will request the raw data
1148
- The other types of data may be defined by event engine
1149
* @param[out] size_or_err - contain error code if function returns NULL or number of actually written bytes otherwise
1150
* @return - the pointer to the requested data or NULL otherwise
1152
void *pcilib_get_data(pcilib_t *ctx, pcilib_event_id_t event_id, pcilib_event_data_type_t data_type, size_t *size_or_err);
1155
* Returns pointer to the data of the specified type associated with the specified event. The data should be returned back to the
1156
* Event engine using pcilib_return_data() call. WARNING: Current implementation may overwrite the data before the pcilib_return_data()
1157
* call is executed, @see pcilib_get_data() for details. Overall this function is very similar to pcilib_get_data(), but allows to
1158
* specify implementation specific argument explaining the requested data format.
1160
* @param[in,out] ctx - pcilib context
1161
* @param[in] event_id - specifies the ID of event to get data from
1162
* @param[in] data_type - specifies the desired type of data
1163
- PCILIB_EVENT_DATA will request the default data type
1164
- PCILIB_EVENT_RAW_DATA will request the raw data
1165
- The other types of data may be defined by event engine
1166
* @param[in] arg_size - specifies the size of `arg` in bytes
1167
* @param[in] arg - implementation-specific argument expalining the requested data format
1168
* @param[out] size_or_err - contain error code if function returns NULL or number of actually written bytes otherwise
1169
* @return - the pointer to the requested data or NULL otherwise
1171
void *pcilib_get_data_with_argument(pcilib_t *ctx, pcilib_event_id_t event_id, pcilib_event_data_type_t data_type, size_t arg_size, void *arg, size_t *size_or_err);
1175
* This function returns data obtained using pcilib_get_data() or pcilib_get_data_with_argument() calls.
1176
* It occasionally may return #PCILIB_ERROR_OVERWRITTEN error indicating that the data was overwritten
1177
* between pcilib_get_data() and pcilib_return_data() calls, @see pcilib_get_data() for details.
1178
* @param[in,out] ctx - pcilib context
1179
* @param[in] event_id - specifies the ID of event to get data from
1180
* @param[in] data_type - specifies the data type request in the pcilib_get_data() call
1181
* @param[in,out] data - specifies the buffer returned by pcilib_get_data() call
1182
* @return - #PCILIB_ERROR_OVERWRITTEN or 0 if data is still valid
1184
int pcilib_return_data(pcilib_t *ctx, pcilib_event_id_t event_id, pcilib_event_data_type_t data_type, void *data);
1186
/** public_api_event_data
1191
/***********************************************************************************************************//**
1192
* \defgroup public_api_value Polymorphic values
1193
* API for manipulation of data formats and units
1198
* Destroys the polymorphic value and frees any extra used memory, but does not free #pcilib_value_t itself
1199
* @param[in] ctx - pcilib context
1200
* @param[in,out] val - initialized polymorphic value
289
1202
void pcilib_clean_value(pcilib_t *ctx, pcilib_value_t *val);
1205
* Copies the polymorphic value. If `dst` already contains the value, cleans it first.
1206
* Therefore, before first usage the value should be always initialized to 0.
1207
* @param[in] ctx - pcilib context
1208
* @param[in,out] dst - initialized polymorphic value
1209
* @param[in] src - initialized polymorphic value
1210
* @return - 0 on success or memory error
290
1212
int pcilib_copy_value(pcilib_t *ctx, pcilib_value_t *dst, const pcilib_value_t *src);
1215
* Initializes the polymorphic value from floating-point number. If `val` already contains the value, cleans it first.
1216
* Therefore, before first usage the value should be always initialized to 0.
1217
* @param[in] ctx - pcilib context
1218
* @param[in,out] val - initialized polymorphic value
1219
* @param[in] fval - initializer
1220
* @return - 0 on success or memory error
291
1222
int pcilib_set_value_from_float(pcilib_t *ctx, pcilib_value_t *val, double fval);
1225
* Initializes the polymorphic value from integer. If `val` already contains the value, cleans it first.
1226
* Therefore, before first usage the value should be always initialized to 0.
1227
* @param[in] ctx - pcilib context
1228
* @param[in,out] val - initialized polymorphic value
1229
* @param[in] ival - initializer
1230
* @return - 0 on success or memory error
292
1232
int pcilib_set_value_from_int(pcilib_t *ctx, pcilib_value_t *val, long ival);
293
int pcilib_set_value_from_register_value(pcilib_t *ctx, pcilib_value_t *value, pcilib_register_value_t regval);
294
int pcilib_set_value_from_static_string(pcilib_t *ctx, pcilib_value_t *value, const char *str);
1235
* Initializes the polymorphic value from the register value. If `val` already contains the value, cleans it first.
1236
* Therefore, before first usage the value should be always initialized to 0.
1237
* @param[in] ctx - pcilib context
1238
* @param[in,out] val - initialized polymorphic value
1239
* @param[in] regval - initializer
1240
* @return - 0 on success or memory error
1242
int pcilib_set_value_from_register_value(pcilib_t *ctx, pcilib_value_t *val, pcilib_register_value_t regval);
1245
* Initializes the polymorphic value from the static string. The string is not copied, but only referenced.
1246
* If `val` already contains the value, cleans it first. Therefore, before first usage the value should be always initialized to 0.
1247
* @param[in] ctx - pcilib context
1248
* @param[in,out] val - initialized polymorphic value
1249
* @param[in] str - initializer
1250
* @return - 0 on success or memory error
1252
int pcilib_set_value_from_static_string(pcilib_t *ctx, pcilib_value_t *val, const char *str);
1255
* Get the floating point value from the polymorphic type. May inmply impliced type conversion,
1256
* for isntance parsing the number from the string. Will return 0. and report an error if
1257
* conversion failed.
1258
* @param[in] ctx - pcilib context
1259
* @param[in] val - initialized polymorphic value of arbitrary type
1260
* @param[out] err - error code or 0 on sccuess
1261
* @return - the value or 0 in the case of error
295
1263
double pcilib_get_value_as_float(pcilib_t *ctx, const pcilib_value_t *val, int *err);
1266
* Get the integer value from the polymorphic type. May inmply impliced type conversion
1267
* resulting in precision loss if the `val` stores floating-point number. The warning
1268
* message will be printed in this case, but no error returned.
1269
* @param[in] ctx - pcilib context
1270
* @param[in] val - initialized polymorphic value of arbitrary type
1271
* @param[out] err - error code or 0 on sccuess
1272
* @return - the value or 0 in the case of error
296
1274
long pcilib_get_value_as_int(pcilib_t *ctx, const pcilib_value_t *val, int *err);
1277
* Get the integer value from the polymorphic type. May inmply impliced type conversion
1278
* resulting in precision loss if the `val` stores floating-point number or complete
1279
* data corruption if negative number is stored. The warning message will be printed
1280
* in this case, but no error returned.
1281
* @param[in] ctx - pcilib context
1282
* @param[in] val - initialized polymorphic value of arbitrary type
1283
* @param[out] err - error code or 0 on sccuess
1284
* @return - the value or 0 in the case of error
297
1286
pcilib_register_value_t pcilib_get_value_as_register_value(pcilib_t *ctx, const pcilib_value_t *val, int *err);
1290
* Convert the units of the supplied polymorphic value. The error will be reported if currently used units of the
1291
* value are unknown, the requested conversion is not supported, or the value is not numeric.
1292
* @param[in] ctx - pcilib context
1293
* @param[in,out] val - initialized polymorphic value of any numeric type
1294
* @param[in] unit_name - the requested units
1295
* @return err - error code or 0 on sccuess
298
1297
int pcilib_convert_value_unit(pcilib_t *ctx, pcilib_value_t *val, const char *unit_name);
1300
* Convert the type of the supplied polymorphic value. The error will be reported if conversion
1301
* is not supported or failed due to non-conformant content.
1302
* @param[in] ctx - pcilib context
1303
* @param[in,out] val - initialized polymorphic value of any type
1304
* @param[in] type - the requested type
1305
* @return err - error code or 0 on sccuess
299
1307
int pcilib_convert_value_type(pcilib_t *ctx, pcilib_value_t *val, pcilib_value_type_t type);
301
int pcilib_get_property_attr(pcilib_t *ctx, const char *prop, const char *attr, pcilib_value_t *val);
302
int pcilib_get_register_attr_by_id(pcilib_t *ctx, pcilib_register_t reg, const char *attr, pcilib_value_t *val);
303
int pcilib_get_register_attr(pcilib_t *ctx, const char *bank, const char *regname, const char *attr, pcilib_value_t *val);
304
int pcilib_get_register_bank_attr(pcilib_t *ctx, const char *bankname, const char *attr, pcilib_value_t *val);
306
int pcilib_reset(pcilib_t *ctx);
307
int pcilib_trigger(pcilib_t *ctx, pcilib_event_t event, size_t trigger_size, void *trigger_data);
310
* The recording of new events will be stopped after reaching max_events records
311
* or when the specified amount of time is elapsed. However, the @pcilib_stop
312
* function should be called still.
313
* NOTE: This options may not be respected if the PCILIB_EVENT_FLAG_RAW_DATA_ONLY
316
int pcilib_configure_autostop(pcilib_t *ctx, size_t max_events, pcilib_timeout_t duration);
319
* Request auto-triggering while grabbing
321
int pcilib_configure_autotrigger(pcilib_t *ctx, pcilib_timeout_t interval, pcilib_event_t event, size_t trigger_size, void *trigger_data);
323
* Request streaming the rawdata from the event engine. It is fastest way to acuqire data.
324
* No memory copies will be performed and DMA buffers will be directly passed to the user
325
* callback. However, to prevent data loss, no processing should be done on the data. The
326
* user callback is only expected to copy data into the appropriate place and return control
327
* to the event engine.
328
* The performance can be boosted further by disabling any data processing within the event
329
* engine. Just pass PCILIB_EVENT_FLAG_RAW_DATA_ONLY flag to the @pcilib_start function.
331
int pcilib_configure_rawdata_callback(pcilib_t *ctx, pcilib_event_rawdata_callback_t callback, void *user);
334
* Configures maximal number of preprocessing threads. Actual amount of threads
335
* may be bigger. For instance, additionaly a real-time reader thread will be
336
* executed for most of hardware
338
int pcilib_configure_preprocessing_threads(pcilib_t *ctx, size_t max_threads);
340
pcilib_context_t *pcilib_get_event_engine(pcilib_t *ctx);
342
int pcilib_start(pcilib_t *ctx, pcilib_event_t event_mask, pcilib_event_flags_t flags);
343
int pcilib_stop(pcilib_t *ctx, pcilib_event_flags_t flags);
345
int pcilib_stream(pcilib_t *ctx, pcilib_event_callback_t callback, void *user);
346
int pcilib_get_next_event(pcilib_t *ctx, pcilib_timeout_t timeout, pcilib_event_id_t *evid, size_t info_size, pcilib_event_info_t *info);
348
int pcilib_copy_data(pcilib_t *ctx, pcilib_event_id_t event_id, pcilib_event_data_type_t data_type, size_t size, void *buf, size_t *retsize);
349
int pcilib_copy_data_with_argument(pcilib_t *ctx, pcilib_event_id_t event_id, pcilib_event_data_type_t data_type, size_t arg_size, void *arg, size_t size, void *buf, size_t *retsize);
350
void *pcilib_get_data(pcilib_t *ctx, pcilib_event_id_t event_id, pcilib_event_data_type_t data_type, size_t *size_or_err);
351
void *pcilib_get_data_with_argument(pcilib_t *ctx, pcilib_event_id_t event_id, pcilib_event_data_type_t data_type, size_t arg_size, void *arg, size_t *size_or_err);
354
* This function is provided to find potentially corrupted data. If the data is overwritten by
355
* the time return_data is called it will return error.
357
int pcilib_return_data(pcilib_t *ctx, pcilib_event_id_t event_id, pcilib_event_data_type_t data_type, void *data);
360
* @param data - will be allocated and shuld be freed if NULL, otherwise used and size should contain correct size.
361
* In case of failure the content of data is undefined.
362
* @param timeout - will be autotriggered if NULL
364
int pcilib_grab(pcilib_t *ctx, pcilib_event_t event_mask, size_t *size, void **data, pcilib_timeout_t timeout);
1309
/** public_api_value
366
1314
#ifdef __cplusplus