NAME

       llvm-remarkutil - Remark utility

SYNOPSIS

       llvm-remarkutil [subcommmand] [options]

DESCRIPTION

       Utility for displaying information from, and converting between different remark formats.

SUBCOMMANDS

          • bitstream2yaml - Reserialize bitstream remarks to YAML.

          • yaml2bitstream - Reserialize YAML remarks to bitstream.

          • instruction-count - Output function instruction counts.

          • annotation-count - Output remark type count from annotation remarks.

          • size-diff - Compute diff in size remarks.

   bitstream2yaml
       USAGE: llvm-remarkutil bitstream2yaml <input file> -o <output file>

   Summary
       Takes a bitstream remark file as input, and reserializes that file as YAML.

   yaml2bitstream
       USAGE: llvm-remarkutil yaml2bitstream <input file> -o <output file>

   Summary
       Takes a YAML remark file as input, and reserializes that file in the bitstream format.

   instruction-count
       USAGE:    llvm-remarkutil   instruction-count   <input   file>   --parser=<bitstream|yaml>
       [--use-debug-loc] -o <output file>

   Summary
       Outputs instruction count remarks for every function. Instruction count remarks encode the
       number of instructions in a function at assembly printing time.

       Instruction count remarks require asm-printer remarks.

       CSV format is as follows:

       ::     Function,InstructionCount foo,123

       if  --use-debug-loc  is  passed then the CSV will include the source path, line number and
       column.

       ::     Source,Function,InstructionCount path:line:column,foo,3

   annotation-count
       USAGE:   llvm-remarkutil   annotation-count   <input    file>    --parser=<bitstream|yaml>
       --annotation-type=<type>  [--use-debug-loc] -o <output file>

   Summary
       Outputs  a count for annotation-type <type> remark for every function. The count expresses
       the number of remark checks inserted at the function.

       Annotation count remarks require AnnotationRemarksPass remarks.

       CSV format is as follows:

       ::     Function,Count foo,123

       if --use-debug-loc is passed then the CSV will include the source path,  line  number  and
       column.

       ::     Source,Function,Count path:line:column,foo,3

   count
       ..program:: llvm-remarkutil count

       USAGE: llvm-remarkutil count [options] <input file>

   Summary
       llvm-remarkutil   count   counts  remarks  <https://llvm.org/docs/Remarks.html>  based  on
       specified properties.  By default the tool counts remarks based on how  many  occur  in  a
       source  file  or  function or total for the generated remark file.  The tool also supports
       collecting count based on specific remark arguments. The specified arguments  should  have
       an integer value to be able to report a count.

       The  tool  contains  utilities to filter the remark count based on remark name, pass name,
       argument value and remark type.  OPTIONS -------

       --parser=<yaml|bitstream>
              Select the type of input remark parser. Required.  * yaml: The tool will parse YAML
              remarks.  * bitstream: The tool will parse bitstream remarks.

       --count-by<value>

       Select option to collect remarks by.

       * ``remark-name``: count how many individual remarks exist.

       *  ``arg``:  count  remarks based on specified arguments passed by --(r)args. The argument
       value must be a number.

       --group-by=<value>

       group count of remarks by property.

       * ``source``: Count will be collected per source path. Remarks with no debug location will
       not be counted.

       * ``function``: Count is collected per function.

       * ``function-with-loc``: Count is collected per function per source. Remarks with no debug
       location will not be counted.

       * ``Total``: Report a count for the provided remark file.

       --args[=arguments]

       If `count-by` is set to `arg` this flag can be  used  to  collect  from  specified  remark
       arguments represented as a comma separated string.

       The arguments must have a numeral value to be able to count remarks by

       --rargs[=arguments]

       If  `count-by`  is  set  to  `arg`  this flag can be used to collect from specified remark
       arguments using regular expression.

       The arguments must have a numeral value to be able to count remarks by

       --pass-name[=<string>]

       Filter count by pass name.

       --rpass-name[=<string>]

       Filter count by pass name using regular expressions.

       --remark-name[=<string>]

       Filter count by remark name.

       --rremark-name[=<string>]

       Filter count by remark name using regular expressions.

       --filter-arg-by[=<string>]

       Filter count by argument value.

       --rfilter-arg-by[=<string>]

       Filter count by argument value using regular expressions.

       --remark-type=<value>

       Filter remarks by type with the following options.

       * ``unknown``

       * ``passed``

       * ``missed``

       * ``analysis``

       * ``analysis-fp-commute``

       * ``analysis-aliasing``

       * ``failure``

   size-diff
       USAGE: llvm-remarkutil size-diff [options] file_a file_b --parser parser

   Summary
       llvm-remarkutil size-diff diffs size remarks in two remark files: file_a and file_b.

       llvm-remarkutil size-diff can be used to gain insight into which functions  were  impacted
       the most by code generation changes.

       In  most  common  use-cases  file_a and file_b will be remarks output by compiling a fixed
       source with differing compilers or differing optimization settings.

       llvm-remarkutil size-diff handles both YAML and bitstream remarks.

