drivers/gpu/arm/mali400/mali/common/mali_osk_mali.h

   1 /*
   2  * Copyright (C) 2011-2012 ARM Limited. All rights reserved.
   3  *
   4  * This program is free software and is provided to you under the terms of the GNU General Public License version 2
   5  * as published by the Free Software Foundation, and any use by you of this program is subject to the terms of such GNU licence.
   6  *
   7  * A copy of the licence is included with the program, and can also be obtained from Free Software
   8  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
   9  */
  10
  11 /**
  12  * @file mali_osk_mali.h
  13  * Defines the OS abstraction layer which is specific for the Mali kernel device driver (OSK)
  14  */
  15
  16 #ifndef __MALI_OSK_MALI_H__
  17 #define __MALI_OSK_MALI_H__
  18
  19 #include <mali_osk.h>
  20
  21 #ifdef __cplusplus
  22 extern "C"
  23 {
  24 #endif
  25
  26 /** @addtogroup _mali_osk_miscellaneous
  27  * @{ */
  28
  29 /** @brief Struct with device specific configuration data
  30  */
  31 struct _mali_osk_device_data
  32 {
  33         /* Dedicated GPU memory range (physical). */
  34         u32 dedicated_mem_start;
  35         u32 dedicated_mem_size;
  36
  37         /* Shared GPU memory */
  38         u32 shared_mem_size;
  39
  40         /* Frame buffer memory to be accessible by Mali GPU (physical) */
  41         u32 fb_start;
  42         u32 fb_size;
  43
  44         /* Report GPU utilization in this interval (specified in ms) */
  45         u32 utilization_interval;
  46
  47         /* Function that will receive periodic GPU utilization numbers */
  48         void (*utilization_handler)(unsigned int);
  49 };
  50
  51 /** @brief Find Mali GPU HW resource
  52  *
  53  * @param addr Address of Mali GPU resource to find
  54  * @param res Storage for resource information if resource is found.
  55  * @return _MALI_OSK_ERR_OK on success, _MALI_OSK_ERR_ITEM_NOT_FOUND if resource is not found
  56  */
  57 _mali_osk_errcode_t _mali_osk_resource_find(u32 addr, _mali_osk_resource_t *res);
  58
  59
  60 /** @brief Find Mali GPU HW base address
  61  *
  62  * @return 0 if resources are found, otherwise the Mali GPU component with lowest address.
  63  */
  64 u32 _mali_osk_resource_base_address(void);
  65
  66 /** @brief Retrieve the Mali GPU specific data
  67  *
  68  * @return _MALI_OSK_ERR_OK on success, otherwise failure.
  69  */
  70 _mali_osk_errcode_t _mali_osk_device_data_get(struct _mali_osk_device_data *data);
  71
  72 /** @} */ /* end group _mali_osk_miscellaneous */
  73
  74
  75
  76
  77 /** @addtogroup _mali_osk_low_level_memory
  78  * @{ */
  79
  80 /** @brief Initialize a user-space accessible memory range
  81  *
  82  * This initializes a virtual address range such that it is reserved for the
  83  * current process, but does not map any physical pages into this range.
  84  *
  85  * This function may initialize or adjust any members of the
  86  * mali_memory_allocation \a descriptor supplied, before the physical pages are
  87  * mapped in with _mali_osk_mem_mapregion_map().
  88  *
  89  * The function will always be called with MALI_MEMORY_ALLOCATION_FLAG_MAP_INTO_USERSPACE
  90  * set in \a descriptor->flags. It is an error to call this function without
  91  * setting this flag. Otherwise, \a descriptor->flags bits are reserved for
  92  * future expansion
  93  *
  94  * The \a descriptor's process_addr_mapping_info member can be modified to
  95  * allocate OS-specific information. Note that on input, this will be a
  96  * ukk_private word from the U/K inteface, as inserted by _mali_ukk_mem_mmap().
  97  * This is used to pass information from the U/K interface to the OSK interface,
  98  * if necessary. The precise usage of the process_addr_mapping_info member
  99  * depends on the U/K implementation of _mali_ukk_mem_mmap().
 100  *
 101  * Therefore, the U/K implementation of _mali_ukk_mem_mmap() and the OSK
 102  * implementation of  _mali_osk_mem_mapregion_init() must agree on the meaning and
 103  * usage of the ukk_private word and process_addr_mapping_info member.
 104  *
 105  * Refer to \ref u_k_api for more information on the U/K interface.
 106  *
 107  * On successful return, \a descriptor's mapping member will be correct for
 108  * use with _mali_osk_mem_mapregion_term() and _mali_osk_mem_mapregion_map().
 109  *
 110  * @param descriptor the mali_memory_allocation to initialize.
 111  */
 112 _mali_osk_errcode_t _mali_osk_mem_mapregion_init( mali_memory_allocation * descriptor );
 113
 114 /** @brief Terminate a user-space accessible memory range
 115  *
 116  * This terminates a virtual address range reserved in the current user process,
 117  * where none, some or all of the virtual address ranges have mappings to
 118  * physical pages.
 119  *
 120  * It will unmap any physical pages that had been mapped into a reserved
 121  * virtual address range for the current process, and then releases the virtual
 122  * address range. Any extra book-keeping information or resources allocated
 123  * during _mali_osk_mem_mapregion_init() will also be released.
 124  *
 125  * The \a descriptor itself is not freed - this must be handled by the caller of
 126  * _mali_osk_mem_mapregion_term().
 127  *
 128  * The function will always be called with MALI_MEMORY_ALLOCATION_FLAG_MAP_INTO_USERSPACE
 129  * set in descriptor->flags. It is an error to call this function without
 130  * setting this flag. Otherwise, descriptor->flags bits are reserved for
 131  * future expansion
 132  *
 133  * @param descriptor the mali_memory_allocation to terminate.
 134  */
 135 void _mali_osk_mem_mapregion_term( mali_memory_allocation * descriptor );
 136
 137 /** @brief Map physical pages into a user process's virtual address range
 138  *
 139  * This is used to map a number of physically contigous pages into a
 140  * user-process's virtual address range, which was previously reserved by a
 141  * call to _mali_osk_mem_mapregion_init().
 142  *
 143  * This need not provide a mapping for the entire virtual address range
 144  * reserved for \a descriptor - it may be used to map single pages per call.
 145  *
 146  * The function will always be called with MALI_MEMORY_ALLOCATION_FLAG_MAP_INTO_USERSPACE
 147  * set in \a descriptor->flags. It is an error to call this function without
 148  * setting this flag. Otherwise, \a descriptor->flags bits are reserved for
 149  * future expansion
 150  *
 151  * The function may supply \a *phys_addr == \ref MALI_MEMORY_ALLOCATION_OS_ALLOCATED_PHYSADDR_MAGIC.
 152  * In this case, \a size must be set to \ref _MALI_OSK_CPU_PAGE_SIZE, and the function
 153  * will allocate the physical page itself. The physical address of the
 154  * allocated page will be returned through \a phys_addr.
 155  *
 156  * It is an error to set \a size != \ref _MALI_OSK_CPU_PAGE_SIZE while
 157  * \a *phys_addr == \ref MALI_MEMORY_ALLOCATION_OS_ALLOCATED_PHYSADDR_MAGIC,
 158  * since it is not always possible for OSs to support such a setting through this
 159  * interface.
 160  *
 161  * @note \b IMPORTANT: This code must validate the input parameters. If the
 162  * range defined by \a offset and \a size is outside the range allocated in
 163  * \a descriptor, then this function \b MUST not attempt any mapping, and must
 164  * instead return a suitable \ref _mali_osk_errcode_t \b failure code.
 165  *
 166  * @param[in,out] descriptor the mali_memory_allocation representing the
 167  * user-process's virtual address range to map into.
 168  *
 169  * @param[in] offset the offset into the virtual address range. This is only added
 170  * to the mapping member of the \a descriptor, and not the \a phys_addr parameter.
 171  * It must be a multiple of \ref _MALI_OSK_CPU_PAGE_SIZE.
 172  *
 173  * @param[in,out] phys_addr a pointer to the physical base address to begin the
 174  * mapping from. If \a size == \ref _MALI_OSK_CPU_PAGE_SIZE and
 175  * \a *phys_addr == \ref MALI_MEMORY_ALLOCATION_OS_ALLOCATED_PHYSADDR_MAGIC, then this
 176  * function will allocate the physical page itself, and return the
 177  * physical address of the page through \a phys_addr, which will be aligned to
 178  * \ref _MALI_OSK_CPU_PAGE_SIZE. Otherwise, \a *phys_addr must be aligned to
 179  * \ref _MALI_OSK_CPU_PAGE_SIZE, and is unmodified after the call.
 180  * \a phys_addr is unaffected by the \a offset parameter.
 181  *
 182  * @param[in] size the number of bytes to map in. This must be a multiple of
 183  * \ref _MALI_OSK_CPU_PAGE_SIZE.
 184  *
 185  * @return _MALI_OSK_ERR_OK on sucess, otherwise a _mali_osk_errcode_t value
 186  * on failure
 187  *
 188  * @note could expand to use _mali_osk_mem_mapregion_flags_t instead of
 189  * \ref MALI_MEMORY_ALLOCATION_OS_ALLOCATED_PHYSADDR_MAGIC, but note that we must
 190  * also modify the mali process address manager in the mmu/memory engine code.
 191  */
 192 _mali_osk_errcode_t _mali_osk_mem_mapregion_map( mali_memory_allocation * descriptor, u32 offset, u32 *phys_addr, u32 size );
 193
 194
 195 /** @brief Unmap physical pages from a user process's virtual address range
 196  *
 197  * This is used to unmap a number of physically contigous pages from a
 198  * user-process's virtual address range, which were previously mapped by a
 199  * call to _mali_osk_mem_mapregion_map(). If the range specified was allocated
 200  * from OS memory, then that memory will be returned to the OS. Whilst pages
 201  * will be mapped out, the Virtual address range remains reserved, and at the
 202  * same base address.
 203  *
 204  * When this function is used to unmap pages from OS memory
 205  * (_mali_osk_mem_mapregion_map() was called with *phys_addr ==
 206  * \ref MALI_MEMORY_ALLOCATION_OS_ALLOCATED_PHYSADDR_MAGIC), then the \a flags must
 207  * include \ref _MALI_OSK_MEM_MAPREGION_FLAG_OS_ALLOCATED_PHYSADDR. This is because
 208  * it is not always easy for an OS implementation to discover whether the
 209  * memory was OS allocated or not (and so, how it should release the memory).
 210  *
 211  * For this reason, only a range of pages of the same allocation type (all OS
 212  * allocated, or none OS allocacted) may be unmapped in one call. Multiple
 213  * calls must be made if allocations of these different types exist across the
 214  * entire region described by the \a descriptor.
 215  *
 216  * The function will always be called with MALI_MEMORY_ALLOCATION_FLAG_MAP_INTO_USERSPACE
 217  * set in \a descriptor->flags. It is an error to call this function without
 218  * setting this flag. Otherwise, \a descriptor->flags bits are reserved for
 219  * future expansion
 220  *
 221  * @param[in,out] descriptor the mali_memory_allocation representing the
 222  * user-process's virtual address range to map into.
 223  *
 224  * @param[in] offset the offset into the virtual address range. This is only added
 225  * to the mapping member of the \a descriptor. \a offset must be a multiple of
 226  * \ref _MALI_OSK_CPU_PAGE_SIZE.
 227  *
 228  * @param[in] size the number of bytes to unmap. This must be a multiple of
 229  * \ref _MALI_OSK_CPU_PAGE_SIZE.
 230  *
 231  * @param[in] flags specifies how the memory should be unmapped. For a range
 232  * of pages that were originally OS allocated, this must have
 233  * \ref _MALI_OSK_MEM_MAPREGION_FLAG_OS_ALLOCATED_PHYSADDR set.
 234  */
 235 void _mali_osk_mem_mapregion_unmap( mali_memory_allocation * descriptor, u32 offset, u32 size, _mali_osk_mem_mapregion_flags_t flags );
 236 /** @} */ /* end group _mali_osk_low_level_memory */
 237
 238
 239 #ifdef __cplusplus
 240 }
 241 #endif
 242
 243 #endif /* __MALI_OSK_MALI_H__ */