BaseTools/Capsule: Do not support -o with --dump-info
[mirror_edk2.git] / QuarkPlatformPkg / Readme.md
1 # **EDK II firmware for Intel(R) Quark SoC X1000 based platforms**
2
3 ## **Features**
4 * UEFI firmware image with ability to enable/disable major features such as
5 - Logging
6 - Source level debug using [Intel(R) UEFI Development Kit Debugger Tool](
7 https://firmware.intel.com/develop/intel-uefi-tools-and-utilities/intel-uefi-development-kit-debugger-tool)
8 - Boot Performance Measurements
9 - UEFI Secure Boot with Physical Presence
10 - TCG Measured Boot using TPM 1.2 hardware devices on I2C bus
11 * Minimal firmware image for initial power-on and debug
12 * UEFI Shell built into FLASH image
13 * UEFI Linux operating system boot support from Micro SD FLASH
14 * Hardware Support
15 - [Intel(R) Quark SoC X1000 CPU](
16 http://www.intel.com/content/www/us/en/embedded/products/quark/quark-x1000-datasheet.html)
17 - [Intel(R) Galileo Development Board](
18 http://www.intel.com/content/www/us/en/embedded/products/galileo/galileo-g1-datasheet.html)
19 - [Intel(R) Galileo Gen 2 Development Board](
20 http://www.intel.com/content/www/us/en/embedded/products/galileo/galileo-overview.html)
21 - HPET Timer
22 - Real Time Clock
23 * Major I/O Subsystems
24 - PCI including support for Mini PCI Express Cards
25 - USB using EHCI and OHCI host controllers
26 - Micro SD FLASH with FAT file system support
27 - Serial UART up to 921600 baud for console, logging, and debug
28 * ACPI Tables with ACPI S3 sleep state support
29 * SMBIOS Tables
30
31 ## **Windows Build Instructions**
32
33 ### Pre-requisites
34
35 * GIT client: Available from https://git-scm.com/downloads
36 * Microsoft Visual Studio.
37 - Visual Studio 2015 recommended and is used in the examples below.
38 * Microsoft Windows Driver Development Kit 3790.1830
39 - http://download.microsoft.com/download/9/0/f/90f019ac-8243-48d3-91cf-81fc4093ecfd/1830_usa_ddk.iso
40 - Mount ISO image
41 - Right click on ```x86\kitsetup.exe``` & choose **Run as administrator**
42 - Install to C:\WINDDK\3790.1830
43 - Uncheck all Component Groups
44 - Expand Build Environment Component
45 - Check Windows Driver Development Kit 16-bit Additional Build Tools
46 - Install
47 * ASL compiler: Available from http://www.acpica.org
48 - Install into ```C:\ASL``` to match default tools_def.txt configuration.
49 * Python 2.7: Available from http://www.python.org
50
51 Create a new directory for an EDK II WORKSPACE.
52
53 The code block below shows the GIT clone operations required to pull the EDK II
54 source tree and the edk2-non-osi repository that provides a binary file for the
55 Quark Remote Management Unit (RMU).
56
57 Next it sets environment variables that must be set before running
58 ```edksetup.bat```. Since content is being pulled from multiple repositories,
59 the EDK II [Multiple Workspace](
60 https://github.com/tianocore/tianocore.github.io/wiki/Multiple_Workspace)
61 feature is used.
62
63 Next, the EDK II BaseTools required to build firmware images are built.
64
65 Next, the ```edksetup.bat``` file is run to complete the initialization of an
66 EDK II build environment. Two example build commands are shown. The first one
67 in ```QuarkPlatformPlg/Quark.dsc``` builds a full UEFI firmware image that is
68 able to boot the built-in UEFI Shell and Linux from a micro SD FLASH card. The
69 second one in ```QuarkPlatformPkg/QuarkMin.dsc``` builds a minimal firmware
70 image that is useful for initial power-on and debug of new features.
71
72 ```cmd
73 git clone https://github.com/tianocore/edk2.git
74 git clone https://github.com/tianocore/edk2-non-osi.git
75
76 set PYTHON_HOME=c:\Python27
77 set WORKSPACE=%CD%
78 set PACKAGES_PATH=%WORKSPACE%\edk2;%WORKSPACE%\edk2-non-osi\Silicon\Intel
79 set EDK_TOOLS_PATH=%WORKSPACE%\edk2\BaseTools
80 cd %WORKSPACE%\edk2
81
82 BaseTools\toolsetup.bat Rebuild
83
84 edksetup.bat Rebuild
85
86 build -a IA32 -t VS2015x86 -p QuarkPlatformPkg/Quark.dsc
87 build -a IA32 -t VS2015x86 -p QuarkPlatformPkg/QuarkMin.dsc
88 ```
89
90 ## **Linux Build Instructions**
91
92 ### Pre-requisites
93
94 * GIT client
95 * GCC 4.9 compiler
96 * ASL compiler: Available from http://www.acpica.org.
97 * Python 2.7
98
99 Create a new directory for an EDK II WORKSPACE.
100
101 The code block below shows the GIT clone operations required to pull the EDK II
102 source tree and the edk2-non-osi repository that provides a binary file for the
103 Quark Remote Management Unit (RMU).
104
105 Next it sets environment variables that must be set before running
106 ```edksetup.bat```. Since content is being pulled from multiple repositories,
107 the EDK II [Multiple Workspace](
108 https://github.com/tianocore/tianocore.github.io/wiki/Multiple_Workspace)
109 feature is used.
110
111 Next, the EDK II BaseTools required to build firmware images are built.
112
113 Next, the ```edksetup.sh``` file is run to complete the initialization of an
114 EDK II build environment. Two example build commands are shown. The first one
115 in ```QuarkPlatformPlg/Quark.dsc``` builds a full UEFI firmware image that is
116 able to boot the built-in UEFI Shell and Linux from a micro SD FLASH card. The
117 second one in ```QuarkPlatformPkg/QuarkMin.dsc``` builds a minimal firmware
118 image that is useful for initial power-on and debug of new features.
119
120 ```sh
121 git clone https://github.com/tianocore/edk2.git
122 git clone https://github.com/tianocore/edk2-non-osi.git
123
124 export WORKSPACE=$PWD
125 export PACKAGES_PATH=$WORKSPACE/edk2:$WORKSPACE/edk2-non-osi/Silicon/Intel
126 export EDK_TOOLS_PATH=$WORKSPACE/edk2/BaseTools
127 cd $WORKSPACE/edk2
128
129 make -C BaseTools
130
131 . edksetup.sh BaseTools
132
133 build -a IA32 -t GCC49 -p QuarkPlatformPkg/Quark.dsc
134 build -a IA32 -t GCC49 -p QuarkPlatformPkg/QuarkMin.dsc
135 ```
136
137 ## **Build Features**
138
139 The table below contains a summary of the build flags to enable or disable
140 features on the build command line using ```-D``` flags.
141
142 | **Define Name** | **Default Value** | **Supported Values** |
143 | -------------------------- | ----------------- | -------------------- |
144 | ```GALILEO``` | GEN2 | GEN1, GEN2 |
145 | ```LOGGING``` | TRUE | TRUE, FALSE |
146 | ```SOURCE_DEBUG_ENABLE``` | FALSE | TRUE, FALSE |
147 | ```PERFORMANCE_ENABLE``` | FALSE | TRUE, FALSE |
148 | ```SECURE_BOOT_ENABLE``` | FALSE | TRUE, FALSE |
149 | ```MEASURED_BOOT_ENABLE``` | FALSE | TRUE, FALSE |
150 | ```TPM_12_HARDWARE``` | NONE | NONE, LPC, ATMEL_I2C, INFINEON_I2C |
151 | ```CAPSULE_ENABLE``` | FALSE | TRUE, FALSE |
152 | ```RECOVERY_ENABLE``` | FALSE | TRUE, FALSE |
153
154 * ```GALILEO``` - Used to specify the type of Intel(R) Galileo board type. The
155 default is ```GEN2``` for the [Intel(R) Galileo Gen 2 Development Board](
156 http://www.intel.com/content/www/us/en/embedded/products/galileo/galileo-overview.html).
157 The other supported value is ```GEN1``` for the [Intel(R) Galileo Development Board](
158 http://www.intel.com/content/www/us/en/embedded/products/galileo/galileo-g1-datasheet.html).
159 Add ```-D GALILEO=GEN1``` to the build command for [Intel(R) Galileo Development Board](
160 http://www.intel.com/content/www/us/en/embedded/products/galileo/galileo-g1-datasheet.html).
161
162 * ```LOGGING``` - Used to enable/disable logging messages from DEBUG() macros to
163 a serial UART. The default is TRUE for enabled when the BUILDTARGET is DEBUG
164 (```-b DEBUG```). The default is FALSE for disabled when the BUILDTARGET is
165 not DEBUG (e.g. ```-b RELEASE```). Add ```-D LOGGING``` to the build command
166 to force logging enabled. Add ```-D LOGGING=FALSE``` to force logging
167 disabled.
168
169 * ```SOURCE_DEBUG_ENABLE``` - Used to enable/disable source level debug using the
170 [Intel(R) UEFI Development Kit Debugger Tool](
171 https://firmware.intel.com/develop/intel-uefi-tools-and-utilities/intel-uefi-development-kit-debugger-tool).
172 The default is FALSE for disabled. Add ```-D SOURCE_DEBUG_ENABLE``` to the
173 build command line to enable source level debug.
174
175 * ```PERFORMANCE_ENABLE``` - Used to enable/disable boot performance measurement.
176 The default is FALSE for disabled. Add ```-D PERFORMANCE_ENABLE``` to the
177 build command line to enable boot performance measurement. When this feature
178 is enabled, both ```LOGGING``` and ```SOURCE_DEBUG_ENABLE``` are automatically
179 disabled so there is not boot time overhead from the serial UART for logging
180 messages or the debug agent.
181
182 * ```SECURE_BOOT_ENABLE``` - Used to enable/disable UEFI Secure Boot features.
183 The default is FALSE for disabled. Add ```-D SECURE_BOOT_ENABLE``` to the
184 build command line to enable UEFI Secure Boot features.
185
186 * ```MEASURED_BOOT_ENABLE``` - Used to enable/disable measurement of firmware
187 code and data into a TPM 1.2 hardware device. The default is FALSE for
188 disabled. Add ```-D MEASURED_BOOT_ENABLE``` to the build command line to
189 enable UEFI Secure Boot features.
190
191 * ```TPM_12_HARDWARE``` - Used to specify the type of TPM 1.2 hardware device
192 that is connected to the Galileo board. This define is valid if the measure
193 boot feature is enabled using ```-D MEASURED_BOOT_ENABLE```. The default is
194 NONE for no TPM 1.2 hardware device connected. Add ```-D TPM_12_HARDWARE=LPC```
195 for a TPM hardware device attached to an LPC bus (not supported on on Intel(R)
196 Quark SoC X1000). Add ```-D TPM_12_HARDWARE=ATMEL_I2C``` for an
197 [Atmel AT97SC3204T](http://www.atmel.com/devices/AT97SC3204T.aspx) or
198 [Atmel AT97SC3205T](http://www.atmel.com/images/atmel-8883s-tpm-at97sc3205t-datasheet-summary.pdf)
199 attached to the I2C bus of the Galileo Arduino header. Add
200 ```-D TPM_12_HARDWARE=INFINION_I2C``` for an [Infineon SLB9645](
201 http://www.infineon.com/dgdl/Infineon-TPM+SLB+9645-DS-v01_00-EN.pdf?fileId=5546d4625185e0e201518b83d0c63d7c)
202 attached to the I2C bus of the Galileo Arduino header. The ATMEL_I2C setting
203 has been tested with the [CryptoShield](https://www.sparkfun.com/products/13183)
204 available from [SparkFun](https://www.sparkfun.com/).
205
206 * ```CAPSULE_ENABLE``` - Used to enable/disable capsule update features.
207 The default is FALSE for disabled. Add ```-D CAPSULE_ENABLE``` to the
208 build command line to enable capsule update features.
209 The build process generate capsule update image - QUARKFIRMWAREUPDATECAPSULEFMPPKCS7.Cap.
210 The user need copy QUARKFIRMWAREUPDATECAPSULEFMPPKCS7.Cap and CapsuleApp.efi
211 to a storage media attached to the Quark Board.
212 Then the user can boot to shell and run ```CapsuleApp QUARKFIRMWAREUPDATECAPSULEFMPPKCS7.Cap```.
213 In next reboot, the system firmware is updated.
214
215 * ```RECOVERY_ENABLE``` - Used to enable/disable recovery features.
216 The default is FALSE for disabled. Add ```-D RECOVERY_ENABLE``` to the
217 build command line to enable recovery features.
218 The build process generates the recovery capsule image - QUARKREC.Cap.
219 Then the user need copy QUARKREC.Cap to a USB KEY, plug the USB KEY to the Quark Board.
220 In next boot, if a user runs ForceRecovery.efi in shell, or if a user presses the RESET button during power on, warm reset or REBOOT,
221 or if the FvMain is corrupted in flash, the system will boot into recovery mode.
222
223 ### **Example Build Commands**
224
225 Default build with logging enabled:
226
227 ```build -a IA32 -t VS2015x86 -p QuarkPlatformPkg/Quark.dsc```
228
229 Release build with logging disabled:
230
231 ```build -a IA32 -t VS2015x86 -p QuarkPlatformPkg/Quark.dsc -b RELEASE```
232
233 Enable source level debugging:
234
235 ```build -a IA32 -t VS2015x86 -p QuarkPlatformPkg/Quark.dsc -D SOURCE_DEBUG_ENABLE```
236
237 Enable boot performance metrics:
238
239 ```build -a IA32 -t VS2015x86 -p QuarkPlatformPkg/Quark.dsc -D PERFORMANCE_ENABLE```
240
241 Enable UEFI Secure Boot features:
242
243 ```build -a IA32 -t VS2015x86 -p QuarkPlatformPkg/Quark.dsc -D UEFI_SECURE_BOOT```
244
245 Enable UEFI Secure Boot and Measured Boot using Atmel I2C TPM hardware device:
246
247 ```build -a IA32 -t VS2015x86 -p QuarkPlatformPkg/Quark.dsc -D UEFI_SECURE_BOOT -D MEASURED_BOOT_ENABLE -D TPM_12_HARDWARE=ATMEL_I2C```
248
249 ## **FLASH Update using DediProg SF100**
250
251 Once the sources have been downloaded, an EDK II build environment established,
252 and an EDK II firmware image has been built, the EDK II firmware image needs to
253 installed into the FLASH device on the target Galileo development board. One
254 way to do this is with the [Dediprog SF100 IC Programmer](
255 http://www.dediprog.com/pd/spi-flash-solution/SF100).
256
257 * Install the DediProg SF100 software.
258
259 * Connect the DediProg SF100 to the Galileo development board.
260
261 ![](https://github.com/tianocore/tianocore.github.io/wiki/Projects/QuarkPlatformPkg/Images/Dediprog.jpg)
262
263 * Make sure ```dpcmd.exe``` is in ```PATH```
264
265 ```PATH=%PATH%;"c:\Program Files (x86)\DediProg\SF100"```
266
267 * **NOTE**: It is recommended that the FLASH image that was shipped with the
268 Galileo development board be read and saved before updating FLASH image. The
269 command shown below read the FLASH image and saves it to the file
270 called ```GalileoOriginalFirmware.bin```.
271
272 ```dpcmd.exe -r GalileoOriginalFirmware.bin```
273
274 * Update FLASH image using either the DediProg SF100 GUI or ```dpcmd.exe```.
275 - Example update of Galileo firmware image when BUILDTARGET is DEBUG (default)
276
277 ```dpcmd.exe -u%WORKSPACE%\Build\Quark\DEBUG_VS2015x86\FV\QUARK.fd ```
278
279 - Example update of Galileo firmware image when BUILDTARGET is RELEASE
280 (```-b RELEASE```)
281
282 ```dpcmd.exe -u%WORKSPACE%\Build\Quark\RELEASE_VS2015x86\FV\QUARK.fd ```
283
284 ## **Setting up a Serial Console and Booting to UEFI Shell**
285
286 After the FLASH is updated on Galileo, a serial cable is connected between the
287 host system and the Galileo target. A serial terminal emulator (such as
288 [Tera Term](https://en.osdn.jp/projects/ttssh2/releases/)) can be used to see
289 the logging messages from DEBUG() macros and the serial console for the UEFI
290 Boot Manager, UEFI Shell, and operating system.
291
292 The default serial communication parameters for the Intel(R) Galileo Gen 2
293 Development Board is 921600,n,8,1 with no hardware flow control.
294
295 ![](https://github.com/tianocore/tianocore.github.io/wiki/Projects/QuarkPlatformPkg/Images/TeraTermSerialParameters.png)
296
297 The default serial communication parameters for the Intel(R) Galileo Development
298 Board is 461800,n,8,1 with no hardware flow control.
299
300 The following changes to the [Tera Term](https://en.osdn.jp/projects/ttssh2/releases/)
301 configuration files are recommended for UEFI serial console compatibility.
302 Some of the later use cases involve using the TCPIP mode, so some of these
303 recommendation apply to the TCPIP use cases.
304
305 * TERATERM.INI - Set terminal size to 80 x 25 and terminal settings to UTF8.
306
307 ![](https://github.com/tianocore/tianocore.github.io/wiki/Projects/QuarkPlatformPkg/Images/TeraTermTerminal.png)
308
309 * TERATERM.INI - Set font type to Terminal to support box drawing glyphs.
310
311 ![](https://github.com/tianocore/tianocore.github.io/wiki/Projects/QuarkPlatformPkg/Images/TeraTermFont.png)
312
313 * TERATERM.INI - Disable line mode to make TCPIP mode work like COM port mode.
314
315 ```ini
316 ; Line at a time mode
317 EnableLineMode=off
318 ```
319
320 * KEYBOARD.CNF - Disable VT function keys for F5..F10
321
322 ```ini
323 [VT function keys]
324 ;F6 key
325 ;F6=64
326 ;F7 key
327 ;F7=65
328 ;F8 key
329 ;F8=66
330 ;F9 key
331 ;F9=67
332 ;F10 key
333 ;F10=68
334 ```
335
336 * KEYBOARD.CNF - Disable X function keys for F1..F4
337
338 ```ini
339 [X function keys]
340 ; F1 key
341 XF1=off
342 ; F2 key
343 ;XF2=60
344 XF2=off
345 ; F3 key
346 ;XF3=61
347 XF3=off
348 ; F4 key
349 ;XF4=62
350 XF4=off
351 ; F5 key
352 ;XF5=63
353 ```
354
355 * KEYBOARD.CNF - Add UEFI serial console sequences for F1..F10
356
357 ```ini
358 [User keys]
359 User1=59,0,$1B[M
360 User2=60,0,$1B[N
361 User3=61,0,$1B[O
362 User4=62,0,$1B[P
363 User5=63,0,$1B[Q
364 User6=64,0,$1B[R
365 User7=65,0,$1B[S
366 User8=66,0,$1B[T
367 User9=67,0,$1B[U
368 User10=68,0,$1B[V
369 ```
370
371 Connect power adapter to Galileo development board, and the logging messages
372 should be seen, followed by 5 second countdown, followed by an automatic boot to
373 the built-in UEFI Shell.
374
375 ![](https://github.com/tianocore/tianocore.github.io/wiki/Projects/QuarkPlatformPkg/Images/UefiShell.png)
376
377 ## **Source Level Debug Using Intel(R) UEFI Development Kit Debugger Tool**
378
379 ### Pre-requisites
380
381 * Intel(R) UEFI Development Kit Debugger Tool User Manual for Ver 1.5 or higher:
382 Available from https://firmware.intel.com/develop/intel-uefi-tools-and-utilities/intel-uefi-development-kit-debugger-tool
383 * Intel(R) UEFI Development Kit Debugger Tool Ver 1.5 or higher: Available from
384 https://firmware.intel.com/develop/intel-uefi-tools-and-utilities/intel-uefi-development-kit-debugger-tool
385 * [Tera Term](https://en.osdn.jp/projects/ttssh2/releases/) or other serial
386 terminal emulator with TCPIP support
387
388 Follow instructions in Intel(R) UEFI Development Kit Debugger Tool User manual
389 to setup host system.
390
391 Build a firmware image with SOURCE_DEBUG_ENABLE enabled
392 (```-D SOURCE_DEBUG_ENABLE```). This will select the appropriate libraries,
393 debug agent, and PCDs for Galileo. Galileo does not support a USB 2.0 debug
394 port, so only the UART based communications library is used.
395
396 Use Dediprog SF100 to update the Galileo development board FLASH image.
397
398 Update the ```[Debug Port]``` section of the SoftDebugger.ini file with the host
399 side UART configuration settings. The following example uses COM5, which must
400 be updated with the COM port the Galileo target is attached. The following
401 example also shows a baud rate of 921600 which is correct for a Galileo Gen 2.
402 If a Galileo Gen 1 is being used, set the baud rate to 460800. By default, the
403 Galileo console is redirected to TCPIP port 20715.
404
405 ```ini
406 [Debug Port]
407 Channel = Serial
408 Port = COM5
409 FlowControl = 0
410 BaudRate = 921600
411 Server =
412 ```
413
414 Connect power adapter to Galileo development board and run a command script with
415 the contents below to start a Tera Term session on TCPIP port 20715 and start
416 the Intel(R) UEFI Development Kit Debugger Tool using UART connection between
417 the host and target and WinDbg. The REBOOT button on the Galileo development
418 board may need to be pressed for the debugger to perform the initial connect.
419
420 ```cmd
421 start "Console" /B "c:\Program Files (x86)\teraterm\ttermpro.exe" localhost:20715 /nossh
422 start "Debugger" /B "C:\Program Files (x86)\Intel\Intel(R) UEFI Development Kit Debugger Tool\eXdi.exe" /LaunchWinDbg
423 ```
424
425 The figure below should be seen when a connection is made. The SoftDebugger
426 Debug Console window shows the status of the connection between the host and the
427 target. The Tera Term window shows the console output from the SEC phase until
428 the debug agent is initialized. The WinDbg window shows that the debugger is
429 connected and the WinDbg application can be used for run control, breakpoint
430 management, and viewing call stacks, local variables, global variables, etc.
431
432 ![](https://github.com/tianocore/tianocore.github.io/wiki/Projects/QuarkPlatformPkg/Images/UdkDebugger.png)
433
434 ## **Debug Using Intel(R) System Debugger using OpenOCD**
435
436 Setup hardware and software components following the instructions in the article at:
437 https://software.intel.com/en-us/articles/using-intel-system-debugger-with-openocd
438
439 Connect power adapter to Galileo development board.
440
441 The following batch file starts Tera Term serial console on COM5 at 921600 baud,
442 starts OpenOCD using a Flyswatter2, and starts Intel(R) System Studio Debugger.
443 Select the **Connect** button to complete the host to target connection.
444
445 ```cmd
446 set OPENOCD="C:\Program Files (x86)\IntelSWTools\system_studio_for_windows_2016.0.023\debugger\openocd"
447 start "Console" /B "c:\Program Files (x86)\teraterm\ttermpro.exe" /C=5 /BAUD=921600
448 start "OpenOcd" /B %OPENOCD%\bin\openocd.exe -f ..\scripts\interface\ftdi\flyswatter2.cfg -f ..\scripts\board\quark_x10xx_board.cfg
449 call "C:\Program Files (x86)\IntelSWTools\System Debugger 2016\system_debugger\start_xdb_gdb_remote.bat"
450 ```
451
452 When **Reset Target** is selected, the Galileo development board does not always
453 halt at the first instruction at the reset vector. If debug is required from
454 the first instruction of the reset vector, then update the file
455 ```UefiCpuPkg/SecCore/Ia32/ResetVector.asm``` and change the two NOP
456 instructions at the label ```ResetHandler:``` to ```JMP $```. This puts the CPU
457 into a wait loop until the debugger is connected and the debugger is used to set
458 instruction pointer to the next instruction.
459
460 ```
461 ;
462 ; For IA32, the reset vector must be at 0xFFFFFFF0, i.e., 4G-16 byte
463 ; Execution starts here upon power-on/platform-reset.
464 ;
465 ResetHandler:
466 ; nop
467 ; nop
468 jmp $
469 ApStartup:
470 ;
471 ; Jmp Rel16 instruction
472 ; Use machine code directly in case of the assembler optimization
473 ; SEC entry point relative address will be fixed up by some build tool.
474 ;
475 ; Typically, SEC entry point is the function _ModuleEntryPoint() defined in
476 ; SecEntry.asm
477 ;
478 DB 0e9h
479 DW -3
480 ```
481
482 ## **Install, Configure, and Boot Linux**
483
484 * Download SD Card Linux Image: Available at
485 http://www.intel.com/content/www/us/en/support/boards-and-kits/intel-galileo-boards/000005614.html
486 * Extract the SD Card Linux Image to a FAT formatted Micro SD FLASH device
487 * Install Micro SD FLASH device into Galileo development board
488
489 Connect power adapter to Galileo development board and boot to the UEFI Shell.
490
491 From the UEFI Shell execute the following commands to copy the GRUB EFI boot
492 loader to ```\efi\boot\bootia32.efi```. This allows the UEFI Boot Manager, on
493 all future boots, to auto detect that the Micro SD FLASH device is bootable.
494
495 ```
496 Shell> connect -r
497 Shell> map -r
498 Shell> fs0:
499 FS0:> mkdir efi
500 FS0:> mkdir efi\boot
501 FS0:> cp grub.efi efi\boot\bootia32.efi
502 ```
503
504 The GRUB boot loader is set to a UART baud rate of 115200. A couple changes are
505 required to change the baud rate to 460800 for Galileo Gen 1 or 921600 for
506 Galileo Gen 2. From the UEFI Shell, execute the following commands to make a
507 backup copy and edit the GRUB configuration file.
508
509 ```
510 FS0:> cp boot\grub\grub.conf boot\grub\grub.conf.org
511 FS0:> edit boot\grub\grub.conf
512 ```
513
514 * Delete the lines associated with the boot option with the following title.
515
516 ```
517 title Clanton SVP kernel-SPI initrd-SPI IMR-On IO-APIC/HPET NoEMU
518 ```
519
520 * Replace the two instances of 115200 in the following line to 460800 for
521 Galileo Gen 1 or 921600 for Galileo Gen 2.
522
523 ```
524 kernel /bzImage root=/dev/ram0 console=ttyS1,115200n8 earlycon=uart8250,mmio32,$EARLY_CON_ADDR_REPLACE,115200n8 reboot=efi,warm apic=debug rw LABEL=boot debugshell=5 rootimage=image-full-galileo-clanton.ext3
525 ```
526 * Press F3 to save the file
527 * Run the ```exit``` command to exit from the UEFI Shell and return to the
528 UEFI Boot Manager
529 * Select **Boot Manager**
530 * Select **UEFI Misc Device** for the Micro SD FLASH device.
531 * GRUB should run and Linux should boot with serial log messages.
532 * When the serial log messages stop, change the Tera Term baud rate to 115200
533 * Login as ```root```. No password is required.
534 * Use ```vi``` to edit ```/etc/inittab```
535 * Change the baud rate of ttyS1 from 115200 to 460800 for Galileo Gen 1 or
536 921600 for Galileo Gen 2. The line that need to be updated is shown below
537
538 ```
539 S:2345:respawn:/sbin/getty 115200 ttyS1
540 ```
541
542 * Save the updated ```/etc/inittab```
543 * Run ```reboot -f``` to shutdown Linux and reboot the platform.
544 * Set the Tera Term baud rate back to 460800 for Galileo Gen 1 or 921600 for
545 Galileo Gen 2.
546
547 After these changes both the EDK II firmware and the Linux operating system use
548 the same baud rate.
549
550 ### **Testing ACPI S3 Sleep**
551
552 The ACPI S3 Sleep and Resume feature can be tested on a Galileo development
553 board using the Real Time Clock (RTC) for a wake event. The shell script shown
554 below arms the RTC wake alarm 10 seconds in the future and puts the system to
555 sleep. A shorter time in seconds can be passed in as the first argument to the
556 script, but do not use times shorter than 2 or 3 seconds.
557
558 **NOTE**: The stmmac module is unloaded because the module is not compatible
559 with S3 resume.
560
561 ```sh
562 #
563 # Unload NIC driver that causes S3 to fail
564 #
565 rmmod stmmac
566
567 #
568 # Disable RTC wake alarm
569 #
570 echo 0 > /sys/class/rtc/rtc0/wakealarm
571
572 #
573 # Compute wake time that is $1 seconds in the future
574 #
575 let WakeTime=`date '+%s'`
576 echo $WakeTime
577 if ["$1" = ""]; then
578 let WakeTime=$WakeTime+10
579 else
580 let WakeTime=$WakeTime+$1
581 fi
582 echo $WakeTime
583
584 #
585 # Enable RTC wake alarm $1 seconds in the future
586 #
587 echo $WakeTime > /sys/class/rtc/rtc0/wakealarm
588
589 #
590 # Put systems into ACPI S3 sleep state
591 #
592 echo mem > /sys/power/state
593 ```
594
595 ## **UEFI Secure Boot Feature and Physical Presence**
596
597 Build a firmware image with SECURE_BOOT_ENABLE enabled
598 (```-D SECURE_BOOT_ENABLE```). This builds in support for UEFI authenticated
599 variables, UEFI image verification, and UEFI Secure Boot configuration screens
600 in the Device Manager. In order to change the UEFI Secure Boot configuration,
601 the user must assert physical presence. The Galileo development board only has
602 two push buttons (REBOOT and RESET). The REBOOT button unconditionally reboots
603 the platform. The RESET button asserts the reset signal on the Arduino header
604 and is also connected to a GPIO pin, so the state of the RESET button can be
605 read. The user asserts physical presence by holding the RESET button while the
606 Galileo development board boots, or by holding the RESET button while selecting
607 the **Secure Boot Configuration** option in the Device Manager.
608
609 Use Dediprog SF100 to update the Galileo development board FLASH image.
610
611 Connect power adapter to Galileo development board and boot to the UEFI Boot
612 Manager by pressing F2 or running the ```exit``` command from the UEFI Shell.
613 Select **Device Manager** and then**Secure Boot Configuration**. Change
614 **Customize Secure Boot** to **Customized** and then select **Custom Secure Boot
615 Options**. If **Custom Secure Boot Options** can not be selected, then physical
616 presence was not asserted using one of two methods listed above. Assert
617 physical presence and try again.
618
619 The **Custom Secure Boot Options** screen allows the Galileo development board
620 to be enrolled into UEFI Secure Boot. See [How to Sign UEFI Drivers & Application V1.31](
621 http://sourceforge.net/projects/edk2/files/General%20Documentation/SigningUefiImages%20-v1dot31.pdf/download)
622 in the [SecurityPkg Wiki](https://github.com/tianocore/tianocore.github.io/wiki/SecurityPkg)
623 for details on how to complete the UEFI Secure Boot enrollment.
624
625 ## **Enable Measured Boot Feature using Atmel I2C TPM on CryptoShield**
626
627 Build a firmware image with MEASURED_BOOT_ENABLE enabled
628 (```-D MEASURED_BOOT_ENABLE```) and TPM_12_HARDWARE set to ATMEL_I2C
629 (```-D TMP_12_HARDWARE=ATMEL_I2C```). This builds in the TCG PEIM and DXE
630 modules and uses the library for the Atmel I2C TPM hardware device.
631
632 Use Dediprog SF100 to update the Galileo development board FLASH image.
633
634 Attach the CryptoShield to the Arduino header of the Galileo development board
635 as shown below.
636
637 ![](https://github.com/tianocore/tianocore.github.io/wiki/Projects/QuarkPlatformPkg/Images/GalileoCryptoShield.jpg)
638
639 Connect power adapter to Galileo development board and boot to the UEFI Shell.
640 In the boot logging messages, messages similar to the following should be seen
641 as the Atmel I2C TPM hardware device is detected and used to measure the
642 contents of firmware volumes and firmware tables.
643
644 ```
645 Loading PEIM at 0x0000FC75188 EntryPoint=0x0000FC75260 TrEEConfigPei.efi
646 PROGRESS CODE: V03020002 I0
647 TrEEConfiguration.TpmDevice from Setup: 1
648 DetectTpmDevice:
649 TpmDevice final: 1
650 TpmDevice PCD: 8B01E5B6-4F19-46E8-AB93-1C53671B90CC
651 . . .
652 Loading PEIM at 0x0000FC70190 EntryPoint=0x0000FC70260 TcgPei.efi
653 PROGRESS CODE: V03020002 I0
654 Install PPI: E9DB0D58-D48D-47F6-9C6E-6F40E86C7B41
655 Install PPI: A030D115-54DD-447B-9064-F206883D7CCC
656 PROGRESS CODE: V03020003 I0
657 The FV which is measured by TcgPei starts at: 0xFFF10000
658 The FV which is measured by TcgPei has the size: 0xF0000
659 The FV which is measured by TcgPei starts at: 0xFFD00000
660 The FV which is measured by TcgPei has the size: 0x1E0000
661 . . .
662 Loading driver at 0x0000F620000 EntryPoint=0x0000F620260 TcgDxe.efi
663 . . .
664 TPM TcgDxe Measure Data when ReadyToBoot
665 ```
666 See the [SecurityPkg Wiki](https://github.com/tianocore/tianocore.github.io/wiki/SecurityPkg)
667 for additional details on EDK II TPM support
668
669 ## **Measuring Boot Performance**
670
671 Build a firmware image with PERFORMANCE_ENABLE enabled
672 (```-D PERFORMANCE_ENABLE```). This builds in the UEFI Shell and the DP.EFI
673 (Dump Performance) into a firmware volume and also includes a simple file system
674 driver for firmware volumes so the DP.EFI command can be run out of the FLASH.
675
676 Use Dediprog SF100 to update the Galileo development board FLASH image.
677
678 Connect power adapter to Galileo development board and let it boot to the UEFI
679 Shell. Then use the REBOOT button or the ```reset``` UEFI Shell command to
680 reboot the Galileo development board. The first boot after a FLASH update does
681 extra work that is only performed one time. In order to get correct performance
682 measurements, use the 2nd or later boots. After the 2nd boot, run the
683 ```dp -s``` command. The output should look similar to the figure below.
684
685 ![](https://github.com/tianocore/tianocore.github.io/wiki/Projects/QuarkPlatformPkg/Images/DpCommand.png)