include/efi_selftest.h

   1 /* SPDX-License-Identifier: GPL-2.0+ */
   2 /*
   3  *  EFI application loader
   4  *
   5  *  Copyright (c) 2017 Heinrich Schuchardt <xypron.glpk@gmx.de>
   6  */
   7
   8 #ifndef _EFI_SELFTEST_H
   9 #define _EFI_SELFTEST_H
  10
  11 #include <common.h>
  12 #include <efi.h>
  13 #include <efi_api.h>
  14 #include <efi_loader.h>
  15 #include <linker_lists.h>
  16
  17 #define EFI_ST_SUCCESS 0
  18 #define EFI_ST_FAILURE 1
  19 #define EFI_ST_SUCCESS_STR L"SUCCESS"
  20
  21 /**
  22  * efi_st_printf() - print a message
  23  *
  24  * @...:        format string followed by fields to print
  25  */
  26 #define efi_st_printf(...) \
  27         (efi_st_printc(-1, __VA_ARGS__))
  28
  29 /**
  30  * efi_st_error() - prints an error message
  31  *
  32  * @...:        format string followed by fields to print
  33  */
  34 #define efi_st_error(...) \
  35         (efi_st_printc(EFI_LIGHTRED, "%s(%u):\nERROR: ", __FILE__, __LINE__), \
  36         efi_st_printc(EFI_LIGHTRED, __VA_ARGS__))
  37
  38 /**
  39  * efi_st_todo() - prints a TODO message
  40  *
  41  * @...:        format string followed by fields to print
  42  */
  43 #define efi_st_todo(...) \
  44         (efi_st_printc(EFI_YELLOW, "%s(%u):\nTODO: ", __FILE__, __LINE__), \
  45         efi_st_printc(EFI_YELLOW, __VA_ARGS__)) \
  46
  47 /**
  48  * enum efi_test_phase - phase when test will be executed
  49  *
  50  * A test may be setup and executed at boottime,
  51  * it may be setup at boottime and executed at runtime,
  52  * or it may be setup and executed at runtime.
  53  */
  54 enum efi_test_phase {
  55         /**
  56          * @EFI_EXECUTE_BEFORE_BOOTTIME_EXIT:
  57          *
  58          * Setup, execute, and teardown are executed before ExitBootServices().
  59          */
  60         EFI_EXECUTE_BEFORE_BOOTTIME_EXIT = 1,
  61         /**
  62          * @EFI_SETUP_BEFORE_BOOTTIME_EXIT:
  63          *
  64          * Setup is executed before ExitBootServices() while execute, and
  65          * teardown are executed after ExitBootServices().
  66          */
  67         EFI_SETUP_BEFORE_BOOTTIME_EXIT,
  68         /**
  69          * @EFI_SETTING_VIRTUAL_ADDRESS_MAP:
  70          *
  71          * Execute calls SetVirtualAddressMap(). Setup is executed before
  72          * ExitBootServices() while execute is executed after
  73          * ExitBootServices(), and after the execute of tests marked as
  74          * @EFI_SETUP_BEFORE_BOOTTIME_EXIT. Teardown is executed thereafter.
  75          */
  76         EFI_SETTING_VIRTUAL_ADDRESS_MAP,
  77 };
  78
  79 extern struct efi_simple_text_output_protocol *con_out;
  80 extern struct efi_simple_text_input_protocol *con_in;
  81
  82 /**
  83  * efi_st_exit_boot_services() - exit the boot services
  84  *
  85  * * The size of the memory map is determined.
  86  * * Pool memory is allocated to copy the memory map.
  87  * * The memory map is copied and the map key is obtained.
  88  * * The map key is used to exit the boot services.
  89  */
  90 void efi_st_exit_boot_services(void);
  91
  92 /**
  93  * efi_st_printc() - print a colored message
  94  *
  95  * @color:      color, see constants in efi_api.h, use -1 for no color
  96  * @fmt:        printf style format string
  97  * @...:        arguments to be printed
  98  */
  99 void efi_st_printc(int color, const char *fmt, ...)
 100                  __attribute__ ((format (__printf__, 2, 3)));
 101
 102 /**
 103  * efi_st_translate_char() - translate a Unicode character to a string
 104  *
 105  * @code:       Unicode character
 106  * Return:      string
 107  */
 108 u16 *efi_st_translate_char(u16 code);
 109
 110 /**
 111  * efi_st_translate_code() - translate a scan code to a human readable string
 112  *
 113  * This function translates the scan code returned by the simple text input
 114  * protocol to a human readable string, e.g. 0x04 is translated to L"Left".
 115  *
 116  * @code:       scan code
 117  * Return:      Unicode string
 118  */
 119 u16 *efi_st_translate_code(u16 code);
 120
 121 /**
 122  * efi_st_strcmp_16_8() - compare an u16 string to a char string
 123  *
 124  * This function compares each u16 value to the char value at the same
 125  * position. This function is only useful for ANSI strings.
 126  *
 127  * @buf1:       u16 string
 128  * @buf2:       char string
 129  * Return:      0 if both buffers contain equivalent strings
 130  */
 131 int efi_st_strcmp_16_8(const u16 *buf1, const char *buf2);
 132
 133 /**
 134  * efi_st_get_key() - reads an Unicode character from the input device
 135  *
 136  * Return:      Unicode character
 137  */
 138 u16 efi_st_get_key(void);
 139
 140 /**
 141  * struct efi_unit_test - EFI unit test
 142  *
 143  * The &struct efi_unit_test structure provides a interface to an EFI unit test.
 144  *
 145  * @name:       name of the unit test used in the user interface
 146  * @phase:      specifies when setup and execute are executed
 147  * @setup:      set up function of the unit test
 148  * @execute:    execute function of the unit test
 149  * @teardown:   tear down function of the unit test
 150  * @on_request: flag indicating that the test shall only be executed on request
 151  */
 152 struct efi_unit_test {
 153         const char *name;
 154         const enum efi_test_phase phase;
 155         int (*setup)(const efi_handle_t handle,
 156                      const struct efi_system_table *systable);
 157         int (*execute)(void);
 158         int (*teardown)(void);
 159         bool on_request;
 160 };
 161
 162 /**
 163  * EFI_UNIT_TEST() - macro to declare a new EFI unit test
 164  *
 165  * The macro EFI_UNIT_TEST() declares an EFI unit test using the &struct
 166  * efi_unit_test structure. The test is added to a linker generated list which
 167  * is evaluated by the 'bootefi selftest' command.
 168  *
 169  * @__name:     string identifying the unit test in the linker generated list
 170  */
 171 #define EFI_UNIT_TEST(__name)                                           \
 172         ll_entry_declare(struct efi_unit_test, __name, efi_unit_test)
 173
 174 #endif /* _EFI_SELFTEST_H */