git-svn-id: https://edk2.svn.sourceforge.net/svnroot/edk2/trunk/edk2@2769 6f19259b...
[mirror_edk2.git] / MdePkg / Include / IndustryStandard / Pal.h
1 /** @file
2 Main PAL API's defined in IPF PAL Spec.
3
4 Copyright (c) 2006 - 2007, Intel Corporation
5 All rights reserved. This program and the accompanying materials
6 are licensed and made available under the terms and conditions of the BSD License
7 which accompanies this distribution. The full text of the license may be found at
8 http://opensource.org/licenses/bsd-license.php
9
10 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
11 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
12
13 Module Name: PalApi.h
14
15 **/
16
17 #ifndef __PAL_API_H__
18 #define __PAL_API_H__
19
20 //
21 // IPF Specific Functions
22 //
23 #ifdef _MSC_VER
24 //
25 // Disabling bitfield type checking warnings.
26 //
27 #pragma warning ( disable : 4214 )
28 #endif
29
30 typedef struct {
31 UINT64 Status;
32 UINT64 r9;
33 UINT64 r10;
34 UINT64 r11;
35 } PAL_CALL_RETURN;
36
37
38
39 //
40 // CacheType of PAL_CACHE_FLUSH.
41 //
42 #define PAL_CACHE_FLUSH_INSTRUCTION_ALL 1
43 #define PAL_CACHE_FLUSH_DATA_ALL 2
44 #define PAL_CACHE_FLUSH_ALL 3
45 #define PAL_CACHE_FLUSH_SYNC_TO_DATA 4
46
47
48 //
49 // Bitmask of Opearation of PAL_CACHE_FLUSH.
50 //
51 #define PAL_CACHE_FLUSH_INVIDED_LINES BIT0
52 #define PAL_CACHE_FLUSH_PROBE_INTERRUPT BIT1
53
54 /**
55
56 Flush the instruction or data caches. It is required by IPF.
57 The PAL procedure supports the Static Registers calling
58 convention. It could be called at virtual mode and physical
59 mode.
60
61 @param Index Index of PAL_CACHE_FLUSH within the
62 list of PAL procedures.
63
64 @param CacheType Unsigned 64-bit integer indicating
65 which cache to flush.
66
67 @param Operation Formatted bit vector indicating the
68 operation of this call.
69
70 @param ProgressIndicator Unsigned 64-bit integer specifying
71 the starting position of the flush
72 operation.
73
74 @return R9 Unsigned 64-bit integer specifying the vector
75 number of the pending interrupt.
76
77 @return R10 Unsigned 64-bit integer specifying the
78 starting position of the flush operation.
79
80 @return R11 Unsigned 64-bit integer specifying the vector
81 number of the pending interrupt.
82
83 @return Status 2 - Call completed without error, but a PMI
84 was taken during the execution of this
85 procedure.
86
87 @return Status 1 - Call has not completed flushing due to
88 a pending interrupt.
89
90 @return Status 0 - Call completed without error
91
92 @return Status -2 - Invalid argument
93
94 @return Status -3 - Call completed with error
95
96 **/
97 #define PAL_CACHE_FLUSH 1
98
99
100 //
101 // Attributes of PAL_CACHE_CONFIG_INFO1
102 //
103 #define PAL_CACHE_ATTR_WT 0
104 #define PAL_CACHE_ATTR_WB 1
105
106 //
107 // PAL_CACHE_CONFIG_INFO1.StoreHint
108 //
109 #define PAL_CACHE_STORE_TEMPORAL 0
110 #define PAL_CACHE_STORE_NONE_TEMPORAL 3
111
112 //
113 // PAL_CACHE_CONFIG_INFO1.StoreHint
114 //
115 #define PAL_CACHE_STORE_TEMPORAL_LVL_1 0
116 #define PAL_CACHE_STORE_NONE_TEMPORAL_LVL_ALL 3
117
118 //
119 // PAL_CACHE_CONFIG_INFO1.StoreHint
120 //
121 #define PAL_CACHE_LOAD_TEMPORAL_LVL_1 0
122 #define PAL_CACHE_LOAD_NONE_TEMPORAL_LVL_1 1
123 #define PAL_CACHE_LOAD_NONE_TEMPORAL_LVL_ALL 3
124
125 //
126 // Detail the characteristics of a given processor controlled
127 // cache in the cache hierarchy.
128 //
129 typedef struct {
130 UINT64 IsUnified : 1;
131 UINT64 Attributes : 2;
132 UINT64 Associativity:8;
133 UINT64 LineSize:8;
134 UINT64 Stride:8;
135 UINT64 StoreLatency:8;
136 UINT64 StoreHint:8;
137 UINT64 LoadHint:8;
138 } PAL_CACHE_INFO_RETURN1;
139
140 //
141 // Detail the characteristics of a given processor controlled
142 // cache in the cache hierarchy.
143 //
144 typedef struct {
145 UINT64 CacheSize:32;
146 UINT64 AliasBoundary:8;
147 UINT64 TagLsBits:8;
148 UINT64 TagMsBits:8;
149 } PAL_CACHE_INFO_RETURN2;
150
151 /**
152
153 Return detailed instruction or data cache information. It is
154 required by IPF. The PAL procedure supports the Static
155 Registers calling convention. It could be called at virtual
156 mode and physical mode.
157
158 @param Index Index of PAL_CACHE_INFO within the list of
159 PAL procedures.
160
161 @param CacheLevel Unsigned 64-bit integer specifying the
162 level in the cache hierarchy for which
163 information is requested. This value must
164 be between 0 and one less than the value
165 returned in the cache_levels return value
166 from PAL_CACHE_SUMMARY.
167
168 @param CacheType Unsigned 64-bit integer with a value of 1
169 for instruction cache and 2 for data or
170 unified cache. All other values are
171 reserved.
172
173 @param Reserved Should be 0.
174
175
176 @return R9 Detail the characteristics of a given
177 processor controlled cache in the cache
178 hierarchy. See PAL_CACHE_INFO_RETURN1.
179
180 @return R10 Detail the characteristics of a given
181 processor controlled cache in the cache
182 hierarchy. See PAL_CACHE_INFO_RETURN2.
183
184 @return R11 Reserved with 0.
185
186
187 @return Status 0 - Call completed without error
188
189 @return Status -2 - Invalid argument
190
191 @return Status -3 - Call completed with error
192
193 **/
194 #define PAL_CACHE_INFO 2
195
196
197
198 //
199 // Level of PAL_CACHE_INIT.
200 //
201 #define PAL_CACHE_INIT_ALL 0xffffffffffffffffULL
202
203 //
204 // Restrict of PAL_CACHE_INIT.
205 //
206 #define PAL_CACHE_INIT_NO_RESTRICT 0
207 #define PAL_CACHE_INIT_RESTRICTED 1
208
209 /**
210
211 Initialize the instruction or data caches. It is required by
212 IPF. The PAL procedure supports the Static Registers calling
213 convention. It could be called at physical mode.
214
215 @param Index Index of PAL_CACHE_INIT within the list of PAL
216 procedures.
217
218 @param Level Unsigned 64-bit integer containing the level of
219 cache to initialize. If the cache level can be
220 initialized independently, only that level will
221 be initialized. Otherwise
222 implementation-dependent side-effects will
223 occur.
224
225 @param CacheType Unsigned 64-bit integer with a value of 1 to
226 initialize the instruction cache, 2 to
227 initialize the data cache, or 3 to
228 initialize both. All other values are
229 reserved.
230
231 @param Restrict Unsigned 64-bit integer with a value of 0 or
232 1. All other values are reserved. If
233 restrict is 1 and initializing the specified
234 level and cache_type of the cache would
235 cause side-effects, PAL_CACHE_INIT will
236 return -4 instead of initializing the cache.
237
238
239 @return Status 0 - Call completed without error
240
241 @return Status -2 - Invalid argument
242
243 @return Status -3 - Call completed with error.
244
245 @return Status -4 - Call could not initialize the specified
246 level and cache_type of the cache without
247 side-effects and restrict was 1.
248
249 **/
250 #define PAL_CACHE_INIT 3
251
252
253 //
254 // PAL_CACHE_PROTECTION.Method.
255 //
256 #define PAL_CACHE_PROTECTION_NONE_PROTECT 0
257 #define PAL_CACHE_PROTECTION_ODD_PROTECT 1
258 #define PAL_CACHE_PROTECTION_EVEN_PROTECT 2
259 #define PAL_CACHE_PROTECTION_ECC_PROTECT 3
260
261
262
263 //
264 // PAL_CACHE_PROTECTION.TagOrData.
265 //
266 #define PAL_CACHE_PROTECTION_PROTECT_DATA 0
267 #define PAL_CACHE_PROTECTION_PROTECT_TAG 1
268 #define PAL_CACHE_PROTECTION_PROTECT_TAG_ANDTHEN_DATA 2
269 #define PAL_CACHE_PROTECTION_PROTECT_DATA_ANDTHEN_TAG 3
270
271 //
272 // 32-bit protection information structures.
273 //
274 typedef struct {
275 UINT32 DataBits:8;
276 UINT32 TagProtLsb:6;
277 UINT32 TagProtMsb:6;
278 UINT32 ProtBits:6;
279 UINT32 Method:4;
280 UINT32 TagOrData:2;
281 } PAL_CACHE_PROTECTION;
282
283 /**
284
285 Return instruction or data cache protection information. It is
286 required by IPF. The PAL procedure supports the Static
287 Registers calling convention. It could be called at physical
288 mode and Virtual mode.
289
290 @param Index Index of PAL_CACHE_PROT_INFO within the list of
291 PAL procedures.
292
293 @param CacheLevel Unsigned 64-bit integer specifying the level
294 in the cache hierarchy for which information
295 is requested. This value must be between 0
296 and one less than the value returned in the
297 cache_levels return value from
298 PAL_CACHE_SUMMARY.
299
300 @param CacheType Unsigned 64-bit integer with a value of 1
301 for instruction cache and 2 for data or
302 unified cache. All other values are
303 reserved.
304
305 @return R9 Detail the characteristics of a given
306 processor controlled cache in the cache
307 hierarchy. See PAL_CACHE_PROTECTION[0..1].
308
309 @return R10 Detail the characteristics of a given
310 processor controlled cache in the cache
311 hierarchy. See PAL_CACHE_PROTECTION[2..3].
312
313 @return R11 Detail the characteristics of a given
314 processor controlled cache in the cache
315 hierarchy. See PAL_CACHE_PROTECTION[4..5].
316
317
318 @return Status 0 - Call completed without error
319
320 @return Status -2 - Invalid argument
321
322 @return Status -3 - Call completed with error.
323
324 **/
325 #define PAL_CACHE_PROT_INFO 38
326
327
328
329
330
331
332
333 ///
334 // ?????????
335
336
337
338 /**
339
340 Returns information on which logical processors share caches.
341 It is optional.
342
343 @param CallingConvention Static Registers
344
345 @param Mode Physical/Virtual
346
347 **/
348 #define PAL_CACHE_SHARED_INFO 43
349
350
351 /**
352
353 Return a summary of the cache hierarchy. It is required by
354 IPF.
355
356 @param CallingConvention Static Registers
357
358 @param Mode Physical/Virtual
359
360 **/
361 #define PAL_CACHE_SUMMARY 4
362
363 /**
364
365 Return a list of supported memory attributes.. It is required
366 by IPF.
367
368 @param CallingConvention Static Registers
369
370 @param Mode Physical/Virtual
371
372 **/
373 #define PAL_MEM_ATTRIB 5
374
375 /**
376
377 Used in architected sequence to transition pages from a
378 cacheable, speculative attribute to an uncacheable attribute.
379 It is required by IPF.
380
381 @param CallingConvention Static Registers
382
383 @param Mode Physical/Virtual
384
385 **/
386 #define PAL_PREFETCH_VISIBILITY 41
387
388 /**
389
390 Return information needed for ptc.e instruction to purge
391 entire TC. It is required by IPF.
392
393 @param CallingConvention Static Registers
394
395 @param Mode Physical/Virtual
396
397 **/
398 #define PAL_PTCE_INFO 6
399
400 /**
401
402 Return detailed information about virtual memory features
403 supported in the processor. It is required by IPF.
404
405 @param CallingConvention Static Registers
406
407 @param Mode Physical/Virtual
408
409 **/
410 #define PAL_VM_INFO 7
411
412
413 /**
414
415 Return virtual memory TC and hardware walker page sizes
416 supported in the processor. It is required by IPF.
417
418 @param CallingConvention Static Registers
419
420 @param Mode Physical
421
422 **/
423 #define PAL_VM_PAGE_SIZE 34
424
425 /**
426
427 Return summary information about virtual memory features
428 supported in the processor. It is required by IPF.
429
430 @param CallingConvention Static Registers
431
432 @param Mode Physical/Virtual
433
434 **/
435 #define PAL_VM_SUMMARY 8
436
437 /**
438
439 Read contents of a translation register. It is required by
440 IPF.
441
442 @param CallingConvention Stacked Register
443
444 @param Mode Physical
445
446 **/
447 #define PAL_VM_TR_READ 261
448
449 /**
450
451 Return configurable processor bus interface features and their
452 current settings. It is required by IPF.
453
454 @param CallingConvention Static Registers
455
456 @param Mode Physical
457
458 **/
459 #define PAL_BUS_GET_FEATURES 9
460
461
462 /**
463
464 Enable or disable configurable features in processor bus
465 interface. It is required by IPF.
466
467 @param CallingConvention Static Registers
468
469 @param Mode Physical
470
471 **/
472 #define PAL_BUS_SET_FEATURES 10
473
474
475 /**
476
477 Return the number of instruction and data breakpoint
478 registers. It is required by IPF.
479
480 @param CallingConvention Static Registers
481
482 @param Mode Physical/Virtual
483
484 **/
485 #define PAL_DEBUG_INFO 11
486
487 /**
488
489 Return the fixed component of a processor¡¯s directed address.
490 It is required by IPF.
491
492 @param CallingConvention Static Registers
493
494 @param Mode Physical/Virtual
495
496 **/
497 #define PAL_FIXED_ADDR 12
498
499 /**
500
501 Return the frequency of the output clock for use by the
502 platform, if generated by the processor. It is optinal.
503
504 @param CallingConvention Static Registers
505
506 @param Mode Physical/Virtual
507
508 **/
509 #define PAL_FREQ_BASE 13
510
511 /**
512
513 Return ratio of processor, bus, and interval time counter to
514 processor input clock or output clock for platform use, if
515 generated by the processor. It is required by IPF.
516
517 @param CallingConvention Static Registers
518
519 @param Mode Physical/Virtual
520
521 **/
522 #define PAL_FREQ_RATIOS 14
523
524 /**
525
526 Return information on which logical processors map to a
527 physical processor die. It is optinal.
528
529 @param CallingConvention Static Registers
530
531 @param Mode Physical/Virtual
532
533 **/
534 #define PAL_LOGICAL_TO_PHYSICAL 42
535
536 /**
537
538 Return the number and type of performance monitors. It is
539 required by IPF.
540
541 @param CallingConvention Static Registers
542
543 @param Mode Physical/Virtual
544
545 **/
546 #define PAL_PERF_MON_INFO 15
547
548 /**
549
550 Specify processor interrupt block address and I/O port space
551 address. It is required by IPF.
552
553 @param CallingConvention Static Registers
554
555 @param Mode Physical/Virtual
556
557 **/
558 #define PAL_PLATFORM_ADDR 16
559
560
561 /**
562
563 Return configurable processor features and their current
564 setting. It is required by IPF.
565
566 @param CallingConvention Static Registers
567
568 @param Mode Physical/Virtual
569
570 **/
571 #define PAL_PROC_GET_FEATURES 17
572
573
574 /**
575
576 Enable or disable configurable processor features. It is
577 required by IPF.
578
579 @param CallingConvention Static Registers
580
581 @param Mode Physical
582
583 **/
584 #define PAL_PROC_SET_FEATURES 18
585
586 /**
587
588 Return AR and CR register information. It is required by IPF.
589
590 @param CallingConvention Static Registers
591
592 @param Mode Physical/Virtual
593
594 **/
595 #define PAL_REGISTER_INFO 39
596
597 /**
598
599 Return RSE information. It is required by
600 IPF.
601
602 @param CallingConvention Static Registers
603
604 @param Mode Physical/Virtual
605
606 **/
607 #define PAL_RSE_INFO 19
608
609 /**
610
611 Return version of PAL code. It is required by IPF.
612
613 @param CallingConvention Static Registers
614
615 @param Mode Physical/Virtual
616
617 **/
618 #define PAL_VERSION 20
619
620 /**
621
622 Clear all error information from processor error logging
623 registers. It is required by IPF.
624
625 @param CallingConvention Static Registers
626
627 @param Mode Physical/Virtual
628
629 **/
630 #define PAL_MC_CLEAR_LOG 21
631
632 /**
633
634 Ensure that all operations that could cause an MCA have
635 completed. It is required by IPF.
636
637 @param CallingConvention Static Registers
638
639 @param Mode Physical/Virtual
640
641 **/
642 #define PAL_MC_DRAIN 22
643
644 /**
645
646 Return Processor Dynamic State for logging by SAL. It is
647 optional.
648
649 @param CallingConvention Static Registers
650
651 @param Mode Physical
652
653 **/
654 #define PAL_MC_DYNAMIC_STATE 24
655
656 /**
657
658 Return Processor Machine Check Information and Processor
659 Static State for logging by SAL. It is required by IPF.
660
661 @param CallingConvention Static Registers
662
663 @param Mode Physical/Virtual
664
665 **/
666 #define PAL_MC_ERROR_INFO 25 Req. Static Both
667
668 /**
669
670 Set/Reset Expected Machine Check Indicator. It is required by
671 IPF.
672
673 @param CallingConvention Static Registers
674
675 @param Mode Physical
676
677 **/
678 #define PAL_MC_EXPECTED 23
679
680 /**
681
682 Register min-state save area with PAL for machine checks and
683 inits. It is required by IPF.
684
685 @param CallingConvention Static Registers
686
687 @param Mode Physical
688
689 **/
690 #define PAL_MC_REGISTER_MEM 27
691
692 /**
693
694 Restore minimal architected state and return to interrupted
695 process. It is required by IPF.
696
697 @param CallingConvention Static Registers
698
699 @param Mode Physical
700
701 **/
702 #define PAL_MC_RESUME 26
703
704 /**
705
706 Enter the low-power HALT state or an implementation-dependent
707 low-power state. It is optinal.
708
709 @param CallingConvention Static Registers
710
711 @param Mode Physical
712
713 **/
714 #define PAL_HALT 28
715
716
717 /**
718
719 Return the low power capabilities of the processor. It is
720 required by IPF.
721
722 @param CallingConvention Stacked Register
723
724 @param Mode Physical/Virtual
725
726 **/
727 #define PAL_HALT_INFO 257
728
729
730 /**
731
732 Enter the low power LIGHT HALT state. It is required by
733 IPF.
734
735 @param CallingConvention Static Registers
736
737 @param Mode Physical/Virtual
738
739 **/
740 #define PAL_HALT_LIGHT 29
741
742 /**
743
744 Initialize tags and data of a cache line for processor
745 testing. It is required by IPF.
746
747 @param CallingConvention Static Registers
748
749 @param Mode Physical
750
751 **/
752 #define PAL_CACHE_LINE_INIT 31
753
754 /**
755
756 Read tag and data of a cache line for diagnostic testing. It
757 is optional.
758
759 @param CallingConvention Satcked Register
760
761 @param Mode Physical
762
763 **/
764 #define PAL_CACHE_READ 259
765
766 /**
767
768 Write tag and data of a cache for diagnostic testing. It is
769 optional.
770
771 @param CallingConvention Satcked Registers
772
773 @param Mode Physical
774
775 **/
776 #define PAL_CACHE_WRITE 260
777
778 /**
779
780 Returns alignment and size requirements needed for the memory
781 buffer passed to the PAL_TEST_PROC procedure as well as
782 information on self-test control words for the processor self
783 tests. It is required by IPF.
784
785 @param CallingConvention Static Registers
786
787 @param Mode Physical
788
789 **/
790 #define PAL_TEST_INFO 37
791
792 /**
793
794 Perform late processor self test. It is required by
795 IPF.
796
797 @param CallingConvention Stacked Registers
798
799 @param Mode Physical
800
801 **/
802 #define PAL_TEST_PROC 258
803
804 /**
805
806 Return information needed to relocate PAL procedures and PAL
807 PMI code to memory. It is required by IPF.
808
809 @param CallingConvention Static Registers
810
811 @param Mode Physical
812
813 **/
814 #define PAL_COPY_INFO 30
815
816 /**
817
818 Relocate PAL procedures and PAL PMI code to memory. It is
819 required by IPF.
820
821 @param CallingConvention Stacked Registers
822
823 @param Mode Physical
824
825 **/
826 #define PAL_COPY_PAL 256
827
828 /**
829
830 Enter IA-32 System environment. It is optional.
831
832 @param CallingConvention Static Registers
833
834 @param Mode Physical
835
836 **/
837 #define PAL_ENTER_IA_32_ENV 33
838
839 /**
840
841 Register PMI memory entrypoints with processor. It is required
842 by IPF.
843
844 @param CallingConvention Static Registers
845
846 @param Mode Physical
847
848 **/
849 #define PAL_PMI_ENTRYPOINT 32
850
851
852
853 #endif