manual/platform.texi

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