Typedefs
typedef void *	CHILD_PROCESS

typedef BOOL(*	FOLLOW_CHILD_PROCESS_CALLBACK) (CHILD_PROCESS cProcess, VOID *val)

Functions
OS_PROCESS_ID	CHILD_PROCESS_GetId (CHILD_PROCESS cProcess)

VOID	CHILD_PROCESS_GetCommandLine (CHILD_PROCESS cProcess, INT pArgc, const CHAR const **pArgv)

VOID	CHILD_PROCESS_SetPinCommandLine (CHILD_PROCESS cProcess, INT argc, const CHAR const argv)

NORETURN VOID	PIN_ExitProcess (INT32 exitCode)

INT	PIN_GetPid ()

BOOL	PIN_IsAmxActive (THREADID threadId)

UINT32	TileCfg_GetTileRows (UINT8 *tileCfgReg, REG tmm)

UINT32	TileCfg_GetTileBytesPerRow (UINT8 *tileCfgReg, REG tmm)

UINT8	TileCfg_GetPaletteID (UINT8 *tileCfgReg)

NORETURN VOID	PIN_ExitApplication (INT32 status)

Detailed Description

These APIs provide information about the instrumented process. They are available in any thread, including any internal thread spawned by the tool.

Typedef Documentation

◆ CHILD_PROCESS

typedef void* CHILD_PROCESS

Pin client functions for the follow child process mechanism

CHILD_PROCESS - Handle for child process APIs

◆ FOLLOW_CHILD_PROCESS_CALLBACK

typedef BOOL(* FOLLOW_CHILD_PROCESS_CALLBACK) (CHILD_PROCESS cProcess, VOID *val)

Call back function before child(Windows*)/exec-ed(Linux*) process is starting to execute. The function can be registered by PIN_AddFollowChildProcessFunction().

Parameters

[in]	childProcess	Child process handle, it's lifetime is in the scope of the callback
[in]	val	The tool's call-back value

Returns: TRUE If user is interested to inject Pin (and tool) into child/exec-ed process
FALSE If user is not interested to inject Pin (and tool) into child/exec-ed process

Function Documentation

◆ CHILD_PROCESS_GetCommandLine()

VOID CHILD_PROCESS_GetCommandLine	(	CHILD_PROCESS	cProcess,
		INT *	pArgc,
		const CHAR const *	pArgv
	)

Get application's original command line (without Pin's command line)

Parameters

[in]	childProcess	child process handle
[out]	pArgc	pointer to application's argc
[out]	pArgv	pointer to application's argv this data is allocated by Pin and can't be modified by tool, it's lifetime is in the scope of the callback

Availability:: Mode: JIT & Probe
O/S: Windows
CPU: All

◆ CHILD_PROCESS_GetId()

OS_PROCESS_ID CHILD_PROCESS_GetId ( CHILD_PROCESS cProcess )

Get process id of child process (meaningful only for Windows*)

Parameters

[in] childProcess child process handle

Returns: process id of child process

Availability:: Mode: JIT & Probe
O/S: Windows
CPU: All

◆ CHILD_PROCESS_SetPinCommandLine()

VOID CHILD_PROCESS_SetPinCommandLine	(	CHILD_PROCESS	cProcess,
		INT	argc,
		const CHAR const	argv
	)

Set Pin's (and tool's) command line for the child process (e.g. "c:\\pin_path\\pin -probe -follow_execv -t c:\\pintool_path\\tool --")

If this API is not called, Pin will be injected into child/exec-ed process with the same command line as of current process.

NOTE:

Providing full path for Pin and tool is the safest way to ensure they will be found (e.g. changing execution directory by application)
Use same Pin version for all process tree

Parameters

[in]	childProcess	handle to child process
[in]	argc	Pin's (and tool's) argc
[in]	argv	Pin's (and tool's) argv, this data is allocated by tool and can't be modified by Pin, it's lifetime is in the scope of this function

Availability:: Mode: JIT & Probe
O/S: Windows
CPU: All

◆ PIN_ExitApplication()

NORETURN VOID PIN_ExitApplication ( INT32 status )

Terminate the current process after calling the relevant thread and process exit callbacks. This call behaves "as if" the application process itself had executed a process termination system call. It therefore does perform all the finalization actions Pin normally takes on application process exit, including calling registered thread and process fini-functions, unlike PIN_ExitProcess, which exits immediately.

This API may be called from an instrumentation callback function or an analysis routine. However, it should not be called from any FINI_CALLBACK or THREAD_FINI_CALLBACK routines. It may be called by an application thread or a tool internal thread (that was created via PIN_SpawnInternalThread).

