Skip to content

Commit

Permalink
Merged PR 1306: Design update for Mu telemetry
Browse files Browse the repository at this point in the history 
Design update for Mu telemetry:
1. A new CPER section type and structure is defined for telemetry report (MuTelemetrySectionType will be the one and only data acknowledged by the listeners);
2. Added helper library to assist mu telemetry reporting;
3. Updated backend processing to work with newly defined structure in #1;
4. Updated unit test application to test new library APIs and backend routines;
  • Loading branch information
@kuqin12
kuqin12 committed Jul 10, 2019
1 parent ce3581c commit a447eae
Show file tree
Hide file tree
Showing 25 changed files with 1,238 additions and 1,905 deletions.
69 changes: 69 additions & 0 deletions MsWheaPkg/Include/Guid/MuTelemetryCperSection.h
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,69 @@
/** @file -- MsWheaErrorStatus.h
This header file defines the Guid and data structure of Mu Telemetry section type
that will be used in Common Platform Error Record (CPER) for WHEA events.
Copyright (C) Microsoft Corporation. All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:
1. Redistributions of source code must retain the above copyright notice,
this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright notice,
this list of conditions and the following disclaimer in the documentation
and/or other materials provided with the distribution.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
**/

#ifndef __MU_TELEMETRY_CPER_SECTION_DATA__
#define __MU_TELEMETRY_CPER_SECTION_DATA__

#define MU_TELEMETRY_SECTION_TYPE_GUID \
{ \
0x85183a8b, 0x9c41, 0x429c, { 0x93, 0x9c, 0x5c, 0x3c, 0x08, 0x7c, 0xa2, 0x80 } \
}

extern EFI_GUID gMuTelemetrySectionTypeGuid;

#pragma pack(1)

/**
Telemetry report structure. This structure corresponds to the gMuTelemetrySectionTypeGuid.
This will contain the most essential information regarding the error of interest. Any
other arbitrary data will not be reported/collected through telemetry pipeline
Note: Please be compliant with privacy policy. Microsoft is not responsible for
sanitizing the data being transported to cloud.
ComponentID: Component Guid which invoked telemetry report, will be gCallerId if not supplied.
SubComponentID: Subcomponent Guid which invoked telemetry report, will be NULL if not supplied.
Reserved: Not used
ErrorStatusValue: Reported Status Code Value upon calling ReportStatusCode
AdditionalInfo1: 64 bit value used for caller to include necessary interrogative information
AdditionalInfo2: Secondary 64 bit value, usage same as AdditionalInfo1
**/
typedef struct {
EFI_GUID ComponentID;
EFI_GUID SubComponentID;
UINT32 Reserved;
EFI_STATUS_CODE_VALUE ErrorStatusValue;
UINT64 AdditionalInfo1;
UINT64 AdditionalInfo2;
} MU_TELEMETRY_CPER_SECTION_DATA;

#pragma pack()

#endif // __MU_TELEMETRY_CPER_SECTION_DATA__
7 changes: 1 addition & 6 deletions MsWheaPkg/Include/Library/MsWheaEarlyStorageLib.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,9 +2,8 @@
This header defines APIs to utilize special memory for MsWheaReport during early stage.
Copyright (c) 2018, Microsoft Corporation
Copyright (C) Microsoft Corporation. All rights reserved.
All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:
1. Redistributions of source code must retain the above copyright notice,
Expand All @@ -29,10 +28,6 @@ ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
#ifndef __MS_WHEA_EARLY_STORAGE_LIB__
#define __MS_WHEA_EARLY_STORAGE_LIB__

#include <Uefi/UefiBaseType.h>

#define EARLY_STORAGE_DEFAULT_VALUE 0xFF

/**
This routine returns the maximum number of bytes that can be stored in the early storage area.
Expand Down
76 changes: 76 additions & 0 deletions MsWheaPkg/Include/Library/MuTelemetryHelperLib.h
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,76 @@
/** @file -- MuTelemetryHelperLib.h
Helper functions to make it even easier to report telemetry events in
source code.
Copyright (c) 2019, Microsoft Corporation
All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:
1. Redistributions of source code must retain the above copyright notice,
this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright notice,
this list of conditions and the following disclaimer in the documentation
and/or other materials provided with the distribution.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
**/

#ifndef _MU_TELEMETRY_HELPER_LIB_H_
#define _MU_TELEMETRY_HELPER_LIB_H_

// TODO: This is against common Mu practice.
#include <Library/ReportStatusCodeLib.h>

// TODO: Make this a MACRO so it can be disabled.

/**
Helper function to minimize the number of parameters for a critical telemetry event
and to clarify the purpose of each field.
This helper constructs the most detailed report possible that can still be persisted in case
of power loss or reset. It will log a critical fatal event through the telemetry system.
@param[in] ComponentId [Optional] This identifier should uniquely identify the module that is emitting this
event. When this is passed in as NULL, report status code will automatically populate
this field with gEfiCallerIdGuid.
@param[in] ClassId An EFI_STATUS_CODE_VALUE representing the event that has occurred. This
value will occupy the same space as EventId from LogCriticalEvent(), and
should be unique enough to identify a module or region of code.
@param[in] LibraryId This should identify the library that is emitting this event.
@param[in] IhvId This should identify the Ihv related to this event if applicable. For example,
this would typically be used for TPM and SOC specific events.
@param[in] ExtraData1 [Optional] This should be data specific to the cause. Ideally, used to contain contextual
or runtime data related to the event (e.g. register contents, failure codes, etc.).
It will be persisted.
@param[in] ExtraData2 [Optional] Another UINT32 similar to ExtraData1.
@retval EFI_SUCCESS Event has been reported.
@retval EFI_ERROR Something has gone wrong.
**/
EFI_STATUS
EFIAPI
LogTelemetry (
IN BOOLEAN IsFatal,
IN EFI_GUID* ComponentId OPTIONAL,
IN EFI_STATUS_CODE_VALUE ClassId,
IN EFI_GUID* LibraryId OPTIONAL,
IN EFI_GUID* IhvId OPTIONAL,
IN UINT64 ExtraData1,
IN UINT64 ExtraData2
);


