bzr branch
http://suren.me/webbzr/alps/pcitool
365
by Suren A. Chilingaryan
Restructure driver headers |
1 |
#ifndef _PCILIB_H
|
2 |
#define _PCILIB_H
|
|
6
by Suren A. Chilingaryan
Initial support for registers, infrastructure only |
3 |
|
117
by Suren A. Chilingaryan
new event architecture, first trial |
4 |
#include <sys/time.h> |
236
by Suren A. Chilingaryan
Big redign of model structures |
5 |
#include <stddef.h> |
6
by Suren A. Chilingaryan
Initial support for registers, infrastructure only |
6 |
#include <stdint.h> |
247
by Suren A. Chilingaryan
New error reporting public interface |
7 |
#include <stdarg.h> |
6
by Suren A. Chilingaryan
Initial support for registers, infrastructure only |
8 |
|
7.1.1
by Suren A. Chilingaryan
Initial support of IPECamera protocol |
9 |
typedef struct pcilib_s pcilib_t; |
117
by Suren A. Chilingaryan
new event architecture, first trial |
10 |
typedef struct pcilib_event_context_s pcilib_context_t; |
45
by root
North West Logick DMA implementation |
11 |
|
253
by Suren A. Chilingaryan
Include version information in all API descriptions |
12 |
typedef uint32_t pcilib_version_t; |
13 |
||
7.1.1
by Suren A. Chilingaryan
Initial support of IPECamera protocol |
14 |
typedef uint8_t pcilib_bar_t; /**< Type holding the PCI Bar number */ |
236
by Suren A. Chilingaryan
Big redign of model structures |
15 |
typedef uint16_t pcilib_register_t; /**< Type holding the register position within the field listing registers in the model */ |
307
by Suren A. Chilingaryan
Finalyze XML support and provide initial support for views (only descriptions so far) |
16 |
typedef uint16_t pcilib_view_t; /**< Type holding the register view position within view listing in the model */ |
17 |
typedef uint16_t pcilib_unit_t; /**< Type holding the value unit position within unit listing in the model */ |
|
236
by Suren A. Chilingaryan
Big redign of model structures |
18 |
typedef uint32_t pcilib_register_addr_t; /**< Type holding the register address within address-space of BARs */ |
7.1.1
by Suren A. Chilingaryan
Initial support of IPECamera protocol |
19 |
typedef uint8_t pcilib_register_size_t; /**< Type holding the size in bits of the register */ |
330
by Suren A. Chilingaryan
Support for 64-bit registes |
20 |
typedef uint64_t pcilib_register_value_t; /**< Type holding the register value */ |
49
by Suren A. Chilingaryan
A bit of renaming |
21 |
typedef uint8_t pcilib_dma_engine_addr_t; |
22 |
typedef uint8_t pcilib_dma_engine_t; |
|
50
by Suren A. Chilingaryan
Compilation fix |
23 |
typedef uint64_t pcilib_event_id_t; |
15
by Suren A. Chilingaryan
Infrastructure for event API |
24 |
typedef uint32_t pcilib_event_t; |
176
by Suren A. Chilingaryan
print results even if no frames grabbed |
25 |
typedef uint64_t pcilib_timeout_t; /**< In microseconds */ |
236
by Suren A. Chilingaryan
Big redign of model structures |
26 |
typedef unsigned int pcilib_irq_hw_source_t; |
27 |
typedef uint32_t pcilib_irq_source_t; |
|
303
by Suren A. Chilingaryan
Initial integration of XML support |
28 |
typedef struct _xmlNode pcilib_xml_node_t; |
7.1.1
by Suren A. Chilingaryan
Initial support of IPECamera protocol |
29 |
|
30 |
typedef enum { |
|
250
by Suren A. Chilingaryan
Provide an interface for logging debug messages |
31 |
PCILIB_LOG_DEBUG = 0, /**< Debug messages will be always printed as they should be filtered based on setting of corresponding environmental variable */ |
32 |
PCILIB_LOG_INFO, /**< Informational message are suppresed by default */ |
|
33 |
PCILIB_LOG_WARNING, /**< Warnings messages indicate that something unexpected happen, but application can continue */ |
|
34 |
PCILIB_LOG_ERROR /**< The error which is impossible to handle on this level of library */ |
|
247
by Suren A. Chilingaryan
New error reporting public interface |
35 |
} pcilib_log_priority_t; |
36 |
||
37 |
typedef enum { |
|
319
by Suren A. Chilingaryan
Provide register listings in public API |
38 |
PCILIB_HOST_ENDIAN = 0, /**< The same byte ordering as on the host system running the driver */ |
39 |
PCILIB_LITTLE_ENDIAN, /**< x86 is Little-endian, least significant bytes are at the lower addresses */ |
|
40 |
PCILIB_BIG_ENDIAN /**< Old mainframes and network byte order, most significant bytes are at the lower addresses */ |
|
7.1.1
by Suren A. Chilingaryan
Initial support of IPECamera protocol |
41 |
} pcilib_endianess_t; |
42 |
||
43 |
typedef enum { |
|
315
by Suren A. Chilingaryan
Support properties of arbitrary type |
44 |
PCILIB_ACCESS_R = 1, /**< getting property is allowed */ |
45 |
PCILIB_ACCESS_W = 2, /**< setting property is allowed */ |
|
353
by Suren A. Chilingaryan
Merge Python scripting support from Vasiliy Chernov |
46 |
PCILIB_ACCESS_RW = 3, |
47 |
PCILIB_ACCESS_INCONSISTENT = 0x10000 /**< inconsistent access, one will not read that one has written */ |
|
315
by Suren A. Chilingaryan
Support properties of arbitrary type |
48 |
} pcilib_access_mode_t; |
49 |
||
50 |
typedef enum { |
|
319
by Suren A. Chilingaryan
Provide register listings in public API |
51 |
PCILIB_REGISTER_R = 1, /**< reading from register is allowed */ |
52 |
PCILIB_REGISTER_W = 2, /**< normal writting to register is allowed */ |
|
53 |
PCILIB_REGISTER_RW = 3, |
|
54 |
PCILIB_REGISTER_W1C = 4, /**< writting 1 resets the bit, writting 0 keeps the value */ |
|
55 |
PCILIB_REGISTER_RW1C = 5, |
|
56 |
PCILIB_REGISTER_W1I = 8, /**< writting 1 inversts the bit, writting 0 keeps the value */ |
|
57 |
PCILIB_REGISTER_RW1I = 9, |
|
353
by Suren A. Chilingaryan
Merge Python scripting support from Vasiliy Chernov |
58 |
PCILIB_REGISTER_INCONSISTENT = 0x10000 /**< inconsistent register, writting and reading does not match */ |
319
by Suren A. Chilingaryan
Provide register listings in public API |
59 |
} pcilib_register_mode_t; |
60 |
||
61 |
typedef enum { |
|
309
by Suren A. Chilingaryan
Base functions for views |
62 |
PCILIB_TYPE_INVALID = 0, /**< uninitialized */ |
63 |
PCILIB_TYPE_DEFAULT = 0, /**< default type */ |
|
64 |
PCILIB_TYPE_STRING = 1, /**< char* */ |
|
65 |
PCILIB_TYPE_DOUBLE = 2, /**< double */ |
|
66 |
PCILIB_TYPE_LONG = 3 |
|
67 |
} pcilib_value_type_t; |
|
307
by Suren A. Chilingaryan
Finalyze XML support and provide initial support for views (only descriptions so far) |
68 |
|
69 |
typedef enum { |
|
236
by Suren A. Chilingaryan
Big redign of model structures |
70 |
PCILIB_DMA_IRQ = 1, |
71 |
PCILIB_EVENT_IRQ = 2 |
|
72 |
} pcilib_irq_type_t; |
|
73 |
||
74 |
typedef enum { /**< 0x8000 and up are reserved for driver-specific types */ |
|
75 |
PCILIB_EVENT_DATA = 0, /**< default data format */ |
|
76 |
PCILIB_EVENT_RAW_DATA = 1 /**< raw data */ |
|
15
by Suren A. Chilingaryan
Infrastructure for event API |
77 |
} pcilib_event_data_type_t; |
78 |
||
45
by root
North West Logick DMA implementation |
79 |
typedef enum { |
236
by Suren A. Chilingaryan
Big redign of model structures |
80 |
PCILIB_DMA_TO_DEVICE = 1, |
81 |
PCILIB_DMA_FROM_DEVICE = 2, |
|
82 |
PCILIB_DMA_BIDIRECTIONAL = 3 |
|
83 |
} pcilib_dma_direction_t; |
|
84 |
||
85 |
typedef enum { |
|
45
by root
North West Logick DMA implementation |
86 |
PCILIB_DMA_FLAGS_DEFAULT = 0, |
236
by Suren A. Chilingaryan
Big redign of model structures |
87 |
PCILIB_DMA_FLAG_EOP = 1, /**< last buffer of the packet */ |
88 |
PCILIB_DMA_FLAG_WAIT = 2, /**< wait completion of write operation / wait for data during read operation */ |
|
89 |
PCILIB_DMA_FLAG_MULTIPACKET = 4, /**< read multiple packets */ |
|
90 |
PCILIB_DMA_FLAG_PERSISTENT = 8, /**< do not stop DMA engine on application termination / permanently close DMA engine on dma_stop */ |
|
343
by Suren A. Chilingaryan
Configure number of DMA buffers in IPEDMA and improve checking and reporting inconsistent kmem buffers while re-using |
91 |
PCILIB_DMA_FLAG_IGNORE_ERRORS = 16, /**< do not crash on errors, but return appropriate error codes */ |
92 |
PCILIB_DMA_FLAG_STOP = 32 /**< indicates that we actually calling pcilib_dma_start to stop persistent DMA engine */ |
|
45
by root
North West Logick DMA implementation |
93 |
} pcilib_dma_flags_t; |
94 |
||
47
by Suren A. Chilingaryan
Support FIFO reading/writting, code restructurization, few fixes |
95 |
typedef enum { |
315
by Suren A. Chilingaryan
Support properties of arbitrary type |
96 |
PCILIB_STREAMING_STOP = 0, /**< stop streaming */ |
324
by Suren A. Chilingaryan
Documentation update |
97 |
PCILIB_STREAMING_CONTINUE = 1, /**< wait DMA timeout and return gracefuly if no new data appeared */ |
98 |
PCILIB_STREAMING_WAIT = 2, /**< wait the specified timeout and return gracefuly if no new data appeared */ |
|
99 |
PCILIB_STREAMING_CHECK = 3, /**< check if more data is available without waiting, return gracefuly if no data is ready */ |
|
100 |
PCILIB_STREAMING_TIMEOUT_MASK = 3, /**< mask specifying all timeout modes */ |
|
101 |
PCILIB_STREAMING_FAIL = 4, /**< a flag indicating that the error should be generated if no data is available upon the timeout (whatever timeout mode is used) */ |
|
315
by Suren A. Chilingaryan
Support properties of arbitrary type |
102 |
PCILIB_STREAMING_REQ_FRAGMENT = 5, /**< only fragment of a packet is read, wait for next fragment and fail if no data during DMA timeout */ |
324
by Suren A. Chilingaryan
Documentation update |
103 |
PCILIB_STREAMING_REQ_PACKET = 6 /**< wait for next packet and fail if no data during the specified timeout */ |
279
by Suren A. Chilingaryan
Make pcilib_streaming_action_t public |
104 |
} pcilib_streaming_action_t; |
105 |
||
106 |
typedef enum { |
|
117
by Suren A. Chilingaryan
new event architecture, first trial |
107 |
PCILIB_EVENT_FLAGS_DEFAULT = 0, |
145
by Suren A. Chilingaryan
Print more statistics |
108 |
PCILIB_EVENT_FLAG_RAW_DATA_ONLY = 1, /**< Do not parse data, just read raw and pass it to rawdata callback. If passed to rawdata callback, idicates the data is not identified as event (most probably just padding) */ |
119
by Suren A. Chilingaryan
Initial support of event streaming in cli |
109 |
PCILIB_EVENT_FLAG_STOP_ONLY = 1, /**< Do not cleanup, just stop acquiring new frames, the cleanup should be requested afterwards */ |
126
by Suren A. Chilingaryan
multithread preprocessing of ipecamera frames and code reorganization |
110 |
PCILIB_EVENT_FLAG_EOF = 2, /**< Indicates that it is the last part of the frame (not required) */ |
111 |
PCILIB_EVENT_FLAG_PREPROCESS = 4 /**< Enables preprocessing of the raw data (decoding frames, etc.) */ |
|
117
by Suren A. Chilingaryan
new event architecture, first trial |
112 |
} pcilib_event_flags_t; |
113 |
||
114 |
typedef enum { |
|
119
by Suren A. Chilingaryan
Initial support of event streaming in cli |
115 |
PCILIB_EVENT_INFO_FLAG_BROKEN = 1 /**< Indicates broken frames (if this flag is fales, the frame still can be broken) */ |
116 |
} pcilib_event_info_flags_t; |
|
117 |
||
315
by Suren A. Chilingaryan
Support properties of arbitrary type |
118 |
typedef enum { |
119 |
PCILIB_LIST_FLAGS_DEFAULT = 0, |
|
120 |
PCILIB_LIST_FLAG_CHILDS = 1 /**< Request all sub-elements or indicated that sub-elements are available */ |
|
121 |
} pcilib_list_flags_t; |
|
122 |
||
309
by Suren A. Chilingaryan
Base functions for views |
123 |
typedef struct { |
315
by Suren A. Chilingaryan
Support properties of arbitrary type |
124 |
pcilib_value_type_t type; /**< Current data type */ |
125 |
const char *unit; /**< Units (if known) */ |
|
126 |
const char *format; /**< requested printf format (may enforce using output in hex form) */ |
|
309
by Suren A. Chilingaryan
Base functions for views |
127 |
|
128 |
union { |
|
315
by Suren A. Chilingaryan
Support properties of arbitrary type |
129 |
long ival; /**< The value if type = PCILIB_TYPE_LONG */ |
130 |
double fval; /**< The value if type = PCILIB_TYPE_DOUBLE */ |
|
131 |
const char *sval; /**< The value if type = PCILIB_TYPE_STRING, the pointer may point to static location or reference actual string in str or data */ |
|
309
by Suren A. Chilingaryan
Base functions for views |
132 |
};
|
133 |
||
134 |
// This is a private part
|
|
315
by Suren A. Chilingaryan
Support properties of arbitrary type |
135 |
size_t size; /**< Size of the data */ |
136 |
void *data; /**< Arbitrary data, for instance actual string referenced by the sval */ |
|
137 |
char str[16]; /**< Used for shorter strings converted from integer/float types */ |
|
309
by Suren A. Chilingaryan
Base functions for views |
138 |
} pcilib_value_t; |
139 |
||
315
by Suren A. Chilingaryan
Support properties of arbitrary type |
140 |
typedef struct { |
319
by Suren A. Chilingaryan
Provide register listings in public API |
141 |
pcilib_register_value_t min, max; /**< Minimum and maximum allowed values */ |
142 |
} pcilib_register_value_range_t; |
|
143 |
||
144 |
typedef struct { |
|
145 |
pcilib_register_value_t value; /**< This value will get assigned instead of the name */ |
|
146 |
pcilib_register_value_t min, max; /**< the values in the specified range are aliased by name */ |
|
147 |
const char *name; /**< corresponding string to value */ |
|
320
by Suren A. Chilingaryan
Add optional description in the value name-aliases |
148 |
const char *description; /**< longer description */ |
319
by Suren A. Chilingaryan
Provide register listings in public API |
149 |
} pcilib_register_value_name_t; |
150 |
||
151 |
typedef struct { |
|
152 |
pcilib_register_t id; /**< Direct register ID which can be used in API calls */ |
|
153 |
const char *name; /**< The access name of the register */ |
|
154 |
const char *description; /**< Brief description of the register */ |
|
155 |
const char *bank; /**< The name of the bank register belongs to */ |
|
156 |
pcilib_register_mode_t mode; /**< Register access (ro/wo/rw) and how writting to register works (clearing/inverting set bits) */ |
|
157 |
pcilib_register_value_t defvalue; /**< Default register value */ |
|
158 |
const pcilib_register_value_range_t *range; /**< Specifies default, minimum, and maximum values */ |
|
159 |
const pcilib_register_value_name_t *values; /**< The list of enum names for the register value */ |
|
160 |
} pcilib_register_info_t; |
|
161 |
||
162 |
typedef struct { |
|
315
by Suren A. Chilingaryan
Support properties of arbitrary type |
163 |
const char *name; /**< Name of the property view */ |
164 |
const char *path; /**< Full path to the property */ |
|
165 |
const char *description; /**< Short description */ |
|
166 |
pcilib_value_type_t type; /**< The default data type or PCILIB_TYPE_INVALID if directory */ |
|
167 |
pcilib_access_mode_t mode; /**< Specifies if the view is read/write-only */ |
|
168 |
pcilib_list_flags_t flags; /**< Indicates if have sub-folders, etc. */ |
|
169 |
const char *unit; /**< Returned unit (if any) */ |
|
170 |
} pcilib_property_info_t; |
|
171 |
||
319
by Suren A. Chilingaryan
Provide register listings in public API |
172 |
typedef struct { |
173 |
pcilib_event_t type; |
|
174 |
uint64_t seqnum; /**< we will add seqnum_overflow if required */ |
|
175 |
uint64_t offset; /**< nanoseconds */ |
|
176 |
struct timeval timestamp; /**< most accurate timestamp */ |
|
177 |
pcilib_event_info_flags_t flags; /**< flags */ |
|
178 |
} pcilib_event_info_t; |
|
179 |
||
45
by root
North West Logick DMA implementation |
180 |
|
7.1.1
by Suren A. Chilingaryan
Initial support of IPECamera protocol |
181 |
#define PCILIB_BAR_DETECT ((pcilib_bar_t)-1)
|
39
by root
Move to new FPGA design |
182 |
#define PCILIB_BAR_INVALID ((pcilib_bar_t)-1)
|
275
by Suren A. Chilingaryan
Integration of software registers |
183 |
#define PCILIB_BAR_NOBAR ((pcilib_bar_t)-2)
|
39
by root
Move to new FPGA design |
184 |
#define PCILIB_BAR0 0
|
185 |
#define PCILIB_BAR1 1
|
|
62
by Suren A. Chilingaryan
Suppport DMA modes in console application (not functional yet) |
186 |
#define PCILIB_DMA_ENGINE_INVALID ((pcilib_dma_engine_t)-1)
|
65
by Suren A. Chilingaryan
Separate NWL loopback code, provide DMA start/stop interfaces |
187 |
#define PCILIB_DMA_ENGINE_ALL ((pcilib_dma_engine_t)-1)
|
188 |
#define PCILIB_DMA_FLAGS_DEFAULT ((pcilib_dma_flags_t)0)
|
|
62
by Suren A. Chilingaryan
Suppport DMA modes in console application (not functional yet) |
189 |
#define PCILIB_DMA_ENGINE_ADDR_INVALID ((pcilib_dma_engine_addr_t)-1)
|
7.1.1
by Suren A. Chilingaryan
Initial support of IPECamera protocol |
190 |
#define PCILIB_REGISTER_INVALID ((pcilib_register_t)-1)
|
332
by Suren A. Chilingaryan
Provide API calls for register and bank address resolution |
191 |
#define PCILIB_REGISTER_ADDRESS_INVALID ((pcilib_register_addr_t)-1)
|
7.1.1
by Suren A. Chilingaryan
Initial support of IPECamera protocol |
192 |
#define PCILIB_ADDRESS_INVALID ((uintptr_t)-1)
|
16
by Suren A. Chilingaryan
Prototype of IPECamera image protocol |
193 |
#define PCILIB_EVENT0 1
|
194 |
#define PCILIB_EVENT1 2
|
|
195 |
#define PCILIB_EVENT2 4
|
|
196 |
#define PCILIB_EVENT3 8
|
|
197 |
#define PCILIB_EVENTS_ALL ((pcilib_event_t)-1)
|
|
29
by Suren A. Chilingaryan
Support non-callback way of getting events |
198 |
#define PCILIB_EVENT_INVALID ((pcilib_event_t)-1)
|
123
by Suren A. Chilingaryan
Parse required event & data_type |
199 |
#define PCILIB_EVENT_DATA_TYPE_INVALID ((pcilib_event_data_type_t)-1)
|
62
by Suren A. Chilingaryan
Suppport DMA modes in console application (not functional yet) |
200 |
#define PCILIB_TIMEOUT_INFINITE ((pcilib_timeout_t)-1)
|
45
by root
North West Logick DMA implementation |
201 |
#define PCILIB_TIMEOUT_IMMEDIATE 0
|
194
by Suren A. Chilingaryan
DMA-independent IRQ functions |
202 |
#define PCILIB_IRQ_TYPE_ALL 0
|
88
by Suren A. Chilingaryan
IRQ acknowledgement support in the engine API |
203 |
#define PCILIB_IRQ_SOURCE_DEFAULT 0
|
236
by Suren A. Chilingaryan
Big redign of model structures |
204 |
#define PCILIB_MODEL_DETECT NULL
|
7.1.1
by Suren A. Chilingaryan
Initial support of IPECamera protocol |
205 |
|
324
by Suren A. Chilingaryan
Documentation update |
206 |
/**
|
207 |
* Callback function called when pcilib wants to log a new message
|
|
208 |
* @param[in,out] arg - logging context provided with pcilib_set_logger() call
|
|
209 |
* @param[in] file - source file generating the message
|
|
210 |
* @param[in] line - source line generating the message
|
|
211 |
* @param[in] prio - the message priority (messages with priority bellow the currently set loglevel are already filtered)
|
|
212 |
* @param[in] msg - message or printf-style formating string
|
|
213 |
* @param[in] va - vairable parameters defined by formating string
|
|
214 |
*/
|
|
247
by Suren A. Chilingaryan
New error reporting public interface |
215 |
typedef void (*pcilib_logger_t)(void *arg, const char *file, int line, pcilib_log_priority_t prio, const char *msg, va_list va); |
216 |
||
324
by Suren A. Chilingaryan
Documentation update |
217 |
/**
|
109
by Suren A. Chilingaryan
Improvements of DMA engine |
218 |
* Callback function called when new data is read by DMA streaming function
|
324
by Suren A. Chilingaryan
Documentation update |
219 |
* @param[in,out] ctx - DMA Engine context
|
220 |
* @param[in] flags - DMA Flags
|
|
221 |
* @param[in] bufsize - size of data in bytes
|
|
222 |
* @param[in] buf - data
|
|
223 |
* @return - #pcilib_streaming_action_t instructing how the streaming should continue or a negative error code in the case of error
|
|
109
by Suren A. Chilingaryan
Improvements of DMA engine |
224 |
*/
|
225 |
typedef int (*pcilib_dma_callback_t)(void *ctx, pcilib_dma_flags_t flags, size_t bufsize, void *buf); |
|
324
by Suren A. Chilingaryan
Documentation update |
226 |
|
227 |
/**
|
|
228 |
* Callback function called when new event is generated by event engine
|
|
229 |
* @param[in] event_id - event id
|
|
230 |
* @param[in] info - event description (depending on event engine may provide additional fields on top of #pcilib_event_info_t)
|
|
231 |
* @param[in,out] user - User-specific data provided in pcilib_stream() call
|
|
232 |
* @return - #pcilib_streaming_action_t instructing how the streaming should continue or a negative error code in the case of error
|
|
233 |
*/
|
|
234 |
typedef int (*pcilib_event_callback_t)(pcilib_event_id_t event_id, const pcilib_event_info_t *info, void *user); |
|
235 |
||
236 |
/**
|
|
237 |
* Callback function called when new portion of raw data is read by event engine
|
|
238 |
* @param[in] event_id - id of the event this data will be associated with if processing is successful
|
|
239 |
* @param[in] info - event description (depending on event engine may provide additional fields on top of #pcilib_event_info_t)
|
|
240 |
* @param[in] flags - may indicate if it is the last portion of data for current event
|
|
241 |
* @param[in] size - size of data in bytes
|
|
242 |
* @param[in,out] data - data (the callback may modify the data, but the size should be kept of course)
|
|
243 |
* @param[in,out] user - User-specific data provided in pcilib_stream() call
|
|
244 |
* @return - #pcilib_streaming_action_t instructing how the streaming should continue or a negative error code in the case of error
|
|
245 |
*/
|
|
246 |
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); |
|
50
by Suren A. Chilingaryan
Compilation fix |
247 |
|
277
by Suren A. Chilingaryan
Keep C++ compilers happy |
248 |
#ifdef __cplusplus
|
249 |
extern "C" { |
|
250 |
#endif
|
|
251 |
||
324
by Suren A. Chilingaryan
Documentation update |
252 |
/***********************************************************************************************************//**
|
253 |
* \defgroup public_api_global Global Public API (logging, etc.)
|
|
254 |
* Global functions which does not require existing pcilib context
|
|
255 |
* @{
|
|
256 |
*/
|
|
257 |
||
258 |
/**
|
|
259 |
* Replaces default logging function.
|
|
260 |
* @param min_prio - messages with priority below \a min_prio will be ignored
|
|
261 |
* @param logger - configures a new logging function or restores the default one if NULL is passed
|
|
262 |
* @param arg - logging context, this parameter will be passed through to the \a logger
|
|
263 |
* @return - error code or 0 on success
|
|
264 |
*/
|
|
247
by Suren A. Chilingaryan
New error reporting public interface |
265 |
int pcilib_set_logger(pcilib_log_priority_t min_prio, pcilib_logger_t logger, void *arg); |
6
by Suren A. Chilingaryan
Initial support for registers, infrastructure only |
266 |
|
324
by Suren A. Chilingaryan
Documentation update |
267 |
/** public_api_global
|
268 |
* @}
|
|
269 |
*/
|
|
270 |
||
271 |
||
272 |
/***********************************************************************************************************//**
|
|
273 |
* \defgroup public_api Public API
|
|
274 |
* Base pcilib functions which does not belong to the specific APIs
|
|
275 |
* @{
|
|
276 |
*/
|
|
277 |
||
278 |
/**
|
|
279 |
* Initializes pcilib context, detects model configuration, and populates model-specific registers.
|
|
280 |
* Event and DMA engines will not be started automatically, but calls to pcilib_start() / pcilib_start_dma()
|
|
281 |
* are provided for this purpose. In the end, the context should be cleaned using pcilib_stop().
|
|
282 |
* @param[in] device - path to the device file [/dev/fpga0]
|
|
283 |
* @param[in] model - specifies the model of hardware, autodetected if NULL is passed
|
|
284 |
* @return - initialized context or NULL in the case of error
|
|
285 |
*/
|
|
236
by Suren A. Chilingaryan
Big redign of model structures |
286 |
pcilib_t *pcilib_open(const char *device, const char *model); |
324
by Suren A. Chilingaryan
Documentation update |
287 |
|
288 |
/**
|
|
289 |
* Destroy pcilib context and all memory associated with it. The function will stop event engine if necessary,
|
|
290 |
* but DMA engine stay running if it was already running before pcilib_open() was called
|
|
291 |
* @param[in,out] ctx - pcilib context
|
|
292 |
*/
|
|
7.1.1
by Suren A. Chilingaryan
Initial support of IPECamera protocol |
293 |
void pcilib_close(pcilib_t *ctx); |
294 |
||
324
by Suren A. Chilingaryan
Documentation update |
295 |
/**
|
296 |
* Should reset the hardware and software in default state. It is implementation-specific, but is not actively
|
|
297 |
* used in existing implementations because the hardware is initialized from bash scripts which are often
|
|
298 |
* changed by Michele and his band. On the software side, it probably should reset all software registers
|
|
299 |
* to default value and may be additionaly re-start and clear DMA. However, this is not implemented yet.
|
|
300 |
* @param[in,out] ctx - pcilib context
|
|
301 |
* @return - error code or 0 on success
|
|
302 |
*/
|
|
303 |
||
304 |
int pcilib_reset(pcilib_t *ctx); |
|
305 |
||
306 |
/** public_api
|
|
307 |
* @}
|
|
308 |
*/
|
|
309 |
||
310 |
||
311 |
/***********************************************************************************************************//**
|
|
312 |
* \defgroup public_api_pci Public PCI API (MMIO)
|
|
313 |
* API for manipulation with memory-mapped PCI BAR space
|
|
314 |
* @{
|
|
315 |
*/
|
|
316 |
||
317 |
/**
|
|
318 |
* Resolves the phisycal PCI address to a virtual address in the process address space.
|
|
319 |
* The required BAR will be mapped if necessary.
|
|
320 |
* @param[in,out] ctx - pcilib context
|
|
321 |
* @param[in] bar - specifies the BAR address belong to, use PCILIB_BAR_DETECT for autodetection
|
|
322 |
* @param[in] addr - specifies the physical address on the PCI bus or offset in the BAR if \a bar is specified
|
|
323 |
* @return - the virtual address in the process address space or NULL in case of error
|
|
324 |
*/
|
|
325 |
char *pcilib_resolve_bar_address(pcilib_t *ctx, pcilib_bar_t bar, uintptr_t addr); |
|
326 |
||
327 |
/**
|
|
328 |
* Performs PIO read from the PCI BAR. The BAR will be automatically mapped and unmapped if necessary.
|
|
329 |
* @param[in,out] ctx - pcilib context
|
|
330 |
* @param[in] bar - the BAR to read, use PCILIB_BAR_DETECT to detect bar by the specified physical address
|
|
331 |
* @param[in] addr - absolute physical address to read or the offset in the specified bar
|
|
345
by Suren A. Chilingaryan
64-bit access to BAR memory |
332 |
* @param[in] access - word size (access width in bytes)
|
333 |
* @param[in] n - number of words to read
|
|
324
by Suren A. Chilingaryan
Documentation update |
334 |
* @param[out] buf - the read data will be placed in this buffer
|
335 |
* @return - error code or 0 on success
|
|
336 |
*/
|
|
345
by Suren A. Chilingaryan
64-bit access to BAR memory |
337 |
int pcilib_read(pcilib_t *ctx, pcilib_bar_t bar, uintptr_t addr, uint8_t access, size_t n, void *buf); |
324
by Suren A. Chilingaryan
Documentation update |
338 |
|
339 |
/**
|
|
340 |
* Performs PIO write to the PCI BAR. The BAR will be automatically mapped and unmapped if necessary.
|
|
341 |
* @param[in,out] ctx - pcilib context
|
|
342 |
* @param[in] bar - the BAR to write, use PCILIB_BAR_DETECT to detect bar by the specified physical address
|
|
343 |
* @param[in] addr - absolute physical address to write or the offset in the specified bar
|
|
345
by Suren A. Chilingaryan
64-bit access to BAR memory |
344 |
* @param[in] access - word size (access width in bytes)
|
345 |
* @param[in] n - number of words to write
|
|
324
by Suren A. Chilingaryan
Documentation update |
346 |
* @param[out] buf - the pointer to the data to be written
|
347 |
* @return - error code or 0 on success
|
|
348 |
*/
|
|
345
by Suren A. Chilingaryan
64-bit access to BAR memory |
349 |
int pcilib_write(pcilib_t *ctx, pcilib_bar_t bar, uintptr_t addr, uint8_t access, size_t n, void *buf); |
324
by Suren A. Chilingaryan
Documentation update |
350 |
|
351 |
/**
|
|
352 |
* Performs PIO read from the PCI BAR. The specified address is treated as FIFO and will be read
|
|
353 |
* \a n times. The BAR will be automatically mapped and unmapped if necessary.
|
|
354 |
* @param[in,out] ctx - pcilib context
|
|
355 |
* @param[in] bar - the BAR to read, use PCILIB_BAR_DETECT to detect bar by the specified physical address
|
|
356 |
* @param[in] addr - absolute physical address to read or the offset in the specified bar
|
|
357 |
* @param[in] access - the size of FIFO register in bytes (i.e. if `access = 4`, the 32-bit reads from FIFO will be performed)
|
|
358 |
* @param[in] n - specifies how many times the data should be read from FIFO
|
|
359 |
* @param[out] buf - the data will be placed in this buffer which should be at least `n * access` bytes long
|
|
360 |
* @return - error code or 0 on success
|
|
361 |
*/
|
|
362 |
int pcilib_read_fifo(pcilib_t *ctx, pcilib_bar_t bar, uintptr_t addr, uint8_t access, size_t n, void *buf); |
|
363 |
||
364 |
/**
|
|
365 |
* Performs PIO write to the PCI BAR. The specified address is treated as FIFO and will be written
|
|
366 |
* \a n times. The BAR will be automatically mapped and unmapped if necessary.
|
|
367 |
* @param[in,out] ctx - pcilib context
|
|
368 |
* @param[in] bar - the BAR to write, use PCILIB_BAR_DETECT to detect bar by the specified physical address
|
|
369 |
* @param[in] addr - absolute physical address to write or the offset in the specified bar
|
|
370 |
* @param[in] access - the size of FIFO register in bytes (i.e. if `access = 4`, the 32-bit writes to FIFO will be performed)
|
|
371 |
* @param[in] n - specifies how many times the data should be written to FIFO
|
|
372 |
* @param[out] buf - buffer to write which should be at least `n * access` bytes long
|
|
373 |
* @return - error code or 0 on success
|
|
374 |
*/
|
|
375 |
int pcilib_write_fifo(pcilib_t *ctx, pcilib_bar_t bar, uintptr_t addr, uint8_t access, size_t n, void *buf); |
|
376 |
||
377 |
/** public_api_pci
|
|
378 |
* @}
|
|
379 |
*/
|
|
380 |
||
381 |
||
382 |
/***********************************************************************************************************//**
|
|
383 |
* \defgroup public_api_register Public Register API
|
|
384 |
* API for register manipulations
|
|
385 |
* @{
|
|
386 |
*/
|
|
387 |
||
388 |
/**
|
|
389 |
* Returns the list of registers provided by the hardware model.
|
|
390 |
* @param[in,out] ctx - pcilib context
|
|
391 |
* @param[in] bank - if set, only register within the specified bank will be returned
|
|
392 |
* @param[in] flags - currently ignored
|
|
393 |
* @return - the list of the register which should be cleaned with pcilib_free_register_info() or NULL in the case of error
|
|
394 |
*/
|
|
395 |
pcilib_register_info_t *pcilib_get_register_list(pcilib_t *ctx, const char *bank, pcilib_list_flags_t flags); |
|
396 |
||
397 |
/**
|
|
398 |
* Returns the information about the specified register
|
|
399 |
* @param[in,out] ctx - pcilib context
|
|
400 |
* @param[in] bank - indicates the bank where to look for register, autodetected if NULL is passed
|
|
401 |
* @param[in] reg - the name of the register
|
|
402 |
* @param[in] flags - currently ignored
|
|
403 |
* @return - information about the specified register which should be cleaned with pcilib_free_register_info() or NULL in the case of error
|
|
404 |
*/
|
|
405 |
pcilib_register_info_t *pcilib_get_register_info(pcilib_t *ctx, const char *bank, const char *reg, pcilib_list_flags_t flags); |
|
406 |
||
407 |
/**
|
|
408 |
* Cleans up the memory occupied by register list returned from the pcilib_get_register_list() and pcilib_get_register_info() calls
|
|
409 |
* @param[in,out] ctx - pcilib context
|
|
410 |
* @param[in,out] info - buffer to clean
|
|
411 |
*/
|
|
412 |
void pcilib_free_register_info(pcilib_t *ctx, pcilib_register_info_t *info); |
|
413 |
||
414 |
/**
|
|
415 |
* Finds register id corresponding to the specified bank and register names. It is faster
|
|
416 |
* to access registers by id instead of names. Therefore, in long running applications it
|
|
417 |
* is preferred to resolve names of all required registers during initialization and access
|
|
418 |
* them using ids only.
|
|
419 |
* @param[in,out] ctx - pcilib context
|
|
420 |
* @param[in] bank - should specify the bank name if register with the same name may occur in multiple banks, NULL otherwise
|
|
421 |
* @param[in] reg - the name of the register
|
|
422 |
* @return - register id or PCILIB_REGISTER_INVALID if register is not found
|
|
423 |
*/
|
|
424 |
pcilib_register_t pcilib_find_register(pcilib_t *ctx, const char *bank, const char *reg); |
|
425 |
||
426 |
/**
|
|
427 |
* Extracts additional information about the specified register. The additional information
|
|
428 |
* is model-specific and are provided as extra XML attributes in XML-described registers.
|
|
429 |
* The available attributes are only restricted by used XSD schema.
|
|
430 |
* @param[in,out] ctx - pcilib context
|
|
431 |
* @param[in] reg - register id
|
|
432 |
* @param[in] attr - requested attribute name
|
|
433 |
* @param[in,out] val - the value of attribute is returned here (see \ref public_api_value),
|
|
434 |
* pcilib_clean_value() will be executed if \a val contains data. Therefore it should be always initialized to 0 before first use
|
|
435 |
* @return - error code or 0 on success
|
|
436 |
*/
|
|
437 |
int pcilib_get_register_attr_by_id(pcilib_t *ctx, pcilib_register_t reg, const char *attr, pcilib_value_t *val); |
|
438 |
||
439 |
/**
|
|
440 |
* Extracts additional information about the specified register.
|
|
441 |
* Equivalent to the pcilib_get_register_attr_by_id(), but first resolves register id using the specified bank and name.
|
|
442 |
* @param[in,out] ctx - pcilib context
|
|
443 |
* @param[in] bank - should specify the bank name if register with the same name may occur in multiple banks, NULL otherwise
|
|
444 |
* @param[in] regname - register name
|
|
445 |
* @param[in] attr - requested attribute name
|
|
446 |
* @param[in,out] val - the value of attribute is returned here (see \ref public_api_value),
|
|
447 |
* pcilib_clean_value() will be executed if \a val contains data. Therefore it should be always initialized to 0 before first use
|
|
448 |
* @return - error code or 0 on success
|
|
449 |
*/
|
|
450 |
int pcilib_get_register_attr(pcilib_t *ctx, const char *bank, const char *regname, const char *attr, pcilib_value_t *val); |
|
451 |
||
452 |
/**
|
|
453 |
* Reads one or multiple sequential registers from the specified register bank. This function may provide access
|
|
454 |
* to the undefined registers in the bank. In other cases, the pcilib_read_register() / pcilib_read_register_by_id()
|
|
455 |
* calls are preferred.
|
|
456 |
* @param[in,out] ctx - pcilib context
|
|
457 |
* @param[in] bank - the bank to read (should be specified, no autodetection)
|
|
458 |
* @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)
|
|
459 |
* @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)
|
|
460 |
* @param[out] buf - the buffer of `n * register_size` bytes long where the data will be stored
|
|
461 |
* @return - error code or 0 on success
|
|
462 |
*/
|
|
463 |
int pcilib_read_register_space(pcilib_t *ctx, const char *bank, pcilib_register_addr_t addr, size_t n, pcilib_register_value_t *buf); |
|
464 |
||
465 |
/**
|
|
466 |
* Writes one or multiple sequential registers from the specified register bank. This function may provide access
|
|
467 |
* to the undefined registers in the bank. In other cases, the pcilib_write_register() / pcilib_write_register_by_id()
|
|
468 |
* calls are preferred.
|
|
469 |
* @param[in,out] ctx - pcilib context
|
|
470 |
* @param[in] bank - the bank to write (should be specified, no autodetection)
|
|
471 |
* @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)
|
|
472 |
* @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)
|
|
473 |
* @param[in] buf - the buffer of `n * register_size` bytes long with the data
|
|
474 |
* @return - error code or 0 on success
|
|
475 |
*/
|
|
476 |
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); |
|
477 |
||
478 |
/**
|
|
479 |
* Reads the specified register.
|
|
480 |
* @param[in,out] ctx - pcilib context
|
|
481 |
* @param[in] reg - register id
|
|
482 |
* @param[out] value - the register value is returned here
|
|
483 |
* @return - error code or 0 on success
|
|
484 |
*/
|
|
485 |
int pcilib_read_register_by_id(pcilib_t *ctx, pcilib_register_t reg, pcilib_register_value_t *value); |
|
486 |
||
487 |
/**
|
|
488 |
* Writes to the specified register.
|
|
489 |
* @param[in,out] ctx - pcilib context
|
|
490 |
* @param[in] reg - register id
|
|
491 |
* @param[in] value - the register value to write
|
|
492 |
* @return - error code or 0 on success
|
|
493 |
*/
|
|
494 |
int pcilib_write_register_by_id(pcilib_t *ctx, pcilib_register_t reg, pcilib_register_value_t value); |
|
495 |
||
496 |
/**
|
|
497 |
* Reads the specified register.
|
|
498 |
* Equivalent to the pcilib_read_register_by_id(), but first resolves register id using the specified bank and name.
|
|
499 |
* @param[in,out] ctx - pcilib context
|
|
500 |
* @param[in] bank - should specify the bank name if register with the same name may occur in multiple banks, NULL otherwise
|
|
501 |
* @param[in] regname - the name of the register
|
|
502 |
* @param[out] value - the register value is returned here
|
|
503 |
* @return - error code or 0 on success
|
|
504 |
*/
|
|
505 |
int pcilib_read_register(pcilib_t *ctx, const char *bank, const char *regname, pcilib_register_value_t *value); |
|
506 |
||
507 |
/**
|
|
508 |
* Writes to the specified register.
|
|
509 |
* Equivalent to the pcilib_write_register_by_id(), but first resolves register id using the specified bank and name.
|
|
510 |
* @param[in,out] ctx - pcilib context
|
|
511 |
* @param[in] bank - should specify the bank name if register with the same name may occur in multiple banks, NULL otherwise
|
|
512 |
* @param[in] regname - the name of the register
|
|
513 |
* @param[in] value - the register value to write
|
|
514 |
* @return - error code or 0 on success
|
|
515 |
*/
|
|
516 |
int pcilib_write_register(pcilib_t *ctx, const char *bank, const char *regname, pcilib_register_value_t value); |
|
517 |
||
518 |
||
519 |
/**
|
|
520 |
* Reads a view of the specified register. The views allow to convert values to standard units
|
|
521 |
* or get self-explanatory names associated with the values (enums).
|
|
522 |
* @param[in,out] ctx - pcilib context
|
|
523 |
* @param[in] reg - register id
|
|
524 |
* @param[in] view - specifies the name of the view associated with register or desired units
|
|
525 |
* @param[out] value - the register value is returned here (see \ref public_api_value),
|
|
526 |
* pcilib_clean_value() will be executed if \a val contains data. Therefore it should be always initialized to 0 before first use.
|
|
527 |
* @return - error code or 0 on success
|
|
528 |
*/
|
|
529 |
int pcilib_read_register_view_by_id(pcilib_t *ctx, pcilib_register_t reg, const char *view, pcilib_value_t *value); |
|
530 |
||
531 |
/**
|
|
532 |
* Writes the specified register using value represented in the specified view. The views allow to convert values from standard units
|
|
533 |
* or self-explanatory names associated with the values (enums).
|
|
534 |
* @param[in,out] ctx - pcilib context
|
|
535 |
* @param[in] reg - register id
|
|
536 |
* @param[in] view - specifies the name of the view associated with register or the used units
|
|
537 |
* @param[in] value - the register value in the specified view (see \ref public_api_value)
|
|
538 |
* @return - error code or 0 on success
|
|
539 |
*/
|
|
540 |
int pcilib_write_register_view_by_id(pcilib_t *ctx, pcilib_register_t reg, const char *view, const pcilib_value_t *value); |
|
541 |
||
542 |
/**
|
|
543 |
* Reads a view of the specified register. The views allow to convert values to standard units
|
|
544 |
* or get self-explanatory names associated with the values (enums).
|
|
545 |
* Equivalent to the pcilib_read_register_view_by_id(), but first resolves register id using the specified bank and name.
|
|
546 |
* @param[in,out] ctx - pcilib context
|
|
547 |
* @param[in] bank - should specify the bank name if register with the same name may occur in multiple banks, NULL otherwise
|
|
548 |
* @param[in] regname - the name of the register
|
|
549 |
* @param[in] view - specifies the name of the view associated with register or desired units
|
|
550 |
* @param[out] value - the register value is returned here (see \ref public_api_value),
|
|
551 |
* pcilib_clean_value() will be executed if \a val contains data. Therefore it should be always initialized to 0 before first use
|
|
552 |
* @return - error code or 0 on success
|
|
553 |
*/
|
|
554 |
int pcilib_read_register_view(pcilib_t *ctx, const char *bank, const char *regname, const char *view, pcilib_value_t *value); |
|
555 |
||
556 |
||
557 |
/**
|
|
558 |
* Writes the specified register using value represented in the specified view. The views allow to convert values from standard units
|
|
559 |
* or self-explanatory names associated with the values (enums).
|
|
560 |
* Equivalent to the pcilib_write_register_view_by_id(), but first resolves register id using the specified bank and name.
|
|
561 |
* @param[in,out] ctx - pcilib context
|
|
562 |
* @param[in] bank - should specify the bank name if register with the same name may occur in multiple banks, NULL otherwise
|
|
563 |
* @param[in] regname - the name of the register
|
|
564 |
* @param[in] view - specifies the name of the view associated with register or the used units
|
|
565 |
* @param[in] value - the register value in the specified view (see \ref public_api_value)
|
|
566 |
* @return - error code or 0 on success
|
|
567 |
*/
|
|
568 |
int pcilib_write_register_view(pcilib_t *ctx, const char *bank, const char *regname, const char *view, const pcilib_value_t *value); |
|
569 |
||
570 |
/** public_api_register
|
|
571 |
* @}
|
|
572 |
*/
|
|
573 |
||
574 |
/***********************************************************************************************************//**
|
|
575 |
* \defgroup public_api_property Public Property API
|
|
576 |
* Properties is another abstraction on top of registers allowing arbitrary data types and computed registers
|
|
577 |
* @{
|
|
578 |
*/
|
|
579 |
||
580 |
/**
|
|
581 |
* Returns the list of properties available under the specified path
|
|
582 |
* @param[in,out] ctx - pcilib context
|
|
583 |
* @param[in] branch - path or NULL to return the top-level properties
|
|
584 |
* @param[in] flags - not used at the moment
|
|
585 |
* @return - the list of the properties which should be cleaned with pcilib_free_property_info() or NULL in the case of error
|
|
586 |
*/
|
|
319
by Suren A. Chilingaryan
Provide register listings in public API |
587 |
pcilib_property_info_t *pcilib_get_property_list(pcilib_t *ctx, const char *branch, pcilib_list_flags_t flags); |
324
by Suren A. Chilingaryan
Documentation update |
588 |
|
589 |
/**
|
|
590 |
* Cleans up the memory occupied by property list returned from the pcilib_get_property_list() call
|
|
591 |
* @param[in,out] ctx - pcilib context
|
|
592 |
* @param[in,out] info - buffer to clean
|
|
593 |
*/
|
|
319
by Suren A. Chilingaryan
Provide register listings in public API |
594 |
void pcilib_free_property_info(pcilib_t *ctx, pcilib_property_info_t *info); |
324
by Suren A. Chilingaryan
Documentation update |
595 |
|
596 |
/**
|
|
597 |
* Extracts additional information about the specified register.
|
|
598 |
* Equivalent to the pcilib_get_register_attr_by_id(), but first resolves register id using the specified bank and name.
|
|
599 |
* @param[in,out] ctx - pcilib context
|
|
600 |
* @param[in] prop - property name (full name including path)
|
|
601 |
* @param[in] attr - requested attribute name
|
|
602 |
* @param[in,out] val - the value of attribute is returned here (see \ref public_api_value),
|
|
603 |
* pcilib_clean_value() will be executed if \a val contains data. Therefore it should be always initialized to 0 before first use
|
|
604 |
* @return - error code or 0 on success
|
|
605 |
*/
|
|
606 |
int pcilib_get_property_attr(pcilib_t *ctx, const char *prop, const char *attr, pcilib_value_t *val); |
|
607 |
||
608 |
/**
|
|
609 |
* Reads / computes the property value.
|
|
610 |
* @param[in,out] ctx - pcilib context
|
|
611 |
* @param[in] prop - property name (full name including path)
|
|
612 |
* @param[out] val - the register value is returned here (see \ref public_api_value),
|
|
613 |
* pcilib_clean_value() will be executed if \a val contains data. Therefore it should be always initialized to 0 before first use
|
|
614 |
* @return - error code or 0 on success
|
|
615 |
*/
|
|
616 |
int pcilib_get_property(pcilib_t *ctx, const char *prop, pcilib_value_t *val); |
|
617 |
||
618 |
/**
|
|
619 |
* Writes the property value or executes the code associated with property
|
|
620 |
* @param[in,out] ctx - pcilib context
|
|
621 |
* @param[in] prop - property name (full name including path)
|
|
622 |
* @param[out] val - the property value (see \ref public_api_value),
|
|
623 |
* @return - error code or 0 on success
|
|
624 |
*/
|
|
625 |
int pcilib_set_property(pcilib_t *ctx, const char *prop, const pcilib_value_t *val); |
|
626 |
||
627 |
/** public_api_property
|
|
628 |
* @}
|
|
629 |
*/
|
|
630 |
||
631 |
/***********************************************************************************************************//**
|
|
632 |
* \defgroup public_api_dma Public DMA API
|
|
633 |
* High speed interface for reading and writting unstructured data
|
|
634 |
* @{
|
|
635 |
*/
|
|
636 |
||
637 |
/**
|
|
638 |
* This function resolves the ID of DMA engine from its address and direction.
|
|
639 |
* It is a bit confusing, but addresses should be able to represent bi-directional
|
|
640 |
* DMA engines. Unfortunatelly, implementation often is limited to uni-directional
|
|
641 |
* engines. In this case, two DMA engines with different IDs can be virtually
|
|
642 |
* combined in a DMA engine with the uniq address. This will allow user to specify
|
|
643 |
* the same engine address in all types of accesses and we will resolve the appropriate
|
|
644 |
* engine ID depending on the requested direction.
|
|
645 |
* @param[in,out] ctx - pcilib context
|
|
646 |
* @param[in] direction - DMA direction (to/from device)
|
|
647 |
* @param[in] dma - address of DMA engine
|
|
648 |
* @return - ID of DMA engine or PCILIB_DMA_INVALID if the specified engine does not exist
|
|
649 |
*/
|
|
650 |
pcilib_dma_engine_t pcilib_find_dma_by_addr(pcilib_t *ctx, pcilib_dma_direction_t direction, pcilib_dma_engine_addr_t dma); |
|
651 |
||
652 |
/**
|
|
653 |
* Starts DMA engine. This call will allocate DMA buffers and pass their bus addresses to the hardware.
|
|
654 |
* - During the call, the C2S engine may start writting data. The written buffers are marked as
|
|
655 |
* ready and can be read-out using pcilib_stream_dma() and pcilib_read_dma() calls. If no empty
|
|
656 |
* buffers left, the C2S DMA engine will stall until some buffers are read out.
|
|
657 |
* - The S2C engine waits until the data is pushed with pcilib_push_data() call
|
|
658 |
*
|
|
659 |
* After pcilib_start_dma() call, the pcilib_stop_dma() function should be necessarily called. However,
|
|
660 |
* it will clean up the process memory, but only in some cases actually stop the DMA engine.
|
|
661 |
* This depends on \a flags passed to both pcilib_start_dma() and pcilib_stop_dma() calls.
|
|
662 |
* if PCILIB_DMA_FLAG_PERSISTENT flag is passed to the pcilib_start_dma(), the DMA engine
|
|
663 |
* will remain running unless the same flag is also passed to the pcilib_stop_dma() call.
|
|
664 |
* The allocated DMA buffers will stay intact and the hardware may continue reading / writting
|
|
665 |
* data while there is space/data left. However, the other functions of DMA API should not
|
|
666 |
* be called after pcilib_stop_dma() until new pcilib_start_dma() call is issued.
|
|
667 |
*
|
|
668 |
* The process- and thread-safety is implementation depedent. However, currently the process-
|
|
669 |
* safety is ensured while accessing the kernel memory (todo: this may get complicated if we
|
|
670 |
* provide a way to perform DMA directly to the user-supplied pages).
|
|
671 |
* The thread-safety is not provided by currently implemented DMA engines. The DMA functions
|
|
672 |
* may be called from multiple threads, but it is user responsibility to ensure that only a
|
|
673 |
* single DMA-related call is running. On other hand, the DMA and register APIs may be used
|
|
674 |
* in parallel.
|
|
675 |
*
|
|
676 |
* @param[in,out] ctx - pcilib context
|
|
677 |
* @param[in] dma - ID of DMA engine, the ID should first be resolved using pcilib_find_dma_by_addr()
|
|
678 |
* @param[in] flags - PCILIB_DMA_FLAG_PERSISTENT indicates that engine should be kept running after pcilib_stop_dma() call
|
|
679 |
* @return - error code or 0 on success
|
|
680 |
*/
|
|
62
by Suren A. Chilingaryan
Suppport DMA modes in console application (not functional yet) |
681 |
int pcilib_start_dma(pcilib_t *ctx, pcilib_dma_engine_t dma, pcilib_dma_flags_t flags); |
324
by Suren A. Chilingaryan
Documentation update |
682 |
|
683 |
/**
|
|
684 |
* Stops DMA engine or just cleans up the process-specific memory buffers (see
|
|
685 |
* pcilib_start_dma() for details). No DMA API calls allowed after this point
|
|
686 |
* until pcilib_start_dma() is called anew.
|
|
687 |
*
|
|
688 |
* @param[in,out] ctx - pcilib context
|
|
689 |
* @param[in] dma - ID of DMA engine, the ID should first be resolved using pcilib_find_dma_by_addr()
|
|
690 |
* @param[in] flags - PCILIB_DMA_FLAG_PERSISTENT indicates that engine should be actually stopped independent of the flags passed to pcilib_start_dma() call
|
|
691 |
* @return - error code or 0 on success
|
|
692 |
*/
|
|
62
by Suren A. Chilingaryan
Suppport DMA modes in console application (not functional yet) |
693 |
int pcilib_stop_dma(pcilib_t *ctx, pcilib_dma_engine_t dma, pcilib_dma_flags_t flags); |
88
by Suren A. Chilingaryan
IRQ acknowledgement support in the engine API |
694 |
|
324
by Suren A. Chilingaryan
Documentation update |
695 |
/**
|
696 |
* Tries to drop all pending data in the DMA channel. It will drop not only data currently in the DMA buffers,
|
|
697 |
* but will allow hardware to write more and will drop the newly written data as well. The standard DMA timeout
|
|
698 |
* is allowed to receive new data. If hardware continuously writes data, after #PCILIB_DMA_SKIP_TIMEOUT
|
|
699 |
* microseconds the function will exit with #PCILIB_ERROR_TIMEOUT error.
|
|
700 |
*
|
|
701 |
* @param[in,out] ctx - pcilib context
|
|
702 |
* @param[in] dma - ID of DMA engine, the ID should first be resolved using pcilib_find_dma_by_addr()
|
|
703 |
* @return - error code or 0 on success
|
|
704 |
*/
|
|
705 |
int pcilib_skip_dma(pcilib_t *ctx, pcilib_dma_engine_t dma); |
|
706 |
||
707 |
/**
|
|
708 |
* Reads data from DMA buffers and pass it to the specified callback function. The return code of the callback
|
|
709 |
* function determines if streaming should continue and how much to wait for next data to arrive before
|
|
710 |
* triggering timeout.
|
|
711 |
* The function is process- and thread-safe. The PCILIB_ERROR_BUSY will be returned immediately if DMA is used
|
|
712 |
* by another thread or process.
|
|
713 |
*
|
|
714 |
* The function waits the specified \a timeout microseconds for the first data. Afterwards, the waiting time
|
|
715 |
* for next portion of data depends on the last return code \a (ret) from callback function.
|
|
716 |
* If `ret & PCILIB_STREAMING_TIMEOUT_MASK` is
|
|
717 |
* - PCILIB_STREAMING_STOP - the streaming stops
|
|
718 |
* - PCILIB_STREAMING_CONTINUE - the standard DMA timeout will be used to wait for a new data
|
|
719 |
* - PCILIB_STREAMING_WAIT - the timeout specified in the function arguments will be used to wait for a new data
|
|
720 |
* - PCILIB_STREAMING_CHECK - the function will return if new data is not available immediately
|
|
721 |
* The function return code depends on the return code from the callback as well. If no data received within the specified
|
|
722 |
* timeout and no callback is called, the PCILIB_ERROR_TIMEOUT is returned. Otherwise, success is returned unless
|
|
723 |
* PCILIB_STREAMING_FAIL flag has been set in the callback return code before the timeout was triggered.
|
|
724 |
*
|
|
725 |
* @param[in,out] ctx - pcilib context
|
|
726 |
* @param[in] dma - ID of DMA engine, the ID should first be resolved using pcilib_find_dma_by_addr()
|
|
727 |
* @param[in] addr - instructs DMA to start reading at the specified address (not supported by existing DMA engines)
|
|
728 |
* @param[in] size - instructs DMA to read only \a size bytes (not supported by existing DMA engines)
|
|
729 |
* @param[in] flags - not used by existing DMA engines
|
|
730 |
* @param[in] timeout - specifies number of microseconds to wait before reporting timeout, special values #PCILIB_TIMEOUT_IMMEDIATE and #PCILIB_TIMEOUT_INFINITE are supported.
|
|
731 |
* @param[in] cb - callback function to call
|
|
732 |
* @param[in,out] cbattr - passed through as the first parameter of callback function
|
|
733 |
* @return - error code or 0 on success
|
|
734 |
*/
|
|
735 |
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); |
|
736 |
||
737 |
/**
|
|
738 |
* Reads data from DMA until timeout is hit, a full DMA packet is read, or the specified number of bytes are read.
|
|
739 |
* The function is process- and thread-safe. The #PCILIB_ERROR_BUSY will be returned immediately if DMA is used
|
|
740 |
* by another thread or process.
|
|
741 |
*
|
|
742 |
* We can't read arbitrary number of bytes from DMA. A full DMA packet is always read. The DMA packet is not equal
|
|
743 |
* to DMA buffer, but may consist of multiple buffers and the size may vary during run time. This may cause problems
|
|
744 |
* if not treated properly. While the number of actually read bytes is bellow the specified size, the function may
|
|
745 |
* continue to read the data. But as the new packet is started, it should fit completely in the provided buffer space
|
|
746 |
* or PCILIB_ERROR_TOOBIG error will be returned. Therefore, it is a good practice to read only a single packet at
|
|
747 |
* once and provide buffer capable to store the larges possible packet.
|
|
748 |
*
|
|
749 |
* Unless #PCILIB_DMA_FLAG_MULTIPACKET flag is specified, the function will stop after the first full packet is read.
|
|
750 |
* Otherwise, the reading will continue until all `size` bytes are read or timeout is hit. The stanard DMA timeout
|
|
751 |
* should be met while reading DMA buffers belonging to the same packet. Otherwise, PCILIB_ERROR_TIMEOUT is returned
|
|
752 |
* and number of bytes read so far is returned in the `rdsize`.
|
|
753 |
* If #PCILIB_DMA_FLAG_WAIT flag is specified, the number of microseconds specified in the `timeout` parameter are
|
|
754 |
* allowed for a new packet to come. If no new data arrived in the specified timeout, the function returns successfuly
|
|
755 |
* and number of read bytes is returned in the `rdsize`.
|
|
756 |
*
|
|
757 |
* We can't put the read data back into the DMA. Therefore, even in the case of error some data may be returned. The
|
|
758 |
* number of actually read bytes is always reported in `rdsize` and the specified amount of data is always written
|
|
759 |
* to the provided buffer.
|
|
760 |
*
|
|
761 |
* @param[in,out] ctx - pcilib context
|
|
762 |
* @param[in] dma - ID of DMA engine, the ID should first be resolved using pcilib_find_dma_by_addr()
|
|
763 |
* @param[in] addr - instructs DMA to start reading at the specified address (not supported by existing DMA engines)
|
|
764 |
* @param[in] size - specifies how many bytes should be read
|
|
765 |
* @param[in] flags - Various flags controlling the function behavior
|
|
766 |
* - #PCILIB_DMA_FLAG_MULTIPACKET indicates that multiple DMA packets will be read (not recommended, use pcilib_stream_dma() in this case)
|
|
767 |
* - #PCILIB_DMA_FLAG_WAIT indicates that we need to wait the specified timeout between consequitive DMA packets (default DMA timeout is used otherwise)
|
|
768 |
* @param[in] timeout - specifies number of microseconds to wait before reporting timeout, special values #PCILIB_TIMEOUT_IMMEDIATE and #PCILIB_TIMEOUT_INFINITE are supported.
|
|
769 |
* This parameter specifies timeout between consequtive DMA packets, the standard DMA timeout is expected between buffers belonging to the same DMA packet.
|
|
770 |
* @param[out] buf - the buffer of \a size bytes long to store the data
|
|
771 |
* @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.
|
|
772 |
* @return - error code or 0 on success. In both cases some data may be returned in the buffer, check `rdsize`.
|
|
773 |
*/
|
|
774 |
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); |
|
775 |
||
776 |
/**
|
|
777 |
* Reads data from DMA until timeout is hit, a full DMA packet is read, or the specified number of bytes are read.
|
|
778 |
* Please, check detailed explanation when reading is stopped in the description of pcilib_read_dma_custom().
|
|
779 |
* The function is process- and thread-safe. The #PCILIB_ERROR_BUSY will be returned immediately if DMA is used
|
|
780 |
* by another thread or process.
|
|
781 |
*
|
|
782 |
* The function actually executes the pcilib_read_dma_custom() without special flags and with default DMA timeout
|
|
783 |
*
|
|
784 |
* @param[in,out] ctx - pcilib context
|
|
785 |
* @param[in] dma - ID of DMA engine, the ID should first be resolved using pcilib_find_dma_by_addr()
|
|
786 |
* @param[in] addr - instructs DMA to start reading at the specified address (not supported by existing DMA engines)
|
|
787 |
* @param[in] size - specifies how many bytes should be read
|
|
788 |
* @param[out] buf - the buffer of \a size bytes long to store the data
|
|
789 |
* @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.
|
|
790 |
* @return - error code or 0 on success. In both cases some data may be returned in the buffer, check `rdsize`.
|
|
791 |
*/
|
|
792 |
int pcilib_read_dma(pcilib_t *ctx, pcilib_dma_engine_t dma, uintptr_t addr, size_t size, void *buf, size_t *rdsize); |
|
793 |
||
794 |
/**
|
|
795 |
* Pushes new data to the DMA engine. The actual behavior is implementation dependent. The successful exit does not mean
|
|
796 |
* what all data have reached hardware, but only guarantees that it is stored in DMA buffers and the hardware is instructed
|
|
797 |
* to start reading buffers. The function may return #PCILIB_ERROR_TIMEOUT is all DMA buffers are occupied and no buffers is
|
|
798 |
* read by the hardware within the specified timeout. Even if an error is returned, part of the data may be already send to
|
|
799 |
* DMA and can't be revoked back. Number of actually written bytes is always returned in the `wrsize`.
|
|
800 |
*
|
|
801 |
* The function is process- and thread-safe. The #PCILIB_ERROR_BUSY will be returned immediately if DMA is used
|
|
802 |
* by another thread or process.
|
|
803 |
*
|
|
804 |
* @param[in,out] ctx - pcilib context
|
|
805 |
* @param[in] dma - ID of DMA engine, the ID should first be resolved using pcilib_find_dma_by_addr()
|
|
806 |
* @param[in] addr - instructs DMA to start writting at the specified address (not supported by existing DMA engines)
|
|
807 |
* @param[in] size - specifies how many bytes should be written
|
|
808 |
* @param[in] flags - Various flags controlling the function behavior
|
|
809 |
* - #PCILIB_DMA_FLAG_EOP indicates that this is the last data in the DMA packet
|
|
810 |
* - #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.
|
|
811 |
* @param[in] timeout - specifies number of microseconds to wait before reporting timeout, special values #PCILIB_TIMEOUT_IMMEDIATE and #PCILIB_TIMEOUT_INFINITE are supported.
|
|
812 |
* @param[out] buf - the buffer with the data
|
|
813 |
* @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.
|
|
814 |
* @return - error code or 0 on success. In both cases some data may be written to the DMA, check `wrsize`.
|
|
815 |
*/
|
|
816 |
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); |
|
817 |
||
818 |
||
819 |
/**
|
|
820 |
* Pushes new data to the DMA engine and blocks until hardware gets it all. Even if an error has occured, a
|
|
821 |
* part of the data may be already had send to DMA and can't be revoked back. Number of actually written bytes
|
|
822 |
* is always returned in the `wrsize`.
|
|
823 |
*
|
|
824 |
* The function is process- and thread-safe. The #PCILIB_ERROR_BUSY will be returned immediately if DMA is used
|
|
825 |
* by another thread or process.
|
|
826 |
||
827 |
* The function actually executes the pcilib_push_dma() with #PCILIB_DMA_FLAG_EOP and #PCILIB_DMA_FLAG_WAIT flags set and
|
|
828 |
* the default DMA timeout.
|
|
829 |
*
|
|
830 |
* @param[in,out] ctx - pcilib context
|
|
831 |
* @param[in] dma - ID of DMA engine, the ID should first be resolved using pcilib_find_dma_by_addr()
|
|
832 |
* @param[in] addr - instructs DMA to start writting at the specified address (not supported by existing DMA engines)
|
|
833 |
* @param[in] size - specifies how many bytes should be written
|
|
834 |
* @param[out] buf - the buffer with the data
|
|
835 |
* @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.
|
|
836 |
* @return - error code or 0 on success. In both cases some data may be written to the DMA, check `wrsize`.
|
|
837 |
*/
|
|
838 |
int pcilib_write_dma(pcilib_t *ctx, pcilib_dma_engine_t dma, uintptr_t addr, size_t size, void *buf, size_t *wrsize); |
|
839 |
||
840 |
/**
|
|
841 |
* Benchmarks the DMA implementation. The reported performance may be significantly affected by several environmental variables.
|
|
842 |
* - 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.
|
|
843 |
* - 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
|
|
844 |
*
|
|
845 |
* The function is process- and thread-safe. The #PCILIB_ERROR_BUSY will be returned immediately if DMA is used
|
|
846 |
* by another thread or process.
|
|
847 |
*
|
|
848 |
* @param[in,out] ctx - pcilib context
|
|
849 |
* @param[in] dma - Address of DMA engine
|
|
850 |
* @param[in] addr - Benchmark will read and write data at the specified address (ignored by existing DMA engines)
|
|
851 |
* @param[in] size - specifies how many bytes should be read and written at each iteration
|
|
852 |
* @param[in] iterations - number of iterations to execute
|
|
853 |
* @param[in] direction - Specifies if DMA reading or writting should be benchmarked, bi-directional benchmark is possible as well
|
|
854 |
* @return - bandwidth in MiB/s (Mebibytes per second)
|
|
855 |
*/
|
|
856 |
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); |
|
857 |
||
858 |
/** public_api_dma
|
|
859 |
* @}
|
|
860 |
*/
|
|
861 |
||
862 |
/***********************************************************************************************************//**
|
|
863 |
* \defgroup public_api_irq Public IRQ API
|
|
864 |
* This is actually part of DMA API. IRQ handling is currently provided by DMA engine.
|
|
865 |
* However, the IRQs are barely used so far. Therefore, the API can be significantly changed when confronted with harsh reallity.
|
|
866 |
* @{
|
|
867 |
*/
|
|
868 |
||
63
by Suren A. Chilingaryan
Provide IRQ enable/disable call |
869 |
int pcilib_enable_irq(pcilib_t *ctx, pcilib_irq_type_t irq_type, pcilib_dma_flags_t flags); |
62
by Suren A. Chilingaryan
Suppport DMA modes in console application (not functional yet) |
870 |
int pcilib_disable_irq(pcilib_t *ctx, pcilib_dma_flags_t flags); |
88
by Suren A. Chilingaryan
IRQ acknowledgement support in the engine API |
871 |
int pcilib_wait_irq(pcilib_t *ctx, pcilib_irq_hw_source_t source, pcilib_timeout_t timeout, size_t *count); |
324
by Suren A. Chilingaryan
Documentation update |
872 |
int pcilib_acknowledge_irq(pcilib_t *ctx, pcilib_irq_type_t irq_type, pcilib_irq_source_t irq_source); |
88
by Suren A. Chilingaryan
IRQ acknowledgement support in the engine API |
873 |
int pcilib_clear_irq(pcilib_t *ctx, pcilib_irq_hw_source_t source); |
55
by Suren A. Chilingaryan
IRQ support in NWL DMA engine |
874 |
|
324
by Suren A. Chilingaryan
Documentation update |
875 |
/** public_api_irq
|
876 |
* @}
|
|
877 |
*/
|
|
878 |
||
879 |
/***********************************************************************************************************//**
|
|
880 |
* \defgroup public_api_event Public Event API
|
|
881 |
* High level API for reading the structured data from hardware
|
|
882 |
* @{
|
|
883 |
*/
|
|
884 |
||
885 |
/**
|
|
886 |
* Provides access to the context of event engine. This may be required to call implementation-specific
|
|
887 |
* functions of event engine.
|
|
888 |
* @param [in,out] ctx - pcilib context
|
|
889 |
* @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.
|
|
890 |
*/
|
|
891 |
pcilib_context_t *pcilib_get_event_engine(pcilib_t *ctx); |
|
892 |
||
893 |
/**
|
|
894 |
* Resolves the event ID based on its name.
|
|
895 |
* @param [in,out] ctx - pcilib context
|
|
896 |
* @param [in] event - the event name
|
|
897 |
* @return - the event ID or PCILIB_EVENT_INVALID if event is not found
|
|
898 |
*/
|
|
16
by Suren A. Chilingaryan
Prototype of IPECamera image protocol |
899 |
pcilib_event_t pcilib_find_event(pcilib_t *ctx, const char *event); |
324
by Suren A. Chilingaryan
Documentation update |
900 |
|
901 |
||
902 |
/**
|
|
903 |
* Analyzes current configuration, allocates necessary buffers and spawns required data processing threads.
|
|
904 |
* Depending on the implementation and the current configuration, the actual event grabbing may start already
|
|
905 |
* here. In this case, the preprocessed events will be storred in the temporary buffers and may be lost if
|
|
906 |
* pcilib_stop() is called before reading them out. Alternatively, the actual grabbing may only commend when
|
|
907 |
* the pcilib_stream() or pcilib_get_next_event() functions are executed.
|
|
908 |
* The function is non-blocking and will return immediately after allocating required memory and spawning
|
|
909 |
* of the preprocessing threads. It is important to call pcilib_stop() in the end.
|
|
910 |
*
|
|
911 |
* The grabbing will stop automatically if conditions defined using pcilib_configure_autostop() function
|
|
912 |
* are met. It also possible to stop grabbing using pcilib_stop() call at any moment.
|
|
913 |
*
|
|
914 |
* The process- and thread-safety is implementation depedent. However, normally the event engine will depend
|
|
915 |
* on DMA and if DMA engine is process-safe it will ensure the process-safety for event engine as well.
|
|
916 |
* The thread-safety is not directly ensured by currently implemented Event engines. The functions of Event
|
|
917 |
* engine may be called from multiple threads, but it is the user responsibility to ensure that only a single
|
|
918 |
* function of Event engine is running at each moment. On other hand, the Event and register APIs may be used
|
|
919 |
* in parallel.
|
|
920 |
*
|
|
921 |
* @param[in,out] ctx - pcilib context
|
|
922 |
* @param[in] ev_mask - specifies events to listen for, use #PCILIB_EVENTS_ALL to grab all events
|
|
923 |
* @param[in] flags - various implementation-specific flags controlling operation of event engine
|
|
924 |
* - #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)
|
|
925 |
* - #PCILIB_EVENT_FLAG_RAW_DATA_ONLY - disables data processing at all, only raw data will be provided in this case
|
|
926 |
* @return - error code or 0 on success
|
|
927 |
*/
|
|
928 |
int pcilib_start(pcilib_t *ctx, pcilib_event_t ev_mask, pcilib_event_flags_t flags); |
|
929 |
||
930 |
||
931 |
/**
|
|
932 |
* Stops event grabbing and optionally cleans up the used memory.
|
|
933 |
* This function operates in two modes. If #PCILIB_EVENT_FLAG_STOP_ONLY flag is specified, the
|
|
934 |
* event grabbing is stopped, but all memory structures are kept intact. This also forces the
|
|
935 |
* blocked pcilib_stream() and pcilib_get_next_event() to return after a short while.
|
|
936 |
||
937 |
* Unlike DMA engine, the event engine is not persistent and is always completely stopped when
|
|
938 |
* application is finished. Therefore, later the pcilib_stop() should be necessarily called
|
|
939 |
* again without #PCILIB_EVENT_FLAG_STOP_ONLY flag to commend full clean up and release all
|
|
940 |
* used memory. Such call may only be issued when no threads are using Event engine any more.
|
|
941 |
* There should be no functions waiting for next event to appear and all of the obtained event
|
|
942 |
* data should be already returned back to the system.
|
|
943 |
*
|
|
944 |
* pcilib_stop executed with #PCILIB_EVENT_FLAG_STOP_ONLY is thread safe. The full version of
|
|
945 |
* the function is not and should be never called in parallel with any other action of the
|
|
946 |
* event engine. Actually, it is thread safe in the case of ipecamera, but this is not
|
|
947 |
* guaranteed for other event engines.
|
|
948 |
*
|
|
949 |
* @param[in,out] ctx - pcilib context
|
|
950 |
* @param[in] flags - flags specifying operation mode
|
|
951 |
* - #PCILIB_EVENT_FLAG_STOP_ONLY - instructs library to keep all the data structures intact and to onlystop the data grabbing
|
|
952 |
* @return - error code or 0 on success
|
|
953 |
*/
|
|
954 |
int pcilib_stop(pcilib_t *ctx, pcilib_event_flags_t flags); |
|
955 |
||
956 |
/**
|
|
957 |
* Streams the incomming events to the provided callback function. If Event engine is not started
|
|
958 |
* yet, it will be started and terminated upon the completion of the call. The streaming will
|
|
959 |
* continue while Event engine is started and the callback function does not return an error (negative)
|
|
960 |
* or #PCILIB_STREAMING_STOP.
|
|
961 |
*
|
|
962 |
* The callback is called only when all the data associated with the event is received from hardware.
|
|
963 |
* So, the raw data is necessarily present, but availability of alternative data formats is
|
|
964 |
* optional. Depending on the implementation and current configuration, the data decoding can be
|
|
965 |
* performed beforehand, in parallel with callback execution, or only them the data is
|
|
966 |
* requested with pcilib_get_data() or pcilib_copy_data() calls.
|
|
967 |
*
|
|
968 |
* The function is thread-safe. The multiple requests to pcilib_stream() and pcilib_get_next_event()
|
|
969 |
* will be automatically serialized by the event engine. The pcilib_stream() is running in the
|
|
970 |
* single thread and no new calls to callback are issued until currently executed callback
|
|
971 |
* returns. The client application may get hold on the data from multiple events simultaneously.
|
|
972 |
* However, the data could be overwritten meanwhile by the hardware. The pcilib_return_data()
|
|
973 |
* will inform if it has happened by returning #PCILIB_ERROR_OVERWRITTEN.
|
|
974 |
*
|
|
975 |
* @param[in,out] ctx - pcilib context
|
|
976 |
* @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
|
|
977 |
* @param[in,out] user - used data is passed through as the last parameter of callback function
|
|
978 |
* @return - error code or 0 on success
|
|
979 |
*/
|
|
980 |
int pcilib_stream(pcilib_t *ctx, pcilib_event_callback_t callback, void *user); |
|
981 |
||
982 |
/**
|
|
983 |
* Waits until the next event is available.
|
|
984 |
* The event is only returned when all the data associated with the event is received from hardware.
|
|
985 |
* So, the raw data is necessarily present, but availability of alternative data formats is
|
|
986 |
* optional. Depending on the implementation and current configuration, the data decoding can be
|
|
987 |
* performed beforehand, in parallel, or only them the data is requested with pcilib_get_data()
|
|
988 |
* or pcilib_copy_data() calls.
|
|
989 |
*
|
|
990 |
* The function is thread-safe. The multiple requests to pcilib_stream() and pcilib_get_next_event()
|
|
991 |
* will be automatically serialized by the event engine. The client application may get hold on
|
|
992 |
* the data from multiple events simultaneously. However, the data could be overwritten meanwhile
|
|
993 |
* by the hardware. The pcilib_return_data() will inform if it has happened by returning
|
|
994 |
* #PCILIB_ERROR_OVERWRITTEN.
|
|
995 |
*
|
|
996 |
* @param[in,out] ctx - pcilib context
|
|
997 |
* @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.
|
|
998 |
* @param[out] evid - the event ID is returned in this parameter
|
|
999 |
* @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.
|
|
1000 |
If big enough info buffer is provided, this additional information will be copied as well. Otherwise only standard information is provided.
|
|
1001 |
* @param[out] info - The information about the recorded event is written to `info`
|
|
1002 |
* @return - error code or 0 on success
|
|
1003 |
*/
|
|
1004 |
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); |
|
1005 |
||
1006 |
/**
|
|
1007 |
* Requests the streaming the rawdata from the event engine. The callback will be called
|
|
1008 |
* each time new DMA packet is received. It is the fastest way to acuqire data.
|
|
1009 |
* No memory copies performed and DMA buffers are directly passed to the specified callback.
|
|
1010 |
* However, to prevent data loss, no long processing is allowed is only expected to copy data
|
|
1011 |
* into the appropriate place and return control to the event engine.
|
|
1012 |
*
|
|
1013 |
* This function should be exectued before the grabbing is started with pcilib_start().
|
|
1014 |
* The performance can be boosted further by disabling any data processing within the event
|
|
1015 |
* engine. This is achieved by passing the #PCILIB_EVENT_FLAG_RAW_DATA_ONLY flag to pcilib_start()
|
|
1016 |
* function while starting the grabbing.
|
|
1017 |
*
|
|
1018 |
* @param[in,out] ctx - pcilib context
|
|
1019 |
* @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
|
|
1020 |
* @param[in,out] user - used data is passed through as the last parameter of callback function
|
|
1021 |
* @return - error code or 0 on success
|
|
1022 |
*/
|
|
1023 |
int pcilib_configure_rawdata_callback(pcilib_t *ctx, pcilib_event_rawdata_callback_t callback, void *user); |
|
1024 |
||
1025 |
/**
|
|
1026 |
* Configures conditions when the grabbing will be stopped automatically. The recording of new events may be
|
|
1027 |
* stopped after reaching max_events records or when the specified amount of time is elapsed whatever happens
|
|
1028 |
* first. However, the pcilib_stop() function still must be called afterwards.
|
|
1029 |
*
|
|
1030 |
* This function should be exectued before the grabbing is started with pcilib_start().
|
|
1031 |
* NOTE that this options might not be respected if grabbing is started with the
|
|
1032 |
* #PCILIB_EVENT_FLAG_RAW_DATA_ONLY flag specified.
|
|
1033 |
*
|
|
1034 |
* @param[in,out] ctx - pcilib context
|
|
1035 |
* @param[in] max_events - specifies number of events after which the grabbing is stopped
|
|
1036 |
* @param[in] duration - specifies number of microseconds to run the grabbing, special values #PCILIB_TIMEOUT_IMMEDIATE and #PCILIB_TIMEOUT_INFINITE are supported.
|
|
1037 |
* @return - error code or 0 on success
|
|
1038 |
*/
|
|
1039 |
int pcilib_configure_autostop(pcilib_t *ctx, size_t max_events, pcilib_timeout_t duration); |
|
1040 |
||
1041 |
/**
|
|
1042 |
* Request the auto-triggering while grabbing. The software triggering is currently not supported (but planned).
|
|
1043 |
* Therefore it is fully relied on hardware support. If no hardware support is available, #PCILIB_ERROR_NOTSUPPORTED
|
|
1044 |
* will be returned.
|
|
1045 |
*
|
|
1046 |
* This function should be exectued before the grabbing is started with pcilib_start().
|
|
1047 |
*
|
|
1048 |
* @param[in,out] ctx - pcilib context
|
|
1049 |
* @param[in] interval - instructs hardware that each `interval` microseconds a new trigger should be issued
|
|
1050 |
* @param[in] event - specifies ID of the event which will be triggered
|
|
1051 |
* @param[in] trigger_size - specifies the size of `trigger` buffer
|
|
1052 |
* @param[in] trigger_data - this implementation-specific buffer which will be passed through to the Event engine
|
|
1053 |
* @return - error code or 0 on success
|
|
1054 |
*/
|
|
1055 |
int pcilib_configure_autotrigger(pcilib_t *ctx, pcilib_timeout_t interval, pcilib_event_t event, size_t trigger_size, void *trigger_data); |
|
1056 |
||
1057 |
/**
|
|
1058 |
* Issues a single software trigger for the specified event. No hardware support is required. The function
|
|
1059 |
* is fully thread safe and can be called while other thread is blocked in the pcilib_stream() or pcilib_get_next_event()
|
|
1060 |
* calls.
|
|
1061 |
*
|
|
1062 |
* @param[in,out] ctx - pcilib context
|
|
1063 |
* @param[in] event - specifies ID of the event to trigger
|
|
1064 |
* @param[in] trigger_size - specifies the size of `trigger` buffer
|
|
1065 |
* @param[in] trigger_data - this implementation-specific buffer which will be passed through to the Event engine
|
|
1066 |
* @return - error code or 0 on success
|
|
1067 |
*/
|
|
1068 |
int pcilib_trigger(pcilib_t *ctx, pcilib_event_t event, size_t trigger_size, void *trigger_data); |
|
1069 |
||
1070 |
/** public_api_event
|
|
1071 |
* @}
|
|
1072 |
*/
|
|
1073 |
||
1074 |
/***********************************************************************************************************//**
|
|
1075 |
* \defgroup public_api_event_data Public Event Data API
|
|
1076 |
* A part of Event API actually providing access to the data
|
|
1077 |
* @{
|
|
1078 |
*/
|
|
1079 |
||
1080 |
/**
|
|
1081 |
* Resolves the data type based on its name.
|
|
1082 |
* @param[in,out] ctx - pcilib context
|
|
1083 |
* @param[in] event - the ID of the event producing the data
|
|
1084 |
* @param[in] data_type - the name of data type
|
|
1085 |
* @return - the data type or PCILIB_EVENT_DATA_TYPE_INVALID if the specified type is not found
|
|
1086 |
*/
|
|
117
by Suren A. Chilingaryan
new event architecture, first trial |
1087 |
pcilib_event_data_type_t pcilib_find_event_data_type(pcilib_t *ctx, pcilib_event_t event, const char *data_type); |
324
by Suren A. Chilingaryan
Documentation update |
1088 |
|
1089 |
/**
|
|
1090 |
* This is a simples way to grab the data from the event engine. The event engine is started, a software trigger
|
|
1091 |
* for the specified event is issued if `timeout` is equal to PCILIB_TIMEOUT_IMMEDIATE, event is grabbed and the
|
|
1092 |
* default data is copied into the user buffer. Then, the grabbing is stopped.
|
|
1093 |
* @param[in,out] ctx - pcilib context
|
|
1094 |
* @param[in] event - the event to trigger and/or event mask to grab
|
|
1095 |
* @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
|
|
1096 |
* @param[in,out] data - Either contains a pointer to user-supplied buffer where the data will be written or pointer to NULL otherwise.
|
|
1097 |
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.
|
|
1098 |
In case of failure, the content of data is undefined.
|
|
1099 |
* @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
|
|
1100 |
* @return - error code or 0 on success
|
|
1101 |
*/
|
|
1102 |
int pcilib_grab(pcilib_t *ctx, pcilib_event_t event, size_t *size, void **data, pcilib_timeout_t timeout); |
|
1103 |
||
1104 |
/**
|
|
1105 |
* Copies the data of the specified type associated with the specified event into the provided buffer. May return #PCILIB_ERROR_OVERWRITTEN
|
|
1106 |
* if the data was overwritten during the call.
|
|
1107 |
*
|
|
1108 |
* @param[in,out] ctx - pcilib context
|
|
1109 |
* @param[in] event_id - specifies the ID of event to get data from
|
|
1110 |
* @param[in] data_type - specifies the desired type of data
|
|
1111 |
- PCILIB_EVENT_DATA will request the default data type
|
|
1112 |
- PCILIB_EVENT_RAW_DATA will request the raw data
|
|
1113 |
- The other types of data may be defined by event engine
|
|
1114 |
* @param[in] size - specifies the size of provided buffer in bytes
|
|
1115 |
* @param[out] buf - the data will be copied in this buffer if it is big enough, otherwise #PCILIB_ERROR_TOOBIG will be returned
|
|
1116 |
* @param[out] retsize - the number of actually written bytes will be returned in this parameter
|
|
1117 |
* @return - error code or 0 on success
|
|
1118 |
*/
|
|
1119 |
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); |
|
1120 |
||
1121 |
/**
|
|
1122 |
* Copies the data of the specified type associated with the specified event into the provided buffer. May return #PCILIB_ERROR_OVERWRITTEN
|
|
1123 |
* if the data was overwritten during the call. This is very similar to pcilib_copy_data(), but allows to specify implementation specific
|
|
1124 |
* argument explaining the requested data format.
|
|
1125 |
*
|
|
1126 |
* @param[in,out] ctx - pcilib context
|
|
1127 |
* @param[in] event_id - specifies the ID of event to get data from
|
|
1128 |
* @param[in] data_type - specifies the desired type of data
|
|
1129 |
- PCILIB_EVENT_DATA will request the default data type
|
|
1130 |
- PCILIB_EVENT_RAW_DATA will request the raw data
|
|
1131 |
- The other types of data may be defined by event engine
|
|
1132 |
* @param[in] arg_size - specifies the size of `arg` in bytes
|
|
1133 |
* @param[in] arg - implementation-specific argument expalining the requested data format
|
|
1134 |
* @param[in] size - specifies the size of provided buffer in bytes
|
|
1135 |
* @param[out] buf - the data will be copied in this buffer if it is big enough, otherwise #PCILIB_ERROR_TOOBIG will be returned
|
|
1136 |
* @param[out] retsize - the number of actually written bytes will be returned in this parameter
|
|
1137 |
* @return - error code or 0 on success
|
|
1138 |
*/
|
|
1139 |
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); |
|
1140 |
||
1141 |
||
1142 |
/**
|
|
1143 |
* Returns pointer to the data of the specified type associated with the specified event. The data should be returned back to the
|
|
1144 |
* Event engine using pcilib_return_data() call. WARNING: Current implementation may overwrite the data before the pcilib_return_data()
|
|
1145 |
* call is executed. In this case the #PCILIB_ERROR_OVERWRITTEN error will be returned by pcilib_return_data() call. I guess this is
|
|
1146 |
* a bad idea and have to be changed. Meanwhile, for the ipecamera implementation the image data will be never overwritten. However,
|
|
1147 |
* the raw data may get overwritten and the error code of pcilib_return_data() has to be consulted.
|
|
1148 |
*
|
|
1149 |
* @param[in,out] ctx - pcilib context
|
|
1150 |
* @param[in] event_id - specifies the ID of event to get data from
|
|
1151 |
* @param[in] data_type - specifies the desired type of data
|
|
1152 |
- PCILIB_EVENT_DATA will request the default data type
|
|
1153 |
- PCILIB_EVENT_RAW_DATA will request the raw data
|
|
1154 |
- The other types of data may be defined by event engine
|
|
1155 |
* @param[out] size_or_err - contain error code if function returns NULL or number of actually written bytes otherwise
|
|
1156 |
* @return - the pointer to the requested data or NULL otherwise
|
|
1157 |
*/
|
|
1158 |
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); |
|
1159 |
||
1160 |
/**
|
|
1161 |
* Returns pointer to the data of the specified type associated with the specified event. The data should be returned back to the
|
|
1162 |
* Event engine using pcilib_return_data() call. WARNING: Current implementation may overwrite the data before the pcilib_return_data()
|
|
1163 |
* call is executed, @see pcilib_get_data() for details. Overall this function is very similar to pcilib_get_data(), but allows to
|
|
1164 |
* specify implementation specific argument explaining the requested data format.
|
|
1165 |
*
|
|
1166 |
* @param[in,out] ctx - pcilib context
|
|
1167 |
* @param[in] event_id - specifies the ID of event to get data from
|
|
1168 |
* @param[in] data_type - specifies the desired type of data
|
|
1169 |
- PCILIB_EVENT_DATA will request the default data type
|
|
1170 |
- PCILIB_EVENT_RAW_DATA will request the raw data
|
|
1171 |
- The other types of data may be defined by event engine
|
|
1172 |
* @param[in] arg_size - specifies the size of `arg` in bytes
|
|
1173 |
* @param[in] arg - implementation-specific argument expalining the requested data format
|
|
1174 |
* @param[out] size_or_err - contain error code if function returns NULL or number of actually written bytes otherwise
|
|
1175 |
* @return - the pointer to the requested data or NULL otherwise
|
|
1176 |
*/
|
|
1177 |
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); |
|
1178 |
||
1179 |
||
1180 |
/*
|
|
1181 |
* This function returns data obtained using pcilib_get_data() or pcilib_get_data_with_argument() calls.
|
|
1182 |
* It occasionally may return #PCILIB_ERROR_OVERWRITTEN error indicating that the data was overwritten
|
|
1183 |
* between pcilib_get_data() and pcilib_return_data() calls, @see pcilib_get_data() for details.
|
|
1184 |
* @param[in,out] ctx - pcilib context
|
|
1185 |
* @param[in] event_id - specifies the ID of event to get data from
|
|
1186 |
* @param[in] data_type - specifies the data type request in the pcilib_get_data() call
|
|
1187 |
* @param[in,out] data - specifies the buffer returned by pcilib_get_data() call
|
|
1188 |
* @return - #PCILIB_ERROR_OVERWRITTEN or 0 if data is still valid
|
|
1189 |
*/
|
|
1190 |
int pcilib_return_data(pcilib_t *ctx, pcilib_event_id_t event_id, pcilib_event_data_type_t data_type, void *data); |
|
1191 |
||
1192 |
/** public_api_event_data
|
|
1193 |
* @}
|
|
1194 |
*/
|
|
1195 |
||
1196 |
||
1197 |
/***********************************************************************************************************//**
|
|
1198 |
* \defgroup public_api_value Polymorphic values
|
|
1199 |
* API for manipulation of data formats and units
|
|
1200 |
* @{
|
|
1201 |
*/
|
|
1202 |
||
1203 |
/**
|
|
1204 |
* Destroys the polymorphic value and frees any extra used memory, but does not free #pcilib_value_t itself
|
|
1205 |
* @param[in] ctx - pcilib context
|
|
1206 |
* @param[in,out] val - initialized polymorphic value
|
|
1207 |
*/
|
|
309
by Suren A. Chilingaryan
Base functions for views |
1208 |
void pcilib_clean_value(pcilib_t *ctx, pcilib_value_t *val); |
324
by Suren A. Chilingaryan
Documentation update |
1209 |
|
1210 |
/**
|
|
1211 |
* Copies the polymorphic value. If `dst` already contains the value, cleans it first.
|
|
1212 |
* Therefore, before first usage the value should be always initialized to 0.
|
|
1213 |
* @param[in] ctx - pcilib context
|
|
1214 |
* @param[in,out] dst - initialized polymorphic value
|
|
1215 |
* @param[in] src - initialized polymorphic value
|
|
1216 |
* @return - 0 on success or memory error
|
|
1217 |
*/
|
|
309
by Suren A. Chilingaryan
Base functions for views |
1218 |
int pcilib_copy_value(pcilib_t *ctx, pcilib_value_t *dst, const pcilib_value_t *src); |
324
by Suren A. Chilingaryan
Documentation update |
1219 |
|
1220 |
/**
|
|
1221 |
* Initializes the polymorphic value from floating-point number. If `val` already contains the value, cleans it first.
|
|
1222 |
* Therefore, before first usage the value should be always initialized to 0.
|
|
1223 |
* @param[in] ctx - pcilib context
|
|
1224 |
* @param[in,out] val - initialized polymorphic value
|
|
1225 |
* @param[in] fval - initializer
|
|
1226 |
* @return - 0 on success or memory error
|
|
1227 |
*/
|
|
309
by Suren A. Chilingaryan
Base functions for views |
1228 |
int pcilib_set_value_from_float(pcilib_t *ctx, pcilib_value_t *val, double fval); |
324
by Suren A. Chilingaryan
Documentation update |
1229 |
|
1230 |
/**
|
|
1231 |
* Initializes the polymorphic value from integer. If `val` already contains the value, cleans it first.
|
|
1232 |
* Therefore, before first usage the value should be always initialized to 0.
|
|
1233 |
* @param[in] ctx - pcilib context
|
|
1234 |
* @param[in,out] val - initialized polymorphic value
|
|
1235 |
* @param[in] ival - initializer
|
|
1236 |
* @return - 0 on success or memory error
|
|
1237 |
*/
|
|
309
by Suren A. Chilingaryan
Base functions for views |
1238 |
int pcilib_set_value_from_int(pcilib_t *ctx, pcilib_value_t *val, long ival); |
324
by Suren A. Chilingaryan
Documentation update |
1239 |
|
1240 |
/**
|
|
1241 |
* Initializes the polymorphic value from the register value. If `val` already contains the value, cleans it first.
|
|
1242 |
* Therefore, before first usage the value should be always initialized to 0.
|
|
1243 |
* @param[in] ctx - pcilib context
|
|
1244 |
* @param[in,out] val - initialized polymorphic value
|
|
1245 |
* @param[in] regval - initializer
|
|
1246 |
* @return - 0 on success or memory error
|
|
1247 |
*/
|
|
1248 |
int pcilib_set_value_from_register_value(pcilib_t *ctx, pcilib_value_t *val, pcilib_register_value_t regval); |
|
1249 |
||
1250 |
/**
|
|
1251 |
* Initializes the polymorphic value from the static string. The string is not copied, but only referenced.
|
|
1252 |
* If `val` already contains the value, cleans it first. Therefore, before first usage the value should be always initialized to 0.
|
|
1253 |
* @param[in] ctx - pcilib context
|
|
1254 |
* @param[in,out] val - initialized polymorphic value
|
|
1255 |
* @param[in] str - initializer
|
|
1256 |
* @return - 0 on success or memory error
|
|
1257 |
*/
|
|
1258 |
int pcilib_set_value_from_static_string(pcilib_t *ctx, pcilib_value_t *val, const char *str); |
|
1259 |
||
1260 |
/**
|
|
353
by Suren A. Chilingaryan
Merge Python scripting support from Vasiliy Chernov |
1261 |
* Initializes the polymorphic value from the string. The string is copied.
|
1262 |
* If `val` already contains the value, cleans it first. Therefore, before first usage the value should be always initialized to 0.
|
|
1263 |
* @param[in] ctx - pcilib context
|
|
1264 |
* @param[in,out] val - initialized polymorphic value
|
|
1265 |
* @param[in] str - initializer
|
|
1266 |
* @return - 0 on success or memory error
|
|
1267 |
*/
|
|
361
by Suren A. Chilingaryan
Documentation update |
1268 |
int pcilib_set_value_from_string(pcilib_t *ctx, pcilib_value_t *val, const char *str); |
353
by Suren A. Chilingaryan
Merge Python scripting support from Vasiliy Chernov |
1269 |
|
1270 |
/**
|
|
324
by Suren A. Chilingaryan
Documentation update |
1271 |
* Get the floating point value from the polymorphic type. May inmply impliced type conversion,
|
1272 |
* for isntance parsing the number from the string. Will return 0. and report an error if
|
|
1273 |
* conversion failed.
|
|
1274 |
* @param[in] ctx - pcilib context
|
|
1275 |
* @param[in] val - initialized polymorphic value of arbitrary type
|
|
1276 |
* @param[out] err - error code or 0 on sccuess
|
|
1277 |
* @return - the value or 0 in the case of error
|
|
1278 |
*/
|
|
312
by Suren A. Chilingaryan
Support transform views |
1279 |
double pcilib_get_value_as_float(pcilib_t *ctx, const pcilib_value_t *val, int *err); |
324
by Suren A. Chilingaryan
Documentation update |
1280 |
|
1281 |
/**
|
|
1282 |
* Get the integer value from the polymorphic type. May inmply impliced type conversion
|
|
1283 |
* resulting in precision loss if the `val` stores floating-point number. The warning
|
|
1284 |
* message will be printed in this case, but no error returned.
|
|
1285 |
* @param[in] ctx - pcilib context
|
|
1286 |
* @param[in] val - initialized polymorphic value of arbitrary type
|
|
1287 |
* @param[out] err - error code or 0 on sccuess
|
|
1288 |
* @return - the value or 0 in the case of error
|
|
1289 |
*/
|
|
312
by Suren A. Chilingaryan
Support transform views |
1290 |
long pcilib_get_value_as_int(pcilib_t *ctx, const pcilib_value_t *val, int *err); |
324
by Suren A. Chilingaryan
Documentation update |
1291 |
|
1292 |
/**
|
|
1293 |
* Get the integer value from the polymorphic type. May inmply impliced type conversion
|
|
1294 |
* resulting in precision loss if the `val` stores floating-point number or complete
|
|
1295 |
* data corruption if negative number is stored. The warning message will be printed
|
|
1296 |
* in this case, but no error returned.
|
|
1297 |
* @param[in] ctx - pcilib context
|
|
1298 |
* @param[in] val - initialized polymorphic value of arbitrary type
|
|
1299 |
* @param[out] err - error code or 0 on sccuess
|
|
1300 |
* @return - the value or 0 in the case of error
|
|
1301 |
*/
|
|
312
by Suren A. Chilingaryan
Support transform views |
1302 |
pcilib_register_value_t pcilib_get_value_as_register_value(pcilib_t *ctx, const pcilib_value_t *val, int *err); |
324
by Suren A. Chilingaryan
Documentation update |
1303 |
|
1304 |
||
1305 |
/**
|
|
1306 |
* Convert the units of the supplied polymorphic value. The error will be reported if currently used units of the
|
|
1307 |
* value are unknown, the requested conversion is not supported, or the value is not numeric.
|
|
1308 |
* @param[in] ctx - pcilib context
|
|
1309 |
* @param[in,out] val - initialized polymorphic value of any numeric type
|
|
1310 |
* @param[in] unit_name - the requested units
|
|
1311 |
* @return err - error code or 0 on sccuess
|
|
1312 |
*/
|
|
309
by Suren A. Chilingaryan
Base functions for views |
1313 |
int pcilib_convert_value_unit(pcilib_t *ctx, pcilib_value_t *val, const char *unit_name); |
324
by Suren A. Chilingaryan
Documentation update |
1314 |
|
1315 |
/**
|
|
1316 |
* Convert the type of the supplied polymorphic value. The error will be reported if conversion
|
|
1317 |
* is not supported or failed due to non-conformant content.
|
|
1318 |
* @param[in] ctx - pcilib context
|
|
1319 |
* @param[in,out] val - initialized polymorphic value of any type
|
|
1320 |
* @param[in] type - the requested type
|
|
1321 |
* @return err - error code or 0 on sccuess
|
|
1322 |
*/
|
|
309
by Suren A. Chilingaryan
Base functions for views |
1323 |
int pcilib_convert_value_type(pcilib_t *ctx, pcilib_value_t *val, pcilib_value_type_t type); |
1324 |
||
324
by Suren A. Chilingaryan
Documentation update |
1325 |
/** public_api_value
|
1326 |
* @}
|
|
1327 |
*/
|
|
1328 |
||
15
by Suren A. Chilingaryan
Infrastructure for event API |
1329 |
|
277
by Suren A. Chilingaryan
Keep C++ compilers happy |
1330 |
#ifdef __cplusplus
|
1331 |
}
|
|
1332 |
#endif
|
|
1333 |
||
365
by Suren A. Chilingaryan
Restructure driver headers |
1334 |
#endif /* _PCILIB_H */ |