summaryrefslogtreecommitdiffstats
path: root/pcilib
diff options
context:
space:
mode:
authorSuren A. Chilingaryan <csa@suren.me>2016-03-02 05:47:04 +0100
committerSuren A. Chilingaryan <csa@suren.me>2016-03-02 05:47:04 +0100
commit8933c45c177556353570f92513bb49f182ce3be8 (patch)
tree08ee02c6a6e97f72ad5cdb23717f9600813cff6d /pcilib
parent3c58980b3ca558096340e51c215897e8614ba00a (diff)
downloadpcitool-8933c45c177556353570f92513bb49f182ce3be8.tar.gz
pcitool-8933c45c177556353570f92513bb49f182ce3be8.tar.bz2
pcitool-8933c45c177556353570f92513bb49f182ce3be8.tar.xz
pcitool-8933c45c177556353570f92513bb49f182ce3be8.zip
Documentation update
Diffstat (limited to 'pcilib')
-rw-r--r--pcilib/bank.h114
-rw-r--r--pcilib/bar.h14
-rw-r--r--pcilib/cpu.h15
-rw-r--r--pcilib/datacpy.h54
-rw-r--r--pcilib/kmem.h28
-rw-r--r--pcilib/memcpy.h52
-rw-r--r--pcilib/pcilib.h2
-rw-r--r--pcilib/plugin.h53
-rw-r--r--pcilib/timing.h55
-rw-r--r--pcilib/tools.h52
10 files changed, 416 insertions, 23 deletions
diff --git a/pcilib/bank.h b/pcilib/bank.h
index e7be825..00ba688 100644
--- a/pcilib/bank.h
+++ b/pcilib/bank.h
@@ -171,21 +171,135 @@ int pcilib_add_register_protocols(pcilib_t *ctx, pcilib_model_modification_flags
*/
int pcilib_add_register_ranges(pcilib_t *ctx, pcilib_model_modification_flags_t flags, size_t n, const pcilib_register_range_t *ranges);
+/**
+ * Find the register bank id (offset in \a banks array) corresponding to the specified bank address
+ * @param[in,out] ctx - pcilib context
+ * @param[in] bank - the address of register bank
+ * @return - bank id or PCILIB_REGISTER_BANK_INVALID if bank is not found
+ */
pcilib_register_bank_t pcilib_find_register_bank_by_addr(pcilib_t *ctx, pcilib_register_bank_addr_t bank);
+
+/**
+ * Find the register bank id (offset in \a banks array) corresponding to the specified bank name
+ * @param[in,out] ctx - pcilib context
+ * @param[in] bankname - the name of register bank
+ * @return - bank id or PCILIB_REGISTER_BANK_INVALID if bank is not found
+ */
pcilib_register_bank_t pcilib_find_register_bank_by_name(pcilib_t *ctx, const char *bankname);
+
+/**
+ * Find the register bank id (offset in \a banks array) corresponding to the specified bank name or address
+ * @param[in,out] ctx - pcilib context
+ * @param[in] bank - either the name or the address of the required register bank
+ * @return - bank id or PCILIB_REGISTER_BANK_INVALID if bank is not found
+ */
pcilib_register_bank_t pcilib_find_register_bank(pcilib_t *ctx, const char *bank);
+/**
+ * Find the register protocol id (offset in \a protocols array) corresponding to the specified protocol address
+ * @param[in,out] ctx - pcilib context
+ * @param[in] protocol - the address of register protocol
+ * @return - protocol id or PCILIB_REGISTER_PROTOCOL_INVALID if register protocol is not found
+ */
pcilib_register_protocol_t pcilib_find_register_protocol_by_addr(pcilib_t *ctx, pcilib_register_protocol_addr_t protocol);
+
+/**
+ * Find the register protocol id (offset in \a protocols array) corresponding to the specified protocol name
+ * @param[in,out] ctx - pcilib context
+ * @param[in] name - the name of register protocol
+ * @return - protocol id or PCILIB_REGISTER_PROTOCOL_INVALID if register protocol is not found
+ */
pcilib_register_protocol_t pcilib_find_register_protocol_by_name(pcilib_t *ctx, const char *name);
+
+/**
+ * Find the register protocol id (offset in \a protocols array) corresponding to the specified protocol name or address
+ * @param[in,out] ctx - pcilib context
+ * @param[in] name - either the name or the address of the required register protocol
+ * @return - protocol id or PCILIB_REGISTER_PROTOCOL_INVALID if register protocol is not found
+ */
pcilib_register_protocol_t pcilib_find_register_protocol(pcilib_t *ctx, const char *name);
+/**
+ * Resolves the address of the specified register bank. The address of the register0 in the bank is returned.
+ *
+ * All address types (virtual address in process address space, physical address, or bus address) can be resolved.
+ * The caller has also to specify the requested access mode (read, write, read/write) and the error will be returned
+ * if the requested access type is not possible.
+ *
+ * @param[in,out] ctx - pcilib context
+ * @param[in] flags - specifies the type of required address (virtual, physical, or bus) and the required access (ro/wo/rw)
+ * @param[in] bank - the id of register bank
+ * @return - the resolved address or PCILIB_ADDRESS_INVALID on error
+ */
uintptr_t pcilib_resolve_bank_address_by_id(pcilib_t *ctx, pcilib_address_resolution_flags_t flags, pcilib_register_bank_t bank);
+
+/**
+ * Resolves the address of the specified register bank. The address of the register0 in the bank is returned.
+ *
+ * All address types (virtual address in process address space, physical address, or bus address) can be resolved.
+ * The caller has also to specify the requested access mode (read, write, read/write) and the error will be returned
+ * if the requested access type is not possible.
+ *
+ * @param[in,out] ctx - pcilib context
+ * @param[in] flags - specifies the type of required address (virtual, physical, or bus) and the required access (ro/wo/rw)
+ * @param[in] bank - the name of register bank
+ * @return - the resolved address or PCILIB_ADDRESS_INVALID on error
+ */
uintptr_t pcilib_resolve_bank_address(pcilib_t *ctx, pcilib_address_resolution_flags_t flags, const char *bank);
+/**
+ * Resolves the address of the specified register.
+ *
+ * All address types (virtual address in process address space, physical address, or bus address) can be resolved.
+ * The caller has also to specify the requested access mode (read, write, read/write) and the error will be returned
+ * if the requested access type is not possible.
+ *
+ * @param[in,out] ctx - pcilib context
+ * @param[in] flags - specifies the type of required address (virtual, physical, or bus) and the required access (ro/wo/rw)
+ * @param[in] reg - the id of register
+ * @return - the resolved address or PCILIB_ADDRESS_INVALID on error
+ */
uintptr_t pcilib_resolve_register_address_by_id(pcilib_t *ctx, pcilib_address_resolution_flags_t flags, pcilib_register_t reg);
+
+/**
+ * Resolves the address of the specified register.
+ *
+ * All address types (virtual address in process address space, physical address, or bus address) can be resolved.
+ * The caller has also to specify the requested access mode (read, write, read/write) and the error will be returned
+ * if the requested access type is not possible.
+ *
+ * @param[in,out] ctx - pcilib context
+ * @param[in] flags - specifies the type of required address (virtual, physical, or bus) and the required access (ro/wo/rw)
+ * @param[in] bank - should specify the bank name if register with the same name may occur in multiple banks, NULL otherwise
+ * @param[in] regname - the name of the register
+ * @return - the resolved address or PCILIB_ADDRESS_INVALID on error
+ */
uintptr_t pcilib_resolve_register_address(pcilib_t *ctx, pcilib_address_resolution_flags_t flags, const char *bank, const char *regname);
+/**
+ * Extracts additional information about the specified register bank. The additional information
+ * is model-specific and are provided as extra XML attributes in XML-described register bank.
+ * The available attributes are only restricted by used XSD schema.
+ * @param[in,out] ctx - pcilib context
+ * @param[in] bank - register bank id
+ * @param[in] attr - requested attribute name
+ * @param[in,out] val - the value of attribute is returned here (see \ref public_api_value),
+ * pcilib_clean_value() will be executed if \a val contains data. Therefore it should be always initialized to 0 before first use
+ * @return - error code or 0 on success
+ */
int pcilib_get_register_bank_attr_by_id(pcilib_t *ctx, pcilib_register_bank_t bank, const char *attr, pcilib_value_t *val);
+
+/**
+ * Extracts additional information about the specified register bank. The additional information
+ * is model-specific and are provided as extra XML attributes in XML-described register bank.
+ * The available attributes are only restricted by used XSD schema.
+ * @param[in,out] ctx - pcilib context
+ * @param[in] bankname - the name of register bank
+ * @param[in] attr - requested attribute name
+ * @param[in,out] val - the value of attribute is returned here (see \ref public_api_value),
+ * pcilib_clean_value() will be executed if \a val contains data. Therefore it should be always initialized to 0 before first use
+ * @return - error code or 0 on success
+ */
int pcilib_get_register_bank_attr(pcilib_t *ctx, const char *bankname, const char *attr, pcilib_value_t *val);
#ifdef __cplusplus
diff --git a/pcilib/bar.h b/pcilib/bar.h
index 3c0eef6..accc4ba 100644
--- a/pcilib/bar.h
+++ b/pcilib/bar.h
@@ -72,7 +72,21 @@ int pcilib_detect_address(pcilib_t *ctx, pcilib_bar_t *bar, uintptr_t *addr, siz
*/
char *pcilib_resolve_data_space(pcilib_t *ctx, uintptr_t addr, size_t *size);
+/**
+ * Return information about the specified BAR or NULL if BAR is not present in hardware
+ * @param[in,out] ctx - pcilib context
+ * @param[in] bar - the PCI BAR number (numbered from 0)
+ * @return - pointer to structure describing the specified BAR or NULL in case of error
+ */
const pcilib_bar_info_t *pcilib_get_bar_info(pcilib_t *ctx, pcilib_bar_t bar);
+
+/**
+ * Return a list of BAR memory regions available in the hardware.
+ * The list is terminated by a dummy BAR description with 0 size.
+ *
+ * @param[in,out] ctx - pcilib context
+ * @return - pointer to structure describing the BARs or NULL in case of error
+ */
const pcilib_bar_info_t *pcilib_get_bar_list(pcilib_t *ctx);
diff --git a/pcilib/cpu.h b/pcilib/cpu.h
index 2b3ed80..9b4b1d7 100644
--- a/pcilib/cpu.h
+++ b/pcilib/cpu.h
@@ -5,8 +5,23 @@
extern "C" {
#endif
+/**
+ * Return the mask of system memory page
+ * @return - page mask, the bits which will correspond to offset within the page are set to 1
+ */
int pcilib_get_page_mask();
+
+/**
+ * Number of CPU cores in the system (including HyperThreading cores)
+ * @return - number of available CPU cores
+ */
int pcilib_get_cpu_count();
+
+/**
+ * Returns the generation of Intel Core architecture
+ * Processors up to Intel Core gen4 are recognized.
+ * @return - Generation of Intel Core architecture (1 to 4) or 0 for non-Intel and Intel pre-Core architectures
+ */
int pcilib_get_cpu_gen();
#ifdef __cplusplus
diff --git a/pcilib/datacpy.h b/pcilib/datacpy.h
index 1ce2e79..e807e01 100644
--- a/pcilib/datacpy.h
+++ b/pcilib/datacpy.h
@@ -10,9 +10,61 @@
extern "C" {
#endif
+/**
+ * The collection of slow memcpy functions to move the data between BAR and system memory.
+ * If necessary the endianess conversion is performed to ensure that the data is encoded
+ * using the specified endianess in the BAR memory and using the native host order in the
+ * system memory. Since endianess conversion is symmetric, it is irrelevant if we are
+ * copying from system memory to BAR memory or vice-versa.
+ *
+ * The hardware may restrict access width or expose different behavior depending on the
+ * access width. These functions access memory using the specified word width only.
+ * 8-, 16-, 32-, and 64-bit wide access is supported.
+ *
+ * @param[out] dst - the destination memory region
+ * @param[in] src - the source memory region
+ * @param[in] access - the size of word (a single memory access) in bytes
+ * @param[in] n - the number of words to copy (\p n * \p access bytes are copied).
+ * @param[in] endianess - the endianess of the data words in the BAR memory
+ * @return - `dst` or NULL on error
+ */
+void *pcilib_datacpy(void * dst, void const * src, uint8_t access, size_t n, pcilib_endianess_t endianess);
+
+/**
+ * The collection of slow memcpy functions to move the data between BAR and system memory.
+ * If necessary the endianess conversion is performed to ensure that the data is encoded
+ * using the specified endianess in the BAR memory and using the native host order in the
+ * system memory. Since endianess conversion is symmetric, it is irrelevant if we are
+ * copying from system memory to BAR memory or vice-versa.
+ *
+ * The hardware may restrict access width or expose different behavior depending on the
+ * access width. This function only perform 32-bit memory accesses.
+ *
+ * @param[out] dst - the destination memory region
+ * @param[in] src - the source memory region
+ * @param[in] n - the number of 32-bit words to copy (4 * \p n bytes are copied)
+ * @param[in] endianess - the endianess of the data words in the BAR memory
+ * @return - `dst` or NULL on error
+ */
void *pcilib_datacpy32(void * dst, void const * src, size_t n, pcilib_endianess_t endianess);
+
+/**
+ * The collection of slow memcpy functions to move the data between BAR and system memory.
+ * If necessary the endianess conversion is performed to ensure that the data is encoded
+ * using the specified endianess in the BAR memory and using the native host order in the
+ * system memory. Since endianess conversion is symmetric, it is irrelevant if we are
+ * copying from system memory to BAR memory or vice-versa.
+ *
+ * The hardware may restrict access width or expose different behavior depending on the
+ * access width. This function only perform 64-bit memory accesses.
+ *
+ * @param[out] dst - the destination memory region
+ * @param[in] src - the source memory region
+ * @param[in] n - the number of 64-bit words to copy (8 * \p n bytes are copied)
+ * @param[in] endianess - the endianess of the data words in the BAR memory
+ * @return - `dst` or NULL on error
+ */
void *pcilib_datacpy64(void * dst, void const * src, size_t n, pcilib_endianess_t endianess);
-void *pcilib_datacpy(void * dst, void const * src, uint8_t size, size_t n, pcilib_endianess_t endianess);
#ifdef __cplusplus
}
diff --git a/pcilib/kmem.h b/pcilib/kmem.h
index 500ca0e..1d63e3b 100644
--- a/pcilib/kmem.h
+++ b/pcilib/kmem.h
@@ -106,23 +106,23 @@ extern "C" {
* This function either allocates new buffers in the kernel space or just re-uses existing buffers.
*
* Sometimes kernel memory is allocated for the specific use-case, for example to provide buffers for DMA engine.
- * It is possible to specify intended use using \a use parameter.
- * The kernel memory with the specified use (i.e. \a use != 0) can be declared persistent (\a flags include
- * PCILIB_KMEM_FLAG_PERSISTENT). Such memory will not be de-allocated on clean-up and will be maintained by
+ * It is possible to specify intended use using \p use parameter.
+ * The kernel memory with the specified use (i.e. \p use != 0) can be declared persistent (\p flags include
+ * ::PCILIB_KMEM_FLAG_PERSISTENT). Such memory will not be de-allocated on clean-up and will be maintained by
* the kernel module across the runs of various pcilib applications. To re-use persistent kernel memory,
- * PCILIB_KMEM_FLAG_REUSE should be set. In this case, the pcilib will either allocate new kernel memory
- * or re-use the already allocated kernel buffers with the specified \a use. If PCILIB_KMEM_FLAG_REUSE
+ * ::PCILIB_KMEM_FLAG_REUSE should be set. In this case, the pcilib will either allocate new kernel memory
+ * or re-use the already allocated kernel buffers with the specified \p use. If ::PCILIB_KMEM_FLAG_REUSE
* is not set, but the kernel memory with the specified use is already allocated, an error will be returned.
*
* It is also possible to allocate persistent kernel memory which can be execlusively used by a single process.
- * The PCILIB_KMEM_FLAG_EXCLUSIVE flag have to be provided to pcilib_alloc_kernel_memory() function in this
+ * The ::PCILIB_KMEM_FLAG_EXCLUSIVE flag have to be provided to pcilib_alloc_kernel_memory() function in this
* case. Only a single process may call hold a reference to kernel memory. Before next process would be able
* to obtain it, the process holding the reference should return it using pcilib_free_kernel_memory()
* call. For example, DMA engine uses exclusive kernel memory to guarantee that exactly one process is
* controlling DMA operations.
*
* To clean up allocated persistent kernel memory, pcilib_free_kernel_memory() have to be called with
- * PCILIB_KMEM_FLAG_PERSISTENT flag set.
+ * ::PCILIB_KMEM_FLAG_PERSISTENT flag set.
*
* @param[in,out] ctx - pcilib context
* @param[in] type - specifies type of allocation (simple pages, DMA pages, consistent memory, etc.)
@@ -138,16 +138,16 @@ pcilib_kmem_handle_t *pcilib_alloc_kernel_memory(pcilib_t *ctx, pcilib_kmem_type
/**
* This function either frees the allocated kernel memory or just releases some of the references.
*
- * Only reference tracking is performed If the PCILIB_KMEM_FLAG_REUSE flag is passed to the
+ * Only reference tracking is performed If the ::PCILIB_KMEM_FLAG_REUSE flag is passed to the
* function. Otherwise, non-persistent memory is released when pcilib_free_kernel_memory() called.
- * The persistent memory is released if PCILIB_KMEM_FLAG_PERSISTENT is passed in \a flags parameter
+ * The persistent memory is released if ::PCILIB_KMEM_FLAG_PERSISTENT is passed in \p flags parameter
* unless the hold references are preventing us from releasing this memory. The error is reported
- * in this case. The kernel memory can be freed irrespective of hold references if PCILIB_KMEM_FLAG_FORCE
+ * in this case. The kernel memory can be freed irrespective of hold references if ::PCILIB_KMEM_FLAG_FORCE
* flag is specified.
*
* There are several types of references:
* - The hardware reference - indicates that the memory may be used by DMA engine of the device. It is set
- * if pcilib_alloc_kernel_memory() is executed with PCILIB_KMEM_FLAG_HARDWARE flag. The reference can
+ * if pcilib_alloc_kernel_memory() is executed with ::PCILIB_KMEM_FLAG_HARDWARE flag. The reference can
* be released if the same flag is passed to pcilib_free_kernel_memory()
* - The software references - are obtained when the memory is reused with pcilib_alloc_kernel_memory().
* They are released when corresponding pcilib_free_kernel_memory() is called.
@@ -160,13 +160,13 @@ pcilib_kmem_handle_t *pcilib_alloc_kernel_memory(pcilib_t *ctx, pcilib_kmem_type
* used to keep track of non-persistent memory allocated and re-used within the same application (which is
* actually discouraged). In this case the number of pcilib_alloc_kernel_memory() should be matched by
* number of pcilib_free_kernel_memory() calls and only on a last call the memory will be really released.
- * Normally, all but last calls have to be accompanied by PCILIB_KMEM_FLAG_REUSE flag or the error
+ * Normally, all but last calls have to be accompanied by ::PCILIB_KMEM_FLAG_REUSE flag or the error
* is reported. But to keep code simpler, the pcilib will not complain until there are software references
* on hold. When the last software reference is released, we try actually clean up the memory and the
* error is reported if other types of references are still present.
* The software references may stuck if application crashes before calling pcilib_free_kernel_memory().
* pcilib will prevent us from releasing the kernel memory with stuck references. Such memory can
- * be cleaned only with PCILIB_KMEM_FLAG_FORCE flag or using pcilib_clean_kernel_memory() call.
+ * be cleaned only with ::PCILIB_KMEM_FLAG_FORCE flag or using pcilib_clean_kernel_memory() call.
*
* @param[in,out] ctx - pcilib context
* @param[in,out] k - kernel memory handle returned from pcilib_alloc_kernel_memory() call
@@ -176,7 +176,7 @@ void pcilib_free_kernel_memory(pcilib_t *ctx, pcilib_kmem_handle_t *k, pcilib_km
/**
- * Free / dereference all kernel memory buffers associated with the specified \a use
+ * Free / dereference all kernel memory buffers associated with the specified \p use
*
* @param[in,out] ctx - pcilib context
* @param[in] use - use-number to clean
diff --git a/pcilib/memcpy.h b/pcilib/memcpy.h
index dbfae36..99317bf 100644
--- a/pcilib/memcpy.h
+++ b/pcilib/memcpy.h
@@ -9,10 +9,60 @@
extern "C" {
#endif
+/**
+ * The collection of slow memcpy functions to move the data between BAR and system memory.
+ *
+ * The hardware may restrict access width or expose different behavior depending on the
+ * access width. These functions access memory using the specified word width only.
+ * 8-, 16-, 32-, and 64-bit wide access is supported.
+ *
+ * @param[out] dst - the destination memory region
+ * @param[in] src - the source memory region
+ * @param[in] access - the size of word (a single memory access) in bytes
+ * @param[in] n - the number of words to copy (\p n * \p access bytes are copied).
+ * @return - `dst` or NULL on error
+ */
+void *pcilib_memcpy(void * dst, void const * src, uint8_t access, size_t n);
+
+/**
+ * The collection of slow memcpy functions to move the data between BAR and system memory.
+ *
+ * The hardware may restrict access width or expose different behavior depending on the
+ * access width. This function only perform 8-bit memory accesses.
+ *
+ * @param[out] dst - the destination memory region
+ * @param[in] src - the source memory region
+ * @param[in] len - the number of bytes to copy
+ * @return - `dst` or NULL on error
+ */
void *pcilib_memcpy8(void * dst, void const * src, size_t len);
+
+/**
+ * The collection of slow memcpy functions to move the data between BAR and system memory.
+ *
+ * The hardware may restrict access width or expose different behavior depending on the
+ * access width. This function only perform 32-bit memory accesses.
+ *
+ * @param[out] dst - the destination memory region
+ * @param[in] src - the source memory region
+ * @param[in] len - the number of bytes to copy
+ * @return - `dst` or NULL on error
+ */
void *pcilib_memcpy32(void * dst, void const * src, size_t len);
+
+
+/**
+ * The collection of slow memcpy functions to move the data between BAR and system memory.
+ *
+ * The hardware may restrict access width or expose different behavior depending on the
+ * access width. This function only perform 64-bit memory accesses.
+ *
+ * @param[out] dst - the destination memory region
+ * @param[in] src - the source memory region
+ * @param[in] len - the number of bytes to copy
+ * @return - `dst` or NULL on error
+ */
void *pcilib_memcpy64(void * dst, void const * src, size_t len);
-void *pcilib_memcpy(void * dst, void const * src, uint8_t access, size_t n);
#ifdef __cplusplus
}
diff --git a/pcilib/pcilib.h b/pcilib/pcilib.h
index 8ab8e9e..f1c0dd7 100644
--- a/pcilib/pcilib.h
+++ b/pcilib/pcilib.h
@@ -1265,7 +1265,7 @@ int pcilib_set_value_from_static_string(pcilib_t *ctx, pcilib_value_t *val, cons
* @param[in] str - initializer
* @return - 0 on success or memory error
*/
-int pcilib_set_value_from_string(pcilib_t *ctx, pcilib_value_t *value, const char *str);
+int pcilib_set_value_from_string(pcilib_t *ctx, pcilib_value_t *val, const char *str);
/**
* Get the floating point value from the polymorphic type. May inmply impliced type conversion,
diff --git a/pcilib/plugin.h b/pcilib/plugin.h
index f9ff7cf..d79936a 100644
--- a/pcilib/plugin.h
+++ b/pcilib/plugin.h
@@ -5,11 +5,60 @@
extern "C" {
#endif
+/**
+ * Loads the specified plugin
+ * The plugin symbols are loaded localy and not available for symbol resolution, but should be requested
+ * with pcilib_plugin_get_symbol() instead.
+ * @param[in] name - the plugin name (with extension, but without path)
+ * @return - dlopen'ed plugin or NULL in the case of error
+ */
void *pcilib_plugin_load(const char *name);
+
+/**
+ * Cleans up the loaded plugin
+ * @param[in] plug - plugin loaded with pcilib_plugin_load()
+ */
void pcilib_plugin_close(void *plug);
+
+/**
+ * Resolves the specified symbol in the plugin
+ * @param[in] plug - plugin loaded with pcilib_plugin_load()
+ * @param[in] symbol - name of the symbol
+ * @return - pointer to the symbol or NULL if not found
+ */
void *pcilib_plugin_get_symbol(void *plug, const char *symbol);
-const pcilib_model_description_t *pcilib_get_plugin_model(pcilib_t *pcilib, void *plug, unsigned short vendor_id, unsigned short device_id, const char *model);
-const pcilib_model_description_t *pcilib_find_plugin_model(pcilib_t *pcilib, unsigned short vendor_id, unsigned short device_id, const char *model);
+
+/**
+ * Verifies if plugin can handle the hardware and requests appropriate model description
+ * @param[in,out] ctx - pcilib context
+ * @param[in] plug - plugin loaded with pcilib_plugin_load()
+ * @param[in] vendor_id - Vendor ID reported by hardware
+ * @param[in] device_id - Device ID reported by hardware
+ * @param[in] model - the requested pcilib model or NULL for autodetction
+ * @return - the appropriate model description or NULL if the plugin does not handle the installed hardware or requested model
+ */
+const pcilib_model_description_t *pcilib_get_plugin_model(pcilib_t *ctx, void *plug, unsigned short vendor_id, unsigned short device_id, const char *model);
+
+/**
+ * Finds the appropriate plugin and returns model description.
+ *
+ * The function sequentially loads plugins available in ::PCILIB_PLUGIN_DIR and
+ * checks if they support the installed hardware and requested model. If hardware
+ * is not supported, the plugin is immideately unloaded. On a first success
+ * the model description is returned to caller and no further plguins are loaded.
+ * If no suitable plugin is found, the NULL is returned.
+ *
+ * If model is specified, first a plugin with the same name is loaded and check performed
+ * if it can handle the installed hardware. If not, we iterate over all available
+ * plugins as usual.
+ *
+ * @param[in,out] ctx - pcilib context
+ * @param[in] vendor_id - Vendor ID reported by hardware
+ * @param[in] device_id - Device ID reported by hardware
+ * @param[in] model - the requested pcilib model or NULL for autodetction
+ * @return - the appropriate model description or NULL if no plugin found able to handle the installed hardware or requested model
+ */
+const pcilib_model_description_t *pcilib_find_plugin_model(pcilib_t *ctx, unsigned short vendor_id, unsigned short device_id, const char *model);
#ifdef __cplusplus
}
diff --git a/pcilib/timing.h b/pcilib/timing.h
index 630df44..b8df7c3 100644
--- a/pcilib/timing.h
+++ b/pcilib/timing.h
@@ -8,14 +8,63 @@
extern "C" {
#endif
+
+/**
+ * Add the specified number of microseconds to the time stored in \p tv
+ * @param[in,out] tv - timestamp
+ * @param[in] timeout - number of microseconds to add
+ * @return - error code or 0 for correctness
+ */
int pcilib_add_timeout(struct timeval *tv, pcilib_timeout_t timeout);
+
+/**
+ * Computes the deadline by adding the specified number of microseconds to the current timestamp
+ * @param[out] tv - the deadline
+ * @param[in] timeout - number of microseconds to add
+ * @return - error code or 0 for correctness
+ */
int pcilib_calc_deadline(struct timeval *tv, pcilib_timeout_t timeout);
-int pcilib_check_deadline(struct timeval *tve, pcilib_timeout_t timeout);
-pcilib_timeout_t pcilib_calc_time_to_deadline(struct timeval *tve);
+
+/**
+ * Check if we are within \p timeout microseconds before the specified deadline or already past it
+ * @param[in] tv - the deadline
+ * @param[in] timeout - maximum number of microseconds before deadline
+ * @return - 1 if we are within \p timeout microseconds before deadline or past it, 0 - otherwise
+ */
+int pcilib_check_deadline(struct timeval *tv, pcilib_timeout_t timeout);
+
+/**
+ * Compute the remaining time to deadline
+ * @param[in] tv - the deadline
+ * @return - number of microseconds until deadline or 0 if we are already past it
+ */
+pcilib_timeout_t pcilib_calc_time_to_deadline(struct timeval *tv);
+
+/**
+ * Executes sleep until the specified deadline
+ * Real-time capabilities are not used. TThe sleep could wake slightly after the specified deadline.
+ * @param[in] tv - the deadline
+ * @return - error code or 0 for correctness
+ */
int pcilib_sleep_until_deadline(struct timeval *tv);
-int pcilib_timecmp(struct timeval *tv1, struct timeval *tv2);
+
+/**
+ * Computes the number of microseconds between 2 timestamps.
+ * This function expects that \p tve is after \p tvs.
+ * @param[in] tve - the end of the time interval
+ * @param[in] tvs - the beginning of the time interval
+ * @return - number of microseconds between two timestamps
+ */
pcilib_timeout_t pcilib_timediff(struct timeval *tve, struct timeval *tvs);
+/**
+ * Compares two timestamps
+ * @param[in] tv1 - the first timestamp
+ * @param[in] tv2 - the second timestamp
+ * @return - 0 if timestamps are equal, 1 if the first timestamp is after the second, or -1 if the second is after the first.
+ */
+int pcilib_timecmp(struct timeval *tv1, struct timeval *tv2);
+
#ifdef __cplusplus
}
diff --git a/pcilib/tools.h b/pcilib/tools.h
index 8c525e0..7b4aea0 100644
--- a/pcilib/tools.h
+++ b/pcilib/tools.h
@@ -14,15 +14,65 @@
extern "C" {
#endif
+/**
+ * Check if provided string is a decimal integer
+ * @param[in] str - string to check
+ * @return - 1 if string is a number and 0 - otherwise
+ */
int pcilib_isnumber(const char *str);
+
+/**
+ * Check if provided string is a hexdecimal integer, optionally prefexed with 0x
+ * @param[in] str - string to check
+ * @return - 1 if string is a number and 0 - otherwise
+ */
int pcilib_isxnumber(const char *str);
+
+/**
+ * Check if first \p len bytes of the provided string is a decimal integer
+ * @param[in] str - string to check
+ * @param[in] len - size of the string
+ * @return - 1 if string is a number and 0 - otherwise
+ */
int pcilib_isnumber_n(const char *str, size_t len);
+
+/**
+ * Check if first \p len bytes of the provided string is a hexdecimal integer, optionally prefexed with 0x
+ * @param[in] str - string to check
+ * @param[in] len - size of the string
+ * @return - 1 if string is a number and 0 - otherwise
+ */
int pcilib_isxnumber_n(const char *str, size_t len);
+/**
+ * Change the endianess of the provided number (between big- and little-endian format)
+ * @param[in] x - number in little/big endian format
+ * @return - number in big/little endian format
+ */
uint16_t pcilib_swap16(uint16_t x);
+
+/**
+ * Change the endianess of the provided number (between big- and little-endian format)
+ * @param[in] x - number in little/big endian format
+ * @return - number in big/little endian format
+ */
uint32_t pcilib_swap32(uint32_t x);
+
+/**
+ * Change the endianess of the provided number (between big- and little-endian format)
+ * @param[in] x - number in little/big endian format
+ * @return - number in big/little endian format
+ */
uint64_t pcilib_swap64(uint64_t x);
-void pcilib_swap(void *dst, void *src, size_t size, size_t n);
+
+/**
+ * Change the endianess of the provided array
+ * @param[out] dst - the destination memory region, can be equal to \p src
+ * @param[in] src - the source memory region
+ * @param[in] access - the size of word in bytes (1, 2, 4, or 8)
+ * @param[in] n - the number of words to copy (\p n * \p access bytes are copied).
+ */
+void pcilib_swap(void *dst, void *src, size_t access, size_t n);
#ifdef __cplusplus
}