From de8c7e39bce97f13e09e53a3a1bdf4edcfebec79 Mon Sep 17 00:00:00 2001 From: Lee Leahy Date: Sun, 14 Feb 2016 14:55:29 -0800 Subject: Documentation: x86 device tree processing and memory map Add documentation on: * FSP Silicon Init * How to start the x86 device tree processing for ramstage * Disabling the PCI devices * Generic PCI device drivers * Memory map support TEST=None Change-Id: If8f729a0ea1d48db4d5ec1d4ae3ad693e9fe44f0 Signed-off-by: Lee Leahy Reviewed-on: https://review.coreboot.org/13718 Tested-by: build bot (Jenkins) Reviewed-by: Martin Roth --- Documentation/Intel/SoC/soc.html | 178 ++++++++++++++++++++++++++++++++++++++- 1 file changed, 177 insertions(+), 1 deletion(-) (limited to 'Documentation/Intel/SoC/soc.html') diff --git a/Documentation/Intel/SoC/soc.html b/Documentation/Intel/SoC/soc.html index b5daac8fb5..146e768183 100644 --- a/Documentation/Intel/SoC/soc.html +++ b/Documentation/Intel/SoC/soc.html @@ -26,6 +26,12 @@
  • Add the MemoryInit Support
    • +
  • Ramstage +
      +
    1. Start Device Tree Processing
      2. +
    2. Set up the Memory Map"
      3. +
    +
    • @@ -382,6 +388,176 @@ Use the following steps to debug the call to TempRamInit:
    -

    Modified: 31 January 2016

    +

    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. +
      2. Use the CHIP_NAME macro to specify the name for the chip
        3. +
      3. For FSP 1.1, specify a .init routine which calls intel_silicon_init
        4. +
      +
      2. +
    2. Edit src/soc/<SoC Vendor>/<SoC Family>/Makefile.inc and add chip.c to ramstage
      3. +
    + +

    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. +
      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. +
      3. + During the BS_DEV_ENUMERATE state, ramstage now display the device IDs + for the PCI devices on the bus. +
        4. +
      +
      2. +
    2. Set CONFIG_DEBUG_BOOT_STATE=y in the .config file
      3. +
    3. + Debug the result until the PCI vendor and device IDs are displayed + during the BS_DEV_ENUMERATE state. +
      4. +
    + + +

    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. +
    2. .device - PCI device ID value of the device or
      + .devices - Address of a zero terminated array of PCI device IDs +
      3. +
    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. +
    4. Turn on the device in mainboard/<Vendor>/<Board>/devicetree.cb
      5. +
    5. + Debug until the device is on and properly configured in coreboot and + usable by the payload +
      6. +
    + +

    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: +
        +
      • ram_resource
        • +
      • reserved_ram_resource
        • +
      • bad_ram_resource
        • +
      • uma_resource
        • +
      • mmio_resource
        • +
      +
      2. +
    + +

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

    + + + + +
    +

    Modified: 18 February 2016

    \ No newline at end of file -- cgit v1.2.3