iPXE
efi_timer.c
Go to the documentation of this file.
1 /*
2  * Copyright (C) 2008 Michael Brown <mbrown@fensystems.co.uk>.
3  *
4  * This program is free software; you can redistribute it and/or
5  * modify it under the terms of the GNU General Public License as
6  * published by the Free Software Foundation; either version 2 of the
7  * License, or any later version.
8  *
9  * This program is distributed in the hope that it will be useful, but
10  * WITHOUT ANY WARRANTY; without even the implied warranty of
11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12  * General Public License for more details.
13  *
14  * You should have received a copy of the GNU General Public License
15  * along with this program; if not, write to the Free Software
16  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
17  * 02110-1301, USA.
18  *
19  * You can also choose to distribute this program under the terms of
20  * the Unmodified Binary Distribution Licence (as given in the file
21  * COPYING.UBDL), provided that you have satisfied its requirements.
22  */
23 
24 FILE_LICENCE ( GPL2_OR_LATER_OR_UBDL );
25 
26 #include <string.h>
27 #include <errno.h>
28 #include <unistd.h>
29 #include <ipxe/timer.h>
30 #include <ipxe/init.h>
31 #include <ipxe/efi/efi.h>
32 
33 /** @file
34  *
35  * iPXE timer API for EFI
36  *
37  */
38 
39 /**
40  * Number of jiffies per second
41  *
42  * This is a policy decision.
43  */
44 #define EFI_JIFFIES_PER_SEC 32
45 
46 /** Current tick count */
47 static unsigned long efi_jiffies;
48 
49 /** Timer tick event */
51 
52 /** Colour for debug messages */
53 #define colour &efi_jiffies
54 
55 /**
56  * Delay for a fixed number of microseconds
57  *
58  * @v usecs Number of microseconds for which to delay
59  */
60 static void efi_udelay ( unsigned long usecs ) {
62  EFI_STATUS efirc;
63  int rc;
64 
65  if ( ( efirc = bs->Stall ( usecs ) ) != 0 ) {
66  rc = -EEFI ( efirc );
67  DBGC ( colour, "EFI could not delay for %ldus: %s\n",
68  usecs, strerror ( rc ) );
69  /* Probably screwed */
70  }
71 }
72 
73 /**
74  * Get current system time in ticks
75  *
76  * @ret ticks Current time, in ticks
77  */
78 static unsigned long efi_currticks ( void ) {
80 
81  /* UEFI manages to ingeniously combine the worst aspects of
82  * both polling and interrupt-driven designs. There is no way
83  * to support proper interrupt-driven operation, since there
84  * is no way to hook in an interrupt service routine. A
85  * mockery of interrupts is provided by UEFI timers, which
86  * trigger at a preset rate and can fire at any time.
87  *
88  * We therefore have all of the downsides of a polling design
89  * (inefficiency and inability to sleep until something
90  * interesting happens) combined with all of the downsides of
91  * an interrupt-driven design (the complexity of code that
92  * could be preempted at any time).
93  *
94  * The UEFI specification expects us to litter the entire
95  * codebase with calls to RaiseTPL() as needed for sections of
96  * code that are not reentrant. Since this doesn't actually
97  * gain us any substantive benefits (since even with such
98  * calls we would still be suffering from the limitations of a
99  * polling design), we instead choose to run at TPL_CALLBACK
100  * almost all of the time, dropping to TPL_APPLICATION to
101  * allow timer ticks to occur.
102  *
103  *
104  * For added excitement, UEFI provides no clean way for device
105  * drivers to shut down in preparation for handover to a
106  * booted operating system. The platform firmware simply
107  * doesn't bother to call the drivers' Stop() methods.
108  * Instead, all non-trivial drivers must register an
109  * EVT_SIGNAL_EXIT_BOOT_SERVICES event to be signalled when
110  * ExitBootServices() is called, and clean up without any
111  * reference to the EFI driver model.
112  *
113  * Unfortunately, all timers silently stop working when
114  * ExitBootServices() is called. Even more unfortunately, and
115  * for no discernible reason, this happens before any
116  * EVT_SIGNAL_EXIT_BOOT_SERVICES events are signalled. The
117  * net effect of this entertaining design choice is that any
118  * timeout loops on the shutdown path (e.g. for gracefully
119  * closing outstanding TCP connections) may wait indefinitely.
120  *
121  * There is no way to report failure from currticks(), since
122  * the API lazily assumes that the host system continues to
123  * travel through time in the usual direction. Work around
124  * EFI's violation of this assumption by falling back to a
125  * simple free-running monotonic counter during shutdown.
126  */
127  if ( efi_shutdown_in_progress ) {
128  efi_jiffies++;
129  } else {
130  bs->RestoreTPL ( TPL_APPLICATION );
131  bs->RaiseTPL ( TPL_CALLBACK );
132  }
133 
134  return ( efi_jiffies * ( TICKS_PER_SEC / EFI_JIFFIES_PER_SEC ) );
135 }
136 
137 /**
138  * Timer tick
139  *
140  * @v event Timer tick event
141  * @v context Event context
142  */
143 static EFIAPI void efi_tick ( EFI_EVENT event __unused,
144  void *context __unused ) {
145 
146  /* Increment tick count */
147  efi_jiffies++;
148 }
149 
150 /**
151  * Start timer tick
152  *
153  */
154 static void efi_tick_startup ( void ) {
156  EFI_STATUS efirc;
157  int rc;
158 
159  /* Create timer tick event */
160  if ( ( efirc = bs->CreateEvent ( ( EVT_TIMER | EVT_NOTIFY_SIGNAL ),
162  &efi_tick_event ) ) != 0 ) {
163  rc = -EEFI ( efirc );
164  DBGC ( colour, "EFI could not create timer tick: %s\n",
165  strerror ( rc ) );
166  /* Nothing we can do about it */
167  return;
168  }
169 
170  /* Start timer tick */
171  if ( ( efirc = bs->SetTimer ( efi_tick_event, TimerPeriodic,
172  ( 10000000 / EFI_JIFFIES_PER_SEC ) ))!=0){
173  rc = -EEFI ( efirc );
174  DBGC ( colour, "EFI could not start timer tick: %s\n",
175  strerror ( rc ) );
176  /* Nothing we can do about it */
177  return;
178  }
179  DBGC ( colour, "EFI timer started at %d ticks per second\n",
181 }
182 
183 /**
184  * Stop timer tick
185  *
186  * @v booting System is shutting down in order to boot
187  */
188 static void efi_tick_shutdown ( int booting __unused ) {
190  EFI_STATUS efirc;
191  int rc;
192 
193  /* Stop timer tick */
194  if ( ( efirc = bs->SetTimer ( efi_tick_event, TimerCancel, 0 ) ) != 0 ){
195  rc = -EEFI ( efirc );
196  DBGC ( colour, "EFI could not stop timer tick: %s\n",
197  strerror ( rc ) );
198  /* Self-destruct initiated */
199  return;
200  }
201  DBGC ( colour, "EFI timer stopped\n" );
202 
203  /* Destroy timer tick event */
204  if ( ( efirc = bs->CloseEvent ( efi_tick_event ) ) != 0 ) {
205  rc = -EEFI ( efirc );
206  DBGC ( colour, "EFI could not destroy timer tick: %s\n",
207  strerror ( rc ) );
208  /* Probably non-fatal */
209  return;
210  }
211 }
212 
213 /** Timer tick startup function */
214 struct startup_fn efi_tick_startup_fn __startup_fn ( STARTUP_EARLY ) = {
215  .name = "efi_tick",
216  .startup = efi_tick_startup,
217  .shutdown = efi_tick_shutdown,
218 };
219 
220 /** EFI timer */
221 struct timer efi_timer __timer ( TIMER_NORMAL ) = {
222  .name = "efi",
223  .currticks = efi_currticks,
224  .udelay = efi_udelay,
225 };
static void efi_udelay(unsigned long usecs)
Delay for a fixed number of microseconds.
Definition: efi_timer.c:60
EFI_BOOT_SERVICES * BootServices
A pointer to the EFI Boot Services Table.
Definition: UefiSpec.h:2000
struct arbelprm_rc_send_wqe rc
Definition: arbel.h:14
static EFI_EVENT efi_tick_event
Timer tick event.
Definition: efi_timer.c:50
#define TICKS_PER_SEC
Number of ticks per second.
Definition: timer.h:15
#define EEFI(efirc)
Convert an EFI status code to an iPXE status code.
Definition: efi.h:159
EFI_RAISE_TPL RaiseTPL
Definition: UefiSpec.h:1845
An event is to be signaled periodically at a specified interval from the current time.
Definition: UefiSpec.h:489
EFI_STALL Stall
Definition: UefiSpec.h:1893
#define colour
Colour for debug messages.
Definition: efi_timer.c:53
Error codes.
#define TPL_APPLICATION
Definition: UefiSpec.h:590
VOID * EFI_EVENT
Handle to an event structure.
Definition: UefiBaseType.h:43
static unsigned long efi_jiffies
Current tick count.
Definition: efi_timer.c:47
#define STARTUP_EARLY
Early startup.
Definition: init.h:62
#define DBGC(...)
Definition: compiler.h:505
EFI_CLOSE_EVENT CloseEvent
Definition: UefiSpec.h:1864
EFI_SET_TIMER SetTimer
Definition: UefiSpec.h:1861
iPXE timers
const char * name
Definition: init.h:42
A timer.
Definition: timer.h:28
A startup/shutdown function.
Definition: init.h:41
An event's timer settings is to be cancelled and not trigger time is to be set/.
Definition: UefiSpec.h:485
static void efi_tick_shutdown(int booting __unused)
Stop timer tick.
Definition: efi_timer.c:188
static void efi_tick_startup(void)
Start timer tick.
Definition: efi_timer.c:154
EFI_CREATE_EVENT CreateEvent
Definition: UefiSpec.h:1860
char * strerror(int errno)
Retrieve string representation of error number.
Definition: strerror.c:78
#define EFIAPI
EFI Boot Services Table.
Definition: UefiSpec.h:1836
#define TPL_CALLBACK
Definition: UefiSpec.h:591
#define EVT_NOTIFY_SIGNAL
Definition: UefiSpec.h:394
EFI API.
#define __unused
Declare a variable or data structure as unused.
Definition: compiler.h:573
const char * name
Name.
Definition: timer.h:30
FILE_LICENCE(GPL2_OR_LATER_OR_UBDL)
struct startup_fn efi_tick_startup_fn __startup_fn(STARTUP_EARLY)
Timer tick startup function.
RETURN_STATUS EFI_STATUS
Function return status for EFI API.
Definition: UefiBaseType.h:35
#define EFI_JIFFIES_PER_SEC
Number of jiffies per second.
Definition: efi_timer.c:44
EFI_SYSTEM_TABLE * efi_systab
EFI_RESTORE_TPL RestoreTPL
Definition: UefiSpec.h:1846
struct timer efi_timer __timer(TIMER_NORMAL)
EFI timer.
static unsigned long efi_currticks(void)
Get current system time in ticks.
Definition: efi_timer.c:78
#define NULL
NULL pointer (VOID *)
Definition: Base.h:362
String functions.
static EFIAPI void efi_tick(EFI_EVENT event __unused, void *context __unused)
Timer tick.
Definition: efi_timer.c:143
#define TIMER_NORMAL
Normal timer.
Definition: timer.h:63
int efi_shutdown_in_progress
EFI shutdown is in progress.
Definition: efi_init.c:47
#define EVT_TIMER
Definition: UefiSpec.h:391