src/include/bootstate.h

   1 /*
   2  * This file is part of the coreboot project.
   3  *
   4  * Copyright (C) 2013 Google, Inc.
   5  *
   6  * This program is free software; you can redistribute it and/or modify
   7  * it under the terms of the GNU General Public License as published by
   8  * the Free Software Foundation; version 2 of the License.
   9  *
  10  * This program is distributed in the hope that it will be useful,
  11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13  * GNU General Public License for more details.
  14  */
  15 #ifndef BOOTSTATE_H
  16 #define BOOTSTATE_H
  17
  18 #include <rules.h>
  19 #include <string.h>
  20 #include <stdlib.h>
  21 #include <stddef.h>
  22 #include <stdint.h>
  23 /* Only declare main() when in ramstage. */
  24 #if ENV_RAMSTAGE
  25 #include <main_decl.h>
  26 #endif
  27
  28 /*
  29  * The boot state machine provides a mechanism for calls to be made through-
  30  * out the main boot process. The boot process is separated into discrete
  31  * states. Upon a state's entry and exit and callbacks can be made. For
  32  * example:
  33  *
  34  *      Enter State
  35  *           +
  36  *           |
  37  *           V
  38  *   +-----------------+
  39  *   | Entry callbacks |
  40  *   +-----------------+
  41  *   | State Actions   |
  42  *   +-----------------+
  43  *   | Exit callbacks  |
  44  *   +-------+---------+
  45  *           |
  46  *           V
  47  *       Next State
  48  *
  49  * Below is the current flow from top to bottom:
  50  *
  51  *        start
  52  *          |
  53  *    BS_PRE_DEVICE
  54  *          |
  55  *    BS_DEV_INIT_CHIPS
  56  *          |
  57  *    BS_DEV_ENUMERATE
  58  *          |
  59  *    BS_DEV_RESOURCES
  60  *          |
  61  *    BS_DEV_ENABLE
  62  *          |
  63  *    BS_DEV_INIT
  64  *          |
  65  *    BS_POST_DEVICE
  66  *          |
  67  *    BS_OS_RESUME_CHECK -------- BS_OS_RESUME
  68  *          |                          |
  69  *    BS_WRITE_TABLES              os handoff
  70  *          |
  71  *    BS_PAYLOAD_LOAD
  72  *          |
  73  *    BS_PAYLOAD_BOOT
  74  *          |
  75  *      payload run
  76  *
  77  * Brief description of states:
  78  *   BS_PRE_DEVICE - before any device tree actions take place
  79  *   BS_DEV_INIT_CHIPS - init all chips in device tree
  80  *   BS_DEV_ENUMERATE - device tree probing
  81  *   BS_DEV_RESOURCES - device tree resource allocation and assignment
  82  *   BS_DEV_ENABLE - device tree enabling/disabling of devices
  83  *   BS_DEV_INIT - device tree device initialization
  84  *   BS_POST_DEVICE - all device tree actions performed
  85  *   BS_OS_RESUME_CHECK - check for OS resume
  86  *   BS_OS_RESUME - resume to OS
  87  *   BS_WRITE_TABLES - write coreboot tables
  88  *   BS_PAYLOAD_LOAD - Load payload into memory
  89  *   BS_PAYLOAD_BOOT - Boot to payload
  90  */
  91
  92 typedef enum {
  93         BS_PRE_DEVICE,
  94         BS_DEV_INIT_CHIPS,
  95         BS_DEV_ENUMERATE,
  96         BS_DEV_RESOURCES,
  97         BS_DEV_ENABLE,
  98         BS_DEV_INIT,
  99         BS_POST_DEVICE,
 100         BS_OS_RESUME_CHECK,
 101         BS_OS_RESUME,
 102         BS_WRITE_TABLES,
 103         BS_PAYLOAD_LOAD,
 104         BS_PAYLOAD_BOOT,
 105 } boot_state_t;
 106
 107 /* The boot_state_sequence_t describes when a callback is to be made. It is
 108  * called either before a state is entered or when a state is exited. */
 109 typedef enum {
 110         BS_ON_ENTRY,
 111         BS_ON_EXIT
 112 } boot_state_sequence_t;
 113
 114 struct boot_state_callback {
 115         void *arg;
 116         void (*callback)(void *arg);
 117         /* For use internal to the boot state machine. */
 118         struct boot_state_callback *next;
 119 #if IS_ENABLED(CONFIG_DEBUG_BOOT_STATE)
 120         const char *location;
 121 #endif
 122 };
 123
 124 #if IS_ENABLED(CONFIG_DEBUG_BOOT_STATE)
 125 #define BOOT_STATE_CALLBACK_LOC __FILE__ ":" STRINGIFY(__LINE__)
 126 #define BOOT_STATE_CALLBACK_INIT_DEBUG .location = BOOT_STATE_CALLBACK_LOC,
 127 #define INIT_BOOT_STATE_CALLBACK_DEBUG(bscb_)                   \
 128         do {                                                    \
 129                 bscb_->location = BOOT_STATE_CALLBACK_LOC;      \
 130         } while (0)
 131 #else
 132 #define BOOT_STATE_CALLBACK_INIT_DEBUG
 133 #define INIT_BOOT_STATE_CALLBACK_DEBUG(bscb_)
 134 #endif
 135
 136 #define BOOT_STATE_CALLBACK_INIT(func_, arg_)           \
 137         {                                               \
 138                 .arg = arg_,                            \
 139                 .callback = func_,                      \
 140                 .next = NULL,                           \
 141                 BOOT_STATE_CALLBACK_INIT_DEBUG          \
 142         }
 143
 144 #define BOOT_STATE_CALLBACK(name_, func_, arg_) \
 145         struct boot_state_callback name_ = BOOT_STATE_CALLBACK_INIT(func_, arg_)
 146
 147 /* Initialize an allocated boot_state_callback. */
 148 #define INIT_BOOT_STATE_CALLBACK(bscb_, func_, arg_)    \
 149         do {                                            \
 150                 INIT_BOOT_STATE_CALLBACK_DEBUG(bscb_)   \
 151                 bscb_->callback = func_;                \
 152                 bscb_->arg = arg_                       \
 153         } while (0)
 154
 155 /* The following 2 functions schedule a callback to be called on entry/exit
 156  * to a given state. Note that there are no ordering guarantees between the
 157  * individual callbacks on a given state. 0 is returned on success < 0 on
 158  * error. */
 159 int boot_state_sched_on_entry(struct boot_state_callback *bscb,
 160                                 boot_state_t state);
 161 int boot_state_sched_on_exit(struct boot_state_callback *bscb,
 162                                 boot_state_t state);
 163 /* Schedule an array of entries of size num. */
 164 struct boot_state_init_entry;
 165 void boot_state_sched_entries(struct boot_state_init_entry *entries,
 166                                 size_t num);
 167
 168 /* Block/Unblock the (state, seq) pair from transitioning. Returns 0 on
 169  * success < 0  when the phase of the (state,seq) has already ran. */
 170 int boot_state_block(boot_state_t state, boot_state_sequence_t seq);
 171 int boot_state_unblock(boot_state_t state, boot_state_sequence_t seq);
 172 /* Block/Unblock current state phase from transitioning. */
 173 void boot_state_current_block(void);
 174 void boot_state_current_unblock(void);
 175
 176 /* In order to schedule boot state callbacks at compile-time specify the
 177  * entries in an array using the BOOT_STATE_INIT_ENTRIES and
 178  * BOOT_STATE_INIT_ENTRY macros below. */
 179 struct boot_state_init_entry {
 180         boot_state_t state;
 181         boot_state_sequence_t when;
 182         struct boot_state_callback bscb;
 183 };
 184
 185 #if ENV_RAMSTAGE
 186 #define BOOT_STATE_INIT_ATTR  __attribute__((used, section(".bs_init")))
 187 #else
 188 #define BOOT_STATE_INIT_ATTR  __attribute__((unused))
 189 #endif
 190
 191 #define BOOT_STATE_INIT_ENTRY(state_, when_, func_, arg_)               \
 192         static struct boot_state_init_entry func_ ##_## state_ ##_## when_ = \
 193         {                                                               \
 194                 .state = state_,                                        \
 195                 .when = when_,                                          \
 196                 .bscb = BOOT_STATE_CALLBACK_INIT(func_, arg_),          \
 197         };                                                              \
 198         static struct boot_state_init_entry *                           \
 199                 bsie_ ## func_ ##_## state_ ##_## when_ BOOT_STATE_INIT_ATTR = \
 200                 &func_ ##_## state_ ##_## when_;
 201
 202 /* Hook per arch when coreboot is exiting to payload or ACPI OS resume. It's
 203  * the very last thing done before the transition. */
 204 void arch_bootstate_coreboot_exit(void);
 205
 206 #endif /* BOOTSTATE_H */