[llvm] ef403f9 - [CGData] Document for llvm-cgdata (#106320)

[via llvm-commits]

Author: Kyungwoo Lee
Date: 2024-08-28T11:02:00-07:00
New Revision: ef403f9a64f33ae3b1ad51bf67476391d18ff390

URL: https://github.com/llvm/llvm-project/commit/ef403f9a64f33ae3b1ad51bf67476391d18ff390
DIFF: https://github.com/llvm/llvm-project/commit/ef403f9a64f33ae3b1ad51bf67476391d18ff390.diff

LOG: [CGData] Document for llvm-cgdata (#106320)

This is a follow-up for
https://github.com/llvm/llvm-project/pull/101461.

This is a patch for
https://discourse.llvm.org/t/rfc-enhanced-machine-outliner-part-2-thinlto-nolto/78753.

Added: 
    llvm/docs/CommandGuide/llvm-cgdata.rst

Modified: 
    llvm/docs/CommandGuide/index.rst

Removed: 
    


################################################################################
diff  --git a/llvm/docs/CommandGuide/index.rst b/llvm/docs/CommandGuide/index.rst
index 0dbb5f40f10f00..643951eca2a260 100644
--- a/llvm/docs/CommandGuide/index.rst
+++ b/llvm/docs/CommandGuide/index.rst
@@ -18,6 +18,7 @@ Basic Commands
    llc
    lli
    llvm-as
+   llvm-cgdata
    llvm-config
    llvm-cov
    llvm-cxxmap

diff  --git a/llvm/docs/CommandGuide/llvm-cgdata.rst b/llvm/docs/CommandGuide/llvm-cgdata.rst
new file mode 100644
index 00000000000000..f592e1508844ee
--- /dev/null
+++ b/llvm/docs/CommandGuide/llvm-cgdata.rst
@@ -0,0 +1,68 @@
+llvm-cgdata - LLVM CodeGen Data Tool
+====================================
+
+.. program:: llvm-cgdata
+
+SYNOPSIS
+--------
+
+:program:`llvm-cgdata` [**commands**] [**options**] (<binaries>|<.cgdata>)
+
+DESCRIPTION
+-----------
+
+The :program:llvm-cgdata utility parses raw codegen data embedded
+in compiled binary files and merges them into a single .cgdata file.
+It can also inspect and manipulate .cgdata files.
+Currently, the tool supports saving and restoring outlined hash trees,
+enabling global function outlining across modules, allowing for more
+efficient function outlining in subsequent compilations.
+The design is extensible, allowing for the incorporation of additional
+codegen summaries and optimization techniques, such as global function
+merging, in the future.
+
+COMMANDS
+--------
+
+At least one of the following commands are required:
+
+.. option:: --convert
+
+  Convert a .cgdata file from one format to another.
+
+.. option:: --merge
+
+  Merge multiple raw codgen data in binaries into a single .cgdata file.
+
+.. option:: --show
+
+  Show summary information about a .cgdata file.
+
+OPTIONS
+-------
+
+:program:`llvm-cgdata` supports the following options:
+
+.. option:: --format=[text|binary]
+
+  Specify the format of the output .cgdata file.
+
+.. option:: --output=<string>
+
+  Specify the output file name.
+
+.. option:: --cgdata-version
+
+  Print the version of the llvm-cgdata tool.
+
+EXAMPLES
+--------
+
+To convert a .cgdata file from binary to text format:
+    $ llvm-cgdata --convert --format=text input.cgdata --output=output.data
+
+To merge multiple raw codegen data in object files into a single .cgdata file:
+    $ llvm-cgdata --merge file1.o file2.o --output=merged.cgdata
+
+To show summary information about a .cgdata file:
+    $ llvm-cgdata --show input.cgdata