1@node Platform, Contributors, Maintenance, Top 2@c %MENU% Describe all platform-specific facilities provided 3@appendix Platform-specific facilities 4 5@Theglibc{} can provide machine-specific functionality. 6 7@menu 8* PowerPC:: Facilities Specific to the PowerPC Architecture 9* RISC-V:: Facilities Specific to the RISC-V Architecture 10* X86:: Facilities Specific to the X86 Architecture 11@end menu 12 13@node PowerPC 14@appendixsec PowerPC-specific Facilities 15 16Facilities specific to PowerPC that are not specific to a particular 17operating system are declared in @file{sys/platform/ppc.h}. 18 19@deftypefun {uint64_t} __ppc_get_timebase (void) 20@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} 21Read the current value of the Time Base Register. 22 23The @dfn{Time Base Register} is a 64-bit register that stores a monotonically 24incremented value updated at a system-dependent frequency that may be 25different from the processor frequency. More information is available in 26@cite{Power ISA 2.06b - Book II - Section 5.2}. 27 28@code{__ppc_get_timebase} uses the processor's time base facility directly 29without requiring assistance from the operating system, so it is very 30efficient. 31@end deftypefun 32 33@deftypefun {uint64_t} __ppc_get_timebase_freq (void) 34@safety{@prelim{}@mtunsafe{@mtuinit{}}@asunsafe{@asucorrupt{:init}}@acunsafe{@acucorrupt{:init}}} 35@c __ppc_get_timebase_freq=__get_timebase_freq @mtuinit @acsfd 36@c __get_clockfreq @mtuinit @asucorrupt:init @acucorrupt:init @acsfd 37@c the initialization of the static timebase_freq is not exactly 38@c safe, because hp_timing_t cannot be atomically set up. 39@c syscall:get_tbfreq ok 40@c open dup @acsfd 41@c read dup ok 42@c memcpy dup ok 43@c memmem dup ok 44@c close dup @acsfd 45Read the current frequency at which the Time Base Register is updated. 46 47This frequency is not related to the processor clock or the bus clock. 48It is also possible that this frequency is not constant. More information is 49available in @cite{Power ISA 2.06b - Book II - Section 5.2}. 50@end deftypefun 51 52The following functions provide hints about the usage of resources that are 53shared with other processors. They can be used, for example, if a program 54waiting on a lock intends to divert the shared resources to be used by other 55processors. More information is available in @cite{Power ISA 2.06b - Book II - 56Section 3.2}. 57 58@deftypefun {void} __ppc_yield (void) 59@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} 60Provide a hint that performance will probably be improved if shared resources 61dedicated to the executing processor are released for use by other processors. 62@end deftypefun 63 64@deftypefun {void} __ppc_mdoio (void) 65@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} 66Provide a hint that performance will probably be improved if shared resources 67dedicated to the executing processor are released until all outstanding storage 68accesses to caching-inhibited storage have been completed. 69@end deftypefun 70 71@deftypefun {void} __ppc_mdoom (void) 72@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} 73Provide a hint that performance will probably be improved if shared resources 74dedicated to the executing processor are released until all outstanding storage 75accesses to cacheable storage for which the data is not in the cache have been 76completed. 77@end deftypefun 78 79@deftypefun {void} __ppc_set_ppr_med (void) 80@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} 81Set the Program Priority Register to medium value (default). 82 83The @dfn{Program Priority Register} (PPR) is a 64-bit register that controls 84the program's priority. By adjusting the PPR value the programmer may 85improve system throughput by causing the system resources to be used 86more efficiently, especially in contention situations. 87The three unprivileged states available are covered by the functions 88@code{__ppc_set_ppr_med} (medium -- default), @code{__ppc_set_ppc_low} (low) 89and @code{__ppc_set_ppc_med_low} (medium low). More information 90available in @cite{Power ISA 2.06b - Book II - Section 3.1}. 91@end deftypefun 92 93@deftypefun {void} __ppc_set_ppr_low (void) 94@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} 95Set the Program Priority Register to low value. 96@end deftypefun 97 98@deftypefun {void} __ppc_set_ppr_med_low (void) 99@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} 100Set the Program Priority Register to medium low value. 101@end deftypefun 102 103Power ISA 2.07 extends the priorities that can be set to the Program Priority 104Register (PPR). The following functions implement the new priority levels: 105very low and medium high. 106 107@deftypefun {void} __ppc_set_ppr_very_low (void) 108@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} 109Set the Program Priority Register to very low value. 110@end deftypefun 111 112@deftypefun {void} __ppc_set_ppr_med_high (void) 113@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} 114Set the Program Priority Register to medium high value. The medium high 115priority is privileged and may only be set during certain time intervals by 116problem-state programs. If the program priority is medium high when the time 117interval expires or if an attempt is made to set the priority to medium high 118when it is not allowed, the priority is set to medium. 119@end deftypefun 120 121@node RISC-V 122@appendixsec RISC-V-specific Facilities 123 124Cache management facilities specific to RISC-V systems that implement the Linux 125ABI are declared in @file{sys/cachectl.h}. 126 127@deftypefun {void} __riscv_flush_icache (void *@var{start}, void *@var{end}, unsigned long int @var{flags}) 128@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} 129Enforce ordering between stores and instruction cache fetches. The range of 130addresses over which ordering is enforced is specified by @var{start} and 131@var{end}. The @var{flags} argument controls the extent of this ordering, with 132the default behavior (a @var{flags} value of 0) being to enforce the fence on 133all threads in the current process. Setting the 134@code{SYS_RISCV_FLUSH_ICACHE_LOCAL} bit allows users to indicate that enforcing 135ordering on only the current thread is necessary. All other flag bits are 136reserved. 137@end deftypefun 138 139@node X86 140@appendixsec X86-specific Facilities 141 142Facilities specific to X86 that are not specific to a particular 143operating system are declared in @file{sys/platform/x86.h}. 144 145@deftypefun {const struct cpuid_feature *} __x86_get_cpuid_feature_leaf (unsigned int @var{leaf}) 146@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} 147Return a pointer to x86 CPU feature structure used by query macros for x86 148CPU feature @var{leaf}. 149@end deftypefun 150 151@deftypefn Macro int CPU_FEATURE_PRESENT (@var{name}) 152This macro returns a nonzero value (true) if the processor has the feature 153@var{name}. 154@end deftypefn 155 156@deftypefn Macro int CPU_FEATURE_ACTIVE (@var{name}) 157This macro returns a nonzero value (true) if the processor has the feature 158@var{name} and the feature is active. There may be other preconditions, 159like sufficient stack space or further setup for AMX, which must be 160satisfied before the feature can be used. 161@end deftypefn 162 163The supported processor features are: 164 165@itemize @bullet 166 167@item 168@code{ACPI} -- Thermal Monitor and Software Controlled Clock Facilities. 169 170@item 171@code{ADX} -- ADX instruction extensions. 172 173@item 174@code{APIC} -- APIC On-Chip. 175 176@item 177@code{AES} -- The AES instruction extensions. 178 179@item 180@code{AESKLE} -- AES Key Locker instructions are enabled by OS. 181 182@item 183@code{AMD_IBPB} -- Indirect branch predictor barrier (IBPB) for AMD cpus. 184 185@item 186@code{AMD_IBRS} -- Indirect branch restricted speculation (IBPB) for AMD cpus. 187 188@item 189@code{AMD_SSBD} -- Speculative Store Bypass Disable (SSBD) for AMD cpus. 190 191@item 192@code{AMD_STIBP} -- Single thread indirect branch predictors (STIBP) for AMD cpus. 193 194@item 195@code{AMD_VIRT_SSBD} -- Speculative Store Bypass Disable (SSBD) for AMD cpus (older systems). 196 197@item 198@code{AMX_BF16} -- Tile computational operations on bfloat16 numbers. 199 200@item 201@code{AMX_INT8} -- Tile computational operations on 8-bit numbers. 202 203@item 204@code{AMX_TILE} -- Tile architecture. 205 206@item 207@code{ARCH_CAPABILITIES} -- IA32_ARCH_CAPABILITIES MSR. 208 209@item 210@code{AVX} -- The AVX instruction extensions. 211 212@item 213@code{AVX2} -- The AVX2 instruction extensions. 214 215@item 216@code{AVX_VNNI} -- The AVX-VNNI instruction extensions. 217 218@item 219@code{AVX512_4FMAPS} -- The AVX512_4FMAPS instruction extensions. 220 221@item 222@code{AVX512_4VNNIW} -- The AVX512_4VNNIW instruction extensions. 223 224@item 225@code{AVX512_BF16} -- The AVX512_BF16 instruction extensions. 226 227@item 228@code{AVX512_BITALG} -- The AVX512_BITALG instruction extensions. 229 230@item 231@code{AVX512_FP16} -- The AVX512_FP16 instruction extensions. 232 233@item 234@code{AVX512_IFMA} -- The AVX512_IFMA instruction extensions. 235 236@item 237@code{AVX512_VBMI} -- The AVX512_VBMI instruction extensions. 238 239@item 240@code{AVX512_VBMI2} -- The AVX512_VBMI2 instruction extensions. 241 242@item 243@code{AVX512_VNNI} -- The AVX512_VNNI instruction extensions. 244 245@item 246@code{AVX512_VP2INTERSECT} -- The AVX512_VP2INTERSECT instruction 247extensions. 248 249@item 250@code{AVX512_VPOPCNTDQ} -- The AVX512_VPOPCNTDQ instruction extensions. 251 252@item 253@code{AVX512BW} -- The AVX512BW instruction extensions. 254 255@item 256@code{AVX512CD} -- The AVX512CD instruction extensions. 257 258@item 259@code{AVX512ER} -- The AVX512ER instruction extensions. 260 261@item 262@code{AVX512DQ} -- The AVX512DQ instruction extensions. 263 264@item 265@code{AVX512F} -- The AVX512F instruction extensions. 266 267@item 268@code{AVX512PF} -- The AVX512PF instruction extensions. 269 270@item 271@code{AVX512VL} -- The AVX512VL instruction extensions. 272 273@item 274@code{BMI1} -- BMI1 instructions. 275 276@item 277@code{BMI2} -- BMI2 instructions. 278 279@item 280@code{CLDEMOTE} -- CLDEMOTE instruction. 281 282@item 283@code{CLFLUSHOPT} -- CLFLUSHOPT instruction. 284 285@item 286@code{CLFSH} -- CLFLUSH instruction. 287 288@item 289@code{CLWB} -- CLWB instruction. 290 291@item 292@code{CMOV} -- Conditional Move instructions. 293 294@item 295@code{CMPXCHG16B} -- CMPXCHG16B instruction. 296 297@item 298@code{CNXT_ID} -- L1 Context ID. 299 300@item 301@code{CORE_CAPABILITIES} -- IA32_CORE_CAPABILITIES MSR. 302 303@item 304@code{CX8} -- CMPXCHG8B instruction. 305 306@item 307@code{DCA} -- Data prefetch from a memory mapped device. 308 309@item 310@code{DE} -- Debugging Extensions. 311 312@item 313@code{DEPR_FPU_CS_DS} -- Deprecates FPU CS and FPU DS values. 314 315@item 316@code{DS} -- Debug Store. 317 318@item 319@code{DS_CPL} -- CPL Qualified Debug Store. 320 321@item 322@code{DTES64} -- 64-bit DS Area. 323 324@item 325@code{EIST} -- Enhanced Intel SpeedStep technology. 326 327@item 328@code{ENQCMD} -- Enqueue Stores instructions. 329 330@item 331@code{ERMS} -- Enhanced REP MOVSB/STOSB. 332 333@item 334@code{F16C} -- 16-bit floating-point conversion instructions. 335 336@item 337@code{FMA} -- FMA extensions using YMM state. 338 339@item 340@code{FMA4} -- FMA4 instruction extensions. 341 342@item 343@code{FPU} -- X87 Floating Point Unit On-Chip. 344 345@item 346@code{FSGSBASE} -- RDFSBASE/RDGSBASE/WRFSBASE/WRGSBASE instructions. 347 348@item 349@code{FSRCS} -- Fast Short REP CMP and SCA. 350 351@item 352@code{FSRM} -- Fast Short REP MOV. 353 354@item 355@code{FSRS} -- Fast Short REP STO. 356 357@item 358@code{FXSR} -- FXSAVE and FXRSTOR instructions. 359 360@item 361@code{FZLRM} -- Fast Zero-Length REP MOV. 362 363@item 364@code{GFNI} -- GFNI instruction extensions. 365 366@item 367@code{HLE} -- HLE instruction extensions. 368 369@item 370@code{HTT} -- Max APIC IDs reserved field is Valid. 371 372@item 373@code{HRESET} -- History reset. 374 375@item 376@code{HYBRID} -- Hybrid processor. 377 378@item 379@code{IBRS_IBPB} -- Indirect branch restricted speculation (IBRS) and 380the indirect branch predictor barrier (IBPB). 381 382@item 383@code{IBT} -- Intel Indirect Branch Tracking instruction extensions. 384 385@item 386@code{INVARIANT_TSC} -- Invariant TSC. 387 388@item 389@code{INVPCID} -- INVPCID instruction. 390 391@item 392@code{KL} -- AES Key Locker instructions. 393 394@item 395@code{LAM} -- Linear Address Masking. 396 397@item 398@code{L1D_FLUSH} -- IA32_FLUSH_CMD MSR. 399 400@item 401@code{LAHF64_SAHF64} -- LAHF/SAHF available in 64-bit mode. 402 403@item 404@code{LM} -- Long mode. 405 406@item 407@code{LWP} -- Lightweight profiling. 408 409@item 410@code{LZCNT} -- LZCNT instruction. 411 412@item 413@code{MCA} -- Machine Check Architecture. 414 415@item 416@code{MCE} -- Machine Check Exception. 417 418@item 419@code{MD_CLEAR} -- MD_CLEAR. 420 421@item 422@code{MMX} -- Intel MMX Technology. 423 424@item 425@code{MONITOR} -- MONITOR/MWAIT instructions. 426 427@item 428@code{MOVBE} -- MOVBE instruction. 429 430@item 431@code{MOVDIRI} -- MOVDIRI instruction. 432 433@item 434@code{MOVDIR64B} -- MOVDIR64B instruction. 435 436@item 437@code{MPX} -- Intel Memory Protection Extensions. 438 439@item 440@code{MSR} -- Model Specific Registers RDMSR and WRMSR instructions. 441 442@item 443@code{MTRR} -- Memory Type Range Registers. 444 445@item 446@code{NX} -- No-execute page protection. 447 448@item 449@code{OSPKE} -- OS has set CR4.PKE to enable protection keys. 450 451@item 452@code{OSXSAVE} -- The OS has set CR4.OSXSAVE[bit 18] to enable 453XSETBV/XGETBV instructions to access XCR0 and to support processor 454extended state management using XSAVE/XRSTOR. 455 456@item 457@code{PAE} -- Physical Address Extension. 458 459@item 460@code{PAGE1GB} -- 1-GByte page. 461 462@item 463@code{PAT} -- Page Attribute Table. 464 465@item 466@code{PBE} -- Pending Break Enable. 467 468@item 469@code{PCID} -- Process-context identifiers. 470 471@item 472@code{PCLMULQDQ} -- PCLMULQDQ instruction. 473 474@item 475@code{PCONFIG} -- PCONFIG instruction. 476 477@item 478@code{PDCM} -- Perfmon and Debug Capability. 479 480@item 481@code{PGE} -- Page Global Bit. 482 483@item 484@code{PKS} -- Protection keys for supervisor-mode pages. 485 486@item 487@code{PKU} -- Protection keys for user-mode pages. 488 489@item 490@code{POPCNT} -- POPCNT instruction. 491 492@item 493@code{PREFETCHW} -- PREFETCHW instruction. 494 495@item 496@code{PREFETCHWT1} -- PREFETCHWT1 instruction. 497 498@item 499@code{PSE} -- Page Size Extension. 500 501@item 502@code{PSE_36} -- 36-Bit Page Size Extension. 503 504@item 505@code{PSN} -- Processor Serial Number. 506 507@item 508@code{PTWRITE} -- PTWRITE instruction. 509 510@item 511@code{RDPID} -- RDPID instruction. 512 513@item 514@code{RDRAND} -- RDRAND instruction. 515 516@item 517@code{RDSEED} -- RDSEED instruction. 518 519@item 520@code{RDT_A} -- Intel Resource Director Technology (Intel RDT) Allocation 521capability. 522 523@item 524@code{RDT_M} -- Intel Resource Director Technology (Intel RDT) Monitoring 525capability. 526 527@item 528@code{RDTSCP} -- RDTSCP instruction. 529 530@item 531@code{RTM} -- RTM instruction extensions. 532 533@item 534@code{RTM_ALWAYS_ABORT} -- Transactions always abort, making RTM unusable. 535 536@item 537@code{SDBG} -- IA32_DEBUG_INTERFACE MSR for silicon debug. 538 539@item 540@code{SEP} -- SYSENTER and SYSEXIT instructions. 541 542@item 543@code{SERIALIZE} -- SERIALIZE instruction. 544 545@item 546@code{SGX} -- Intel Software Guard Extensions. 547 548@item 549@code{SGX_LC} -- SGX Launch Configuration. 550 551@item 552@code{SHA} -- SHA instruction extensions. 553 554@item 555@code{SHSTK} -- Intel Shadow Stack instruction extensions. 556 557@item 558@code{SMAP} -- Supervisor-Mode Access Prevention. 559 560@item 561@code{SMEP} -- Supervisor-Mode Execution Prevention. 562 563@item 564@code{SMX} -- Safer Mode Extensions. 565 566@item 567@code{SS} -- Self Snoop. 568 569@item 570@code{SSBD} -- Speculative Store Bypass Disable (SSBD). 571 572@item 573@code{SSE} -- Streaming SIMD Extensions. 574 575@item 576@code{SSE2} -- Streaming SIMD Extensions 2. 577 578@item 579@code{SSE3} -- Streaming SIMD Extensions 3. 580 581@item 582@code{SSE4_1} -- Streaming SIMD Extensions 4.1. 583 584@item 585@code{SSE4_2} -- Streaming SIMD Extensions 4.2. 586 587@item 588@code{SSE4A} -- SSE4A instruction extensions. 589 590@item 591@code{SSSE3} -- Supplemental Streaming SIMD Extensions 3. 592 593@item 594@code{STIBP} -- Single thread indirect branch predictors (STIBP). 595 596@item 597@code{SVM} -- Secure Virtual Machine. 598 599@item 600@code{SYSCALL_SYSRET} -- SYSCALL/SYSRET instructions. 601 602@item 603@code{TBM} -- Trailing bit manipulation instructions. 604 605@item 606@code{TM} -- Thermal Monitor. 607 608@item 609@code{TM2} -- Thermal Monitor 2. 610 611@item 612@code{TRACE} -- Intel Processor Trace. 613 614@item 615@code{TSC} -- Time Stamp Counter. RDTSC instruction. 616 617@item 618@code{TSC_ADJUST} -- IA32_TSC_ADJUST MSR. 619 620@item 621@code{TSC_DEADLINE} -- Local APIC timer supports one-shot operation 622using a TSC deadline value. 623 624@item 625@code{TSXLDTRK} -- TSXLDTRK instructions. 626 627@item 628@code{UINTR} -- User interrupts. 629 630@item 631@code{UMIP} -- User-mode instruction prevention. 632 633@item 634@code{VAES} -- VAES instruction extensions. 635 636@item 637@code{VME} -- Virtual 8086 Mode Enhancements. 638 639@item 640@code{VMX} -- Virtual Machine Extensions. 641 642@item 643@code{VPCLMULQDQ} -- VPCLMULQDQ instruction. 644 645@item 646@code{WAITPKG} -- WAITPKG instruction extensions. 647 648@item 649@code{WBNOINVD} -- WBINVD/WBNOINVD instructions. 650 651@item 652@code{WIDE_KL} -- AES wide Key Locker instructions. 653 654@item 655@code{X2APIC} -- x2APIC. 656 657@item 658@code{XFD} -- Extended Feature Disable (XFD). 659 660@item 661@code{XGETBV_ECX_1} -- XGETBV with ECX = 1. 662 663@item 664@code{XOP} -- XOP instruction extensions. 665 666@item 667@code{XSAVE} -- The XSAVE/XRSTOR processor extended states feature, the 668XSETBV/XGETBV instructions, and XCR0. 669 670@item 671@code{XSAVEC} -- XSAVEC instruction. 672 673@item 674@code{XSAVEOPT} -- XSAVEOPT instruction. 675 676@item 677@code{XSAVES} -- XSAVES/XRSTORS instructions. 678 679@item 680@code{XTPRUPDCTRL} -- xTPR Update Control. 681 682@end itemize 683 684You could query if a processor supports @code{AVX} with: 685 686@smallexample 687#include <sys/platform/x86.h> 688 689int 690avx_present (void) 691@{ 692 return CPU_FEATURE_PRESENT (AVX); 693@} 694@end smallexample 695 696and if @code{AVX} is active and may be used with: 697 698@smallexample 699#include <sys/platform/x86.h> 700 701int 702avx_active (void) 703@{ 704 return CPU_FEATURE_ACTIVE (AVX); 705@} 706@end smallexample 707