Skip to content

Commit 960d22f

Browse files
author
Colin Robertson
committed
Initial clean-up pass of existing PGO topics
1 parent 23447d3 commit 960d22f

11 files changed

Lines changed: 405 additions & 352 deletions

‎docs/build/reference/environment-variables-for-profile-guided-optimizations.md‎

Lines changed: 54 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -1,32 +1,67 @@
11
---
22
title: "Environment Variables for Profile-Guided Optimizations | Microsoft Docs"
33
ms.custom: ""
4-
ms.date: "11/04/2016"
5-
ms.reviewer: ""
6-
ms.suite: ""
4+
ms.date: "03/14/2018"
75
ms.technology: ["cpp-tools"]
8-
ms.tgt_pltfrm: ""
9-
ms.topic: "article"
6+
ms.topic: "reference"
107
dev_langs: ["C++"]
118
helpviewer_keywords: ["profile-guided optimizations, environment variables"]
129
ms.assetid: f95a6d1e-49a4-4802-a144-092026b600a3
13-
caps.latest.revision: 6
1410
author: "corob-msft"
1511
ms.author: "corob"
1612
manager: "ghogen"
1713
ms.workload: ["cplusplus"]
1814
---
1915
# Environment Variables for Profile-Guided Optimizations
20-
This section contains information about environment variables that affect test scenarios on an image created with /LTCG:PGI.
21-
22-
## Remarks
23-
There are three environment variables that affect test scenarios for profile-guided optimizations:
24-
25-
- [PogoSafeMode](../../build/reference/pogosafemode.md)
26-
27-
- [VCPROFILE_ALLOC_SCALE](../../build/reference/vcprofile-alloc-scale.md)
28-
29-
- [VCPROFILE_PATH](../../build/reference/vcprofile-path.md)
30-
31-
## See Also
32-
[Tools for Manual Profile-Guided Optimization](../../build/reference/tools-for-manual-profile-guided-optimization.md)
16+
17+
There are three environment variables that affect test scenarios on an image created with /LTCG:PGI for profile-guided optimizations:
18+
19+
- **PogoSafeMode** specifies whether to use fast mode or safe mode for application profiling.
20+
21+
- **VCPROFILE_ALLOC_SCALE** adds additional memory for use by the profiler.
22+
23+
- **VCPROFILE_PATH** lets you specify the folder used for .pgc files.
24+
25+
## PogoSafeMode
26+
27+
Clear or set the PogoSafeMode environment variable to specify whether to use fast mode or safe mode for application profiling on x86 systems.
28+
29+
Profile-guided optimization (PGO) has two possible modes during the profiling phase: *fast mode* and *safe mode*. When profiling is in fast mode, it uses the **INC** instruction to increase data counters. The **INC** instruction is faster but is not thread-safe. When profiling is in safe mode, it uses the **LOCK INC** instruction to increase data counters. The **LOCK INC** instruction has the same functionality as the **INC** instruction has, and is thread-safe, but it is slower than the **INC** instruction.
30+
31+
By default, PGO profiling operates in fast mode. **PogoSafeMode** is only required if you want to use safe mode.
32+
33+
To run PGO profiling in safe mode, you must either use the environment variable **PogoSafeMode** or the linker switch **/PogoSafeMode**, depending on the system. If you are performing the profiling on an x64 computer, you must use the linker switch. If you are performing the profiling on an x86 computer, you may use the linker switch or set the **PogoSafeMode** environment variable to any value before you start the optimization process.
34+
35+
### PogoSafeMode syntax
36+
37+
> **set PogoSafeMode**[**=**_value_]
38+
39+
Set **PogoSafeMode** to any value to enable safe mode. Set without a value to clear a previous value and re-enable fast mode.
40+
41+
## VCPROFILE_ALLOC_SCALE
42+
43+
Modify the **VCPROFILE_ALLOC_SCALE** environment variable to change the amount of memory allocated to hold the profile data. In rare cases, there will not be enough memory available to support gathering profile data when running test scenarios. In those cases, you can increase the amount of memory by setting **VCPROFILE_ALLOC_SCALE**. If you receive an error message during a test run that indicates that you have insufficient memory, assign a larger value to **VCPROFILE_ALLOC_SCALE**, until the test runs complete with no out-of-memory errors.
44+
45+
### VCPROFILE_ALLOC_SCALE syntax
46+
47+
> **set VCPROFILE_ALLOC_SCALE**[__=__*scale_value*]
48+
49+
The *scale_value* parameter is a scaling factor for the amount of memory you want for running test scenarios. The default is 1. For example, this command line sets the scale factor to 2:
50+
51+
`set VCPROFILE_ALLOC_SCALE=2`
52+
53+
## VCPROFILE_PATH
54+
55+
Use the **VCPROFILE_PATH** environment variable to specify the directory to create .pgc files. By default, .pgc files are created in the same directory as the binary being profiled. However, if the absolute path of the binary does not exist, as may be the case when you run profile scenarios on a different machine from where the binary was built, you can set **VCPROFILE_PATH** to a path that exists on the target machine.
56+
57+
### VCPROFILE_PATH syntax
58+
59+
> **set VCPROFILE_PATH**[**=**_path_]
60+
61+
Set the *path* parameter to the directory path in which to add .pgc files. For example, this command line sets the folder to C:\profile:
62+
63+
`set VCPROFILE_PATH=c:\profile`
64+
65+
## See also
66+
67+
[Tools for Manual Profile-Guided Optimization](../../build/reference/tools-for-manual-profile-guided-optimization.md)

