Finalyze XML support and provide initial support for views (only descriptions so far)

2 files changed, 29 insertions, 58 deletions

diff --git a/protocols/software.c b/protocols/software.c
index 55f62e8..55ed647 100644
--- a/protocols/software.c
+++ b/protocols/software.c
@@ -12,33 +12,21 @@
 
 typedef struct pcilib_software_register_bank_context_s pcilib_software_register_bank_context_t;
 
+/**
+ * structure defining the context of software registers
+ */
 struct pcilib_software_register_bank_context_s {
-    pcilib_register_bank_context_t bank_ctx;	 /**< the bank context associated with the software registers */
-
+    pcilib_register_bank_context_t bank_ctx;	/**< the bank context associated with the software registers */
     pcilib_kmem_handle_t *kmem;			/**< the kernel memory for software registers */
     void *addr;					/**< the virtual adress of the allocated kernel memory*/
 };
 
-/**
- * pcilib_software_registers_close
- * this function clear the kernel memory space that could have been allocated for software registers
- * @param[in] bank_ctx the bank context running that we get from the initialisation function
- */	
 void pcilib_software_registers_close(pcilib_t *ctx, pcilib_register_bank_context_t *bank_ctx) {
 	if (((pcilib_software_register_bank_context_t*)bank_ctx)->kmem)
 	    pcilib_free_kernel_memory(ctx, ((pcilib_software_register_bank_context_t*)bank_ctx)->kmem, PCILIB_KMEM_FLAG_REUSE);
 	free(bank_ctx);
 }
 