#endif // _MU_TELEMETRY_HELPER_LIB_H_
97 changes: 7 additions & 90 deletions MsWheaPkg/Include/MsWheaErrorStatus.h
View file
Original file line number Diff line number Diff line change
@@ -1,10 +1,9 @@
/** @file -- MsWheaErrorStatus.h
This header file defines MsWheaReport expected/applied header components.
This header file defines MsWheaReport expected/applied invocation components.
Copyright (c) 2018, Microsoft Corporation
Copyright (C) Microsoft Corporation. All rights reserved.
All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:
1. Redistributions of source code must retain the above copyright notice,
Expand All @@ -29,100 +28,18 @@ ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
#ifndef __MS_WHEA_ERROR_STATUS__
#define __MS_WHEA_ERROR_STATUS__

#include <Guid/Cper.h>
#include <Pi/PiStatusCode.h>

#define MS_WHEA_ERROR_SIGNATURE SIGNATURE_32('W', 'H', 'E', 'A')

/**
Accepted phase values
**/
#define MS_WHEA_PHASE_PEI 0x00
#define MS_WHEA_PHASE_DXE 0x01
#define MS_WHEA_PHASE_DXE_RUNTIME 0x02

/**
Accepted revision values
**/
#define MS_WHEA_REV_0 0x0000
#define MS_WHEA_REV_1 0x0001
#define MS_WHEA_REV_WILDCARD 0x7FFF
#define MS_WHEA_EARLY_STORAGE_SUBCLASS \
0x00CA0000

#define MS_WHEA_ERROR_EARLY_STORAGE_STORE_FULL \
0xAFAFAFAF
(EFI_SOFTWARE | MS_WHEA_EARLY_STORAGE_SUBCLASS | EFI_SW_EC_EVENT_LOG_FULL)

/**
Microsoft WHEA accepted error status type, other types will be ignored
**/
#define MS_WHEA_ERROR_STATUS_TYPE (EFI_ERROR_MAJOR | EFI_ERROR_CODE)

typedef UINT16 MS_WHEA_REV;
typedef UINT16 MS_WHEA_ERROR_PHASE;

/**
Minimal information reported for reported status codes under fatal severity (Rev0 and above).
Note: All the upcoming Early Storage entry should start with the following parameters
Rev: Revision used for parser to identify supplied payload format.
Phase: Phase of boot process reporting module, will be filled at the backend.
ErrorStatusCode: Reported Status Code Value upon calling ReportStatusCode*
**/
typedef struct MS_WHEA_EARLY_STORAGE_ENTRY_V0_T_DEF {
MS_WHEA_REV Rev;
MS_WHEA_ERROR_PHASE Phase;
UINT32 ErrorStatusCode;
} MS_WHEA_EARLY_STORAGE_ENTRY_V0, MS_WHEA_EARLY_STORAGE_ENTRY_COMMON;

/**
Minimal information reported for reported status codes under Rev 1 and fatal severity
Rev: Revision used for parser to identify supplied payload format.
Phase: Phase of boot process reporting module, will be filled at the backend.
ErrorStatusCode: Reported Status Code Value upon calling ReportStatusCode*
CriticalInfo: Critical information to be filled by caller
ReporterID: ReporterID to be filled by caller to reporter identification purpose
**/
typedef struct MS_WHEA_EARLY_STORAGE_ENTRY_V1_T_DEF {
MS_WHEA_REV Rev;
MS_WHEA_ERROR_PHASE Phase;
UINT32 ErrorStatusCode;
UINT64 CriticalInfo;
UINT64 ReporterID;
} MS_WHEA_EARLY_STORAGE_ENTRY_V1;

/**
Microsoft WHEA error list entry header, to be included as error header when using
ReportStatusCodeWithExtendedData.
Signature: 'WHEA', indocator of WHEA compliance
Rev: Revision used for parser to identify supplied payload format.
Phase: Phase of boot process reporting module, will be filled at the backend.
ErrorStatusCode: Reported Status Code Value upon calling ReportStatusCode*
CriticalInfo: Critical information to be filled by caller, Ignored for Rev: 0 and wildcard
ReporterID: ReporterID to be filled by caller to reporter identification purpose, ignored for
Rev: 0 and wildcard
**/
typedef struct MS_WHEA_ERROR_HDR_T_DEF {
UINT32 Signature;
MS_WHEA_REV Rev;
MS_WHEA_ERROR_PHASE Phase;
UINT32 ErrorSeverity;
UINT32 Reserved;
UINT64 CriticalInfo;
UINT64 ReporterID;
} MS_WHEA_ERROR_HDR;
#define MS_WHEA_ERROR_STATUS_TYPE_INFO (EFI_ERROR_MINOR | EFI_ERROR_CODE)
#define MS_WHEA_ERROR_STATUS_TYPE_FATAL (EFI_ERROR_MAJOR | EFI_ERROR_CODE)

#endif // __MS_WHEA_ERROR_STATUS__
2 changes: 2 additions & 0 deletions MsWheaPkg/Library/MsWheaEarlyStorageLib/MsWheaEarlyStorageLib.c
View file
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,8 @@ ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
**/

#include <Uefi/UefiBaseType.h>

#include <Library/DebugLib.h>
#include <Library/IoLib.h>
#include <Library/PcdLib.h>
Expand Down
Loading

0 comments on commit a447eae

Please sign in to comment.