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.
191 lines
5.7 KiB
191 lines
5.7 KiB
/*
|
|
* Copyright 2002-2019 Intel Corporation.
|
|
*
|
|
* This software and the related documents are Intel copyrighted materials, and your
|
|
* use of them is governed by the express license under which they were provided to
|
|
* you ("License"). Unless the License provides otherwise, you may not use, modify,
|
|
* copy, publish, distribute, disclose or transmit this software or the related
|
|
* documents without Intel's prior written permission.
|
|
*
|
|
* This software and the related documents are provided as is, with no express or
|
|
* implied warranties, other than those that are expressly stated in the License.
|
|
*/
|
|
|
|
// <COMPONENT>: os-apis
|
|
// <FILE-TYPE>: component public header
|
|
|
|
#ifndef OS_APIS_PIN_TLS_H_
|
|
#define OS_APIS_PIN_TLS_H_
|
|
|
|
#include "types.h"
|
|
|
|
/*!
|
|
* @defgroup OS_APIS_PIN_TLS Thread local storage
|
|
* @brief Contains API for thread local storage (TLS).
|
|
*/
|
|
|
|
/*! @ingroup OS_APIS_PIN_TLS
|
|
* Prototype for TLS value destructor function.
|
|
* The only argument for this function is the value stored in TLS.
|
|
*/
|
|
typedef VOID (*TLS_DESTRUCTOR)(VOID*);
|
|
|
|
/*! @ingroup OS_APIS_PIN_TLS
|
|
* Type for index inside the dynamic TLS.
|
|
*/
|
|
typedef ADDRINT PIN_TLS_INDEX;
|
|
|
|
#define OS_APIS_INVALID_PIN_TLS_INDEX ((PIN_TLS_INDEX)-1)
|
|
|
|
/*! @ingroup OS_APIS_PIN_TLS
|
|
* Return the base address for the application-wide TLS data structure.
|
|
* The TLS data structure is used to implement a TLS which is not based
|
|
* on segment registers.
|
|
*
|
|
* @return Pointer to the base address of the TLS data structure.
|
|
*
|
|
* @par Availability:
|
|
* @b O/S: Windows, Linux & macOS*\n
|
|
* @b CPU: All\n
|
|
*/
|
|
VOID* OS_TlsGetBaseAddress();
|
|
|
|
/*! @ingroup OS_APIS_PIN_TLS
|
|
* Allocates a new slot in the dynamic TLS.
|
|
*
|
|
* @param[in] dest Optional destructor function that will be called on each value stores in TLS
|
|
* when its corresponding thread dies.
|
|
*
|
|
* @return Index for the newly allocated slot or OS_APIS_INVALID_PIN_TLS_INDEX on error.
|
|
*
|
|
* @par Availability:
|
|
* @b O/S: Windows, Linux & macOS*\n
|
|
* @b CPU: All\n
|
|
*/
|
|
PIN_TLS_INDEX OS_TlsAlloc(TLS_DESTRUCTOR dest);
|
|
|
|
/*! @ingroup OS_APIS_PIN_TLS
|
|
* Free a previously allocated slot in the dynamic TLS.
|
|
*
|
|
* @param[in] idx The index to free.
|
|
*
|
|
* @return True on success.
|
|
*
|
|
* @par Availability:
|
|
* @b O/S: Windows, Linux & macOS*\n
|
|
* @b CPU: All\n
|
|
*/
|
|
BOOL_T OS_TlsFree(PIN_TLS_INDEX idx);
|
|
|
|
/*! @ingroup OS_APIS_PIN_TLS
|
|
* Get the value associated with a particular index from the current thread's
|
|
* dynamic TLS.
|
|
*
|
|
* @param[in] idx The index of the value to get.
|
|
*
|
|
* @return Pointer to the value, or NULL otherwise.
|
|
*
|
|
* @par Availability:
|
|
* @b O/S: Windows, Linux & macOS*\n
|
|
* @b CPU: All\n
|
|
*/
|
|
VOID* OS_TlsGetValue(PIN_TLS_INDEX idx);
|
|
|
|
/*! @ingroup OS_APIS_PIN_TLS
|
|
* Get the value associated with a particular index of a particular thread's
|
|
* dynamic TLS.
|
|
*
|
|
* @param[in] idx The index of the value to get.
|
|
* @param[in] ntid The thread ID for which the TLS value will be retrieved.
|
|
*
|
|
* @return Pointer to the value, or NULL otherwise.
|
|
*
|
|
* @par Availability:
|
|
* @b O/S: Windows, Linux & macOS*\n
|
|
* @b CPU: All\n
|
|
*/
|
|
VOID* OS_TlsGetValueForThread(PIN_TLS_INDEX idx, NATIVE_TID ntid);
|
|
|
|
/*! @ingroup OS_APIS_PIN_TLS
|
|
* Return the address of the static TLS for the current thread
|
|
*
|
|
* @return Address of the static TLS for the current threads (which is a VOID* array).
|
|
*
|
|
* @par Availability:
|
|
* @b O/S: Windows, Linux & macOS*\n
|
|
* @b CPU: All\n
|
|
*/
|
|
VOID** OS_TlsGetArrayAddress(void);
|
|
|
|
/*! @ingroup OS_APIS_PIN_TLS
|
|
* Return the address of the static TLS for a particular thread
|
|
*
|
|
* @param[in] ntid The thread ID for which the static TLS will be retrieved.
|
|
*
|
|
* @return Address of the static TLS for the specified threads (which is a VOID* array).
|
|
*
|
|
* @par Availability:
|
|
* @b O/S: Windows, Linux & macOS*\n
|
|
* @b CPU: All\n
|
|
*/
|
|
VOID** OS_TlsGetArrayAddressForThread(NATIVE_TID ntid);
|
|
|
|
/*! @ingroup OS_APIS_PIN_TLS
|
|
* Set the value associated with a particular index in the current thread's
|
|
* dynamic TLS.
|
|
*
|
|
* @param[in] idx The index of the value to set.
|
|
* @param[in] val The new value to set.
|
|
*
|
|
* @return True on success.
|
|
*
|
|
* @par Availability:
|
|
* @b O/S: Windows, Linux & macOS*\n
|
|
* @b CPU: All\n
|
|
*/
|
|
BOOL_T OS_TlsSetValue(PIN_TLS_INDEX idx, VOID* val);
|
|
|
|
/*! @ingroup OS_APIS_PIN_TLS
|
|
* Set the value associated with a particular index in of a particular thread's
|
|
* dynamic TLS.
|
|
*
|
|
* @param[in] idx The index of the value to set.
|
|
* @param[in] ntid The thread ID for which the value will be set in its TLS.
|
|
* @param[in] val The new value to set.
|
|
*
|
|
* @return True on success.
|
|
*
|
|
* @par Availability:
|
|
* @b O/S: Windows, Linux & macOS*\n
|
|
* @b CPU: All\n
|
|
*/
|
|
BOOL_T OS_TlsSetValueForThread(PIN_TLS_INDEX idx, NATIVE_TID ntid, VOID* val);
|
|
|
|
/*! @ingroup OS_APIS_PIN_TLS
|
|
* Free all resources that are used for a particular thread's TLS.
|
|
* This function is usually called when a thread is about to exit.
|
|
*
|
|
* @param[in] ntid The thread ID for which the TLS need to be freed.
|
|
*
|
|
* @par Availability:
|
|
* @b O/S: Windows, Linux & macOS*\n
|
|
* @b CPU: All\n
|
|
*/
|
|
VOID OS_TlsFreeThreadTls(NATIVE_TID ntid);
|
|
|
|
/*! @ingroup OS_APIS_PIN_TLS
|
|
* Add a destructor for all threads' static TLS.
|
|
* The destructor for static TLS is called on each thread termination, provided
|
|
* that the thread had an allocated static TLS.
|
|
*
|
|
* @param[in] destructor Destructor function that will be called with the pointer
|
|
* to the fixed TLS when a thread terminates.
|
|
*
|
|
* @par Availability:
|
|
* @b O/S: Windows, Linux & macOS*\n
|
|
* @b CPU: All\n
|
|
*/
|
|
BOOL_T OS_TlsAddStaticTlsDestructor(TLS_DESTRUCTOR destructor);
|
|
|
|
#endif // file guard
|