Philipp Deppenwiese (zaolin.daisuki@googlemail.com) just uploaded a new patch set to gerrit, which you can find at https://review.coreboot.org/15535
-gerrit
commit 572b621ce29abd00d78db82b502416972f743e9b Author: Philipp Deppenwiese zaolin@das-labor.org Date: Sat Jul 2 01:29:16 2016 +0200
Documentation: Port html and markdown documentation for Hugo.
The Intel documentation will be converted to markdown. All other leftofers integrated.
Currently WIP
Change-Id: I45bf8aca3abdde6b008dea141520d5bc59a8be1e Signed-off-by: Philipp Deppenwiese zaolin@das-labor.org --- Documentation/content/.empty | 0 Documentation/content/docs/core/index.md | 8 + Documentation/content/docs/core/timestamps.md | 116 ++ .../content/docs/vendor/intel/boards/boards.md | 169 +++ .../content/docs/vendor/intel/boards/galileo.md | 100 ++ .../docs/vendor/intel/boards/galileo_checklist.md | 1356 ++++++++++++++++++++ .../content/docs/vendor/intel/development.md | 129 ++ Documentation/content/docs/vendor/intel/fsp1_1.md | 66 + Documentation/content/docs/vendor/intel/index.md | 9 + .../content/docs/vendor/intel/soc/quark.md | 152 +++ Documentation/content/docs/vendor/intel/soc/soc.md | 593 +++++++++ .../content/docs/vendor/intel/tableofcontents.md | 70 + Documentation/content/getting-started/gerrit.md | 126 ++ Documentation/content/getting-started/index.md | 10 + .../content/getting-started/submodules.md | 43 + Documentation/content/index.md | 10 + Documentation/content/licenses/index.md | 9 + 17 files changed, 2966 insertions(+)
diff --git a/Documentation/content/.empty b/Documentation/content/.empty deleted file mode 100644 index e69de29..0000000 diff --git a/Documentation/content/docs/core/index.md b/Documentation/content/docs/core/index.md new file mode 100644 index 0000000..433b764 --- /dev/null +++ b/Documentation/content/docs/core/index.md @@ -0,0 +1,8 @@ +--- +date: 2016-07-01T19:25:34.000Z +title: Core Documentation +name: Core Documentation +weight: 10 +menu: + main: +--- diff --git a/Documentation/content/docs/core/timestamps.md b/Documentation/content/docs/core/timestamps.md new file mode 100644 index 0000000..6c316f0 --- /dev/null +++ b/Documentation/content/docs/core/timestamps.md @@ -0,0 +1,116 @@ +--- +date: 2016-07-01T19:25:34.000Z +title: Timestamps +name: Timestamps +weight: 20 +menu: + main: + parent: Core Documentation +--- + +## Table of Contents + +Introduction Transition from cache to cbmem + +Data structures used cache_state table entries + +Function APIs timestamp_init timestamp_add timestamp_add_now timestamp_sync + +Use / Test Cases Case 1: Timestamp Region Exists Case 2: No timestamp region, fresh boot, cbmem_initialize called after timestamp_init Case 3: No timestamp region, fresh boot, cbmem_initialize called before timestamp_init Case 4: No timestamp region, resume, cbmem_initialize called after timestamp_init Case 5: No timestamp region, resume, cbmem_initialize called before timestamp_init + +## Introduction + +The aim of the timestamp library is to make it easier for different boards to save timestamps in cbmem / stash (until cbmem is brought up) by providing a simple API to initialize, add and sync timestamps. In order to make the timestamps persistent and accessible from the kernel, we need to ensure that all the saved timestamps end up in cbmem under the CBMEM_ID_TIMESTAMP tag. However, until the cbmem area is available, the timestamps can be saved to a SoC-defined _timestamp region or in a local stage-specific stash. The work of identifying the right location for storing timestamps is done by the library and is not exposed to the user. + +Working of timestamp library from a user perspective can be outlined in the following steps: + +1. Initialize the base time and reset cbmem timestamp area +2. Start adding timestamps + +Behind the scenes, the timestamp library takes care of: + +1. Identifying the correct location for storing timestamps (cbmem or timestamp region or local stash). +2. Once cbmem is up, ensure that all timestamps are synced from timestamp region or local stash into the cbmem area. +3. Add a new cbmem timestamp area based on whether a reset of the cbmem timestamp region is required or not. + +## Transition from cache to cbmem + +To move timestamps from the cache to cbmem (and initialize the cbmem area in the first place), we use the CBMEM_INIT_HOOK infrastructure of coreboot. + +When cbmem is initialized, the hook is called, which creates the area, copies all timestamps to cbmem and disables the cache. + +After such a transition, timestamp_init() must not be run again. + +# Data structures used + +The main structure that maintains information about the timestamp cache is: struct **attribute**((**packed**)) timestamp_cache { uint16_t cache_state; struct timestamp_table table; struct timestamp_entry entries[MAX_TIMESTAMP_CACHE]; }; + +## cache_state + +The state of the cache is maintained by cache_state attribute which can be any one of the following: + +enum { TIMESTAMP_CACHE_UNINITIALIZED = 0, TIMESTAMP_CACHE_INITIALIZED, TIMESTAMP_CACHE_NOT_NEEDED, }; + +By default, if the cache is stored in local stash (bss area), then it will be reset to uninitialized state. However, if the cache is stored in timestamp region, then it might have garbage in any of the attributes. Thus, if the timestamp region is being used by any board, it is initialized to default values by the library. + +Once the cache is initialized, its state is set to CACHE_INITIALIZED. Henceforth, the calls to cache i.e. timestamp_add know that the state reflected is valid and timestamps can be directly saved in the cache. + +Once the cbmem area is up (i.e. call to timestamp_sync_cache_to_cbmem), we do not need to store the timestamps in local stash / timestamp area anymore. Thus, the cache state is set to CACHE_NOT_NEEDED, which allows timestamp_add to store all timestamps directly into the cbmem area. + +## table + +This field is represented by a structure which provides overall information about the entries in the timestamp area: + +struct timestamp_table { uint64_t base_time; uint32_t max_entries; uint32_t num_entries; struct timestamp_entry entries[0]; / _Variable number of entries_ / } __attribute__((packed)); + +It indicates the base time for all timestamp entries, maximum number of entries that can be stored, total number of entries that currently exist and an entry structure to hold variable number of entries. + +### entries + +This field holds the details of each timestamp entry, upto a maximum of MAX_TIMESTAMP_CACHE which is defined as 16 entries. Each entry is defined by: + +struct timestamp_entry { uint32_t entry_id; uint64_t entry_stamp; } __attribute__((packed)); + +entry_id holds the timestamp id corresponding to this entry and entry_stamp holds the actual timestamp. + +For timestamps stored in the cbmem area, a timestamp_table is allocated with space for MAX_TIMESTAMPS equal to 30. Thus, the cbmem area holds base_time, max_entries (which is 30), current number of entries and the actual entries represented by timestamp_entry. + +## Function APIs + +### timestamp_init + +This function initializes the timestamp cache and should be run as early as possible. On platforms with SRAM, this might mean in bootblock, on x86 with its CAR backed memory in romstage, this means romstage before memory init. + +### timestamp_add + +This function accepts from user a timestamp id and time to record in the timestamp table. It stores the entry in the appropriate table in cbmem or _timestamp region or local stash. + +## timestamp_add_now + +This function calls timestamp_add with user-provided id and current time. + +# Use / Test Cases + +The following cases have been considered while designing the timestamp library. It is important to ensure that any changes made to this library satisfy each of the following use cases: + +## Case 1: Timestamp Region Exists (Fresh Boot / Resume) + +In this case, the library needs to call timestamp_init as early as possible to enable the timestamp cache. Once cbmem is available, the values will be transferred automatically. + +All regions are automatically reset on initialization. + +## Case 2: No timestamp region, fresh boot, cbmem_initialize called after timestamp_init + +timestamp_init will set up a local cache. cbmem must be initialized before that cache vanishes - as happens when jumping to the next stage. + +## Case 3: No timestamp region, fresh boot, cbmem_initialize called before timestamp_init + +This case is not supported right now, just don't call timestamp_init after cbmem_initialize. (Patches to make this more robust are welcome.) + +## Case 4: No timestamp region, resume, cbmem_initialize called after timestamp_init + +We always reset the cbmem region before using it, so pre-suspend timestamps will be gone. + +## Case 5: No timestamp region, resume, cbmem_initialize called before timestamp_init + +We always reset the cbmem region before using it, so pre-suspend timestamps will be gone. diff --git a/Documentation/content/docs/vendor/intel/boards/boards.md b/Documentation/content/docs/vendor/intel/boards/boards.md new file mode 100644 index 0000000..0ae64d3 --- /dev/null +++ b/Documentation/content/docs/vendor/intel/boards/boards.md @@ -0,0 +1,169 @@ +--- +date: 2016-07-01T19:25:34.000Z +title: Boards +name: Boards +weight: 60 +menu: + main: + parent: Intel Documentation +--- + +## x86 Board Development + +Board development requires System-on-a-Chip (SoC) support. The combined steps are listed [here](../development.html). The development steps for the board are listed below: + +1. [Required Files](#RequiredFiles) +2. Enable [Serial Output](#SerialOutput) +3. Load the [Memory Timing Data](#SpdData) +4. [Disable](#DisablePciDevices) the PCI devices +5. [ACPI Tables](#AcpiTables) + +-------------------------------------------------------------------------------- + +## [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. Kconfig + + 1. Selects the SoC for the board and specifies the SPI flash size + + 1. BOARD_ROMSIZE_KB_<Size> + 2. SOC_<Vendor>_<Chip Family> + + 2. Declare the Kconfig values for: + + 1. MAINBOARD_DIR + 2. MAINBOARD_PART_NUMBER + 3. MAINBOARD_VENDOR + +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 + +4. romstage.c + + 1. Add routine mainboard_romstage_entry which calls romstage_common + +5. Configure coreboot build: + + 1. Set LOCALVERSION + 2. Select vendor for the board + 3. Select the board + 4. CBFS_SIZE = 0x00100000 + 5. Set the CPU_MICROCODE_CBFS_LEN + 6. Set the CPU_MICROCODE_CBFS_LOC + 7. Set the FSP_IMAGE_ID_STRING + 8. Set the FSP_LOC + 9. Disable GOP_SUPPORT + 10. No payload + 11. Choose the default value for all other options + +-------------------------------------------------------------------------------- + +# [Enable Serial Output]() + +Use the following steps to enable serial output: + +1. Implement the car_mainboard_pre_console_init routine in the com_init.c file: + + 1. Power on and enable the UART controller + 2. Connect the UART receive and transmit data lines to the appropriate SoC pins + +2. Add Makefile.inc + + 1. Add com_init.c to romstage + +-------------------------------------------------------------------------------- + +# [Memory Timing Data]() + +Memory timing data is located in the flash. This data is in the format of [serial presence detect](https://en.wikipedia.org/wiki/Serial_presence_detect) (SPD) data. Use the following steps to load the SPD data: + +1. Edit Kconfig to add the DISPLAY_SPD_DATA" value which enables the display of the SPD data being passed to MemoryInit +2. Create an "spd" subdirectory +3. Create an spd/spd.c file for the SPD implementation + + 1. Implement the mainboard_fill_spd_data routine + + 1. Read the SPD data either from the spd.bin file or using I2C or SMBUS + 2. Fill in the pei_data structure with SPD data for each of the DIMMs + 3. Set the DIMM channel configuration + +4. Add an .spd.hex file containing the memory timing data to the spd subdirectory + +5. Create spd/Makefile.inc + + 1. Add spd.c to romstage + 2. Add the .spd.hex file to SPD_SOURCES + +6. Edit Makefile.inc to add the spd subdirectory + +7. Edit romstage.c + + 1. Call mainboard_fill_spd_data + 2. Add mainboard_memory_init_params to copy the SPD and DRAM configuration data from the pei_data structure into the UPDs for MemoryInit + +8. Edit devicetree.cb + + 1. Include the UPD parameters for MemoryInit except for: + + - Address of SPD data + - DRAM configuration set above + +9. A working FSP [MemoryInit](../fsp1_1.html#MemoryInit) routine is required to complete debugging + +10. Debug the result until port 0x80 outputs + + 1. 0x34: - Just after entering [raminit](http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/...) + 2. 0x36: - Just before displaying the [UPD parameters](http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/...) for FSP MemoryInit + 3. 0x92: [POST_FSP_MEMORY_INIT](http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/include/consol...) - Just before calling FSP [MemoryInit](http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/...) + 4. 0x37: - Just after returning from FSP [MemoryInit](http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/...) + +11. Continue debugging with CONFIG_DISPLAY_HOBS enabled until TempRamExit is called + +-------------------------------------------------------------------------------- + +# [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. Turn on the devices for: + + - Memory Controller + - Debug serial device + +2. Debug until the BS_DEV_ENUMERATE state shows the proper state for all of the devices + +-------------------------------------------------------------------------------- + +# [ACPI Tables]() + +1. Edit Kconfig + + 1. Add "select HAVE_ACPI_TABLES" + +2. Add the acpi_tables.c module: + + 1. Include soc/acpi.h + 2. Add the acpi_create_fadt routine + + 1. fill in the ACPI header + 2. Call the acpi_fill_in_fadt routine + +3. Add the dsdt.asl module: + +-------------------------------------------------------------------------------- + +Modified: 20 February 2016 diff --git a/Documentation/content/docs/vendor/intel/boards/galileo.md b/Documentation/content/docs/vendor/intel/boards/galileo.md new file mode 100644 index 0000000..c557834 --- /dev/null +++ b/Documentation/content/docs/vendor/intel/boards/galileo.md @@ -0,0 +1,100 @@ +--- +date: 2016-07-01T19:25:34.000Z +title: Galileo Board +name: Galileo Board +weight: 70 +menu: + main: + parent: Intel Documentation +--- + +## Intel® Galileo Development Board + ++--------------------------------------+--------------------------------------+ +| [](http | Intel® [Quark™](../SoC/quark.html) | +| ://www.mouser.com/images/microsites/ | SoC: | +| Intel_Galileo2_lrg.jpg) | - [Overall](../development.html) | +| | development | +| | - [SoC](../SoC/soc.html) support | +| | - [FSP 1.1](../fsp1_1.html) | +| | integration | +| | - [Board](board.html) support | +| | - [Implementation | +| | Checklist](Galileo_checklist.htm | +| | l) | ++--------------------------------------+--------------------------------------+ + +## Galileo Board Documentation + +- Common Components + + - A/D: Texas Instruments [ADC108S102](http://www.ti.com/lit/ds/symlink/adc108s102.pdf) + - Analog Switch: Texas Instruments [TS5A23159](http://www.ti.com/lit/ds/symlink/ts5a23159.pdf) + - Ethernet (10/100 MB/S): Texas Instruments [DP83848](http://www.ti.com/lit/ds/symlink/dp83848-ep.pdf) + - Load Switch: Texas Instruments [TPS22920x](http://www.ti.com/lit/ds/symlink/tps22920.pdf) + - Memory (256 MiB): Micron [MT41K128M8](https://www.micron.com/~/media/Documents/Products/Data%20Sheet/DRAM/DDR3/1Gb...) + - SoC: Intel® Quark™ [X-1000](../SoC/quark.html) + - Serial EEPROM (1 KiB): ON Semiconductor® [CAT24C08](http://www.onsemi.com/pub_link/Collateral/CAT24C01-D.PDF) + - SPI Flash (8 MiB): Winbond™ [W25Q64FV](http://www.winbond-usa.com/resource-files/w25q64fv_revl1_100713.pdf) + - Step Down Converter: Texas Instruments [TPS62130](http://www.ti.com/lit/ds/slvsag7c/slvsag7c.pdf) + - Step Down Converter: Texas Instruments [TPS652510](http://www.ti.com/lit/ug/slvu570/slvu570.pdf) + - Termination Regulator: Texas Instruments [TPS51200](http://www.ti.com/lit/ds/symlink/tps51200.pdf) + +- Make a bootable [micro SD card](https://software.intel.com/en-us/get-started-galileo-linux-step1) + +### Galileo Gen 2 Board Documentation + +- [Block Diagram](http://files.linuxgizmos.com/intel_galileo_gen2_blockdiagram.jpg) +- [Getting Started](https://software.intel.com/en-us/iot/library/galileo-getting-started) +- [Overview](http://www.intel.com/content/www/us/en/embedded/products/galileo/galileo-ove...) +- [Port Diagram](http://files.linuxgizmos.com/intel_galileo_gen2_ports.jpg) +- [Product Brief](http://download.intel.com/support/galileo/sb/intelgalileogen2prodbrief_33073...) +- [Schematic](http://www.intel.com/content/dam/www/public/us/en/documents/guides/galileo-g...) +- [User Guide](http://download.intel.com/support/galileo/sb/galileo_boarduserguide_330237_0...) +- Components + + - A/D: Texas Instruments [ADC108S102](http://www.ti.com/lit/ds/symlink/adc108s102.pdf) + - I2C 16-channel, 12-bit PWM: NXP Semiconductors [PCA9685](http://cache.nxp.com/documents/data_sheet/PCA9685.pdf) + - I2C I/O Ports: NXP Semiconductors [PCAL9535A](http://www.nxp.com/documents/data_sheet/PCAL9535A.pdf) + - Octal Buffer/Driver: Texas Instruments [SN74LV541AT](http://www.ti.com/lit/ds/symlink/sn74lv541at.pdf) + - Quadruple Bus Buffer: Texas Instruments [SN74LV125A](http://www.ti.com/lit/ds/symlink/sn74lv125a.pdf) + - Quadruple Bus Buffer with 3-State Outputs: Texas Instruments [SN74LVC126A](http://www.ti.com/lit/ds/symlink/sn74lvc126a.pdf) + - Serial EEPROM (1 KiB): ON Semiconductor® [CAT24C08](http://www.onsemi.com/pub_link/Collateral/CAT24C01-D.PDF) + - Single 2-input multiplexer: NXP Semiconductors [74LVC1G157](http://www.nxp.com/documents/data_sheet/74LVC1G157.pdf) + - Step Down Converter: Texas Instruments [TPS62130](http://www.ti.com/lit/ds/slvsag7c/slvsag7c.pdf) + +### Galileo Gen 1 Board Documentation + +- [Datasheet](http://www.intel.com/content/dam/www/public/us/en/documents/datasheets/galil...) +- [Schematic](http://www.intel.com/content/dam/www/public/us/en/documents/guides/galileo-g...) +- Components + + - A/D: Analog Devices [AD7298](http://www.analog.com/media/en/technical-documentation/data-sheets/AD7298-1....) + - Analog Switch, 2 channel: Texas Instruments [TS5A23159](http://www.ti.com.cn/cn/lit/ds/symlink/ts5a23159.pdf) + - EEPROM & GPIO: Cypress [CY8C9540A](http://www.cypress.com/file/37971/download) + - Power Distribution Switch: Texas Instruments [TPS2051BDBVR](http://www.ti.com/lit/ds/symlink/tps2044b.pdf) + - RS232 Converter: Texas Instruments [MAX3232](http://www.ti.com/lit/ds/symlink/max3232.pdf) + - Voltage-Level Translator: Texas Instruments[TXS0108E](http://www.ti.com/lit/ds/symlink/txs0108e.pdf) + +-------------------------------------------------------------------------------- + +## Debug Tools + +- Flash Programmer: + + - Dediprog [SF100](http://www.dediprog.com/pd/spi-flash-solution/SF100) ISP IC Programmer + +- JTAG Connector: [Olimex ARM-JTAG-20-10](https://www.google.com/webhp?sourceid=chrome-instant&ion=1&espv=2&am...) +- JTAG Debugger: + + - Olimex LTD [ARM-USB-OCD-H](https://www.google.com/webhp?sourceid=chrome-instant&ion=1&espv=2&am...) + - Tincan Tools [Flyswatter2](https://www.tincantools.com/wiki/Flyswatter2) + +- [Hardware Setup and Software Installation](http://download.intel.com/support/processors/quark/sb/sourcedebugusingopenoc...) +- USB Serial cable: FTDI [TTL-232R-3V3](https://www.google.com/webhp?sourceid=chrome-instant&ion=1&espv=2&am...) + +-------------------------------------------------------------------------------- + +Modified: 29 February 2016 diff --git a/Documentation/content/docs/vendor/intel/boards/galileo_checklist.md b/Documentation/content/docs/vendor/intel/boards/galileo_checklist.md new file mode 100644 index 0000000..d4fd55b --- /dev/null +++ b/Documentation/content/docs/vendor/intel/boards/galileo_checklist.md @@ -0,0 +1,1356 @@ +--- +date: 2016-07-01T19:25:34.000Z +title: Galileo Checklist +name: Galileo Checklist +weight: 80 +menu: + main: + parent: Intel Documentation +--- + +## Galileo Implementation Status + +<table> +<tr> +<td colspan="2"> +**Legend** + +</td> +</tr> +<tr> +<td bgcolor="#ffc0c0"> +Red + +</td> +<td> +Required - To-be-implemented + +</td> +</tr> +<tr> +<td bgcolor="#ffffc0"> +Yellow + +</td> +<td> +Optional + +</td> +</tr> +<tr> +<td bgcolor="#c0ffc0"> +Green + +</td> +<td> +Implemented + +</td> +</tr> +</table> +<table> +<tr valign="top"> +<td> +<table border="1"> +<tr> +<th colspan="2"> +bootblock: 100% Done + +</th> +</tr> +<tr> +<th> +Type + +</th> +<th> +Routine + +</td> +</tr> +<tr bgcolor="#ffffc0"> +<td> +Optional + +</td> +<td> +bootblock_c_entry + +</td> +</tr> +<tr bgcolor="#c0ffc0"> +<td> +Required + +</td> +<td> +bootblock_main_with_timestamp + +</td> +</tr> +<tr bgcolor="#ffffc0"> +<td> +Optional + +</td> +<td> +bootblock_mainboard_early_init + +</td> +</tr> +<tr bgcolor="#ffffc0"> +<td> +Optional + +</td> +<td> +bootblock_mainboard_init + +</td> +</tr> +<tr bgcolor="#c0ffc0"> +<td> +Required + +</td> +<td> +bootblock_pre_c_entry + +</td> +</tr> +<tr bgcolor="#c0ffc0"> +<td> +Required + +</td> +<td> +bootblock_protected_mode_entry + +</td> +</tr> +<tr bgcolor="#c0ffc0"> +<td> +Required + +</td> +<td> +bootblock_soc_early_init + +</td> +</tr> +<tr bgcolor="#ffffc0"> +<td> +Optional + +</td> +<td> +bootblock_soc_init + +</td> +</tr> +<tr bgcolor="#c0ffc0"> +<td> +Required + +</td> +<td> +tsc_freq_mhz + +</td> +</tr> +<tr bgcolor="#c0ffc0"> +<td> +Required + +</td> +<td> +uart_init + +</td> +</tr> +</table> +</td> +<td width="5"> + + +</td> +<td> +<table border="1"> +<tr> +<th colspan="2"> +romstage: 66% Done + +</th> +</tr> +<tr> +<th> +Type + +</th> +<th> +Routine + +</td> +</tr> +<tr bgcolor="#ffffc0"> +<td> +Optional + +</td> +<td> +arch_segment_loaded + +</td> +</tr> +<tr bgcolor="#ffffc0"> +<td> +Optional + +</td> +<td> +backup_top_of_ram + +</td> +</tr> +<tr bgcolor="#ffffc0"> +<td> +Optional + +</td> +<td> +boot_device_init + +</td> +</tr> +<tr bgcolor="#ffffc0"> +<td> +Optional + +</td> +<td> +car_mainboard_post_console_init + +</td> +</tr> +<tr bgcolor="#c0ffc0"> +<td> +Required + +</td> +<td> +car_mainboard_pre_console_init + +</td> +</tr> +<tr bgcolor="#c0ffc0"> +<td> +Required + +</td> +<td> +car_soc_post_console_init + +</td> +</tr> +<tr bgcolor="#c0ffc0"> +<td> +Required + +</td> +<td> +car_soc_pre_console_init + +</td> +</tr> +<tr bgcolor="#c0ffc0"> +<td> +Required + +</td> +<td> +car_stage_entry + +</td> +</tr> +<tr bgcolor="#c0ffc0"> +<td> +Required + +</td> +<td> +cbfs_master_header_locator + +</td> +</tr> +<tr bgcolor="#ffffc0"> +<td> +Optional + +</td> +<td> +cbmem_fail_resume + +</td> +</tr> +<tr bgcolor="#ffffc0"> +<td> +Optional + +</td> +<td> +clear_recovery_mode_switch + +</td> +</tr> +<tr bgcolor="#ffffc0"> +<td> +Optional + +</td> +<td> +cpu_smi_handler + +</td> +</tr> +<tr bgcolor="#c0ffc0"> +<td> +Required + +</td> +<td> +fill_power_state + +</td> +</tr> +<tr bgcolor="#ffffc0"> +<td> +Optional + +</td> +<td> +get_sw_write_protect_state + +</td> +</tr> +<tr bgcolor="#ffffc0"> +<td> +Optional + +</td> +<td> +get_top_of_ram + +</td> +</tr> +<tr bgcolor="#ffffc0"> +<td> +Optional + +</td> +<td> +gpio_acpi_path + +</td> +</tr> +<tr bgcolor="#c0ffc0"> +<td> +Required + +</td> +<td> +init_timer + +</td> +</tr> +<tr bgcolor="#ffffc0"> +<td> +Optional + +</td> +<td> +mainboard_add_dimm_info + +</td> +</tr> +<tr bgcolor="#ffffc0"> +<td> +Optional + +</td> +<td> +mainboard_check_ec_image + +</td> +</tr> +<tr bgcolor="#ffc0c0"> +<td> +Required + +</td> +<td> +mainboard_fill_spd_data + +</td> +</tr> +<tr bgcolor="#ffffc0"> +<td> +Optional + +</td> +<td> +mainboard_io_trap_handler + +</td> +</tr> +<tr bgcolor="#ffc0c0"> +<td> +Required + +</td> +<td> +mainboard_memory_init_params + +</td> +</tr> +<tr bgcolor="#ffffc0"> +<td> +Optional + +</td> +<td> +mainboard_post + +</td> +</tr> +<tr bgcolor="#c0ffc0"> +<td> +Required + +</td> +<td> +mainboard_romstage_entry + +</td> +</tr> +<tr bgcolor="#ffffc0"> +<td> +Optional + +</td> +<td> +mainboard_save_dimm_info + +</td> +</tr> +<tr bgcolor="#ffffc0"> +<td> +Optional + +</td> +<td> +mainboard_smi_apmc + +</td> +</tr> +<tr bgcolor="#ffffc0"> +<td> +Optional + +</td> +<td> +mainboard_smi_gpi + +</td> +</tr> +<tr bgcolor="#ffffc0"> +<td> +Optional + +</td> +<td> +mainboard_smi_sleep + +</td> +</tr> +<tr bgcolor="#ffffc0"> +<td> +Optional + +</td> +<td> +map_oprom_vendev + +</td> +</tr> +<tr bgcolor="#ffc0c0"> +<td> +Required + +</td> +<td> +migrate_power_state + +</td> +</tr> +<tr bgcolor="#ffc0c0"> +<td> +Required + +</td> +<td> +mrc_cache_get_current_with_version + +</td> +</tr> +<tr bgcolor="#ffc0c0"> +<td> +Required + +</td> +<td> +mrc_cache_stash_data_with_version + +</td> +</tr> +<tr bgcolor="#ffffc0"> +<td> +Optional + +</td> +<td> +platform_prog_run + +</td> +</tr> +<tr bgcolor="#ffffc0"> +<td> +Optional + +</td> +<td> +platform_segment_loaded + +</td> +</tr> +<tr bgcolor="#c0ffc0"> +<td> +Required + +</td> +<td> +print_fsp_info + +</td> +</tr> +<tr bgcolor="#c0ffc0"> +<td> +Required + +</td> +<td> +raminit + +</td> +</tr> +<tr bgcolor="#c0ffc0"> +<td> +Required + +</td> +<td> +ramstage_cache_invalid + +</td> +</tr> +<tr bgcolor="#ffc0c0"> +<td> +Required + +</td> +<td> +report_memory_config + +</td> +</tr> +<tr bgcolor="#c0ffc0"> +<td> +Required + +</td> +<td> +romstage_common + +</td> +</tr> +<tr bgcolor="#ffffc0"> +<td> +Optional + +</td> +<td> +save_chromeos_gpios + +</td> +</tr> +<tr bgcolor="#ffc0c0"> +<td> +Required + +</td> +<td> +set_max_freq + +</td> +</tr> +<tr bgcolor="#c0ffc0"> +<td> +Required + +</td> +<td> +setup_stack_and_mtrrs + +</td> +</tr> +<tr bgcolor="#ffc0c0"> +<td> +Required + +</td> +<td> +smm_region + +</td> +</tr> +<tr bgcolor="#ffc0c0"> +<td> +Required + +</td> +<td> +smm_region_size + +</td> +</tr> +<tr bgcolor="#c0ffc0"> +<td> +Required + +</td> +<td> +soc_after_ram_init + +</td> +</tr> +<tr bgcolor="#ffffc0"> +<td> +Optional + +</td> +<td> +soc_display_memory_init_params + +</td> +</tr> +<tr bgcolor="#c0ffc0"> +<td> +Required + +</td> +<td> +soc_display_mtrrs + +</td> +</tr> +<tr bgcolor="#c0ffc0"> +<td> +Required + +</td> +<td> +soc_get_variable_mtrr_count + +</td> +</tr> +<tr bgcolor="#c0ffc0"> +<td> +Required + +</td> +<td> +soc_memory_init_params + +</td> +</tr> +<tr bgcolor="#ffffc0"> +<td> +Optional + +</td> +<td> +soc_pre_ram_init + +</td> +</tr> +<tr bgcolor="#ffffc0"> +<td> +Optional + +</td> +<td> +southbridge_smi_handler + +</td> +</tr> +<tr bgcolor="#ffffc0"> +<td> +Optional + +</td> +<td> +stage_cache_add + +</td> +</tr> +<tr bgcolor="#ffffc0"> +<td> +Optional + +</td> +<td> +stage_cache_load_stage + +</td> +</tr> +<tr bgcolor="#ffffc0"> +<td> +Optional + +</td> +<td> +timestamp_get + +</td> +</tr> +<tr bgcolor="#c0ffc0"> +<td> +Required + +</td> +<td> +tsc_freq_mhz + +</td> +</tr> +<tr bgcolor="#ffffc0"> +<td> +Optional + +</td> +<td> +vb2ex_hwcrypto_digest_extend + +</td> +</tr> +<tr bgcolor="#ffffc0"> +<td> +Optional + +</td> +<td> +vb2ex_hwcrypto_digest_finalize + +</td> +</tr> +<tr bgcolor="#ffffc0"> +<td> +Optional + +</td> +<td> +vb2ex_hwcrypto_digest_init + +</td> +</tr> +<tr bgcolor="#ffffc0"> +<td> +Optional + +</td> +<td> +vboot_platform_prepare_reboot + +</td> +</tr> +<tr bgcolor="#ffffc0"> +<td> +Optional + +</td> +<td> +verstage_mainboard_init + +</td> +</tr> +</table> +</td> +<td width="5"> + + +</td> +<td> +<table border="1"> +<tr> +<th colspan="2"> +ramstage: 55% Done + +</th> +</tr> +<tr> +<th> +Type + +</th> +<th> +Routine + +</td> +</tr> +<tr bgcolor="#ffc0c0"> +<td> +Required + +</td> +<td> +acpi_create_serialio_ssdt + +</td> +</tr> +<tr bgcolor="#ffffc0"> +<td> +Optional + +</td> +<td> +arch_segment_loaded + +</td> +</tr> +<tr bgcolor="#ffffc0"> +<td> +Optional + +</td> +<td> +backup_top_of_ram + +</td> +</tr> +<tr bgcolor="#ffffc0"> +<td> +Optional + +</td> +<td> +boot_device_init + +</td> +</tr> +<tr bgcolor="#c0ffc0"> +<td> +Required + +</td> +<td> +cbfs_master_header_locator + +</td> +</tr> +<tr bgcolor="#ffffc0"> +<td> +Optional + +</td> +<td> +cbmem_fail_resume + +</td> +</tr> +<tr bgcolor="#ffffc0"> +<td> +Optional + +</td> +<td> +clear_recovery_mode_switch + +</td> +</tr> +<tr bgcolor="#ffffc0"> +<td> +Optional + +</td> +<td> +cpu_smi_handler + +</td> +</tr> +<tr bgcolor="#ffffc0"> +<td> +Optional + +</td> +<td> +fw_cfg_acpi_tables + +</td> +</tr> +<tr bgcolor="#ffffc0"> +<td> +Optional + +</td> +<td> +get_sw_write_protect_state + +</td> +</tr> +<tr bgcolor="#ffffc0"> +<td> +Optional + +</td> +<td> +get_top_of_ram + +</td> +</tr> +<tr bgcolor="#ffffc0"> +<td> +Optional + +</td> +<td> +gpio_acpi_path + +</td> +</tr> +<tr bgcolor="#c0ffc0"> +<td> +Required + +</td> +<td> +init_timer + +</td> +</tr> +<tr bgcolor="#ffffc0"> +<td> +Optional + +</td> +<td> +lb_board + +</td> +</tr> +<tr bgcolor="#ffffc0"> +<td> +Optional + +</td> +<td> +lb_framebuffer + +</td> +</tr> +<tr bgcolor="#ffffc0"> +<td> +Optional + +</td> +<td> +mainboard_add_dimm_info + +</td> +</tr> +<tr bgcolor="#ffffc0"> +<td> +Optional + +</td> +<td> +mainboard_io_trap_handler + +</td> +</tr> +<tr bgcolor="#ffffc0"> +<td> +Optional + +</td> +<td> +mainboard_post + +</td> +</tr> +<tr bgcolor="#ffffc0"> +<td> +Optional + +</td> +<td> +mainboard_silicon_init_params + +</td> +</tr> +<tr bgcolor="#ffffc0"> +<td> +Optional + +</td> +<td> +mainboard_smi_apmc + +</td> +</tr> +<tr bgcolor="#ffffc0"> +<td> +Optional + +</td> +<td> +mainboard_smi_gpi + +</td> +</tr> +<tr bgcolor="#ffffc0"> +<td> +Optional + +</td> +<td> +mainboard_smi_sleep + +</td> +</tr> +<tr bgcolor="#ffffc0"> +<td> +Optional + +</td> +<td> +mainboard_suspend_resume + +</td> +</tr> +<tr bgcolor="#ffffc0"> +<td> +Optional + +</td> +<td> +map_oprom_vendev + +</td> +</tr> +<tr bgcolor="#ffffc0"> +<td> +Optional + +</td> +<td> +mirror_payload + +</td> +</tr> +<tr bgcolor="#ffffc0"> +<td> +Optional + +</td> +<td> +northbridge_smi_handler + +</td> +</tr> +<tr bgcolor="#ffffc0"> +<td> +Optional + +</td> +<td> +nvm_mmio_to_flash_offset + +</td> +</tr> +<tr bgcolor="#ffffc0"> +<td> +Optional + +</td> +<td> +platform_prog_run + +</td> +</tr> +<tr bgcolor="#ffffc0"> +<td> +Optional + +</td> +<td> +platform_segment_loaded + +</td> +</tr> +<tr bgcolor="#ffffc0"> +<td> +Optional + +</td> +<td> +save_chromeos_gpios + +</td> +</tr> +<tr bgcolor="#ffffc0"> +<td> +Optional + +</td> +<td> +smbios_mainboard_bios_version + +</td> +</tr> +<tr bgcolor="#ffffc0"> +<td> +Optional + +</td> +<td> +smbios_mainboard_manufacturer + +</td> +</tr> +<tr bgcolor="#ffffc0"> +<td> +Optional + +</td> +<td> +smbios_mainboard_product_name + +</td> +</tr> +<tr bgcolor="#ffffc0"> +<td> +Optional + +</td> +<td> +smbios_mainboard_serial_number + +</td> +</tr> +<tr bgcolor="#ffffc0"> +<td> +Optional + +</td> +<td> +smbios_mainboard_set_uuid + +</td> +</tr> +<tr bgcolor="#c0ffc0"> +<td> +Required + +</td> +<td> +smbios_mainboard_version + +</td> +</tr> +<tr bgcolor="#ffffc0"> +<td> +Optional + +</td> +<td> +smm_disable_busmaster + +</td> +</tr> +<tr bgcolor="#ffffc0"> +<td> +Optional + +</td> +<td> +soc_after_silicon_init + +</td> +</tr> +<tr bgcolor="#ffffc0"> +<td> +Optional + +</td> +<td> +soc_display_silicon_init_params + +</td> +</tr> +<tr bgcolor="#ffc0c0"> +<td> +Required + +</td> +<td> +soc_fill_acpi_wake + +</td> +</tr> +<tr bgcolor="#c0ffc0"> +<td> +Required + +</td> +<td> +soc_silicon_init_params + +</td> +</tr> +<tr bgcolor="#ffffc0"> +<td> +Optional + +</td> +<td> +soc_skip_ucode_update + +</td> +</tr> +<tr bgcolor="#ffffc0"> +<td> +Optional + +</td> +<td> +southbridge_smi_handler + +</td> +</tr> +<tr bgcolor="#ffffc0"> +<td> +Optional + +</td> +<td> +stage_cache_add + +</td> +</tr> +<tr bgcolor="#ffffc0"> +<td> +Optional + +</td> +<td> +stage_cache_load_stage + +</td> +</tr> +<tr bgcolor="#ffc0c0"> +<td> +Required + +</td> +<td> +timestamp_get + +</td> +</tr> +<tr bgcolor="#ffc0c0"> +<td> +Required + +</td> +<td> +timestamp_tick_freq_mhz + +</td> +</tr> +<tr bgcolor="#c0ffc0"> +<td> +Required + +</td> +<td> +tsc_freq_mhz + +</td> +</tr> +<tr bgcolor="#ffffc0"> +<td> +Optional + +</td> +<td> +vb2ex_hwcrypto_digest_extend + +</td> +</tr> +<tr bgcolor="#ffffc0"> +<td> +Optional + +</td> +<td> +vb2ex_hwcrypto_digest_finalize + +</td> +</tr> +<tr bgcolor="#ffffc0"> +<td> +Optional + +</td> +<td> +vb2ex_hwcrypto_digest_init + +</td> +</tr> +<tr bgcolor="#ffffc0"> +<td> +Optional + +</td> +<td> +wifi_regulatory_domain + +</td> +</tr> +<tr bgcolor="#ffffc0"> +<td> +Optional + +</td> +<td> +write_smp_table + +</td> +</tr> +</table> +</td> +<td width="5"> + + +</td> +</tr> +</table> diff --git a/Documentation/content/docs/vendor/intel/development.md b/Documentation/content/docs/vendor/intel/development.md new file mode 100644 index 0000000..61af5b6 --- /dev/null +++ b/Documentation/content/docs/vendor/intel/development.md @@ -0,0 +1,129 @@ +--- +date: 2016-07-01T19:25:34.000Z +title: Development +name: Development +weight: 30 +menu: + main: + parent: Intel Documentation +prev: fsp1_1 +--- + +## Intel® x86 coreboot/FSP Development Process + +The x86 development process for coreboot is broken into the following components: + +- coreboot [SoC](SoC/soc.html) development +- coreboot [mainboard](Board/board.html) development +- [FSP 1.1](fsp1_1.md) integration + +The development process has two main phases: + +1. Minimal coreboot; This phase is single threaded +2. Adding coreboot features + +## 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. 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. Get something to build: + + 1. [FSP 1.1](fsp1_1.html#RequiredFiles) required files + 2. [SoC](SoC/soc.html#RequiredFiles) required files + 3. [Board](Board/board.html#RequiredFiles) required files + +4. Get result to start [booting](SoC/soc.html#Descriptor) + +5. [Early Debug](SoC/soc.html#EarlyDebug) +6. Implement and debug the [bootblock](SoC/soc.html#Bootblock) code +7. Implement and debug the call to [TempRamInit](SoC/soc.html#TempRamInit) +8. Enable the serial port + + 1. Power on, enable and configure GPIOs for the [debug serial UART](Board/board.html#SerialOutput) + 2. Add the [serial outupt](SoC/soc.html#SerialOutput) support to romstage + +9. Enable [coreboot/FSP](fsp1_1.html#corebootFspDebugging) debugging + +10. Determine the [Previous Sleep State](SoC/soc.html#PreviousSleepState) +11. Enable DRAM: + + 1. Implement the SoC [MemoryInit](SoC/soc.html#MemoryInit) Support + 2. Implement the board support to read the [Memory Timing Data](Board/board.html#SpdData) + +12. Disable the [Shadow ROM](SoC/soc.html#DisableShadowRom) + +13. Enable CONFIG_DISPLAY_MTRRS to verify the MTRR configuration +14. Implement the .init routine for the [chip operations](SoC/soc.html#ChipOperations) structure which calls FSP SiliconInit +15. Start ramstage's [device tree processing](SoC/soc.html#DeviceTree) to display the PCI vendor and device IDs +16. Disable the [PCI devices](Board/board.html#DisablePciDevices) +17. Implement the [memory map](SoC/soc.html#MemoryMap) +18. coreboot should now attempt to load the payload + +## Add coreboot Features + +Most of the coreboot development gets done in this phase. Implementation tasks in this phase are easily done in parallel. + +- Payload and OS Features: + + - [ACPI Tables](SoC/soc.html#AcpiTables) + - [Legacy hardware](SoC/soc.html#LegacyHardware) support + +-------------------------------------------------------------------------------- + +| Features ======== +| -------------------------------------- +SoC | Where | Testing +8254 Programmable Interval Timer | [Legacy hardware](SoC/soc.html#LegacyHardware) support | [CorebootPayloadPkg](SoC/quark.html#CorebootPayloadPkg) gets to shell prompt +8259 Programmable Interrupt Controller | [Legacy hardware](SoC/soc.html#LegacyHardware) support | [CorebootPayloadPkg](SoC/quark.html#CorebootPayloadPkg) gets to shell prompt +Cache-as-RAM | [Find](SoC/soc.html#TempRamInit) FSP binary: [cache_as_ram.inc](https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel... Enable: FSP 1.1 [TempRamInit](SoC/soc.html#TempRamInit) called from [cache_as_ram.inc](https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel... Disable: FSP 1.1 TempRamExit called from [after_raminit.S](https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel... | FindFSP: POST code 0x90 ([POST_FSP_TEMP_RAM_INIT](http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/include/consol...)) is displayed\ Enable: POST code [0x2A](https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel...) is displayed\ Disable: CONFIG_DISPLAY_MTRRS=y, MTRRs displayed after call to TempRamExit +Memory Map | Implement a device driver for the [north cluster](SoC/soc.html#MemoryMap) | coreboot displays the memory map correctly during the BS_WRITE_TABLES state +MTRRs | Set values: src/drivers/intel/fsp1_1/stack.c/[setup_stack_and_mtrrs](https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel... Load values: src/drivers/intel/fsp1_1/[after_raminit.S](https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel...) | Set: Post code 0x91 ([POST_FSP_TEMP_RAM_EXIT](https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/include/conso...)) is displayed by [after_raminit.S](https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel... Load: Post code 0x3C is displayed by [after_raminit.S](https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel... and CONFIG_DISPLAY_MTRRS=y displays the correct memory regions +PCI Device Support | Implement a PCI [device driver](SoC/soc.html#DeviceDrivers) | 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](SoC/soc.html#DeviceTree) processing | During the BS_DEV_ENUMERATE state, ramstage now display the device IDs for the PCI devices on the bus. +ROM Shadow\ 0x000E0000 - 0x000FFFFF | Disable: src/soc/<Vendor>/<Chip Family>/romstage/romstage.c/[soc_after_ram_init routine](SoC/soc.html#DisableShadowRom) | Operates as RAM: Writes followed by a read to the 0x000E0000 - 0x000FFFFF region returns the value written +Board | Where | Testing +Device Tree | [List](SoC/soc.html#DeviceTree) PCI vendor and device IDs by starting the device tree processing\ [Disable](Board/board.html#DisablePciDevices) PCI devices\ Enable: Implement a PCI [device driver](SoC/soc.html#DeviceDrivers) | 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 | Load SPD data: src/soc/mainboard/<Vendor>/<Board>/spd/[spd.c](Board/board.html#SpdData)\ UPD Setup: - src/soc<Vendor>//<Chip Family>/romstage/[romstage.c](SoC/soc.html#MemoryInit) - src/mainboard/<Vendor>/<Board>/[romstage.c](Board/board.html#SpdData) FSP 1.1 MemoryInit called from src/drivers/intel/fsp1_1/[raminit.c](https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel...) | Select the following Kconfig values - DISPLAY_HOBS - DISPLAY_UPD_DATA Testing successful if: - MemoryInit UPD values are correct - MemoryInit returns 0 (success) and - The the message "ERROR - coreboot's requirements not met by FSP binary!" is not displayed +Serial Port | SoC [Support](SoC/soc.html#SerialOutput)\ Enable: src/soc/mainboard/<Board>/com_init.c/[car_mainboard_pre_console_init](Board/board.html#SerialOutput) | Debug serial output works +Payload | Where | Testing +ACPI Tables | SoC [Support](SoC/soc.html#AcpiTables)\ | Verified by payload or OS +FSP | Where | Testing +TempRamInit | FSP [TempRamInit](SoC/soc.html#TempRamInit) | FSP binary found: POST code 0x90 ([POST_FSP_TEMP_RAM_INIT](http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/include/consol...)) is displayed\ TempRamInit successful: POST code [0x2A](https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel...) is displayed\ +MemoryInit | [SoC](SoC/soc.html#MemoryInit) support\ [Board](Board/board.html#SpdData) support\ | Select the following Kconfig values - DISPLAY_HOBS - DISPLAY_UPD_DATA Testing successful if: - MemoryInit UPD values are correct - MemoryInit returns 0 (success) and - The the message "ERROR - coreboot's requirements not met by FSP binary!" is not displayed +TempRamExit | src/drivers/intel/fsp1_1/[after_raminit.S](http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/...) | Post code 0x91 ([POST_FSP_TEMP_RAM_EXIT](https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/include/conso...)) is displayed before calling TempRamExit by [after_raminit.S](https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel...), CONFIG_DISPLAY_MTRRS=y displays the correct memory regions and Post code 0x39 is displayed by [after_raminit.S](https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel... +SiliconInit | Implement the .init routine for the [chip operations](SoC/soc.html#ChipOperations) 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](http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/...). 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: 4 March 2016 diff --git a/Documentation/content/docs/vendor/intel/fsp1_1.md b/Documentation/content/docs/vendor/intel/fsp1_1.md new file mode 100644 index 0000000..48d58d4 --- /dev/null +++ b/Documentation/content/docs/vendor/intel/fsp1_1.md @@ -0,0 +1,66 @@ +--- +date: 2016-07-01T19:25:34.000Z +title: FSP 1.1 +name: FSP 1.1 +menu: + main: + parent: Intel Documentation +next: development +prev: index +weight: 20 +--- + +## x86 FSP 1.1 Integration + +Firmware Support Package (FSP) integration requires System-on-a-Chip (SoC) and board support. The combined steps are listed [here](development.html). The development steps for FSP are listed below: + +1. [Required Files](#RequiredFiles) +2. Add the [FSP Binary File](#FspBinary) to the coreboot File System +3. Enable [coreboot/FSP Debugging](#corebootFspDebugging) + +FSP Documentation: + +- Intel® Firmware Support Package External Architecture Specification [V1.1](http://www.intel.com/content/dam/www/public/us/en/documents/technical-specif...) + +-------------------------------------------------------------------------------- + +## [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. 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 + +-------------------------------------------------------------------------------- + +## [Add the FSP Binary File to coreboot File System]() + +Add the FSP binary to the coreboot flash image using the following command: + +``` +util/cbfstool/cbfstool build/coreboot.rom add -t fsp -n fsp.bin -b <base address> -f fsp.bin +``` + +This command relocates the FSP binary to the 4K byte aligned location in CBFS so that the FSP code for TempRamInit may be executed in place. + +-------------------------------------------------------------------------------- + +## [Enable coreboot/FSP Debugging]() + +Set the following Kconfig values: + +- CONFIG_DISPLAY_FSP_ENTRY_POINTS - Display the FSP entry points in romstage +- CONFIG_DISPLAY_HOBS - Display and verify the hand-off-blocks (HOBs) returned by MemoryInit +- CONFIG_DISPLAY_VBT - Display Video BIOS Table (VBT) used for GOP +- CONFIG_DISPLAY_UPD_DATA - Display the user specified product data passed to MemoryInit and SiliconInit + +-------------------------------------------------------------------------------- + +Modified: 17 May 2016 diff --git a/Documentation/content/docs/vendor/intel/index.md b/Documentation/content/docs/vendor/intel/index.md new file mode 100644 index 0000000..5df16e1 --- /dev/null +++ b/Documentation/content/docs/vendor/intel/index.md @@ -0,0 +1,9 @@ +--- +date: 2016-07-01T19:25:34.000Z +title: Intel Documentation +name: Intel Documentation +weight: 10 +menu: + main: +next: fsp1_1 +--- diff --git a/Documentation/content/docs/vendor/intel/soc/quark.md b/Documentation/content/docs/vendor/intel/soc/quark.md new file mode 100644 index 0000000..16beb0c --- /dev/null +++ b/Documentation/content/docs/vendor/intel/soc/quark.md @@ -0,0 +1,152 @@ +--- +date: 2016-07-01T19:25:34.000Z +title: Quark +name: Quark +weight: 50 +menu: + main: + parent: Intel Documentation +--- + +## Intel® Quark™ SoC + ++--------------------------------------+--------------------------------------+ +| [ board: | +| ed/16x9/edc-quark-block-diagram-16x9 | - [Overall](../development.html) | +| .png)](http://www.intel.com/content/ | development | +| dam/www/public/us/en/images/embedded | - [SoC](soc.html) support | +| /16x9/edc-quark-block-diagram-16x9.p | - [FSP 1.1](../fsp1_1.html) | +| ng) | integration | +| | - [Board](../Board/board.html) | +| | support | +| | - [Quark™ FSP](#QuarkFsp) | +| | - [CorebootPayloadPkg](#CorebootPa | +| | yloadPkg) | ++--------------------------------------+--------------------------------------+ + +## Quark™ Documentation + +- [Block Diagram](http://www.intel.com/content/dam/www/public/us/en/images/embedded/16x9/edc-q...) +- [Specifications](http://www.intel.com/content/www/us/en/embedded/products/quark/specification...): + + - [X1000](http://ark.intel.com/products/79084/Intel-Quark-SoC-X1000-16K-Cache-400-MHz) - [Documentation](http://www.intel.com/content/www/us/en/search.html?keyword=X1000): + + - [Datasheet](http://www.intel.com/content/dam/www/public/us/en/documents/datasheets/quark...) + - [Developer's Manual](http://www.intel.com/content/dam/support/us/en/documents/processors/quark/sb...) + - [Product Brief](http://www.intel.com/content/dam/www/public/us/en/documents/product-briefs/i...) + +- [More documentation](../index.html#Documentation) + +-------------------------------------------------------------------------------- + +## [Quark™ EDK2 CorebootPayloadPkg]() + +Build Instructions: + +1. Set up [build environment](#BuildEnvironment) +2. Linux (assumes GCC48): + + ``` + build -p CorebootPayloadPkg/CorebootPayloadPkgIa32.dsc -a IA32 \ + -t GCC48 -b DEBUG -DDEBUG_PROPERTY_MASK=0x27 \ + -DDEBUG_PRINT_ERROR_LEVEL=0x80000042 -DSHELL_TYPE=BUILD_SHELL \ + -DMAX_LOGICAL_PROCESSORS=1 + ls Build/CorebootPayloadPkgIA32/DEBUG_GCC48/FV/UEFIPAYLOAD.fd + ``` + +3. Windows (assumes Visual Studio 2015): + + ``` + build -p CorebootPayloadPkg\CorebootPayloadPkgIa32.dsc -a IA32 -t VS2015x86 -b DEBUG -DDEBUG_PROPERTY_MASK=0x27 -DDEBUG_PRINT_ERROR_LEVEL=0x80000042 -DSHELL_TYPE=BUILD_SHELL -DMAX_LOGICAL_PROCESSORS=1 + dir Build\CorebootPayloadPkgIA32\DEBUG_VS2015x86\FV\UEFIPAYLOAD.fd + ``` + +4. In the .config for coreboot, set the following Kconfig values: + + - CONFIG_PAYLOAD_ELF=y + - CONFIG_PAYLOAD_FILE="path to UEFIPAYLOAD.fd" + +5. Build coreboot + +6. Copy the image build/coreboot.rom into flash + +-------------------------------------------------------------------------------- + +## [Quark™ EDK2 Build Environment]() + +Use the following steps to setup a build environment: + +1. Get the EDK2 sources: + + 1. EDK2: git clone https://github.com/tianocore/edk2.git + 2. EDK2-non-osi: git clone https://github.com/tianocore/edk2-non-osi.git + 3. Win32 BaseTools: git clone https://github.com/tianocore/edk2-BaseTools-win32.git + +2. Set up a build window: + + - Linux: + + ``` + export WORKSPACE=$PWD + export PACKAGES_PATH="$PWD/edk2:$PWD/edk2-non-osi" + cd edk2 + export WORKSPACE=$PWD + . edksetup.sh + ``` + + - Windows: + + ``` + set WORKSPACE=%CD% + set PACKAGES_PATH=%WORKSPACE%\edk2;%WORKSPACE%\edk2-non-osi + set EDK_TOOLS_BIN=%WORKSPACE%\edk2-BaseTools-win32 + cd edk2 + edksetup.bat + ``` + +-------------------------------------------------------------------------------- + +## [Quark™ FSP]() + +Getting the Quark FSP source: + +1. Set up an EDK-II [Build Environment](#BuildEnvironment) +2. cd edk2 +3. mkdir QuarkFspPkg +4. cd QuarkFspPkg +5. Use git to clone [QuarkFspPkg](https://review.gerrithub.io/#/admin/projects/LeeLeahy/quarkfsp) into the QuarkFpsPkg directory (.) + +Building QuarkFspPkg: + +- Linux: QuarkFspPkg/BuildFsp.sh -d32 +- Windows: QuarkFspPkg/BuildFsp.bat -d32 + +-------------------------------------------------------------------------------- + +## Quark™ EDK2 BIOS + +Build Instructions: + +1. Set up [build environment](#BuildEnvironment) +2. Build the image: + + - Linux: + + ``` + build -p QuarkPlatformPkg/Quark.dsc -a IA32 -t GCC48 -b DEBUG -DDEBUG_PROPERTY_MASK=0x27 -DDEBUG_PRINT_ERROR_LEVEL=0x80000042 + ls Build/Quark/DEBUG_GCC48/FV/Quark.fd + ``` + + - Windows: + + ``` + build -p QuarkPlatformPkg/Quark.dsc -a IA32 -t VS2012x86 -b DEBUG -DDEBUG_PROPERTY_MASK=0x27 -DDEBUG_PRINT_ERROR_LEVEL=0x80000042 + dir Build\Quark\DEBUG_VS2012x86\FV\Quark.fd + ``` + +Documentation: + +- [EDK II firmware for Intel® Quark™ SoC X1000 based platforms](https://github.com/tianocore/edk2/tree/master/QuarkPlatformPkg) +- Intel® Quark™ SoC X1000 [UEFI Firmware Writer's Guide](http://www.intel.com/content/dam/www/public/us/en/documents/guides/quark-x10...) diff --git a/Documentation/content/docs/vendor/intel/soc/soc.md b/Documentation/content/docs/vendor/intel/soc/soc.md new file mode 100644 index 0000000..fc2b309 --- /dev/null +++ b/Documentation/content/docs/vendor/intel/soc/soc.md @@ -0,0 +1,593 @@ +--- +date: 2016-07-01T19:25:34.000Z +title: SoC +name: SoC +weight: 40 +menu: + main: + parent: Intel Documentation +--- + +## 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](../development.html). The development steps for the SoC are listed below: + +1. [FSP 1.1](../fsp1_1.html#RequiredFiles) required files +2. SoC [Required Files](#RequiredFiles) +3. [Start Booting](#Descriptor) +4. [Early Debug](#EarlyDebug) +5. [Bootblock](#Bootblock) +6. [TempRamInit](#TempRamInit) +7. [Romstage](#Romstage) + + 1. Enable [Serial Output"](#SerialOutput) + 2. Get the [Previous Sleep State](#PreviousSleepState) + 3. Add the [MemoryInit](#MemoryInit) Support + 4. Disable the [Shadow ROM](#DisableShadowRom) + +8. [Ramstage](#Ramstage) + + 1. [Start Device Tree Processing](#DeviceTree) + 2. Set up the [Memory Map"](#MemoryMap) + +9. [ACPI Tables](#AcpiTables) + +10. [Legacy Hardware](#LegacyHardware) + +-------------------------------------------------------------------------------- + +## [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: + +- 0x01: [POST_RESET_VECTOR_CORRECT](http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/include/consol...) - Bootblock successfully executed the [reset vector](http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/cpu/x86/16bit/...) and entered the 16-bit code at [_start](http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/cpu/x86/16bit/...) + +-------------------------------------------------------------------------------- + +## [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](http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/include/consol...) - Bootblock successfully executed the [reset vector](http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/cpu/x86/16bit/...) and entered the 16-bit code at [_start](http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/cpu/x86/16bit/...) + 2. 0x10: [POST_ENTER_PROTECTED_MODE](http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/include/consol...) - Bootblock executing in [32-bit mode](http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/cpu/x86/32bit/...) + 3. 0x10 - Verstage/romstage reached 32-bit mode + +**Build Note:** The following files are included into the default bootblock image: + +- [src/arch/x86/bootblock_romcc.S](http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/arch/x86/bootb...) added by [src/arch/x86/Makefile.inc](http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/arch/x86/Makef...) and includes the following files: + + - [src/arch/x86/prologue.inc](http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/arch/x86/prolo...) + - [src/cpu/x86/16bit/reset16.inc](http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/cpu/x86/16bit/...) + - [src/cpu/x86/16bit/entry16.inc](http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/cpu/x86/16bit/...) + - [src/cpu/x86/32bit/entry32.inc](http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/cpu/x86/32bit/...) + - The code in [src/arch/x86/bootblock_romcc.S](http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/arch/x86/bootb...) includes src/soc/<Vendor>/<Chip Family>/bootblock/timestamp.inc using the CONFIG_CHIPSET_BOOTBLOCK_INCLUDE value set above + - [src/cpu/x86/sse_enable.inc](http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/cpu/x86/sse_en...) + - The code in [src/arch/x86/Makefile.inc](http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/arch/x86/Makef...) invokes the ROMCC tool to convert the following "C" code into assembler as bootblock.inc: + + - [src/arch/x86/include/arch/bootblock_romcc.h](http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/arch/x86/inclu...) + - [src/cpu/x86/lapic/boot_cpu.c](http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/cpu/x86/lapic/...) + - The CONFIG_BOOTBLOCK_CPU_INIT value set above typically points to the code in src/soc/<Vendor>/<Chip Family>/bootblock/bootblock.c + +- [src/arch/x86/id.S](http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/arch/x86/id.S) added by [src/arch/x86/Makefile.inc](http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/arch/x86/Makef...) +- [src/cpu/intel/fit/fit.S](http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/cpu/intel/fit/...) added by [src/cpu/intel/fit/Makefile.inc](http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/cpu/intel/fit/...) +- [src/arch/x86/walkcbfs.S](http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/arch/x86/walkc...) added by [src/arch/x86/Makefile.inc](http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/arch/x86/Makef...) + +-------------------------------------------------------------------------------- + +## [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](http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/...) + 2. Add "select SOC_INTEL_COMMON" to enable the use of the files from src/soc/intel/common specifically building [util.c](http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/soc/intel/comm...) + +2. Debug the result until port 0x80 outputs + + 1. 0x90: [POST_FSP_TEMP_RAM_INIT](http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/include/consol...) - Just before calling [TempRamInit](http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/...) + 2. Alternating 0xba and 0x01 - The FSP image was not found + +3. Add the [FSP binary file](../fsp1_1.html#FspBinary) to the flash image + +4. Set the following Kconfig values: + + - CONFIG_FSP_LOC to the FSP base address specified in the previous step + - CONFIG_FSP_IMAGE_ID_STRING + +5. Debug the result until port 0x80 outputs + + 1. 0x90: [POST_FSP_TEMP_RAM_INIT](http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/include/consol...) - Just before calling [TempRamInit](http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/...) + 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](http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/include/consol...) - Just before calling [TempRamInit](http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/...) + 2. 0x2A - Just before calling [cache_as_ram_main](http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/...) 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: + + - CONFIG_DRIVERS_UART_<driver>=y + - CONFIG_CONSOLE_SERIAL=y + - CONFIG_UART_FOR_CONSOLE=<port> + - CONFIG_CONSOLE_SERIAL_115200=y + +### [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](http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/...) + 2. 0x33 - Just after calling [soc_pre_ram_init](http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/...) + 3. 0x34: - Just after entering [raminit](http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/...) + +### [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](http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/lib/hardwarema...) 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](http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/device/device_...). + +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](http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/include/device...) like: + + - ram_resource + - reserved_ram_resource + - bad_ram_resource + - uma_resource + - mmio_resource + +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](quark.html#CorebootPayloadPkg). + +## FADT + +The EDK2 module CorebootModulePkg/Library/CbParseLib/[CbParseLib.c](https://github.com/tianocore/edk2/blob/master/CorebootModulePkg/Library/CbPa...) requires that the FADT contains the values in the table below. These values are placed into a HOB identified by [gUefiAcpiBoardInfoGuid](https://github.com/tianocore/edk2/blob/master/CorebootModulePkg/CorebootModu...) by routine CorebootModulePkg/CbSupportPei/CbSupportPei/[CbPeiEntryPoint](https://github.com/tianocore/edk2/blob/master/CorebootModulePkg/CbSupportPei...). + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Coreboot Field | EDK2 Field | gUefiAcpiBoardInfoGuid | Use | [ACPI Spec.](http://www.uefi.org/sites/default/files/resources/ACPI_6.0.pdf) Section +---------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ +gpe0_blk\ gpe0_blk_len | Gpe0Blk\ Gpe0BlkLen | [PmGpeEnBase](https://github.com/tianocore/edk2/blob/master/CorebootModulePkg/Library/CbPa...) | [Shutdown](https://github.com/tianocore/edk2/blob/master/CorebootPayloadPkg/Library/Res...) | 4.8.4.1 +pm1a_cnt_blk | Pm1aCntBlk | PmCtrlRegBase | [Shutdown](https://github.com/tianocore/edk2/blob/master/CorebootPayloadPkg/Library/Res... + + + +[Suspend](https://github.com/tianocore/edk2/blob/master/CorebootPayloadPkg/Library/Res...) | 4.8.3.2.1 +pm1a_evt_blk | Pm1aEvtBlk | PmEvtBase | [Shutdown](https://github.com/tianocore/edk2/blob/master/CorebootPayloadPkg/Library/Res...) | 4.8.3.1.1 +pm_tmr_blk | PmTmrBlk | PmTimerRegBase | [Timer](https://github.com/tianocore/edk2/blob/master/CorebootPayloadPkg/Library/Acp...) | 4.8.3.3 +reset_reg. | ResetReg.Address | ResetRegAddress | [Cold](https://github.com/tianocore/edk2/blob/master/CorebootPayloadPkg/Library/Res...) and [Warm](https://github.com/tianocore/edk2/blob/master/CorebootPayloadPkg/Library/Res...) resets | 4.3.3.6 +reset_value | ResetValue | ResetValue | [Cold](https://github.com/tianocore/edk2/blob/master/CorebootPayloadPkg/Library/Res...) and [Warm](https://github.com/tianocore/edk2/blob/master/CorebootPayloadPkg/Library/Res...) resets | 4.8.3.6 + + The EDK2 data structure is defined in MdeModulePkg/Include/IndustryStandard/[Acpi61.h](https://github.com/tianocore/edk2/blob/master/MdePkg/Include/IndustryStandar...) The coreboot data structure is defined in src/arch/x86/include/arch/[acpi.h](http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/arch/x86/inclu...) + + + +1. Select [HAVE_ACPI_TABLES](../Board/board.html#AcpiTables) 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](quark.html#CorebootPayloadPkg). + +-------------------------------------------------------------------------------- + +Peripheral Use 8259 Interrupt Vector IDT Base Offset Interrupt Handler + +-------------------------------------------------------------------------------- + +[8254](http://www.scs.stanford.edu/10wi-cs140/pintos/specs/8254.pdf) Programmable Interval Timer EDK2: PcAtChipsetPkg/8254TimerDxe/[Timer.c](https://github.com/tianocore/edk2/blob/master/PcAtChipsetPkg/8254TimerDxe/Ti...) 0 0x340 [TimerInterruptHandler](https://github.com/tianocore/edk2/blob/master/PcAtChipsetPkg/8254TimerDxe/Ti...) + +[8259](https://www.google.com/url?sa=t&rct=j&q=&esrc=s&source=web&a...) Programmable Interrupt Controller EDK2: PcAtChipsetPkg/8259InterruptControllerDxe/[8259.c](https://github.com/tianocore/edk2/blob/master/PcAtChipsetPkg/8259InterruptCo...) Master interrupts: 0, 2 - 7\ Master: 0x340, 0x350 - 0x378<br> +Slave interrupts: 8 - 15\ Slave: 0x380 - 0x3b8\ + +``` + Interrupt vector 1 is never generated, the cascaded input generates interrupts 8 - 15 Interrupt descriptors are 8 bytes each +``` + +-------------------------------------------------------------------------------- + +-------------------------------------------------------------------------------- + +Modified: 4 March 2016 diff --git a/Documentation/content/docs/vendor/intel/tableofcontents.md b/Documentation/content/docs/vendor/intel/tableofcontents.md new file mode 100644 index 0000000..9625eba --- /dev/null +++ b/Documentation/content/docs/vendor/intel/tableofcontents.md @@ -0,0 +1,70 @@ +--- +date: 2016-07-01T19:25:34.000Z +title: Table of Contents +name: Table of Contents +menu: + main: + parent: Intel Documentation +next: fsp1_1 +prev: index +weight: 10 +--- + +## Intel® x86 Boards + +- [Galileo](Board/galileo.html) +- [MinnowBoard MAX](http://wiki.minnowboard.org/Coreboot) + +# Intel® x86 SoCs + +- [Quark™](SoC/quark.html) + +-------------------------------------------------------------------------------- + +## x86 coreboot Development + +- Get the [coreboot source](https://www.coreboot.org/Git) +[](https://www.coreboot.org/Git)- [](https://www.coreboot.org/Git)%5BOverall%5D(development.html) development +- [FSP 1.1](fsp1_1.md) integration +- {{< relref "fsp1_1.md" >}} +- [SoC](SoC/soc.html) support +- [Board](Board/board.html) support + +-------------------------------------------------------------------------------- + +## Payload Development + +- [CorebootPayloadPkg](SoC/quark.html#CorebootPayloadPkg) + + - [EDK II Development Process](https://github.com/tianocore/tianocore.github.io/wiki/EDK-II-Development-Pro...) + - EDK II [White Papers](https://github.com/tianocore/tianocore.github.io/wiki/EDK%20II%20White%20pap...) + - [SourceForge to Github Quick Start](https://github.com/tianocore/tianocore.github.io/wiki/SourceForge-to-Github-...) + - UEFI [2.5 Errata A](http://www.uefi.org/sites/default/files/resources/UEFI%20Spec%202_5_Errata_A...) + +-------------------------------------------------------------------------------- + +## [Documentation]() + +- [ACPI Specifications](http://www.uefi.org/specifications) +- Intel® 64 and IA-32 Architectures [Software Developer Manual](http://www.intel.com/content/dam/www/public/us/en/documents/manuals/64-ia-32...) +- [UEFI Specifications](http://www.uefi.org/specifications) + +## [EDK-II Documentation]() + +- Build [V1.26](https://github.com/tianocore-docs/Docs/raw/master/Specifications/Build_Spec_...) +- Coding Standards [V2.1](https://github.com/tianocore-docs/Docs/raw/master/Specifications/CCS_2_1_Dra...) +- DEC [V1.25](https://github.com/tianocore-docs/Docs/raw/master/Specifications/DEC_Spec_1_...) +- DSC [V1.26](https://github.com/tianocore-docs/Docs/raw/master/Specifications/DSC_Spec_1_...) +- [Driver Writer's Guide](https://github.com/tianocore/tianocore.github.io/wiki/UEFI-Driver-Writer%27s...) +- Expression Syntax [V1.1](https://github.com/tianocore-docs/Docs/raw/master/Specifications/ExpressionS...) +- FDF [V1.26](https://github.com/tianocore-docs/Docs/raw/master/Specifications/FDF_Spec_1_...) +- INF [V1.25](https://github.com/tianocore-docs/Docs/raw/master/Specifications/INF_Spec_1_...) +- PCD [PCD](https://github.com/tianocore-docs/Docs/raw/master/Specifications/PCD_Infrast... +- UNI [V1.2 Errata A](https://github.com/tianocore-docs/Docs/raw/master/Specifications/UNI_File_Sp...) +- VRF [V1.9](https://github.com/tianocore-docs/Docs/raw/master/Specifications/VFR_1_9.pdf) + +## [FSP Documentation]() + +- Intel® Firmware Support Package External Architecture Specification [V2.0](http://www.intel.com/content/dam/www/public/us/en/documents/technical-specif...) +- Intel® Firmware Support Package External Architecture Specification [V1.1](http://www.intel.com/content/dam/www/public/us/en/documents/technical-specif...) +- Intel® Firmware Support Package External Architecture Specification [V1.0](http://www.intel.com/content/dam/www/public/us/en/documents/technical-specif...) diff --git a/Documentation/content/getting-started/gerrit.md b/Documentation/content/getting-started/gerrit.md new file mode 100644 index 0000000..878a90c --- /dev/null +++ b/Documentation/content/getting-started/gerrit.md @@ -0,0 +1,126 @@ +--- +date: 2016-07-01T19:25:34.000Z +title: Gerrit Guidelines +weight: 20 +menu: + main: + parent: Getting Started +name: Gerrit Guidelines +next: Submodules +prev: Getting Started +--- + +## Gerrit Guidelines + +### Gerrit Etiquette and Guidelines + +The following rules are the requirements for behavior in the coreboot codebase in gerrit. These have mainly been unwritten rules up to this point, and should be familiar to most users who have been active in coreboot for a period of time. Following these rules will help reduce friction in the community. + +Note that as with many rules, there are exceptions. Some have been noted in the 'More Detail' section. If you feel there is an exception not listed here, please discuss it in the mailing list to get this document updated. Don't just assume that it's okay, even if someone on IRC says it is. + +### Summary: + +These are the expectations for committing, reviewing, and submitting code into coreboot git and gerrit. While breaking individual rules may not have immediate consequences, the coreboot leadership may act on repeated or flagrant violations with or without notice. + +- Don't violate the licenses. +- Let non-trivial patches sit in a review state for at least 24 hours before submission. +- Try to coordinate with platform maintainers when making changes to platforms. +- If you give a patch a -2, you are responsible for giving concrete recommendations for what could be changed to resolve the issue the patch addresses. +- Don't modify other people's patches without their consent. +- Be respectful to others when commenting. +- Don't submit patches that you know will break other platforms. + +### More detail: + +- Don't violate the licenses. If you're submitting code that you didn't write yourself, make sure the license is compatible with the license of the project you're submitting the changes to. If you're submitting code that you wrote that might be owned by your employer, make sure that your employer is aware and you are authorized to submit the code. For clarification, see the Developer's Certificate of Origin in the coreboot [Signed-off-by policy](http://www.coreboot.org/Development_Guidelines#Sign-off_Procedure). + +- Let non-trivial patches sit in a review state for at least 24 hours before submission. Remember that there are coreboot developers in timezones all over the world, and everyone should have a chance to contribute. Trivial patches would be things like whitespace changes or spelling fixes. In general, small changes that don't impact the final binary output. The 24-hour period would start at submission, and would be restarted at any update which significantly changes any part of the patch. Patches can be 'Fast-tracked' and submitted in under this 24 hour with the agreement of at least 3 +2 votes. + +- Do not +2 patches that you authored or own, even for something as trivial as whitespace fixes. When working on your own patches, it's easy to overlook something like accidentally updating file permissions or git submodule commit IDs. Let someone else review the patch. An exception to this would be if two people worked in the patch together. If both +2 the patch, that is acceptable, as each is giving a +2 to the other's work. + +- Try to coordinate with platform maintainers and other significant contributors to the code when making changes to platforms. The platform maintainers are the users who initially pushed the code for that platform, as well as users who have made significant changes to a platform. To find out who maintains a piece of code, please use util/scripts/maintainers.go or refer to the original author of the code in git log. + +- If you give a patch a -2, you are responsible for giving concrete recommendations for what could be changed to resolve the issue the patch addresses. If you feel strongly that a patch should NEVER be merged, you are responsible for defending your position and listening to other points of view. Giving a -2 and walking away is not acceptable, and may cause your -2 to be removed by the coreboot leadership after no less than a week. A notification that the -2 will be removed unless there is a response will be sent out at least 2 days before it is removed. + +- Don't modify other people's patches unless you have coordinated this with the owner of that patch. Not only is this considered rude, but your changes could be unintentionally lost. An exception to this would be for patches that have not been updated for more than 90 days. In that case, the patch can be taken over if the original author does not respond to requests for updates. Alternatively, a new patch can be pushed with the original content, and both patches should be updated to reference the other. + +- Be respectful to others when commenting on patches. Comments should be kept to the code, and should be kept in a polite tone. We are a worldwide community and English is a difficult language. Assume your colleagues are intelligent and do not intend disrespect. Resist the urge to retaliate against perceived verbal misconduct, such behavior is not conducive to getting patches merged. + +- Don't submit code that you know will break other platforms. If your patch affects code that is used by other platforms, it should be compatible with those platforms. While it would be nice to update any other platforms, you must at least provide a path that will allow other platforms to continue working. + +### Recommendations for gerrit activity: + +These guidelines are less strict than the ones listed above. These are more of the "good idea" variety. You are requested to follow the below guidelines, but there will probably be no actual consequences if they're not followed. That said, following the recommendations below will speed up review of your patches, and make the members of the community do less work. + +- Each patch should be kept to one logical change, which should be described in the title of the patch. Unrelated changes should be split out into separate patches. Fixing whitespace on a line you're editing is reasonable. Fixing whitespace around the code you're working on should be a separate 'cleanup' patch. Larger patches that touch several areas are fine, so long as they are one logical change. Adding new chips and doing code cleanup over wide areas are two examples of this. + +- Test your patches before submitting them to gerrit. It's also appreciated if you add a line to the commit message describing how the patch was tested. This prevents people from having to ask whether and how the patch was tested. Examples of this sort of comment would be 'TEST=Built platform' or 'Tested by building and booting platform'. Stating that the patch was not tested is also fine, although you might be asked to do some testing in cases where that would be reasonable. + +- Take advantage of the lint tools to make sure your patches don't contain trivial mistakes. By running 'make gitconfig', the lint-stable tools are automatically put in place and will test your patches before they are committed. As a violation of these tools will cause the jenkins build test to fail, it's to your advantage to test this before pushing to gerrit. + +- Don't submit patch trains longer than around 20 patches unless you understand how to manage long patch trains. Long patch trains can become difficult to handle and tie up the build servers for long periods of time if not managed well. Rebasing a patch train over and over as you fix earlier patches in the train can hide comments, and make people review the code multiple times to see if anything has changed between revisions. When pushing long patch trains, it is recommended to only push the full patch train once - the initial time, and only to rebase three or four patches at a time. + +- Run 'make what-jenkins-does' locally on patch trains before submitting. This helps verify that the patch train won't tie up the jenkins builders for no reason if there are failing patches in the train. For running parallel builds, you can specify the number of cores to use by setting the the CPUS environment variable. Example: + + ```sh + make what-jenkins-does CPUS=8 + ``` + +- Use a topic when pushing a train of patches. This groups the commits together so people can easily see the connection at the top level of gerrit. Topics can be set for individual patches in gerrit by going into the patch and clicking on the icon next to the topic line. Topics can also be set when you push the patches into gerrit. For example, to push a set of commits with the the i915-kernel-x60 set, use the command: + + ```sh + git push origin HEAD:refs/for/master/i915-kernel-x60 + ``` + +- If one of your patches isn't ready to be merged, make sure it's obvious that you don't feel it's ready for merge yet. The preferred way to show this is by marking in the commit message that it's not ready until X. The commit message can be updated easily when it's ready to be pushed. Examples of this are "WIP: title" or "[NEEDS_TEST]: title". Another way to mark the patch as not ready would be to give it a -1 or -2 review, but isn't as obvious as the commit message. These patches can also be pushed as drafts as shown in the next guideline. + +- When pushing patches that are not for submission, these should be marked as such. This can be done in the title '[DONOTSUBMIT]', or can be pushed as draft commits, so that only explicitly added reviewers will see them. These sorts of patches are frequently posted as ideas or RFCs for the community to look at. To push a draft, use the command: + + ```sh + git push origin HEAD:refs/drafts/master + ``` + +- Respond to anyone who has taken the time to review your patches, even if it's just to say that you disagree. While it may seem annoying to address a request to fix spelling or 'trivial' issues, it's generally easy to handle in gerrit's built-in editor. If you do use the built-in editor, remember to get that change to your local copy before re-pushing. It's also acceptable to add fixes for these sorts of comments to another patch, but it's recommended that that patch be pushed to gerrit before the initial patch gets submitted. + +- Consider breaking up large individual patches into smaller patches grouped by areas. This makes the patches easier to review, but increases the number of patches. The way you want to handle this is a personal decision, as long as each patch is still one logical change. + +- If you have an interest in a particular area or mainboard, set yourself up as a 'maintainer' of that area by adding yourself to the MAINTAINERS file in the coreboot root directory. Eventually, this should automatically add you as a reviewer when an area that you're listed as a maintainer is changed. + +- Submit mainboards that you're working on to the board-status repo. This helps others and shows that these mainboards are currently being maintained. At some point, boards that are not up to date in the board-status repo will probably end up getting removed from the coreboot master branch. + +- Abandon patches that are no longer useful, or that you don't intend to keep working on to get submitted. + +- Bring attention to patches that you would like reviewed. Add reviewers, ask for reviewers on IRC or even just rebase it against the current codebase to bring it to the top of the gerrit list. If you're not sure who would be a good reviewer, look in the MAINTAINERS file or git history of the files that you've changed, and add those people. + +- Familiarize yourself with the coreboot [commit message guidelines](http://www.coreboot.org/Git#Commit_messages), before pushing patches. This will help to keep annoying requests to fix your commit message to a minimum. + +- If there have been comments or discussion on a patch, verify that the comments have been addressed before giving a +2. If you feel that a comment is invalid, please respond to that comment instead of just ignoring it. + +- Be conscientious when reviewing patches. As a reviewer who approves (+2) a patch, you are responsible for the patch and the effect it has on the codebase. In the event that the patch breaks things, you are expected to be actively involved in the cleanup effort. This means you shouldn't +2 a patch just because you trust the author of a patch - Make sure you understand what the implications of a patch might be, or leave the review to others. Partial reviews, reviewing code style, for example, can be given a +1 instead of a +2. This also applies if you think the patch looks good, but may not have the experience to know if there may be unintended consequences. + +- If there is still ongoing discussion to a patch, try to wait for a conclusion to the discussion before submitting it to the tree. If you feel that someone is just bikeshedding, maybe just state that and give a time that the patch will be submitted if no new objections are raised. + +- When working with patch trains, for minor requests it's acceptable to create a fix addressing a comment in another patch at the end of the patch train. This minimizes rebases of the patch train while still addressing the request. For major problems where the change doesn't work as intended or breaks other platforms, the change really needs to go into the original patch. + +- When bringing in a patch from another git repo, update the original git/gerrit tags by prepending the lines with 'Original-'. Marking the original text this way makes it much easier to tell what changes happened in which repository. This applies to these lines, not the actual commit message itself: + + ``` + Commit-Id: + Change-Id: + Signed-off-by: + Reviewed-on: + Tested-by: + Reviewed-by: + ``` + + The script 'util/gitconfig/rebase.sh' can be used to help automate this. Other tags such as 'Commit-Queue' can simply be removed. + +### Expectations contributors should have: + +- Don't expect that people will review your patch unless you ask them to. Adding other people as reviewers is the easiest way. Asking for reviews for individual patches in the IRC channel, or by sending a direct request to an individual through your favorite messenger is usually the best way to get a patch reviewed quickly. + +- Don't expect that your patch will be submitted immediately after getting a +2. As stated previously, non-trivial patches should wait at least 24 hours before being submitted. That said, if you feel that your patch or series of patches has been sitting longer than needed, you can ask for it to be submitted on IRC, or comment that it's ready for submission in the patch. This will move it to the top of the list where it's more likely to be noticed and acted upon. + +- Reviews are about the code. It's easy to take it personally when someone is criticising your code, but the whole idea is to get better code into our codebase. Again, this also applies in the other direction: review code, criticize code, but don't make it personal. + +Requests for clarification and suggestions for updates to these guidelines should be sent to the coreboot mailing list at [coreboot@coreboot.org](mailto:coreboot@coreboot.org). diff --git a/Documentation/content/getting-started/index.md b/Documentation/content/getting-started/index.md new file mode 100644 index 0000000..ff4b5b9 --- /dev/null +++ b/Documentation/content/getting-started/index.md @@ -0,0 +1,10 @@ +--- +date: 2016-07-01T19:25:34.000Z +title: Getting Started +weight: 10 +menu: + main: +name: Getting Started +url: getting-started/ +next: Gerrit Guidelines +--- diff --git a/Documentation/content/getting-started/submodules.md b/Documentation/content/getting-started/submodules.md new file mode 100644 index 0000000..c1c895d --- /dev/null +++ b/Documentation/content/getting-started/submodules.md @@ -0,0 +1,43 @@ +--- +date: 2016-07-01T19:25:34.000Z +title: Git Submodules +weight: 30 +menu: + main: + parent: Getting Started +name: Submodules +--- + +## Use of git submodules in coreboot + +coreboot uses git submodules to keep certain parts of the tree separate, with two major use cases: + +First, we use a vendor tool by NVIDIA for systems based on their SoC and since they publish it through git, we can just import it into our tree using submodules. + +Second, lots of boards these days require binaries and we want to keep them separate from coreboot proper to clearly delineate shiny Open Source from ugly blobs. Since we don't want to impose blobs on users who really don't need them, that repository is only downloaded and checked out on explicit request. + +### Handling submodules + +For the most part, submodules should be automatically checked out on the first execution of the coreboot Makefile. + +To manually fetch all repositories (eg. when you want to prepare the tree for archiving, or to use it without network access), run + +``` +$ git submodule update --init --checkout +``` + +This also checks out the binaries below `3rdparty/` + +### Mirroring coreboot + +When running a coreboot mirror to checkout from, for full operation, you should also mirror the blobs and nvidia-cbootimage repository, and place them in the same directory as the coreboot repository mirror. + +That is, when residing in coreboot's repository, `cd ../blobs.git` should move you to the blobs repository. + +With that, no matter what the URL of your coreboot repository is, the git client (of a sufficiently new version) is able to pick up the other repositories transparently. + +### Minimum requirements + +git needs to be able to handle relative paths to submodule repositories, and it needs to know about non-automatic submodules. + +For these features, we require git version 1.7.6.1 or newer. diff --git a/Documentation/content/index.md b/Documentation/content/index.md new file mode 100644 index 0000000..0c7ee73 --- /dev/null +++ b/Documentation/content/index.md @@ -0,0 +1,10 @@ +--- +date: 2016-03-08T21:07:13+01:00 +title: The Project +type: index +weight: 0 +--- + +## Introduction + +Welcome to coreboot diff --git a/Documentation/content/licenses/index.md b/Documentation/content/licenses/index.md new file mode 100644 index 0000000..11979f5 --- /dev/null +++ b/Documentation/content/licenses/index.md @@ -0,0 +1,9 @@ +--- +date: 2016-07-01T19:25:34.000Z +title: Licenses +weight: 99 +menu: + main: +name: Licenses +url: licenses/ +---