[clang] [docs] Fix markdown migration defects in the user manual (PR #210785)
Reid Kleckner via cfe-commits
cfe-commits at lists.llvm.org
Wed Jul 22 13:49:51 PDT 2026
================
@@ -3591,166 +3455,160 @@ its GCC counterpart, it *does not* handle profile formats produced by GCC.
Both `-fprofile-use` and `-fprofile-instr-use` accept profiles in the
indexed format, regardeless whether it is produced by frontend or the IR pass.
-```{eval-rst}
-.. option:: -fprofile-generate[=<dirname>]
-
- The ``-fprofile-generate`` and ``-fprofile-generate=`` flags will use
- an alternative instrumentation method for profile generation. When
- given a directory name, it generates the profile file
- ``default_%m.profraw`` in the directory named ``dirname`` if specified.
- If ``dirname`` does not exist, it will be created at runtime. ``%m`` specifier
- will be substituted with a unique id documented in step 2 above. In other words,
- with ``-fprofile-generate[=<dirname>]`` option, the "raw" profile data automatic
- merging is turned on by default, so there will no longer any risk of profile
- clobbering from different running processes. For example,
-
- .. code-block:: console
-
- $ clang++ -O2 -fprofile-generate=yyy/zzz code.cc -o code
-
- When ``code`` is executed, the profile will be written to the file
- ``yyy/zzz/default_xxxx.profraw``.
+:::{option} -fprofile-generate[=<dirname>]
- To generate the profile data file with the compiler readable format, the
- ``llvm-profdata`` tool can be used with the profile directory as the input:
+The `-fprofile-generate` and `-fprofile-generate=` flags will use
+an alternative instrumentation method for profile generation. When
+given a directory name, it generates the profile file
+`default_%m.profraw` in the directory named `dirname` if specified.
+If `dirname` does not exist, it will be created at runtime. `%m` specifier
+will be substituted with a unique id documented in step 2 above. In other words,
+with `-fprofile-generate[=<dirname>]` option, the "raw" profile data automatic
+merging is turned on by default, so there will no longer any risk of profile
+clobbering from different running processes. For example,
- .. code-block:: console
-
- $ llvm-profdata merge -output=code.profdata yyy/zzz/
-
- If the user wants to turn off the auto-merging feature, or simply override the
- the profile dumping path specified at command line, the environment variable
- ``LLVM_PROFILE_FILE`` can still be used to override
- the directory and filename for the profile file at runtime.
- To override the path and filename at compile time, use
- ``-Xclang -fprofile-instrument-path=/path/to/file_pattern.profraw``.
+```console
+$ clang++ -O2 -fprofile-generate=yyy/zzz code.cc -o code
```
-```{eval-rst}
-.. option:: -fcs-profile-generate[=<dirname>]
-
- The ``-fcs-profile-generate`` and ``-fcs-profile-generate=`` flags will use
- the same instrumentation method, and generate the same profile as in the
- ``-fprofile-generate`` and ``-fprofile-generate=`` flags. The difference is
- that the instrumentation is performed after inlining so that the resulted
- profile has a better context sensitive information. They cannot be used
- together with ``-fprofile-generate`` and ``-fprofile-generate=`` flags.
- They are typically used in conjunction with ``-fprofile-use`` flag.
- The profile generated by ``-fcs-profile-generate`` and ``-fprofile-generate``
- can be merged by llvm-profdata. A use example:
+When `code` is executed, the profile will be written to the file
+`yyy/zzz/default_xxxx.profraw`.
- .. code-block:: console
+To generate the profile data file with the compiler readable format, the
+`llvm-profdata` tool can be used with the profile directory as the input:
- $ clang++ -O2 -fprofile-generate=yyy/zzz code.cc -o code
- $ ./code
- $ llvm-profdata merge -output=code.profdata yyy/zzz/
-
- The first few steps are the same as that in ``-fprofile-generate``
- compilation. Then perform a second round of instrumentation.
-
- .. code-block:: console
-
- $ clang++ -O2 -fprofile-use=code.profdata -fcs-profile-generate=sss/ttt \
- -o cs_code
- $ ./cs_code
- $ llvm-profdata merge -output=cs_code.profdata sss/ttt code.profdata
+```console
+$ llvm-profdata merge -output=code.profdata yyy/zzz/
+```
- The resulted ``cs_code.prodata`` combines ``code.profdata`` and the profile
- generated from binary ``cs_code``. Profile ``cs_code.profata`` can be used by
- ``-fprofile-use`` compilation.
+If the user wants to turn off the auto-merging feature, or simply override the
+the profile dumping path specified at command line, the environment variable
+`LLVM_PROFILE_FILE` can still be used to override
+the directory and filename for the profile file at runtime.
+To override the path and filename at compile time, use
+`-Xclang -fprofile-instrument-path=/path/to/file_pattern.profraw`.
+:::
- .. code-block:: console
+:::{option} -fcs-profile-generate[=<dirname>]
- $ clang++ -O2 -fprofile-use=cs_code.profdata
+The `-fcs-profile-generate` and `-fcs-profile-generate=` flags will use
+the same instrumentation method, and generate the same profile as in the
+`-fprofile-generate` and `-fprofile-generate=` flags. The difference is
+that the instrumentation is performed after inlining so that the resulted
+profile has a better context sensitive information. They cannot be used
+together with `-fprofile-generate` and `-fprofile-generate=` flags.
+They are typically used in conjunction with `-fprofile-use` flag.
+The profile generated by `-fcs-profile-generate` and `-fprofile-generate`
+can be merged by llvm-profdata. A use example:
- The above command will read both profiles to the compiler at the identical
- point of instrumentations.
+```console
+$ clang++ -O2 -fprofile-generate=yyy/zzz code.cc -o code
+$ ./code
+$ llvm-profdata merge -output=code.profdata yyy/zzz/
```
-```{eval-rst}
-.. option:: -fprofile-use[=<pathname>]
+The first few steps are the same as that in `-fprofile-generate`
+compilation. Then perform a second round of instrumentation.
- Without any other arguments, ``-fprofile-use`` behaves identically to
- ``-fprofile-instr-use``. Otherwise, if ``pathname`` is the full path to a
- profile file, it reads from that file. If ``pathname`` is a directory name,
- it reads from ``pathname/default.profdata``.
+```console
+$ clang++ -O2 -fprofile-use=code.profdata -fcs-profile-generate=sss/ttt \
+ -o cs_code
+$ ./cs_code
+$ llvm-profdata merge -output=cs_code.profdata sss/ttt code.profdata
```
-```{eval-rst}
-.. option:: -fprofile-update[=<method>]
+The resulted `cs_code.prodata` combines `code.profdata` and the profile
+generated from binary `cs_code`. Profile `cs_code.profata` can be used by
+`-fprofile-use` compilation.
- Unless ``-fsanitize=thread`` is specified, the default is ``single``, which
- uses non-atomic increments. The counters can be inaccurate under thread
- contention. ``atomic`` uses atomic increments which is accurate but has
- overhead. ``prefer-atomic`` will be transformed to ``atomic`` when supported
- by the target, or ``single`` otherwise.
+```console
+$ clang++ -O2 -fprofile-use=cs_code.profdata
```
-```{eval-rst}
-.. option:: -fprofile-continuous
+The above command will read both profiles to the compiler at the identical
+point of instrumentations.
+:::
- Enables the continuous instrumentation profiling where profile counter updates
- are continuously synced to a file. This option sets any necessary modifiers
- (currently ``%c``) in the default profile filename and passes any necessary
- flags to the middle-end to support this mode. Value profiling is not supported
- in continuous mode.
+:::{option} -fprofile-use[=<pathname>]
- .. code-block:: console
+Without any other arguments, `-fprofile-use` behaves identically to
+`-fprofile-instr-use`. Otherwise, if `pathname` is the full path to a
+profile file, it reads from that file. If `pathname` is a directory name,
+it reads from `pathname/default.profdata`.
+:::
- $ clang++ -O2 -fprofile-generate -fprofile-continuous code.cc -o code
+:::{option} -fprofile-update[=<method>]
- Running ``./code`` will collect the profile and write it to the
- ``default_xxxx.profraw`` file. However, if ``./code`` abruptly terminates or
- does not call ``exit()``, in continuous mode the profile collected up to the
- point of termination will be available in ``default_xxxx.profraw`` while in
- the non-continuous mode, no profile file is generated.
-```
+Unless `-fsanitize=thread` is specified, the default is `single`, which
+uses non-atomic increments. The counters can be inaccurate under thread
+contention. `atomic` uses atomic increments which is accurate but has
+overhead. `prefer-atomic` will be transformed to `atomic` when supported
+by the target, or `single` otherwise.
+:::
-```{eval-rst}
-.. option:: -ftemporal-profile
+:::{option} -fprofile-continuous
- Enables the temporal profiling extension for IRPGO to improve startup time by
- reducing ``.text`` section page faults. To do this, we instrument function
- timestamps to measure when each function is called for the first time and use
- this data to generate a function order to improve startup.
+Enables the continuous instrumentation profiling where profile counter updates
+are continuously synced to a file. This option sets any necessary modifiers
+(currently `%c`) in the default profile filename and passes any necessary
+flags to the middle-end to support this mode. Value profiling is not supported
+in continuous mode.
- The profile is generated as normal.
+```console
+$ clang++ -O2 -fprofile-generate -fprofile-continuous code.cc -o code
+```
- .. code-block:: console
+Running `./code` will collect the profile and write it to the
+`default_xxxx.profraw` file. However, if `./code` abruptly terminates or
+does not call `exit()`, in continuous mode the profile collected up to the
+point of termination will be available in `default_xxxx.profraw` while in
+the non-continuous mode, no profile file is generated.
+:::
- $ clang++ -O2 -fprofile-generate -ftemporal-profile code.cc -o code
- $ ./code
- $ llvm-profdata merge -o code.profdata yyy/zzz
+:::{option} -ftemporal-profile
- Using the resulting profile, we can generate a function order to pass to the
- linker via ``--symbol-ordering-file`` for ELF or ``-order_file`` for Mach-O.
+Enables the temporal profiling extension for IRPGO to improve startup time by
+reducing `.text` section page faults. To do this, we instrument function
+timestamps to measure when each function is called for the first time and use
+this data to generate a function order to improve startup.
- .. code-block:: console
+The profile is generated as normal.
- $ llvm-profdata order code.profdata -o code.orderfile
- $ clang++ -O2 -Wl,--symbol-ordering-file=code.orderfile code.cc -o code
+```console
+$ clang++ -O2 -fprofile-generate -ftemporal-profile code.cc -o code
+$ ./code
+$ llvm-profdata merge -o code.profdata yyy/zzz
+```
- Or the profile can be passed to LLD directly.
+Using the resulting profile, we can generate a function order to pass to the
+linker via `--symbol-ordering-file` for ELF or `-order_file` for Mach-O.
- .. code-block:: console
+```console
+$ llvm-profdata order code.profdata -o code.orderfile
+$ clang++ -O2 -Wl,--symbol-ordering-file=code.orderfile code.cc -o code
+```
- $ clang++ -O2 -fuse-ld=lld -Wl,--irpgo-profile=code.profdata,--bp-startup-sort=function code.cc -o code
+Or the profile can be passed to LLD directly.
- For more information, please read the RFC:
- https://discourse.llvm.org/t/rfc-temporal-profiling-extension-for-irpgo/68068
+```console
+$ clang++ -O2 -fuse-ld=lld -Wl,--irpgo-profile=code.profdata,--bp-startup-sort=function code.cc -o code
```
+For more information, please read the RFC:
+https://discourse.llvm.org/t/rfc-temporal-profiling-extension-for-irpgo/68068
+:::
+
#### Fine Tuning Profile Collection
The PGO infrastructure provides user program knobs to fine tune profile
collection. Specifically, the PGO runtime provides the following functions
that can be used to control the regions in the program where profiles should
be collected.
-> - `void __llvm_profile_set_filename(const char *Name)`: changes the name of
-> the profile file to `Name`.
-> - `void __llvm_profile_reset_counters(void)`: resets all counters to zero.
-> - `int __llvm_profile_dump(void)`: write the profile data to disk.
+- `void __llvm_profile_set_filename(const char *Name)`: changes the name of
----------------
rnk wrote:
This was an intentional change. The blockquotes were inserted by rst2myst, for cases like this:
```
❯ echo '
lorum ipsump
* bullet1
* bullet2
' |
../../venv/bin/rst2myst stream -
lorum ipsump
> - bullet1
> - bullet2
```
I missed them when this landed, and this change is a follow-up to remove the blockquotes that we don't need or want.
https://github.com/llvm/llvm-project/pull/210785
More information about the cfe-commits
mailing list