diff options
Diffstat (limited to 'Lessons/Lesson_10/README.md')
| -rw-r--r-- | Lessons/Lesson_10/README.md | 156 |
1 files changed, 156 insertions, 0 deletions
diff --git a/Lessons/Lesson_10/README.md b/Lessons/Lesson_10/README.md new file mode 100644 index 0000000..cca1dc5 --- /dev/null +++ b/Lessons/Lesson_10/README.md @@ -0,0 +1,156 @@ + +It is common in UEFI code to use construct like this: +``` +if (!EFI_ERROR(Status) { + ... +} else { + ... +} +``` + +For the internal implementation of EFI_STATUS functionality look at the files: +MdePkg/Include/Uefi/UefiBaseType.h +MdePkg/Include/Base.h + +``` +#define EFI_ERROR(A) RETURN_ERROR(A) + +... + +/** + Returns TRUE if a specified RETURN_STATUS code is an error code. + + This function returns TRUE if StatusCode has the high bit set. Otherwise, FALSE is returned. + + @param StatusCode The status code value to evaluate. + + @retval TRUE The high bit of StatusCode is set. + @retval FALSE The high bit of StatusCode is clear. + +**/ +#define RETURN_ERROR(StatusCode) (((INTN)(RETURN_STATUS)(StatusCode)) < 0) + +... + +// +// Status codes common to all execution phases +// +typedef UINTN RETURN_STATUS; +``` + +So the `EFI_ERROR` macro simply test if a passed value is negative which is the same fact for a signed integer that is has high bit set. + +Enumration of possible EFI_STATUS values is in the file MdePkg/Include/Uefi/UefiBaseType.h +``` +/// +/// Enumeration of EFI_STATUS. +///@{ +#define EFI_SUCCESS RETURN_SUCCESS +#define EFI_LOAD_ERROR RETURN_LOAD_ERROR +#define EFI_INVALID_PARAMETER RETURN_INVALID_PARAMETER +#define EFI_UNSUPPORTED RETURN_UNSUPPORTED +#define EFI_BAD_BUFFER_SIZE RETURN_BAD_BUFFER_SIZE +#define EFI_BUFFER_TOO_SMALL RETURN_BUFFER_TOO_SMALL +#define EFI_NOT_READY RETURN_NOT_READY +#define EFI_DEVICE_ERROR RETURN_DEVICE_ERROR +#define EFI_WRITE_PROTECTED RETURN_WRITE_PROTECTED +#define EFI_OUT_OF_RESOURCES RETURN_OUT_OF_RESOURCES +#define EFI_VOLUME_CORRUPTED RETURN_VOLUME_CORRUPTED +#define EFI_VOLUME_FULL RETURN_VOLUME_FULL +#define EFI_NO_MEDIA RETURN_NO_MEDIA +#define EFI_MEDIA_CHANGED RETURN_MEDIA_CHANGED +#define EFI_NOT_FOUND RETURN_NOT_FOUND +#define EFI_ACCESS_DENIED RETURN_ACCESS_DENIED +#define EFI_NO_RESPONSE RETURN_NO_RESPONSE +#define EFI_NO_MAPPING RETURN_NO_MAPPING +#define EFI_TIMEOUT RETURN_TIMEOUT +#define EFI_NOT_STARTED RETURN_NOT_STARTED +#define EFI_ALREADY_STARTED RETURN_ALREADY_STARTED +#define EFI_ABORTED RETURN_ABORTED +#define EFI_ICMP_ERROR RETURN_ICMP_ERROR +#define EFI_TFTP_ERROR RETURN_TFTP_ERROR +#define EFI_PROTOCOL_ERROR RETURN_PROTOCOL_ERROR +#define EFI_INCOMPATIBLE_VERSION RETURN_INCOMPATIBLE_VERSION +#define EFI_SECURITY_VIOLATION RETURN_SECURITY_VIOLATION +#define EFI_CRC_ERROR RETURN_CRC_ERROR +#define EFI_END_OF_MEDIA RETURN_END_OF_MEDIA +#define EFI_END_OF_FILE RETURN_END_OF_FILE +#define EFI_INVALID_LANGUAGE RETURN_INVALID_LANGUAGE +#define EFI_COMPROMISED_DATA RETURN_COMPROMISED_DATA +#define EFI_HTTP_ERROR RETURN_HTTP_ERROR + +#define EFI_WARN_UNKNOWN_GLYPH RETURN_WARN_UNKNOWN_GLYPH +#define EFI_WARN_DELETE_FAILURE RETURN_WARN_DELETE_FAILURE +#define EFI_WARN_WRITE_FAILURE RETURN_WARN_WRITE_FAILURE +#define EFI_WARN_BUFFER_TOO_SMALL RETURN_WARN_BUFFER_TOO_SMALL +#define EFI_WARN_STALE_DATA RETURN_WARN_STALE_DATA +#define EFI_WARN_FILE_SYSTEM RETURN_WARN_FILE_SYSTEM +``` + +If you want to see how they encoded look at the MdePkg\Include\Base.h : +``` +/// +/// The operation completed successfully. +/// +#define RETURN_SUCCESS 0 + +/// +/// The image failed to load. +/// +#define RETURN_LOAD_ERROR ENCODE_ERROR (1) + +/// +/// The parameter was incorrect. +/// +#define RETURN_INVALID_PARAMETER ENCODE_ERROR (2) + +<...> + +/** + Produces a RETURN_STATUS code with the highest bit set. + + @param StatusCode The status code value to convert into a warning code. + StatusCode must be in the range 0x00000000..0x7FFFFFFF. + + @return The value specified by StatusCode with the highest bit set. + +**/ +#define ENCODE_ERROR(StatusCode) ((RETURN_STATUS)(MAX_BIT | (StatusCode))) + +/** + Produces a RETURN_STATUS code with the highest bit clear. + + @param StatusCode The status code value to convert into a warning code. + StatusCode must be in the range 0x00000000..0x7FFFFFFF. + + @return The value specified by StatusCode with the highest bit clear. + +**/ +#define ENCODE_WARNING(StatusCode) ((RETURN_STATUS)(StatusCode)) +``` + +Let's use `EFI_ERROR` macro in our code and test error printing with the help of `%r` Print formatting option. + +We could test error display with a passing `NULL` pointer instead of ImageHandle: +``` +Print(L"________\n"); +EFI_GUID **ProtocolGuidArray; +UINTN ArrayCount; +EFI_STATUS Status = gBS->ProtocolsPerHandle(NULL, + &ProtocolGuidArray, + &ArrayCount); + +if (!EFI_ERROR(Status)) { + for (int i=0; i<ArrayCount; i++) { + Print(L"%g\n", ProtocolGuidArray[i]); + } + FreePool(ProtocolGuidArray); +} else { + Print(L"ProtocolsPerHandle error: %r\n", Status); +} +``` + +This would give us this message in OVMF: +``` +ProtocolsPerHandle error: Invalid Parameter +``` |