SWDEV-229776 - Add bin/roc-obj

Change-Id: If4449d7c47b72e437aaca71ae64ea37d202e2b18

docs/markdown/obj_tooling.md

@@ -1,8 +1,37 @@
 # ROCm Code Object tooling
 
-ROCm compiler generated code objects (executables, object files, and shared object libraries) can be examined and code objects extracted with the following tools.
+ROCm compiler generated code objects (executables, object files, and shared
+object libraries) can be examined and code objects extracted with the following
+tools.
 
-## URI syntax:
+## roc-obj
+
+High-level wrapper around low-level tooling described below. For a more
+detailed overview, see the help text available with `roc-obj --help`.
+
+### Examples:
+
+#### Extract all ROCm code objects from a list of executables
+    roc-obj executable...
+
+#### Extract all ROCm code objects from a list of executables, and disassemble them
+    roc-obj --disassemble executable...
+    # or
+    roc-obj -d executable...
+
+#### Extract all ROCm code objects from a list of executables into dir/
+    roc-obj --outdir dir/ executable...
+    # or
+    roc-obj -o dir/ executable...
+
+#### Extract only ROCm code objects matching regex over Target ID
+    roc-obj --grep gfx9 executable...
+    # or
+    roc-obj -g gfx9 executable...
+
+## Low-Level Tooling
+
+### URI syntax:
 
   ROCm Code Objects can be listed/accessed using the following URI syntax:
 ```
@@ -17,8 +46,7 @@ ROCm compiler generated code objects (executables, object files, and shared obje
   Example: file://dir1/dir2/hello_world#offset=133&size=14472
            memory://1234#offset=0x20000&size=3000
 
-
-## List available ROCm Code Objects: rocm-obj-ls
+### List available ROCm Code Objects: rocm-obj-ls
 
   Use this tool to list available ROCm code objects.  Code objects are listed using URI syntax.
 
@@ -28,7 +56,7 @@ ROCm compiler generated code objects (executables, object files, and shared obje
     -h Show this help message
 
 
-## Extract ROCm Code Objects: rocm-obj-extract
+### Extract ROCm Code Objects: rocm-obj-extract
 
   Extracts available ROCm code objects from specified URI.
 
@@ -44,24 +72,24 @@ ROCm compiler generated code objects (executables, object files, and shared obje
   Note, when specifying a URI argument to roc-obj-extract, if cut and pasting the output from roc-obj-ls you need to escape the '&' character or your shell will interpret it as the option to run the command as a background process.
   As an example, if roc-obj-ls generates a URI like this ```file://my_exe#offset=24576&size=46816xxi```, you need to use the following argument to roc-obj-extract: ```file://my_exe#offset=24576\&size=46816```
 
-## Examples:
+### Examples:
 
-### Dump all code objects to current directory:
+#### Dump all code objects to current directory:
     roc-obj-ls <exe> | roc-obj-extract
 
-### Dump the ISA for gfx906:
-    roc-obj-ls -v <exe> | grep "gfx906" | awk '{print $2}' | roc-obj-extract -o - | llvm-objdump -d - > <exe>.gfx906.isa
+#### Dump the ISA for gfx906:
+    roc-obj-ls -v <exe> | awk '/gfx906/{print $2}' | roc-obj-extract -o - | llvm-objdump -d - > <exe>.gfx906.isa
 
-### Check the e_flags of the gfx908 code object:
-    roc-obj-ls -v <exe> | grep "gfx908" | awk '{print $2}' | roc-obj-extract -o - | llvm-readelf -h - | grep Flags
+#### Check the e_flags of the gfx908 code object:
+    roc-obj-ls -v <exe> | awk '/gfx908/{print $2}' | roc-obj-extract -o - | llvm-readelf -h - | grep Flags
 
-### Disassemble the fourth code object:
+#### Disassemble the fourth code object:
     roc-obj-ls <exe> | sed -n 4p | roc-obj-extract -o - | llvm-objdump -d -
 
-### Sort embedded code objects by size:
+#### Sort embedded code objects by size:
     for uri in $(roc-obj-ls <exe>); do printf "%d: %s\n" "$(roc-obj-extract -o - "$uri" | wc -c)" "$uri"; done | sort -n
 
-### Compare disassembly of gfx803 and gfx900 code objects:
+#### Compare disassembly of gfx803 and gfx900 code objects:
     dis() { roc-obj-ls -v <exe> | grep "$1" | awk '{print $2}' | roc-obj-extract -o - | llvm-objdump -d -; }
     diff <(dis gfx803) <(dis gfx900)