Coverage: Document how to collect a profile without a filesystem

[dexonsmith]

Summary

The profiling runtime was designed to work without static initializers
or a a filesystem (see 117cf2bd1ff585f9754b5f30f5a4cfd65b230bbf and
others). The no-static-initializers part was already documented but this
part got missed before.

[vsk]

Thanks for doing this!

+ Eli to comment on whether any workarounds documented in https://lists.llvm.org/pipermail/llvm-dev/2017-September/117156.html are still necessary. To my knowledge it's not currently necessary to explicitly pass -mllvm -enable-value-profiling=false (as value profiling should not be enabled under -fcoverage-mapping -fprofile-instr-generate). It should also not be necessary to shave .o's out of the runtime static archive; so long as the static initializer isn't linked, the linker shouldn't pull in any references to malloc, mmap, etc.

clang/docs/SourceBasedCodeCoverage.rst

368

I think we should leave a note about how to avoid pulling in unwanted symbol references, and perhaps reference the preceding section about using the runtime without its static initializer.

[dexonsmith]

Incorporate feedback from @vsk:

• a bit more explanatory text for the overall context
• explicitly reference the static initializers

[dexonsmith]

clang/docs/SourceBasedCodeCoverage.rst

368

Improved this a bit; let me know if you suggested text that makes the unwanted symbol reference stuff a bit more clear.

Note, BTW, that I've made this a sub-section of "Using the profiling runtime without static initializers"; if you think it should be a peer section that's an option too.

[vsk]

This looks great, thanks.

clang/docs/SourceBasedCodeCoverage.rst

 
 * Forward-declare ``int __llvm_profile_write_file(void)`` and call it to write
   out a profile. This function returns 0 when it succeeds, and a non-zero value
   otherwise. Calling this function multiple times appends profile data to an
   existing on-disk raw profile.
 
 In C++ files, declare these as ``extern "C"``.
 
+Using the profiling runtime without a filesystem
+------------------------------------------------
+
+The profiling runtime also supports freestanding environments that lack a
+filesystem. The runtime ships as a static archive that's structured to make
+dependencies on a hosted environment optional, depending on what features
+the client application uses.
+
+The first step is to export ``__llvm_profile_runtime``, as above, to disable
+the default static initializers. Instead of calling the ``*_file()`` APIs
+described above, use the following to save the profile directly to a buffer
+under your control:
+
+* Forward-declare ``uint64_t __llvm_profile_get_size_for_buffer(void)`` and
+  call it to determine the size of the profile. You'll need to allocate a
+  buffer of this size.
+
+* Forward-declare ``int __llvm_profile_write_buffer(char *Buffer)`` and call it
+  to copy the current counters to ``Buffer``, which is expected to already be
+  allocated and big enough for the profile.
+
+* Optionally, forward-declare ``void __llvm_profile_reset_counters(void)`` and
+  call it to reset the counters before entering a specific section to be
+  profiled. This is only useful if there is some setup that should be excluded
+  from the profile.
+
+In C++ files, declare these as ``extern "C"``.
+
 Collecting coverage reports for the llvm project
 ================================================
 
 To prepare a coverage report for llvm (and any of its sub-projects), add
 ``-DLLVM_BUILD_INSTRUMENTED_COVERAGE=On`` to the cmake configuration. Raw
 profiles will be written to ``$BUILD_DIR/profiles/``. To prepare an html
 report, run ``llvm/utils/prepare-code-coverage-artifact.py``.