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. SoC Required Files
  3. Start Booting
  4. Early Debug
  5. Bootblock
  6. TempRamInit
  7. Romstage
    1. Enable Serial Output"
    2. Get the Previous Sleep State
    3. Add the MemoryInit Support
    4. Disable the Shadow ROM
  8. Ramstage
    1. Start Device Tree Processing
    2. Set up the Memory Map"
  9. ACPI Tables
  10. Legacy Hardware

Required Files

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

The following files are required to build a new SoC:

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:

Bootblock

Implement the bootblock using the following steps:

  1. Create the directory as src/soc/<Vendor>/<Chip Family>/bootblock
  2. Add the timestamp.inc file which initializes the floating point registers and saves the initial timestamp.
  3. Add the bootblock.c file which:
    1. Enables memory-mapped PCI config access
    2. Updates the microcode by calling intel_update_microcode_from_cbfs
    3. Enable ROM caching
  4. Edit the src/soc/<Vendor>/<Chip Family>/Kconfig file
    1. Add the BOOTBLOCK_CPU_INIT value to point to the bootblock.c file
    2. Add the CHIPSET_BOOTBLOCK_INCLUDE value to point to the timestamp.inc file
  5. Edit the src/soc/<Vendor>/<Chip Family>/Makefile.inc file
    1. Add the bootblock subdirectory
  6. Edit the src/soc/<Vendor>/<Chip Family>/memmap.c file
    1. Add the fsp/memmap.h include file
    2. Add the mmap_region_granularity routine
  7. Add the necessary .h files to define the necessary values and structures
  8. When successful port 0x80 will output the following values:
    1. 0x01: POST_RESET_VECTOR_CORRECT - Bootblock successfully executed the reset vector and entered the 16-bit code at _start
    2. 0x10: POST_ENTER_PROTECTED_MODE - Bootblock executing in 32-bit mode
    3. 0x10 - Verstage/romstage reached 32-bit mode

Build Note: The following files are included into the default bootblock image:

TempRamInit

Enable the call to TempRamInit in two stages:

  1. Finding the FSP binary in the read-only CBFS region
  2. Call TempRamInit

Find FSP Binary

Use the following steps to locate the FSP binary:

  1. Edit the src/soc/<Vendor>/<Chip Family>/Kconfig file
    1. Add "select USE_GENERIC_FSP_CAR_INC" to enable the use of src/drivers/intel/fsp1_1/cache_as_ram.inc
    2. Add "select SOC_INTEL_COMMON" to enable the use of the files from src/soc/intel/common specifically building util.c
  2. Debug the result until port 0x80 outputs
    1. 0x90: POST_FSP_TEMP_RAM_INIT - Just before calling TempRamInit
    2. Alternating 0xba and 0x01 - The FSP image was not found
  3. Add the FSP binary file to the flash image
  4. Set the following Kconfig values:
  5. Debug the result until port 0x80 outputs
    1. 0x90: POST_FSP_TEMP_RAM_INIT - Just before calling TempRamInit
    2. Alternating 0xbb and 0x02 - TempRamInit executed, no CPU microcode update found

Calling TempRamInit

Use the following steps to debug the call to TempRamInit:

  1. Add the CPU microcode update file
    1. Add the microcode file with the following command 
      util/cbfstool/cbfstool build/coreboot.rom add -t microcode -n cpu_microcode_blob.bin -b <base address> -f cpu_microcode_blob.bin
    2. Set the Kconfig values
      • CONFIG_CPU_MICROCODE_CBFS_LOC set to the value from the previous step
      • CONFIG_CPU_MICROCODE_CBFS_LEN
  2. Debug the result until port 0x80 outputs
    1. 0x90: POST_FSP_TEMP_RAM_INIT - Just before calling TempRamInit
    2. 0x2A - Just before calling cache_as_ram_main which is the start of the verstage code which may be part of romstage

Romstage

Serial Output

The following steps add the serial output support for romstage:

  1. Create the romstage subdirectory
  2. Add romstage/romstage.c
    1. Program the necessary base addresses
    2. Disable the TCO
  3. Add romstage/Makefile.inc
    1. Add romstage.c to romstage
  4. Add gpio configuration support if necessary
  5. Add the necessary .h files to support the build
  6. Update Makefile.inc
    1. Add the romstage subdirectory
    2. Add the gpio configuration support file to romstage
  7. Set the necessary Kconfig values to enable serial output:

