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 GET_MPIDR_AFFINITY_BITS(MpId)  ((MpId) & 0xFF00FFFFFF)
 119 #define PRIMARY_CORE_ID  (PcdGet32(PcdArmPrimaryCore) & ARM_CORE_MASK)
 120 #define MPIDR_MT_BIT     BIT24
 121
 122 /** Reads the CCSIDR register for the specified cache.
 123
 124   @param CSSELR The CSSELR cache selection register value.
 125
 126   @return The contents of the CCSIDR_EL1 register for the specified cache, when in AARCH64 mode.
 127           Returns the contents of the CCSIDR register in AARCH32 mode.
 128 **/
 129 UINTN
 130 ReadCCSIDR (
 131   IN UINT32  CSSELR
 132   );
 133
 134 /** Reads the CCSIDR2 for the specified cache.
 135
 136   @param CSSELR The CSSELR cache selection register value
 137
 138   @return The contents of the CCSIDR2 register for the specified cache.
 139 **/
 140 UINT32
 141 ReadCCSIDR2 (
 142   IN UINT32  CSSELR
 143   );
 144
 145 /** Reads the Cache Level ID (CLIDR) register.
 146
 147   @return The contents of the CLIDR_EL1 register.
 148 **/
 149 UINT32
 150 ReadCLIDR (
 151   VOID
 152   );
 153
 154 UINTN
 155 EFIAPI
 156 ArmDataCacheLineLength (
 157   VOID
 158   );
 159
 160 UINTN
 161 EFIAPI
 162 ArmInstructionCacheLineLength (
 163   VOID
 164   );
 165
 166 UINTN
 167 EFIAPI
 168 ArmCacheWritebackGranule (
 169   VOID
 170   );
 171
 172 UINTN
 173 EFIAPI
 174 ArmIsArchTimerImplemented (
 175   VOID
 176   );
 177
 178 UINTN
 179 EFIAPI
 180 ArmCacheInfo (
 181   VOID
 182   );
 183
 184 BOOLEAN
 185 EFIAPI
 186 ArmIsMpCore (
 187   VOID
 188   );
 189
 190 VOID
 191 EFIAPI
 192 ArmInvalidateDataCache (
 193   VOID
 194   );
 195
 196 VOID
 197 EFIAPI
 198 ArmCleanInvalidateDataCache (
 199   VOID
 200   );
 201
 202 VOID
 203 EFIAPI
 204 ArmCleanDataCache (
 205   VOID
 206   );
 207
 208 VOID
 209 EFIAPI
 210 ArmInvalidateInstructionCache (
 211   VOID
 212   );
 213
 214 VOID
 215 EFIAPI
 216 ArmInvalidateDataCacheEntryByMVA (
 217   IN  UINTN  Address
 218   );
 219
 220 VOID
 221 EFIAPI
 222 ArmCleanDataCacheEntryToPoUByMVA (
 223   IN  UINTN  Address
 224   );
 225
 226 VOID
 227 EFIAPI
 228 ArmInvalidateInstructionCacheEntryToPoUByMVA (
 229   IN  UINTN  Address
 230   );
 231
 232 VOID
 233 EFIAPI
 234 ArmCleanDataCacheEntryByMVA (
 235   IN  UINTN  Address
 236   );
 237
 238 VOID
 239 EFIAPI
 240 ArmCleanInvalidateDataCacheEntryByMVA (
 241   IN  UINTN  Address
 242   );
 243
 244 VOID
 245 EFIAPI
 246 ArmEnableDataCache (
 247   VOID
 248   );
 249
 250 VOID
 251 EFIAPI
 252 ArmDisableDataCache (
 253   VOID
 254   );
 255
 256 VOID
 257 EFIAPI
 258 ArmEnableInstructionCache (
 259   VOID
 260   );
 261
 262 VOID
 263 EFIAPI
 264 ArmDisableInstructionCache (
 265   VOID
 266   );
 267
 268 VOID
 269 EFIAPI
 270 ArmEnableMmu (
 271   VOID
 272   );
 273
 274 VOID
 275 EFIAPI
 276 ArmDisableMmu (
 277   VOID
 278   );
 279
 280 VOID
 281 EFIAPI
 282 ArmEnableCachesAndMmu (
 283   VOID
 284   );
 285
 286 VOID
 287 EFIAPI
 288 ArmDisableCachesAndMmu (
 289   VOID
 290   );
 291
 292 VOID
 293 EFIAPI
 294 ArmEnableInterrupts (
 295   VOID
 296   );
 297
 298 UINTN
 299 EFIAPI
 300 ArmDisableInterrupts (
 301   VOID
 302   );
 303
 304 BOOLEAN
 305 EFIAPI
 306 ArmGetInterruptState (
 307   VOID
 308   );
 309
 310 VOID
 311 EFIAPI
 312 ArmEnableAsynchronousAbort (
 313   VOID
 314   );
 315
 316 UINTN
 317 EFIAPI
 318 ArmDisableAsynchronousAbort (
 319   VOID
 320   );
 321
 322 VOID
 323 EFIAPI
 324 ArmEnableIrq (
 325   VOID
 326   );
 327
 328 UINTN
 329 EFIAPI
 330 ArmDisableIrq (
 331   VOID
 332   );
 333
 334 VOID
 335 EFIAPI
 336 ArmEnableFiq (
 337   VOID
 338   );
 339
 340 UINTN
 341 EFIAPI
 342 ArmDisableFiq (
 343   VOID
 344   );
 345
 346 BOOLEAN
 347 EFIAPI
 348 ArmGetFiqState (
 349   VOID
 350   );
 351
 352 /**
 353  * Invalidate Data and Instruction TLBs
 354  */
 355 VOID
 356 EFIAPI
 357 ArmInvalidateTlb (
 358   VOID
 359   );
 360
 361 VOID
 362 EFIAPI
 363 ArmUpdateTranslationTableEntry (
 364   IN  VOID  *TranslationTableEntry,
 365   IN  VOID  *Mva
 366   );
 367
 368 VOID
 369 EFIAPI
 370 ArmSetDomainAccessControl (
 371   IN  UINT32  Domain
 372   );
 373
 374 VOID
 375 EFIAPI
 376 ArmSetTTBR0 (
 377   IN  VOID  *TranslationTableBase
 378   );
 379
 380 VOID
 381 EFIAPI
 382 ArmSetTTBCR (
 383   IN  UINT32  Bits
 384   );
 385
 386 VOID *
 387 EFIAPI
 388 ArmGetTTBR0BaseAddress (
 389   VOID
 390   );
 391
 392 BOOLEAN
 393 EFIAPI
 394 ArmMmuEnabled (
 395   VOID
 396   );
 397
 398 VOID
 399 EFIAPI
 400 ArmEnableBranchPrediction (
 401   VOID
 402   );
 403
 404 VOID
 405 EFIAPI
 406 ArmDisableBranchPrediction (
 407   VOID
 408   );
 409
 410 VOID
 411 EFIAPI
 412 ArmSetLowVectors (
 413   VOID
 414   );
 415
 416 VOID
 417 EFIAPI
 418 ArmSetHighVectors (
 419   VOID
 420   );
 421
 422 VOID
 423 EFIAPI
 424 ArmDataMemoryBarrier (
 425   VOID
 426   );
 427
 428 VOID
 429 EFIAPI
 430 ArmDataSynchronizationBarrier (
 431   VOID
 432   );
 433
 434 VOID
 435 EFIAPI
 436 ArmInstructionSynchronizationBarrier (
 437   VOID
 438   );
 439
 440 VOID
 441 EFIAPI
 442 ArmWriteVBar (
 443   IN  UINTN  VectorBase
 444   );
 445
 446 UINTN
 447 EFIAPI
 448 ArmReadVBar (
 449   VOID
 450   );
 451
 452 VOID
 453 EFIAPI
 454 ArmWriteAuxCr (
 455   IN  UINT32  Bit
 456   );
 457
 458 UINT32
 459 EFIAPI
 460 ArmReadAuxCr (
 461   VOID
 462   );
 463
 464 VOID
 465 EFIAPI
 466 ArmSetAuxCrBit (
 467   IN  UINT32  Bits
 468   );
 469
 470 VOID
 471 EFIAPI
 472 ArmUnsetAuxCrBit (
 473   IN  UINT32  Bits
 474   );
 475
 476 VOID
 477 EFIAPI
 478 ArmCallSEV (
 479   VOID
 480   );
 481
 482 VOID
 483 EFIAPI
 484 ArmCallWFE (
 485   VOID
 486   );
 487
 488 VOID
 489 EFIAPI
 490 ArmCallWFI (
 491
 492   VOID
 493   );
 494
 495 UINTN
 496 EFIAPI
 497 ArmReadMpidr (
 498   VOID
 499   );
 500
 501 UINTN
 502 EFIAPI
 503 ArmReadMidr (
 504   VOID
 505   );
 506
 507 UINT32
 508 EFIAPI
 509 ArmReadCpacr (
 510   VOID
 511   );
 512
 513 VOID
 514 EFIAPI
 515 ArmWriteCpacr (
 516   IN  UINT32  Access
 517   );
 518
 519 VOID
 520 EFIAPI
 521 ArmEnableVFP (
 522   VOID
 523   );
 524
 525 /**
 526   Get the Secure Configuration Register value
 527
 528   @return   Value read from the Secure Configuration Register
 529
 530 **/
 531 UINT32
 532 EFIAPI
 533 ArmReadScr (
 534   VOID
 535   );
 536
 537 /**
 538   Set the Secure Configuration Register
 539
 540   @param Value   Value to write to the Secure Configuration Register
 541
 542 **/
 543 VOID
 544 EFIAPI
 545 ArmWriteScr (
 546   IN  UINT32  Value
 547   );
 548
 549 UINT32
 550 EFIAPI
 551 ArmReadMVBar (
 552   VOID
 553   );
 554
 555 VOID
 556 EFIAPI
 557 ArmWriteMVBar (
 558   IN  UINT32  VectorMonitorBase
 559   );
 560
 561 UINT32
 562 EFIAPI
 563 ArmReadSctlr (
 564   VOID
 565   );
 566
 567 VOID
 568 EFIAPI
 569 ArmWriteSctlr (
 570   IN  UINT32  Value
 571   );
 572
 573 UINTN
 574 EFIAPI
 575 ArmReadHVBar (
 576   VOID
 577   );
 578
 579 VOID
 580 EFIAPI
 581 ArmWriteHVBar (
 582   IN  UINTN  HypModeVectorBase
 583   );
 584
 585 //
 586 // Helper functions for accessing CPU ACTLR
 587 //
 588
 589 UINTN
 590 EFIAPI
 591 ArmReadCpuActlr (
 592   VOID
 593   );
 594
 595 VOID
 596 EFIAPI
 597 ArmWriteCpuActlr (
 598   IN  UINTN  Val
 599   );
 600
 601 VOID
 602 EFIAPI
 603 ArmSetCpuActlrBit (
 604   IN  UINTN  Bits
 605   );
 606
 607 VOID
 608 EFIAPI
 609 ArmUnsetCpuActlrBit (
 610   IN  UINTN  Bits
 611   );
 612
 613 //
 614 // Accessors for the architected generic timer registers
 615 //
 616
 617 #define ARM_ARCH_TIMER_ENABLE   (1 << 0)
 618 #define ARM_ARCH_TIMER_IMASK    (1 << 1)
 619 #define ARM_ARCH_TIMER_ISTATUS  (1 << 2)
 620
 621 UINTN
 622 EFIAPI
 623 ArmReadCntFrq (
 624   VOID
 625   );
 626
 627 VOID
 628 EFIAPI
 629 ArmWriteCntFrq (
 630   UINTN  FreqInHz
 631   );
 632
 633 UINT64
 634 EFIAPI
 635 ArmReadCntPct (
 636   VOID
 637   );
 638
 639 UINTN
 640 EFIAPI
 641 ArmReadCntkCtl (
 642   VOID
 643   );
 644
 645 VOID
 646 EFIAPI
 647 ArmWriteCntkCtl (
 648   UINTN  Val
 649   );
 650
 651 UINTN
 652 EFIAPI
 653 ArmReadCntpTval (
 654   VOID
 655   );
 656
 657 VOID
 658 EFIAPI
 659 ArmWriteCntpTval (
 660   UINTN  Val
 661   );
 662
 663 UINTN
 664 EFIAPI
 665 ArmReadCntpCtl (
 666   VOID
 667   );
 668
 669 VOID
 670 EFIAPI
 671 ArmWriteCntpCtl (
 672   UINTN  Val
 673   );
 674
 675 UINTN
 676 EFIAPI
 677 ArmReadCntvTval (
 678   VOID
 679   );
 680
 681 VOID
 682 EFIAPI
 683 ArmWriteCntvTval (
 684   UINTN  Val
 685   );
 686
 687 UINTN
 688 EFIAPI
 689 ArmReadCntvCtl (
 690   VOID
 691   );
 692
 693 VOID
 694 EFIAPI
 695 ArmWriteCntvCtl (
 696   UINTN  Val
 697   );
 698
 699 UINT64
 700 EFIAPI
 701 ArmReadCntvCt (
 702   VOID
 703   );
 704
 705 UINT64
 706 EFIAPI
 707 ArmReadCntpCval (
 708   VOID
 709   );
 710
 711 VOID
 712 EFIAPI
 713 ArmWriteCntpCval (
 714   UINT64  Val
 715   );
 716
 717 UINT64
 718 EFIAPI
 719 ArmReadCntvCval (
 720   VOID
 721   );
 722
 723 VOID
 724 EFIAPI
 725 ArmWriteCntvCval (
 726   UINT64  Val
 727   );
 728
 729 UINT64
 730 EFIAPI
 731 ArmReadCntvOff (
 732   VOID
 733   );
 734
 735 VOID
 736 EFIAPI
 737 ArmWriteCntvOff (
 738   UINT64  Val
 739   );
 740
 741 UINTN
 742 EFIAPI
 743 ArmGetPhysicalAddressBits (
 744   VOID
 745   );
 746
 747 ///
 748 ///  ID Register Helper functions
 749 ///
 750
 751 /**
 752   Check whether the CPU supports the GIC system register interface (any version)
 753
 754   @return   Whether GIC System Register Interface is supported
 755
 756 **/
 757 BOOLEAN
 758 EFIAPI
 759 ArmHasGicSystemRegisters (
 760   VOID
 761   );
 762
 763 /** Checks if CCIDX is implemented.
 764
 765    @retval TRUE  CCIDX is implemented.
 766    @retval FALSE CCIDX is not implemented.
 767 **/
 768 BOOLEAN
 769 EFIAPI
 770 ArmHasCcidx (
 771   VOID
 772   );
 773
 774 #ifdef MDE_CPU_ARM
 775 ///
 776 /// AArch32-only ID Register Helper functions
 777 ///
 778
 779 /**
 780   Check whether the CPU supports the Security extensions
 781
 782   @return   Whether the Security extensions are implemented
 783
 784 **/
 785 BOOLEAN
 786 EFIAPI
 787 ArmHasSecurityExtensions (
 788   VOID
 789   );
 790
 791 #endif // MDE_CPU_ARM
 792
 793 #endif // ARM_LIB_H_