/****************************************************************************

Copyright(c) 2019 by Aerospace C.Power (Chongqing) Microelectronics. ALL RIGHTS RESERVED.

This Information is proprietary to Aerospace C.Power (Chongqing) Microelectronics and MAY NOT
be copied by any method or incorporated into another program without
the express written consent of Aerospace C.Power. This Information or any portion
thereof remains the property of Aerospace C.Power. The Information contained herein
is believed to be accurate and Aerospace C.Power assumes no responsibility or
liability for its use in any way and conveys no license or title under
any patent or copyright and makes no representation or warranty that this
Information is free from patent or copyright infringement.

****************************************************************************/

#ifndef OS_SHIM_MEM_API_H
#define OS_SHIM_MEM_API_H

/* os shim includes */
#include "os_types_api.h"

/* common includes */
#include "iot_config_api.h"
#include "iot_module_api.h"

#ifdef __cplusplus
extern "C" {
#endif

/** \defgroup OS_APIs PLC OS APIs
  * @brief WQ30x1 PLC OS APIs
  */

/**
 * @brief MALLOC Tags
 */
#define MALLOC_CAP_INVALID  0x0000
#define MALLOC_CAP_SYS      0x0001
#define MALLOC_CAP_AI_R     0x0002
#define MALLOC_CAP_AI_W     0x0004

/** @addtogroup OS_APIs
  * @{
  */

/** \defgroup OS_MEM_APIs PLC OS MEM APIs
  * @brief PLC OS MEM
  *
  * OS MEMORY helper function for customer application
  */

/** @addtogroup OS_MEM_APIs
  * @{
  */

/**
 * @brief os_mem_cpy() - copy memory from one location to another, similar to
 * memcpy in standard c. Calling this function with overlapping source and
 * destination memory location will result in unpredictable result.
 * @param dst:              pointer to destination memory location
 * @param src:              pointer to source memory location
 * @param len:              number of bytes to copy
 */
void os_mem_cpy(void *dst, const void *src, uint32_t len);

/**
 * @breif os_mem_move() - move memory from one location to another, similar as
 * os_mem_cpy except that this function take care of source and destination
 * memory location overlapped case.
 * @param dst:              pointer to destination memory location
 * @param src:              pointer to source memory location
 * @param len:              number of bytes to be copied
 */
void os_mem_move(void *dst, const void *src, uint32_t len);

/**
 * @breif os_mem_cmp() - memory compare, compare two pieces of memory, similar
 * to memcmp function in standard c.
 * @param dst:              pointer to first location in memory to compare
 * @param src:              pointer to second location in memory to compare
 * @param len:              number of bytes to compare
 *
 * @return                  0 -- equal
 * @return                  < 0 -- dst is less than src
 * @return                  > 0 -- dst is bigger than src
 */
int32_t os_mem_cmp(const void *dst, const void *src, uint32_t len);

/**
 * @breif os_mem_set() - set memory with a specified byte value
 * @param ptr:              pointer to memory that will be set
 * @param value:            byte set in memory
 * @param len:              number of bytes to be set
 */
void os_mem_set(void *ptr, uint8_t value, uint32_t len);

/**
 * @breif os_mem_malloc() - allocate memory. Dynamicallly allocate
 * the number of bytes of memory. The allocated memory must be reset to 0.
 * @param module_id:     the module mallocing memory. For the debugging purpose.
 * @param size:          number of bytes of memory to be allocated
 *
 * @return               null -- for failure case
 * @return               otherwise -- pointer of allocated memory
 */
 #if IOT_OS_MALLOC_DEBUG
extern void *os_mem_malloc_debug(uint8_t *file, uint32_t line,
            module_id_t  module_id, size_t  size);
#define os_mem_malloc(module_id, size) \
    os_mem_malloc_debug((unsigned char *)__FILE__, __LINE__, module_id, size)
 #else
void *os_mem_malloc(module_id_t module_id, size_t size);
 #endif

 /**
 * @breif os_mem_malloc_tag() - allocate tagged memory. Dynamicallly allocate
 * the number of bytes of memory. The allocated memory must be reset to 0.
 * @param module_id:     the module mallocing memory. For the debugging purpose.
 * @param size:          number of bytes of memory to be allocated
 * @param mode:          MALLOC_CAP_SYS or MALLOC_CAP_AI and so on.
 * @return               null -- for failure case
 * @return               otherwise -- pointer of allocated memory
 */
 #if IOT_OS_MALLOC_DEBUG
 extern void *os_mem_malloc_tag_debug(uint8_t *file, uint32_t line,
    module_id_t  module_id, size_t  size,uint32_t mode);
 #define os_mem_malloc_tag(module_id, size,mode)\
    os_mem_malloc_tag_debug((unsigned char *)__FILE__, __LINE__,\
    module_id, size,mode)
 #else
 void *os_mem_malloc_tag(module_id_t module_id, size_t size,uint32_t mode);
 #endif

/**
 * @breif os_mem_free() - free memory
 * @param ptr:           pointer to the memory to be free'd.
 */
void os_mem_free(void *ptr);

/**
* @breif os_mem_aligned_malloc() - allocate tagged memory. Dynamicallly allocate
* the number of bytes of memory. The allocated memory must be reset to 0.
* @param module_id:     the module mallocing memory. For the debugging purpose.
* @param size:          number of bytes of memory to be allocated
* @param alignment:     alignment number.
* @return               null -- for failure case
* @return               otherwise -- pointer of allocated memory
*/
void* os_mem_aligned_malloc(module_id_t module_id,
    size_t bytes, size_t alignment);

/**
 * @breif os_mem_free() - free memory
 * @param ptr:           alignement pointer to the memory to be free'd.
 */
void os_mem_aligned_free(void* p);

/**
* @breif os_mem_free_get() - Obtain the remaining memory size of the system
*
* @return               return the remaining memory size(Bytes) of the system
*/
size_t os_mem_free_get(void);
/**
  * @}
  */

/**
  * @}
  */


#ifdef __cplusplus
}
#endif

#endif /* OS_SHIM_MEM_API_H */