drivers/gpu/arm/mali400/ump/include/ump_kernel_interface.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 ump_kernel_interface.h
  13  *
  14  * This file contains the kernel space part of the UMP API.
  15  */
  16
  17 #ifndef __UMP_KERNEL_INTERFACE_H__
  18 #define __UMP_KERNEL_INTERFACE_H__
  19
  20
  21 /** @defgroup ump_kernel_space_api UMP Kernel Space API
  22  * @{ */
  23
  24
  25 #include "ump_kernel_platform.h"
  26
  27
  28 #ifdef __cplusplus
  29 extern "C"
  30 {
  31 #endif
  32
  33
  34 /**
  35  * External representation of a UMP handle in kernel space.
  36  */
  37 typedef void * ump_dd_handle;
  38
  39 /**
  40  * Typedef for a secure ID, a system wide identificator for UMP memory buffers.
  41  */
  42 typedef unsigned int ump_secure_id;
  43
  44
  45 /**
  46  * Value to indicate an invalid UMP memory handle.
  47  */
  48 #define UMP_DD_HANDLE_INVALID ((ump_dd_handle)0)
  49
  50
  51 /**
  52  * Value to indicate an invalid secure Id.
  53  */
  54 #define UMP_INVALID_SECURE_ID ((ump_secure_id)-1)
  55
  56
  57 /**
  58  * UMP error codes for kernel space.
  59  */
  60 typedef enum
  61 {
  62         UMP_DD_SUCCESS, /**< indicates success */
  63         UMP_DD_INVALID, /**< indicates failure */
  64 } ump_dd_status_code;
  65
  66
  67 /**
  68  * Struct used to describe a physical block used by UMP memory
  69  */
  70 typedef struct ump_dd_physical_block
  71 {
  72         unsigned long addr; /**< The physical address of the block */
  73         unsigned long size; /**< The length of the block, typically page aligned */
  74 } ump_dd_physical_block;
  75
  76
  77 /**
  78  * Retrieves the secure ID for the specified UMP memory.
  79  *
  80  * This identificator is unique across the entire system, and uniquely identifies
  81  * the specified UMP memory. This identificator can later be used through the
  82  * @ref ump_dd_handle_create_from_secure_id "ump_dd_handle_create_from_secure_id" or
  83  * @ref ump_handle_create_from_secure_id "ump_handle_create_from_secure_id"
  84  * functions in order to access this UMP memory, for instance from another process.
  85  *
  86  * @note There is a user space equivalent function called @ref ump_secure_id_get "ump_secure_id_get"
  87  *
  88  * @see ump_dd_handle_create_from_secure_id
  89  * @see ump_handle_create_from_secure_id
  90  * @see ump_secure_id_get
  91  *
  92  * @param mem Handle to UMP memory.
  93  *
  94  * @return Returns the secure ID for the specified UMP memory.
  95  */
  96 UMP_KERNEL_API_EXPORT ump_secure_id ump_dd_secure_id_get(ump_dd_handle mem);
  97
  98
  99 /**
 100  * Retrieves a handle to allocated UMP memory.
 101  *
 102  * The usage of UMP memory is reference counted, so this will increment the reference
 103  * count by one for the specified UMP memory.
 104  * Use @ref ump_dd_reference_release "ump_dd_reference_release" when there is no longer any
 105  * use for the retrieved handle.
 106  *
 107  * @note There is a user space equivalent function called @ref ump_handle_create_from_secure_id "ump_handle_create_from_secure_id"
 108  *
 109  * @see ump_dd_reference_release
 110  * @see ump_handle_create_from_secure_id
 111  *
 112  * @param secure_id The secure ID of the UMP memory to open, that can be retrieved using the @ref ump_secure_id_get "ump_secure_id_get " function.
 113  *
 114  * @return UMP_INVALID_MEMORY_HANDLE indicates failure, otherwise a valid handle is returned.
 115  */
 116 UMP_KERNEL_API_EXPORT ump_dd_handle ump_dd_handle_create_from_secure_id(ump_secure_id secure_id);
 117
 118
 119 /**
 120  * Retrieves the number of physical blocks used by the specified UMP memory.
 121  *
 122  * This function retrieves the number of @ref ump_dd_physical_block "ump_dd_physical_block" structs needed
 123  * to describe the physical memory layout of the given UMP memory. This can later be used when calling
 124  * the functions @ref ump_dd_phys_blocks_get "ump_dd_phys_blocks_get" and
 125  * @ref ump_dd_phys_block_get "ump_dd_phys_block_get".
 126  *
 127  * @see ump_dd_phys_blocks_get
 128  * @see ump_dd_phys_block_get
 129  *
 130  * @param mem Handle to UMP memory.
 131  *
 132  * @return The number of ump_dd_physical_block structs required to describe the physical memory layout of the specified UMP memory.
 133  */
 134 UMP_KERNEL_API_EXPORT unsigned long ump_dd_phys_block_count_get(ump_dd_handle mem);
 135
 136
 137 /**
 138  * Retrieves all physical memory block information for specified UMP memory.
 139  *
 140  * This function can be used by other device drivers in order to create MMU tables.
 141  *
 142  * @note This function will fail if the num_blocks parameter is either to large or to small.
 143  *
 144  * @see ump_dd_phys_block_get
 145  *
 146  * @param mem Handle to UMP memory.
 147  * @param blocks An array of @ref ump_dd_physical_block "ump_dd_physical_block" structs that will receive the physical description.
 148  * @param num_blocks The number of blocks to return in the blocks array. Use the function
 149  *                   @ref ump_dd_phys_block_count_get "ump_dd_phys_block_count_get" first to determine the number of blocks required.
 150  *
 151  * @return UMP_DD_SUCCESS indicates success, UMP_DD_INVALID indicates failure.
 152  */
 153 UMP_KERNEL_API_EXPORT ump_dd_status_code ump_dd_phys_blocks_get(ump_dd_handle mem, ump_dd_physical_block * blocks, unsigned long num_blocks);
 154
 155
 156 /**
 157  * Retrieves the physical memory block information for specified block for the specified UMP memory.
 158  *
 159  * This function can be used by other device drivers in order to create MMU tables.
 160  *
 161  * @note This function will return UMP_DD_INVALID if the specified index is out of range.
 162  *
 163  * @see ump_dd_phys_blocks_get
 164  *
 165  * @param mem Handle to UMP memory.
 166  * @param index Which physical info block to retrieve.
 167  * @param block Pointer to a @ref ump_dd_physical_block "ump_dd_physical_block" struct which will receive the requested information.
 168  *
 169  * @return UMP_DD_SUCCESS indicates success, UMP_DD_INVALID indicates failure.
 170  */
 171 UMP_KERNEL_API_EXPORT ump_dd_status_code ump_dd_phys_block_get(ump_dd_handle mem, unsigned long index, ump_dd_physical_block * block);
 172
 173
 174 /**
 175  * Retrieves the actual size of the specified UMP memory.
 176  *
 177  * The size is reported in bytes, and is typically page aligned.
 178  *
 179  * @note There is a user space equivalent function called @ref ump_size_get "ump_size_get"
 180  *
 181  * @see ump_size_get
 182  *
 183  * @param mem Handle to UMP memory.
 184  *
 185  * @return Returns the allocated size of the specified UMP memory, in bytes.
 186  */
 187 UMP_KERNEL_API_EXPORT unsigned long ump_dd_size_get(ump_dd_handle mem);
 188
 189
 190 /**
 191  * Adds an extra reference to the specified UMP memory.
 192  *
 193  * This function adds an extra reference to the specified UMP memory. This function should
 194  * be used every time a UMP memory handle is duplicated, that is, assigned to another ump_dd_handle
 195  * variable. The function @ref ump_dd_reference_release "ump_dd_reference_release" must then be used
 196  * to release each copy of the UMP memory handle.
 197  *
 198  * @note You are not required to call @ref ump_dd_reference_add "ump_dd_reference_add"
 199  * for UMP handles returned from
 200  * @ref ump_dd_handle_create_from_secure_id "ump_dd_handle_create_from_secure_id",
 201  * because these handles are already reference counted by this function.
 202  *
 203  * @note There is a user space equivalent function called @ref ump_reference_add "ump_reference_add"
 204  *
 205  * @see ump_reference_add
 206  *
 207  * @param mem Handle to UMP memory.
 208  */
 209 UMP_KERNEL_API_EXPORT void ump_dd_reference_add(ump_dd_handle mem);
 210
 211
 212 /**
 213  * Releases a reference from the specified UMP memory.
 214  *
 215  * This function should be called once for every reference to the UMP memory handle.
 216  * When the last reference is released, all resources associated with this UMP memory
 217  * handle are freed.
 218  *
 219  * @note There is a user space equivalent function called @ref ump_reference_release "ump_reference_release"
 220  *
 221  * @see ump_reference_release
 222  *
 223  * @param mem Handle to UMP memory.
 224  */
 225 UMP_KERNEL_API_EXPORT void ump_dd_reference_release(ump_dd_handle mem);
 226
 227
 228 #ifdef __cplusplus
 229 }
 230 #endif
 231
 232
 233 /** @} */ /* end group ump_kernel_space_api */
 234
 235
 236 #endif  /* __UMP_KERNEL_INTERFACE_H__ */