diff options
author | H.J. Lu <hjl.tools@gmail.com> | 2020-06-29 18:30:54 -0700 |
---|---|---|
committer | H.J. Lu <hjl.tools@gmail.com> | 2020-09-11 17:20:52 -0700 |
commit | 9620398097de3981c1adf5233e2b3478d36bc1b3 (patch) | |
tree | 20e492ba12ab22a57ed91df3698fdf57eba54810 /manual/platform.texi | |
parent | a92f4e6299fe0e3cb6f77e79de00817aece501ce (diff) | |
download | glibc-9620398097de3981c1adf5233e2b3478d36bc1b3.tar.gz glibc-9620398097de3981c1adf5233e2b3478d36bc1b3.tar.xz glibc-9620398097de3981c1adf5233e2b3478d36bc1b3.zip |
x86: Install <sys/platform/x86.h> [BZ #26124]
Install <sys/platform/x86.h> so that programmers can do #if __has_include(<sys/platform/x86.h>) #include <sys/platform/x86.h> #endif ... if (CPU_FEATURE_USABLE (SSE2)) ... if (CPU_FEATURE_USABLE (AVX2)) ... <sys/platform/x86.h> exports only: enum { COMMON_CPUID_INDEX_1 = 0, COMMON_CPUID_INDEX_7, COMMON_CPUID_INDEX_80000001, COMMON_CPUID_INDEX_D_ECX_1, COMMON_CPUID_INDEX_80000007, COMMON_CPUID_INDEX_80000008, COMMON_CPUID_INDEX_7_ECX_1, /* Keep the following line at the end. */ COMMON_CPUID_INDEX_MAX }; struct cpuid_features { struct cpuid_registers cpuid; struct cpuid_registers usable; }; struct cpu_features { struct cpu_features_basic basic; struct cpuid_features features[COMMON_CPUID_INDEX_MAX]; }; /* Get a pointer to the CPU features structure. */ extern const struct cpu_features *__x86_get_cpu_features (unsigned int max) __attribute__ ((const)); Since all feature checks are done through macros, programs compiled with a newer <sys/platform/x86.h> are compatible with the older glibc binaries as long as the layout of struct cpu_features is identical. The features array can be expanded with backward binary compatibility for both .o and .so files. When COMMON_CPUID_INDEX_MAX is increased to support new processor features, __x86_get_cpu_features in the older glibc binaries returns NULL and HAS_CPU_FEATURE/CPU_FEATURE_USABLE return false on the new processor feature. No new symbol version is neeeded. Both CPU_FEATURE_USABLE and HAS_CPU_FEATURE are provided. HAS_CPU_FEATURE can be used to identify processor features. Note: Although GCC has __builtin_cpu_supports, it only supports a subset of <sys/platform/x86.h> and it is equivalent to CPU_FEATURE_USABLE. It doesn't support HAS_CPU_FEATURE.
Diffstat (limited to 'manual/platform.texi')
-rw-r--r-- | manual/platform.texi | 517 |
1 files changed, 517 insertions, 0 deletions
diff --git a/manual/platform.texi b/manual/platform.texi index 504addc956..2c145acdc3 100644 --- a/manual/platform.texi +++ b/manual/platform.texi @@ -7,6 +7,7 @@ @menu * PowerPC:: Facilities Specific to the PowerPC Architecture * RISC-V:: Facilities Specific to the RISC-V Architecture +* X86:: Facilities Specific to the X86 Architecture @end menu @node PowerPC @@ -134,3 +135,519 @@ all threads in the current process. Setting the ordering on only the current thread is necessary. All other flag bits are reserved. @end deftypefun + +@node X86 +@appendixsec X86-specific Facilities + +Facilities specific to X86 that are not specific to a particular +operating system are declared in @file{sys/platform/x86.h}. + +@deftypefun {const struct cpu_features *} __x86_get_cpu_features (unsigned int @var{max}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +Return a pointer to x86 CPU feature structure used by query macros for x86 +CPU features. If @var{max} exceeds @code{COMMON_CPUID_INDEX_MAX} which +is the limit of the CPUID leaves supported by @Theglibc{}, the function +returns @code{NULL}, indicating that the queried processor feature is +unsupported by @Theglibc{} run-time. +@end deftypefun + +@deftypefn Macro int HAS_CPU_FEATURE (@var{name}) +This macro returns a nonzero value (true) if the processor has the feature +@var{name}. +@end deftypefn + +@deftypefn Macro int CPU_FEATURE_USABLE (@var{name}) +This macro returns a nonzero value (true) if the processor has the feature +@var{name} and the feature is supported by the operating system. +@end deftypefn + +The supported processor features are: + +@itemize @bullet + +@item +@code{ACPI} -- Thermal Monitor and Software Controlled Clock Facilities. + +@item +@code{ADX} -- ADX instruction extensions. + +@item +@code{APIC} -- APIC On-Chip. + +@item +@code{AES} -- The AES instruction extensions. + +@item +@code{AMX_BF16} -- Tile computational operations on bfloat16 numbers. + +@item +@code{AMX_INT8} -- Tile computational operations on 8-bit numbers. + +@item +@code{AMX_TILE} -- Tile architecture. + +@item +@code{ARCH_CAPABILITIES} -- IA32_ARCH_CAPABILITIES MSR. + +@item +@code{AVX} -- The AVX instruction extensions. + +@item +@code{AVX2} -- The AVX2 instruction extensions. + +@item +@code{AVX512_4FMAPS} -- The AVX512_4FMAPS instruction extensions. + +@item +@code{AVX512_4VNNIW} -- The AVX512_4VNNIW instruction extensions. + +@item +@code{AVX512_BF16} -- The AVX512_BF16 instruction extensions. + +@item +@code{AVX512_BITALG} -- The AVX512_BITALG instruction extensions. + +@item +@code{AVX512_IFMA} -- The AVX512_IFMA instruction extensions. + +@item +@code{AVX512_VBMI} -- The AVX512_VBMI instruction extensions. + +@item +@code{AVX512_VBMI2} -- The AVX512_VBMI2 instruction extensions. + +@item +@code{AVX512_VNNI} -- The AVX512_VNNI instruction extensions. + +@item +@code{AVX512_VP2INTERSECT} -- The AVX512_VP2INTERSECT instruction +extensions. + +@item +@code{AVX512_VPOPCNTDQ} -- The AVX512_VPOPCNTDQ instruction extensions. + +@item +@code{AVX512BW} -- The AVX512BW instruction extensions. + +@item +@code{AVX512CD} -- The AVX512CD instruction extensions. + +@item +@code{AVX512ER} -- The AVX512ER instruction extensions. + +@item +@code{AVX512DQ} -- The AVX512DQ instruction extensions. + +@item +@code{AVX512F} -- The AVX512F instruction extensions. + +@item +@code{AVX512PF} -- The AVX512PF instruction extensions. + +@item +@code{AVX512VL} -- The AVX512VL instruction extensions. + +@item +@code{BMI1} -- BMI1 instructions. + +@item +@code{BMI2} -- BMI2 instructions. + +@item +@code{CLDEMOTE} -- CLDEMOTE instruction. + +@item +@code{CLFLUSHOPT} -- CLFLUSHOPT instruction. + +@item +@code{CLFSH} -- CLFLUSH instruction. + +@item +@code{CLWB} -- CLWB instruction. + +@item +@code{CMOV} -- Conditional Move instructions. + +@item +@code{CMPXCHG16B} -- CMPXCHG16B instruction. + +@item +@code{CNXT_ID} -- L1 Context ID. + +@item +@code{CORE_CAPABILITIES} -- IA32_CORE_CAPABILITIES MSR. + +@item +@code{CX8} -- CMPXCHG8B instruction. + +@item +@code{DCA} -- Data prefetch from a memory mapped device. + +@item +@code{DE} -- Debugging Extensions. + +@item +@code{DEPR_FPU_CS_DS} -- Deprecates FPU CS and FPU DS values. + +@item +@code{DS} -- Debug Store. + +@item +@code{DS_CPL} -- CPL Qualified Debug Store. + +@item +@code{DTES64} -- 64-bit DS Area. + +@item +@code{EIST} -- Enhanced Intel SpeedStep technology. + +@item +@code{ENQCMD} -- Enqueue Stores instructions. + +@item +@code{ERMS} -- Enhanced REP MOVSB/STOSB. + +@item +@code{F16C} -- 16-bit floating-point conversion instructions. + +@item +@code{FMA} -- FMA extensions using YMM state. + +@item +@code{FMA4} -- FMA4 instruction extensions. + +@item +@code{FPU} -- X87 Floating Point Unit On-Chip. + +@item +@code{FSGSBASE} -- RDFSBASE/RDGSBASE/WRFSBASE/WRGSBASE instructions. + +@item +@code{FSRM} -- Fast Short REP MOV. + +@item +@code{FXSR} -- FXSAVE and FXRSTOR instructions. + +@item +@code{GFNI} -- GFNI instruction extensions. + +@item +@code{HLE} -- HLE instruction extensions. + +@item +@code{HTT} -- Max APIC IDs reserved field is Valid. + +@item +@code{HYBRID} -- Hybrid processor. + +@item +@code{IBRS_IBPB} -- Indirect branch restricted speculation (IBRS) and +the indirect branch predictor barrier (IBPB). + +@item +@code{IBT} -- Intel Indirect Branch Tracking instruction extensions. + +@item +@code{INVARIANT_TSC} -- Invariant TSC. + +@item +@code{INVPCID} -- INVPCID instruction. + +@item +@code{L1D_FLUSH} -- IA32_FLUSH_CMD MSR. + +@item +@code{LAHF64_SAHF64} -- LAHF/SAHF available in 64-bit mode. + +@item +@code{LM} -- Long mode. + +@item +@code{LWP} -- Lightweight profiling. + +@item +@code{LZCNT} -- LZCNT instruction. + +@item +@code{MCA} -- Machine Check Architecture. + +@item +@code{MCE} -- Machine Check Exception. + +@item +@code{MD_CLEAR} -- MD_CLEAR. + +@item +@code{MMX} -- Intel MMX Technology. + +@item +@code{MONITOR} -- MONITOR/MWAIT instructions. + +@item +@code{MOVBE} -- MOVBE instruction. + +@item +@code{MOVDIRI} -- MOVDIRI instruction. + +@item +@code{MOVDIR64B} -- MOVDIR64B instruction. + +@item +@code{MPX} -- Intel Memory Protection Extensions. + +@item +@code{MSR} -- Model Specific Registers RDMSR and WRMSR instructions. + +@item +@code{MTRR} -- Memory Type Range Registers. + +@item +@code{NX} -- No-execute page protection. + +@item +@code{OSPKE} -- OS has set CR4.PKE to enable protection keys. + +@item +@code{OSXSAVE} -- The OS has set CR4.OSXSAVE[bit 18] to enable +XSETBV/XGETBV instructions to access XCR0 and to support processor +extended state management using XSAVE/XRSTOR. + +@item +@code{PAE} -- Physical Address Extension. + +@item +@code{PAGE1GB} -- 1-GByte page. + +@item +@code{PAT} -- Page Attribute Table. + +@item +@code{PBE} -- Pending Break Enable. + +@item +@code{PCID} -- Process-context identifiers. + +@item +@code{PCLMULQDQ} -- PCLMULQDQ instruction. + +@item +@code{PCONFIG} -- PCONFIG instruction. + +@item +@code{PDCM} -- Perfmon and Debug Capability. + +@item +@code{PGE} -- Page Global Bit. + +@item +@code{PKS} -- Protection keys for supervisor-mode pages. + +@item +@code{PKU} -- Protection keys for user-mode pages. + +@item +@code{POPCNT} -- POPCNT instruction. + +@item +@code{PREFETCHW} -- PREFETCHW instruction. + +@item +@code{PREFETCHWT1} -- PREFETCHWT1 instruction. + +@item +@code{PSE} -- Page Size Extension. + +@item +@code{PSE_36} -- 36-Bit Page Size Extension. + +@item +@code{PSN} -- Processor Serial Number. + +@item +@code{RDPID} -- RDPID instruction. + +@item +@code{RDRAND} -- RDRAND instruction. + +@item +@code{RDSEED} -- RDSEED instruction. + +@item +@code{RDT_A} -- Intel Resource Director Technology (Intel RDT) Allocation +capability. + +@item +@code{RDT_M} -- Intel Resource Director Technology (Intel RDT) Monitoring +capability. + +@item +@code{RDTSCP} -- RDTSCP instruction. + +@item +@code{RTM} -- RTM instruction extensions. + +@item +@code{SDBG} -- IA32_DEBUG_INTERFACE MSR for silicon debug. + +@item +@code{SEP} -- SYSENTER and SYSEXIT instructions. + +@item +@code{SERIALIZE} -- SERIALIZE instruction. + +@item +@code{SGX} -- Intel Software Guard Extensions. + +@item +@code{SGX_LC} -- SGX Launch Configuration. + +@item +@code{SHA} -- SHA instruction extensions. + +@item +@code{SHSTK} -- Intel Shadow Stack instruction extensions. + +@item +@code{SMAP} -- Supervisor-Mode Access Prevention. + +@item +@code{SMEP} -- Supervisor-Mode Execution Prevention. + +@item +@code{SMX} -- Safer Mode Extensions. + +@item +@code{SS} -- Self Snoop. + +@item +@code{SSBD} -- Speculative Store Bypass Disable (SSBD). + +@item +@code{SSE} -- Streaming SIMD Extensions. + +@item +@code{SSE2} -- Streaming SIMD Extensions 2. + +@item +@code{SSE3} -- Streaming SIMD Extensions 3. + +@item +@code{SSE4_1} -- Streaming SIMD Extensions 4.1. + +@item +@code{SSE4_2} -- Streaming SIMD Extensions 4.2. + +@item +@code{SSE4A} -- SSE4A instruction extensions. + +@item +@code{SSSE3} -- Supplemental Streaming SIMD Extensions 3. + +@item +@code{STIBP} -- Single thread indirect branch predictors (STIBP). + +@item +@code{SVM} -- Secure Virtual Machine. + +@item +@code{SYSCALL_SYSRET} -- SYSCALL/SYSRET instructions. + +@item +@code{TBM} -- Trailing bit manipulation instructions. + +@item +@code{TM} -- Thermal Monitor. + +@item +@code{TM2} -- Thermal Monitor 2. + +@item +@code{TRACE} -- Intel Processor Trace. + +@item +@code{TSC} -- Time Stamp Counter. RDTSC instruction. + +@item +@code{TSC_ADJUST} -- IA32_TSC_ADJUST MSR. + +@item +@code{TSC_DEADLINE} -- Local APIC timer supports one-shot operation +using a TSC deadline value. + +@item +@code{TSXLDTRK} -- TSXLDTRK instructions. + +@item +@code{UMIP} -- User-mode instruction prevention. + +@item +@code{VAES} -- VAES instruction extensions. + +@item +@code{VME} -- Virtual 8086 Mode Enhancements. + +@item +@code{VMX} -- Virtual Machine Extensions. + +@item +@code{VPCLMULQDQ} -- VPCLMULQDQ instruction. + +@item +@code{WAITPKG} -- WAITPKG instruction extensions. + +@item +@code{WBNOINVD} -- WBINVD/WBNOINVD instructions. + +@item +@code{X2APIC} -- x2APIC. + +@item +@code{XFD} -- Extended Feature Disable (XFD). + +@item +@code{XGETBV_ECX_1} -- XGETBV with ECX = 1. + +@item +@code{XOP} -- XOP instruction extensions. + +@item +@code{XSAVE} -- The XSAVE/XRSTOR processor extended states feature, the +XSETBV/XGETBV instructions, and XCR0. + +@item +@code{XSAVEC} -- XSAVEC instruction. + +@item +@code{XSAVEOPT} -- XSAVEOPT instruction. + +@item +@code{XSAVES} -- XSAVES/XRSTORS instructions. + +@item +@code{XTPRUPDCTRL} -- xTPR Update Control. + +@end itemize + +You could query if a processor supports @code{AVX} with: + +@smallexample +#include <sys/platform/x86.h> + +int +support_avx (void) +@{ + return HAS_CPU_FEATURE (AVX); +@} +@end smallexample + +and if @code{AVX} is usable with: + +@smallexample +#include <sys/platform/x86.h> + +int +usable_avx (void) +@{ + return CPU_FEATURE_USABLE (AVX); +@} +@end smallexample |