[clang] [doc] Added documentation to intrinsics in cpuid.h

[romanova-ekaterina]

Added doxygen comments to 4 intrinsincs in cpuid.h

[llvmbot]

@llvm/pr-subscribers-backend-x86

@llvm/pr-subscribers-clang

Author: Katya Romanova (romanova-ekaterina)

Changes

Added doxygen comments to 4 intrinsincs in cpuid.h

---

Full diff: https://github.com/llvm/llvm-project/pull/170507.diff

1 Files Affected:

• (modified) clang/lib/Headers/cpuid.h (+94)

diff --git a/clang/lib/Headers/cpuid.h b/clang/lib/Headers/cpuid.h
index 432747ba1f6ad..cd5828d925099 100644
--- a/clang/lib/Headers/cpuid.h
+++ b/clang/lib/Headers/cpuid.h
@@ -278,6 +278,23 @@
         : "0"(__leaf), "2"(__count))
 #endif
 
+/// Queries the processor to determine the highest supported \c CPUID leaf.
+///
+/// \headerfile <cpuid.h>
+///
+/// This intrinsic corresponds to the <c> CPUID </c> instruction.
+///
+/// \param __leaf
+///    \a __leaf can be either 0x0 or 0x8000000. If \a __leaf == 0x0, the
+///    highest supported value for basic \c CPUID information is returned.
+///    If \a __leaf == 0x8000000, the highest supported value for extended
+///    \c CPUID information is returned.
+/// \param __sig
+///    If the \a __sig pointer is non-null, the first four bytes of the
+///    signature (as found in the \c ebx register) are returned in the
+///    location pointed to by \a __sig.
+/// \returns Returns 0 if \c CPUID is supported; otherwise returns the value
+///    that \c CPUID returns in the \c eax register.
 static __inline unsigned int __get_cpuid_max (unsigned int __leaf,
                                               unsigned int *__sig)
 {
@@ -311,6 +328,32 @@ static __inline unsigned int __get_cpuid_max (unsigned int __leaf,
     return __eax;
 }
 
+/// For the requested \c CPUID leaf, queries the processor for information
+/// about the CPU type and CPU features (such as processor vendor, supported
+/// instruction sets, CPU capabilities, cache sizes, CPU model and family, and
+/// other hardware details). This intrinsic is only available on x86 and x64.
+///
+/// \headerfile <cpuid.h>
+///
+/// This intrinsic corresponds to the <c> CPUID </c> instruction.
+///
+/// \param __leaf
+///    An unsigned integer that identifies the level (also called "leaf") at
+///    which the \c CPUID instruction will be executed.
+/// \param __eax
+///    A pointer to an integer that corresponds to the \c eax register where
+///    \c CPUID stores output results.
+/// \param __ebx
+///    A pointer to an integer that corresponds to the \c ebx register where
+///    \c CPUID stores output results.
+/// \param __ecx
+///    A pointer to an integer that corresponds to the \c ecx register where
+///    \c CPUID stores output results.
+/// \param __edx
+///    A pointer to an integer that corresponds to the \c edx register where
+///    \c CPUID stores output results.
+/// \returns Returns 1 if the requested \c CPUID leaf is supported; otherwise
+///    returns 0.
 static __inline int __get_cpuid (unsigned int __leaf, unsigned int *__eax,
                                  unsigned int *__ebx, unsigned int *__ecx,
                                  unsigned int *__edx)
@@ -324,6 +367,36 @@ static __inline int __get_cpuid (unsigned int __leaf, unsigned int *__eax,
     return 1;
 }
 
+/// For the requested \c CPUID leaf and subleaf, queries the processor for
+/// information about the CPU type and CPU features (such as processor vendor,
+/// supported instruction sets, CPU capabilities, cache sizes, CPU model and
+/// family, and other hardware details). This intrinsic is only available on
+/// x86 and x64.
+///
+/// \headerfile <cpuid.h>
+///
+/// This intrinsic corresponds to the <c> CPUID </c> instruction.
+///
+/// \param __leaf
+///    An unsigned integer that identifies the level (also called "leaf") at
+///    which the \c CPUID instruction will be executed.
+/// \param __subleaf
+///    An unsigned integer that identifies the sublevel (also called
+///    "subleaf") at which the \c CPUID instruction will be executed.
+/// \param __eax
+///    A pointer to an integer that corresponds to the \c eax register where
+///    \c CPUID stores output results.
+/// \param __ebx
+///    A pointer to an integer that corresponds to the \c ebx register where
+///    \c CPUID stores output results.
+/// \param __ecx
+///    A pointer to an integer that corresponds to the \c ecx register where
+///    \c CPUID stores output results.
+/// \param __edx
+///    A pointer to an integer that corresponds to the \c edx register where
+///    \c CPUID stores output results.
+/// \returns Returns 1 if the requested \c CPUID leaf is supported; otherwise
+///    returns 0.
 static __inline int __get_cpuid_count (unsigned int __leaf,
                                        unsigned int __subleaf,
                                        unsigned int *__eax, unsigned int *__ebx,
@@ -345,6 +418,27 @@ static __inline int __get_cpuid_count (unsigned int __leaf,
 // builtin. Given __has_builtin does not detect builtins on aux triples, we need
 // to explicitly check for some offloading cases.
 #if !defined(__NVPTX__) && !defined(__AMDGPU__) && !defined(__SPIRV__)
+/// Executes the \c CPUID instruction with the specified leaf and subleaf
+/// values, and returns the results from the CPU's registers.
+///
+/// \headerfile <cpuid.h>
+///
+/// This intrinsic corresponds to the <c> CPUID </c> instruction.
+///
+/// \param __cpu_info
+///    An output array of four integers:
+///    <ul>
+///    <li>\a __cpuInfo[0] receives the value of the \c eax register.</li>
+///    <li>\a__cpuInfo[1] receives the value of the \c ebx register.</li>
+///    <li>\a__cpuInfo[2] receives the value of the \c ecx register.</li>
+///    <li>\a__cpuInfo[3] receives the value of the \c edx register.</li>
+///    </ul>
+/// \param __leaf
+///    An unsigned integer that identifies the level (also called the "leaf")
+///    at which the \c CPUID instruction will be executed.
+/// \param __subleaf
+///    An unsigned integer that identifies the sublevel (also called the
+///    "subleaf") at which the \c CPUID instruction will be executed.
 static __inline void __cpuidex(int __cpu_info[4], int __leaf, int __subleaf) {
   __cpuid_count(__leaf, __subleaf, __cpu_info[0], __cpu_info[1], __cpu_info[2],
                 __cpu_info[3]);

[phoebewang]

LGTM except some nits.

Thanks for the doc, I didn't know what's __get_cpuid_max used for before reading it :)

[phoebewang]

Space after \a

[romanova-ekaterina]

Fixed in the follow up commit.

[phoebewang]

nit: would it better to use upper case \c EAX. The same for below.

[romanova-ekaterina]

Fixed in the follow up commit.

[romanova-ekaterina]

Thank you so much for the review. I assume that I can commit now, since I received LGTM before the minor corrections.