‎docs/build/reference/how-to-merge-multiple-pgo-profiles-into-a-single-profile.md‎

Lines changed: 28 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -17,39 +17,32 @@ manager: "ghogen"
1717
ms.workload: ["cplusplus"]
1818
---
1919
# How to: Merge Multiple PGO Profiles into a Single Profile
20-
Profile-guided optimization (PGO) is a great tool for creating optimized binaries based on a scenario that is profiled. But what if you have an application that has several important, yet distinct scenarios; how do you create a single profile that PGO can use from several different scenarios? In Visual Studio, the PGO Manager, Pgomgr.exe, does this job for you.
21-
22-
The syntax for merging profiles is:
23-
24-
```
25-
pgomgr /merge[:num] [.pgc_files] .pgd_files
26-
```
27-
28-
where `num` is an optional weight that is being used for this merge. Weights are commonly used if there are some scenarios that are more important than others or if there are scenarios that are to be run multiple times.
29-
20+
21+
Profile-guided optimization (PGO) is a great tool for creating optimized binaries based on a scenario that is profiled. But what if you have an application that has several important, yet distinct scenarios? How do you create a single profile that PGO can use from several different scenarios? In Visual Studio, the PGO Manager, [pgomgr.exe](pgomgr.md), does this job for you.
22+
23+
The syntax for merging profiles is:
24+
25+
`pgomgr /merge[:num] [.pgc_files] .pgd_files`
26+
27+
where `num` is an optional weight that is being used for this merge. Weights are commonly used if there are some scenarios that are more important than others or if there are scenarios that are to be run multiple times.
28+
3029
> [!NOTE]
31-
> The PGO Manager will not work with stale profile data. To merge a .pgc file into a .pgd file, the .pgc file must be generated by an executable which was created by the same link invocation that generated the .pgd file.
32-
33-
## Example
34-
In this example, the PGO Manager will add pgcFile.pgc to pgdFile.pgd six times.
35-
36-
```
37-
pgomgr /merge:6 pgcFile.pgc pgdFile.pgd
38-
```
39-
40-
## Example
41-
In this example, the PGO Manager will add pgcFile1.pgc and pgcFile2.pgc to pgdFile.pgd, two times for each .pgc file.
42-
43-
```
44-
pgomgr /merge:2 pgcFile1.pgc pgcFile2.pgc pgdFile.pgd
45-
```
46-
47-
## Example
48-
If the PGO Manager is run without a .pgc file it will search the local directory for all .pgc files that have the same name as the .pgd file appended with an exclamation mark (!) followed by arbitrary characters. If the local directory has files test.pgd, test!1.pgc, test2.pgc, and test!hello.pgc, and the following command is run from the local directory, then test!1.pgc and test!hello.pgc will be merged into test.pgd.
49-
50-
```
51-
pgomgr /merge test.pgd
52-
```
53-
54-
## See Also
55-
[Profile-Guided Optimizations](../../build/reference/profile-guided-optimizations.md)
30+
> The PGO Manager does not work with stale profile data. To merge a .pgc file into a .pgd file, the .pgc file must be generated by an executable which was created by the same link invocation that generated the .pgd file.
31+
32+
## Examples
33+
34+
In this example, the PGO Manager adds pgcFile.pgc to pgdFile.pgd six times:
35+
36+
`pgomgr /merge:6 pgcFile.pgc pgdFile.pgd`
37+
38+
In this example, the PGO Manager adds pgcFile1.pgc and pgcFile2.pgc to pgdFile.pgd, two times for each .pgc file:
39+
40+
`pgomgr /merge:2 pgcFile1.pgc pgcFile2.pgc pgdFile.pgd`
41+
42+
If the PGO Manager is run without a .pgc file, it searches the local directory for all .pgc files that have the same base name as the .pgd file followed by an exclamation mark (!) and then one or more arbitrary characters. For example, if the local directory has files test.pgd, test!1.pgc, test2.pgc, and test!hello.pgc, and the following command is run from the local directory, then test!1.pgc and test!hello.pgc will be merged into test.pgd.
43+
44+
`pgomgr /merge test.pgd`
45+
46+
## See also
47+
48+
[Profile-Guided Optimizations](../../build/reference/profile-guided-optimizations.md)

