ROC-OBJ(1)

🎀 ROC-OBJ 🎀

okay so bestie, welcome to roc-obj, a manual page from the User Commands section (that's section 1, the "you literally just run this in your shell" section 💅). It's giving build-tool energy, it's giving ROCm, and honestly? It's kind of iconic.

---

✨ NAME ✨

roc-obj — the ROCm code object extraction and scripting tool. no cap, that's the whole vibe.

---

🌸 SYNOPSIS 🌸

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

---

💖 DESCRIPTION 💖

So roc-obj is a wrapper for roc-obj-ls and roc-obj-extract, and what it does is pull out the code objects embedded in each EXECUTABLE — and then, if you want, it'll run *COMMAND*s on them. like a little pipeline glow-up ✨

If you hand it the POSIX extended regular expression REGEXP, then only the embedded code objects whose Target ID matches REGEXP get extracted. No REGEXP? Then literally all of them come out. all of them. the whole squad 🫶

If you give it the directory path OUTDIR, it creates that directory if it doesn't already exist, and the code objects go in there. If you don't, they land in the current working directory. easy.

The extracted files get their names by appending a ":" and then the Target ID of the extracted code object onto the input filename EXECUTABLE they came from. so you always know which file birthed which code object, periodt.

Now here's the fun part 👑 — if the list of EXECUTABLE arguments ends with ":", then after all the selected files have been successfully extracted, zero or more extra embedded command-lines (separated by ";") get read off the command line starting right after that ":". Each one has to specify a SUFFIX (used to name the output of the matching COMMAND), plus the COMMAND name and any ARGS for it.

Then each COMMAND is executed — as if by a POSIX "execvp" function — once for every embedded code object that was created in OUTDIR. (note: this usually means you, the user, have to make sure those commands exist in at least one directory listed in your "PATH" environment variable. just a heads up, bestie.)

And for each execution of COMMAND, here's the tea:

• If REPLACE-STRING is specified, every instance of REPLACE-STRING inside ARGS gets swapped out for the file path of the extracted code object before COMMAND runs.
• Standard input is redirected from the extracted code object.
• If SUFFIX is "-", standard output is not redirected. If SUFFIX is "!", standard output gets redirected to /dev/null (bye 👋). Otherwise, standard output gets 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 (that last one only when you asked for disassembly with the -d flag) get searched for in a unique way. A series of directories is searched — some of them conditionally — until a suitable executable is found. If every single directory gets searched and nothing turns up, you get an error. 💀

Here's the search order, bestie, in order:

1. The first directory searched is the one containing the hard-link to the roc-obj being executed. This is known as the "base directory".
2. Next: if the environment variable HIP_CLANG_PATH is set, that gets searched. Otherwise, the base directory path gets "../../llvm/bin" appended to it, and that gets searched.
3. Finally, the PATH is searched, as if by a POSIX "execvp" function.

---

💅 OPTIONS 💅

• -h, --help — prints this help text and dips. that's it, that's the option.
• -t, --target-id — only extract code objects from EXECUTABLE whose Target ID matches the POSIX extended regular expression REGEXP. picky in the best way.
• -o, --outdir — sets the output directory, and yes, it gets created if it doesn't exist. ✨
• -I, --replace-string — replaces every occurrence of the literal string REPLACE-STRING inside ARGS with the input filename.
• -i, --replace — equivalent to -I{}. same thing, shorter to type, we love a shortcut.
• -d, --disassemble — disassembles the 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) — go say hi to the friends, they're the ones doing the actual heavy lifting 💜

---

and that's the whole page, bestie!! this one is roc-obj version 5.7.31921, dated April 2025 — so yeah, fresh-ish, and now you know it inside and out. go extract something. slay 🫶💖