From c1e4f8995362c6eb7d09dfc0618edcc636d30acc Mon Sep 17 00:00:00 2001 From: Lee Leahy Date: Thu, 7 Jan 2016 11:24:24 -0800 Subject: [PATCH] Documentation: Add x86 documentation for required files Document the required files to perform a minimal coreboot/FSP build for x86. TEST=None Change-Id: I65b2947114634fce982ce82fb7c577fd5f47ed10 Signed-off-by: Lee Leahy Reviewed-on: https://review.coreboot.org/13438 Tested-by: build bot (Jenkins) Reviewed-by: Martin Roth --- Documentation/Intel/Board/board.html | 83 +++++++++++++++++++ Documentation/Intel/Board/galileo.html | 100 +++++++++++++++++++++++ Documentation/Intel/SoC/quark.html | 98 +++++++++++++++++++++++ Documentation/Intel/SoC/soc.html | 105 +++++++++++++++++++++++++ Documentation/Intel/development.html | 78 ++++++++++++++++++ Documentation/Intel/fsp1_1.html | 50 ++++++++++++ Documentation/Intel/index.html | 42 ++++++++++ 7 files changed, 556 insertions(+) create mode 100644 Documentation/Intel/Board/board.html create mode 100644 Documentation/Intel/Board/galileo.html create mode 100644 Documentation/Intel/SoC/quark.html create mode 100644 Documentation/Intel/SoC/soc.html create mode 100644 Documentation/Intel/development.html create mode 100644 Documentation/Intel/fsp1_1.html create mode 100644 Documentation/Intel/index.html diff --git a/Documentation/Intel/Board/board.html b/Documentation/Intel/Board/board.html new file mode 100644 index 0000000000..e43985c62d --- /dev/null +++ b/Documentation/Intel/Board/board.html @@ -0,0 +1,83 @@ + + + + Board + + + +

x86 Board Development

+

+ Board development requires System-on-a-Chip (SoC) support. + The combined steps are listed + here. + The development steps for the board are listed below: +

+
    +
  1. Required Files
    2. +
+ + +
+

Required Files

+

+ Create the board directory as src/mainboard/<Vendor>/<Board>. +

+ +

+ The following files are required to build a new board: +

+
    +
  1. Kconfig.name - Defines the Kconfig value for the board
    2. +
  2. Kconfig +
      +
    1. Selects the SoC for the board and specifies the SPI flash size +
        +
      1. BOARD_ROMSIZE_KB_<Size>
        2. +
      2. SOC_<Vendor>_<Chip Family>
        3. +
      +
      2. +
    2. Declare the Kconfig values for: +
        +
      1. MAINBOARD_DIR
        2. +
      2. MAINBOARD_PART_NUMBER
        3. +
      3. MAINBOARD_VENDOR
        4. +
      +
      3. +
    +
    3. +
  3. devicetree.cb - Enable root bridge and serial port +
      +
    1. The first line must be "chip soc/Intel/<soc family>"; + this path is used by the generated static.c to include the chip.h + header file +
      2. +
    +
    4. +
  4. romstage.c +
      +
    1. Add routine mainboard_romstage_entry which calls romstage_common
      2. +
    +
    5. +
  5. Configure coreboot build: +
      +
    1. Set LOCALVERSION
      2. +
    2. FLASHMAP_OFFSET = 0x00700000
      3. +
    3. Select vendor for the board
      4. +
    4. Select the board
      5. +
    5. CBFS_SIZE = 0x00100000
      6. +
    6. Set the CPU_MICROCODE_CBFS_LEN
      7. +
    7. Set the CPU_MICROCODE_CBFS_LOC
      8. +
    8. Set the FSP_IMAGE_ID_STRING
      9. +
    9. Set the FSP_LOC
      10. +
    10. Disable GOP_SUPPORT
      11. +
    11. No payload
      12. +
    12. Choose the default value for all other options
      13. +
    +
    6. +
+ + +
+

Modified: 31 January 2016

+ + \ No newline at end of file diff --git a/Documentation/Intel/Board/galileo.html b/Documentation/Intel/Board/galileo.html new file mode 100644 index 0000000000..210a821b41 --- /dev/null +++ b/Documentation/Intel/Board/galileo.html @@ -0,0 +1,100 @@ + + + + Galileo Gen 2 + + + +

Intel® Galileo Gen 2 Development Board

