/*************************************************************************/ /*!
@File
@Title          Resource Allocator API
@Copyright      Copyright (c) Imagination Technologies Ltd. All Rights Reserved
@License        Dual MIT/GPLv2

The contents of this file are subject to the MIT license as set out below.

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.

Alternatively, the contents of this file may be used under the terms of
the GNU General Public License Version 2 ("GPL") in which case the provisions
of GPL are applicable instead of those above.

If you wish to allow use of your version of this file only under the terms of
GPL, and not to allow others to use your version of this file under the terms
of the MIT license, indicate your decision by deleting the provisions above
and replace them with the notice and other provisions required by GPL as set
out in the file called "GPL-COPYING" included in this distribution. If you do
not delete the provisions above, a recipient may use your version of this file
under the terms of either the MIT license or GPL.

This License is also included in this distribution in the file called
"MIT-COPYING".

EXCEPT AS OTHERWISE STATED IN A NEGOTIATED AGREEMENT: (A) THE SOFTWARE IS
PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING
BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
PURPOSE AND NONINFRINGEMENT; AND (B) IN NO EVENT SHALL THE AUTHORS OR
COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/ /**************************************************************************/

#ifndef _RA_H_
#define _RA_H_


#include "img_types.h"
#include "pvrsrv_error.h"

/** Resource arena.
 *  struct _RA_ARENA_ deliberately opaque
 */
typedef struct _RA_ARENA_ RA_ARENA;			//PRQA S 3313

/*
 * Per-Arena handle - this is private data for the caller of the RA.
 * The RA knows nothing about this data.  It is given it upon
 * RA_Create, and promises to pass it to calls to the ImportAlloc and
 * ImportFree callbacks
 */
typedef IMG_HANDLE RA_PERARENA_HANDLE;
/*
 * Per-Import handle - this is private data for the caller of the RA.
 * The RA knows nothing about this data.  It is given it on a
 * per-import basis, either the "initial" import at RA_Create time, or
 * further imports via the ImportAlloc callback.  It sends it back via
 * the ImportFree callback, and also provides it in answer to any
 * RA_Alloc request to signify from which "import" the allocation came
 */
typedef IMG_HANDLE RA_PERISPAN_HANDLE;

typedef IMG_UINT64 RA_BASE_T;
typedef IMG_UINT32 RA_LOG2QUANTUM_T;
typedef IMG_UINT64 RA_LENGTH_T;

/* Lock classes: describes the level of nesting between different arenas. */
#define RA_LOCKCLASS_0 0
#define RA_LOCKCLASS_1 1
#define RA_LOCKCLASS_2 2

#define RA_NO_IMPORT_MULTIPLIER 1

/*
 * Flags in an "import" must much the flags for an allocation
 */
typedef IMG_UINT32 RA_FLAGS_T;

/**
 *  @Function   RA_Create
 *
 *  @Description
 *
 *  To create a resource arena.
 *
 *  @Input name - the name of the arena for diagnostic purposes.
 *  @Input uQuantum - the arena allocation quantum.
 *  @Input ui32LockClass - the lock class level this arena uses.
 *  @Input alloc - a resource allocation callback or 0.
 *  @Input free - a resource de-allocation callback or 0.
 *  @Input per_arena_handle - user private handle passed to alloc and free or 0.
 *  @Input bNoSplit - Disable splitting up imports.
 *  @Return pointer to arena, or NULL.
 */
RA_ARENA *
RA_Create (IMG_CHAR *name,
           /* subsequent imports: */
           RA_LOG2QUANTUM_T uLog2Quantum,
           IMG_UINT32 ui32LockClass,
           PVRSRV_ERROR (*imp_alloc)(RA_PERARENA_HANDLE _h,
                                 RA_LENGTH_T uSize,
                                 RA_FLAGS_T uFlags,
                                 const IMG_CHAR *pszAnnotation,
                                 RA_BASE_T *pBase,
                                 RA_LENGTH_T *pActualSize,
                                 RA_PERISPAN_HANDLE *phPriv),
           void (*imp_free) (RA_PERARENA_HANDLE,
                                 RA_BASE_T,
                                 RA_PERISPAN_HANDLE),
           RA_PERARENA_HANDLE per_arena_handle,
           IMG_BOOL bNoSplit);

/**
 *  @Function   RA_Delete
 *
 *  @Description
 *
 *  To delete a resource arena. All resources allocated from the arena
 *  must be freed before deleting the arena.
 *
 *  @Input  pArena - the arena to delete.
 *  @Return None
 */
void
RA_Delete (RA_ARENA *pArena);

/**
 *  @Function   RA_Add
 *
 *  @Description
 *
 *  To add a resource span to an arena. The span must not overlap with
 *  any span previously added to the arena.
 *
 *  @Input pArena - the arena to add a span into.
 *  @Input base - the base of the span.
 *  @Input uSize - the extent of the span.
 *  @Input hPriv - handle associated to the span (reserved to user uses)
 *  @Return IMG_TRUE - success, IMG_FALSE - failure
 */
IMG_BOOL
RA_Add (RA_ARENA *pArena,
		RA_BASE_T base,
		RA_LENGTH_T uSize,
		RA_FLAGS_T uFlags,
		RA_PERISPAN_HANDLE hPriv);

/**
 *  @Function   RA_Alloc
 *
 *  @Description
 *
 *  To allocate resource from an arena.
 *
 *  @Input  pArena - the arena
 *  @Input  uRequestSize - the size of resource segment requested.
 *  @Input  uImportMultiplier - Import x-times of the uRequestSize
 *          for future RA_Alloc calls.
 *          Use RA_NO_IMPORT_MULTIPLIER to import the exact size.
 *  @Output pActualSize - the actual_size of resource segment allocated,
 *          typcially rounded up by quantum.
 *  @Input  uImportFlags - flags influencing allocation policy.
 *  @Input  uAlignment - the alignment constraint required for the
 *          allocated segment, use 0 if alignment not required.
 *  @Input  pszAnnotation - a string to describe the allocation
 *  @Output pBase - allocated base resource
 *  @Output phPriv - the user reference associated with allocated
 *          resource span.
 *  @Return PVRSRV_OK - success
 */
PVRSRV_ERROR
RA_Alloc (RA_ARENA *pArena,
          RA_LENGTH_T uSize,
          IMG_UINT8 uImportMultiplier,
          RA_FLAGS_T uFlags,
          RA_LENGTH_T uAlignment,
          const IMG_CHAR *pszAnnotation,
          RA_BASE_T *pBase,
          RA_LENGTH_T *pActualSize,
          RA_PERISPAN_HANDLE *phPriv);

/**
 *  @Function   RA_Free
 *
 *  @Description    To free a resource segment.
 *
 *  @Input  pArena - the arena the segment was originally allocated from.
 *  @Input  base - the base of the resource span to free.
 *  @Input  bFreeBackingStore - Should backing store memory be freed?
 *
 *  @Return None
 */
void
RA_Free (RA_ARENA *pArena, RA_BASE_T base);

#endif