Documentation/AMD-S3.txt

   1    _____ ____  _____  ______ ____   ____   ____ _______
   2   / ____/ __ \|  __ \|  ____|  _ \ / __ \ / __ \__   __|
   3  | |   | |  | | |__) | |__  | |_) | |  | | |  | | | |
   4  | |   | |  | |  _  /|  __| |  _ <| |  | | |  | | | |
   5  | |___| |__| | | \ \| |____| |_) | |__| | |__| | | |
   6   \_____\____/|_|  \_\______|____/ \____/ \____/  |_|
   7
   8            __  __ _____     _____   ____
   9      /\   |  \/  |  __ \   / ____| |___ \
  10     /  \  | \  / | |  | | | (___     __) |
  11    / /\ \ | |\/| | |  | |  \___ \   |__ <
  12   / ____ \| |  | | |__| |  ____) |  ___) |
  13  /_/    \_\_|  |_|_____/  |_____/  |____/
  14
  15
  16                S3 in coreboot (V 1.2)
  17 ----------------------------------------
  18                 Zheng Bao
  19             <zheng.bao@amd.com>
  20             <fishbaozi@gmail.com>
  21
  22 Introduction
  23 ============
  24 This document is about how the feature S3 is implemented on coreboot,
  25 specifically on AMD platform. This topic deals with ACPI spec, hardware,
  26 BIOS, OS. We try to help coreboot users to realize their own S3.
  27
  28 S3 in a nutshell
  29 ================
  30 The S3 sleeping state is a low wake latency sleeping state where all
  31 system context is lost except system memory. [1]. S3 is a ACPI
  32 definition.
  33 To enter S3, write 3 in SLP_TYPx and set the SLP_EN bit (See ACPI
  34 registers). But if you do that, board can not resume at where it
  35 sleeps, because you don't save the context. More often than not, we
  36 make the board go into S3 by the tools which OSes provide. For
  37 windows, click Start->sleep. For linux, some distribution provide a
  38 tools called pm-suspend, which can make the system goto S3. If
  39 pm-suspend is not available, we can run "echo mem > /sys/power/state",
  40 but this way may not save all the needed context.
  41 In S3 state, the power is off. So when the power button is pressed,
  42 BIOS runs as it does in cold boot. If BIOS didn't detect whether
  43 board boots or resumes, it would go the same way as boot. It is not
  44 what we expect. BIOS detects the SLP_TYPx. If it is 3, it means BIOS
  45 are waking up.
  46 BIOS is responsible for restore the machine state as it is before
  47 sleep. It needs restore the memory controller, not overwriting memory
  48 which is not marked as reserved. For the peripheral which loses its
  49 registers, BIOS needs to write the original value.
  50 When everything is done, BIOS needs to find out the wakeup vector
  51 provided by OSes and jump there. OSes also have work to do. We can go
  52 to linux kernel or some other open source projects to find out how they
  53 handle S3 resume.
  54
  55 ACPI registers
  56 ==============
  57 ACPI specification defines a group of registers. OSes handle all these
  58 registers to read and write status to all the platform.
  59 On AMD platform, these registers are provided by southbridge. For
  60 example, Hudson uses PMIO 60:6F to define ACPI registers.
  61 OSes don't have any specific driver to know where these registers
  62 are. BIOS has the responsibility to allocated the IO resources and
  63 write all these address to FADT, a ACPI defined table.
  64
  65 Memory Layout
  66 =============
  67 Restoring memory is the most important job done by BIOS. When the
  68 power is off, the memory is maintained by standby power. BIOS need to
  69 make sure that when flow goes to OS, everything in memory should be
  70 the same as it was.
  71
  72 The chip vendor will provide a way, or code, to wake up the memory
  73 from sleeping. In AGESA 2008 arch, it is called AmdInitResume.
  74
  75 The BIOS itself needs some memory to run. Either, BIOS marks the erea
  76 as reserved in e820, or BIOS saves the content into reserved space.
  77
  78 Here is the address Map for S3 Resume. Assumingly the total memory is 1GB.
  79 00000000 --- 00100000      BIOS Reserved area.
  80 00100000 --- 00200000      Free
  81 00200000 --- 01000000      coreboot ramstage area.
  82 01000000 --- 2e160000      Free
  83 2e160000 --- 2e170000      ACPI table
  84 2e170000 --- 2ef70000      OSRAM
  85 2ef70000 --- 2efe0000      Stack in highmem
  86 2efe0000 --- 2f000000      heap in highmem
  87 2f000000                   TOM
  88
  89 AMD requirements in S3
  90 ======================
  91 Chip vendor like AMD will provide bunch of routines to restore the
  92 board.[2]
  93  * AmdS3Save: It is called in cold boot, save required register into
  94  non-volatile storage. Currently, we use SPI flash to store the data.
  95  * AmdInitResume: Restore the memory controller.
  96  * AmdS3LateRestore: Called after AmdInitResume, restore other
  97  register that memory.
  98  * (SouthBridge)InitS3EarlyRestore, (SouthBridge)InitS3LateRestore:
  99  Provided by Southbridge vendor code. Early is called before PCI
 100  enumeration, and Late is called after that.
 101
 102 Lifecycle of booting, sleeping and waking coreboot and Ubuntu
 103 =============================================================
 104 1. Cold boot.
 105 For a system with S3 feature, the BIOS needs to save some data to
 106 non-volatile storage at cold boot stage. What data need to be save are
 107 provided by AmdS3Save. After the wrapper calls the AmdS3Save, it gets
 108 the VolatileStorage and NvStorage, which are where the data are
 109 located. It is the wrappers's responsibility to save the data.[3][4]
 110 Currently, the wrappers allocate a CBFS modules in BIOS image. To do
 111 that, the wrapper needs to have the ability to write flash chips. It
 112 is not as comprehensive as flashrom. But for the SST chip on Parmer,
 113 MX chip on Thather, coreboot works well.[5]
 114
 115 2. OS goes in S3.
 116 For Linux, besides the kernel needs to do some saving, most distributions
 117 run some scripts. For Ubuntu, scripts are located at /usr/lib/pm-utils/sleep.d.
 118   # ls /usr/lib/pm-utils/sleep.d
 119    000kernel-change  49bluetooth        90clock       95led
 120    00logging         55NetworkManager   94cpufreq     98video-quirk-db-handler
 121    00powersave       60_wpa_supplicant  95anacron     99video
 122    01PulseAudio      75modules          95hdparm-apm
 123 The script with lower prefix runs before the one with higher prefix.
 124 99video is the last one.
 125 Those scripts have hooks called hibernate, suspend, thaw, resume. For
 126 each script, suspend is called when system sleeps and wakeup is called
 127 when system wakeups.
 128
 129 3. Firmware detects S3 wakeup
 130 As we mentioned, Firmware detects the SLP_TYPx to find out if the board
 131 wakes up. In romstage.c, AmdInitReset and AmdInitEarly are called
 132 as they are during cold boot. AmdInitResume and AmdS3LateRestore are
 133 called only during resume. For whole ramstage, coreboot goes through
 134 almost the same way as cold boot, other than not calling the AmdInitMid,
 135 AmdInitLate and AmdS3Save, and restoring all the MTRRs.
 136 At last step of coreboot stage, coreboot finds out the wakeup vector in FADT,
 137 written by OS, and jump.
 138
 139 4. OS resumes.
 140 When Linux resumes, all the sleeping scripts call their resume
 141 hooks. If we are more lucky, all the scripts can go through. More
 142 chances that the 99video hangs or fails to get the display
 143 back. Sometimes it can fixed if CONFIG_S3_VGA_ROM_RUN is unset in
 144 coreboot/Kconfig. That needs more troubleshooting.
 145
 146
 147 Reference
 148 =========
 149 [1]   ACPI40a, http://www.acpi.info/spec40a.htm
 150 [2]   coreboot Vendorcode, {top}/src/vendorcode/amd/agesa/{family}/Proc/Common/
 151 [3]   coreboot AGESA wrapper, {top}/src/mainboard/amd/parmer/agesawrapper.c
 152 [4]   coreboot AGESA wrapper, {top}/src/cpu/amd/agesa/s3_resume.c
 153 [5]   coreboot Southbridge, {top}/src/southbridge/amd/agesa/hudson/spi.c