35599f9a66
Recommonmark has been deprecated since 2021 [1] and the last release was
over 3 years ago [2]. As per their announcement, Markedly Structured
Text (MyST) Parser [3] is the recommended replacement.
For the most part, the existing documentation is compatible with MyST,
as both parsers are built around the CommonMark flavor of Markdown. The
main difference that affects coreboot is how the Sphinx toctree is
generated. Recommonmark has a feature called auto_toc_tree, which
converts single level lists of references into a toctree:
* [Part 1: Starting from scratch](part1.md)
* [Part 2: Submitting a patch to coreboot.org](part2.md)
* [Part 3: Writing unit tests](part3.md)
* [Managing local additions](managing_local_additions.md)
* [Flashing firmware](flashing_firmware/index.md)
MyST Parser does not provide a replacement for this feature, meaning the
toctree must be defined manually. This is done using MyST's syntax for
Sphinx directives:
```{toctree}
:maxdepth: 1
Part 1: Starting from scratch <part1.md>
Part 2: Submitting a patch to coreboot.org <part2.md>
Part 3: Writing unit tests <part3.md>
Managing local additions <managing_local_additions.md>
Flashing firmware <flashing_firmware/index.md>
```
Internally, auto_toc_tree essentially converts lists of references into
the Sphinx toctree structure that the MyST syntax above more directly
represents.
The toctrees were converted to the MyST syntax using the following
command and Python script:
`find ./ -iname "*.md" | xargs -n 1 python conv_toctree.py`
```
import re
import sys
in_list = False
f = open(sys.argv[1])
lines = f.readlines()
f.close()
with open(sys.argv[1], "w") as f:
for line in lines:
match = re.match(r"^[-*+] \[(.*)\]\((.*)\)$", line)
if match is not None:
if not in_list:
in_list = True
f.write("```{toctree}\n")
f.write(":maxdepth: 1\n\n")
f.write(match.group(1) + " <" + match.group(2) + ">\n")
else:
if in_list:
f.write("```\n")
f.write(line)
in_list = False
if in_list:
f.write("```\n")
```
While this does add a little more work for creating the toctree, this
does give more control over exactly what goes into the toctree. For
instance, lists of links to external resources currently end up in the
toctree, but we may want to limit it to pages within coreboot.
This change does break rendering and navigation of the documentation in
applications that can render Markdown, such as Okular, Gitiles, or the
GitHub mirror. Assuming the docs are mainly intended to be viewed after
being rendered to doc.coreboot.org, this is probably not an issue in
practice.
Another difference is that MyST natively supports Markdown tables,
whereas with Recommonmark, tables had to be written in embedded rST [4].
However, MyST also supports embedded rST, so the existing tables can be
easily converted as the syntax is nearly identical.
These were converted using
`find ./ -iname "*.md" | xargs -n 1 sed -i "s/eval_rst/{eval-rst}/"`
Makefile.sphinx and conf.py were regenerated from scratch by running
`sphinx-quickstart` using the updated version of Sphinx, which removes a
lot of old commented out boilerplate. Any relevant changes coreboot had
made on top of the previous autogenerated versions of these files were
ported over to the newly generated file.
From some initial testing the generated webpages appear and function
identically to the existing documentation built with Recommonmark.
TEST: `make -C util/docker docker-build-docs` builds the documentation
successfully and the generated output renders properly when viewed in
a web browser.
[1] https://github.com/readthedocs/recommonmark/issues/221
[2] https://pypi.org/project/recommonmark/
[3] https://myst-parser.readthedocs.io/en/latest/
[4] https://doc.coreboot.org/getting_started/writing_documentation.html
Change-Id: I0837c1722fa56d25c9441ea218e943d8f3d9b804
Signed-off-by: Nicholas Chin <nic.c3.14@gmail.com>
Reviewed-on: https://review.coreboot.org/c/coreboot/+/73158
Reviewed-by: Matt DeVillier <matt.devillier@gmail.com>
Tested-by: build bot (Jenkins) <no-reply@coreboot.org>
6.4 KiB
Lenovo X200 / T400 / T500 / X301 common
These models are sold with either 8 MiB or 4 MiB flash chip. You can identify the chip in your machine through flashrom:
# flashrom -p internal
Note that this does not allow you to determine whether the chip is in a SOIC-8 or a SOIC-16 package.
Installing with ME firmware
To install coreboot and keep ME working, you don't need to do anything special
with the flash descriptor. Only flash the bios region externally and don't
touch any other regions:
# flashrom -p YOUR_PROGRAMMER -w coreboot.rom --ifd -i bios
Installing without ME firmware
.. Note::
**ThinkPad R500** has slightly different flash layout (it doesn't have
``gbe`` region), so the process would be a little different for that model.
On Montevina machines it's possible to disable ME and remove its firmware from
SPI flash by modifying the flash descriptor. This also makes it possible to use
the flash region the ME used for bios region, allowing for much larger
payloads.
First of all create a backup of your ROM with an external programmer:
# flashrom -p YOUR_PROGRAMMER -r backup.rom
Then, split the IFD regions into separate files with ifdtool. You will need
flashregion_3_gbe.bin later.
$ ifdtool -x backup.rom
Now you need to patch the flash descriptor. You can either modify the one from your backup with ifdtool, or use one from the coreboot repository.
Modifying flash descriptor using ifdtool
Pick the layout according to your chip size from the table below and save it to
the new_layout.txt file:
+---------------------------+---------------------------+---------------------------+
| 4 MiB chip | 8 MiB chip | 16 MiB chip |
+===========================+===========================+===========================+
| .. code-block:: none | .. code-block:: none | .. code-block:: none |
| | | |
| 00000000:00000fff fd | 00000000:00000fff fd | 00000000:00000fff fd |
| 00001000:00002fff gbe | 00001000:00002fff gbe | 00001000:00002fff gbe |
| 00003000:003fffff bios | 00003000:007fffff bios | 00003000:00ffffff bios |
| 00fff000:00000fff pd | 00fff000:00000fff pd | 00fff000:00000fff pd |
| 00fff000:00000fff me | 00fff000:00000fff me | 00fff000:00000fff me |
+---------------------------+---------------------------+---------------------------+
The last two lines define pd and me regions of negative size. This way
ifdtool will mark those as unused.
Update regions in the flash descrpitor (it was extracted previously with
ifdtool -x):
$ ifdtool -n new_layout.txt flashregion_0_flashdescriptor.bin
Set MeDisable bit in ICH0 and MCH0 straps:
$ ifdtool -M 1 flashregion_0_flashdescriptor.bin.new
Delete previous descriptors and rename the final one:
$ rm flashregion_0_flashdescriptor.bin
$ rm flashregion_0_flashdescriptor.bin.new
$ mv flashregion_0_flashdescriptor.bin.new.new flashregion_0_flashdescriptor.bin
Continue to the Configuring coreboot section.
Using checked-in flash descriptor via bincfg
There is a copy of an X200's flash descriptor checked into the coreboot
repository. It is supposed to work for the T400/T500 as well. The descriptor
can be converted back to its binary form using a tool called bincfg. Go
to util/bincfg and build it:
$ cd util/bincfg
$ make
If your flash is not 8 MiB, you need to change values of flcomp_density1 and
flreg1_limit in the ifd-x200.set file according to following table:
+-----------------+-------+-------+--------+
| | 4 MiB | 8 MiB | 16 MiB |
+=================+=======+=======+========+
| flcomp_density1 | 0x3 | 0x4 | 0x5 |
+-----------------+-------+-------+--------+
| flreg1_limit | 0x3ff | 0x7ff | 0xfff |
+-----------------+-------+-------+--------+
Then convert the flash descriptor:
$ make gen-ifd-x200
It will be saved to the flashregion_0_fd.bin file.
Configuring coreboot
Now configure coreboot. You need to select correct chip size and specify paths to flash descriptor and gbe dump.
Mainboard --->
ROM chip size (8192 KB (8 MB)) # According to your chip
(0x7fd000) Size of CBFS filesystem in ROM # or 0x3fd000 for 4 MiB chip / 0xffd000 for 16 MiB chip
Chipset --->
[*] Add Intel descriptor.bin file
# Note: if you used bincfg, specify path to generated util/bincfg/flashregion_0_fd.bin
(/path/to/flashregion_0_flashdescriptor.bin) Path and filename of the descriptor.bin file
[*] Add gigabit ethernet configuration
(/path/to/flashregion_3_gbe.bin) Path to gigabit ethernet configuration
Then build coreboot and flash whole build/coreboot.rom to the chip.
Flash layout
The flash layouts of the OEM firmware are as follows:
+---------------------------------+---------------------------------+
| 4 MiB chip | 8 MiB chip |
+=================================+=================================+
| .. code-block:: none | .. code-block:: none |
| | |
| 00000000:00000fff fd | 00000000:00000fff fd |
| 00001000:001f5fff me | 00001000:005f5fff me |
| 001f6000:001f7fff gbe | 005f6000:005f7fff gbe |
| 001f8000:001fffff pd | 005f8000:005fffff pd |
| 00200000:003fffff bios | 00600000:007fffff bios |
| 00290000:002affff ec | 00690000:006affff ec |
| 003e0000:003fffff bootblock | 007e0000:007fffff bootblock |
+---------------------------------+---------------------------------+
On each boot of vendor BIOS ec area in flash is checked for having firmware
there, and if there is one, it proceedes to update firmware on H8S/2116 (when
both external power and main battery are attached). Once update is performed,
first 64 KiB of ec area is erased. Visit
thinkpad-ec repository to learn
more about how to extract EC firmware from vendor updates.