eive-obsw/gomspace/libutil/include/gs/util/vmem.h

#ifndef GS_UTIL_VMEM_H
#define GS_UTIL_VMEM_H
/* Copyright (c) 2013-2017 GomSpace A/S. All rights reserved. */
/**
   @file

   Virtual memory interface.

   The API provides support for accessing different hardware components using a common API, by providing a component specific driver.
*/

#include <gs/util/stdio.h>

#ifdef __cplusplus
extern "C" {
#endif

/**
   Virtual memory mapping.
*/
typedef struct gs_vmem gs_vmem_t;
    
/**
   VMEM driver write.

   @param[in] vmem vmem entry.
   @param[in] to   Address where to write data to.
   @param[in] from Address where to write data from.
   @param[in] size Number of bytes to write.
   @return_gs_error_t
*/
typedef gs_error_t (*gs_vmem_write_function_t)(const gs_vmem_t * vmem, void* to, const void * from, size_t size);

/**
   VMEM driver read.

   @param[in] vmem vmem entry.
   @param[in] to   Address where to read data to.
   @param[in] from Address where to read data from.
   @param[in] size Number of bytes to read.
   @return_gs_error_t
*/
typedef gs_error_t (*gs_vmem_read_function_t)(const gs_vmem_t * vmem, void* to, const void * from, size_t size);

/**
   VMEM driver lock.

   @param[in] vmem vmem entry.
   @param[in] on   Enable/Disable lock.
   @return_gs_error_t
*/
typedef gs_error_t (*gs_vmem_lock_function_t)(const gs_vmem_t * vmem, bool on);

/**
   VMEM driver information.

   Return relevant information for the VMEM driver.

   @param[in] vmem vmem entry.
   @param[in] buffer user allocated buffer for returning information.
   @param[in] buffer_size size (length) of \a buffer.
   @return_gs_error_t
*/
typedef gs_error_t (*gs_vmem_info_function_t)(const gs_vmem_t * vmem, char * buffer, size_t buffer_size);
    
/**
   VMEM driver interface.
*/
typedef struct {
    /**
       Write function.
    */
    const gs_vmem_write_function_t write;
    /**
       Read function.
    */
    const gs_vmem_read_function_t  read;
    /**
       Lock function.
    */
    const gs_vmem_lock_function_t  lock;
    /**
       Information function.
    */
    const gs_vmem_info_function_t  info;
} gs_vmem_driver_t;

/**
   Virtual memory mapping.

   @note Call gs_vmem_set_map() for registering mappings.
*/
struct gs_vmem {
    /**
       Logical name of enry.
    */
    const char *const name;
    /**
       Virtual memory start.
    */
    gs_address_t virtmem;
    /**
       Physical memory start.
       This address only makes sense for the VMEM driver.
    */
    gs_address_t physmem;
    /**
       Size of memory block.
    */
    const size_t size;
    /**
       Driver function.
    */
    const gs_vmem_driver_t* drv;
    /**
       Driver data.
    */
    const void* drv_data;
};

/**
   Set VMEM mapping.
   Must be done for the API to work.
   @param[in] map VMEM mapping table, must be terminated with an NULL entry.
   @return_gs_error_t
*/
gs_error_t gs_vmem_set_map(const gs_vmem_t * map);

/**
   Return VMEM map.
*/
const gs_vmem_t * gs_vmem_get_map(void);

/**
   Print all VMEM entries to stdout.
   @param[in] out output stream
   @return_gs_error_t
*/
gs_error_t gs_vmem_list(FILE * out);

/**
   Get VMEM entry by name.
   @param[in] name name of VMEM entry.
   @return VMEM mapping or NULL if not found.
*/
const gs_vmem_t * gs_vmem_get_by_name(const char * name);

/**
   Lock/un-lock VMEM area.
   @param[in] name name of VMEM entry.
   @param[in] on   Enable/Disable lock.
   @return GS_ERROR_NOT_FOUND area not found.
   @return GS_ERROR_NOT_SUPPORTED if locking isn't supported.
   @return_gs_error_t
*/
gs_error_t gs_vmem_lock_by_name(const char * name, bool on);

/**
   Lock/un-lock all VMEM areas.
   @param[in] on lock on or off.
   @return_gs_error_t
*/
gs_error_t gs_vmem_lock_all(bool on);

/**
   memcpy on VMEM.
   @note if no VMEM entries are found, a normal memcpy is called with the provided pointers.
   @param[in] to to location.
   @param[in] from from location.
   @param[in] size number of bytes to copy.
*/
void* gs_vmem_cpy(void* to, const void* from, size_t size);

/**
   Macro for calling gs_vmem_cpy().
*/
#define GS_VMEM_CPY(to, from, size) gs_vmem_cpy(to, from, size)

/**
   Macro for calling gs_vmem_cpy().
   @deprecated Use gs_vmem_cpy() directly.
*/
#define VMEM_CPY(to, from, size)    gs_vmem_cpy(to, from, size)

/**
   Register VMEM commands.
   @return_gs_error_t
*/
gs_error_t gs_vmem_register_commands(void);

#ifdef __cplusplus
}
#endif
#endif