.TH ROC-OBJ "1" "April 2025" "roc-obj 5.7.31921" "User Commands"
.SH NAME
roc-obj \- ROCm code object extraction and scripting tool
.SH SYNOPSIS
.B roc-obj
[\fI\,-h\/\fR] [\fI\,-t REGEXP\/\fR] [\fI\,-o OUTDIR\/\fR] [\fI\,-I REPLACE-STRING|-i\/\fR] [\fI\,-d\/\fR]
EXECUTABLE... [: [SUFFIX COMMAND [ARGS...] ;]...]
.SH DESCRIPTION
.IP
.PP
Wrapper for roc\-obj\-ls and roc\-obj\-extract which extracts code objects
embedded in each EXECUTABLE and optionally applies COMMANDs to them.
.PP
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.
.PP
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.
.PP
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.
.PP
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.
.PP
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:
.PP
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.
.PP
The standard input is redirected from the extracted code object.
.PP
If SUFFIX is "\-" the standard output is not redirected. If SUFFIX is "!" the
standard output is redirected to \fI\,/dev/null\/\fP. Otherwise, the standard output
is redirected to files named by the file path of the extracted code object
with SUFFIX appended.
.PP
.SH NOTES
The executables roc\-obj\-ls, roc\-obj\-extract, and llvm\-objdump (in the
case of disassembly requested using the \fB\-d\fR 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.
.SH OPTIONS
.TP
\fB\-h\fR, \fB\-\-help\fR
print this help text and exit
.TP
\fB\-t\fR, \fB\-\-target\-id\fR
only extract code objects from EXECUTABLE whose Target ID
matches the POSIX extended regular expression REGEXP
.TP
\fB\-o\fR, \fB\-\-outdir\fR
set the output directory, which is created if it
does not exist
.TP
\fB\-I\fR, \fB\-\-replace\-string\fR
replace all occurrences of the literal string
REPLACE\-STRING in ARGS with the input filename
.TP
\fB\-i\fR, \fB\-\-replace\fR
equivalent to \fB\-I\fR{}
.TP
\fB\-d\fR, \fB\-\-disassemble\fR
diassemble extracted code objects; equivalent to
: .s llvm\-objdump \fB\-d\fR \- ;
.PP
.SH EXAMPLES
.PP
Extract all code objects embedded in a.so:
$ roc\-obj a.so
.PP
Extract all code objects embedded in a.so, b.so, and c.so:
$ roc\-obj a.so b.so c.so
.PP
Extract all code objects embedded in a.so with "gfx9" in their Target ID:
$ roc\-obj \fB\-t\fR gfx9 a.so
.PP
Extract all code objects embedded in a.so into output/ (creating it if needed):
$ roc\-obj \fB\-o\fR output/ a.so
.PP
Extract all code objects embedded in a.so with "gfx9" in their Target ID
into output/ (creating it if needed):
$ roc\-obj \fB\-t\fR gfx9 \fB\-o\fR output/ a.so
.PP
Extract all code objects embedded in a.so, and then disassemble each of them
to files ending with .s:
$ roc\-obj \fB\-d\fR a.so
.PP
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 \fB\-c\fR
.PP
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 \fB\-I\fR'{}' a.so : .hdr llvm\-readelf \fB\-h\fR '{}'
.PP
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 \fB\-I\fR'{}' a.so : ! llvm\-objcopy \fB\-O\fR binary :only\-section=.text '{}' '{}.text'
.PP
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 \fB\-I\fR'{}' \fB\-t\fR xnack\- \fB\-o\fR out/ a.so b.so c.so : \e
.IP
\&.count wc \fB\-c\fR \e;
\&.hdr llvm\-readelf \fB\-h\fR '{}' \e;
! llvm\-objcopy \fB\-O\fR binary \fB\-\-only\-section=\fR.text '{}' '{}.text'
.SH SEE ALSO
.sp
\fBroc-obj-ls(1)\fP, \fBroc-obj-extract(1)\fP