1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
|
/** @file
STM API definition
Copyright (c) 2015 - 2016, Intel Corporation. All rights reserved.<BR>
SPDX-License-Identifier: BSD-2-Clause-Patent
@par Specification Reference:
SMI Transfer Monitor (STM) User Guide Revision 1.00
**/
#ifndef _STM_API_H_
#define _STM_API_H_
#include <Register/StmStatusCode.h>
#include <Register/StmResourceDescriptor.h>
#include <Register/ArchitecturalMsr.h>
#pragma pack (1)
/**
STM Header Structures
**/
typedef struct {
UINT32 Intel64ModeSupported :1; ///> bitfield
UINT32 EptSupported :1; ///> bitfield
UINT32 Reserved :30; ///> must be 0
} STM_FEAT;
#define STM_SPEC_VERSION_MAJOR 1
#define STM_SPEC_VERSION_MINOR 0
typedef struct {
UINT8 StmSpecVerMajor;
UINT8 StmSpecVerMinor;
///
/// Must be zero
///
UINT16 Reserved;
UINT32 StaticImageSize;
UINT32 PerProcDynamicMemorySize;
UINT32 AdditionalDynamicMemorySize;
STM_FEAT StmFeatures;
UINT32 NumberOfRevIDs;
UINT32 StmSmmRevID[1];
///
/// The total STM_HEADER should be 4K.
///
} SOFTWARE_STM_HEADER;
typedef struct {
MSEG_HEADER HwStmHdr;
SOFTWARE_STM_HEADER SwStmHdr;
} STM_HEADER;
/**
VMCALL API Numbers
API number convention: BIOS facing VMCALL interfaces have bit 16 clear
**/
/**
StmMapAddressRange enables a SMM guest to create a non-1:1 virtual to
physical mapping of an address range into the SMM guest's virtual
memory space.
@param EAX #STM_API_MAP_ADDRESS_RANGE (0x00000001)
@param EBX Low 32 bits of physical address of caller allocated
STM_MAP_ADDRESS_RANGE_DESCRIPTOR structure.
@param ECX High 32 bits of physical address of caller allocated
STM_MAP_ADDRESS_RANGE_DESCRIPTOR structure. If Intel64Mode is
clear (0), ECX must be 0.
@note All fields of STM_MAP_ADDRESS_RANGE_DESCRIPTOR are inputs only. They
are not modified by StmMapAddressRange.
@retval CF 0
No error, EAX set to STM_SUCCESS.
The memory range was mapped as requested.
@retval CF 1
An error occurred, EAX holds relevant error value.
@retval EAX #ERROR_STM_SECURITY_VIOLATION
The requested mapping contains a protected resource.
@retval EAX #ERROR_STM_CACHE_TYPE_NOT_SUPPORTED
The requested cache type could not be satisfied.
@retval EAX #ERROR_STM_PAGE_NOT_FOUND
Page count must not be zero.
@retval EAX #ERROR_STM_FUNCTION_NOT_SUPPORTED
STM supports EPT and has not implemented StmMapAddressRange().
@retval EAX #ERROR_STM_UNSPECIFIED
An unspecified error occurred.
@note All other registers unmodified.
**/
#define STM_API_MAP_ADDRESS_RANGE 0x00000001
/**
STM Map Address Range Descriptor for #STM_API_MAP_ADDRESS_RANGE VMCALL
**/
typedef struct {
UINT64 PhysicalAddress;
UINT64 VirtualAddress;
UINT32 PageCount;
UINT32 PatCacheType;
} STM_MAP_ADDRESS_RANGE_DESCRIPTOR;
/**
Define values for PatCacheType field of #STM_MAP_ADDRESS_RANGE_DESCRIPTOR
@{
**/
#define STM_MAP_ADDRESS_RANGE_PAT_CACHE_TYPE_ST_UC 0x00
#define STM_MAP_ADDRESS_RANGE_PAT_CACHE_TYPE_WC 0x01
#define STM_MAP_ADDRESS_RANGE_PAT_CACHE_TYPE_WT 0x04
#define STM_MAP_ADDRESS_RANGE_PAT_CACHE_TYPE_WP 0x05
#define STM_MAP_ADDRESS_RANGE_PAT_CACHE_TYPE_WB 0x06
#define STM_MAP_ADDRESS_RANGE_PAT_CACHE_TYPE_UC 0x07
#define STM_MAP_ADDRESS_RANGE_PAT_CACHE_TYPE_FOLLOW_MTRR 0xFFFFFFFF
/// @}
/**
StmUnmapAddressRange enables a SMM guest to remove mappings from its page
table.
If TXT_PROCESSOR_SMM_DESCRIPTOR.EptEnabled bit is set by the STM, BIOS can
control its own page tables. In this case, the STM implementation may
optionally return ERROR_STM_FUNCTION_NOT_SUPPORTED.
@param EAX #STM_API_UNMAP_ADDRESS_RANGE (0x00000002)
@param EBX Low 32 bits of virtual address of caller allocated
STM_UNMAP_ADDRESS_RANGE_DESCRIPTOR structure.
@param ECX High 32 bits of virtual address of caller allocated
STM_UNMAP_ADDRESS_RANGE_DESCRIPTOR structure. If Intel64Mode is
clear (0), ECX must be zero.
@retval CF 0
No error, EAX set to STM_SUCCESS. The memory range was unmapped
as requested.
@retval CF 1
An error occurred, EAX holds relevant error value.
@retval EAX #ERROR_STM_FUNCTION_NOT_SUPPORTED
STM supports EPT and has not implemented StmUnmapAddressRange().
@retval EAX #ERROR_STM_UNSPECIFIED
An unspecified error occurred.
@note All other registers unmodified.
**/
#define STM_API_UNMAP_ADDRESS_RANGE 0x00000002
/**
STM Unmap Address Range Descriptor for #STM_API_UNMAP_ADDRESS_RANGE VMCALL
**/
typedef struct {
UINT64 VirtualAddress;
UINT32 Length;
} STM_UNMAP_ADDRESS_RANGE_DESCRIPTOR;
/**
Since the normal OS environment runs with a different set of page tables than
the SMM guest, virtual mappings will certainly be different. In order to do a
guest virtual to host physical translation of an address from the normal OS
code (EIP for example), it is necessary to walk the page tables governing the
OS page mappings. Since the SMM guest has no direct access to the page tables,
it must ask the STM to do this page table walk. This is supported via the
StmAddressLookup VMCALL. All OS page table formats need to be supported,
(e.g. PAE, PSE, Intel64, EPT, etc.)
StmAddressLookup takes a CR3 value and a virtual address from the interrupted
code as input and returns the corresponding physical address. It also
optionally maps the physical address into the SMM guest's virtual address
space. This new mapping persists ONLY for the duration of the SMI and if
needed in subsequent SMIs it must be remapped. PAT cache types follow the
interrupted environment's page table.
If EPT is enabled, OS CR3 only provides guest physical address information,
but the SMM guest might also need to know the host physical address. Since
SMM does not have direct access rights to EPT (it is protected by the STM),
SMM can input InterruptedEptp to let STM help to walk through it, and output
the host physical address.
@param EAX #STM_API_ADDRESS_LOOKUP (0x00000003)
@param EBX Low 32 bits of virtual address of caller allocated
STM_ADDRESS_LOOKUP_DESCRIPTOR structure.
@param ECX High 32 bits of virtual address of caller allocated
STM_ADDRESS_LOOKUP_DESCRIPTOR structure. If Intel64Mode is
clear (0), ECX must be zero.
@retval CF 0
No error, EAX set to STM_SUCCESS. PhysicalAddress contains the
host physical address determined by walking the interrupted SMM
guest's page tables. SmmGuestVirtualAddress contains the SMM
guest's virtual mapping of the requested address.
@retval CF 1
An error occurred, EAX holds relevant error value.
@retval EAX #ERROR_STM_SECURITY_VIOLATION
The requested page was a protected page.
@retval EAX #ERROR_STM_PAGE_NOT_FOUND
The requested virtual address did not exist in the page given
page table.
@retval EAX #ERROR_STM_BAD_CR3
The CR3 input was invalid. CR3 values must be from one of the
interrupted guest, or from the interrupted guest of another
processor.
@retval EAX #ERROR_STM_PHYSICAL_OVER_4G
The resulting physical address is greater than 4G and no virtual
address was supplied. The STM could not determine what address
within the SMM guest's virtual address space to do the mapping.
STM_ADDRESS_LOOKUP_DESCRIPTOR field PhysicalAddress contains the
physical address determined by walking the interrupted
environment's page tables.
@retval EAX #ERROR_STM_VIRTUAL_SPACE_TOO_SMALL
A specific virtual mapping was requested, but
SmmGuestVirtualAddress + Length exceeds 4G and the SMI handler
is running in 32 bit mode.
@retval EAX #ERROR_STM_UNSPECIFIED
An unspecified error occurred.
@note All other registers unmodified.
**/
#define STM_API_ADDRESS_LOOKUP 0x00000003
/**
STM Lookup Address Range Descriptor for #STM_API_ADDRESS_LOOKUP VMCALL
**/
typedef struct {
UINT64 InterruptedGuestVirtualAddress;
UINT32 Length;
UINT64 InterruptedCr3;
UINT64 InterruptedEptp;
UINT32 MapToSmmGuest:2;
UINT32 InterruptedCr4Pae:1;
UINT32 InterruptedCr4Pse:1;
UINT32 InterruptedIa32eMode:1;
UINT32 Reserved1:27;
UINT32 Reserved2;
UINT64 PhysicalAddress;
UINT64 SmmGuestVirtualAddress;
} STM_ADDRESS_LOOKUP_DESCRIPTOR;
/**
Define values for the MapToSmmGuest field of #STM_ADDRESS_LOOKUP_DESCRIPTOR
@{
**/
#define STM_ADDRESS_LOOKUP_DESCRIPTOR_DO_NOT_MAP 0
#define STM_ADDRESS_LOOKUP_DESCRIPTOR_ONE_TO_ONE 1
#define STM_ADDRESS_LOOKUP_DESCRIPTOR_VIRTUAL_ADDRESS_SPECIFIED 3
/// @}
/**
When returning from a protection exception (see section 6.2), the SMM guest
can instruct the STM to take one of two paths. It can either request a value
be logged to the TXT.ERRORCODE register and subsequently reset the machine
(indicating it couldn't resolve the problem), or it can request that the STM
resume the SMM guest again with the specified register state.
Unlike other VMCALL interfaces, StmReturnFromProtectionException behaves more
like a jump or an IRET instruction than a "call". It does not return directly
to the caller, but indirectly to a different location specified on the
caller's stack (see section 6.2) or not at all.
If the SMM guest STM protection exception handler itself causes a protection
exception (e.g. a single nested exception), or more than 100 un-nested
exceptions occur within the scope of a single SMI event, the STM must write
STM_CRASH_PROTECTION_EXCEPTION_FAILURE to the TXT.ERRORCODE register and
assert TXT.CMD.SYS_RESET. The reason for these restrictions is to simplify
the code requirements while still enabling a reasonable debugging capability.
@param EAX #STM_API_RETURN_FROM_PROTECTION_EXCEPTION (0x00000004)
@param EBX If 0, resume SMM guest using register state found on exception
stack. If in range 0x01..0x0F, EBX contains a BIOS error code
which the STM must record in the TXT.ERRORCODE register and
subsequently reset the system via TXT.CMD.SYS_RESET. The value
of the TXT.ERRORCODE register is calculated as follows:
TXT.ERRORCODE = (EBX & 0x0F) | STM_CRASH_BIOS_PANIC
Values 0x10..0xFFFFFFFF are reserved, do not use.
**/
#define STM_API_RETURN_FROM_PROTECTION_EXCEPTION 0x00000004
/**
VMCALL API Numbers
API number convention: MLE facing VMCALL interfaces have bit 16 set.
The STM configuration lifecycle is as follows:
1. SENTER->SINIT->MLE: MLE begins execution with SMI disabled (masked).
2. MLE invokes #STM_API_INITIALIZE_PROTECTION VMCALL to prepare STM for
setup of initial protection profile. This is done on a single CPU and
has global effect.
3. MLE invokes #STM_API_PROTECT_RESOURCE VMCALL to define the initial
protection profile. The protection profile is global across all CPUs.
4. MLE invokes #STM_API_START VMCALL to enable the STM to begin receiving
SMI events. This must be done on every logical CPU.
5. MLE may invoke #STM_API_PROTECT_RESOURCE VMCALL or
#STM_API_UNPROTECT_RESOURCE VMCALL during runtime as many times as
necessary.
6. MLE invokes #STM_API_STOP VMCALL to disable the STM. SMI is again masked
following #STM_API_STOP VMCALL.
**/
/**
StartStmVmcall() is used to configure an STM that is present in MSEG. SMIs
should remain disabled from the invocation of GETSEC[SENTER] until they are
re-enabled by StartStmVMCALL(). When StartStmVMCALL() returns, SMI is
enabled and the STM has been started and is active. Prior to invoking
StartStmVMCALL(), the MLE root should first invoke
InitializeProtectionVMCALL() followed by as many iterations of
ProtectResourceVMCALL() as necessary to establish the initial protection
profile. StartStmVmcall() must be invoked on all processor threads.
@param EAX #STM_API_START (0x00010001)
@param EDX STM configuration options. These provide the MLE with the
ability to pass configuration parameters to the STM.
@retval CF 0
No error, EAX set to STM_SUCCESS. The STM has been configured
and is now active and the guarding all requested resources.
@retval CF 1
An error occurred, EAX holds relevant error value.
@retval EAX #ERROR_STM_ALREADY_STARTED
The STM is already configured and active. STM remains active and
guarding previously enabled resource list.
@retval EAX #ERROR_STM_WITHOUT_SMX_UNSUPPORTED
The StartStmVMCALL() was invoked from VMX root mode, but outside
of SMX. This error code indicates the STM or platform does not
support the STM outside of SMX. The SMI handler remains active
and operates in legacy mode. See Appendix C
@retval EAX #ERROR_STM_UNSUPPORTED_MSR_BIT
The CPU doesn't support the MSR bit. The STM is not active.
@retval EAX #ERROR_STM_UNSPECIFIED
An unspecified error occurred.
@note All other registers unmodified.
**/
#define STM_API_START (BIT16 | 1)
/**
Bit values for EDX input parameter to #STM_API_START VMCALL
@{
**/
#define STM_CONFIG_SMI_UNBLOCKING_BY_VMX_OFF BIT0
/// @}
/**
The StopStmVMCALL() is invoked by the MLE to teardown an active STM. This is
normally done as part of a full teardown of the SMX environment when the
system is being shut down. At the time the call is invoked, SMI is enabled
and the STM is active. When the call returns, the STM has been stopped and
all STM context is discarded and SMI is disabled.
@param EAX #STM_API_STOP (0x00010002)
@retval CF 0
No error, EAX set to STM_SUCCESS. The STM has been stopped and
is no longer processing SMI events. SMI is blocked.
@retval CF 1
An error occurred, EAX holds relevant error value.
@retval EAX #ERROR_STM_STOPPED
The STM was not active.
@retval EAX #ERROR_STM_UNSPECIFIED
An unspecified error occurred.
@note All other registers unmodified.
**/
#define STM_API_STOP (BIT16 | 2)
/**
The ProtectResourceVMCALL() is invoked by the MLE root to request protection
of specific resources. The request is defined by a STM_RESOURCE_LIST, which
may contain more than one resource descriptor. Each resource descriptor is
processed separately by the STM. Whether or not protection for any specific
resource is granted is returned by the STM via the ReturnStatus bit in the
associated STM_RSC_DESC_HEADER.
@param EAX #STM_API_PROTECT_RESOURCE (0x00010003)
@param EBX Low 32 bits of physical address of caller allocated
STM_RESOURCE_LIST. Bits 11:0 are ignored and assumed to be zero,
making the buffer 4K aligned.
@param ECX High 32 bits of physical address of caller allocated
STM_RESOURCE_LIST.
@note All fields of STM_RESOURCE_LIST are inputs only, except for the
ReturnStatus bit. On input, the ReturnStatus bit must be clear. On
return, the ReturnStatus bit is set for each resource request granted,
and clear for each resource request denied. There are no other fields
modified by ProtectResourceVMCALL(). The STM_RESOURCE_LIST must be
contained entirely within a single 4K page.
@retval CF 0
No error, EAX set to STM_SUCCESS. The STM has successfully
merged the entire protection request into the active protection
profile. There is therefore no need to check the ReturnStatus
bits in the STM_RESOURCE_LIST.
@retval CF 1
An error occurred, EAX holds relevant error value.
@retval EAX #ERROR_STM_UNPROTECTABLE_RESOURCE
At least one of the requested resource protections intersects a
BIOS required resource. Therefore, the caller must walk through
the STM_RESOURCE_LIST to determine which of the requested
resources was not granted protection. The entire list must be
traversed since there may be multiple failures.
@retval EAX #ERROR_STM_MALFORMED_RESOURCE_LIST
The resource list could not be parsed correctly, or did not
terminate before crossing a 4K page boundary. The caller must
walk through the STM_RESOURCE_LIST to determine which of the
requested resources was not granted protection. The entire list
must be traversed since there may be multiple failures.
@retval EAX #ERROR_STM_OUT_OF_RESOURCES
The STM has encountered an internal error and cannot complete
the request.
@retval EAX #ERROR_STM_UNSPECIFIED
An unspecified error occurred.
@note All other registers unmodified.
**/
#define STM_API_PROTECT_RESOURCE (BIT16 | 3)
/**
The UnProtectResourceVMCALL() is invoked by the MLE root to request that the
STM allow the SMI handler access to the specified resources.
@param EAX #STM_API_UNPROTECT_RESOURCE (0x00010004)
@param EBX Low 32 bits of physical address of caller allocated
STM_RESOURCE_LIST. Bits 11:0 are ignored and assumed to be zero,
making the buffer 4K aligned.
@param ECX High 32 bits of physical address of caller allocated
STM_RESOURCE_LIST.
@note All fields of STM_RESOURCE_LIST are inputs only, except for the
ReturnStatus bit. On input, the ReturnStatus bit must be clear. On
return, the ReturnStatus bit is set for each resource processed. For
a properly formed STM_RESOURCE_LIST, this should be all resources
listed. There are no other fields modified by
UnProtectResourceVMCALL(). The STM_RESOURCE_LIST must be contained
entirely within a single 4K page.
@retval CF 0
No error, EAX set to STM_SUCCESS. The requested resources are
not being guarded by the STM.
@retval CF 1
An error occurred, EAX holds relevant error value.
@retval EAX #ERROR_STM_MALFORMED_RESOURCE_LIST
The resource list could not be parsed correctly, or did not
terminate before crossing a 4K page boundary. The caller must
walk through the STM_RESOURCE_LIST to determine which of the
requested resources were not able to be unprotected. The entire
list must be traversed since there may be multiple failures.
@retval EAX #ERROR_STM_UNSPECIFIED
An unspecified error occurred.
@note All other registers unmodified.
**/
#define STM_API_UNPROTECT_RESOURCE (BIT16 | 4)
/**
The GetBiosResourcesVMCALL() is invoked by the MLE root to request the list
of BIOS required resources from the STM.
@param EAX #STM_API_GET_BIOS_RESOURCES (0x00010005)
@param EBX Low 32 bits of physical address of caller allocated destination
buffer. Bits 11:0 are ignored and assumed to be zero, making the
buffer 4K aligned.
@param ECX High 32 bits of physical address of caller allocated destination
buffer.
@param EDX Indicates which page of the BIOS resource list to copy into the
destination buffer. The first page is indicated by 0, the second
page by 1, etc.
@retval CF 0
No error, EAX set to STM_SUCCESS. The destination buffer
contains the BIOS required resources. If the page retrieved is
the last page, EDX will be cleared to 0. If there are more pages
to retrieve, EDX is incremented to the next page index. Calling
software should iterate on GetBiosResourcesVMCALL() until EDX is
returned cleared to 0.
@retval CF 1
An error occurred, EAX holds relevant error value.
@retval EAX #ERROR_STM_PAGE_NOT_FOUND
The page index supplied in EDX input was out of range.
@retval EAX #ERROR_STM_UNSPECIFIED
An unspecified error occurred.
@retval EDX Page index of next page to read. A return of EDX=0 signifies
that the entire list has been read.
@note EDX is both an input and an output register.
@note All other registers unmodified.
**/
#define STM_API_GET_BIOS_RESOURCES (BIT16 | 5)
/**
The ManageVmcsDatabaseVMCALL() is invoked by the MLE root to add or remove an
MLE guest (including the MLE root) from the list of protected domains.
@param EAX #STM_API_MANAGE_VMCS_DATABASE (0x00010006)
@param EBX Low 32 bits of physical address of caller allocated
STM_VMCS_DATABASE_REQUEST. Bits 11:0 are ignored and assumed to
be zero, making the buffer 4K aligned.
@param ECX High 32 bits of physical address of caller allocated
STM_VMCS_DATABASE_REQUEST.
@note All fields of STM_VMCS_DATABASE_REQUEST are inputs only. They are not
modified by ManageVmcsDatabaseVMCALL().
@retval CF 0
No error, EAX set to STM_SUCCESS.
@retval CF 1
An error occurred, EAX holds relevant error value.
@retval EAX #ERROR_STM_INVALID_VMCS
Indicates a request to remove a VMCS from the database was made,
but the referenced VMCS was not found in the database.
@retval EAX #ERROR_STM_VMCS_PRESENT
Indicates a request to add a VMCS to the database was made, but
the referenced VMCS was already present in the database.
@retval EAX #ERROR_INVALID_PARAMETER
Indicates non-zero reserved field.
@retval EAX #ERROR_STM_UNSPECIFIED
An unspecified error occurred
@note All other registers unmodified.
**/
#define STM_API_MANAGE_VMCS_DATABASE (BIT16 | 6)
/**
STM VMCS Database Request for #STM_API_MANAGE_VMCS_DATABASE VMCALL
**/
typedef struct {
///
/// bits 11:0 are reserved and must be 0
///
UINT64 VmcsPhysPointer;
UINT32 DomainType :4;
UINT32 XStatePolicy :2;
UINT32 DegradationPolicy :4;
///
/// Must be 0
///
UINT32 Reserved1 :22;
UINT32 AddOrRemove;
} STM_VMCS_DATABASE_REQUEST;
/**
Values for the DomainType field of #STM_VMCS_DATABASE_REQUEST
@{
**/
#define DOMAIN_UNPROTECTED 0
#define DOMAIN_DISALLOWED_IO_OUT BIT0
#define DOMAIN_DISALLOWED_IO_IN BIT1
#define DOMAIN_INTEGRITY BIT2
#define DOMAIN_CONFIDENTIALITY BIT3
#define DOMAIN_INTEGRITY_PROT_OUT_IN (DOMAIN_INTEGRITY)
#define DOMAIN_FULLY_PROT_OUT_IN (DOMAIN_CONFIDENTIALITY | DOMAIN_INTEGRITY)
#define DOMAIN_FULLY_PROT (DOMAIN_FULLY_PROT_OUT_IN | DOMAIN_DISALLOWED_IO_IN | DOMAIN_DISALLOWED_IO_OUT)
/// @}
/**
Values for the XStatePolicy field of #STM_VMCS_DATABASE_REQUEST
@{
**/
#define XSTATE_READWRITE 0x00
#define XSTATE_READONLY 0x01
#define XSTATE_SCRUB 0x03
/// @}
/**
Values for the AddOrRemove field of #STM_VMCS_DATABASE_REQUEST
@{
**/
#define STM_VMCS_DATABASE_REQUEST_ADD 1
#define STM_VMCS_DATABASE_REQUEST_REMOVE 0
/// @}
/**
InitializeProtectionVMCALL() prepares the STM for setup of the initial
protection profile which is subsequently communicated via one or more
invocations of ProtectResourceVMCALL(), prior to invoking StartStmVMCALL().
It is only necessary to invoke InitializeProtectionVMCALL() on one processor
thread. InitializeProtectionVMCALL() does not alter whether SMIs are masked
or unmasked. The STM should return back to the MLE with "Blocking by SMI" set
to 1 in the GUEST_INTERRUPTIBILITY field for the VMCS the STM created for the
MLE guest.
@param EAX #STM_API_INITIALIZE_PROTECTION (0x00010007)
@retval CF 0
No error, EAX set to STM_SUCCESS, EBX bits set to indicate STM
capabilities as defined below. The STM has set up an empty
protection profile, except for the resources that it sets up to
protect itself. The STM must not allow the SMI handler to map
any pages from the MSEG Base to the top of TSEG. The STM must
also not allow SMI handler access to those MSRs which the STM
requires for its own protection.
@retval CF 1
An error occurred, EAX holds relevant error value.
@retval EAX #ERROR_STM_ALREADY_STARTED
The STM is already configured and active. The STM remains active
and guarding the previously enabled resource list.
@retval EAX #ERROR_STM_UNPROTECTABLE
The STM determines that based on the platform configuration, the
STM is unable to protect itself. For example, the BIOS required
resource list contains memory pages in MSEG.
@retval EAX #ERROR_STM_UNSPECIFIED
An unspecified error occurred.
@note All other registers unmodified.
**/
#define STM_API_INITIALIZE_PROTECTION (BIT16 | 7)
/**
Byte granular support bits returned in EBX from #STM_API_INITIALIZE_PROTECTION
@{
**/
#define STM_RSC_BGI BIT1
#define STM_RSC_BGM BIT2
#define STM_RSC_MSR BIT3
/// @}
/**
The ManageEventLogVMCALL() is invoked by the MLE root to control the logging
feature. It consists of several sub-functions to facilitate establishment of
the log itself, configuring what events will be logged, and functions to
start, stop, and clear the log.
@param EAX #STM_API_MANAGE_EVENT_LOG (0x00010008)
@param EBX Low 32 bits of physical address of caller allocated
STM_EVENT_LOG_MANAGEMENT_REQUEST. Bits 11:0 are ignored and
assumed to be zero, making the buffer 4K aligned.
@param ECX High 32 bits of physical address of caller allocated
STM_EVENT_LOG_MANAGEMENT_REQUEST.
@retval CF=0
No error, EAX set to STM_SUCCESS.
@retval CF=1
An error occurred, EAX holds relevant error value. See subfunction
descriptions below for details.
@note All other registers unmodified.
**/
#define STM_API_MANAGE_EVENT_LOG (BIT16 | 8)
///
/// STM Event Log Management Request for #STM_API_MANAGE_EVENT_LOG VMCALL
///
typedef struct {
UINT32 SubFunctionIndex;
union {
struct {
UINT32 PageCount;
//
// number of elements is PageCount
//
UINT64 Pages[];
} LogBuffer;
//
// bitmap of EVENT_TYPE
//
UINT32 EventEnableBitmap;
} Data;
} STM_EVENT_LOG_MANAGEMENT_REQUEST;
/**
Defines values for the SubFunctionIndex field of
#STM_EVENT_LOG_MANAGEMENT_REQUEST
@{
**/
#define STM_EVENT_LOG_MANAGEMENT_REQUEST_NEW_LOG 1
#define STM_EVENT_LOG_MANAGEMENT_REQUEST_CONFIGURE_LOG 2
#define STM_EVENT_LOG_MANAGEMENT_REQUEST_START_LOG 3
#define STM_EVENT_LOG_MANAGEMENT_REQUEST_STOP_LOG 4
#define STM_EVENT_LOG_MANAGEMENT_REQUEST_CLEAR_LOG 5
#define STM_EVENT_LOG_MANAGEMENT_REQUEST_DELETE_LOG 6
/// @}
/**
Log Entry Header
**/
typedef struct {
UINT32 EventSerialNumber;
UINT16 Type;
UINT16 Lock :1;
UINT16 Valid :1;
UINT16 ReadByMle :1;
UINT16 Wrapped :1;
UINT16 Reserved :12;
} LOG_ENTRY_HEADER;
/**
Enum values for the Type field of #LOG_ENTRY_HEADER
**/
typedef enum {
EvtLogStarted,
EvtLogStopped,
EvtLogInvalidParameterDetected,
EvtHandledProtectionException,
///
/// unhandled protection exceptions result in reset & cannot be logged
///
EvtBiosAccessToUnclaimedResource,
EvtMleResourceProtectionGranted,
EvtMleResourceProtectionDenied,
EvtMleResourceUnprotect,
EvtMleResourceUnprotectError,
EvtMleDomainTypeDegraded,
///
/// add more here
///
EvtMleMax,
///
/// Not used
///
EvtInvalid = 0xFFFFFFFF,
} EVENT_TYPE;
typedef struct {
UINT32 Reserved;
} ENTRY_EVT_LOG_STARTED;
typedef struct {
UINT32 Reserved;
} ENTRY_EVT_LOG_STOPPED;
typedef struct {
UINT32 VmcallApiNumber;
} ENTRY_EVT_LOG_INVALID_PARAM;
typedef struct {
STM_RSC Resource;
} ENTRY_EVT_LOG_HANDLED_PROTECTION_EXCEPTION;
typedef struct {
STM_RSC Resource;
} ENTRY_EVT_BIOS_ACCESS_UNCLAIMED_RSC;
typedef struct {
STM_RSC Resource;
} ENTRY_EVT_MLE_RSC_PROT_GRANTED;
typedef struct {
STM_RSC Resource;
} ENTRY_EVT_MLE_RSC_PROT_DENIED;
typedef struct {
STM_RSC Resource;
} ENTRY_EVT_MLE_RSC_UNPROT;
typedef struct {
STM_RSC Resource;
} ENTRY_EVT_MLE_RSC_UNPROT_ERROR;
typedef struct {
UINT64 VmcsPhysPointer;
UINT8 ExpectedDomainType;
UINT8 DegradedDomainType;
} ENTRY_EVT_MLE_DOMAIN_TYPE_DEGRADED;
typedef union {
ENTRY_EVT_LOG_STARTED Started;
ENTRY_EVT_LOG_STOPPED Stopped;
ENTRY_EVT_LOG_INVALID_PARAM InvalidParam;
ENTRY_EVT_LOG_HANDLED_PROTECTION_EXCEPTION HandledProtectionException;
ENTRY_EVT_BIOS_ACCESS_UNCLAIMED_RSC BiosUnclaimedRsc;
ENTRY_EVT_MLE_RSC_PROT_GRANTED MleRscProtGranted;
ENTRY_EVT_MLE_RSC_PROT_DENIED MleRscProtDenied;
ENTRY_EVT_MLE_RSC_UNPROT MleRscUnprot;
ENTRY_EVT_MLE_RSC_UNPROT_ERROR MleRscUnprotError;
ENTRY_EVT_MLE_DOMAIN_TYPE_DEGRADED MleDomainTypeDegraded;
} LOG_ENTRY_DATA;
typedef struct {
LOG_ENTRY_HEADER Hdr;
LOG_ENTRY_DATA Data;
} STM_LOG_ENTRY;
/**
Maximum STM Log Entry Size
**/
#define STM_LOG_ENTRY_SIZE 256
/**
STM Protection Exception Stack Frame Structures
**/
typedef struct {
UINT32 Rdi;
UINT32 Rsi;
UINT32 Rbp;
UINT32 Rdx;
UINT32 Rcx;
UINT32 Rbx;
UINT32 Rax;
UINT32 Cr3;
UINT32 Cr2;
UINT32 Cr0;
UINT32 VmcsExitInstructionInfo;
UINT32 VmcsExitInstructionLength;
UINT64 VmcsExitQualification;
///
/// An TXT_SMM_PROTECTION_EXCEPTION_TYPE num value
///
UINT32 ErrorCode;
UINT32 Rip;
UINT32 Cs;
UINT32 Rflags;
UINT32 Rsp;
UINT32 Ss;
} STM_PROTECTION_EXCEPTION_STACK_FRAME_IA32;
typedef struct {
UINT64 R15;
UINT64 R14;
UINT64 R13;
UINT64 R12;
UINT64 R11;
UINT64 R10;
UINT64 R9;
UINT64 R8;
UINT64 Rdi;
UINT64 Rsi;
UINT64 Rbp;
UINT64 Rdx;
UINT64 Rcx;
UINT64 Rbx;
UINT64 Rax;
UINT64 Cr8;
UINT64 Cr3;
UINT64 Cr2;
UINT64 Cr0;
UINT64 VmcsExitInstructionInfo;
UINT64 VmcsExitInstructionLength;
UINT64 VmcsExitQualification;
///
/// An TXT_SMM_PROTECTION_EXCEPTION_TYPE num value
///
UINT64 ErrorCode;
UINT64 Rip;
UINT64 Cs;
UINT64 Rflags;
UINT64 Rsp;
UINT64 Ss;
} STM_PROTECTION_EXCEPTION_STACK_FRAME_X64;
typedef union {
STM_PROTECTION_EXCEPTION_STACK_FRAME_IA32 *Ia32StackFrame;
STM_PROTECTION_EXCEPTION_STACK_FRAME_X64 *X64StackFrame;
} STM_PROTECTION_EXCEPTION_STACK_FRAME;
/**
Enum values for the ErrorCode field in
#STM_PROTECTION_EXCEPTION_STACK_FRAME_IA32 and
#STM_PROTECTION_EXCEPTION_STACK_FRAME_X64
**/
typedef enum {
TxtSmmPageViolation = 1,
TxtSmmMsrViolation,
TxtSmmRegisterViolation,
TxtSmmIoViolation,
TxtSmmPciViolation
} TXT_SMM_PROTECTION_EXCEPTION_TYPE;
/**
TXT Pocessor SMM Descriptor (PSD) structures
**/
typedef struct {
UINT64 SpeRip;
UINT64 SpeRsp;
UINT16 SpeSs;
UINT16 PageViolationException:1;
UINT16 MsrViolationException:1;
UINT16 RegisterViolationException:1;
UINT16 IoViolationException:1;
UINT16 PciViolationException:1;
UINT16 Reserved1:11;
UINT32 Reserved2;
} STM_PROTECTION_EXCEPTION_HANDLER;
typedef struct {
UINT8 ExecutionDisableOutsideSmrr:1;
UINT8 Intel64Mode:1;
UINT8 Cr4Pae : 1;
UINT8 Cr4Pse : 1;
UINT8 Reserved1 : 4;
} STM_SMM_ENTRY_STATE;
typedef struct {
UINT8 SmramToVmcsRestoreRequired : 1; ///> BIOS restore hint
UINT8 ReinitializeVmcsRequired : 1; ///> BIOS request
UINT8 Reserved2 : 6;
} STM_SMM_RESUME_STATE;
typedef struct {
UINT8 DomainType : 4; ///> STM input to BIOS on each SMI
UINT8 XStatePolicy : 2; ///> STM input to BIOS on each SMI
UINT8 EptEnabled : 1;
UINT8 Reserved3 : 1;
} STM_SMM_STATE;
#define TXT_SMM_PSD_OFFSET 0xfb00
#define TXT_PROCESSOR_SMM_DESCRIPTOR_SIGNATURE SIGNATURE_64('T', 'X', 'T', 'P', 'S', 'S', 'I', 'G')
#define TXT_PROCESSOR_SMM_DESCRIPTOR_VERSION_MAJOR 1
#define TXT_PROCESSOR_SMM_DESCRIPTOR_VERSION_MINOR 0
typedef struct {
UINT64 Signature;
UINT16 Size;
UINT8 SmmDescriptorVerMajor;
UINT8 SmmDescriptorVerMinor;
UINT32 LocalApicId;
STM_SMM_ENTRY_STATE SmmEntryState;
STM_SMM_RESUME_STATE SmmResumeState;
STM_SMM_STATE StmSmmState;
UINT8 Reserved4;
UINT16 SmmCs;
UINT16 SmmDs;
UINT16 SmmSs;
UINT16 SmmOtherSegment;
UINT16 SmmTr;
UINT16 Reserved5;
UINT64 SmmCr3;
UINT64 SmmStmSetupRip;
UINT64 SmmStmTeardownRip;
UINT64 SmmSmiHandlerRip;
UINT64 SmmSmiHandlerRsp;
UINT64 SmmGdtPtr;
UINT32 SmmGdtSize;
UINT32 RequiredStmSmmRevId;
STM_PROTECTION_EXCEPTION_HANDLER StmProtectionExceptionHandler;
UINT64 Reserved6;
UINT64 BiosHwResourceRequirementsPtr;
// extend area
UINT64 AcpiRsdp;
UINT8 PhysicalAddressBits;
} TXT_PROCESSOR_SMM_DESCRIPTOR;
#pragma pack ()
#endif
|