Documentation update

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
 }