Determine Previous Sleep State

The following steps implement the code to get the previous sleep state:

  1. Implement the fill_power_state routine which determines the previous sleep state
  2. Debug the result until port 0x80 outputs
    1. 0x32: - Just after entering romstage_common
    2. 0x33 - Just after calling soc_pre_ram_init
    3. 0x34: - Just after entering raminit

MemoryInit Support

The following steps implement the code to support the FSP MemoryInit call:

  1. Add the chip.h header file to define the UPD values which get passed to MemoryInit. Skip the values containing SPD addresses and DRAM configuration data which is determined by the board.

    Build Note: The src/mainboard/<Vendor>/<Board>/devicetree.cb file specifies the default values for these parameters. The build process creates the static.c module which contains the config data structure containing these values.

  2. Edit romstage/romstage.c
    1. Implement the romstage/romstage.c/soc_memory_init_params routine to copy the values from the config structure into the UPD structure
    2. Implement the soc_display_memory_init_params routine to display the updated UPD parameters by calling fsp_display_upd_value

Disable Shadow ROM

A shadow of the SPI flash part is mapped from 0x000e0000 to 0x000fffff. This shadow needs to be disabled to allow RAM to properly respond to this address range.

  1. Edit romstage/romstage.c and add the soc_after_ram_init routine

Ramstage

Start Device Tree Processing

The src/mainboard/<Vendor>/<Board>/devicetree.cb file drives the execution during ramstage. This file is processed by the util/sconfig utility to generate build/mainboard/<Vendor>/<Board>/static.c. The various state routines in src/lib/hardwaremain.c call dev_* routines which use the tables in static.c to locate operation tables associated with the various chips and devices. After location the operation tables, the state routines call one or more functions depending upon the state of the state machine.

Chip Operations

Kick-starting the ramstage state machine requires creating the operation table for the chip listed in devicetree.cb:

  1. Edit src/soc/<SoC Vendor>/<SoC Family>/chip.c:
    1. This chip's operation table has the name soc_<SoC Vendor>_<SoC Family>_ops which is derived from the chip path specified in the devicetree.cb file.
    2. Use the CHIP_NAME macro to specify the name for the chip
    3. For FSP 1.1, specify a .init routine which calls intel_silicon_init
  2. Edit src/soc/<SoC Vendor>/<SoC Family>/Makefile.inc and add chip.c to ramstage

Domain Operations

coreboot uses the domain operation table to initiate operations on all of the devices in the domain. By default coreboot enables all PCI devices which it finds. Listing a device in devicetree.cb gives the board vendor control over the device state. Non-PCI devices may also be listed under PCI device such as the LPC bus or SMbus devices.

  1. Edit src/soc/<SoC Vendor>/<SoC Family>/chip.c:
    1. The domain operation table is typically placed in src/soc/<SoC Vendor>/<SoC Family>/chip.c. The table typically looks like the following: 
      static struct device_operations pci_domain_ops = {
	.read_resources	= pci_domain_read_resources,
	.set_resources	= pci_domain_set_resources,
	.scan_bus	= pci_domain_scan_bus,
	.ops_pci_bus	= pci_bus_default_ops,
};
    2. Create a .enable_dev entry in the chip operations table which points to a routine which sets the domain table for the device with the DEVICE_PATH_DOMAIN. 
      	if (dev->path.type == DEVICE_PATH_DOMAIN) {
		dev->ops = &pci_domain_ops;
	}
    3. During the BS_DEV_ENUMERATE state, ramstage now display the device IDs for the PCI devices on the bus.
  2. Set CONFIG_DEBUG_BOOT_STATE=y in the .config file
  3. Debug the result until the PCI vendor and device IDs are displayed during the BS_DEV_ENUMERATE state.

PCI Device Drivers

PCI device drivers consist of a ".c" file which contains a "pci_driver" data structure at the end of the file with the attribute tag "__pci_driver". This attribute tag places an entry into a link time table listing the various coreboot device drivers.

