From 8933c45c177556353570f92513bb49f182ce3be8 Mon Sep 17 00:00:00 2001 From: "Suren A. Chilingaryan" Date: Wed, 2 Mar 2016 05:47:04 +0100 Subject: Documentation update --- pcilib/bank.h | 114 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ pcilib/bar.h | 14 +++++++ pcilib/cpu.h | 15 ++++++++ pcilib/datacpy.h | 54 +++++++++++++++++++++++++- pcilib/kmem.h | 28 +++++++------- pcilib/memcpy.h | 52 ++++++++++++++++++++++++- pcilib/pcilib.h | 2 +- pcilib/plugin.h | 53 +++++++++++++++++++++++++- pcilib/timing.h | 55 +++++++++++++++++++++++++-- pcilib/tools.h | 52 ++++++++++++++++++++++++- 10 files changed, 416 insertions(+), 23 deletions(-) (limited to 'pcilib') 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 } -- cgit v1.2.3