drivers/media/video/samsung/mali/common/mali_osk_mali.h

   1 /*
   2  * Copyright (C) 2010 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 Initialize the OSK layer
  30  *
  31  * This function is used to setup any initialization of OSK functionality, if
  32  * required.
  33  *
  34  * This must be the first function called from the common code, specifically,
  35  * from the common code entry-point, mali_kernel_constructor.
  36  *
  37  * The OS-integration into the OS's kernel must handle calling of
  38  * mali_kernel_constructor when the device driver is loaded.
  39  *
  40  * @return _MALI_OSK_ERR_OK on success, or a suitable _mali_osk_errcode_t on
  41  * failure.
  42  */
  43 _mali_osk_errcode_t _mali_osk_init( void );
  44
  45 /** @brief Terminate the OSK layer
  46  *
  47  * This function is used to terminate any resources initialized by
  48  * _mali_osk_init.
  49  *
  50  * This must be the last function called from the common code, specifically,
  51  * from the common code closedown function, mali_kernel_destructor, and the
  52  * error path in mali_kernel_constructor.
  53  *
  54  * The OS-integration into the OS's kernel must handle calling of
  55  * mali_kernel_destructor when the device driver is terminated.
  56  */
  57 void _mali_osk_term( void );
  58
  59 /** @brief Read the Mali Resource configuration
  60  *
  61  * Populates a _mali_arch_resource_t array from configuration settings, which
  62  * are stored in an OS-specific way.
  63  *
  64  * For example, these may be compiled in to a static structure, or read from
  65  * the filesystem at startup.
  66  *
  67  * On failure, do not call _mali_osk_resources_term.
  68  *
  69  * @param arch_config a pointer to the store the pointer to the resources
  70  * @param num_resources the number of resources read
  71  * @return _MALI_OSK_ERR_OK on success. _MALI_OSK_ERR_NOMEM on allocation
  72  * error. For other failures, a suitable _mali_osk_errcode_t is returned.
  73  */
  74 _mali_osk_errcode_t _mali_osk_resources_init( _mali_osk_resource_t **arch_config, u32 *num_resources );
  75
  76 /** @brief Free resources allocated by _mali_osk_resources_init.
  77  *
  78  * Frees the _mali_arch_resource_t array allocated by _mali_osk_resources_init
  79  *
  80  * @param arch_config a pointer to the stored the pointer to the resources
  81  * @param num_resources the number of resources in the array
  82  */
  83 void _mali_osk_resources_term( _mali_osk_resource_t **arch_config, u32 num_resources);
  84 /** @} */ /* end group _mali_osk_miscellaneous */
  85
  86 /** @addtogroup _mali_osk_low_level_memory
  87  * @{ */
  88
  89 /** @brief Initialize a user-space accessible memory range
  90  *
  91  * This initializes a virtual address range such that it is reserved for the
  92  * current process, but does not map any physical pages into this range.
  93  *
  94  * This function may initialize or adjust any members of the
  95  * mali_memory_allocation \a descriptor supplied, before the physical pages are
  96  * mapped in with _mali_osk_mem_mapregion_map().
  97  *
  98  * The function will always be called with MALI_MEMORY_ALLOCATION_FLAG_MAP_INTO_USERSPACE
  99  * set in \a descriptor->flags. It is an error to call this function without
 100  * setting this flag. Otherwise, \a descriptor->flags bits are reserved for
 101  * future expansion
 102  *
 103  * The \a descriptor's process_addr_mapping_info member can be modified to
 104  * allocate OS-specific information. Note that on input, this will be a
 105  * ukk_private word from the U/K inteface, as inserted by _mali_ukk_mem_mmap().
 106  * This is used to pass information from the U/K interface to the OSK interface,
 107  * if necessary. The precise usage of the process_addr_mapping_info member
 108  * depends on the U/K implementation of _mali_ukk_mem_mmap().
 109  *
 110  * Therefore, the U/K implementation of _mali_ukk_mem_mmap() and the OSK
 111  * implementation of  _mali_osk_mem_mapregion_init() must agree on the meaning and
 112  * usage of the ukk_private word and process_addr_mapping_info member.
 113  *
 114  * Refer to \ref u_k_api for more information on the U/K interface.
 115  *
 116  * On successful return, \a descriptor's mapping member will be correct for
 117  * use with _mali_osk_mem_mapregion_term() and _mali_osk_mem_mapregion_map().
 118  *
 119  * @param descriptor the mali_memory_allocation to initialize.
 120  */
 121 _mali_osk_errcode_t _mali_osk_mem_mapregion_init( mali_memory_allocation * descriptor );
 122
 123 /** @brief Terminate a user-space accessible memory range
 124  *
 125  * This terminates a virtual address range reserved in the current user process,
 126  * where none, some or all of the virtual address ranges have mappings to
 127  * physical pages.
 128  *
 129  * It will unmap any physical pages that had been mapped into a reserved
 130  * virtual address range for the current process, and then releases the virtual
 131  * address range. Any extra book-keeping information or resources allocated
 132  * during _mali_osk_mem_mapregion_init() will also be released.
 133  *
 134  * The \a descriptor itself is not freed - this must be handled by the caller of
 135  * _mali_osk_mem_mapregion_term().
 136  *
 137  * The function will always be called with MALI_MEMORY_ALLOCATION_FLAG_MAP_INTO_USERSPACE
 138  * set in descriptor->flags. It is an error to call this function without
 139  * setting this flag. Otherwise, descriptor->flags bits are reserved for
 140  * future expansion
 141  *
 142  * @param descriptor the mali_memory_allocation to terminate.
 143  */
 144 void _mali_osk_mem_mapregion_term( mali_memory_allocation * descriptor );
 145
 146 /** @brief Map physical pages into a user process's virtual address range
 147  *
 148  * This is used to map a number of physically contigous pages into a
 149  * user-process's virtual address range, which was previously reserved by a
 150  * call to _mali_osk_mem_mapregion_init().
 151  *
 152  * This need not provide a mapping for the entire virtual address range
 153  * reserved for \a descriptor - it may be used to map single pages per call.
 154  *
 155  * The function will always be called with MALI_MEMORY_ALLOCATION_FLAG_MAP_INTO_USERSPACE
 156  * set in \a descriptor->flags. It is an error to call this function without
 157  * setting this flag. Otherwise, \a descriptor->flags bits are reserved for
 158  * future expansion
 159  *
 160  * The function may supply \a *phys_addr == \ref MALI_MEMORY_ALLOCATION_OS_ALLOCATED_PHYSADDR_MAGIC.
 161  * In this case, \a size must be set to \ref _MALI_OSK_CPU_PAGE_SIZE, and the function
 162  * will allocate the physical page itself. The physical address of the
 163  * allocated page will be returned through \a phys_addr.
 164  *
 165  * It is an error to set \a size != \ref _MALI_OSK_CPU_PAGE_SIZE while
 166  * \a *phys_addr == \ref MALI_MEMORY_ALLOCATION_OS_ALLOCATED_PHYSADDR_MAGIC,
 167  * since it is not always possible for OSs to support such a setting through this
 168  * interface.
 169  *
 170  * @note \b IMPORTANT: This code must validate the input parameters. If the
 171  * range defined by \a offset and \a size is outside the range allocated in
 172  * \a descriptor, then this function \b MUST not attempt any mapping, and must
 173  * instead return a suitable \ref _mali_osk_errcode_t \b failure code.
 174  *
 175  * @param[in,out] descriptor the mali_memory_allocation representing the
 176  * user-process's virtual address range to map into.
 177  *
 178  * @param[in] offset the offset into the virtual address range. This is only added
 179  * to the mapping member of the \a descriptor, and not the \a phys_addr parameter.
 180  * It must be a multiple of \ref _MALI_OSK_CPU_PAGE_SIZE.
 181  *
 182  * @param[in,out] phys_addr a pointer to the physical base address to begin the
 183  * mapping from. If \a size == \ref _MALI_OSK_CPU_PAGE_SIZE and
 184  * \a *phys_addr == \ref MALI_MEMORY_ALLOCATION_OS_ALLOCATED_PHYSADDR_MAGIC, then this
 185  * function will allocate the physical page itself, and return the
 186  * physical address of the page through \a phys_addr, which will be aligned to
 187  * \ref _MALI_OSK_CPU_PAGE_SIZE. Otherwise, \a *phys_addr must be aligned to
 188  * \ref _MALI_OSK_CPU_PAGE_SIZE, and is unmodified after the call.
 189  * \a phys_addr is unaffected by the \a offset parameter.
 190  *
 191  * @param[in] size the number of bytes to map in. This must be a multiple of
 192  * \ref _MALI_OSK_CPU_PAGE_SIZE.
 193  *
 194  * @return _MALI_OSK_ERR_OK on sucess, otherwise a _mali_osk_errcode_t value
 195  * on failure
 196  *
 197  * @note could expand to use _mali_osk_mem_mapregion_flags_t instead of
 198  * \ref MALI_MEMORY_ALLOCATION_OS_ALLOCATED_PHYSADDR_MAGIC, but note that we must
 199  * also modify the mali process address manager in the mmu/memory engine code.
 200  */
 201 _mali_osk_errcode_t _mali_osk_mem_mapregion_map( mali_memory_allocation * descriptor, u32 offset, u32 *phys_addr, u32 size );
 202
 203
 204 /** @brief Unmap physical pages from a user process's virtual address range
 205  *
 206  * This is used to unmap a number of physically contigous pages from a
 207  * user-process's virtual address range, which were previously mapped by a
 208  * call to _mali_osk_mem_mapregion_map(). If the range specified was allocated
 209  * from OS memory, then that memory will be returned to the OS. Whilst pages
 210  * will be mapped out, the Virtual address range remains reserved, and at the
 211  * same base address.
 212  *
 213  * When this function is used to unmap pages from OS memory
 214  * (_mali_osk_mem_mapregion_map() was called with *phys_addr ==
 215  * \ref MALI_MEMORY_ALLOCATION_OS_ALLOCATED_PHYSADDR_MAGIC), then the \a flags must
 216  * include \ref _MALI_OSK_MEM_MAPREGION_FLAG_OS_ALLOCATED_PHYSADDR. This is because
 217  * it is not always easy for an OS implementation to discover whether the
 218  * memory was OS allocated or not (and so, how it should release the memory).
 219  *
 220  * For this reason, only a range of pages of the same allocation type (all OS
 221  * allocated, or none OS allocacted) may be unmapped in one call. Multiple
 222  * calls must be made if allocations of these different types exist across the
 223  * entire region described by the \a descriptor.
 224  *
 225  * The function will always be called with MALI_MEMORY_ALLOCATION_FLAG_MAP_INTO_USERSPACE
 226  * set in \a descriptor->flags. It is an error to call this function without
 227  * setting this flag. Otherwise, \a descriptor->flags bits are reserved for
 228  * future expansion
 229  *
 230  * @param[in,out] descriptor the mali_memory_allocation representing the
 231  * user-process's virtual address range to map into.
 232  *
 233  * @param[in] offset the offset into the virtual address range. This is only added
 234  * to the mapping member of the \a descriptor. \a offset must be a multiple of
 235  * \ref _MALI_OSK_CPU_PAGE_SIZE.
 236  *
 237  * @param[in] size the number of bytes to unmap. This must be a multiple of
 238  * \ref _MALI_OSK_CPU_PAGE_SIZE.
 239  *
 240  * @param[in] flags specifies how the memory should be unmapped. For a range
 241  * of pages that were originally OS allocated, this must have
 242  * \ref _MALI_OSK_MEM_MAPREGION_FLAG_OS_ALLOCATED_PHYSADDR set.
 243  */
 244 void _mali_osk_mem_mapregion_unmap( mali_memory_allocation * descriptor, u32 offset, u32 size, _mali_osk_mem_mapregion_flags_t flags );
 245 /** @} */ /* end group _mali_osk_low_level_memory */
 246
 247
 248 #ifdef __cplusplus
 249 }
 250 #endif
 251
 252 #endif /* __MALI_OSK_MALI_H__ */