-/**
- * pcilib_software_registers_open
- * this function initializes the kernel space memory and stores in it the default values of the registers of the given bank index, if it was not initialized by a concurrent process, and return a bank context containing the adress of this kernel space. It the kernel space memory was already initialized by a concurrent process, then this function just return the bank context with the adress of this kernel space already used
- * @param[in] ctx the pcilib_t structure running
- * @param[in] bank the bank index that will permits to get the bank we want registers from
- * @param[in] model not used
- * @param[in] args not used
- * @return a bank context with the adress of the kernel space memory related to it
- */
 pcilib_register_bank_context_t* pcilib_software_registers_open(pcilib_t *ctx, pcilib_register_bank_t bank, const char* model, const void *args) {
 	int err;
 	pcilib_software_register_bank_context_t *bank_ctx;
@@ -59,6 +47,7 @@ pcilib_register_bank_context_t* pcilib_software_registers_open(pcilib_t *ctx, pc
 	    return NULL;
 	}
 
+	/*we get a lock to protect the creation of the kernel space for software registers against multiple creations*/
 	lock = pcilib_get_lock(ctx, PCILIB_LOCK_FLAGS_DEFAULT, "softreg/%s", bank_desc->name);
 	if (!lock) {
 	    pcilib_software_registers_close(ctx, (pcilib_register_bank_context_t*)bank_ctx);
@@ -74,7 +63,7 @@ pcilib_register_bank_context_t* pcilib_software_registers_open(pcilib_t *ctx, pc
 	    return NULL;
 	}
 
-
+	/*creation of the kernel space*/
 	handle = pcilib_alloc_kernel_memory(ctx, PCILIB_KMEM_TYPE_PAGE, 1, PCILIB_KMEM_PAGE_SIZE, 0, PCILIB_KMEM_USE(PCILIB_KMEM_USE_SOFTWARE_REGISTERS, bank_desc->addr), PCILIB_KMEM_FLAG_REUSE|PCILIB_KMEM_FLAG_PERSISTENT);
 	if (!handle) {
 	    pcilib_unlock(lock);
@@ -98,7 +87,8 @@ pcilib_register_bank_context_t* pcilib_software_registers_open(pcilib_t *ctx, pc
 		pcilib_error("Inconsistent software registers are found (only part of required buffers is available)");
 		return NULL;
 	    }
-		
+
+	/* here we fill the software registers with their default value*/		
 	    for (i = 0; ctx->model_info.registers[i].name != NULL; i++) {
 		if ((ctx->model_info.registers[i].bank == ctx->banks[bank].addr)&&(ctx->model_info.registers[i].type == PCILIB_REGISTER_STANDARD)) {
 		    *(pcilib_register_value_t*)(bank_ctx->addr + ctx->model_info.registers[i].addr) = ctx->model_info.registers[i].defvalue;
@@ -112,15 +102,6 @@ pcilib_register_bank_context_t* pcilib_software_registers_open(pcilib_t *ctx, pc
 	return (pcilib_register_bank_context_t*)bank_ctx;
 }
 
-/**
- * pcilib_software_registers_read
- * this function read the value of a said register in the kernel space
- * @param[in] ctx the pcilib_t structure runnning
- * @param[in] bank_ctx the bank context that was returned by the initialisation function
- * @param[in] addr the adress of the register we want to read
- * @param[out] value the value of the register
- * @return 0 in case of success
- */
 int pcilib_software_registers_read(pcilib_t *ctx, pcilib_register_bank_context_t *bank_ctx, pcilib_register_addr_t addr, pcilib_register_value_t *value){
 	if ((addr + sizeof(pcilib_register_value_t)) > bank_ctx->bank->size) {
 	    pcilib_error("Trying to access space outside of the define register bank (bank: %s, addr: 0x%lx)", bank_ctx->bank->name, addr);
@@ -132,15 +113,6 @@ int pcilib_software_registers_read(pcilib_t *ctx, pcilib_register_bank_context_t
 	return 0;
 }
 
-/**
- * pcilib_software_registers_write
- * this function write the said value to a said register in the kernel space
- * @param[in] ctx the pcilib_t structure runnning
- * @param[in] bank_ctx the bank context that was returned by the initialisation function
- * @param[in] addr the adress of the register we want to write in
- * @param[out] value the value we want to write in the register
- * @return 0 in case of success
- */
 int pcilib_software_registers_write(pcilib_t *ctx, pcilib_register_bank_context_t *bank_ctx, pcilib_register_addr_t addr, pcilib_register_value_t value) {
 	if ((addr + sizeof(pcilib_register_value_t)) > bank_ctx->bank->size) {
 	    pcilib_error("Trying to access space outside of the define register bank (bank: %s, addr: 0x%lx)", bank_ctx->bank->name, addr);
diff --git a/protocols/software.h b/protocols/software.h
index d066cd6..484e344 100644
--- a/protocols/software.h
+++ b/protocols/software.h
@@ -1,7 +1,6 @@
 /**
  * @file software.h
- * @skip author nicolas zilio, nicolas.zilio@hotmail.fr
- * @brief header file for implementation of the protocol with software registers allocated in the main memory.
+ * @brief header file for implementation of the protocol with software registers allocated in the kernel space, for parameters sharing between concurrent pcitool instances
  */
 
 #ifndef _PCILIB_SOFTWARE_H
@@ -13,44 +12,44 @@
 
 /**
  * this function initialize the kernel space memory for the use of software register. it initializes the kernel space memory and stores in it the default values of the registers of the given bank index, if it was not initialized by a concurrent process, and return a bank context containing the adress of this kernel space. If the kernel space memory was already initialized by a concurrent process, then this function just return the bank context with the adress of this kernel space already used
- * @param[in] ctx the pcilib_t structure running
- * @param[in] bank the bank index that will permits to get the bank we want registers from
- * @param[in] model not used
- * @param[in] args not used
- * @return a bank context with the adress of the kernel space memory related to it
+ * @param[in] - ctx the pcilib_t structure running
+ * @param[in] - bank the bank index that will permits to get the bank we want registers from
+ * @param[in] - model not used
+ * @param[in] - args not used
+ * @return a bank context with the adress of the kernel space memory related to it, as we could have for BAR
  */
 pcilib_register_bank_context_t* pcilib_software_registers_open(pcilib_t *ctx, pcilib_register_bank_t bank, const char* model, const void *args);
 
 /**
- * this function clear the kernel memory space that could have been allocated for software registers.
- * @param[in] ctx the pcilib_t structure runnning
- * @param[in] bank_ctx the bank context running that we get from the initialisation function
+ * this function clear the kernel memory space that could have been allocated for software registers and the bank context that correspond to it too
+ * @param[in] ctx - the pcilib_t structure runnning
+ * @param[in] bank_ctx - the bank context running that we get from the initialisation function
  */
 void pcilib_software_registers_close(pcilib_t *ctx, pcilib_register_bank_context_t *bank_ctx);
 
 /**
  * this function read the value of a said register in the kernel space.
- * @param[in] ctx the pcilib_t structure runnning
- * @param[in] bank_ctx the bank context that was returned by the initialisation function
- * @param[in] addr the adress of the register we want to read
- * @param[out] value the value of the register
- * @return 0 in case of success
+ * @param[in] - ctx the pcilib_t structure runnning
+ * @param[in] - bank_ctx the bank context that was returned by the initialisation function
+ * @param[in] - addr the adress of the register we want to read
+ * @param[out] - value the value of the register
+ * @return error code : 0 in case of success
  */
 int  pcilib_software_registers_read(pcilib_t *ctx, pcilib_register_bank_context_t* bank_ctx, pcilib_register_addr_t addr, pcilib_register_value_t *value);
 
 /**
- * this function write the said value to a said register in the kernel space
- * @param[in] ctx the pcilib_t structure runnning
- * @param[in] bank_ctx the bank context that was returned by the initialisation function
- * @param[in] addr the adress of the register we want to write in
- * @param[out] value the value we want to write in the register
- * @return 0 in case of success
+ * this function write the given value to a given register in the kernel space
+ * @param[in] ctx - the pcilib_t structure runnning
+ * @param[in] bank_ctx - the bank context that was returned by the initialisation function
+ * @param[in] addr - the adress of the register we want to write in
+ * @param[in] value - the value we want to write in the register
+ * @return error code : 0 in case of success
  */
 int pcilib_software_registers_write(pcilib_t *ctx,pcilib_register_bank_context_t* bank_ctx, pcilib_register_addr_t addr, pcilib_register_value_t value);
 
 #ifdef _PCILIB_EXPORT_C
 /**
- * new protocol addition to the protocol api.
+ * software protocol addition to the protocol api.
  */
 const pcilib_register_protocol_api_description_t pcilib_register_software_protocol_api =
   { PCILIB_VERSION, pcilib_software_registers_open, pcilib_software_registers_close,pcilib_software_registers_read, pcilib_software_registers_write }; /**< we add there the protocol to the list of possible protocols*/