‎docs/build/reference/pgomgr.md‎

Lines changed: 53 additions & 61 deletions
Original file line numberDiff line numberDiff line change
@@ -1,75 +1,67 @@
11
---
22
title: "pgomgr | Microsoft Docs"
33
ms.custom: ""
4-
ms.date: "11/04/2016"
5-
ms.reviewer: ""
6-
ms.suite: ""
4+
ms.date: "03/14/2018"
75
ms.technology: ["cpp-tools"]
8-
ms.tgt_pltfrm: ""
9-
ms.topic: "article"
6+
ms.topic: "reference"
107
dev_langs: ["C++"]
118
helpviewer_keywords: ["pgomgr program", "profile-guided optimizations, pgomgr"]
129
ms.assetid: 74589126-df18-42c9-8739-26d60e148d6a
13-
caps.latest.revision: 18
1410
author: "corob-msft"
1511
ms.author: "corob"
1612
manager: "ghogen"
1713
ms.workload: ["cplusplus"]
1814
---
1915
# pgomgr
20-
Adds profile data from one or more .pgc files to the .pgd file.
21-
22-
## Syntax
23-
24-
```
25-
pgomgr [options] pgcfiles pgdfile
26-
```
27-
28-
#### Parameters
29-
`options`
30-
The following options can be specified to pgomgr:
31-
32-
**/help—**Displays available pgomgr options (short for /?).
33-
34-
**/clear—**Causes the .pgd file to be cleared of all profile information. You cannot specify a .pgc file when **/clear** is specified.
35-
36-
**/detail**—Displays detailed statistics, including flow graph coverage information.
37-
38-
**/summary**—Displays per-function statistics.
39-
40-
**/unique**—when used with **/summary**, causes decorated function names to display. The default, when /unique is not used, is for undecorated function names to be displayed.
41-
42-
**/merge**[**:***n*]**—**Causes the data in the .pgc file or files to be added to the .pgd file. The optional parameter, *n*, lets you specify hat the data should be added *n* times. For example, if a scenario would commonly be done 6 times, you can do it once in a test run and add it to the .pgd file six times with **pgomgr /merge:6**.
43-
44-
`pgcfiles`
45-
One or more .pgc files whose profile data you want to merge into the .pgd file. You can specify a single .pgc file or multiple .pgc files. If you do not specify any .pgc files, pgomgr will merge all .pgc files whose filenames are the same as the .pgd file.
46-
47-
`pgdfile`
48-
The .pgd file into which you are merging data from the .pgc file or files.
49-
50-
## Remarks
51-
16+
17+
Adds profile data from one or more .pgc files to the .pgd file.
18+
19+
## Syntax
20+
21+
> **pgomgr** [*options*] *pgcfiles* *pgdfile*
22+
23+
### Parameters
24+
25+
*options*<br/>
26+
The following options can be specified to **pgomgr**:
27+
28+
- **/help** or **/?** Displays available **pgomgr** options.
29+
30+
- **/clear** Causes the .pgd file to be cleared of all profile information. You cannot specify a .pgc file when **/clear** is specified.
31+
32+
- **/detail** Displays detailed statistics, including flow graph coverage information.
33+
34+
- **/summary** Displays per-function statistics.
35+
36+
- **/unique** When used with **/summary**, causes decorated function names to display. The default, when **/unique** is not used, is for undecorated function names to be displayed.
37+
38+
- **/merge**[**:***n*] Causes the data in the .pgc file or files to be added to the .pgd file. The optional parameter, *n*, lets you specify that the data should be added *n* times. For example, if a scenario would commonly be done six times to reflect how often it is done by customers, you can do it once in a test run and add it to the .pgd file six times with **pgomgr /merge:6**.
39+
40+
*pgcfiles*<br/>
41+
One or more .pgc files whose profile data you want to merge into the .pgd file. You can specify a single .pgc file or multiple .pgc files. If you do not specify any .pgc files, **pgomgr** merges all .pgc files whose filenames are the same as the .pgd file.
42+
43+
*pgdfile*
44+
The .pgd file into which you are merging data from the .pgc file or files.
45+
46+
## Remarks
47+
5248
> [!NOTE]
53-
> You can start this tool only from the [!INCLUDE[vsprvs](../../assembler/masm/includes/vsprvs_md.md)] command prompt. You cannot start it from a system command prompt or from File Explorer.
54-
55-
## Example
56-
In the following example, the .pgd file was cleared of profile data.
57-
58-
```
59-
pgomgr /clear myapp.pgd
60-
```
61-
62-
In the following example, the profile data in myapp1.pgc was added to the .pgd file 3 times.
63-
64-
```
65-
pgomgr /merge:3 myapp1.pgc myapp.pgd
66-
```
67-
68-
In the following example, profile data from all myapp#.pgc files is added to the myapp.pgd file.
69-
70-
```
71-
pgomgr -merge myapp1.pgd
72-
```
73-
74-
## See Also
75-
[Tools for Manual Profile-Guided Optimization](../../build/reference/tools-for-manual-profile-guided-optimization.md)
49+
> You can start this tool only from a Visual Studio developer command prompt. You cannot start it from a system command prompt or from File Explorer.
50+
51+
## Example
52+
53+
This example command clears the myapp.pgd file of profile data:
54+
55+
`pgomgr /clear myapp.pgd`
56+
57+
This example command adds profile data in myapp1.pgc to the .pgd file three times:
58+
59+
`pgomgr /merge:3 myapp1.pgc myapp.pgd`
60+
61+
In this example, profile data from all myapp#.pgc files is added to the myapp.pgd file.
62+
63+
`pgomgr -merge myapp1.pgd`
64+
65+
## See also
66+
67+
[Tools for Manual Profile-Guided Optimization](../../build/reference/tools-for-manual-profile-guided-optimization.md)