OPTIONS

       --parser=<yaml|bitstream>
              Select the type of input remark parser. Required.  * yaml: The tool will parse YAML
              remarks.  * bitstream: The tool will parse bitstream remarks.

       --report-style=<human|json>
              Output  style.   *  human:  Human-readable textual report. Default option.  * json:
              JSON report.

       --pretty
              Pretty-print JSON output. Optional.

              If output is not set to JSON, this does nothing.

       -o=<file>
              Output file for the report. Outputs to stdout by default.

HUMAN-READABLE OUTPUT

       The human-readable format for llvm-remarkutil size-diff is composed of two sections:

       • Per-function changes.

       • A high-level summary of all changes.

   Changed Function Section
       Suppose you are comparing two remark files OLD and NEW.

       For each function with a  changed  instruction  count  in  OLD  and  NEW,  llvm-remarkutil
       size-diff will emit a line like below:

          (++|--|==) (>|<) function_name, N instrs, M stack B

       A breakdown of the format is below:

       (++|--|==)
              Which of OLD and NEW the function_name is present in.

              • ++: Only in NEW. ("Added")

              • --: Only in OLD. ("Removed")

              • ==: In both.

       (>|<)  Denotes  if function_name has more instructions or fewer instructions in the second
              file.

              • >: More instructions in second file than first file.

              • <: Fewer instructions in second file than in first file.

       function_name
              The name of the changed function.

       N instrs
              Second file instruction count - first file instruction count.

       M stack B
              Second file stack byte count - first file stack byte count.

   Summary Section
       llvm-remarkutil size-diff will output a high-level  summary  after  printing  all  changed
       functions.

          instruction count: N (inst_pct_change%)
          stack byte usage: M (sb_pct_change%)

       N      Sum of all instruction count changes between the second and first file.

       inst_pct_change%
              Percent  increase  or  decrease  in  instruction count between the second and first
              file.

       M      Sum of all stack byte count changes between the second and first file.

       sb_pct_change%
              Percent increase or decrease in stack byte usage between the second and first file.

JSON OUTPUT

   High-Level view
       Suppose we are comparing two files, OLD and NEW.

       llvm-remarkutil size-diff will output JSON as follows.

          "Files": [
            "A": "path/to/OLD",
            "B": "path/to/NEW"
          ]

          "InBoth": [
            ...
          ],

          "OnlyInA": [
            ...
          ],

          "OnlyInB": [
            ...
          ]

       Files  Original paths to remark files.

              • A: Path to the first file.

              • B: Path to the second file.

       InBoth Functions present in both files.

       OnlyInA
              Functions only present in the first file.

       OnlyInB
              Functions only present in the second file.

   Function JSON
       The InBoth, OnlyInA, and OnlyInB sections contain size information for  each  function  in
       the input remark files.

          {
            "FunctionName" : "function_name"
            "InstCount": [
                INST_COUNT_A,
                INST_COUNT_B
              ],
            "StackSize": [
                STACK_BYTES_A,
                STACK_BYTES_B
              ],
          }

       FunctionName
              Name of the function.

       InstCount
              Instruction counts for the function.

              • INST_COUNT_A: Instruction count in OLD.

              • INST_COUNT_B: Instruction count in NEW.

       StackSize
              Stack byte counts for the function.

              • STACK_BYTES_A: Stack bytes in OLD.

              • STACK_BYTES_B: Stack bytes in NEW.

   Computing Diffs From Function JSON
       Function JSON does not contain the diffs. Tools consuming JSON output from llvm-remarkutil
       size-diff are responsible for computing the diffs separately.

       To compute the diffs:

       • Instruction count diff: INST_COUNT_B - INST_COUNT_A

       • Stack byte count diff: STACK_BYTES_B - STACK_BYTES_A

EXIT STATUS

       llvm-remarkutil size-diff returns 0 on success, and a non-zero value otherwise.

AUTHOR

       Maintained by the LLVM Team (https://llvm.org/).

COPYRIGHT

       2003-2024, LLVM Project