Specify the following fields in the table:

  1. .vendor - PCI vendor ID value of the device
  2. .device - PCI device ID value of the device or
    .devices - Address of a zero terminated array of PCI device IDs
  3. .ops - Operations table for the device. This is the address of a "static struct device_operations" data structure specifying the routines to execute during the different states and sub-states of ramstage's processing.
  4. Turn on the device in mainboard/<Vendor>/<Board>/devicetree.cb
  5. Debug until the device is on and properly configured in coreboot and usable by the payload

Subsystem IDs

PCI subsystem IDs are assigned during the BS_DEV_ENABLE state. The device driver may use the common mechanism to assign subsystem IDs by adding the ".ops_pci" to the pci_driver data structure. This field points to a "struct pci_operations" that specifies a routine to set the subsystem IDs for the device. The routine might look something like this: 

static void pci_set_subsystem(device_t dev, unsigned vendor, unsigned device)
{
	if (!vendor || !device) {
		vendor = pci_read_config32(dev, PCI_VENDOR_ID);
		device = vendor >> 16;
	}
	printk(BIOS_SPEW,
		"PCI: %02x:%02x:%d subsystem vendor: 0x%04x, device: 0x%04x\n",
		0, PCI_SLOT(dev->path.pci.devfn), PCI_FUNC(dev->path.pci.devfn),
		vendor & 0xffff, device);
	pci_write_config32(dev, PCI_SUBSYSTEM_VENDOR_ID,
			((device & 0xffff) << 16) | (vendor & 0xffff));
}

Set up the Memory Map

The memory map is built by the various PCI device drivers during the BS_DEV_RESOURCES state of ramstage. The northcluster driver will typically specify the DRAM resources while the other drivers will typically specify the IO resources. These resources are hung off the device_t data structure by src/device/device_util.c/new_resource.

During the BS_WRITE_TABLES state, coreboot collects these resources and places them into a data structure identified by LB_MEM_TABLE.

Edit the device driver file:

  1. Implement a read_resources routine which calls macros defined in src/include/device/device.h like:

Testing: Verify that the resources are properly displayed by coreboot during the BS_WRITE_TABLES state.

ACPI Tables

One of the payloads that needs ACPI tables is the EDK2 CorebootPayloadPkg.

FADT

The EDK2 module CorebootModulePkg/Library/CbParseLib/CbParseLib.c requires that the FADT contains the values in the table below. These values are placed into a HOB identified by gUefiAcpiBoardInfoGuid by routine CorebootModulePkg/CbSupportPei/CbSupportPei/CbPeiEntryPoint.

coreboot Field EDK2 Field gUefiAcpiBoardInfoGuid Use ACPI Spec. Section
gpe0_blk
gpe0_blk_len		 Gpe0Blk
Gpe0BlkLen		 PmGpeEnBase Shutdown 4.8.4.1
pm1a_cnt_blk Pm1aCntBlk PmCtrlRegBase Shutdown
Suspend 		4.8.3.2.1
pm1a_evt_blk Pm1aEvtBlk PmEvtBase Shutdown 4.8.3.1.1
pm_tmr_blk PmTmrBlk PmTimerRegBase Timer 4.8.3.3
reset_reg. ResetReg.Address ResetRegAddress Cold and Warm resets 4.3.3.6
reset_value ResetValue ResetValue Cold and Warm resets 4.8.3.6

The EDK2 data structure is defined in MdeModulePkg/Include/IndustryStandard/Acpi61.h The coreboot data structure is defined in src/arch/x86/include/arch/acpi.h

  1. Select HAVE_ACPI_TABLES in the board's Kconfig file
  2. Create a acpi.c module:
    1. Add the acpi_fill_in_fadt routine and initialize the values above

Legacy Hardware

One of the payloads that needs legacy hardare is the EDK2 CorebootPayloadPkg.

Peripheral Use 8259 Interrupt Vector IDT Base Offset Interrupt Handler
8254 Programmable Interval Timer EDK2: PcAtChipsetPkg/8254TimerDxe/Timer.c 0 0x340 TimerInterruptHandler
8259 Programmable Interrupt Controller EDK2: PcAtChipsetPkg/8259InterruptControllerDxe/8259.c Master interrupts: 0, 2 - 7
Slave interrupts: 8 - 15
Interrupt vector 1 is never generated, the cascaded input generates interrupts 8 - 15 		Master: 0x340, 0x350 - 0x378
Slave: 0x380 - 0x3b8
Interrupt descriptors are 8 bytes each 		 

Modified: 4 March 2016