llvm-remarkutil - Remark utility

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

       2003-2025, LLVM Project

15                                                 2025-02-12                                 LLVM-REMARKUTIL(1)

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

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

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

       • Per-function changes.

       • A high-level summary of all changes.

   ChangedFunctionSection
       Suppose you are comparing two remark files OLD and NEW.

       For each function with a changedinstructioncount in OLD and NEW, llvm-remarkutilsize-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.

       Ninstrs
              Second file instruction count - first file instruction count.

       MstackB
              Second file stack byte count - first file stack byte count.

   SummarySectionllvm-remarkutilsize-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.

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

       llvm-remarkutilsize-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.

   FunctionJSON
       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.

   ComputingDiffsFromFunctionJSON
       Function JSON does not contain the diffs. Tools consuming JSON output from llvm-remarkutilsize-diff  are
       responsible for computing the diffs separately.

       Tocomputethediffs:

       • Instruction count diff: INST_COUNT_B-INST_COUNT_A

       • Stack byte count diff: STACK_BYTES_B-STACK_BYTES_A

       llvm-remarkutil - Remark utility

--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.

          • 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>

   Summaryllvm-remarkutilcount 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>Selectoptiontocollectremarksby.*``remark-name``:counthowmanyindividualremarksexist.*``arg``:countremarksbasedonspecifiedargumentspassedby--(r)args.Theargumentvaluemustbeanumber.--group-by=<value>groupcountofremarksbyproperty.*``source``:Countwillbecollectedpersourcepath.Remarkswithnodebuglocationwillnotbecounted.*``function``:Countiscollectedperfunction.*``function-with-loc``:Countiscollectedperfunctionpersource.Remarkswithnodebuglocationwillnotbecounted.*``Total``:Reportacountfortheprovidedremarkfile.--args[=arguments]If`count-by`issetto`arg`thisflagcanbeusedtocollectfromspecifiedremarkargumentsrepresentedasacommaseparatedstring.Theargumentsmusthaveanumeralvaluetobeabletocountremarksby--rargs[=arguments]If`count-by`issetto`arg`thisflagcanbeusedtocollectfromspecifiedremarkargumentsusingregularexpression.Theargumentsmusthaveanumeralvaluetobeabletocountremarksby--pass-name[=<string>]Filtercountbypassname.--rpass-name[=<string>]Filtercountbypassnameusingregularexpressions.--remark-name[=<string>]Filtercountbyremarkname.--rremark-name[=<string>]Filtercountbyremarknameusingregularexpressions.--filter-arg-by[=<string>]Filtercountbyargumentvalue.--rfilter-arg-by[=<string>]Filtercountbyargumentvalueusingregularexpressions.--remark-type=<value>Filterremarksbytypewiththefollowingoptions.*``unknown``*``passed``*``missed``*``analysis``*``analysis-fp-commute``*``analysis-aliasing``*``failure``size-diff
       USAGE: llvm-remarkutil size-diff [options] file_afile_b--parserparserSummaryllvm-remarkutilsize-diff diffs size remarks in two remark files: file_a and file_b.

       llvm-remarkutilsize-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  fixedsource  with
       differingcompilers or differingoptimizationsettings.

       llvm-remarkutilsize-diff handles both YAML and bitstream remarks.

llvm-remarkutil [subcommmand] [options]