Help:Laptop page guidelines

This article unifies the style and layout of all laptop pages and introduces guidelines and
standards
to ensure laptop pages are and remain high quality. This ensures that pages do not devolve to just dumps of the
lspci
and
lsusb
output or a user's personal notes about their device.
General
Add an
appropriate category
to the page, for example
Category:Dell
. If there is no category for your vendor, create one.
The page name should be "Vendor model number", for example "Lenovo ThinkPad X1 Carbon".
Do
not
create a redirect which just omits the vendor name, for example "X1 Carbon" or "ThinkPad X1 Carbon".
Tip
If you do not know what your page should look like,
Dell Latitude 3500
and
Lenovo ThinkPad T14/T14s (Intel) Gen 2
are example pages which follow these guidelines.
Do not duplicate content from the general
Laptop
guidelines. A section just containing e.g "The webcam of this device works fine" will not help anyone, so do not add a section if there are no special instructions for it. Also avoid mentioning desktop environment or window manager specific content. This also applies to other things that are documented in the ArchWiki, e.g do not include instructions on how to flash the archiso to a USB-stick, just link to the page containing the instructions. This will result in less maintenance required.
Be thorough and detailed when describing any
issues
that the laptop is affected by. Do provide links to reports by other users having the same issues and other appropriate sources.
Adding hardware information
Warning
Keep all of the lines as short as possible because a wide table is hard to read and makes the page look disorganized.
Make sure the table is above the
preface or introduction
or the position of the table will change.
Add a table with
class="wikitable archwiki-table-laptop"
at the very beginning of the page with the following columns:
Hardware
It should contain the short name of the part, like "Bluetooth" or "Fingerprint reader".
Only append the name of the vendor to the part if there are more than one. A common example for this would be more than one GPU (see table below).
Consider running
hardware probe
to make the full set of hardware known to the
Linux Hardware Database
.
PCI/USB ID
It should contain the PCI or USB ID of the part, if available. This is important because some laptops may have varying hardware.
lsusb
shows the USB ID by default, but
lspci
must be run with
-nn
in order to obtain the PCI ID of devices—by default it shows
bus
:
device
.
function
.
If there is a PCI/USB ID without a name, consider contributing the part to the
PCI ID repository
or the
USB ID repository
respectively.
If there is no applicable PCI/USB ID for this device, do not use
Template:-
or dashes but simply leave the cell empty. An accepted alternative is putting "PS/2" or "I2C" without an ID (e.g. PS/2 devices cannot be enumerated like PCI or USB ones, only a "device name" is reported by ACPI).
Working?
It should contain
Template:Yes
or
Template:No
. If these are not applicable, use
Template:Y
and a fitting,
short
description of its status, like "Untested" or "Partial".
Use "Partial" when the part still does not work correctly with applied modifications.
Use
Template:Yes
even if you need to install an external driver or if configuring this with
device-specific
parameters enhances its functionality.
Note
If any part requires special instructions, you are encouraged to add a section just for this part. Unfortunately it clutters the page when using certain
standard sections
, so
avoid
using
Known issues
,
Tips and Tricks
and
Troubleshooting
.
Kernel module information
Do not put kernel module information into the table or a separate section for the part. This is usually pointless because there is only one module for this part. This does not apply if there are different drivers to choose from, but this has to be specified in the section for the part, not the table.
Example table
The following code will be displayed like the example on the right:
{| class="wikitable archwiki-table-laptop"
! Hardware !! PCI/USB ID !! Working?
|-
| Wi-Fi || {{ic|14e4:1aaa}} || {{Yes}}
|-
| Bluetooth || {{ic|8087:2bbb}} || {{Yes}}
|-
| Webcam || {{ic|046d:3ccc}} || {{No}}
|-
| GPU (Intel) || {{ic|8086:4ddd}} || {{Yes}}
|-
| GPU (NVIDIA) || {{ic|10de:5eee}} || {{No}}
|-
| Other part || {{ic|056a:6fff}} || {{Y|Untested}}
|}
Hardware
PCI/USB ID
Working?
Wi-Fi
14e4:1aaa
Yes
Bluetooth
8087:2bbb
Yes
Webcam
046d:3ccc
No
GPU (Intel)
8086:4ddd
Yes
GPU (NVIDIA)
10de:5eee
No
Other part
056a:6fff
Untested
List of common parts
Wi-Fi
Bluetooth
Webcam
Ethernet
GPU
Touchpad
Keyboard
TPM
Fingerprint reader
SD-card reader
Speakers
Microphone
Ambient light sensor
Note
If any of the ports (USB, HDMI, Ethernet), or critical hardware like fan-control, do not work out of the box, add a section for it and also add it to the table. Make sure to not include any desktop environment/window manager specific instructions. The sections should go between the "Firmware" and "Function keys" section.
Do not put "Fn keys", "Suspend"/"Hibernate" or "Power management" into the table.
Related articles
Since all laptop pages should contain a hardware table floating right, the use of
Template:Related
as described in
Help:Style#Related articles box
is substituted with using
only
the
"See also" section
or direct links inside relevant sections to avoid right-floating elements clashing with each others.
"Installation" section
This section should contain information that is necessary to install Arch Linux on this device. This includes, but is not limited to:
Kernel parameters
Important firmware settings (also see
#"Firmware" section
)
This does not include obvious settings like changing the boot device.
It is encouraged to link to relevant posts in the forums, like
this example post
focusing on an issue with Dell devices.
If a device needs a special firmware for installation, for example an
AUR
package for network connectivity, make the requirement prominent.
Omit this section if there are no quirks that need to be addressed.
"Accessibility" section
Warning
Adding this section to a laptop page is mandatory. It is not optional since the information is essential for users with disabilities to decide if it is possible to install Arch Linux on such a device without help.
To help disabled users install Arch Linux on the device, add some accessibility info. This includes, but is not limited to:
The appearance of the firmware. Consider settings required to change in order to boot an official Arch Linux install medium.
Newer firmware interfaces may be more difficult to parse with OCR software on phones, which blind users frequently use as daily tools. If there is an option to revert the default design to the "classic" design, add instructions for it.
Some firmware even require the usage of a mouse and/or is overly complex. If it is not possible to change settings without eyesight, add a note describing this. For example:
Note
Blind users should request the help of a sighted person to change firmware settings.
Some firmware interfaces may use radio buttons and tightly packed menus extensively, which might prevent users with Parkinson's disease from changing certain settings.
Refer to a relevant section of the official manual (see
#"See also" section
) for your device that contains a list of all the shortcuts needed to navigate the firmware and to trigger certain actions, like changing the boot device.
If such a manual does not exist, you can add a list to the section instead.
Some devices may have a diagnostic LED, which visualizes beep codes. This is useful for deaf users.
Add a note if there is only a diagnostic LED, but no beep codes.
Tip
If you do not know what that section should look like, see good examples:
Framework Desktop#Accessibility
System76 Oryx Pro#Accessibility
"Firmware" section
The page should contain a short note describing the
fwupd
support for this device.
A page should include a firmware section, when there is special behavior the user should be aware of. This includes, but is not limited to the following:
Certain optional firmware settings that can enhance the compatibility of this device
Firmware quirks that can impact the installation
Lack of a
UEFI
. What booting method does the device use and can UEFI be added to the existing boot process?
Secure Boot
information
Do custom keys work well on this device?
Are there any special firmware settings one needs to change for this?
Are there any other specialties the user should be aware of?
Does the firmware store recovery images or logs in a special path? This is important to know when choosing the size of an
EFI system partition
.
Sometimes it is crucial to update the firmware because it fixes critical bugs. If there are any important firmware updates, mention it in this section.
Lack of an
ACPI
or if the ACPI is not supported in Linux.
"Function keys" section
Note
There are probably unmarked keybinds. In the worst case you may hit an unmarked keybind that emits
XF86Sleep
, suspending your device and scaring you because the screen suddenly gets dark, or one that emits
XF86RFKill
. Both possibilities are mildly disruptive, but not dangerous.
Hold down
Fn
and press every key on your keyboard, while capturing the result as described in
#Capturing function keys
.
Add a table with the following columns:
Note
Remember to follow the
style guidelines for keyboard keys
.
Key
The key one needs to press. They usually start with
Fn
.
Visible?
Use
Template:Yes
or
Template:No
, depending on whether tools like
xev
can see this key.
Marked?
Use
Template:Yes
or
Template:No
, depending on whether the physical key has a symbol on it, which describes its function.
Effect
Usually, function keys emit a key or the firmware does something when the key is pressed.
Specify the
X keyboard extension symbol
when a key is emitted, like
XF86MonBrightnessDown
.
A key may have a special effect which should be mentioned, like
hard blocking
network devices.
Do not add desktop environment or window manager specific instructions.
There are some keys that will be bound by systemd-logind by default, which should be marked—see the
example table
below.
Capturing function keys
It is possible to capture function keys using
xev
(
xorg-xev
) or
wev
(
wev
). There is also
libinput debug-events
but since many Wayland compositors use
xkbcommon
, the Xorg-specific names are preferred.
Desktop environments
and even some
window managers
may come with a default configuration which swallows all the function keys, since it is handling them by itself. Temporarily use a minimal window manager like
Openbox
to capture the keys if this is the case.
Some function keys (such as
XF86Sleep
) may be bound to
systemd-logind
, which means they can not be captured with any tool by default. Use
systemd-inhibit
to temporarily suspend the handling of certain keys:
# systemd-inhibit --what=handle-suspend-key sleep 1h
As long as this command is running,
systemd-logind
will ignore these button presses and properly capturing the button press is possible.
Note
If the key is still invisible it might be firmware-bound or a kernel module is handling it.
Example table
Key
Visible?
1
Marked?
2
Effect
Fn+Esc
No
Yes
Toggles Fn lock
Fn+F1
Yes
Yes
XF86AudioMute
Fn+F2
Yes
Yes
XF86AudioLowerVolume
Fn+F3
Yes
3
Yes
XF86Sleep
...
No
No
Fitting description
The key is visible to
xev
and similar tools.
The physical key has a symbol on it, which describes its function.
systemd-logind handles this by default.
"See also" section
This section should contain helpful links which include, but is not limited to the following:
Related other external wiki pages, such as the
ThinkWiki
.
A link to a page in the
Ubuntu Certified
catalogue, which can be a useful source for PCI/USB IDs and hardware variations.
A link to
hardware probe
search for model in question on the
Linux Hardware Database
, which provides information about compatibility and PCI/USB IDs.
Official manual pages provided by the manufacturer, which can be helpful when debugging firmware issues.