NAME¶

roc-obj - ROCm code object extraction and scripting tool

SYNOPSIS¶

roc-obj [-h] [-t REGEXP] [-o OUTDIR] [-I REPLACE-STRING|-i] [-d] EXECUTABLE... [: [SUFFIX COMMAND [ARGS...] ;]...]

DESCRIPTION¶

Wrapper for roc-obj-ls and roc-obj-extract which extracts code objects embedded in each EXECUTABLE and optionally applies COMMANDs to them.

If the POSIX extended regular expression REGEXP is specified, only embedded code objects whose Target ID matches REGEXP are extracted; otherwise all code objects are extracted.

If the directory path OUTDIR is specified, it is created if it does not already exist, and the code objects are extracted into it; otherwise they are extracted into the current working directory.

The extracted files are named by appending a ":" followed by the Target ID of the extracted code object to the input filename EXECUTABLE they were extracted from.

If the list of EXECUTABLE arguments is terminated with ":" then after all selected files are successfully extracted, zero or more additional embedded command-lines, separated by ";", are read from the command-line starting after the ":". These must specify a SUFFIX used to name the output of the corresponding COMMAND, along with the COMMAND name and any ARGS to it.

Then each COMMAND is executed, as if by a POSIX "execvp" function, once for each embedded code object that was created in OUTDIR. (Note: Typically this means the user must ensure the commands are present in at least one directory of the "PATH" environment variable.) For each execution of COMMAND:

If REPLACE-STRING is specified, all instances of REPLACE-STRING in ARGS are replaced with the file path of the extracted code object before executing COMMAND.

The standard input is redirected from the extracted code object.

If SUFFIX is "-" the standard output is not redirected. If SUFFIX is "!" the standard output is redirected to /dev/null. Otherwise, the standard output is redirected to files named by the file path of the extracted code object with SUFFIX appended.

NOTES¶

The executables roc-obj-ls, roc-obj-extract, and llvm-objdump (in the case of disassembly requested using the -d flag) are searched for in a unique way. A series of directories are searched, some conditionally, until a suitable executable is found. If all directories are searched without finding the executable, an error occurs. The first directory searched is the one containing the hard-link to the roc-obj being executed, known as the "base directory". Next, if the environment variable HIP_CLANG_PATH is set, it is searched; otherwise, the base directory path is appended with "../../llvm/bin" and it is searched. Finally, the PATH is searched as if by a POSIX "execvp" function.

OPTIONS¶

-h, --help

print this help text and exit

-t, --target-id

only extract code objects from EXECUTABLE whose Target ID matches the POSIX extended regular expression REGEXP

-o, --outdir

set the output directory, which is created if it does not exist

-I, --replace-string

replace all occurrences of the literal string REPLACE-STRING in ARGS with the input filename

-i, --replace

equivalent to -I{}

-d, --disassemble

diassemble extracted code objects; equivalent to : .s llvm-objdump -d - ;

EXAMPLES¶

Extract all code objects embedded in a.so: $ roc-obj a.so

Extract all code objects embedded in a.so, b.so, and c.so: $ roc-obj a.so b.so c.so

Extract all code objects embedded in a.so with "gfx9" in their Target ID: $ roc-obj -t gfx9 a.so

Extract all code objects embedded in a.so into output/ (creating it if needed): $ roc-obj -o output/ a.so

Extract all code objects embedded in a.so with "gfx9" in their Target ID into output/ (creating it if needed): $ roc-obj -t gfx9 -o output/ a.so

Extract all code objects embedded in a.so, and then disassemble each of them to files ending with .s: $ roc-obj -d a.so

Extract all code objects embedded in a.so, and count the number of bytes in each, writing the results to files ending with .count: $ roc-obj a.so : .count wc -c

Extract all code objects embedded in a.so, and inspect their ELF headers using llvm-readelf (which will not read from standard input), writing to files ending with .hdr: $ roc-obj -I'{}' a.so : .hdr llvm-readelf -h '{}'

Extract all code objects embedded in a.so, and then extract each of their .text sections using llvm-objcopy (which won't read from standard input or write to standard output): $ roc-obj -I'{}' a.so : ! llvm-objcopy -O binary :only-section=.text '{}' '{}.text'

Extract all code objects embedded in a.so, b.so, and c.so with target feature xnack disabled into directory out/. Then, for each: Write the size in bytes into a file ending with .count, and Write a textual description of the ELF headers to a file ending with .hdr, and Extract the .text section to a file ending with .text $ roc-obj -I'{}' -t xnack- -o out/ a.so b.so c.so : \

.count wc -c \; .hdr llvm-readelf -h '{}' \; ! llvm-objcopy -O binary --only-section=.text '{}' '{}.text'

SEE ALSO¶

roc-obj-ls(1), roc-obj-extract(1)