From a0fe5cdea15bca52d3b101a88c11cb160ef08b2f Mon Sep 17 00:00:00 2001
From: "Suren A. Chilingaryan" <csa@suren.me>
Date: Thu, 22 Oct 2015 15:57:59 +0200
Subject: Documentation update

---
 pcilib/bar.h | 66 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 66 insertions(+)

(limited to 'pcilib/bar.h')

diff --git a/pcilib/bar.h b/pcilib/bar.h
index 9ab1cc0..deb6f81 100644
--- a/pcilib/bar.h
+++ b/pcilib/bar.h
@@ -5,9 +5,75 @@
 extern "C" {
 #endif
 
+/**
+ * Detects in which PCI BAR the specified buffer is residing. The complete specified buffer
+ * of \a size bytes should fit into the BAR. Otherwise, an error will be returned.
+ * @param[in] ctx	- pcilib context
+ * @param[in] addr	- physical address of the begining of the buffer
+ * @param[in] size	- the size of the buffer
+ * @return		- return the BAR (numbered from 0) or PCILIB_BAR_INVALID if buffer does not belong to any BAR.
+ */
 pcilib_bar_t pcilib_detect_bar(pcilib_t *ctx, uintptr_t addr, size_t size);
+
+/**
+ * Maps the specified bar to the address space of the process. This function may be called multiple times for 
+ * the same bar. It will only map the BAR once. Normally, the required BARs will be automatically mapped when
+ * BAR addresses are resolved with pcilib_resolve_bar_address() and similar.
+ * @param[in,out] ctx 	- pcilib context
+ * @param[in] bar	- the PCI BAR number (numbered from 0)
+ * return 		- the address where the BAR is mapped. You can't use this address directly, 
+ *			instead pcilib_resolve_register_address(ctx, bar, 0) have to be used to find 
+ *			the start of the BAR in virtual address space.
+ */
+void *pcilib_map_bar(pcilib_t *ctx, pcilib_bar_t bar);
+
+/**
+ * Unmaps the specified bar from the address space of the process. Actually, it will only unmap the BAR if it is 
+ * not used by DMA or Event egines. So, it is fine to include the calls to pcilib_map_bar() / pcilib_unmap_bar() 
+ * when a specific BAR is needed. On other hand, there is a little point in doing so. The BAR may be left mapped
+ * and will be automatically umapped when pcilib_close() is called.
+ * @param[in,out] ctx	- pcilib context
+ * @param[in] bar	- BAR number (numbered from 0)
+ * @param[in,out] data	- The address returned by pcilib_map_bar() call
+ */
+void pcilib_unmap_bar(pcilib_t *ctx, pcilib_bar_t bar, void *data);
+
+/**
+ * Detects the BAR and mapping offset of the specified PCI buffer. The complete specified buffer
+ * of \a size bytes should fit into the BAR. Otherwise, an error will be returned.
+ * @param[in] ctx	- pcilib context
+ * @param[in,out] bar	- the function will check if the buffer belongs to the specified BAR unless bar is PCILIB_BAR_DETECT.
+ *			It will be set to the actually detected BAR in the last case.
+ * @param[in,out] addr	- specifies the address to detect. The address may be specified as absolute physical address or offset in the BAR.
+ *			On success, the addr will contain offset which should be added to the address returned by pcilib_map_bar()
+ *			to get position of BAR mapping in virtual address space.
+ * @param[in] size	- the size of the buffer
+ * @return		- error code or 0 in case of success
+ */
 int pcilib_detect_address(pcilib_t *ctx, pcilib_bar_t *bar, uintptr_t *addr, size_t size);
 
+/**
+ * Resolves the virtual address and the size of PCI BAR space used for data exchange.
+ * This is left-over from older version of pcilib and currently unused. We may reconsider
+ * how it is organized and implemented. The data_space parameter may go into the model definition.
+ * @param[in] ctx	- pcilib context
+ * @param[in] addr	- may hint there the data space is located, use 0 to autodetect
+ * @param[out] size	- the size of data space is returned
+ * @return		- virtual address of data space (ready to use) or NULL if detection has failed
+ */
+char *pcilib_resolve_data_space(pcilib_t *ctx, uintptr_t addr, size_t *size);
+
+
+/**
+ * The wrapper arround pcilib_resolve_bar_address() provided for backward compatibility. 
+ * If bar is not specified, it first checks the first BAR with registers, before searching
+ * in other available BARs.
+ * @param[in,out] ctx	- pcilib context
+ * @param[in] bar	- specifies the BAR address belong to, use PCILIB_BAR_DETECT for autodetection
+ * @param[in] addr	- specifies the physical address on the PCI bus or offset in the BAR if \a bar is specified
+ * @return		- the virtual address in the process address space or NULL in case of error
+ */
+char *pcilib_resolve_register_address(pcilib_t *ctx, pcilib_bar_t bar, uintptr_t addr);	
 
 #ifdef __cplusplus
 }
-- 
cgit v1.2.3