2 * Copyright (C) 2011-2012 ARM Limited. All rights reserved.
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.
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.
12 * @file mali_osk_mali.h
13 * Defines the OS abstraction layer which is specific for the Mali kernel device driver (OSK)
16 #ifndef __MALI_OSK_MALI_H__
17 #define __MALI_OSK_MALI_H__
26 /** @addtogroup _mali_osk_miscellaneous
29 /** @brief Struct with device specific configuration data
31 struct _mali_osk_device_data
33 /* Dedicated GPU memory range (physical). */
34 u32 dedicated_mem_start;
35 u32 dedicated_mem_size;
37 /* Shared GPU memory */
40 /* Frame buffer memory to be accessible by Mali GPU (physical) */
44 /* Report GPU utilization in this interval (specified in ms) */
45 u32 utilization_interval;
47 /* Function that will receive periodic GPU utilization numbers */
48 void (*utilization_handler)(unsigned int);
51 /** @brief Find Mali GPU HW resource
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
57 _mali_osk_errcode_t _mali_osk_resource_find(u32 addr, _mali_osk_resource_t *res);
60 /** @brief Find Mali GPU HW base address
62 * @return 0 if resources are found, otherwise the Mali GPU component with lowest address.
64 u32 _mali_osk_resource_base_address(void);
66 /** @brief Retrieve the Mali GPU specific data
68 * @return _MALI_OSK_ERR_OK on success, otherwise failure.
70 _mali_osk_errcode_t _mali_osk_device_data_get(struct _mali_osk_device_data *data);
72 /** @} */ /* end group _mali_osk_miscellaneous */
77 /** @addtogroup _mali_osk_low_level_memory
80 /** @brief Initialize a user-space accessible memory range
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.
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().
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
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().
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.
105 * Refer to \ref u_k_api for more information on the U/K interface.
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().
110 * @param descriptor the mali_memory_allocation to initialize.
112 _mali_osk_errcode_t _mali_osk_mem_mapregion_init( mali_memory_allocation * descriptor );
114 /** @brief Terminate a user-space accessible memory range
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
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.
125 * The \a descriptor itself is not freed - this must be handled by the caller of
126 * _mali_osk_mem_mapregion_term().
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
133 * @param descriptor the mali_memory_allocation to terminate.
135 void _mali_osk_mem_mapregion_term( mali_memory_allocation * descriptor );
137 /** @brief Map physical pages into a user process's virtual address range
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().
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.
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
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.
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
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.
166 * @param[in,out] descriptor the mali_memory_allocation representing the
167 * user-process's virtual address range to map into.
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.
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.
182 * @param[in] size the number of bytes to map in. This must be a multiple of
183 * \ref _MALI_OSK_CPU_PAGE_SIZE.
185 * @return _MALI_OSK_ERR_OK on sucess, otherwise a _mali_osk_errcode_t value
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.
192 _mali_osk_errcode_t _mali_osk_mem_mapregion_map( mali_memory_allocation * descriptor, u32 offset, u32 *phys_addr, u32 size );
195 /** @brief Unmap physical pages from a user process's virtual address range
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
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).
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.
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
221 * @param[in,out] descriptor the mali_memory_allocation representing the
222 * user-process's virtual address range to map into.
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.
228 * @param[in] size the number of bytes to unmap. This must be a multiple of
229 * \ref _MALI_OSK_CPU_PAGE_SIZE.
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.
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 */
243 #endif /* __MALI_OSK_MALI_H__ */