‎docs/build/reference/pgosweep.md‎

Lines changed: 42 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ ms.reviewer: ""
66
ms.suite: ""
77
ms.technology: ["cpp-tools"]
88
ms.tgt_pltfrm: ""
9-
ms.topic: "article"
9+
ms.topic: "reference"
1010
dev_langs: ["C++"]
1111
helpviewer_keywords: ["pgosweep program", "profile-guided optimizations, pgosweep"]
1212
ms.assetid: f39dd3b7-1cd9-4c3b-8e8b-fb794744b757
@@ -17,42 +17,44 @@ manager: "ghogen"
1717
ms.workload: ["cplusplus"]
1818
---
1919
# pgosweep
20-
Used in profile-guided optimization to write all profile data from a running program to the .pgc file.
21-
22-
## Syntax
23-
24-
```
25-
pgosweep [options] image pgcfile
26-
```
27-
28-
#### Parameters
29-
`options`
30-
An optional parameter that can be left blank. The valid values for `options` are as follows:
31-
32-
- **/?** or **/help,** displays the help message.
33-
34-
- **/noreset,** preserves the count in the runtime data structures.
35-
36-
`image`
37-
The full path of an .exe or .dll file that was created by using the compiler option /LTCG:PGINSTRUMENT.
38-
39-
`pgcfile`
40-
The .pgc file where this command will write out the data counts.
41-
42-
## Remarks
43-
This command works on programs that were built with the /LTCG:PGINSTRUMENT compiler option. It interrupts a running program and writes the profile data to a new .pgc file. By default, the command resets counts after each write operation. If you specify the **/noreset** option, the command will record the values, but not reset them in the running program. This option will give you duplicate data if you retrieve the profile data later.
44-
45-
An alternative use for `pgosweep` is to retrieve profile information just for the runtime of the application. For example, you could run `pgosweep` shortly after you start the application and discard that file. This would remove profile data associated with startup costs. Then, you can run `pgosweep` before ending the application. Now the collected data has profile information only from runtime.
46-
47-
When you name a .pgc file (`pgcfile`) you can use the standard format, which is *appname!n*.pgc. If you use this format, the compiler will find this data in the /LTCG:PGO phase. If you do not use the standard format, you must use [pgomgr](../../build/reference/pgomgr.md) to merge the .pgc files.
48-
49-
## Example
50-
51-
```
52-
pgosweep myapp.exe myapp!1.pgc
53-
```
54-
55-
In this example, `pgosweep` writes the current profile information for myapp.exe to myapp!1.pgc.
56-
57-
## See Also
58-
[Tools for Manual Profile-Guided Optimization](../../build/reference/tools-for-manual-profile-guided-optimization.md)
20+
21+
Used in profile-guided optimization to write all profile data from a running program to the .pgc file.
22+
23+
## Syntax
24+
25+
> **pgosweep** [*options*] *image* *pgcfile*
26+
27+
### Parameters
28+
29+
*options*<br/>
30+
An optional parameter. The valid values for *options* are:
31+
32+
- **/?** or **/help** displays the help message.
33+
34+
- **/noreset** preserves the count in the runtime data structures.
35+
36+
*image*<br/>
37+
The full path of an .exe or .dll file that was created by using the compiler option /LTCG:PGINSTRUMENT.
38+
39+
*pgcfile*<br/>
40+
The .pgc file where this command writes out the data counts.
41+
42+
## Remarks
43+
44+
The **pgosweep** command works on programs that were built with the [/LTCG:PGINSTRUMENT](ltcg-link-time-code-generation.md) compiler option. It interrupts a running program and writes the profile data to a new .pgc file. By default, the command resets counts after each write operation. If you specify the **/noreset** option, the command will record the values, but not reset them in the running program. This option will give you duplicate data if you retrieve the profile data later.
45+
46+
An alternative use for **pgosweep** is to retrieve profile information just for the runtime of the application. For example, you could run **pgosweep** shortly after you start the application and discard that file. This would remove profile data associated with startup costs. Then, you can run **pgosweep** before ending the application. Now the collected data has profile information only from runtime.
47+
48+
When you name a .pgc file (by using the *pgcfile* parameter) you can use the standard format, which is *appname!n*.pgc. If you use this format, the compiler automatically finds this data in the **/LTCG:PGO** phase. If you do not use the standard format, you must use [pgomgr](pgomgr.md) to merge the .pgc files.
49+
50+
## Example
51+
52+
```
53+
pgosweep myapp.exe myapp!1.pgc
54+
```
55+
56+
In this example, **pgosweep** writes the current profile information for myapp.exe to myapp!1.pgc.
57+
58+
## See also
59+
60+
[Tools for Manual Profile-Guided Optimization](../../build/reference/tools-for-manual-profile-guided-optimization.md)

0 commit comments

Comments
 (0)