r_cdi_api.h

/*
****************************************************************************
PROJECT : VLIB
FILE    : $Id: r_cdi_api.h 4752 2015-02-05 17:50:11Z matthias.nippert $
============================================================================
DESCRIPTION
CDI
============================================================================
                            C O P Y R I G H T
============================================================================
                       Copyright (c) 2013 - 2014
                                  by
                       Renesas Electronics (Europe) GmbH.
                           Arcadiastrasse 10
                          D-40472 Duesseldorf
                               Germany
                          All rights reserved.
============================================================================
Purpose: only for testing, not for mass production

DISCLAIMER

LICENSEE has read, understood and accepted the terms and conditions defined in
the license agreement, especially the usage rights. In any case, it is
LICENSEE's responsibility to make sure that any user of the software complies
with the terms and conditions of the signed license agreement.

SAMPLE CODE is not part of the licensed software, as such it must not be used in
mass-production applications. It can only be used for evaluation and
demonstration purposes at customer's premises listed in the signed license
agreement.

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

#ifndef R_CDI_API_H_
#define R_CDI_API_H_

#ifdef __cplusplus
extern "C"
{
#endif

#define R_CDI_MEM_DEBUG

    /*******************************************************************************
      Title: CDI API Functions

      An application using the buffer and/or the heap management
      must include this file
    */
    /*******************************************************************************
      Section: Global Types
    */

    /*******************************************************************************
      Type: r_cdi_RBuf_t

      Ring buffer structure

      Members:
      Start   - Pointer to valid data start position
      Stop    - Pointer to the first empty position
      Buffer  - Pointer to the data buffer
      Num     - Number of possible data in the Ring buffer
      Size    - Size of the data of buffer (Byte)
    */

    typedef struct
    {
        void    *Start;
        void    *Stop;
        void    *Buffer;
        uint32_t Num;
        uint8_t  Size;
    } r_cdi_RBuf_t;

    /*******************************************************************************
      Type: r_cdi_HpBlkIndex_t

      Used to keep track of the reserved blocks: uint16_t.
    */
    typedef uint16_t r_cdi_HpBlkIndex_t;

    /*******************************************************************************
      Enum: r_cdi_HpType_t

      Enumeration specifying the memory type of a heap block

      Values:
      CPU               - Block is in CPU memory
      VIDEO             - Block is in Video memory
      SPECIAL_MODE      - This mode can only be used on DK4-H Systems!
                          The memory block is located in the video memory but is
                          accessed via a so called "Special Access Mode", which allows to store
                          data in a graphics oriented way.

                          In order to use SPECIAL_MODE, the Vmem Macro has to be enabled and a valid
                          mode must be set. Please refer to "vmem_api.h" and the Chapter "VMEM" in the
                          DK4-H Memory for further information.

                          Be aware that VIDEO and SPECIAL_MODE refer to the same physical Ram, so it is
                          possible to overwrite data if both modes are used at the same time.

                          While in this mode data access is always 32 bit, but only 18 / 20 / 24 bits
                          are valid, depending on the VMEM Settings.

                          Bit assignment:

                          18 bit mode: ------------------------------------------------------------------------------------------------

                                HBUS Write  : 31 - 26 | 25 - 24 | 23 - 18 | 17 - 16 | 15 - 10 |  9 -  0
                                Stored Data : 17 - 12 | ignored | 11 -  6 | ignored |  5 -  0 | ignored

                                HBUS Read   : 31 - 26 | 25 - 24 | 23 - 18 | 17 - 16 | 15 - 10 |  9 -  8 |  7 -  0
                                Stored Data : 17 - 12 | 17 - 16 | 11 -  6 | 11 - 10 |  5 -  0 |  5 -  4 |  Fix 0xFF

                          20 bit mode: ------------------------------------------------------------------------------------------------

                                HBUS Write  : 31 - 26 | 25 - 24 | 23 - 18 | 17 - 16 | 15 - 10 |  9 -  8 | 7 - 6 | 5 - 0
                                Stored Data : 19 - 14 | ignored | 13 -  8 | ignored |  7 -  2 | ignored | 1 - 0 | ignored

                                HBUS Read   : 31 - 26 | 25 - 24 | 23 - 18 | 17 - 16 | 15 - 10 |  9 -  8 | 7 - 6 | 5 - 4 | 3 - 2 | 1 - 0
                                Stored Data : 19 - 14 | 19 - 18 | 13 -  8 | 13 - 12 |  7 -  2 |  7 -  6 | 1 - 0 | 1 - 0 | 1 - 0 | 1 - 0

                          24 bit mode (6666): -----------------------------------------------------------------------------------------

                                HBUS Write  : 31 - 26 | 25 - 24 | 23 - 18 | 17 - 16 | 15 - 10 |  9 -  8 | 7 - 2 | 1 - 0
                                Stored Data : 23 - 18 | ignored | 17 - 12 | ignored | 11 -  6 | ignored | 5 - 0 | ignored

                                HBUS Read   : 31 - 26 | 25 - 24 | 23 - 18 | 17 - 16 | 15 - 10 |  9 -  8 | 7 - 2 | 1 - 0
                                Stored Data : 23 - 18 | 23 - 22 | 17 - 12 | 17 - 16 | 11 -  6 | 11 - 10 | 5 - 0 | 5 - 4

                          24 bit mode (8880): -----------------------------------------------------------------------------------------

                                HBUS Write  : 31 - 24 | 23 - 16 | 15 - 8 |  7 - 0
                                Stored Data : 23 - 16 | 15 -  8 |  7 - 0 | ignored

                                HBUS Read   : 31 - 24 | 23 - 16 | 15 - 8 |  7 - 0
                                Stored Data : 23 - 16 | 15 -  8 |  7 - 0 | Fix 0xFF




    */
    typedef enum
    {
        CPU,
        VIDEO,
        SPECIAL_MODE
    } r_cdi_HpType_t;

    /*******************************************************************************
      Type: r_cdi_HeapMng_t

      Structure defining a heap manager

      Members:
      BaseAddr       - 32-bit start address of heap
      NbOfBlock      - Number of blocks the heap is divided in
      BlockSize      - Size of one block
      Type           - Memory type. See <r_cdi_HpType_t>
      BlockIndexList - Pointer to an array of type <r_cdi_HpBlkIndex_t>
                       Each block has one index.
    */
    typedef struct
    {
        uint32_t            BaseAddr;
        uint32_t            NbOfBlock;
        uint32_t            BlockSize;
        r_cdi_HpType_t      Type;
        r_cdi_HpBlkIndex_t *BlockIndexList;
    } r_cdi_HeapMng_t;

    /*******************************************************************************
      Type: r_cdi_Heap_t

      Structure defining a heap manager

      Members:
      BaseAddr        - 32-bit start address of heap
      NbOfBlock       - Number of blocks the heap is divided in
      BlockSize       - Size of one block
      BlockIdxList    - Pointer to an array of type <r_cdi_HpBlkIndex_t>
                        Each block has one index.
      NextBlockIdx    -
      FreeBlocks      -
      NextFreeBlockNb -
    */
    typedef struct
    {
        uint32_t            BaseAddr;
        uint32_t            NbOfBlock;
        uint32_t            BlockSize;
        r_cdi_HpBlkIndex_t *BlockIdxList;
        r_cdi_HpBlkIndex_t  NextBlockIdx;
        r_cdi_HpBlkIndex_t  FreeBlocks;
        r_cdi_HpBlkIndex_t  NextFreeBlockNb;

    } r_cdi_Heap_t;

    /*******************************************************************************
      Section: Global API Base Functions
    */
    /*******************************************************************************
      Function: R_CDI_Init

      Empty function.

      Parameters:
      None

      Returns:
      int32_t - always 0

    */
    int32_t R_CDI_Init(void);

    /*******************************************************************************
      Function: R_CDI_DeInit

      Empty function.

      Parameters:
      None

      Returns:
      int32_t - always 0

    */
    int32_t R_CDI_DeInit(void);

    /*******************************************************************************
      Section: Global API Ring Buffer Functions
    */

    /*******************************************************************************
      Function: R_CDI_RbSetup

      Setup a ring buffer structure.

      Parameters:
      RBuf       - Ring buffer structure. See: <r_cdi_RBuf_t>
      Buf        - Data buffer
      Num        - Number of elements in buffer
      Size       - Size of the data in buffer

      Returns:
      == 0       - Setup OK
      != 0       - Setup failed
    */
    int32_t R_CDI_RbSetup(r_cdi_RBuf_t *RBuf, void *Buf, uint32_t Num, uint8_t Size);

    /*******************************************************************************
      Function: R_CDI_RbWrite

      Copy data to ring buffer.

      Parameters:
      RBuf       - Ring buffer. See: <r_cdi_RBuf_t>
      Buffer     - Data buffer
      Num        - Number of bytes in data buffer

      Returns:
      Number of elements, which have been copied.
    */
    uint32_t R_CDI_RbWrite(r_cdi_RBuf_t *RBuf, void *Buffer, uint32_t Num);

    /*******************************************************************************
      Function: R_CDI_RbRead

      Copy data from ring buffer.

      Parameters:
      RBuf       - Ring buffer. See: <r_cdi_RBuf_t>
      Buffer     - Data buffer
      MaxNum     - Number of data to read

      Returns:
      Number of elements, which have been copied.
    */
    uint32_t R_CDI_RbRead(r_cdi_RBuf_t *RBuf, void *Buffer, uint32_t MaxNum);

    /*******************************************************************************
      Function: R_CDI_RbSize

      Calculates how much elements are in the buffer

      Parameters:
      RBuf       - Ring buffer. See: <r_cdi_RBuf_t>

      Returns:
      Number of elements, which are in ring buffer.
    */
    uint32_t R_CDI_RbNum(r_cdi_RBuf_t *RBuf);

    /*******************************************************************************
      Section: Global API Memory Controller Functions
    */

    /*******************************************************************************
      Function: R_CDI_InitCpuHeapManager

      Initialise the CPU memory manager with the given parameters.

      Parameters:
      hpaddr         - 32-bit address pointing to an existing heap buffer of type uint32_t.
      hpblkindexlist - Pointer to an array of <r_cdi_HpBlkIndex_t>.
                       This array contains the indexes of the hp blocks
      nbblk          - Number of blocks in the heap
      blksize        - Size of one heap block in bytes

      Returns:
      == 0       - Initialisation OK
      != 0       - Initialisation failed (1 = 1 of the pointer is not correct)
    */
    uint32_t R_CDI_InitCpuHeapManager(
        uint32_t            hpaddr,
        r_cdi_HpBlkIndex_t *hpblkindexlist,
        uint32_t            nbblk,
        uint32_t            blksize);

    /*******************************************************************************
      Function: R_CDI_InitVidHeapManager

      Initialise the video memory manager with the given parameters.

      Parameters:
      hpaddr         - Start address of the VID memory.
      hpblkindexlist - Pointer to an array of <r_cdi_HpBlkIndex_t>
                       This array contains the indexes of the hp blocks
      nbblock        - Number of blocks in the heap
      blksize        - Size of one heap block in bytes

      Returns:
      == 0       - Initialisation OK
      != 0       - Initialisation failed
    */
    uint32_t R_CDI_InitVidHeapManager(
        uint32_t            hpaddr,
        r_cdi_HpBlkIndex_t *hpblkindexlist,
        uint32_t            nbblock,
        uint32_t            blksize);

    /*******************************************************************************
      Function: R_CDI_InitSmHeapManager

      Initialise the SPECIAL_MODE manager with the given parameters.

      The SPECIAL_MODE allows a special access to video memory. It is currently only used in DK4-H (-> VMEM).
      If you use SPECIAL_MODE, make sure that your device supports this type of memory.

      Parameters:
      hpaddr         - Start address of the VID memory.
      hpblkindexlist - Pointer to an array of <r_cdi_HpBlkIndex_t>
                       This array contains the indexes of the hp blocks
      nbblock        - Number of blocks in the heap
      blksize        - Size of one heap block in bytes

      Returns:
      == 0       - Initialisation OK
      != 0       - Initialisation failed
    */
    uint32_t R_CDI_InitSmHeapManager(
        uint32_t            hpaddr,
        r_cdi_HpBlkIndex_t *hpblkindexlist,
        uint32_t            nbblock,
        uint32_t            blksize);

    /*******************************************************************************
      Function: R_CDI_InitHeapManager

      Initialise the given memory manager with the given parameters.

      Parameters:
      HeapAddr        - Start address of the heap memory.
                        Note: If you need aligned memory addresses,
                              please make sure that <HeapAddr> is aligned to <BlkSize>.
                              Also, <R_CDI_AllocAlign> will only work correctly if this requirement is met.
      HeapMng         - Pointer to the heap manager structure, see  <r_cdi_HeapMng_t>
      HeapIdxList     - Pointer to an array of <r_cdi_HpBlkIndex_t>
                        This array contains the indexes of the heap blocks
                        Optional:  If this pointer is NULL, the index list will be placed at
                                   the end of the here-initialised memory area. The required
                                   memory will automatically be reserved during initialisation.
      NbBlocks        - Number of blocks in the heap
      BlkSize         - Size of one heap block in bytes

      Returns:
      == 0       - Initialisation OK
      != 0       - Initialisation failed
    */
    uint32_t R_CDI_InitHeapManager(
        uint32_t            HeapAddr,
        r_cdi_Heap_t       *HeapMng,
        r_cdi_HpBlkIndex_t *HeapIdxList,
        uint32_t            NbBlocks,
        uint32_t            BlkSize);

    /*******************************************************************************
      Function: R_CDI_Alloc

      Allocate one or more blocks of the given heap with the size of memory requested.

      Parameters:
      HeapMng - Pointer to the heap manager structure, see  <r_cdi_Heap_t>
      Size    - Memory size requested.

      Returns:
      !=0     - void pointer to memory start address
      == 0    - Allocation failed
    */
    void *R_CDI_Alloc(r_cdi_Heap_t *HeapMng, uint32_t Size);

    /***********************************************************
      Function: R_CDI_AllocAlign

      This is the same function as R_CDI_Alloc but with aligned allocations.

      The allocation is implemented such that the unused space that is skipped due to alignment
      is marked as "free" and could still be used when the heap is otherwise exhausted.

      NOTE:
      As the alignment is done via a block alignment, it is required that the base address
      of this CDI heap is already aligned to the block size set during heap initialization.

      Parameters:
      HeapMng   - Pointer to the heap manager structure, see  <r_cdi_Heap_t>
      Size      - Memory size requested.
      Alignment - Alignment of the requested memory. Must be a multiple of the power of two.

      Returns:
      !=0     - void pointer to memory start address
      == 0    - Allocation failed
    */
    void *R_CDI_AllocAlign(r_cdi_Heap_t *HeapMng, uint32_t Size, uint32_t Alignment);

    /*******************************************************************************
      Function: R_CDI_Free

      Free allocated memory. The start address and a pointer to the heap manger in question
      must be given as parameters.

      Parameters:
      Addr        - Memory start address
      HeapMng     - Pointer to the heap manager structure, see  <r_cdi_Heap_t>

      Returns:
      == 0       - Successful
      == 1       - Wrong type
      == 2       - Address not found
    */
    uint32_t R_CDI_Free(uint32_t Addr, r_cdi_Heap_t *HeapMng);

    /*******************************************************************************
      Function: R_CDI_HeapAlloc

      Allocate one or more blocks of heap in function of the size of memory requested.
      The heap type is passed as parameter with the size.

      Parameters:
      size    - Memory size requested.
      type    - Type of memory to be allocated. See <r_cdi_HpType_t>

      Returns:
      !=0     - Memory start address
      == 0    - Allocation failed
    */
    uint32_t R_CDI_HeapAlloc(uint32_t size, r_cdi_HpType_t type);

    /*******************************************************************************
      Function: R_CDI_HeapResetNextFreeBlockNb

      Reset the pointer where to start searching for free
      memory (of the specified type) for the next allocation.

      Parameters:
      type    - Type of memory

      Returns:
      == 0       - Successful
      != 0       - Failed
    */
    uint32_t R_CDI_HeapResetNextFreeBlockNb(r_cdi_HpType_t type);

    /*******************************************************************************
      Function: R_CDI_HeapFree

      Free allocated memory. The start address, type of the memory to be free
      must be given as parameters.

      Parameters:
      addr    - Memory start address
      type    - Type of memory

      Returns:
      == 0       - Successful
      == 1       - Wrong type
      == 2       - Address not found
    */
    uint32_t R_CDI_HeapFree(uint32_t addr, r_cdi_HpType_t type);

    /*******************************************************************************
      Function: R_CDI_HeapFreeAll

      Free all blocks of the memory type specified in parameter.

      Parameters:
      type    - Type of memory

      Returns:
      == 0       - Successful
      != 0       - Failed
    */
    uint32_t R_CDI_HeapFreeAll(r_cdi_HpType_t type);

    /*******************************************************************************
      Function: R_CDI_GetHeapSize

      Return the size in byte of the heap block allocated at the address given
      as input.

      Parameters:
      addr    - Start address of the heap memory area
      type    - Type of memory

      Returns:
      uint32_t       - Size of the reserved memory area starting at "addr"
    */
    uint32_t R_CDI_GetHeapSize(uint32_t addr, r_cdi_HpType_t type);

    /*******************************************************************************
      Function: R_CDI_GetVidHeapBlockSize

      Return the size in byte of video heap blocks.

      Parameters:
      None

      Returns:
      uint32_t       - Size of one video heap block
    */
    uint32_t R_CDI_GetVidHeapBlockSize(void);

    /*******************************************************************************
      Function: R_CDI_GetVidHeapBlockMax

      Return the number of video heap blocks.

      Parameters:
      None

      Returns:
      uint32_t       - Number of video heap blocks
    */
    uint32_t R_CDI_GetVidHeapBlockMax(void);

    /*******************************************************************************
      Function: R_CDI_GetVidHeapBlockUsed

      Return the number of video heap blocks already in use.

      Parameters:
      None

      Returns:
      uint32_t       - Number of video heap blocks already in use
    */
    uint32_t R_CDI_GetVidHeapBlockUsed(void);

    /*******************************************************************************
      Function: R_CDI_GetCpuHeapBlockSize

      Return the size in byte of cpu heap blocks.

      Parameters:
      None

      Returns:
      uint32_t       - Size of one cpu heap block
    */
    uint32_t R_CDI_GetCpuHeapBlockSize(void);

    /*******************************************************************************
      Function: R_CDI_GetCpuHeapBlockMax

      Return the number of cpu heap blocks.

      Parameters:
      None

      Returns:
      uint32_t       - Number of cpu heap blocks
    */
    uint32_t R_CDI_GetCpuHeapBlockMax(void);

    /*******************************************************************************
      Function: R_CDI_GetCpuHeapBlockUsed

      Return the number of cpu heap blocks already in use.

      Parameters:
      None

      Returns:
      uint32_t       - Number of cpu heap blocks already in use
    */
    uint32_t R_CDI_GetCpuHeapBlockUsed(void);

#ifdef __cplusplus
}
#endif

#endif /* R_CDI_API_H_ */