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.1 KiB
Acer G43T-AM3
The Acer G43T-AM3 is a microATX-sized desktop board. It was used for the Acer models Aspire M3800, Aspire M5800 and possibly more.
Technology
+------------------+--------------------------------------------------+
| Northbridge | Intel G43 (called x4x in coreboot code) |
+------------------+--------------------------------------------------+
| Southbridge | Intel ICH10R (called i82801jx in coreboot code) |
+------------------+--------------------------------------------------+
| CPU socket | LGA 775 |
+------------------+--------------------------------------------------+
| RAM | 4 x DDR3-1066 |
+------------------+--------------------------------------------------+
| SuperIO | ITE IT8720F |
+------------------+--------------------------------------------------+
| Audio | Realtek ALC888S |
+------------------+--------------------------------------------------+
| Network | Intel 82567V-2 Gigabit Ethernet |
+------------------+--------------------------------------------------+
There is no serial port. Serial console output is possible by soldering to a point at the corresponding Super I/O pin and patching the mainboard-specific code accordingly.
Status
Working
Tests were done with SeaBIOS 1.14.0 and slackware64-live from 2019-07-12 (linux-4.19.50).
- Intel Core 2 processors at up to FSB 1333
- All four DIMM slots at 1066 MHz (tested 2x2GB + 2x4GB)
- Integrated graphics (libgfxinit)
- HDMI and VGA ports
- Both PCI slots
- Both PCI-e slots
- USB (8 internal, 4 external)
- All six SATA ports
- Onboard Ethernet
- Onboard sound card with output on the rear stereo connector
- PS/2 mouse and keyboard
- With SeaBIOS, use CONFIG_SEABIOS_PS2_TIMEOUT, tested: 500
- With FILO it works without further settings
- Temperature readings from the Super I/O (including the CPU temperature via PECI)
- Super I/O EC automatic fan control
- S3 suspend/resume
- Poweroff
Not working
- DDR3 memory with 512Mx8 chips (G43 limitation)
- 4x4GB of DDR3 memory (works, but showed a single bit error within one pass of Memtest86+ 5.01)
- Super I/O voltage reading conversions
Untested
- Other audio jacks or the front panel header
- S/PDIF output
- On-board Firewire
- Wake-on-LAN
Flashing coreboot
+-------------------+---------------------+
| Type | Value |
+===================+=====================+
| Socketed flash | No |
+-------------------+---------------------+
| Model | Macronix MX25L1605D |
+-------------------+---------------------+
| Size | 2 MiB |
+-------------------+---------------------+
| Package | 8-Pin SOP |
+-------------------+---------------------+
| Write protection | No |
+-------------------+---------------------+
| Dual BIOS feature | No |
+-------------------+---------------------+
| Internal flashing | Yes |
+-------------------+---------------------+
The flash is divided into the following regions, as obtained with
ifdtool -f rom.layout backup.rom:
00000000:00001fff fd
00100000:001fffff bios
00006000:000fffff me
00002000:00005fff gbe
In general, flashing is possible internally and from an external header. It
might be necessary to specify the chip type; MX25L1605D/MX25L1608D/MX25L1673E
is the correct one, not MX25L1605.
Internal flashing
Internal access to the flash chip is unrestricted. When installing coreboot,
only the BIOS region should be updated by passing the --ifd and -i bios
parameters to flashrom. A full backup is advisable.
Here is an example:
$ sudo flashrom \
-p internal \
-c "MX25L1605D/MX25L1608D/MX25L1673E" \
-r backup.rom
$ sudo flashrom \
-p internal \
-c "MX25L1605D/MX25L1608D/MX25L1673E" \
--ifd -i bios \
-w coreboot.rom
In addition to the information here, please see the
:doc:`../../tutorial/flashing_firmware/index`.
External flashing
The SPI flash chip on this board can be flashed externally through the SPI_ROM1 header while the board is off and disconnected from power. There seems to be a diode that prevents the external programmer from powering the whole board.
The signal assignment on the header is identical to the pinout of the flash chip. The pinout diagram below is valid when the PCI slots are on the left and the CPU is on the right. Note that HOLD# and WP# must be pulled high (to VCC) to be able to flash the chip.
+---+---+
SPI_CSn <- | x | x | -> VCC
+---+---+
SPI_MISO <- | x | x | -> HOLDn
+---+---+
WPn <- | x | x | -> SPI_CLK
+---+---+
GND <- | x | x | -> SPI_MOSI
+---+---+
Intel Management Engine
The Intel Management Engine (ME) can be disabled by setting the ME_DISABLE jumper on the board. It pulls GPIO33 on the ICH10 low, causing the "Flash Descriptor Security Override Strap" to be set. This disables the ME and also disables any read/write restrictions to the flash chip that may be set in the Intel Flash Descriptor (IFD) (none on this board). Note that changing this jumper only comes into effect when starting the board from a shutdown or suspend state, not during normal operation.
To completely remove the ME blob from the flash image and to decrease the size
of the ME region, thus increasing the size of the BIOS region, me_cleaner can
be used with the -t, -r and -S options.
Fan control
There are two fan connectors that can be controlled individually. CPU_FAN
can only control a fan by a PWM signal and SYS_FAN only by voltage. See
the mainboard's devicetree.cb file for how coreboot configures the Super
I/O to control the fans.
Variants
Various similar mainboards exist, like the Acer Q45T-AM. During a discussion in #coreboot on IRC, ECS was suspected to be the original designer of this series of mainboards. They have similar models such as the ECS G43T-WM.