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/Board/board.html | 29 +++++- Documentation/Intel/SoC/soc.html | 178 ++++++++++++++++++++++++++++++++++- Documentation/Intel/development.html | 83 +++++++++++++++- 3 files changed, 287 insertions(+), 3 deletions(-) (limited to 'Documentation/Intel') diff --git a/Documentation/Intel/Board/board.html b/Documentation/Intel/Board/board.html index 47d329515d..91aa3054d4 100644 --- a/Documentation/Intel/Board/board.html +++ b/Documentation/Intel/Board/board.html @@ -16,6 +16,7 @@
  • Required Files
  • Enable Serial Output
  • Load the Memory Timing Data
    • +
  • Disable the PCI devices
    • @@ -181,7 +182,33 @@ + +
    +

    Disable PCI Devices

    +

    + Ramstage's BS_DEV_ENUMERATE state displays the PCI vendor and device IDs for all + of the devices in the system. Edit the devicetree.cb file: +

    +
      +
    1. Edit the devicetree.cb file: +
        +
      1. Add an entry for a PCI device.function and turn it off. The entry + should look similar to: +
        device pci 14.0 off end
        +
        2. +
      2. Turn on the devices for: +
          +
        • Memory Controller
          • +
        • Debug serial device
          • +
        +
        3. +
      +
      2. +
    2. Debug until the BS_DEV_ENUMERATE state shows the proper state for all of the devices
      3. +
    + +
    -

    Modified: 31 January 2016

    +

    Modified: 15 February 2016

    \ No newline at end of file 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 diff --git a/Documentation/Intel/development.html b/Documentation/Intel/development.html index 0cd2bd59b7..a3136d19d1 100644 --- a/Documentation/Intel/development.html +++ b/Documentation/Intel/development.html @@ -94,6 +94,24 @@ +
  • + Implement the .init routine for the + chip operations + structure which calls FSP SiliconInit +
    • +
  • + Start ramstage's + device tree processing + to display the PCI vendor and device IDs +
    • +
  • + Disable the + PCI devices +
    • +
  • + Implement the + memory map +
    • @@ -129,6 +147,31 @@ Disable: CONFIG_DISPLAY_MTRRS=y, MTRRs displayed after call to TempRamExit + + Memory Map + + Implement a device driver for the + north cluster + + coreboot displays the memory map correctly during the BS_WRITE_TABLES state + + + PCI Device Support + Implement a PCI device driver + The device is detected by coreboot and usable by the payload + + + Ramstage state machine + + Implement the chip and domain operations to start the + device tree + processing + + + During the BS_DEV_ENUMERATE state, ramstage now display the device IDs + for the PCI devices on the bus. + + @@ -136,6 +179,19 @@ Where Testing + + Device Tree + + List PCI vendor and device IDs by starting + the device tree processing
    + Disable PCI devices
    + Enable: Implement a PCI device driver + + List: BS_DEV_ENUMERATE state displays PCI vendor and device IDs
    + Disable: BS_DEV_ENUMERATE state shows the devices as disabled
    + Enable: BS_DEV_ENUMERATE state shows the device as on and the device works for the payload + + DRAM @@ -208,11 +264,36 @@ + + SiliconInit + + Implement the .init routine for the + chip operations structure + + During BS_DEV_INIT_CHIPS state, SiliconInit gets called and returns 0x00000000 + + + FspNotify + + The code which calls FspNotify is located in + src/drivers/intel/fsp1_1/fsp_util.c. + The fsp_notify_boot_state_callback routine is called three times as specified + by the BOOT_STATE_INIT_ENTRY macros below the routine. + + + The FspNotify routines are called during: +
      +
    • BS_DEV_RESOURCES - on exit
      • +
    • BS_PAYLOAD_LOAD - on exit
      • +
    • BS_OS_RESUME - on entry (S3 resume)
      • +
    + +
    -

    Modified: 31 January 2016

    +

    Modified: 15 February 2016

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