Support properties of arbitrary type

1 files changed, 27 insertions, 9 deletions

diff --git a/pcilib/view.h b/pcilib/view.h
index 9d3d32d..6287942 100644
--- a/pcilib/view.h
+++ b/pcilib/view.h
@@ -16,19 +16,19 @@ typedef enum {
 } pcilib_view_flags_t;
 
 typedef struct {
-    pcilib_version_t version;
-    size_t description_size;
-    pcilib_view_context_t *(*init)(pcilib_t *ctx);
-    void (*free)(pcilib_t *ctx, pcilib_view_context_t *view);
-    void (*free_description)(pcilib_t *ctx, pcilib_view_description_t *view);
-    int (*read_from_reg)(pcilib_t *ctx, pcilib_view_context_t *view, pcilib_register_value_t regval, pcilib_value_t *val);
-    int (*write_to_reg)(pcilib_t *ctx, pcilib_view_context_t *view, pcilib_register_value_t *regval, const pcilib_value_t *val);
+    pcilib_version_t version;                                                                                                           /**< Version */
+    size_t description_size;                                                                                                            /**< The actual size of the description */
+    pcilib_view_context_t *(*init)(pcilib_t *ctx);                                                                                      /**< Optional function which should allocated context used by read/write functions */
+    void (*free)(pcilib_t *ctx, pcilib_view_context_t *view);                                                                           /**< Optional function which should clean context */
+    void (*free_description)(pcilib_t *ctx, pcilib_view_description_t *view);                                                           /**< Optional function which shoud clean required parts of the extended description if non-static memory was used to initialize it */
+    int (*read_from_reg)(pcilib_t *ctx, pcilib_view_context_t *view, pcilib_register_value_t regval, pcilib_value_t *val);              /**< Function which computes view value based on the passed the register value (view-based properties should not use register value) */
+    int (*write_to_reg)(pcilib_t *ctx, pcilib_view_context_t *view, pcilib_register_value_t *regval, const pcilib_value_t *val);        /**< Function which computes register value based on the passed value (view-based properties are not required to set the register value) */
 } pcilib_view_api_description_t;
 
 struct pcilib_view_description_s {
     const pcilib_view_api_description_t *api;
     pcilib_value_type_t type;			                                /**< The default data type returned by operation, PCILIB_VIEW_TYPE_STRING is supported by all operations */
-    pcilib_view_flags_t flags;                                                  /**< Flags specifying type of the view */
+    pcilib_access_mode_t mode;                                                  /**< Specifies if the view is read/write-only */
     const char *unit;				                                /**< Returned unit (if any) */
     const char *name;				                                /**< Name of the view */
     const char *description;			                                /**< Short description */
@@ -37,6 +37,7 @@ struct pcilib_view_description_s {
 struct pcilib_view_context_s {
     const char *name;
     pcilib_view_t view;
+    pcilib_view_flags_t flags;                                                  /**< Flags specifying type of the view */
     UT_hash_handle hh;
 };
 
@@ -44,8 +45,25 @@ struct pcilib_view_context_s {
 extern "C" {
 #endif
 
+/**
+ * Use this function to add new view definitions into the model. It is error to re-register
+ * already registered view. The function will copy the context of unit description, but name, 
+ * transform, and other strings in the structure are considered to have static duration 
+ * and will not be copied. On error no new views are initalized.
+ * @param[in,out] ctx - pcilib context
+ * @param[in] n - number of views to initialize. It is OK to pass 0 if protocols variable is NULL terminated (last member of protocols array have all members set to 0)
+ * @param[in] desc - view descriptions
+ * @return - error or 0 on success
+ */
 int pcilib_add_views(pcilib_t *ctx, size_t n, const pcilib_view_description_t *desc);
-void pcilib_clean_views(pcilib_t *ctx);
+
+/**
+ * Destroys data associated with views. This is an internal function and will
+ * be called during clean-up.
+ * @param[in,out] ctx - pcilib context
+ * @param[in] start - specifies first view to clean (used to clean only part of the views to keep the defined state if pcilib_add_views has failed)
+ */
+void pcilib_clean_views(pcilib_t *ctx, pcilib_view_t start);
 
 pcilib_view_context_t *pcilib_find_view_context_by_name(pcilib_t *ctx, const char *view);
 pcilib_view_context_t *pcilib_find_register_view_context_by_name(pcilib_t *ctx, pcilib_register_t reg, const char *name);