| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,85 @@ | ||
| # Intel Common Code Block Publishing EFI_MP_SERVICES_PPI | ||
|
|
||
| ## Introduction | ||
|
|
||
| This documentation is intended to document the purpose for creating EFI service | ||
| Interface inside coreboot space to perform CPU feature programming on Application | ||
| Processors for Intel 9th Gen (Cannon Lake) and beyond CPUs. | ||
|
|
||
| Today coreboot is capable enough to handle multi-processor initialization on IA platforms. | ||
|
|
||
| The multi-processor initialization code has to take care of lots of duties: | ||
|
|
||
| 1. Bringing all cores out of reset | ||
| 2. Load latest microcode on all cores | ||
| 3. Sync latest MTRR snapshot between BSP and APs | ||
| 4. Perform sets of CPU feature programming | ||
| * CPU Power & Thermal Management | ||
| * Overclocking | ||
| * Intel Trusted Execution Technology | ||
| * Intel Software Guard Extensions | ||
| * Intel Processor Trace etc. | ||
|
|
||
| This above CPU feature programming lists are expected to grow with current and future | ||
| CPU complexity and there might be some cases where certain feature programming mightbe | ||
| closed source in nature. | ||
|
|
||
| Platform code might need to compromise on those closed source nature of CPU programming | ||
| if we don't plan to provide an alternate interface which can be used by coreboot to | ||
| get-rid of such close source CPU programming. | ||
|
|
||
| ## Proposal | ||
|
|
||
| As coreboot is doing CPU multi-processor initialization for IA platform before FSP-S | ||
| initialization and having all possible information about cores in terms of maximum number | ||
| of cores, APIC ids, stack size etc. It’s also possible for coreboot to extend its own | ||
| support model and create a sets of APIs which later can be used by FSP to run CPU feature | ||
| programming using coreboot published APIs. | ||
|
|
||
| Due to the fact that FSP is using EFI infrastructure and need to relying on install/locate | ||
| PPI to perform certain API call, hence coreboot has to created MP services APIs known as | ||
| EFI_MP_SERVICES_PPI as per PI specification volume 1, section 8.3.9. | ||
| More details here: [PI_Spec_1_6] | ||
|
|
||
| ### coreboot to publish EFI_MP_SERVICES_PPI APIs | ||
|
|
||
| ```eval_rst | ||
| +------------------------------+------------------------------------------------------------------+ | ||
| | API | Description | | ||
| +==============================+==================================================================+ | ||
| | PeiGetNumberOfProcessors | Get the number of CPU's. | | ||
| +------------------------------+------------------------------------------------------------------+ | ||
| | PeiGetProcessorInfo | Get information on a specific CPU. | | ||
| +------------------------------+------------------------------------------------------------------+ | ||
| | PeiStartupAllAPs | Activate all of the application processors. | | ||
| +------------------------------+------------------------------------------------------------------+ | ||
| | PeiStartupThisAP | Activate a specific application processor. | | ||
| +------------------------------+------------------------------------------------------------------+ | ||
| | PeiSwitchBSP | Switch the boot strap processor. | | ||
| +------------------------------+------------------------------------------------------------------+ | ||
| | PeiEnableDisableAP | Enable or disable an application processor. | | ||
| +------------------------------+------------------------------------------------------------------+ | ||
| | PeiWhoAmI | Identify the currently executing processor. | | ||
| +------------------------------+------------------------------------------------------------------+ | ||
| ``` | ||
|
|
||
| ## Code Flow | ||
|
|
||
| Here is proposed design flow with coreboot has implemented EFI_MP_SERVICES_PPI API and FSP will make | ||
| use of the same to perform some CPU feature programming. | ||
|
|
||
| **coreboot-FSP MP init flow** | ||
| ![coreboot-fsp mp init flow][coreboot_publish_mp_service_api] | ||
|
|
||
| [coreboot_publish_mp_service_api]: coreboot_publish_mp_service_api.png | ||
|
|
||
| ## Benefits | ||
| 1. coreboot was using SkipMpInit=1 which will skip entire FSP CPU feature programming. | ||
| With proposed model, coreboot will make use of SkipMpInit=0 which will allow to run all | ||
| Silicon recommended CPU programming. | ||
| 2. CPU feature programming inside FSP will be more transparent than before as it’s using | ||
| coreboot interfaces to execute those programming. | ||
| 3. coreboot will have more control over running those feature programming as API optimization | ||
| handled by coreboot. | ||
|
|
||
| [PI_Spec_1_6]: http://www.uefi.org/sites/default/files/resources/PI_Spec_1_6.pdf |
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,135 @@ | ||
| # Sandy Bridge Raminit | ||
|
|
||
| ## Introduction | ||
|
|
||
| This documentation is intended to document the closed source memory controller | ||
| hardware for Intel 2nd Gen (Sandy Bride) and 3rd Gen (Ivy Bridge) core-i CPUs. | ||
|
|
||
| The memory initialization code has to take care of lots of duties: | ||
| 1. Selection of operating frequency | ||
| * Selection of common timings | ||
| * Applying frequency specific compensation values | ||
| * Read training of all populated channels | ||
| * Write training of all populated channels | ||
| * Adjusting delay networks of address and command signals | ||
| * DQS training of all populated channels | ||
| * Programming memory map | ||
| * Report DRAM configuration | ||
| * Error handling | ||
|
|
||
| ## Definitions | ||
| ```eval_rst | ||
| +---------+-------------------------------------------------------------------+------------+--------------+ | ||
| | Symbol | Description | Units | Valid region | | ||
| +=========+===================================================================+============+==============+ | ||
| | SCK | DRAM system clock cycle time | s | | | ||
| +---------+-------------------------------------------------------------------+------------+--------------+ | ||
| | tCK | DRAM system clock cycle time | 1/256th ns | | | ||
| +---------+-------------------------------------------------------------------+------------+--------------+ | ||
| | DCK | Data clock cycle time: The time between two SCK clock edges | s | | | ||
| +---------+-------------------------------------------------------------------+------------+--------------+ | ||
| | timA | IO phase: The phase delay of the IO signals | 1/64th DCK | [0-512) | | ||
| +---------+-------------------------------------------------------------------+------------+--------------+ | ||
| | SPD | Manufacturer set memory timings located on an EEPROM on every DIMM| bytes | | | ||
| +---------+-------------------------------------------------------------------+------------+--------------+ | ||
| | REFCK | Reference clock, either 100 or 133 | Mhz | 100, 133 | | ||
| +---------+-------------------------------------------------------------------+------------+--------------+ | ||
| | MULT | DRAM PLL multiplier | | [3-12] | | ||
| +---------+-------------------------------------------------------------------+------------+--------------+ | ||
| | XMP | Extreme Memory Profiles | | | | ||
| +---------+-------------------------------------------------------------------+------------+--------------+ | ||
| ``` | ||
|
|
||
| ## (Inoffical) register documentation | ||
| - [Sandy Bride - Register documentation](SandyBridge_registers.md) | ||
|
|
||
| ## Frequency selection | ||
| - [Sandy Bride - Frequency selection](Sandybridge_freq.md) | ||
|
|
||
| ## Read training | ||
| - [Sandy Bride - Read training](Sandybridge_read.md) | ||
|
|
||
| ### SMBIOS type 17 | ||
| The SMBIOS specification allows to report the memory configuration in use. | ||
| On GNU/Linux you can run `# dmidecode -t 17` to view it. | ||
| Example output of dmidecode: | ||
|
|
||
| ``` | ||
| Handle 0x0045, DMI type 17, 34 bytes | ||
| Memory Device | ||
| Array Handle: 0x0042 | ||
| Error Information Handle: Not Provided | ||
| Total Width: 64 bits | ||
| Data Width: 64 bits | ||
| Size: 8192 MB | ||
| Form Factor: DIMM | ||
| Set: None | ||
| Locator: ChannelB-DIMM0 | ||
| Bank Locator: BANK 2 | ||
| Type: DDR3 | ||
| Type Detail: Synchronous | ||
| Speed: 933 MHz | ||
| Manufacturer: 0420 | ||
| Serial Number: 00000000 | ||
| Asset Tag: 9876543210 | ||
| Part Number: F3-1866C9-8GSR | ||
| Rank: 2 | ||
| Configured Clock Speed: 933 MHz | ||
| ``` | ||
| The memory frequency printed by dmidecode is the active memory frequency. It's | ||
| **not** the double datarate and it's **not** the one encoded maximum frequency | ||
| in each DIMM's SPD. | ||
|
|
||
| > **Note:** This feature is available since coreboot 4.4 | ||
|
|
||
| ### MRC cache | ||
| The name *MRC cache* might be missleading as in case of *Native ram init* | ||
| there's no MRC, but for historical reasons it's still named *MRC cache*. | ||
| The MRC cache is part of flash memory that is writeable by coreboot. | ||
| At the end of the boot process coreboot will write the RAM training results to | ||
| flash for future use, as RAM training is time intensive. Storing the results | ||
| allows to boot faster on normal boot and allows to support S3 resume, | ||
| as the RAM training results can't be stored in RAM (you need to configure | ||
| the memory controller first to access RAM). | ||
|
|
||
| The MRC cache needs to be invalidated in case the memory configuration has | ||
| been changed. To detect a changed memory configuration the CRC16 of each DIMM | ||
| is stored to MRC cache. | ||
| > **Note:** This feature is available since coreboot 4.4 | ||
|
|
||
| ### Error handling | ||
| As of writing the only supported error handling is to disable the failing | ||
| channel and restart the memory training sequence. It's very likely to succeed, | ||
| as memory channels operate independent of each other. | ||
| In case no DIMM could be initilized coreboot will halt. The screen will stay | ||
| black until you power of your device. On some platforms there's additional | ||
| feedback to indicate such an event. | ||
|
|
||
| If you find `dmidecode -t 17` to report only half of the memory installed, | ||
| it's likely that a fatal memory init failure had happened. | ||
| It is assumed, that a working board with less physical memory, is much better, | ||
| than a board that doesn't boot at all. | ||
|
|
||
| > **Note:** This feature is available since coreboot 4.5 | ||
|
|
||
| Try to swap memory modules and or try to use a different vendor. If nothing | ||
| helps you could have a look at capter [Debuggin] or report a ticket | ||
| at [ticket.coreboot.org]. Please provide a full RAM init log, | ||
| that has been captured using EHCI debug. | ||
|
|
||
| To enable extensive RAM training logging enable the Kconfig option | ||
| `DEBUG_RAM_SETUP` | ||
| #### Lenovo Thinkpads | ||
| Lenovo Thinkpads do have an additional feature to indicate that RAM init has | ||
| failed and coreboot has died (it calls die() on fatal error, thus the name). | ||
| The Kconfig options | ||
| `H8_BEEP_ON_DEATH` | ||
| `H8_FLASH_LEDS_ON_DEATH` | ||
| enable blinking LEDs and enable a beep to indicate death. | ||
|
|
||
| > **Note:** This feature is available since coreboot 4.7 | ||
|
|
||
| ## Debugging | ||
| It's recommended to use an external debugger, such as serial or EHCI debug | ||
| dongle. In case of failing memory init the board might not boot at all, | ||
| preventing you from using CBMEM. |
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,165 @@ | ||
| # Frequency selection | ||
|
|
||
| ## Introduction | ||
| This chapter explains the frequency selection done on Sandybride and Ivybridge. | ||
|
|
||
| ## Definitions | ||
| ```eval_rst | ||
| +---------+-------------------------------------------------------------------+------------+--------------+ | ||
| | Symbol | Description | Units | Valid region | | ||
| +=========+===================================================================+============+==============+ | ||
| | SCK | DRAM system clock cycle time | s | | | ||
| +---------+-------------------------------------------------------------------+------------+--------------+ | ||
| | tCK | DRAM system clock cycle time | 1/256th ns | | | ||
| +---------+-------------------------------------------------------------------+------------+--------------+ | ||
| | DCK | Data clock cycle time: The time between two SCK clock edges | s | | | ||
| +---------+-------------------------------------------------------------------+------------+--------------+ | ||
| | SPD | Manufacturer set memory timings located on an EEPROM on every DIMM| bytes | | | ||
| +---------+-------------------------------------------------------------------+------------+--------------+ | ||
| | REFCK | Reference clock, either 100 or 133 | MHz | 100, 133 | | ||
| +---------+-------------------------------------------------------------------+------------+--------------+ | ||
| | MULT | DRAM PLL multiplier | | [3-12] | | ||
| +---------+-------------------------------------------------------------------+------------+--------------+ | ||
| | XMP | Extreme Memory Profiles | | | | ||
| +---------+-------------------------------------------------------------------+------------+--------------+ | ||
| ``` | ||
| ## SPD | ||
| The [SPD](https://de.wikipedia.org/wiki/Serial_Presence_Detect "Serial Presence Detect") | ||
| located on every DIMM is factory program with various timings. One of them | ||
| specifies the maximum clock frequency the DIMM should be used with. The | ||
| operating frequency is stores as fixed point value (tCK), rounded to the next | ||
| smallest supported operating frequency. Some | ||
| [SPD](https://de.wikipedia.org/wiki/Serial_Presence_Detect "Serial Presence Detect") | ||
| contains additional and optional | ||
| [XMP](https://de.wikipedia.org/wiki/Extreme_Memory_Profile "Extreme Memory Profile") | ||
| data, that stores so called "performance" modes, that advertises higher clock | ||
| frequencies. | ||
|
|
||
| ## XMP profiles | ||
| At time of writing coreboot's raminit is able to parse XMP profile 1 and 2. | ||
| Only **XMP profile 1** is being used in case it advertises: | ||
| * 1.5V operating voltage | ||
| * The channel's installed DIMM count doesn't exceed the XMP coded limit | ||
|
|
||
| In case the XMP profile doesn't fullfill those limits, the regular SPD will be | ||
| used. | ||
| > **Note:** XMP Profiles are supported since coreboot 4.4. | ||
|
|
||
| It is possible to ignore the max DIMM count limit set by XMP profiles. | ||
| By activating Kconfig option `NATIVE_RAMINIT_IGNORE_XMP_MAX_DIMMS` it is | ||
| possible to install two DIMMs per channel, even if XMP tells you not to do. | ||
|
|
||
| > **Note:** Ignoring XMP Profiles limit is supported since coreboot 4.7. | ||
|
|
||
| ## Soft fuses | ||
| Every board manufacturer does program "soft" fuses to indicate the maximum | ||
| DRAM frequency supported. However, those fuses don't set a limit in hardware | ||
| and thus are called "soft" fuses, as it is possible to ignore them. | ||
|
|
||
| > **Note:** Ignoring the fuses might cause system instability ! | ||
|
|
||
| On Sandy Bride *CAPID0_A* is being read, and on Ivybridge *CAPID0_B* is being | ||
| read. coreboot reads those registers and honors the limit in case the Kconfig | ||
| option `CONFIG_NATIVE_RAMINIT_IGNORE_MAX_MEM_FUSES` wasn't set. | ||
| Power users that want to let their RAM run at DRAM's "stock" frequency need to | ||
| enable the Kconfig symbol. | ||
|
|
||
| It is possible to override the soft fuses limit by using a board-specific | ||
| [devicetree](#devicetree) setting. | ||
|
|
||
| > **Note:** Ignoring max mem freq. fuses is supported since coreboot 4.7. | ||
|
|
||
| ## Hard fuses | ||
| "Hard" fuses are programmed by Intel and limit the maximum frequency that can | ||
| be used on a given CPU/board/chipset. At time of writing there's no register | ||
| to read this limit, before trying to set a given DRAM frequency. The memory PLL | ||
| won't lock, indicating that the chosen memory multiplier isn't available. In | ||
| this case coreboot tries the next smaller memory multiplier until the PLL will | ||
| lock. | ||
|
|
||
| ## Devicetree | ||
| The devicetree register `max_mem_clock_mhz` overrides the "soft" fuses set | ||
| by the board manufacturer. | ||
|
|
||
| By using this register it's possible to force a minimum operating frequency. | ||
|
|
||
| ## Reference clock | ||
| While Sandybride supports 133 MHz reference clock (REFCK), Ivy Bridge also | ||
| supports 100 MHz reference clock. The reference clock is multiplied by the DRAM | ||
| multiplier to select the DRAM frequency (SCK) by the following formula: | ||
|
|
||
| REFCK * MULT = 1 / DCK | ||
|
|
||
| > **Note:** Since coreboot 4.6 Ivy Bridge supports 100MHz REFCK. | ||
|
|
||
| ## Sandy Bride's supported frequencies | ||
| ```eval_rst | ||
| +------------+-----------+------------------+-------------------------+---------------+ | ||
| | SCK [Mhz] | DDR [Mhz] | Mutiplier (MULT) | Reference clock (REFCK) | Comment | | ||
| +============+===========+==================+=========================+===============+ | ||
| | 400 | DDR3-800 | 3 | 133 MHz | | | ||
| +------------+-----------+------------------+-------------------------+---------------+ | ||
| | 533 | DDR3-1066 | 4 | 133 MHz | | | ||
| +------------+-----------+------------------+-------------------------+---------------+ | ||
| | 666 | DDR3-1333 | 5 | 133 MHz | | | ||
| +------------+-----------+------------------+-------------------------+---------------+ | ||
| | 800 | DDR3-1600 | 6 | 133 MHz | | | ||
| +------------+-----------+------------------+-------------------------+---------------+ | ||
| | 933 | DDR3-1866 | 7 | 133 MHz | | | ||
| +------------+-----------+------------------+-------------------------+---------------+ | ||
| | 1066 | DDR3-2166 | 8 | 133 MHz | | | ||
| +------------+-----------+------------------+-------------------------+---------------+ | ||
| ``` | ||
|
|
||
| ## Ivybridge's supported frequencies | ||
| ```eval_rst | ||
| +------------+-----------+------------------+-------------------------+---------------+ | ||
| | SCK [Mhz] | DDR [Mhz] | Mutiplier (MULT) | Reference clock (REFCK) | Comment | | ||
| +============+===========+==================+=========================+===============+ | ||
| | 400 | DDR3-800 | 3 | 133 MHz | | | ||
| +------------+-----------+------------------+-------------------------+---------------+ | ||
| | 533 | DDR3-1066 | 4 | 133 MHz | | | ||
| +------------+-----------+------------------+-------------------------+---------------+ | ||
| | 666 | DDR3-1333 | 5 | 133 MHz | | | ||
| +------------+-----------+------------------+-------------------------+---------------+ | ||
| | 800 | DDR3-1600 | 6 | 133 MHz | | | ||
| +------------+-----------+------------------+-------------------------+---------------+ | ||
| | 933 | DDR3-1866 | 7 | 133 MHz | | | ||
| +------------+-----------+------------------+-------------------------+---------------+ | ||
| | 1066 | DDR3-2166 | 8 | 133 MHz | | | ||
| +------------+-----------+------------------+-------------------------+---------------+ | ||
| | 700 | DDR3-1400 | 7 | 100 MHz | '1 | | ||
| +------------+-----------+------------------+-------------------------+---------------+ | ||
| | 800 | DDR3-1600 | 8 | 100 MHz | '1 | | ||
| +------------+-----------+------------------+-------------------------+---------------+ | ||
| | 900 | DDR3-1800 | 9 | 100 MHz | '1 | | ||
| +------------+-----------+------------------+-------------------------+---------------+ | ||
| | 1000 | DDR3-2000 | 10 | 100 MHz | '1 | | ||
| +------------+-----------+------------------+-------------------------+---------------+ | ||
| | 1100 | DDR3-2200 | 11 | 100 MHz | '1 | | ||
| +------------+-----------+------------------+-------------------------+---------------+ | ||
| | 1200 | DDR3-2400 | 12 | 100 MHz | '1 | | ||
| +------------+-----------+------------------+-------------------------+---------------+ | ||
| ``` | ||
| > '1: since coreboot 4.6 | ||
|
|
||
| ## Multiplier selection | ||
| coreboot select the maximum frequency to operate at by the following formula: | ||
| ``` | ||
| if devicetree's max_mem_clock_mhz > 0: | ||
| freq_max := max_mem_clock_mhz | ||
| else: | ||
| freq_max := soft_fuse_max_mhz | ||
| for i in SPDs: | ||
| freq_max := MIN(freq_max, ddr_spd_max_mhz[i]) | ||
| ``` | ||
|
|
||
| As you can see, by using DIMMs with different maximum DRAM frequencies, the | ||
| slowest DIMMs' frequency will be selected, to prevent over-clocking it. | ||
|
|
||
| The selected frequency gives the PLL multiplier to operate at. In case the PLL | ||
| locks (see Take me to [Hard fuses](#hard_fuses)) the frequency will be used for | ||
| all DIMMs. At this point it's not possible to change the multiplier again, | ||
| until the system has been powered off. In case the PLL doesn't lock, the next | ||
| smaller multiplier will be used until a working multiplier will be found. |
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,153 @@ | ||
| # Read training | ||
|
|
||
| ## Introduction | ||
|
|
||
| This chapter explains the read training sequence done on Sandy Bride and | ||
| Ivy Bridge memory initialization. | ||
|
|
||
| Read training is done to compensate the skew between DQS and SCK and to find | ||
| the smallest supported roundtrip delay. | ||
|
|
||
| Every board does have a vendor depended routing topology, and can be equip | ||
| with any combination of DDR3 memory modules, that introduces different | ||
| skew between the memory lanes. With DDR3 a "Fly-By" routing topology | ||
| has been introduced, that makes the biggest part of DQS-SCK skew. | ||
| The memory code measures the actual skew and actives delay gates, | ||
| that will "compensate" the skew. | ||
|
|
||
| When in read training the DRAM and the controller are placed in a special mode. | ||
| On every read instruction the DRAM outputs a predefined pattern and the memory | ||
| controller samples the DQS after a given delay. As the pattern is known, the | ||
| actual delay of every lane can be measured. | ||
|
|
||
| The values programmed in read training effect DRAM-to-MC transfers only ! | ||
|
|
||
| ## Definitions | ||
| ```eval_rst | ||
| +---------+-------------------------------------------------------------------+------------+--------------+ | ||
| | Symbol | Description | Units | Valid region | | ||
| +=========+===================================================================+============+==============+ | ||
| | SCK | DRAM system clock cycle time | s | | | ||
| +---------+-------------------------------------------------------------------+------------+--------------+ | ||
| | tCK | DRAM system clock cycle time | 1/256th ns | | | ||
| +---------+-------------------------------------------------------------------+------------+--------------+ | ||
| | DCK | Data clock cycle time: The time between two SCK clock edges | s | | | ||
| +---------+-------------------------------------------------------------------+------------+--------------+ | ||
| | timA | IO phase: The phase delay of the IO signals | 1/64th DCK | [0-512) | | ||
| +---------+-------------------------------------------------------------------+------------+--------------+ | ||
| | SPD | Manufacturer set memory timings located on an EEPROM on every DIMM| bytes | | | ||
| +---------+-------------------------------------------------------------------+------------+--------------+ | ||
| | REFCK | Reference clock, either 100 or 133 | MHz | 100, 133 | | ||
| +---------+-------------------------------------------------------------------+------------+--------------+ | ||
| | MULT | DRAM PLL multiplier | | [3-12] | | ||
| +---------+-------------------------------------------------------------------+------------+--------------+ | ||
| | XMP | Extreme Memory Profiles | | | | ||
| +---------+-------------------------------------------------------------------+------------+--------------+ | ||
| | DQS | Data Strobe signal used to sample all lane's DQ signals | | | | ||
| +---------+-------------------------------------------------------------------+------------+--------------+ | ||
| ``` | ||
| ## Hardware | ||
| The hardware does have delay logic blocks that can delay the DQ / DQS of a | ||
| lane/rank by one or multiple clock cylces and it does have delay logic blocks | ||
| that can delay the signal by a multiple of 1/64th DCK per lane. | ||
|
|
||
| All delay values can be controlled via software by writing registers in the | ||
| MCHBAR. | ||
|
|
||
| ## IO phase | ||
|
|
||
| The IO phase can be adjusted in [0-512) * 1/64th DCK. Incrementing it by 64 is | ||
| the same as Incrementing IO delay by 1. | ||
|
|
||
| ## IO delay | ||
| Delays the DQ / DQS signal by one or multiple clock cycles. | ||
|
|
||
| ### Roundtrip time | ||
| The roundtrip time is the time the memory controller waits for data arraving | ||
| after a read has been issued. Due to clock-domain crossings, multiple | ||
| delay instances and phase interpolators, the signal runtime to DRAM and back | ||
| to memory controller defaults to 55 DCKs. The real roundtrip time has to be | ||
| measured. | ||
|
|
||
| After a read command has been issued, a counter counts down until zero has been | ||
| reached and activates the input buffers. | ||
|
|
||
| The following pictures shows the relationship between those three values. | ||
| The picture was generated from 16 IO delay values times 64 timA values. | ||
| The highest IO delay was set on the right-hand side, while the last block | ||
| on the left-hand side has zero IO delay. | ||
|
|
||
| #### roundtrip 55 DCKs | ||
| ![timA for lane0 - lane3, roundtrip 55][timA_lane0-3_rt55] | ||
|
|
||
| [timA_lane0-3_rt55]: timA_lane0-3_rt55.png | ||
|
|
||
| #### roundtrip 54 DCKs | ||
| ![timA for lane0 - lane3, roundtrip 54][timA_lane0-3_rt54] | ||
|
|
||
| [timA_lane0-3_rt54]: timA_lane0-3_rt54.png | ||
|
|
||
|
|
||
| #### roundtrip 53 DCKs | ||
| ![timA for lane0 - lane3, roundtrip 53][timA_lane0-3_rt53] | ||
|
|
||
| [timA_lane0-3_rt53]: timA_lane0-3_rt53.png | ||
|
|
||
| As you can see the signal has some jitter as every sample was taken in a | ||
| different loop iteration. The result register only contains a single bit per | ||
| lane. | ||
|
|
||
| ## Algorithm | ||
| ### Steps | ||
| The algorithm finds the roundtrip time, IO delay and IO phase. The IO phase | ||
| will be adjusted to match the falling edge of the preamble of each lane. | ||
| The roundtrip time is adjusted to an minimal value, that still includes the | ||
| preamble. | ||
|
|
||
| ### Synchronize to data phase | ||
|
|
||
| The first measurement done in read-leveling samples all DQS values for one | ||
| phase [0-64) * 1/64th DCK. It then searches for the middle of the low data | ||
| symbol and adjusts timA to the found phase and thus the following measurements | ||
| will be aligned to the low data symbol. | ||
| The code assumes that the initial roundtrip time causes the measurement to be | ||
| in the alternating pattern data phase. | ||
|
|
||
| ### Finding the preamble | ||
| After adjusting the IO phase to the middle of one data symbol the preamble will | ||
| be located. Unlike the data phase, which is an alternating pattern (010101...), | ||
| the preamble consists of two high data cycles. | ||
|
|
||
| The code decrements the IO delay/RTT and samples the DQS signal with timA | ||
| untouched. As it has been positioned in the middle of the data symbol, it'll | ||
| read as either "low" or "high". | ||
|
|
||
| If it's "low" we are still in the data phase. | ||
| If it's "high" we have found the preamble. | ||
|
|
||
| The roundtrip time and IO delay will be adjusted until all lanes are aligned. | ||
| The resulting IO delay is visible in the picture below. | ||
|
|
||
| **roundtrip time: 49 DCKs, IO delay (at blue point): 6 DCKs** | ||
| ![timA for lane0 - lane3, finding minimum roundtrip time][timA_lane0-3_discover_420x] | ||
|
|
||
| [timA_lane0-3_discover_420x]: timA_lane0-3_discover_420x.png | ||
|
|
||
| **Note: The sampled data has been shifted by timA. The preamble is now | ||
| in phase.** | ||
|
|
||
| ## Fine adjustment | ||
|
|
||
| As timA still points the middle of the data symbol an offset of 32 is added. | ||
| It now points the falling edge of the preamble. | ||
| The fine adjustment is to reduce errors introduced by jitter. The phase is | ||
| adjusted from `timA - 25` to `timA + 25` and the DQS signal is sampled 100 | ||
| times. The fine adjustment finds the middle of each rising edge (it's actual | ||
| the falling edge of the preamble) to get the final IO phase. You can see the | ||
| result in the picture below. | ||
|
|
||
| ![timA for lane0 - lane3, fine adjustment][timA_lane0-3_adjust_fine] | ||
|
|
||
| [timA_lane0-3_adjust_fine]: timA_lane0-3_adjust_fine.png | ||
|
|
||
| Lanes 0 - 2 will be adjusted by a phase of -10, while lane 3 is already correct. |
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,168 @@ | ||
| coreboot lesson 1 - Starting from scratch | ||
| ========================================= | ||
|
|
||
| From a fresh Ubuntu 16.04 or 18.04 install, here are all the steps required for | ||
| a very basic build: | ||
|
|
||
| Download, configure, and build coreboot | ||
| --------------------------------------- | ||
|
|
||
| ### Step 1 - Install tools and libraries needed for coreboot | ||
| $ sudo apt-get install -y bison build-essential curl flex git gnat-5 libncurses5-dev m4 zlib1g-dev | ||
|
|
||
| ### Step 2 - Download coreboot source tree | ||
| $ git clone https://review.coreboot.org/coreboot | ||
| $ cd coreboot | ||
|
|
||
| ### Step 3 - Build the coreboot toolchain | ||
| Please note that this can take a significant amount of time | ||
|
|
||
| $ make crossgcc-i386 CPUS=$(nproc) | ||
|
|
||
| Also note that you can possibly use your system toolchain, but the results are | ||
| not reproducible, and may have issues, so this is not recommended. See step 5 | ||
| to use your system toolchain. | ||
|
|
||
| ### Step 4 - Build the payload - coreinfo | ||
| $ make -C payloads/coreinfo olddefconfig | ||
| $ make -C payloads/coreinfo | ||
|
|
||
| ### Step 5 - Configure the build | ||
|
|
||
| * ##### Configure your mainboard | ||
| $ make menuconfig | ||
| select 'Mainboard' menu | ||
| Beside 'Mainboard vendor' should be '(Emulation)' | ||
| Beside 'Mainboard model' should be 'QEMU x86 i440fx/piix4' | ||
| select < Exit > | ||
| These should be the default selections, so if anything else was set, run | ||
| `make distclean` to remove your old config file and start over. | ||
|
|
||
| * ##### Optionally use your system toolchain (Again, not recommended) | ||
| select 'General Setup' menu | ||
| select 'Allow building with any toolchain' | ||
| select < Exit > | ||
|
|
||
| * ##### Select the payload | ||
| select 'Payload' menu | ||
| select 'Add a Payload' | ||
| choose 'An Elf executable payload' | ||
| select 'Payload path and filename' | ||
| enter 'payloads/coreinfo/build/coreinfo.elf' | ||
| select < Exit > | ||
| select < Exit > | ||
| select < Yes > | ||
|
|
||
| ##### check your configuration (optional step): | ||
|
|
||
| $ make savedefconfig | ||
| $ cat defconfig | ||
|
|
||
| There should only be two lines (or 3 if you're using the system toolchain): | ||
|
|
||
| CONFIG_PAYLOAD_ELF=y | ||
| CONFIG_PAYLOAD_FILE="payloads/coreinfo/build/coreinfo.elf" | ||
|
|
||
| ### Step 6 - build coreboot | ||
| $ make | ||
|
|
||
| At the end of the build, you should see: | ||
|
|
||
| Build emulation/qemu-i440fx (QEMU x86 i440fx/piix4) | ||
|
|
||
| This means your build was successful. The output from the build is in the build | ||
| directory. build/coreboot.rom is the full rom file. | ||
|
|
||
| Test the image using QEMU | ||
| ------------------------- | ||
|
|
||
| ### Step 7 - Install QEMU | ||
| $ sudo apt-get install -y qemu | ||
|
|
||
| ### Step 8 - Run QEMU | ||
| Start QEMU, and point it to the ROM you just built: | ||
|
|
||
| $ qemu-system-x86_64 -bios build/coreboot.rom -serial stdio | ||
|
|
||
| You should see the serial output of coreboot in the original console window, and | ||
| a new window will appear running the coreinfo payload. | ||
|
|
||
| Summary | ||
| ------- | ||
|
|
||
| ### Step 1 summary - Install tools and libraries needed for coreboot | ||
| You installed the minimum additional requirements for ubuntu to download and | ||
| build coreboot. Ubuntu already has most of the other tools that would be | ||
| required installed by default. | ||
|
|
||
| * `build-essential` is the basic tools for doing builds. It comes pre-installed | ||
| on some Ubuntu flavors, and not on others. | ||
| * `git` is needed to download coreboot from the coreboot git repository. | ||
| * `libncurses5-dev` is needed to build the menu for 'make menuconfig' | ||
| * `m4, bison, curl, flex, gnat-5, zlib1g-dev` are needed to build the coreboot | ||
| toolchain. | ||
|
|
||
| If you started with a different distribution, you might need to install many | ||
| other items which vary by distribution. | ||
|
|
||
| ### Step 2 summary - Download coreboot source tree | ||
| This will download a 'read-only' copy of the coreboot tree. This just means | ||
| that if you made changes to the coreboot tree, you couldn't immediately | ||
| contribute them back to the community. To pull a copy of coreboot that would | ||
| allow you to contribute back, you would first need to sign up for an account on | ||
| gerrit. | ||
|
|
||
| ### Step 3 summary - Build the coreboot toolchain. | ||
| This builds one of the coreboot cross-compiler toolchains for X86 platforms. | ||
| Because of the variability of compilers and the other required tools between | ||
| the various operating systems that coreboot can be built on, coreboot supplies | ||
| and uses its own cross-compiler toolchain to build the binaries that end up as | ||
| part of the coreboot ROM. The toolchain provided by the operating system (the | ||
| 'host toolchain') is used to build various tools that will run on the local | ||
| system during the build process. | ||
|
|
||
| ### Step 4 summary - Build the payload | ||
| To actually do anything useful with coreboot, you need to build a payload to | ||
| include in the rom. The idea behind coreboot is that it does the minimum amount | ||
| possible before passing control of the machine to a payload. There are various | ||
| payloads such as grub or SeaBIOS that are typically used to boot the operating | ||
| system. Instead, we used coreinfo, a small demonstration payload that allows the | ||
| user to look at various things such as memory and the contents of coreboot's | ||
| cbfs - the pieces that make up the coreboot rom. | ||
|
|
||
| ### Step 5 summary - Configure the build | ||
| This step configures coreboot's build options using the menuconfig interface to | ||
| Kconfig. Kconfig is the same configuration program used by the linux kernel. It | ||
| allows you to enable, disable, and change various values to control the coreboot | ||
| build process, including which mainboard(motherboard) to use, which toolchain to | ||
| use, and how the runtime debug console should be presented and saved. | ||
| Anytime you change mainboards in Kconfig, you should always run `make distclean` | ||
| before running `make menuconfig`. Due to the way that Kconfig works, values will | ||
| be kept from the previous mainboard if you skip the clean step. This leads to a | ||
| hybrid configuration which may or may not work as expected. | ||
|
|
||
| ### Step 6 summary - Build coreboot | ||
| You may notice that a number of other pieces are downloaded at the beginning of | ||
| the build process. These are the git submodules used in various coreboot builds. | ||
| By default, the BLOBS submodule is not downloaded. This git submodule may be | ||
| required for other builds for microcode or other binaries. To enable downloading | ||
| this submodule, select the option "Allow use of binary-only repository" in the | ||
| "General Setup" menu of Kconfig | ||
| This attempts to build the coreboot rom. The rom file itself ends up in the | ||
| build directory as 'coreboot.rom'. At the end of the build process, the build | ||
| displayed the contents of the rom file. | ||
|
|
||
| ### Step 7 summary - Install QEMU | ||
| QEMU is a processor emulator which we can use to show coreboot | ||
|
|
||
| ### Step 8 summary - Run QEMU | ||
| Here's the command line broken down: | ||
| * `qemu-system-x86_64` | ||
| This starts the QEMU emulator with the i440FX host PCI bridge and PIIX3 PCI to | ||
| ISA bridge. | ||
| * `-bios build/coreboot.rom` | ||
| Use the bios rom image that we just built. If this is left off, the standard | ||
| SeaBIOS image that comes with QEMU is used. | ||
| * `-serial stdio` | ||
| Send the serial output to the console. This allows you to view the coreboot | ||
| debug output. |
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,281 @@ | ||
| # coreboot Lesson 2: Submitting a patch to coreboot.org | ||
|
|
||
| ## Part 1: Setting up an account at coreboot.org | ||
|
|
||
| If you already have an account, skip to Part 2. | ||
|
|
||
| Otherwise, go to <https://review.coreboot.org> in your preferred web browser. | ||
| Select **Register** in the upper right corner. | ||
|
|
||
| Select the appropriate sign-in. For example, if you have a Google account, | ||
| select **Google OAuth2** (gerrit-oauth-provider plugin)".**Note:** Your | ||
| username for the account will be the username of the account you used to | ||
| sign-in with. (ex. your Google username). | ||
|
|
||
| ## Part 2a: Set up RSA Private/Public Key | ||
|
|
||
| If you prefer to use an HTTP password instead, skip to Part 2b. | ||
|
|
||
| For the most up-to-date instructions on how to set up SSH keys with Gerrit go to | ||
| <https://gerrit-documentation.storage.googleapis.com/Documentation/2.14.2/user-upload.html#configure_ssh)> | ||
| and follow the instructions there. Then, skip to Part 3. | ||
|
|
||
| Additionally, that section of the Web site provides explanation on starting | ||
| an ssh-agent, which may be particularly helpful for those who anticipate | ||
| frequently uploading changes. | ||
|
|
||
| If you instead prefer to have review.coreboot.org specific instructions, | ||
| follow the steps below. Note that this particular section may have the | ||
| most up-to-date instructions. | ||
|
|
||
| If you do not have an RSA key set up on your account already (as is the case | ||
| with a newly created account), follow the instructions below; otherwise, | ||
| doing so could overwrite an existing key. | ||
|
|
||
| In the upper right corner, select your name and click on **Settings**. | ||
| Select **SSH Public Keys** on the left-hand side. | ||
|
|
||
| In a terminal, run "ssh-keygen" and confirm the default path ".ssh/id_rsa". | ||
|
|
||
| Make a passphrase -- remember this phrase. It will be needed whenever you use | ||
| this RSA Public Key. **Note:** You might want to use a short password, or | ||
| forego the password altogether as you will be using it very often. | ||
|
|
||
| Open "id_rsa.pub", copy all contents and paste into the textbox under | ||
| "Add SSH Public Key" in the https://review.coreboot.org webpage. | ||
|
|
||
| ## Part 2b: Setting up an HTTP Password | ||
|
|
||
| Alternatively, instead of using SSH keys, you can use an HTTP password. To do so, | ||
| after you select your name and click on **Settings** on the left-hand side, rather | ||
| than selecting **SSH Public Keys**, select **HTTP Password**. | ||
|
|
||
| Click **Generate Password**. This should fill the "Password" box with a password. Copy | ||
| the password, and add the following to your $HOME/.netrc file: | ||
|
|
||
| machine review.coreboot.org login YourUserNameHere password YourPasswordHere | ||
|
|
||
| where YourUserNameHere is your username, and YourPasswordHere is the password you | ||
| just generated. | ||
|
|
||
| ## Part 3: Clone coreboot and configure it for submitting patches | ||
|
|
||
| Go to the **Projects** tab in the upper left corner and select **List**. | ||
| From the dropdown menu that appears, select "coreboot". | ||
|
|
||
| If you are using SSH keys, select **ssh** from the tabs under "Project coreboot" | ||
| and run the command that appears. This should prompt you for your id_rsa passphrase, | ||
| if you previously set one. | ||
|
|
||
| If you are using HTTP, instead, select **http** from the tabs under "Project coreboot" | ||
| and run the command that appears | ||
|
|
||
| After it finishes cloning, "cd coreboot" will take you into the local | ||
| git repository. Run "make gitconfig" to set up the hooks and configurations. | ||
| For example, you will be asked to run the following commands to set your | ||
| username and email. | ||
|
|
||
| git config --global user.name "Your Name" | ||
| git config --global user.email "Your Email" | ||
|
|
||
| ## Part 4: Submit a commit | ||
|
|
||
| An easy first commit to make is fixing existing checkpatch errors and warnings | ||
| in the source files. To see errors that are already present, build the files in | ||
| the repository by running 'make lint' in the coreboot directory. Alternatively, | ||
| if you want to run 'make lint' on a specific directory, run: | ||
|
|
||
| for file in $(git ls-files | grep src/amd/quadcore); do \ | ||
| util/lint/checkpatch.pl --file $file --terse; done | ||
|
|
||
| where <filepath> is the filepath of the directory (ex. src/cpu/amd/car). | ||
|
|
||
| Any changes made to files under the src directory are made locally, | ||
| and can be submitted for review. | ||
|
|
||
| Once you finish making your desired changes, use the command line to stage | ||
| and submit your changes. An alternative and potentially easier way to stage | ||
| and submit commits is to use git cola, a graphical user interface for git. For | ||
| instructions on how to do so, skip to Part 4b. | ||
|
|
||
| ## Part 4a: Using the command line to stage and submit a commit | ||
|
|
||
| To use the command line to stage a commit, run | ||
|
|
||
| git add <filename> | ||
|
|
||
| where `filename` is the name of your file. | ||
|
|
||
| To commit the change, run | ||
|
|
||
| git commit -s | ||
|
|
||
| **Note:** The -s adds a signed-off-by line by the committer. Your commit should be | ||
| signed off with your name and email (i.e. **Your Name** **<Your Email>**, based on | ||
| what you set with git config earlier). | ||
|
|
||
| Running git commit first checks for any errors and warnings using lint. If | ||
| there are any, you must go back and fix them before submitting your commit. | ||
| You can do so by making the necessary changes, and then staging your commit again. | ||
|
|
||
| When there are no errors or warnings, your default text editor will open. | ||
| This is where you will write your commit message. | ||
|
|
||
| The first line of your commit message is your commit summary. This is a brief | ||
| one-line description of what you changed in the files using the template | ||
| below: | ||
|
|
||
| <filepath>: Short description | ||
| *ex. cpu/amd/pi/00630F01: Fix checkpatch warnings and errors* | ||
| **Note:** It is good practice to use present tense in your descriptions | ||
| and do not punctuate your summary. | ||
|
|
||
| Then hit Enter. The next paragraph should be a more in-depth explanation of the | ||
| changes you've made to the files. Again, it is good practice to use present | ||
| tense. | ||
| *ex. Fix space prohibited between function name and open parenthesis, | ||
| line over 80 characters, unnecessary braces for single statement blocks, | ||
| space required before open brace errors and warnings.* | ||
|
|
||
| When you have finished writing your commit message, save and exit the text | ||
| editor. You have finished committing your change. If, after submitting your | ||
| commit, you wish to make changes to it, running "git commit --amend" allows | ||
| you to take back your commit and amend it. | ||
|
|
||
| When you are done with your commit, run 'git push' to push your commit to | ||
| coreboot.org. **Note:** To submit as a draft, use | ||
| 'git push origin HEAD:refs/drafts/master' Submitting as a draft means that | ||
| your commit will be on coreboot.org, but is only visible to those you add | ||
| as reviewers. | ||
|
|
||
| ## Part 4b: Using git cola to stage and submit a commit | ||
|
|
||
| If git cola is not installed on your machine, see | ||
| https://git-cola.github.io/downloads.html for download instructions. | ||
|
|
||
| After making some edits to src files, rather than run "git add," run | ||
| 'git cola' from the command line. You should see all of the files | ||
| edited under "Modified". | ||
|
|
||
| In the textbox labeled "Commit summary" provide a brief one-line | ||
| description of what you changed in the files according to the template | ||
| below: | ||
|
|
||
| <filepath>: Short description | ||
| *ex. cpu/amd/pi/00630F01: Fix checkpatch warnings and errors* | ||
| **Note:** It is good practice to use present tense in your descriptions | ||
| and do not punctuate your short description. | ||
|
|
||
| In the larger text box labeled 'Extended description...' provide a more | ||
| in-depth explanation of the changes you've made to the files. Again, it | ||
| is good practice to use present tense. | ||
| *ex. Fix space prohibited between function name and open parenthesis, | ||
| line over 80 characters, unnecessary braces for single statement blocks, | ||
| space required before open brace errors and warnings.* | ||
|
|
||
| Then press Enter two times to move the cursor to below your description. | ||
| To the left of the text boxes, there is an icon with an downward arrow. | ||
| Press the arrow and select "Sign Off." Make sure that you are signing off | ||
| with your name and email (i.e. **Your Name** **<Your Email>**, based on what | ||
| you set with git config earlier). | ||
|
|
||
| Now, review each of your changes and mark either individual changes or | ||
| an entire file as Ready to Commit by marking it as 'Staged'. To do | ||
| this, select one file from the 'Modified' list. If you only want to | ||
| submit particular changes from each file, then highlight the red and | ||
| green lines for your changes, right click and select 'Stage Selected | ||
| Lines'. Alternatively, if an entire file is ready to be committed, just | ||
| double click on the file under 'Modified' and it will be marked as | ||
| Staged. | ||
|
|
||
| Once the descriptions are done and all the edits you would like to | ||
| commit have been staged, press 'Commit' on the right of the text | ||
| boxes. | ||
|
|
||
| If the commit fails due to persisting errors, a text box will appear | ||
| showing the errors. You can correct these errors within 'git cola' by | ||
| right-clicking on the file in which the error occurred and selecting | ||
| 'Launch Diff Tool'. Make necessary corrections, close the Diff Tool and | ||
| 'Stage' the corrected file again. It might be necessary to refresh | ||
| 'git cola' in order for the file to be shown under 'Modified' again. | ||
| Note: Be sure to add any other changes that haven't already been | ||
| explained in the extended description. | ||
|
|
||
| When ready, select 'Commit' again. Once all errors have been satisfied | ||
| and the commit succeeds, move to the command line and run 'git push'. | ||
| **Note:** To submit as a draft, use 'git push origin HEAD:refs/drafts/master' | ||
| Submitting as a draft means that your commit will be on coreboot.org, but is | ||
| only visible to those you add as reviewers. | ||
|
|
||
| ## Part 5: Getting your commit reviewed | ||
|
|
||
| Your commits can now be seen on review.coreboot.org if you select “My” | ||
| and click on “Changes” and can be reviewed by others. Your code will | ||
| first be reviewed by build bot (Jenkins), which will either give you a warning | ||
| or verify a successful build; if so, your commit will receive a +1. Other | ||
| users may also give your commit +1. For a commit to be merged, it needs | ||
| to receive a +2.**Note:** A +1 and a +1 does not make a +2. Only certain users | ||
| can give a +2. | ||
|
|
||
| ## Part 6 (optional): bash-git-prompt | ||
|
|
||
| To help make it easier to understand the state of the git repository | ||
| without running 'git status' or 'git log', there is a way to make the | ||
| command line show the status of the repository at every point. This | ||
| is through bash-git-prompt. | ||
|
|
||
| Instructions for installing this are found at: | ||
| https://github.com/magicmonty/bash-git-prompt | ||
| **Note:** Feel free to search for different versions of git prompt, | ||
| as this one is specific to bash. | ||
|
|
||
| Alternatively, follow the instructions below: | ||
| Run the following two commands in the command line: | ||
|
|
||
| cd | ||
| git clone https://github.com/magicmonty/bash-git-prompt.git .bash-git-prompt --depth=1 | ||
|
|
||
| **Note:** cd will change your directory to your home directory, so the | ||
| git clone command will be run there. | ||
|
|
||
| Finally, open the ~/.bashrc file and append the following two lines: | ||
|
|
||
| GIT_PROMPT_ONLY_IN_REPO=1 | ||
| source ~/.bash-git-prompt/gitprompt.sh | ||
|
|
||
| Now, whenever you are in a git repository, it will continuously display | ||
| its state. | ||
|
|
||
| There also are additional configurations that you can change depending on your | ||
| preferences. If you wish to do so, look at the "All configs for .bashrc" section | ||
| on https://github.com/magicmonty/bash-git-prompt. Listed in that section are | ||
| various lines that you can copy, uncomment and add to your .bashrc file to | ||
| change the configurations. Example configurations include avoid fetching remote | ||
| status, and supporting versions of Git older than 1.7.10. | ||
|
|
||
| ## Appendix: Miscellaneous Advice | ||
|
|
||
| ### Updating a commit after running git push: | ||
|
|
||
| Suppose you would like to update a commit that has already been pushed to the | ||
| remote repository. If the commit you wish to update is the most recent | ||
| commit you have made, after making your desired changes, stage the files | ||
| (either using git add or in git cola), and amend the commit. To do so, | ||
| if you are using the command line, run "git commit --amend." If you are | ||
| using git cola, click on the gear icon located on the upper left side under | ||
| **Commit** and select **Amend Last Commit** in the drop down menu. Then, stage | ||
| the files you have changed, commit the changes, and run git push to push the | ||
| changes to the remote repository. Your change should be reflected in Gerrit as | ||
| a new patch set. | ||
|
|
||
| If, however, the commit you wish to update is not the most recent commit you | ||
| have made, you will first need to checkout that commit. To do so, find the | ||
| URL of the commit on <https://review.coreboot.org> and go to that page; if | ||
| the commit is one that you previously pushed, it can be found by selecting | ||
| **My** and then **Changes** in the upper left corner. To checkout this commit, | ||
| in the upper right corner, click on **Download**, and copy the command listed | ||
| next to checkout by clicking **Copy to clipboard**. Then, run the copied | ||
| command in your coreboot repository. Now, the last commit should be the most | ||
| recent commit to that patch; to update it, make your desired changes, stage | ||
| the files, then amend and push the commit using the instructions in the above | ||
| paragraph. |
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,225 @@ | ||
| # Makefile for Sphinx documentation | ||
| # | ||
|
|
||
| # You can set these variables from the command line. | ||
| SPHINXOPTS = | ||
| SPHINXBUILD = sphinx-build | ||
| PAPER = | ||
| BUILDDIR = _build | ||
|
|
||
| # Internal variables. | ||
| PAPEROPT_a4 = -D latex_paper_size=a4 | ||
| PAPEROPT_letter = -D latex_paper_size=letter | ||
| ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . | ||
| # the i18n builder cannot share the environment and doctrees with the others | ||
| I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . | ||
|
|
||
| .PHONY: help | ||
| help: | ||
| @echo "Please use \`make <target>' where <target> is one of" | ||
| @echo " html to make standalone HTML files" | ||
| @echo " dirhtml to make HTML files named index.html in directories" | ||
| @echo " singlehtml to make a single large HTML file" | ||
| @echo " pickle to make pickle files" | ||
| @echo " json to make JSON files" | ||
| @echo " htmlhelp to make HTML files and a HTML help project" | ||
| @echo " qthelp to make HTML files and a qthelp project" | ||
| @echo " applehelp to make an Apple Help Book" | ||
| @echo " devhelp to make HTML files and a Devhelp project" | ||
| @echo " epub to make an epub" | ||
| @echo " epub3 to make an epub3" | ||
| @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" | ||
| @echo " latexpdf to make LaTeX files and run them through pdflatex" | ||
| @echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx" | ||
| @echo " text to make text files" | ||
| @echo " man to make manual pages" | ||
| @echo " texinfo to make Texinfo files" | ||
| @echo " info to make Texinfo files and run them through makeinfo" | ||
| @echo " gettext to make PO message catalogs" | ||
| @echo " changes to make an overview of all changed/added/deprecated items" | ||
| @echo " xml to make Docutils-native XML files" | ||
| @echo " pseudoxml to make pseudoxml-XML files for display purposes" | ||
| @echo " linkcheck to check all external links for integrity" | ||
| @echo " doctest to run all doctests embedded in the documentation (if enabled)" | ||
| @echo " coverage to run coverage check of the documentation (if enabled)" | ||
| @echo " dummy to check syntax errors of document sources" | ||
|
|
||
| .PHONY: clean | ||
| clean: | ||
| rm -rf $(BUILDDIR)/* | ||
|
|
||
| .PHONY: html | ||
| html: | ||
| $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html | ||
| @echo | ||
| @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." | ||
|
|
||
| .PHONY: dirhtml | ||
| dirhtml: | ||
| $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml | ||
| @echo | ||
| @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." | ||
|
|
||
| .PHONY: singlehtml | ||
| singlehtml: | ||
| $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml | ||
| @echo | ||
| @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." | ||
|
|
||
| .PHONY: pickle | ||
| pickle: | ||
| $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle | ||
| @echo | ||
| @echo "Build finished; now you can process the pickle files." | ||
|
|
||
| .PHONY: json | ||
| json: | ||
| $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json | ||
| @echo | ||
| @echo "Build finished; now you can process the JSON files." | ||
|
|
||
| .PHONY: htmlhelp | ||
| htmlhelp: | ||
| $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp | ||
| @echo | ||
| @echo "Build finished; now you can run HTML Help Workshop with the" \ | ||
| ".hhp project file in $(BUILDDIR)/htmlhelp." | ||
|
|
||
| .PHONY: qthelp | ||
| qthelp: | ||
| $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp | ||
| @echo | ||
| @echo "Build finished; now you can run "qcollectiongenerator" with the" \ | ||
| ".qhcp project file in $(BUILDDIR)/qthelp, like this:" | ||
| @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/coreboot.qhcp" | ||
| @echo "To view the help file:" | ||
| @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/coreboot.qhc" | ||
|
|
||
| .PHONY: applehelp | ||
| applehelp: | ||
| $(SPHINXBUILD) -b applehelp $(ALLSPHINXOPTS) $(BUILDDIR)/applehelp | ||
| @echo | ||
| @echo "Build finished. The help book is in $(BUILDDIR)/applehelp." | ||
| @echo "N.B. You won't be able to view it unless you put it in" \ | ||
| "~/Library/Documentation/Help or install it in your application" \ | ||
| "bundle." | ||
|
|
||
| .PHONY: devhelp | ||
| devhelp: | ||
| $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp | ||
| @echo | ||
| @echo "Build finished." | ||
| @echo "To view the help file:" | ||
| @echo "# mkdir -p $$HOME/.local/share/devhelp/coreboot" | ||
| @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/coreboot" | ||
| @echo "# devhelp" | ||
|
|
||
| .PHONY: epub | ||
| epub: | ||
| $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub | ||
| @echo | ||
| @echo "Build finished. The epub file is in $(BUILDDIR)/epub." | ||
|
|
||
| .PHONY: epub3 | ||
| epub3: | ||
| $(SPHINXBUILD) -b epub3 $(ALLSPHINXOPTS) $(BUILDDIR)/epub3 | ||
| @echo | ||
| @echo "Build finished. The epub3 file is in $(BUILDDIR)/epub3." | ||
|
|
||
| .PHONY: latex | ||
| latex: | ||
| $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex | ||
| @echo | ||
| @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." | ||
| @echo "Run \`make' in that directory to run these through (pdf)latex" \ | ||
| "(use \`make latexpdf' here to do that automatically)." | ||
|
|
||
| .PHONY: latexpdf | ||
| latexpdf: | ||
| $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex | ||
| @echo "Running LaTeX files through pdflatex..." | ||
| $(MAKE) -C $(BUILDDIR)/latex all-pdf | ||
| @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." | ||
|
|
||
| .PHONY: latexpdfja | ||
| latexpdfja: | ||
| $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex | ||
| @echo "Running LaTeX files through platex and dvipdfmx..." | ||
| $(MAKE) -C $(BUILDDIR)/latex all-pdf-ja | ||
| @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." | ||
|
|
||
| .PHONY: text | ||
| text: | ||
| $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text | ||
| @echo | ||
| @echo "Build finished. The text files are in $(BUILDDIR)/text." | ||
|
|
||
| .PHONY: man | ||
| man: | ||
| $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man | ||
| @echo | ||
| @echo "Build finished. The manual pages are in $(BUILDDIR)/man." | ||
|
|
||
| .PHONY: texinfo | ||
| texinfo: | ||
| $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo | ||
| @echo | ||
| @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo." | ||
| @echo "Run \`make' in that directory to run these through makeinfo" \ | ||
| "(use \`make info' here to do that automatically)." | ||
|
|
||
| .PHONY: info | ||
| info: | ||
| $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo | ||
| @echo "Running Texinfo files through makeinfo..." | ||
| make -C $(BUILDDIR)/texinfo info | ||
| @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo." | ||
|
|
||
| .PHONY: gettext | ||
| gettext: | ||
| $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale | ||
| @echo | ||
| @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." | ||
|
|
||
| .PHONY: changes | ||
| changes: | ||
| $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes | ||
| @echo | ||
| @echo "The overview file is in $(BUILDDIR)/changes." | ||
|
|
||
| .PHONY: linkcheck | ||
| linkcheck: | ||
| $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck | ||
| @echo | ||
| @echo "Link check complete; look for any errors in the above output " \ | ||
| "or in $(BUILDDIR)/linkcheck/output.txt." | ||
|
|
||
| .PHONY: doctest | ||
| doctest: | ||
| $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest | ||
| @echo "Testing of doctests in the sources finished, look at the " \ | ||
| "results in $(BUILDDIR)/doctest/output.txt." | ||
|
|
||
| .PHONY: coverage | ||
| coverage: | ||
| $(SPHINXBUILD) -b coverage $(ALLSPHINXOPTS) $(BUILDDIR)/coverage | ||
| @echo "Testing of coverage in the sources finished, look at the " \ | ||
| "results in $(BUILDDIR)/coverage/python.txt." | ||
|
|
||
| .PHONY: xml | ||
| xml: | ||
| $(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml | ||
| @echo | ||
| @echo "Build finished. The XML files are in $(BUILDDIR)/xml." | ||
|
|
||
| .PHONY: pseudoxml | ||
| pseudoxml: | ||
| $(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml | ||
| @echo | ||
| @echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml." | ||
|
|
||
| .PHONY: dummy | ||
| dummy: | ||
| $(SPHINXBUILD) -b dummy $(ALLSPHINXOPTS) $(BUILDDIR)/dummy | ||
| @echo | ||
| @echo "Build finished. Dummy builder generates no files." |
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,19 @@ | ||
| /* | ||
| * Copyright 2018 Patrick Rudolph <siro@das-labor.org> | ||
| * | ||
| * licensed under CC-by 4.0 | ||
| */ | ||
|
|
||
| /* override table width restrictions */ | ||
| @media screen and (min-width: 767px) { | ||
| .wy-table-responsive table td { | ||
| /* !important prevents the common CSS stylesheets from overriding | ||
| this as on RTD they are loaded after this stylesheet */ | ||
| white-space: normal !important; | ||
| } | ||
|
|
||
| .wy-table-responsive { | ||
| overflow: visible !important; | ||
| } | ||
| } | ||
|
|
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,24 @@ | ||
| # ABI data consumption | ||
|
|
||
| This text describes the ABI coreboot presents to downstream users. Such | ||
| users are payloads and/or operating systems. Therefore, this text serves | ||
| at what can be relied on for downstream consumption. Anything not explicitly | ||
| listed as consumable is subject to change without notice. | ||
|
|
||
| ## Background and Usage | ||
|
|
||
| coreboot passes information to downstream users using coreboot tables. These | ||
| table definitions can be found in src/include/boot/coreboot_tables.h and | ||
| payloads/libpayload/include/coreboot_tables.h respectively within coreboot | ||
| and libpayload. One of the most vital and important pieces of information | ||
| found within these tables is the memory map of the system indicating | ||
| available and reserved memory. | ||
|
|
||
| In 2009 cbmem was added to coreboot. The "CBMEM high table memory manager" | ||
| serves a way for coreboot to bookkeep its own internal data. While some | ||
| of this data may be exposed through the coreboot tables the data structures | ||
| used to manage the data within the cbmem area is subject to change. | ||
|
|
||
| Provided the above, if one needs a piece of data exposed to the OS | ||
| or payload it should reside within the coreboot tables. If it isn't there | ||
| then a code change will be required to add it to the coreboot tables. |
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,189 @@ | ||
| # -*- coding: utf-8 -*- | ||
|
|
||
| # Add any paths that contain templates here, relative to this directory. | ||
| templates_path = ['_templates'] | ||
|
|
||
| # The suffix(es) of source filenames. | ||
| source_suffix = ['.md'] | ||
|
|
||
| # The master toctree document. | ||
| master_doc = 'index' | ||
|
|
||
| # General information about the project. | ||
| project = u'coreboot' | ||
| copyright = u'the coreboot project' | ||
| author = u'the coreboot project' | ||
|
|
||
| # The version info for the project you're documenting, acts as replacement for | ||
| # |version| and |release|, also used in various other places throughout the | ||
| # built documents. | ||
| # | ||
| # The short X.Y version. | ||
| version = u'4.7' | ||
| # The full version, including alpha/beta/rc tags. | ||
| release = u'4.7' # TODO: use 'git describe' | ||
|
|
||
| # The language for content autogenerated by Sphinx. Refer to documentation | ||
| # for a list of supported languages. | ||
| # | ||
| # This is also used if you do content translation via gettext catalogs. | ||
| # Usually you set "language" from the command line for these cases. | ||
| language = None | ||
|
|
||
| # List of patterns, relative to source directory, that match files and | ||
| # directories to ignore when looking for source files. | ||
| # This patterns also effect to html_static_path and html_extra_path | ||
| exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] | ||
|
|
||
| # The name of the Pygments (syntax highlighting) style to use. | ||
| pygments_style = 'sphinx' | ||
|
|
||
| # A list of ignored prefixes for module index sorting. | ||
| # modindex_common_prefix = [] | ||
|
|
||
| # If true, keep warnings as "system message" paragraphs in the built documents. | ||
| # keep_warnings = False | ||
|
|
||
| # If true, `todo` and `todoList` produce output, else they produce nothing. | ||
| todo_include_todos = False | ||
|
|
||
|
|
||
| # -- Options for HTML output ---------------------------------------------- | ||
|
|
||
| # The theme to use for HTML and HTML Help pages. See the documentation for | ||
| # a list of builtin themes. | ||
| # | ||
| html_theme = 'sphinx_rtd_theme' | ||
|
|
||
| # Add any paths that contain custom static files (such as style sheets) here, | ||
| # relative to this directory. They are copied after the builtin static files, | ||
| # so a file named "default.css" will overwrite the builtin "default.css". | ||
| html_static_path = ['_static'] | ||
|
|
||
| html_context = { | ||
| 'css_files': [ | ||
| '_static/theme_overrides.css', # override wide tables in RTD theme | ||
| ], | ||
| } | ||
|
|
||
| # Output file base name for HTML help builder. | ||
| htmlhelp_basename = 'corebootdoc' | ||
|
|
||
| # -- Options for LaTeX output --------------------------------------------- | ||
|
|
||
| latex_elements = { | ||
| # The paper size ('letterpaper' or 'a4paper'). | ||
| # | ||
| # 'papersize': 'letterpaper', | ||
|
|
||
| # The font size ('10pt', '11pt' or '12pt'). | ||
| # | ||
| # 'pointsize': '10pt', | ||
|
|
||
| # Additional stuff for the LaTeX preamble. | ||
| # | ||
| # 'preamble': '', | ||
|
|
||
| # Latex figure (float) alignment | ||
| # | ||
| # 'figure_align': 'htbp', | ||
| } | ||
|
|
||
| # Grouping the document tree into LaTeX files. List of tuples | ||
| # (source start file, target name, title, | ||
| # author, documentclass [howto, manual, or own class]). | ||
| latex_documents = [ | ||
| (master_doc, 'coreboot.tex', u'coreboot Documentation', | ||
| u'the coreboot project', 'manual'), | ||
| ] | ||
|
|
||
| # The name of an image file (relative to this directory) to place at the top of | ||
| # the title page. | ||
| # | ||
| # latex_logo = None | ||
|
|
||
| # For "manual" documents, if this is true, then toplevel headings are parts, | ||
| # not chapters. | ||
| # | ||
| # latex_use_parts = False | ||
|
|
||
| # If true, show page references after internal links. | ||
| # | ||
| # latex_show_pagerefs = False | ||
|
|
||
| # If true, show URL addresses after external links. | ||
| # | ||
| # latex_show_urls = False | ||
|
|
||
| # Documents to append as an appendix to all manuals. | ||
| # | ||
| # latex_appendices = [] | ||
|
|
||
| # It false, will not define \strong, \code, itleref, \crossref ... but only | ||
| # \sphinxstrong, ..., \sphinxtitleref, ... To help avoid clash with user added | ||
| # packages. | ||
| # | ||
| # latex_keep_old_macro_names = True | ||
|
|
||
| # If false, no module index is generated. | ||
| # | ||
| # latex_domain_indices = True | ||
|
|
||
|
|
||
| # -- Options for manual page output --------------------------------------- | ||
|
|
||
| # One entry per manual page. List of tuples | ||
| # (source start file, name, description, authors, manual section). | ||
| man_pages = [ | ||
| (master_doc, 'coreboot', u'coreboot Documentation', | ||
| [author], 1) | ||
| ] | ||
|
|
||
| # If true, show URL addresses after external links. | ||
| # | ||
| # man_show_urls = False | ||
|
|
||
|
|
||
| # -- Options for Texinfo output ------------------------------------------- | ||
|
|
||
| # Grouping the document tree into Texinfo files. List of tuples | ||
| # (source start file, target name, title, author, | ||
| # dir menu entry, description, category) | ||
| texinfo_documents = [ | ||
| (master_doc, 'coreboot', u'coreboot Documentation', | ||
| author, 'coreboot', 'One line description of project.', | ||
| 'Miscellaneous'), | ||
| ] | ||
|
|
||
| source_parsers = { | ||
| '.md': 'recommonmark.parser.CommonMarkParser', | ||
| } | ||
|
|
||
| # Documents to append as an appendix to all manuals. | ||
| # | ||
| # texinfo_appendices = [] | ||
|
|
||
| # If false, no module index is generated. | ||
| # | ||
| # texinfo_domain_indices = True | ||
|
|
||
| # How to display URL addresses: 'footnote', 'no', or 'inline'. | ||
| # | ||
| # texinfo_show_urls = 'footnote' | ||
|
|
||
| # If true, do not generate a @detailmenu in the "Top" node's menu. | ||
| # | ||
| # texinfo_no_detailmenu = False | ||
|
|
||
| enable_auto_toc_tree = True | ||
|
|
||
|
|
||
| def setup(app): | ||
| from recommonmark.transform import AutoStructify | ||
| app.add_config_value('recommonmark_config', { | ||
| 'enable_auto_toc_tree': True, | ||
| 'enable_auto_doc_ref': True, | ||
| 'enable_eval_rst': True, | ||
| 'url_resolver': lambda url: '/' + url | ||
| }, True) | ||
| app.add_transform(AutoStructify) |
