diff options
Diffstat (limited to 'include')
| -rwxr-xr-x | include/linux/dma-buf-test-exporter.h | 78 | ||||
| -rwxr-xr-x | include/linux/kds.h | 173 | ||||
| -rwxr-xr-x | include/linux/ump-common.h | 252 | ||||
| -rwxr-xr-x | include/linux/ump-import.h | 99 | ||||
| -rwxr-xr-x | include/linux/ump-ioctl.h | 152 | ||||
| -rwxr-xr-x | include/linux/ump.h | 481 |
6 files changed, 1235 insertions, 0 deletions
diff --git a/include/linux/dma-buf-test-exporter.h b/include/linux/dma-buf-test-exporter.h new file mode 100755 index 000000000000..98984ba6032f --- /dev/null +++ b/include/linux/dma-buf-test-exporter.h @@ -0,0 +1,78 @@ +/* + * + * (C) COPYRIGHT 2012-2013 ARM Limited. All rights reserved. + * + * This program is free software and is provided to you under the terms of the + * GNU General Public License version 2 as published by the Free Software + * Foundation, and any use by you of this program is subject to the terms + * of such GNU licence. + * + * A copy of the licence is included with the program, and can also be obtained + * from Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, + * Boston, MA 02110-1301, USA. + * + */ + + + + +#ifndef _LINUX_DMA_BUF_TEST_EXPORTER_H_ +#define _LINUX_DMA_BUF_TEST_EXPORTER_H_ + +#include <linux/types.h> +#include <asm/ioctl.h> + +#define DMA_BUF_TE_VER_MAJOR 1 +#define DMA_BUF_TE_VER_MINOR 0 +#define DMA_BUF_TE_ENQ 0x642d7465 +#define DMA_BUF_TE_ACK 0x68692100 + +struct dma_buf_te_ioctl_version +{ + int op; /**< Must be set to DMA_BUF_TE_ENQ by client, driver will set it to DMA_BUF_TE_ACK */ + int major; /**< Major version */ + int minor; /**< Minor version */ +}; + +struct dma_buf_te_ioctl_alloc +{ + __u64 size; /* size of buffer to allocate, in pages */ +}; + +struct dma_buf_te_ioctl_status +{ + /* in */ + int fd; /* the dma_buf to query, only dma_buf objects exported by this driver is supported */ + /* out */ + int attached_devices; /* number of devices attached (active 'dma_buf_attach's) */ + int device_mappings; /* number of device mappings (active 'dma_buf_map_attachment's) */ + int cpu_mappings; /* number of cpu mappings (active 'mmap's) */ +}; + +struct dma_buf_te_ioctl_set_failing +{ + /* in */ + int fd; /* the dma_buf to set failure mode for, only dma_buf objects exported by this driver is supported */ + + /* zero = no fail injection, non-zero = inject failure */ + int fail_attach; + int fail_map; + int fail_mmap; +}; + +struct dma_buf_te_ioctl_fill +{ + int fd; + unsigned int value; +}; + +#define DMA_BUF_TE_IOCTL_BASE 'E' +/* Below all returning 0 if successful or -errcode except DMA_BUF_TE_ALLOC which will return fd or -errcode */ +#define DMA_BUF_TE_VERSION _IOR(DMA_BUF_TE_IOCTL_BASE, 0x00, struct dma_buf_te_ioctl_version) +#define DMA_BUF_TE_ALLOC _IOR(DMA_BUF_TE_IOCTL_BASE, 0x01, struct dma_buf_te_ioctl_alloc) +#define DMA_BUF_TE_QUERY _IOR(DMA_BUF_TE_IOCTL_BASE, 0x02, struct dma_buf_te_ioctl_status) +#define DMA_BUF_TE_SET_FAILING _IOW(DMA_BUF_TE_IOCTL_BASE, 0x03, struct dma_buf_te_ioctl_set_failing) +#define DMA_BUF_TE_ALLOC_CONT _IOR(DMA_BUF_TE_IOCTL_BASE, 0x04, struct dma_buf_te_ioctl_alloc) +#define DMA_BUF_TE_FILL _IOR(DMA_BUF_TE_IOCTL_BASE, 0x05, struct dma_buf_te_ioctl_fill) + +#endif /* _LINUX_DMA_BUF_TEST_EXPORTER_H_ */ diff --git a/include/linux/kds.h b/include/linux/kds.h new file mode 100755 index 000000000000..1346edae04cc --- /dev/null +++ b/include/linux/kds.h @@ -0,0 +1,173 @@ +/* + * + * (C) COPYRIGHT 2012-2013 ARM Limited. All rights reserved. + * + * This program is free software and is provided to you under the terms of the + * GNU General Public License version 2 as published by the Free Software + * Foundation, and any use by you of this program is subject to the terms + * of such GNU licence. + * + * A copy of the licence is included with the program, and can also be obtained + * from Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, + * Boston, MA 02110-1301, USA. + * + */ + + + + + +#ifndef _KDS_H_ +#define _KDS_H_ + +#include <linux/list.h> +#include <linux/workqueue.h> + +#define KDS_WAIT_BLOCKING (ULONG_MAX) + +struct kds_resource_set; + +typedef void (*kds_callback_fn) (void *callback_parameter, void *callback_extra_parameter); + +struct kds_callback +{ + kds_callback_fn user_cb; /* real cb */ + int direct; /* do direct or queued call? */ + struct workqueue_struct *wq; +}; + +struct kds_link +{ + struct kds_resource_set *parent; + struct list_head link; + unsigned long state; +}; + +struct kds_resource +{ + struct kds_link waiters; +}; + +/* callback API */ + +/* Initialize a callback object. + * + * Typically created per context or per hw resource. + * + * Callbacks can be performed directly if no nested locking can + * happen in the client. + * + * Nested locking can occur when a lock is held during the kds_async_waitall or + * kds_resource_set_release call. If the callback needs to take the same lock + * nested locking will happen. + * + * If nested locking could happen non-direct callbacks can be requested. + * Callbacks will then be called asynchronous to the triggering call. + */ +int kds_callback_init(struct kds_callback *cb, int direct, kds_callback_fn user_cb); + +/* Terminate the use of a callback object. + * + * If the callback object was set up as non-direct + * any pending callbacks will be flushed first. + * Note that to avoid a deadlock the lock callbacks needs + * can't be held when a callback object is terminated. + */ +void kds_callback_term(struct kds_callback *cb); + + +/* resource object API */ + +/* initialize a resource handle for a shared resource */ +void kds_resource_init(struct kds_resource * const resource); + +/* + * Will return 0 on success. + * If the resource is being used or waited -EBUSY is returned. + * The caller should NOT try to terminate a resource that could still have clients. + * After the function returns the resource is no longer known by kds. + */ +int kds_resource_term(struct kds_resource *resource); + +/* Asynchronous wait for a set of resources. + * Callback will be called when all resources are available. + * If all the resources was available the callback will be called before kds_async_waitall returns. + * So one must not hold any locks the callback code-flow can take when calling kds_async_waitall. + * Caller considered to own/use the resources until \a kds_rset_release is called. + * exclusive_access_bitmap is a bitmap where a high bit means exclusive access while a low bit means shared access. + * Use the Linux __set_bit API, where the index of the buffer to control is used as the bit index. + * + * Standard Linux error return value. + */ +int kds_async_waitall( + struct kds_resource_set ** const pprset, + struct kds_callback *cb, + void *callback_parameter, + void *callback_extra_parameter, + int number_resources, + unsigned long *exclusive_access_bitmap, + struct kds_resource **resource_list); + +/* Synchronous wait for a set of resources. + * Function will return when one of these have happened: + * - all resources have been obtained + * - timeout lapsed while waiting + * - a signal was received while waiting + * + * To wait without a timeout, specify KDS_WAIT_BLOCKING for \a jifies_timeout, otherwise + * the timeout in jiffies. A zero timeout attempts to obtain all resources and returns + * immediately with a timeout if all resources could not be obtained. + * + * Caller considered to own/use the resources when the function returns. + * Caller must release the resources using \a kds_rset_release. + * + * Calling this function while holding already locked resources or other locking primitives is dangerous. + * One must if this is needed decide on a lock order of the resources and/or the other locking primitives + * and always take the resources/locking primitives in the specific order. + * + * Use the ERR_PTR framework to decode the return value. + * NULL = time out + * If IS_ERR then PTR_ERR gives: + * ERESTARTSYS = signal received, retry call after signal + * all other values = internal error, lock failed + * Other values = successful wait, now the owner, must call kds_resource_set_release + */ +struct kds_resource_set *kds_waitall( + int number_resources, + unsigned long *exclusive_access_bitmap, + struct kds_resource **resource_list, + unsigned long jifies_timeout); + +/* Release resources after use. + * Caller must handle that other async callbacks will trigger, + * so must avoid holding any locks a callback will take. + * + * The function takes a pointer to your poiner to handle a race + * between a cancelation and a completion. + * + * If the caller can't guarantee that a race can't occur then + * the passed in pointer must be the same in both call paths + * to allow kds to manage the potential race. + */ +void kds_resource_set_release(struct kds_resource_set **pprset); + +/* Release resources after use and wait callbacks to complete. + * Caller must handle that other async callbacks will trigger, + * so must avoid holding any locks a callback will take. + * + * The function takes a pointer to your poiner to handle a race + * between a cancelation and a completion. + * + * If the caller can't guarantee that a race can't occur then + * the passed in pointer must be the same in both call paths + * to allow kds to manage the potential race. + * + * This should be used to cancel waits which are pending on a kds + * resource. + * + * It is a bug to call this from atomic contexts and from within + * a kds callback that now owns the kds_rseource. + */ + +void kds_resource_set_release_sync(struct kds_resource_set **pprset); +#endif /* _KDS_H_ */ diff --git a/include/linux/ump-common.h b/include/linux/ump-common.h new file mode 100755 index 000000000000..0015bda6ffc7 --- /dev/null +++ b/include/linux/ump-common.h @@ -0,0 +1,252 @@ +/* + * + * (C) COPYRIGHT 2010-2013 ARM Limited. All rights reserved. + * + * This program is free software and is provided to you under the terms of the + * GNU General Public License version 2 as published by the Free Software + * Foundation, and any use by you of this program is subject to the terms + * of such GNU licence. + * + * A copy of the licence is included with the program, and can also be obtained + * from Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, + * Boston, MA 02110-1301, USA. + * + */ + + + + + +/** + * @file ump-common.h + * + * This file contains some common enum values used both in both the user and kernel space side of UMP. + */ + +#ifndef _UMP_COMMON_H_ +#define _UMP_COMMON_H_ + +#ifdef __cplusplus +extern "C" +{ +#endif + +#ifdef __KERNEL__ +#include <linux/types.h> +#else +#include <stdint.h> +#endif + +#define UMP_UINT32_MAX (4294967295U) +#define UMP_UINT64_MAX (18446744073709551615ULL) + +#ifdef __GNUC__ + #define CHECK_RESULT __attribute__((__warn_unused_result__)) + #define INLINE __inline__ +#else + #define CHECK_RESULT + #define INLINE __inline +#endif + +#ifndef STATIC + #define STATIC static +#endif + +/** + * Values to identify major and minor version of UMP + */ +#define UMP_VERSION_MAJOR 2 +#define UMP_VERSION_MINOR 0 + +/** + * Typedef for a secure ID, a system wide identifier for UMP memory buffers. + */ +typedef int32_t ump_secure_id; + +/** + * Value to indicate an invalid secure Id. + */ +#define UMP_INVALID_SECURE_ID ((ump_secure_id)0) + +/** + * UMP error codes. + */ +typedef enum +{ + UMP_OK = 0, /**< indicates success */ + UMP_ERROR = 1 /**< indicates failure */ +} ump_result; + +/** + * Allocation flag bits. + * + * ump_allocate accepts zero or more flags to specify the type of memory to allocate and how to expose it to devices. + * + * For each supported device there are 4 flags to control access permissions and give usage characteristic hints to optimize the allocation/mapping. + * They are; + * @li @a UMP_PROT_<device>_RD read permission + * @li @a UMP_PROT_<device>_WR write permission + * @li @a UMP_HINT_<device>_RD read often + * @li @a UMP_HINT_<device>_WR written often + * + * 5 devices are currently supported, with a device being the CPU itself. + * The other 4 devices will be mapped to real devices per SoC design. + * They are just named W,X,Y,Z by UMP as it has no knowledge of their real names/identifiers. + * As an example device W could be a camera device while device Z could be an ARM GPU device, leaving X and Y unused. + * + * 2 additional flags control the allocation; + * @li @a UMP_CONSTRAINT_PHYSICALLY_LINEAR the allocation must be physical linear. Typical for devices without an MMU and no IOMMU to help it. + * @li @a UMP_PROT_SHAREABLE the allocation can be shared with other processes on the system. Without this flag the returned allocation won't be resolvable in other processes. + * + * All UMP allocation are growable unless they're @a UMP_PROT_SHAREABLE. + * The hint bits should be used to indicate the access pattern so the driver can select the most optimal memory type and cache settings based on the what the system supports. + */ +typedef enum +{ + /* Generic helpers */ + UMP_PROT_DEVICE_RD = (1u << 0), + UMP_PROT_DEVICE_WR = (1u << 1), + UMP_HINT_DEVICE_RD = (1u << 2), + UMP_HINT_DEVICE_WR = (1u << 3), + UMP_DEVICE_MASK = 0xF, + UMP_DEVICE_CPU_SHIFT = 0, + UMP_DEVICE_W_SHIFT = 4, + UMP_DEVICE_X_SHIFT = 8, + UMP_DEVICE_Y_SHIFT = 12, + UMP_DEVICE_Z_SHIFT = 16, + + /* CPU protection and hints. */ + UMP_PROT_CPU_RD = (1u << 0), + UMP_PROT_CPU_WR = (1u << 1), + UMP_HINT_CPU_RD = (1u << 2), + UMP_HINT_CPU_WR = (1u << 3), + + /* device W */ + UMP_PROT_W_RD = (1u << 4), + UMP_PROT_W_WR = (1u << 5), + UMP_HINT_W_RD = (1u << 6), + UMP_HINT_W_WR = (1u << 7), + + /* device X */ + UMP_PROT_X_RD = (1u << 8), + UMP_PROT_X_WR = (1u << 9), + UMP_HINT_X_RD = (1u << 10), + UMP_HINT_X_WR = (1u << 11), + + /* device Y */ + UMP_PROT_Y_RD = (1u << 12), + UMP_PROT_Y_WR = (1u << 13), + UMP_HINT_Y_RD = (1u << 14), + UMP_HINT_Y_WR = (1u << 15), + + /* device Z */ + UMP_PROT_Z_RD = (1u << 16), + UMP_PROT_Z_WR = (1u << 17), + UMP_HINT_Z_RD = (1u << 18), + UMP_HINT_Z_WR = (1u << 19), + + /* 20-26 reserved for future use */ + UMPP_ALLOCBITS_UNUSED = (0x7Fu << 20), + /** Allocations marked as @ UMP_CONSTRAINT_UNCACHED won't be mapped as cached by the cpu */ + UMP_CONSTRAINT_UNCACHED = (1u << 27), + /** Require 32-bit physically addressable memory */ + UMP_CONSTRAINT_32BIT_ADDRESSABLE = (1u << 28), + /** For devices without an MMU and with no IOMMU assistance. */ + UMP_CONSTRAINT_PHYSICALLY_LINEAR = (1u << 29), + /** Shareable must be set to allow the allocation to be used by other processes, the default is non-shared */ + UMP_PROT_SHAREABLE = (1u << 30) + /* (1u << 31) should not be used to ensure compiler portability */ +} ump_allocation_bits; + +/** + * ump_allocation_bits combination argument type. + * + * Type used to pass zero or more bits from the @ref ump_allocation_bits enum + */ +typedef uint32_t ump_alloc_flags; + + +/** + * Default allocation flags for UMP v1 compatible allocations. + */ +#define UMP_V1_API_DEFAULT_ALLOCATION_FLAGS UMP_PROT_CPU_RD | UMP_PROT_CPU_WR | \ + UMP_PROT_W_RD | UMP_PROT_W_WR | \ + UMP_PROT_X_RD | UMP_PROT_X_WR | \ + UMP_PROT_Y_RD | UMP_PROT_Y_WR | \ + UMP_PROT_Z_RD | UMP_PROT_Z_WR | \ + UMP_PROT_SHAREABLE | \ + UMP_CONSTRAINT_32BIT_ADDRESSABLE + +/** + * CPU cache sync operations. + * + * Cache synchronization operations to pass to @ref ump_cpu_msync_now + */ +enum +{ + /** + * Cleans any dirty cache lines to main memory, but the data will still be available in the cache. + * After a clean the contents of memory is considered to be "owned" by the device. + * */ + UMP_MSYNC_CLEAN = 1, + + /** Cleans any dirty cache lines to main memory and Ejects all lines from the cache. + * After an clean&invalidate the contents of memory is considered to be "owned" by the CPU. + * Any subsequent access will fetch data from main memory. + * + * @note Due to CPUs doing speculative prefetching a UMP_MSYNC_CLEAN_AND_INVALIDATE must be done before and after interacting with hardware. + * */ + UMP_MSYNC_CLEAN_AND_INVALIDATE + +}; + +typedef uint32_t ump_cpu_msync_op; + +/** + * Memory import types supported. + * If new import types are added they will appear here. + * They must be added before UMPP_EXTERNAL_MEM_COUNT and + * must be assigned an explicit sequantial number. + * + * @li UMP_EXTERNAL_MEM_TYPE_ION - Import an ION allocation + * Takes a int* (pointer to a file descriptor) + * Another ION reference is taken which is released on the final ump_release + */ +enum ump_external_memory_type +{ + UMPP_EXTERNAL_MEM_TYPE_UNUSED = 0, /* reserve type 0 */ + UMP_EXTERNAL_MEM_TYPE_ION = 1, + UMPP_EXTERNAL_MEM_COUNT +}; + +/** @name UMP v1 API + * + *@{ + */ + +/** + * Allocation constraints. + * + * Allocation flags to pass @ref ump_ref_drv_allocate + * + * UMP v1 API only. + */ +typedef enum +{ + /** the allocation is mapped as noncached. */ + UMP_REF_DRV_CONSTRAINT_NONE = 0, + /** not supported. */ + UMP_REF_DRV_CONSTRAINT_PHYSICALLY_LINEAR = 1, + /** the allocation is mapped as cached by the cpu. */ + UMP_REF_DRV_CONSTRAINT_USE_CACHE = 4 +} ump_alloc_constraints; + +/* @} */ + + +#ifdef __cplusplus +} +#endif + + +#endif /* _UMP_COMMON_H_ */ diff --git a/include/linux/ump-import.h b/include/linux/ump-import.h new file mode 100755 index 000000000000..89ce727d4f87 --- /dev/null +++ b/include/linux/ump-import.h @@ -0,0 +1,99 @@ +/* + * + * (C) COPYRIGHT 2011-2013 ARM Limited. All rights reserved. + * + * This program is free software and is provided to you under the terms of the + * GNU General Public License version 2 as published by the Free Software + * Foundation, and any use by you of this program is subject to the terms + * of such GNU licence. + * + * A copy of the licence is included with the program, and can also be obtained + * from Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, + * Boston, MA 02110-1301, USA. + * + */ + + + + + +#ifndef _UMP_IMPORT_H_ +#define _UMP_IMPORT_H_ + +#include <linux/ump.h> +#include <linux/module.h> + +/** + * UMP import module info. + * Contains information about the Linux module providing the import module, + * used to block unloading of the Linux module while imported memory exists. + * Lists the functions implementing the UMP import functions. + */ +struct ump_import_handler +{ + /** + * Linux module of the import handler + */ + struct module * linux_module; + + /** + * UMP session usage begin. + * + * Called when a UMP session first is bound to the handler. + * Typically used to set up any import module specific per-session data. + * The function returns a pointer to this data in the output pointer custom_session_data + * which will be passed to \a session_end and \a import. + * + * Note: custom_session_data must be set to non-NULL if successful. + * If no pointer is needed set it a magic value to validate instead. + * + * @param[out] custom_session_data Pointer to a generic pointer where any data can be stored + * @return 0 on success, error code if the session could not be initiated. + */ + int (*session_begin)(void ** custom_session_data); + + /** + * UMP session usage end. + * + * Called when a UMP session is no longer using the handler. + * Only called if @a session_begin returned OK. + * + * @param[in] custom_session_data The value set by the session_begin handler + */ + void (*session_end)(void * custom_session_data); + + /** + * Import request. + * + * Called when a client has asked to import a resource of the type the import module was installed for. + * Only called if @a session_begin returned OK. + * + * The requested flags must be verified to be valid to apply to the imported memory. + * If not valid return UMP_DD_INVALID_MEMORY_HANDLE. + * If the flags are found to be valid call \a ump_dd_create_from_phys_blocks_64 to create a handle. + * + * @param[in] custom_session_data The value set by the session_begin handler + * @param[in] phandle Pointer to the handle to import + * @param flags The requested UMPv2 flags to assign to the imported handle + * @return UMP_DD_INVALID_MEMORY_HANDLE if the import failed, a valid ump handle on success + */ + ump_dd_handle (*import)(void * custom_session_data, void * phandle, ump_alloc_flags flags); +}; + +/** + * Import module registration. + * Registers a ump_import_handler structure for a memory type. + * @param type Type of the memory to register a handler for + * @param[in] handler Handler strcture to install + * @return 0 on success, a Linux error code on failure + */ +int ump_import_module_register(enum ump_external_memory_type type, struct ump_import_handler * handler); + +/** + * Import module deregistration. + * Uninstalls the handler for the given memory type. + * @param type Type of the memory to unregister the handler for + */ +void ump_import_module_unregister(enum ump_external_memory_type type); + +#endif /* _UMP_IMPORT_H_ */ diff --git a/include/linux/ump-ioctl.h b/include/linux/ump-ioctl.h new file mode 100755 index 000000000000..451403e7c1ee --- /dev/null +++ b/include/linux/ump-ioctl.h @@ -0,0 +1,152 @@ +/* + * + * (C) COPYRIGHT 2008-2013 ARM Limited. All rights reserved. + * + * This program is free software and is provided to you under the terms of the + * GNU General Public License version 2 as published by the Free Software + * Foundation, and any use by you of this program is subject to the terms + * of such GNU licence. + * + * A copy of the licence is included with the program, and can also be obtained + * from Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, + * Boston, MA 02110-1301, USA. + * + */ + + + + + +#ifndef _UMP_IOCTL_H_ +#define _UMP_IOCTL_H + +#include <linux/ump-common.h> + +/* + * The order and size of the members of these have been chosen so the structures look the same in 32-bit and 64-bit builds. + * If any changes are done build the ump_struct_size_checker test for 32-bit and 64-bit targets. Both must compile successfully to commit. + */ + +/** 32/64-bit neutral way to represent pointers */ +typedef union ump_pointer +{ + void * value; /**< client should store their pointers here */ + uint32_t compat_value; /**< 64-bit kernels should fetch value here when handling 32-bit clients */ + uint64_t sizer; /**< Force 64-bit storage for all clients regardless */ +} ump_pointer; + +/** + * UMP allocation request. + * Used when performing ump_allocate + */ +typedef struct ump_k_allocate +{ + uint64_t size; /**< [in] Size in bytes to allocate */ + ump_secure_id secure_id; /**< [out] Secure ID of allocation on success */ + ump_alloc_flags alloc_flags; /**< [in] Flags to use when allocating */ +} ump_k_allocate; + +/** + * UMP size query request. + * Used when performing ump_size_get + */ +typedef struct ump_k_sizequery +{ + uint64_t size; /**< [out] Size of allocation */ + ump_secure_id secure_id; /**< [in] ID of allocation to query the size of */ + uint32_t padding; /* don't remove */ +} ump_k_sizequery; + +/** + * UMP cache synchronization request. + * Used when performing ump_cpu_msync_now + */ +typedef struct ump_k_msync +{ + ump_pointer mapped_ptr; /**< [in] CPU VA to perform cache operation on */ + ump_secure_id secure_id; /**< [in] ID of allocation to perform cache operation on */ + ump_cpu_msync_op cache_operation; /**< [in] Cache operation to perform */ + uint64_t size; /**< [in] Size in bytes of the range to synchronize */ +} ump_k_msync; + +/** + * UMP memory retain request. + * Used when performing ump_retain + */ +typedef struct ump_k_retain +{ + ump_secure_id secure_id; /**< [in] ID of allocation to retain a reference to */ + uint32_t padding; /* don't remove */ +} ump_k_retain; + +/** + * UMP memory release request. + * Used when performing ump_release + */ +typedef struct ump_k_release +{ + ump_secure_id secure_id; /**< [in] ID of allocation to release a reference to */ + uint32_t padding; /* don't remove */ +} ump_k_release; + +typedef struct ump_k_import +{ + ump_pointer phandle; /**< [in] Pointer to handle to import */ + uint32_t type; /**< [in] Type of handle to import */ + ump_alloc_flags alloc_flags; /**< [in] Flags to assign to the imported memory */ + ump_secure_id secure_id; /**< [out] UMP ID representing the imported memory */ + uint32_t padding; /* don't remove */ +} ump_k_import; + +/** + * UMP allocation flags request. + * Used when performing umpp_get_allocation_flags + * + * used only by v1 API + */ +typedef struct ump_k_allocation_flags +{ + ump_secure_id secure_id; /**< [in] Secure ID of allocation on success */ + ump_alloc_flags alloc_flags; /**< [out] Flags to use when allocating */ +} ump_k_allocation_flags; + +#define UMP_CALL_MAX_SIZE 512 +/* + * Ioctl definitions + */ + +/* Use '~' as magic number */ + +#define UMP_IOC_MAGIC '~' + +#define UMP_FUNC_ALLOCATE _IOWR(UMP_IOC_MAGIC, 1, ump_k_allocate) +#define UMP_FUNC_SIZEQUERY _IOWR(UMP_IOC_MAGIC, 2, ump_k_sizequery) +#define UMP_FUNC_MSYNC _IOWR(UMP_IOC_MAGIC, 3, ump_k_msync) +#define UMP_FUNC_RETAIN _IOW(UMP_IOC_MAGIC, 4, ump_k_retain) +#define UMP_FUNC_RELEASE _IOW(UMP_IOC_MAGIC, 5, ump_k_release) +#define UMP_FUNC_ALLOCATION_FLAGS_GET _IOWR(UMP_IOC_MAGIC, 6, ump_k_allocation_flags) +#define UMP_FUNC_IMPORT _IOWR(UMP_IOC_MAGIC, 7, ump_k_import) + +/*max ioctl sequential number*/ +#define UMP_IOC_MAXNR 7 + +/* 15 bits for the UMP ID (allowing 32768 IDs) */ +#define UMP_LINUX_ID_BITS 15 +#define UMP_LINUX_ID_MASK ((1ULL << UMP_LINUX_ID_BITS) - 1ULL) + +/* 64-bit (really 52 bits) encoding: 15 bits for the ID, 37 bits for the offset */ +#define UMP_LINUX_OFFSET_BITS_64 37 +#define UMP_LINUX_OFFSET_MASK_64 ((1ULL << UMP_LINUX_OFFSET_BITS_64)-1) +/* 32-bit encoding: 15 bits for the ID, 17 bits for the offset */ +#define UMP_LINUX_OFFSET_BITS_32 17 +#define UMP_LINUX_OFFSET_MASK_32 ((1ULL << UMP_LINUX_OFFSET_BITS_32)-1) + +#if __SIZEOF_LONG__ == 8 +#define UMP_LINUX_OFFSET_BITS UMP_LINUX_OFFSET_BITS_64 +#define UMP_LINUX_OFFSET_MASK UMP_LINUX_OFFSET_MASK_64 +#else +#define UMP_LINUX_OFFSET_BITS UMP_LINUX_OFFSET_BITS_32 +#define UMP_LINUX_OFFSET_MASK UMP_LINUX_OFFSET_MASK_32 +#endif + +#endif /* _UMP_IOCTL_H_ */ diff --git a/include/linux/ump.h b/include/linux/ump.h new file mode 100755 index 000000000000..16f9c39f69c1 --- /dev/null +++ b/include/linux/ump.h @@ -0,0 +1,481 @@ +/* + * + * (C) COPYRIGHT 2008-2013, 2015 ARM Limited. All rights reserved. + * + * This program is free software and is provided to you under the terms of the + * GNU General Public License version 2 as published by the Free Software + * Foundation, and any use by you of this program is subject to the terms + * of such GNU licence. + * + * A copy of the licence is included with the program, and can also be obtained + * from Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, + * Boston, MA 02110-1301, USA. + * + */ + + + + + +/** + * @file + * + * This file contains the kernel space part of the UMP API. + * + */ + +#ifndef _UMP_KERNEL_INTERFACE_H_ +#define _UMP_KERNEL_INTERFACE_H_ + +/** + * @addtogroup ump_api + * @{ + */ + +/** @defgroup ump_kernel_space_api UMP Kernel Space API + * @{ */ + +/** + * External representation of a UMP handle in kernel space. + */ +typedef void * ump_dd_handle; + +#ifdef CONFIG_KDS +#include <linux/kds.h> +#endif + +#include <linux/ump-common.h> + +#define UMP_KERNEL_API_EXPORT + +#if defined(__KERNEL__) +#include <linux/ump-import.h> +#else +#include <ump/src/library/common/ump_user.h> +#endif + +#ifdef __cplusplus +extern "C" +{ +#endif + +/** + * Value to indicate an invalid UMP memory handle. + */ +#define UMP_DD_INVALID_MEMORY_HANDLE ((ump_dd_handle)0) + +/** + * Struct used to describe a physical block used by UMP memory + */ +typedef struct ump_dd_physical_block_64 +{ + uint64_t addr; /**< The physical address of the block */ + uint64_t size; /**< The length of the block, in bytes, typically page aligned */ +} ump_dd_physical_block_64; + +/** + * Security filter hook. + * + * Each allocation can have a security filter attached to it.@n + * The hook receives + * @li the secure ID + * @li a handle to the allocation + * @li the callback_data argument provided to @ref ump_dd_allocate_64 or @ref ump_dd_create_from_phys_blocks_64 + * + * The hook must return @a true to indicate that access to the handle is allowed or @n + * @a false to state that no access is permitted.@n + * This hook is guaranteed to be called in the context of the requesting process/address space. + * + * The arguments provided to the hook are; + * @li the secure ID + * @li handle to the allocation + * @li the callback_data set when registering the hook + * + * Return value; + * @li @a true to permit access + * @li @a false to deny access + */ +typedef bool (*ump_dd_security_filter)(ump_secure_id, ump_dd_handle, void *); + +/** + * Final release notify hook. + * + * Allocations can have a hook attached to them which is called when the last reference to the allocation is released. + * No reference count manipulation is allowed on the provided handle, just property querying (ID get, size get, phys block get). + * This is similar to finalizers in OO languages. + * + * The arguments provided to the hook are; + * * handle to the allocation + * * the callback_data set when registering the hook + */ +typedef void (*ump_dd_final_release_callback)(const ump_dd_handle, void *); + +/** + * Allocate a buffer. + * The lifetime of the allocation is controlled by a reference count. + * The reference count of the returned buffer is set to 1. + * The memory will be freed once the reference count reaches 0. + * Use @ref ump_dd_retain and @ref ump_dd_release to control the reference count. + * @param size Number of bytes to allocate. Will be padded up to a multiple of the page size. + * @param flags Bit-wise OR of zero or more of the allocation flag bits. + * @param[in] filter_func Pointer to a function which will be called when an allocation is required from a + * secure id before the allocation itself is returned to user-space. + * NULL permitted if no need for a callback. + * @param[in] final_release_func Pointer to a function which will be called when the last reference is removed, + * just before the allocation is freed. NULL permitted if no need for a callback. + * @param[in] callback_data An opaque pointer which will be provided to @a filter_func and @a final_release_func + * @return Handle to the new allocation, or @a UMP_DD_INVALID_MEMORY_HANDLE on allocation failure. + */ +UMP_KERNEL_API_EXPORT ump_dd_handle ump_dd_allocate_64(uint64_t size, ump_alloc_flags flags, ump_dd_security_filter filter_func, ump_dd_final_release_callback final_release_func, void* callback_data); + + +/** + * Allocation bits getter. + * Retrieves the allocation flags used when instantiating the given handle. + * Just a copy of the flag given to @ref ump_dd_allocate_64 and @ref ump_dd_create_from_phys_blocks_64 + * @param mem The handle retrieve the bits for + * @return The allocation bits used to instantiate the allocation + */ +UMP_KERNEL_API_EXPORT ump_alloc_flags ump_dd_allocation_flags_get(const ump_dd_handle mem); + + +/** + * Retrieves the secure ID for the specified UMP memory. + * + * This identifier is unique across the entire system, and uniquely identifies + * the specified UMP memory allocation. This identifier can later be used through the + * @ref ump_dd_from_secure_id or + * @ref ump_from_secure_id + * functions in order to access this UMP memory, for instance from another process (if shared of course). + * Unless the allocation was marked as shared the returned ID will only be resolvable in the same process as did the allocation. + * + * Calling on an @a UMP_DD_INVALID_MEMORY_HANDLE will result in undefined behavior. + * Debug builds will assert on this. + * + * @note There is a user space equivalent function called @ref ump_secure_id_get + * + * @see ump_dd_from_secure_id + * @see ump_from_secure_id + * @see ump_secure_id_get + * + * @param mem Handle to UMP memory. + * + * @return Returns the secure ID for the specified UMP memory. + */ +UMP_KERNEL_API_EXPORT ump_secure_id ump_dd_secure_id_get(const ump_dd_handle mem); + +#ifdef CONFIG_KDS +/** + * Retrieve the KDS resource for the specified UMP memory. + * + * The KDS resource should be used to synchronize access to the UMP allocation. + * See the KDS API for how to do that. + * + * @param mem Handle to the UMP memory to query. + * @return Pointer to the KDS resource controlling access to the UMP memory. + */ +UMP_KERNEL_API_EXPORT struct kds_resource * ump_dd_kds_resource_get(const ump_dd_handle mem); +#endif + +/** + * Retrieves a handle to allocated UMP memory. + * + * The usage of UMP memory is reference counted, so this will increment the reference + * count by one for the specified UMP memory. + * Use @ref ump_dd_release when there is no longer any + * use for the retrieved handle. + * + * If called on an non-shared allocation and this is a different process @a UMP_DD_INVALID_MEMORY_HANDLE will be returned. + * + * Calling on an @a UMP_INVALID_SECURE_ID will return @a UMP_DD_INVALID_MEMORY_HANDLE + * + * @note There is a user space equivalent function called @ref ump_from_secure_id + * + * @see ump_dd_release + * @see ump_from_secure_id + * + * @param secure_id The secure ID of the UMP memory to open, that can be retrieved using the @ref ump_secure_id_get function. + * + * @return @a UMP_DD_INVALID_MEMORY_HANDLE indicates failure, otherwise a valid handle is returned. + */ +UMP_KERNEL_API_EXPORT ump_dd_handle ump_dd_from_secure_id(ump_secure_id secure_id); + + +/** + * Retrieves all physical memory block information for specified UMP memory. + * + * This function can be used by other device drivers in order to create MMU tables. + * This function will return a pointer to an array of @ref ump_dd_physical_block_64 in @a pArray and the number of array elements in @a pCount + * + * Calling on an @a UMP_DD_INVALID_MEMORY_HANDLE results in undefined behavior. + * Debug builds will assert on this. + * + * @param mem Handle to UMP memory. + * @param[out] pCount Pointer to where to store the number of items in the returned array + * @param[out] pArray Pointer to where to store a pointer to the physical blocks array + */ +UMP_KERNEL_API_EXPORT void ump_dd_phys_blocks_get_64(const ump_dd_handle mem, uint64_t * const pCount, const ump_dd_physical_block_64 ** const pArray); + +/** + * Retrieves the actual size of the specified UMP memory. + * + * The size is reported in bytes, and is typically page aligned. + * + * Calling on an @a UMP_DD_INVALID_MEMORY_HANDLE results in undefined behavior. + * Debug builds will assert on this. + * + * @note There is a user space equivalent function called @ref ump_size_get + * + * @see ump_size_get + * + * @param mem Handle to UMP memory. + * + * @return Returns the allocated size of the specified UMP memory, in bytes. + */ +UMP_KERNEL_API_EXPORT uint64_t ump_dd_size_get_64(const ump_dd_handle mem); + + +/** + * Adds an extra reference to the specified UMP memory allocation. + * + * The function @ref ump_dd_release must then be used + * to release each copy of the UMP memory handle. + * + * Calling on an @a UMP_DD_INVALID_MEMORY_HANDLE results in undefined behavior. + * Debug builds will assert on this. + * + * @note You are not required to call @ref ump_dd_retain + * for UMP handles returned from + * @ref ump_dd_from_secure_id, + * because these handles are already reference counted by this function. + * + * @note There is a user space equivalent function called @ref ump_retain + * + * @see ump_retain + * + * @param mem Handle to UMP memory. + * @return 0 indicates success, any other value indicates failure. + */ +UMP_KERNEL_API_EXPORT int ump_dd_retain(ump_dd_handle mem); + + +/** + * Releases a reference from the specified UMP memory. + * + * This function must be called once for every reference to the UMP memory handle. + * When the last reference is released, all resources associated with this UMP memory + * handle are freed. + * + * One can only call ump_release when matched with a successful ump_dd_retain, ump_dd_allocate_64 or ump_dd_from_secure_id + * If called on an @a UMP_DD_INVALID_MEMORY_HANDLE the function will early out. + * + * @note There is a user space equivalent function called @ref ump_release + * + * @see ump_release + * + * @param mem Handle to UMP memory. + */ +UMP_KERNEL_API_EXPORT void ump_dd_release(ump_dd_handle mem); + +/** + * Create an ump allocation handle based on externally managed memory. + * Used to wrap an existing allocation as an UMP memory handle. + * Once wrapped the memory acts just like a normal allocation coming from @ref ump_dd_allocate_64. + * The only exception is that the freed physical memory is not put into the pool of free memory, but instead considered returned to the caller once @a final_release_func returns. + * The blocks array will be copied, so no need to hold on to it after this function returns. + * @param[in] blocks Array of @ref ump_dd_physical_block_64 + * @param num_blocks Number of elements in the array pointed to by @a blocks + * @param flags Allocation flags to mark the handle with + * @param[in] filter_func Pointer to a function which will be called when an allocation is required from a secure id before the allocation itself is returned to user-space. + * NULL permitted if no need for a callback. + * @param[in] final_release_func Pointer to a function which will be called when the last reference is removed, just before the allocation is freed. NULL permitted if no need for a callback. + * @param[in] callback_data An opaque pointer which will be provided to @a filter_func and @a final_release_func + * @return Handle to the UMP allocation handle created, or @a UMP_DD_INVALID_MEMORY_HANDLE if no such handle could be created. + */ +UMP_KERNEL_API_EXPORT ump_dd_handle ump_dd_create_from_phys_blocks_64(const ump_dd_physical_block_64 * blocks, uint64_t num_blocks, ump_alloc_flags flags, ump_dd_security_filter filter_func, ump_dd_final_release_callback final_release_func, void* callback_data); + + +/** @name UMP v1 API + * Functions provided to support compatibility with UMP v1 API + * + *@{ + */ + +/** + * Value to indicate an invalid UMP memory handle. + */ +#define UMP_DD_HANDLE_INVALID UMP_DD_INVALID_MEMORY_HANDLE + +/** + * UMP error codes for kernel space. + */ +typedef enum +{ + UMP_DD_SUCCESS, /**< indicates success */ + UMP_DD_INVALID /**< indicates failure */ +} ump_dd_status_code; + + +/** + * Struct used to describe a physical block used by UMP memory + */ +typedef struct ump_dd_physical_block +{ + unsigned long addr; /**< The physical address of the block */ + unsigned long size; /**< The length of the block, typically page aligned */ +} ump_dd_physical_block; + + +/** + * Retrieves a handle to allocated UMP memory. + * + * The usage of UMP memory is reference counted, so this will increment the reference + * count by one for the specified UMP memory. + * Use @ref ump_dd_reference_release "ump_dd_reference_release" when there is no longer any + * use for the retrieved handle. + * + * @note There is a user space equivalent function called @ref ump_handle_create_from_secure_id "ump_handle_create_from_secure_id" + * + * @see ump_dd_reference_release + * @see ump_handle_create_from_secure_id + * + * @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. + * + * @return UMP_INVALID_MEMORY_HANDLE indicates failure, otherwise a valid handle is returned. + */ +UMP_KERNEL_API_EXPORT ump_dd_handle ump_dd_handle_create_from_secure_id(ump_secure_id secure_id); + + + +/** + * Create an ump allocation handle based on externally managed memory. + * Used to wrap an existing allocation as an UMP memory handle. + * + * @param[in] blocks Array of @ref ump_dd_physical_block + * @param num_blocks Number of elements in the array pointed to by @a blocks + * + * @return Handle to the UMP allocation handle created, or @a UMP_DD_INVALID_MEMORY_HANDLE if no such handle could be created. + */ +UMP_KERNEL_API_EXPORT ump_dd_handle ump_dd_handle_create_from_phys_blocks(ump_dd_physical_block * blocks, unsigned long num_blocks); + + +/** + * Retrieves the number of physical blocks used by the specified UMP memory. + * + * This function retrieves the number of @ref ump_dd_physical_block "ump_dd_physical_block" structs needed + * to describe the physical memory layout of the given UMP memory. This can later be used when calling + * the functions @ref ump_dd_phys_blocks_get "ump_dd_phys_blocks_get" and + * @ref ump_dd_phys_block_get "ump_dd_phys_block_get". + * + * @see ump_dd_phys_blocks_get + * @see ump_dd_phys_block_get + * + * @param mem Handle to UMP memory. + * + * @return The number of ump_dd_physical_block structs required to describe the physical memory layout of the specified UMP memory. + */ +UMP_KERNEL_API_EXPORT unsigned long ump_dd_phys_block_count_get(ump_dd_handle mem); + + +/** + * Retrieves all physical memory block information for specified UMP memory. + * + * This function can be used by other device drivers in order to create MMU tables. + * + * @note This function will fail if the num_blocks parameter is either to large or to small. + * + * @see ump_dd_phys_block_get + * + * @param mem Handle to UMP memory. + * @param blocks An array of @ref ump_dd_physical_block "ump_dd_physical_block" structs that will receive the physical description. + * @param num_blocks The number of blocks to return in the blocks array. Use the function + * @ref ump_dd_phys_block_count_get "ump_dd_phys_block_count_get" first to determine the number of blocks required. + * + * @return UMP_DD_SUCCESS indicates success, UMP_DD_INVALID indicates failure. + */ +UMP_KERNEL_API_EXPORT ump_dd_status_code ump_dd_phys_blocks_get(ump_dd_handle mem, ump_dd_physical_block * const blocks, unsigned long num_blocks); + + +/** + * Retrieves the physical memory block information for specified block for the specified UMP memory. + * + * This function can be used by other device drivers in order to create MMU tables. + * + * @note This function will return UMP_DD_INVALID if the specified index is out of range. + * + * @see ump_dd_phys_blocks_get + * + * @param mem Handle to UMP memory. + * @param index Which physical info block to retrieve. + * @param block Pointer to a @ref ump_dd_physical_block "ump_dd_physical_block" struct which will receive the requested information. + * + * @return UMP_DD_SUCCESS indicates success, UMP_DD_INVALID indicates failure. + */ +UMP_KERNEL_API_EXPORT ump_dd_status_code ump_dd_phys_block_get(ump_dd_handle mem, unsigned long index, ump_dd_physical_block * const block); + + +/** + * Retrieves the actual size of the specified UMP memory. + * + * The size is reported in bytes, and is typically page aligned. + * + * @note There is a user space equivalent function called @ref ump_size_get "ump_size_get" + * + * @see ump_size_get + * + * @param mem Handle to UMP memory. + * + * @return Returns the allocated size of the specified UMP memory, in bytes. + */ +UMP_KERNEL_API_EXPORT unsigned long ump_dd_size_get(ump_dd_handle mem); + + +/** + * Adds an extra reference to the specified UMP memory. + * + * This function adds an extra reference to the specified UMP memory. This function should + * be used every time a UMP memory handle is duplicated, that is, assigned to another ump_dd_handle + * variable. The function @ref ump_dd_reference_release "ump_dd_reference_release" must then be used + * to release each copy of the UMP memory handle. + * + * @note You are not required to call @ref ump_dd_reference_add "ump_dd_reference_add" + * for UMP handles returned from + * @ref ump_dd_handle_create_from_secure_id "ump_dd_handle_create_from_secure_id", + * because these handles are already reference counted by this function. + * + * @note There is a user space equivalent function called @ref ump_reference_add "ump_reference_add" + * + * @see ump_reference_add + * + * @param mem Handle to UMP memory. + */ +UMP_KERNEL_API_EXPORT void ump_dd_reference_add(ump_dd_handle mem); + + +/** + * Releases a reference from the specified UMP memory. + * + * This function should be called once for every reference to the UMP memory handle. + * When the last reference is released, all resources associated with this UMP memory + * handle are freed. + * + * @note There is a user space equivalent function called @ref ump_reference_release "ump_reference_release" + * + * @see ump_reference_release + * + * @param mem Handle to UMP memory. + */ +UMP_KERNEL_API_EXPORT void ump_dd_reference_release(ump_dd_handle mem); + +/* @} */ + +#ifdef __cplusplus +} +#endif + + +/** @} */ /* end group ump_kernel_space_api */ + +/** @} */ /* end group ump_api */ + +#endif /* _UMP_KERNEL_INTERFACE_H_ */ |