+ + + + + +
Galileo Gen 2 + + + + +
+Warning: Use of the Intel® Galileo Gen 2 mainboard code requires modification of the +util/xcompile/xcompile file to change the machine architecture from i686 to i586 because +the Quark™ processor does not support the instructions introduced with the +Pentium™ 6 architecture. +
    +
  1. Edit the file util/xcompile/xcompile
    2. +
  2. Search for +-march
    3. +
  3. Replace i686 with i586
    4. +
  4. Save the result
    5. +
+Without this change the Quark™ processor will halt when it executes one of the +instructions introduced with the Pentium™ 6 architecture. +
+

+ The Intel® Galileo Gen 2 mainboard code was developed along with the Intel® + Quark™ SoC: +

+ +
+ + + +
+

Galileo Gen 2 Board Documentation

+ + + + +
+

Debug Tools

+ + + +
+

Modified: 30 January 2016

+ + diff --git a/Documentation/Intel/SoC/quark.html b/Documentation/Intel/SoC/quark.html new file mode 100644 index 0000000000..14dd5076b3 --- /dev/null +++ b/Documentation/Intel/SoC/quark.html @@ -0,0 +1,98 @@ + + + + Quark™ SoC + + + +

Intel® Quark™ SoC

+ + + + + +
Quark Block Diagram + + + + +
+Warning: Use of the Intel® Quark™ SoC code requires modification of the util/xcompile/xcompile file to change the machine +architecture from i686 to i586 because the Quark™ processor does not support the instructions +introduced with the Pentium™ 6 architecture. +
    +
  1. Edit the file util/xcompile/xcompile
    2. +
  2. Search for +-march
    3. +
  3. Replace i686 with i586
    4. +
  4. Save the result
    5. +
+Without this change the Quark™ processor will halt when it executes one of the +instructions introduced with the Pentium™ 6 architecture. +
+

+ The Quark™ SoC code was developed using the + Galileo Gen 2 + board: +

+ +
+ + + +
+

Quark™ Documentation

+ + + + +
+

Quark™ FSP

+ + + + +
+

Modified: 30 January 2016

+ + \ No newline at end of file diff --git a/Documentation/Intel/SoC/soc.html b/Documentation/Intel/SoC/soc.html new file mode 100644 index 0000000000..30821dcd9c --- /dev/null +++ b/Documentation/Intel/SoC/soc.html @@ -0,0 +1,105 @@ + + + + SoC + + + +

x86 System on a Chip (SoC) Development

+

+ SoC development is best done in parallel with development for a specific + board. The combined steps are listed + here. + The development steps for the SoC are listed below: +

+
    +
  1. FSP 1.1 required files
    2. +
  2. SoC Required Files
    3. +
  3. Start Booting
    4. +
  4. Early Debug
    5. +
+ + +
+

Required Files

+

+ Create the directory as src/soc/<Vendor>/<Chip Family>. +

+ +

+ The following files are required to build a new SoC: +

+
    +
  • Include files +
      +
    • include/soc/pei_data.h
      • +
    • include/soc/pm.h
      • +
    +
    • +
  • Kconfig - Defines the Kconfig value for the SoC and selects the tool + chains for the various stages: +
      +
    • select ARCH_BOOTBLOCK_<Tool Chain>
      • +
    • select ARCH_RAMSTAGE_<Tool Chain>
      • +
    • select ARCH_ROMSTAGE_<Tool Chain>
      • +
    • select ARCH_VERSTAGE_<Tool Chain>
      • +
    +
    • +
  • Makefile.inc - Specify the include paths
    • +
  • memmap.c - Top of usable RAM
    • +
+ + +
+

Start Booting

+

+ Some SoC parts require additional firmware components in the flash. + This section describes how to add those pieces. +

+ +

Intel Firmware Descriptor

+

+ The Intel Firmware Descriptor (IFD) is located at the base of the flash part. + The following command overwrites the base of the flash image with the Intel + Firmware Descriptor: +

+
dd if=descriptor.bin of=build/coreboot.rom conv=notrunc >/dev/null 2>&1
+ + +

Management Engine Binary

+

+ Some SoC parts contain and require that the Management Engine (ME) be running + before it is possible to bring the x86 processor out of reset. A binary file + containing the management engine code must be added to the firmware using the + ifdtool. The following commands add this binary blob: +

