You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 
 
 
 
 
hardware_samsung/exynos4/hal/include/ump.h

268 lines
8.2 KiB

/*
* Copyright (C) 2010-2013 ARM Limited. All rights reserved.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
/**
* @file ump.h
*
* This file contains the user space part of the UMP API.
*/
#ifndef _UNIFIED_MEMORY_PROVIDER_H_
#define _UNIFIED_MEMORY_PROVIDER_H_
/** @defgroup ump_user_space_api UMP User Space API
* @{ */
#include "ump_platform.h"
#ifdef __cplusplus
extern "C" {
#endif
/**
* External representation of a UMP handle in user space.
*/
typedef void * ump_handle;
/**
* Typedef for a secure ID, a system wide identificator for UMP memory buffers.
*/
typedef unsigned int ump_secure_id;
/**
* Value to indicate an invalid UMP memory handle.
*/
#define UMP_INVALID_MEMORY_HANDLE ((ump_handle)0)
/**
* Value to indicate an invalid secure Id.
*/
#define UMP_INVALID_SECURE_ID ((ump_secure_id)-1)
/**
* UMP error codes for user space.
*/
typedef enum
{
UMP_OK = 0, /**< indicates success */
UMP_ERROR, /**< indicates failure */
} ump_result;
/**
* Opens and initializes the UMP library.
*
* This function must be called at least once before calling any other UMP API functions.
* Each open is reference counted and must be matched with a call to @ref ump_close "ump_close".
*
* @see ump_close
*
* @return UMP_OK indicates success, UMP_ERROR indicates failure.
*/
UMP_API_EXPORT ump_result ump_open(void);
/**
* Terminate the UMP library.
*
* This must be called once for every successful @ref ump_open "ump_open". The UMP library is
* terminated when, and only when, the last open reference to the UMP interface is closed.
*
* @see ump_open
*/
UMP_API_EXPORT void ump_close(void);
/**
* Retrieves the secure ID for the specified UMP memory.
*
* This identificator is unique across the entire system, and uniquely identifies
* the specified UMP memory. This identificator can later be used through the
* @ref ump_handle_create_from_secure_id "ump_handle_create_from_secure_id" or
* @ref ump_dd_handle_create_from_secure_id "ump_dd_handle_create_from_secure_id"
* functions in order to access this UMP memory, for instance from another process.
*
* @note There is a kernel space equivalent function called @ref ump_dd_secure_id_get "ump_dd_secure_id_get"
*
* @see ump_handle_create_from_secure_id
* @see ump_dd_handle_create_from_secure_id
* @see ump_dd_secure_id_get
*
* @param mem Handle to UMP memory.
*
* @return Returns the secure ID for the specified UMP memory.
*/
UMP_API_EXPORT ump_secure_id ump_secure_id_get(ump_handle mem);
/**
* 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_reference_release "ump_reference_release" when there is no longer any
* use for the retrieved handle.
*
* @note There is a kernel space equivalent function called @ref ump_dd_handle_create_from_secure_id "ump_dd_handle_create_from_secure_id"
*
* @see ump_reference_release
* @see ump_dd_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_API_EXPORT ump_handle ump_handle_create_from_secure_id(ump_secure_id secure_id);
/**
* Retrieves the actual size of the specified UMP memory.
*
* The size is reported in bytes, and is typically page aligned.
*
* @note There is a kernel space equivalent function called @ref ump_dd_size_get "ump_dd_size_get"
*
* @see ump_dd_size_get
*
* @param mem Handle to UMP memory.
*
* @return Returns the allocated size of the specified UMP memory, in bytes.
*/
UMP_API_EXPORT unsigned long ump_size_get(ump_handle mem);
/**
* Read from specified UMP memory.
*
* Another way of reading from (and writing to) UMP memory is to use the
* @ref ump_mapped_pointer_get "ump_mapped_pointer_get" to retrieve
* a CPU mapped pointer to the memory.
*
* @see ump_mapped_pointer_get
*
* @param dst Destination buffer.
* @param src Handle to UMP memory to read from.
* @param offset Where to start reading, given in bytes.
* @param length How much to read, given in bytes.
*/
UMP_API_EXPORT void ump_read(void * dst, ump_handle src, unsigned long offset, unsigned long length);
/**
* Write to specified UMP memory.
*
* Another way of writing to (and reading from) UMP memory is to use the
* @ref ump_mapped_pointer_get "ump_mapped_pointer_get" to retrieve
* a CPU mapped pointer to the memory.
*
* @see ump_mapped_pointer_get
*
* @param dst Handle to UMP memory to write to.
* @param offset Where to start writing, given in bytes.
* @param src Buffer to read from.
* @param length How much to write, given in bytes.
*/
UMP_API_EXPORT void ump_write(ump_handle dst, unsigned long offset, const void * src, unsigned long length);
/**
* Retrieves a memory mapped pointer to the specified UMP memory.
*
* This function retrieves a memory mapped pointer to the specified UMP memory,
* that can be used by the CPU. Every successful call to
* @ref ump_mapped_pointer_get "ump_mapped_pointer_get" is reference counted,
* and must therefore be followed by a call to
* @ref ump_mapped_pointer_release "ump_mapped_pointer_release " when the
* memory mapping is no longer needed.
*
* @note Systems without a MMU for the CPU only return the physical address, because no mapping is required.
*
* @see ump_mapped_pointer_release
*
* @param mem Handle to UMP memory.
*
* @return NULL indicates failure, otherwise a CPU mapped pointer is returned.
*/
UMP_API_EXPORT void * ump_mapped_pointer_get(ump_handle mem);
/**
* Releases a previously mapped pointer to the specified UMP memory.
*
* The CPU mapping of the specified UMP memory memory is reference counted,
* so every call to @ref ump_mapped_pointer_get "ump_mapped_pointer_get" must
* be matched with a call to this function when the mapping is no longer needed.
*
* The CPU mapping is not removed before all references to the mapping is released.
*
* @note Systems without a MMU must still implement this function, even though no unmapping should be needed.
*
* @param mem Handle to UMP memory.
*/
UMP_API_EXPORT void ump_mapped_pointer_release(ump_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_handle
* variable. The function @ref ump_reference_release "ump_reference_release" must then be used
* to release each copy of the UMP memory handle.
*
* @note You are not required to call @ref ump_reference_add "ump_reference_add"
* for UMP handles returned from
* @ref ump_handle_create_from_secure_id "ump_handle_create_from_secure_id",
* because these handles are already reference counted by this function.
*
* @note There is a kernel space equivalent function called @ref ump_dd_reference_add "ump_dd_reference_add"
*
* @see ump_dd_reference_add
*
* @param mem Handle to UMP memory.
*/
UMP_API_EXPORT void ump_reference_add(ump_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 kernel space equivalent function called @ref ump_dd_reference_release "ump_dd_reference_release"
*
* @see ump_dd_reference_release
*
* @param mem Handle to UMP memory.
*/
UMP_API_EXPORT void ump_reference_release(ump_handle mem);
#ifdef __cplusplus
}
#endif
/** @} */ /* end group ump_user_space_api */
#endif /*_UNIFIED_MEMORY_PROVIDER_H_ */