Be aware, that when called from an internal thread, the calling thread will not exit until after the tool's fini callbacks return. Therefore, to avoid deadlock, your fini callbacks should not wait for that internal thread to exit.

Parameters

[in] status The result argument to exit

Returns: This function does not return.

Note: The vm and pin client locks are obtained during the call of this API.

Availability:: Mode: JIT
O/S: Linux,Windows,BSD
CPU: All

◆ PIN_ExitProcess()

NORETURN VOID PIN_ExitProcess ( INT32 exitCode )

Terminate the current process immediately, without calling any thread or process fini callbacks that may be registered. (See PIN_ExitApplication, if you want fini callbacks to be called).

This function should be used only for abnormal termination of the instrumented process. Normally, the process is terminated when Pin executes a process termination system call on behalf of the application.

Parameters

[in] exitCode exit code of the process to be reported to the operating system.

Returns: the function never returns.

Availability:: Mode: JIT & Probe
O/S: Linux, Windows & macOS*
CPU: All

◆ PIN_GetPid()

INT PIN_GetPid ( )

Returns current process id

Availability:: Mode: JIT & Probe
O/S: Linux, Windows & macOS*
CPU: All

◆ PIN_IsAmxActive()

BOOL PIN_IsAmxActive ( THREADID threadId )

AMX auxiliary API

Return TRUE is if AMX is in use in the specified thread, FALSE otherwise (AMX is in init state). Also return FALSE on CPU does not support AMX. (For additional information see Intel SDM documentation on AMX)

Parameters

[in] threadId Pin thread ID for which AMX status is requested INVALID_THREADID can be used, Pin will find and use current thread (Not recommended as this flow cost more performance wise)

Returns: TRUE is if AMX is in use, FALSE otherwise (AMX is in init state).

Availability:: Mode: JIT
O/S: Linux & Windows
CPU: Intel(R) 64 architecture

◆ TileCfg_GetPaletteID()

UINT8 TileCfg_GetPaletteID ( UINT8 * tileCfgReg )

Return palette ID for the specified tile configuration value. (For additional information see Intel SDM documentation on AMX)

Parameters

[in] tileCfgReg Pointer to a buffer holding tile configuration value (generated with IARG_REG_REFERENCE)

Returns: palette ID for the specified tile configuration value.

Availability:: Mode: JIT
O/S: Linux & Windows
CPU: Intel(R) 64 architecture

◆ TileCfg_GetTileBytesPerRow()

UINT32 TileCfg_GetTileBytesPerRow	(	UINT8 *	tileCfgReg,
		REG	tmm
	)

Return number of bytes per row for the specified tmm tile register and the specified tile configuration value. (For additional information see Intel SDM documentation on AMX)

Parameters

[in]	tileCfgReg	Pointer to a buffer holding tile configuration value (generated with IARG_REG_REFERENCE)
[in]	tmm	tile register enumeration for which this information is requested.

Returns: number of bytes per row for the specified tmm tile register and the specified tile configuration value.

Availability:: Mode: JIT
O/S: Linux & Windows
CPU: Intel(R) 64 architecture

◆ TileCfg_GetTileRows()

UINT32 TileCfg_GetTileRows	(	UINT8 *	tileCfgReg,
		REG	tmm
	)

Return number of rows for the specified tmm tile register and the specified tile configuration value. (For additional information see Intel SDM documentation on AMX)

Parameters

[in]	tileCfgReg	Pointer to a buffer holding tile configuration value (generated with IARG_REG_REFERENCE)
[in]	tmm	tile register enumeration for which this information is requested.

Returns: number of rows for the specified tmm tile register and the specified tile configuration value.

Availability:: Mode: JIT
O/S: Linux & Windows
CPU: Intel(R) 64 architecture

Typedefs

Functions

Detailed Description

Typedef Documentation

◆ CHILD_PROCESS

◆ FOLLOW_CHILD_PROCESS_CALLBACK

Function Documentation

◆ CHILD_PROCESS_GetCommandLine()

◆ CHILD_PROCESS_GetId()

◆ CHILD_PROCESS_SetPinCommandLine()

◆ PIN_ExitApplication()

◆ PIN_ExitProcess()

◆ PIN_GetPid()

◆ PIN_IsAmxActive()

◆ TileCfg_GetPaletteID()

◆ TileCfg_GetTileBytesPerRow()

◆ TileCfg_GetTileRows()