+
util/ifdtool/ifdtool -i ME:me.bin  build/coreboot.rom
+mv build/coreboot.rom.new build/coreboot.rom
+
+ + +

Early Debug

+

+ Early debugging between the reset vector and the time the serial port is enabled + is most easily done by writing values to port 0x80. +

+ + +

Success

+

+ When the reset vector is successfully invoked, port 0x80 will output the following value: +

+ + + +
+

Modified: 31 January 2016

+ + \ No newline at end of file diff --git a/Documentation/Intel/development.html b/Documentation/Intel/development.html new file mode 100644 index 0000000000..1dbef9cbda --- /dev/null +++ b/Documentation/Intel/development.html @@ -0,0 +1,78 @@ + + + + Development + + + +

Intel® x86 Coreboot/FSP Development Process

+

+ The x86 development process for coreboot is broken into the following components: +

+ +

+ The development process has two main phases: +

+
    +
  1. Minimal coreboot; This phase is single threaded
    2. +
  2. Adding coreboot features
    3. +
+ +

Minimal Coreboot

+

+ The combined steps below describe how to bring up a minimal coreboot for a + system-on-a-chip (SoC) and a development board: +

+ + + + +
The initial coreboot steps are single threaded! + The initial minimal FSP development is also single threaded. + Progress can speed up by adding more developers after the minimal coreboot/FSP + implementation reaches the payload. +
+
    +
  1. Get the necessary tools: +
      +
    • Linux: Use your package manager to install m4 bison flex and the libcurses development + package. +
        +
      • Ubuntu or other Linux distribution that use apt, run: +
        sudo apt-get install m4 bison flex libncurses5-dev
+
        +
        • +
      +
      • +
    +
    2. +
  2. Build the cross tools for i386: +
      +
    • Linux: +
      make crossgcc-i386
      + To use multiple processors for the toolchain build (which takes a long time), use: +
      make crossgcc-i386 CPUS=N
      + where N is the number of cores to use for the build. +
      • +
    +
    3. +
  3. Get something to build: +
      +
    1. FSP 1.1 required files
      2. +
    2. SoC required files
      3. +
    3. Board required files
      4. +
    +
    4. +
  4. Get result to start booting
    5. +
  5. Early Debug
    6. +
+ + +
+

Modified: 31 January 2016

+ + \ No newline at end of file diff --git a/Documentation/Intel/fsp1_1.html b/Documentation/Intel/fsp1_1.html new file mode 100644 index 0000000000..c210ffb89c --- /dev/null +++ b/Documentation/Intel/fsp1_1.html @@ -0,0 +1,50 @@ + + + + FSP 1.1 + + + +

x86 FSP 1.1 Development

+

+ Firmware Support Package (FSP) development requires System-on-a-Chip (SoC) + and board support. The combined steps are listed + here. + The development steps for FSP are listed below: +

+
    +
  1. Required Files
    2. +
+ +

+ FSP Documentation: +

+
    +
  • Intel® Firmware Support Package External Architecture Specification V1.1
    • +
+ +
+

Required Files

+

Coreboot Required Files

+
    +
  1. Create the following directories if they do not already exist: +
      +
    • src/vendorcode/intel/fsp/fsp1_1/<Chip Family>
      • +
    • 3rdparty/blobs/mainboard/<Board Vendor>/<Board Name>
      • +
    +
    2. +
  2. + The following files may need to be copied from the FSP build or release into the + directories above if they are not present or are out of date: +
      +
    • FspUpdVpd.h: src/vendorcode/intel/fsp/fsp1_1/<Chip Family>/FspUpdVpd.h
      • +
    • FSP.bin: 3rdparty/blobs/mainboard/<Board Vendor>/<Board Name>/fsp.bin
      • +
    +
    3. +
+ + +
+

Modified: 31 January 2016

+ + \ No newline at end of file diff --git a/Documentation/Intel/index.html b/Documentation/Intel/index.html new file mode 100644 index 0000000000..6d5810f110 --- /dev/null +++ b/Documentation/Intel/index.html @@ -0,0 +1,42 @@ + + + + Intel® x86 + + + +

Intel® x86 Boards

+ + + + +

Intel® x86 SoCs

+ + + + +

x86 Coreboot Development

+ + +

Documentation

+ + + +
+

Modified: 31 January 2016

+ + \ No newline at end of file