ArmPkg/Include/Library/ArmLib.h

   1 /** @file
   2
   3   Copyright (c) 2008 - 2009, Apple Inc. All rights reserved.<BR>
   4   Copyright (c) 2011 - 2016, ARM Ltd. All rights reserved.<BR>
   5   Copyright (c) 2020 - 2021, NUVIA Inc. All rights reserved.<BR>
   6
   7   SPDX-License-Identifier: BSD-2-Clause-Patent
   8
   9 **/
  10
  11 #ifndef ARM_LIB_H_
  12 #define ARM_LIB_H_
  13
  14 #include <Uefi/UefiBaseType.h>
  15
  16 #ifdef MDE_CPU_ARM
  17   #include <Chipset/ArmV7.h>
  18 #elif defined (MDE_CPU_AARCH64)
  19   #include <Chipset/AArch64.h>
  20 #else
  21   #error "Unknown chipset."
  22 #endif
  23
  24 #define EFI_MEMORY_CACHETYPE_MASK  (EFI_MEMORY_UC | EFI_MEMORY_WC |  \
  25                                      EFI_MEMORY_WT | EFI_MEMORY_WB | \
  26                                      EFI_MEMORY_UCE)
  27
  28 /**
  29  * The UEFI firmware must not use the ARM_MEMORY_REGION_ATTRIBUTE_NONSECURE_* attributes.
  30  *
  31  * The Non Secure memory attribute (ARM_MEMORY_REGION_ATTRIBUTE_NONSECURE_*) should only
  32  * be used in Secure World to distinguished Secure to Non-Secure memory.
  33  */
  34 typedef enum {
  35   ARM_MEMORY_REGION_ATTRIBUTE_UNCACHED_UNBUFFERED = 0,
  36   ARM_MEMORY_REGION_ATTRIBUTE_NONSECURE_UNCACHED_UNBUFFERED,
  37   ARM_MEMORY_REGION_ATTRIBUTE_WRITE_BACK,
  38   ARM_MEMORY_REGION_ATTRIBUTE_NONSECURE_WRITE_BACK,
  39
  40   // On some platforms, memory mapped flash region is designed as not supporting
  41   // shareable attribute, so WRITE_BACK_NONSHAREABLE is added for such special
  42   // need.
  43   // Do NOT use below two attributes if you are not sure.
  44   ARM_MEMORY_REGION_ATTRIBUTE_WRITE_BACK_NONSHAREABLE,
  45   ARM_MEMORY_REGION_ATTRIBUTE_NONSECURE_WRITE_BACK_NONSHAREABLE,
  46
  47   ARM_MEMORY_REGION_ATTRIBUTE_WRITE_THROUGH,
  48   ARM_MEMORY_REGION_ATTRIBUTE_NONSECURE_WRITE_THROUGH,
  49   ARM_MEMORY_REGION_ATTRIBUTE_DEVICE,
  50   ARM_MEMORY_REGION_ATTRIBUTE_NONSECURE_DEVICE
  51 } ARM_MEMORY_REGION_ATTRIBUTES;
  52
  53 #define IS_ARM_MEMORY_REGION_ATTRIBUTES_SECURE(attr)  ((UINT32)(attr) & 1)
  54
  55 typedef struct {
  56   EFI_PHYSICAL_ADDRESS            PhysicalBase;
  57   EFI_VIRTUAL_ADDRESS             VirtualBase;
  58   UINT64                          Length;
  59   ARM_MEMORY_REGION_ATTRIBUTES    Attributes;
  60 } ARM_MEMORY_REGION_DESCRIPTOR;
  61
  62 typedef VOID (*CACHE_OPERATION)(
  63   VOID
  64   );
  65 typedef VOID (*LINE_OPERATION)(
  66   UINTN
  67   );
  68
  69 //
  70 // ARM Processor Mode
  71 //
  72 typedef enum {
  73   ARM_PROCESSOR_MODE_USER       = 0x10,
  74   ARM_PROCESSOR_MODE_FIQ        = 0x11,
  75   ARM_PROCESSOR_MODE_IRQ        = 0x12,
  76   ARM_PROCESSOR_MODE_SUPERVISOR = 0x13,
  77   ARM_PROCESSOR_MODE_ABORT      = 0x17,
  78   ARM_PROCESSOR_MODE_HYP        = 0x1A,
  79   ARM_PROCESSOR_MODE_UNDEFINED  = 0x1B,
  80   ARM_PROCESSOR_MODE_SYSTEM     = 0x1F,
  81   ARM_PROCESSOR_MODE_MASK       = 0x1F
  82 } ARM_PROCESSOR_MODE;
  83
  84 //
  85 // ARM Cpu IDs
  86 //
  87 #define ARM_CPU_IMPLEMENTER_MASK      (0xFFU << 24)
  88 #define ARM_CPU_IMPLEMENTER_ARMLTD    (0x41U << 24)
  89 #define ARM_CPU_IMPLEMENTER_DEC       (0x44U << 24)
  90 #define ARM_CPU_IMPLEMENTER_MOT       (0x4DU << 24)
  91 #define ARM_CPU_IMPLEMENTER_QUALCOMM  (0x51U << 24)
  92 #define ARM_CPU_IMPLEMENTER_MARVELL   (0x56U << 24)
  93
  94 #define ARM_CPU_PRIMARY_PART_MASK       (0xFFF << 4)
  95 #define ARM_CPU_PRIMARY_PART_CORTEXA5   (0xC05 << 4)
  96 #define ARM_CPU_PRIMARY_PART_CORTEXA7   (0xC07 << 4)
  97 #define ARM_CPU_PRIMARY_PART_CORTEXA8   (0xC08 << 4)
  98 #define ARM_CPU_PRIMARY_PART_CORTEXA9   (0xC09 << 4)
  99 #define ARM_CPU_PRIMARY_PART_CORTEXA15  (0xC0F << 4)
 100
 101 //
 102 // ARM MP Core IDs
 103 //
 104 #define ARM_CORE_AFF0  0xFF
 105 #define ARM_CORE_AFF1  (0xFF << 8)
 106 #define ARM_CORE_AFF2  (0xFF << 16)
 107 #define ARM_CORE_AFF3  (0xFFULL << 32)
 108
 109 #define ARM_CORE_MASK     ARM_CORE_AFF0
 110 #define ARM_CLUSTER_MASK  ARM_CORE_AFF1
 111 #define GET_CORE_ID(MpId)            ((MpId) & ARM_CORE_MASK)
 112 #define GET_CLUSTER_ID(MpId)         (((MpId) & ARM_CLUSTER_MASK) >> 8)
 113 #define GET_MPID(ClusterId, CoreId)  (((ClusterId) << 8) | (CoreId))
 114 #define GET_MPIDR_AFF0(MpId)         ((MpId) & ARM_CORE_AFF0)
 115 #define GET_MPIDR_AFF1(MpId)         (((MpId) & ARM_CORE_AFF1) >> 8)
 116 #define GET_MPIDR_AFF2(MpId)         (((MpId) & ARM_CORE_AFF2) >> 16)
 117 #define GET_MPIDR_AFF3(MpId)         (((MpId) & ARM_CORE_AFF3) >> 32)
 118 #define PRIMARY_CORE_ID  (PcdGet32(PcdArmPrimaryCore) & ARM_CORE_MASK)
 119
 120 /** Reads the CCSIDR register for the specified cache.
 121
 122   @param CSSELR The CSSELR cache selection register value.
 123
 124   @return The contents of the CCSIDR_EL1 register for the specified cache, when in AARCH64 mode.
 125           Returns the contents of the CCSIDR register in AARCH32 mode.
 126 **/
 127 UINTN
 128 ReadCCSIDR (
 129   IN UINT32  CSSELR
 130   );
 131
 132 /** Reads the CCSIDR2 for the specified cache.
 133
 134   @param CSSELR The CSSELR cache selection register value
 135
 136   @return The contents of the CCSIDR2 register for the specified cache.
 137 **/
 138 UINT32
 139 ReadCCSIDR2 (
 140   IN UINT32  CSSELR
 141   );
 142
 143 /** Reads the Cache Level ID (CLIDR) register.
 144
 145   @return The contents of the CLIDR_EL1 register.
 146 **/
 147 UINT32
 148 ReadCLIDR (
 149   VOID
 150   );
 151
 152 UINTN
 153 EFIAPI
 154 ArmDataCacheLineLength (
 155   VOID
 156   );
 157
 158 UINTN
 159 EFIAPI
 160 ArmInstructionCacheLineLength (
 161   VOID
 162   );
 163
 164 UINTN
 165 EFIAPI
 166 ArmCacheWritebackGranule (
 167   VOID
 168   );
 169
 170 UINTN
 171 EFIAPI
 172 ArmIsArchTimerImplemented (
 173   VOID
 174   );
 175
 176 UINTN
 177 EFIAPI
 178 ArmCacheInfo (
 179   VOID
 180   );
 181
 182 BOOLEAN
 183 EFIAPI
 184 ArmIsMpCore (
 185   VOID
 186   );
 187
 188 VOID
 189 EFIAPI
 190 ArmInvalidateDataCache (
 191   VOID
 192   );
 193
 194 VOID
 195 EFIAPI
 196 ArmCleanInvalidateDataCache (
 197   VOID
 198   );
 199
 200 VOID
 201 EFIAPI
 202 ArmCleanDataCache (
 203   VOID
 204   );
 205
 206 VOID
 207 EFIAPI
 208 ArmInvalidateInstructionCache (
 209   VOID
 210   );
 211
 212 VOID
 213 EFIAPI
 214 ArmInvalidateDataCacheEntryByMVA (
 215   IN  UINTN  Address
 216   );
 217
 218 VOID
 219 EFIAPI
 220 ArmCleanDataCacheEntryToPoUByMVA (
 221   IN  UINTN  Address
 222   );
 223
 224 VOID
 225 EFIAPI
 226 ArmInvalidateInstructionCacheEntryToPoUByMVA (
 227   IN  UINTN  Address
 228   );
 229
 230 VOID
 231 EFIAPI
 232 ArmCleanDataCacheEntryByMVA (
 233   IN  UINTN  Address
 234   );
 235
 236 VOID
 237 EFIAPI
 238 ArmCleanInvalidateDataCacheEntryByMVA (
 239   IN  UINTN  Address
 240   );
 241
 242 VOID
 243 EFIAPI
 244 ArmEnableDataCache (
 245   VOID
 246   );
 247
 248 VOID
 249 EFIAPI
 250 ArmDisableDataCache (
 251   VOID
 252   );
 253
 254 VOID
 255 EFIAPI
 256 ArmEnableInstructionCache (
 257   VOID
 258   );
 259
 260 VOID
 261 EFIAPI
 262 ArmDisableInstructionCache (
 263   VOID
 264   );
 265
 266 VOID
 267 EFIAPI
 268 ArmEnableMmu (
 269   VOID
 270   );
 271
 272 VOID
 273 EFIAPI
 274 ArmDisableMmu (
 275   VOID
 276   );
 277
 278 VOID
 279 EFIAPI
 280 ArmEnableCachesAndMmu (
 281   VOID
 282   );
 283
 284 VOID
 285 EFIAPI
 286 ArmDisableCachesAndMmu (
 287   VOID
 288   );
 289
 290 VOID
 291 EFIAPI
 292 ArmEnableInterrupts (
 293   VOID
 294   );
 295
 296 UINTN
 297 EFIAPI
 298 ArmDisableInterrupts (
 299   VOID
 300   );
 301
 302 BOOLEAN
 303 EFIAPI
 304 ArmGetInterruptState (
 305   VOID
 306   );
 307
 308 VOID
 309 EFIAPI
 310 ArmEnableAsynchronousAbort (
 311   VOID
 312   );
 313
 314 UINTN
 315 EFIAPI
 316 ArmDisableAsynchronousAbort (
 317   VOID
 318   );
 319
 320 VOID
 321 EFIAPI
 322 ArmEnableIrq (
 323   VOID
 324   );
 325
 326 UINTN
 327 EFIAPI
 328 ArmDisableIrq (
 329   VOID
 330   );
 331
 332 VOID
 333 EFIAPI
 334 ArmEnableFiq (
 335   VOID
 336   );
 337
 338 UINTN
 339 EFIAPI
 340 ArmDisableFiq (
 341   VOID
 342   );
 343
 344 BOOLEAN
 345 EFIAPI
 346 ArmGetFiqState (
 347   VOID
 348   );
 349
 350 /**
 351  * Invalidate Data and Instruction TLBs
 352  */
 353 VOID
 354 EFIAPI
 355 ArmInvalidateTlb (
 356   VOID
 357   );
 358
 359 VOID
 360 EFIAPI
 361 ArmUpdateTranslationTableEntry (
 362   IN  VOID  *TranslationTableEntry,
 363   IN  VOID  *Mva
 364   );
 365
 366 VOID
 367 EFIAPI
 368 ArmSetDomainAccessControl (
 369   IN  UINT32  Domain
 370   );
 371
 372 VOID
 373 EFIAPI
 374 ArmSetTTBR0 (
 375   IN  VOID  *TranslationTableBase
 376   );
 377
 378 VOID
 379 EFIAPI
 380 ArmSetTTBCR (
 381   IN  UINT32  Bits
 382   );
 383
 384 VOID *
 385 EFIAPI
 386 ArmGetTTBR0BaseAddress (
 387   VOID
 388   );
 389
 390 BOOLEAN
 391 EFIAPI
 392 ArmMmuEnabled (
 393   VOID
 394   );
 395
 396 VOID
 397 EFIAPI
 398 ArmEnableBranchPrediction (
 399   VOID
 400   );
 401
 402 VOID
 403 EFIAPI
 404 ArmDisableBranchPrediction (
 405   VOID
 406   );
 407
 408 VOID
 409 EFIAPI
 410 ArmSetLowVectors (
 411   VOID
 412   );
 413
 414 VOID
 415 EFIAPI
 416 ArmSetHighVectors (
 417   VOID
 418   );
 419
 420 VOID
 421 EFIAPI
 422 ArmDataMemoryBarrier (
 423   VOID
 424   );
 425
 426 VOID
 427 EFIAPI
 428 ArmDataSynchronizationBarrier (
 429   VOID
 430   );
 431
 432 VOID
 433 EFIAPI
 434 ArmInstructionSynchronizationBarrier (
 435   VOID
 436   );
 437
 438 VOID
 439 EFIAPI
 440 ArmWriteVBar (
 441   IN  UINTN  VectorBase
 442   );
 443
 444 UINTN
 445 EFIAPI
 446 ArmReadVBar (
 447   VOID
 448   );
 449
 450 VOID
 451 EFIAPI
 452 ArmWriteAuxCr (
 453   IN  UINT32  Bit
 454   );
 455
 456 UINT32
 457 EFIAPI
 458 ArmReadAuxCr (
 459   VOID
 460   );
 461
 462 VOID
 463 EFIAPI
 464 ArmSetAuxCrBit (
 465   IN  UINT32  Bits
 466   );
 467
 468 VOID
 469 EFIAPI
 470 ArmUnsetAuxCrBit (
 471   IN  UINT32  Bits
 472   );
 473
 474 VOID
 475 EFIAPI
 476 ArmCallSEV (
 477   VOID
 478   );
 479
 480 VOID
 481 EFIAPI
 482 ArmCallWFE (
 483   VOID
 484   );
 485
 486 VOID
 487 EFIAPI
 488 ArmCallWFI (
 489
 490   VOID
 491   );
 492
 493 UINTN
 494 EFIAPI
 495 ArmReadMpidr (
 496   VOID
 497   );
 498
 499 UINTN
 500 EFIAPI
 501 ArmReadMidr (
 502   VOID
 503   );
 504
 505 UINT32
 506 EFIAPI
 507 ArmReadCpacr (
 508   VOID
 509   );
 510
 511 VOID
 512 EFIAPI
 513 ArmWriteCpacr (
 514   IN  UINT32  Access
 515   );
 516
 517 VOID
 518 EFIAPI
 519 ArmEnableVFP (
 520   VOID
 521   );
 522
 523 /**
 524   Get the Secure Configuration Register value
 525
 526   @return   Value read from the Secure Configuration Register
 527
 528 **/
 529 UINT32
 530 EFIAPI
 531 ArmReadScr (
 532   VOID
 533   );
 534
 535 /**
 536   Set the Secure Configuration Register
 537
 538   @param Value   Value to write to the Secure Configuration Register
 539
 540 **/
 541 VOID
 542 EFIAPI
 543 ArmWriteScr (
 544   IN  UINT32  Value
 545   );
 546
 547 UINT32
 548 EFIAPI
 549 ArmReadMVBar (
 550   VOID
 551   );
 552
 553 VOID
 554 EFIAPI
 555 ArmWriteMVBar (
 556   IN  UINT32  VectorMonitorBase
 557   );
 558
 559 UINT32
 560 EFIAPI
 561 ArmReadSctlr (
 562   VOID
 563   );
 564
 565 VOID
 566 EFIAPI
 567 ArmWriteSctlr (
 568   IN  UINT32  Value
 569   );
 570
 571 UINTN
 572 EFIAPI
 573 ArmReadHVBar (
 574   VOID
 575   );
 576
 577 VOID
 578 EFIAPI
 579 ArmWriteHVBar (
 580   IN  UINTN  HypModeVectorBase
 581   );
 582
 583 //
 584 // Helper functions for accessing CPU ACTLR
 585 //
 586
 587 UINTN
 588 EFIAPI
 589 ArmReadCpuActlr (
 590   VOID
 591   );
 592
 593 VOID
 594 EFIAPI
 595 ArmWriteCpuActlr (
 596   IN  UINTN  Val
 597   );
 598
 599 VOID
 600 EFIAPI
 601 ArmSetCpuActlrBit (
 602   IN  UINTN  Bits
 603   );
 604
 605 VOID
 606 EFIAPI
 607 ArmUnsetCpuActlrBit (
 608   IN  UINTN  Bits
 609   );
 610
 611 //
 612 // Accessors for the architected generic timer registers
 613 //
 614
 615 #define ARM_ARCH_TIMER_ENABLE   (1 << 0)
 616 #define ARM_ARCH_TIMER_IMASK    (1 << 1)
 617 #define ARM_ARCH_TIMER_ISTATUS  (1 << 2)
 618
 619 UINTN
 620 EFIAPI
 621 ArmReadCntFrq (
 622   VOID
 623   );
 624
 625 VOID
 626 EFIAPI
 627 ArmWriteCntFrq (
 628   UINTN  FreqInHz
 629   );
 630
 631 UINT64
 632 EFIAPI
 633 ArmReadCntPct (
 634   VOID
 635   );
 636
 637 UINTN
 638 EFIAPI
 639 ArmReadCntkCtl (
 640   VOID
 641   );
 642
 643 VOID
 644 EFIAPI
 645 ArmWriteCntkCtl (
 646   UINTN  Val
 647   );
 648
 649 UINTN
 650 EFIAPI
 651 ArmReadCntpTval (
 652   VOID
 653   );
 654
 655 VOID
 656 EFIAPI
 657 ArmWriteCntpTval (
 658   UINTN  Val
 659   );
 660
 661 UINTN
 662 EFIAPI
 663 ArmReadCntpCtl (
 664   VOID
 665   );
 666
 667 VOID
 668 EFIAPI
 669 ArmWriteCntpCtl (
 670   UINTN  Val
 671   );
 672
 673 UINTN
 674 EFIAPI
 675 ArmReadCntvTval (
 676   VOID
 677   );
 678
 679 VOID
 680 EFIAPI
 681 ArmWriteCntvTval (
 682   UINTN  Val
 683   );
 684
 685 UINTN
 686 EFIAPI
 687 ArmReadCntvCtl (
 688   VOID
 689   );
 690
 691 VOID
 692 EFIAPI
 693 ArmWriteCntvCtl (
 694   UINTN  Val
 695   );
 696
 697 UINT64
 698 EFIAPI
 699 ArmReadCntvCt (
 700   VOID
 701   );
 702
 703 UINT64
 704 EFIAPI
 705 ArmReadCntpCval (
 706   VOID
 707   );
 708
 709 VOID
 710 EFIAPI
 711 ArmWriteCntpCval (
 712   UINT64  Val
 713   );
 714
 715 UINT64
 716 EFIAPI
 717 ArmReadCntvCval (
 718   VOID
 719   );
 720
 721 VOID
 722 EFIAPI
 723 ArmWriteCntvCval (
 724   UINT64  Val
 725   );
 726
 727 UINT64
 728 EFIAPI
 729 ArmReadCntvOff (
 730   VOID
 731   );
 732
 733 VOID
 734 EFIAPI
 735 ArmWriteCntvOff (
 736   UINT64  Val
 737   );
 738
 739 UINTN
 740 EFIAPI
 741 ArmGetPhysicalAddressBits (
 742   VOID
 743   );
 744
 745 ///
 746 ///  ID Register Helper functions
 747 ///
 748
 749 /**
 750   Check whether the CPU supports the GIC system register interface (any version)
 751
 752   @return   Whether GIC System Register Interface is supported
 753
 754 **/
 755 BOOLEAN
 756 EFIAPI
 757 ArmHasGicSystemRegisters (
 758   VOID
 759   );
 760
 761 /** Checks if CCIDX is implemented.
 762
 763    @retval TRUE  CCIDX is implemented.
 764    @retval FALSE CCIDX is not implemented.
 765 **/
 766 BOOLEAN
 767 EFIAPI
 768 ArmHasCcidx (
 769   VOID
 770   );
 771
 772 #ifdef MDE_CPU_ARM
 773 ///
 774 /// AArch32-only ID Register Helper functions
 775 ///
 776
 777 /**
 778   Check whether the CPU supports the Security extensions
 779
 780   @return   Whether the Security extensions are implemented
 781
 782 **/
 783 BOOLEAN
 784 EFIAPI
 785 ArmHasSecurityExtensions (
 786   VOID
 787   );
 788
 789 #endif // MDE_CPU_ARM
 790
 791 #endif // ARM_LIB_H_