These APIs provide information about the instrumented process. They are available in any thread, including any internal thread spawned by the tool.
◆ 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
◆ 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()
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()
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