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)

roc-obj 5.7.31921                                  April 2025                                         ROC-OBJ(1)