<table border="1" cellspacing="0" cellpadding="8">
    <tr>
        <th>Issue</th>
        <td>
            <a href=https://github.com/llvm/llvm-project/issues/74022>74022</a>
        </td>
    </tr>

    <tr>
        <th>Summary</th>
        <td>
            Rework Clang PGO documentation
        </td>
    </tr>

    <tr>
      <th>Labels</th>
      <td>
            clang
      </td>
    </tr>

    <tr>
      <th>Assignees</th>
      <td>
      </td>
    </tr>

    <tr>
      <th>Reporter</th>
      <td>
          zamazan4ik
      </td>
    </tr>
</table>

<pre>
    Here I want to propose several suggestions to the Clang PGO [documentation](https://clang.llvm.org/docs/UsersManual.html#profile-guided-optimization).

We need to add information about LLVM runtime functions to the PGO documentation. Right now it does not cover at all provided by LLVM PGO-oriented functions like `__llvm_profile_write_buffer` and other functions from https://github.com/llvm/llvm-project/blob/main/compiler-rt/lib/profile/InstrProfiling.h (and probably other files - I am not familiar much yet with this piece of LLVM). Knowing which functions are provided by the instrumentation runtime and how to use them is important for users since in many cases they want to implement manual logic with dumping PGO profiles. Right now only a small subset of these functions are covered in https://clang.llvm.org/docs/SourceBasedCodeCoverage.html#running-the-instrumented-program - we need to move these descriptions to the main PGO documentation and extend it.

Here are some examples of existing usages:

* YugabyteDB: https://github.com/yugabyte/yugabyte-db/commit/34cb791ed9d3d5f8ae9a9b9e9181a46485e1981d
* Symbolicator: https://github.com/getsentry/symbolicator/issues/1334

We need to write LLVM profdata backward and forward compatibility guarantees directly in the Clang PGO documentation. Right now this information is located here - https://clang.llvm.org/docs/SourceBasedCodeCoverage.html#format-compatibility-guarantees . Having this information in the "SourceBasedCodeCoverage" can be confusing for the users since this at least the source-code coverage in terms of PGO refers only to FE PGO. But Clang also supports IR PGO (the recommended way to do PGO with Clang nowadays). As far as I understand, from the profile format point of view, the guarantees are the same - it should be documented as well.

</pre>
<img width="1px" height="1px" alt="" src="http://email.email.llvm.org/o/eJysVstu28gS_ZrWpiBBbEm2uNDCj6vEuAkSJLh3MCujyC6SPe4H0Q8rzNcPqqXY0gSeBzAbm3ZX1-PUOYfEGHXviHZicys29zPMafBh9x0tfke31k-zxqtp954CwQMc0CVIHsbgRx8JIj1TQAMx9z3FpL2LfJwGgjuDrofP7z6B2Nwq32ZLLiGHiM29kNshpTGK1Y2QeyH3LUcvjHm2Cx96IffKt1HI_f8ihfgRXUazGJI1Qq7G4DttaN5nrUjN_Zi01d-PmWW9EMt7sbw5_vyFwBEpbgmVAu06H2yJBGx8TvDhw_8_QsguaUvQZddejMDNX3S-gC-6HxI4fwCdQHmK4HyC1j9TAEyAxjA2z9wZNNMx_-d3n-Y-aHKJ1FkRo58IxNXy8ZHHfjyN9XgIOtFjk7uOgrhaAjoFPg0Uzq52wVu4BLDXacjNovVWyD0nPP2aj8H_Rm0Sct8Y3wi5t6gdI-7tqA2FeeAzo_no1IOQ-wcXU_hc_tSuXwwg5JY7GYNvsDHTj5a0oQhzeAC0BYkOrTYaA9jcDjBRgoNOA6RBRxg1tQS-K6jwquC_zh-06-Ew6HY4mw8DXcDIy9Dc0esqXrbGXQ3-wDvLkTjUgo6g7ehDYrp2PvBJiBC1azkRWHQTtBgpcvz0QmttR0NcgiMyGjC-1-1xBJXtqE-MPuEUz_ngnZkAIVrmQMxNpMSzpoEi_WG0QhdiPsLfU8FXn0NLtxhJ3XlFd3wfe_qhiJCd066fp4HmrzCR4t33AS3M4fCqBOuf6dSWotgGPV6QnunxM_MLzPQtkVOg04XIijXwWNFbAvqGDGLk2embjokxyxF7KmOe3RPyBn7NPTZTovtbsbr5M0ZPp8Czx7lqjjS2mhm8WrfNdV2RqtVKbbotUo11U1NdbStcX623G6rqbaVei3-dbOONbjH58Bfle0qRXAqTkPt4fk3udYyZeEnVarV-w3yKpo9mwNRRmBAabJ8OGFRBtvOhPLMoMelGG50m6DMGdIkogtKB2mQm5sylu75pUEVz55anIxjfIrvQwDub_zvsOxaYX7Q-P2t9Ae_xmVnwc0PHWYSUb5QQUkKLDhrWjOty5DSsZ752rumSGhMYwpjKaSwZ561XJ71hX6SfKNhCTsYuUMc5inSTh_1_-L8LuM3pBDCa6CHmkb0kwsOX4_tMbrlCIOYeOfaoA5YEypeA4hfHBM4fUOEUi93dROgwAEZ4gOwUhZjQKSHvjobOSU_OAkeQYPTaFRt51nTgQI45w5ZlV6ZFy_vUCeLgs1GM2A9ikOKKBzLmJNuZ2q1UvapxRrvqelmt6s2yrmfDbnm9rTeralttrq6WbbeprivcqvqaNqQ2my3N9E4u5aqSy2pZrdebelFtcb1Wq-tVt5XbmpRYL8miNi8smhV57K7XSylnBhsysXxpSFnYJqTkj46wK6-qJvdRrJdGxxRfMySdDO2-0MGHp7d4P8vB7P7xC_FFuqW93wMAAP__B90ihw">