drivers/gpu/drm/img-rogue/ra.h - chromiumos/third_party/kernel - Git at Google

 /*************************************************************************/ /*!
 @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
	/************************************************************************/ /!
	@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