git: 654c02af03 - main - handbook/x11: refactor
- Go to: [ bottom of page ] [ top of archives ] [ this month ]
Date: Mon, 14 Jul 2025 13:24:56 UTC
The branch main has been updated by ziaee:
URL: https://cgit.FreeBSD.org/doc/commit/?id=654c02af03202616767f7c38d69298aab841c851
commit 654c02af03202616767f7c38d69298aab841c851
Author: Alexander Ziaee <ziaee@FreeBSD.org>
AuthorDate: 2024-12-19 16:45:33 +0000
Commit: Alexander Ziaee <ziaee@FreeBSD.org>
CommitDate: 2025-07-14 13:22:48 +0000
handbook/x11: refactor
General:
+ Add many search keywords to tags
+ Add detail to subsections, and an abstract
+ Add drm and kms to glossary
Graphics:
+ drivers logically come first, and explain why we have to install them
+ intel graphics is not always integrated and not always cards
+ add graphics to keywords
+ refactor for flow
+ add markup for linking
Xorg:
+ add an overview subchapter
+ disambiguate Xorg server/X Window System
+ xorg-ins should directly precede xorg-cfg
+ try to tersely explain why at more points
+ autoconfiguration should not be a warning in a previous chapter,
it needs to be part of the introduction to configuration
+ explain libinput, and atomic configuration via xinput and setxkbmap
+ explain why we have xf86-input drivers, there are good use cases
Fonts:
+ sort and sync fonts intro
+ truetype fonts are what most users are looking for, for screens.
+ postscript fonts are specialized for typography, for printing.
+ therefore, move truetype first, and explain the difference.
+ add fonts to keywords
Outstanding:
+ hybrid graphics
+ the fonts section really needs more love, the X freetype module does
not actually exist for many years.
+ xorg configuration => see desktop environments
+ ...the whole thing could still be a little clearer
+ mention fwget
+ consider moving driver installation to basics
Discussed with: bcr, carlavilla, vishwin, Jim Brown
Differential Revision: https://reviews.freebsd.org/D46248
---
.../content/en/books/handbook/glossary.adoc | 18 +
.../content/en/books/handbook/x11/_index.adoc | 655 ++++++++++++++-------
2 files changed, 464 insertions(+), 209 deletions(-)
diff --git a/documentation/content/en/books/handbook/glossary.adoc b/documentation/content/en/books/handbook/glossary.adoc
index de369e8d2f..005a10e66f 100644
--- a/documentation/content/en/books/handbook/glossary.adoc
+++ b/documentation/content/en/books/handbook/glossary.adoc
@@ -240,6 +240,9 @@ See crossref:glossary[dhcp-glossary,Dynamic Host Configuration Protocol].
DNS::
See crossref:glossary[dns-glossary,Domain Name System].
+DRM::
+See crossref:glossary[drm-glossary,Direct Rendering Manager].
+
DSDT::
See crossref:glossary[dsdt-glossary,Differentiated System Description Table].
@@ -286,6 +289,10 @@ Distance-Vector Multicast Routing Protocol::
Domain Name System::
The system that converts humanly readable hostnames (i.e., mail.example.net) to Internet addresses and vice versa.
+[[drm-glossary]]
+Direct Rendering Manager::
+The man:drm[7] kernel module allows client applications direct access to the graphical hardware via the Direct Rendering Infrastructure.
+
[[dhcp-glossary]]
Dynamic Host Configuration Protocol::
A protocol that dynamically assigns IP addresses to a computer (host) when it requests one from the server.
@@ -467,6 +474,9 @@ See crossref:glossary[kdc-glossary,Key Distribution Center].
KLD::
See crossref:glossary[kld-glossary,Kernel ld(1)].
+KMS::
+See crossref:glossary[kms-glossary,Kernel Mode Setting].
+
KSE::
See crossref:glossary[kse-glossary,Kernel Scheduler Entities].
@@ -476,6 +486,9 @@ See crossref:glossary[kva-glossary,Kernel Virtual Address].
Kbps::
See crossref:glossary[kbps-glossary,Kilo Bits Per Second].
+[[kms-glossary]]
+Setting the display mode in kernel space.
+
[[kld-glossary]]
Kernel man:ld[1]::
A method of dynamically loading functionality into a FreeBSD kernel without rebooting the system.
@@ -791,6 +804,11 @@ As FreeBSD evolves, changes visible to the user should be kept as unsurprising a
For example, arbitrarily rearranging system startup variables in [.filename]#/etc/defaults/rc.conf# violates POLA.
Developers consider POLA when contemplating user-visible system changes.
+[[prime-glossary]]
+PRIME::
+A method of multiple physical graphics coprocessors coexisting by
+sharing their direct memory access buffers.
+
[[pr-glossary]]
Problem Report::
A description of some kind of problem that has been found in either the FreeBSD source or documentation.
diff --git a/documentation/content/en/books/handbook/x11/_index.adoc b/documentation/content/en/books/handbook/x11/_index.adoc
index ea2b2954ea..ed08ab6298 100644
--- a/documentation/content/en/books/handbook/x11/_index.adoc
+++ b/documentation/content/en/books/handbook/x11/_index.adoc
@@ -3,8 +3,8 @@ title: Chapter 5. The X Window System
part: Part I. Getting Started
prev: books/handbook/ports
next: books/handbook/wayland
-description: This chapter describes how to install and configure Xorg on FreeBSD, which provides the open source X Window System used to provide a graphical environment
-tags: ["X11", "Xorg", "TrueType", "Intel", "AMD", "NVIDIA", "Anti-Aliased", "VESA", "SCFB"]
+description: This chapter describes how to install and configure the X Window System providing a graphical environment
+tags: ["AMD", "DRM", "Fonts", "Graphics", "Input", "Intel", "Monitor", "NVIDIA", "PRIME", "SCFB", "TrueType", "VESA", "Video", "X11", "Xf86", "Xorg"]
showBookMenu: true
weight: 7
params:
@@ -15,7 +15,7 @@ params:
= The X Window System
:doctype: book
:toc: macro
-:toclevels: 1
+:toclevels: 2
:icons: font
:sectnums:
:sectnumlevels: 6
@@ -52,125 +52,127 @@ endif::[]
[[x11-synopsis]]
== Synopsis
-An installation of FreeBSD using bsdinstall does not automatically install a graphical user interface.
-This chapter describes how to install and configure Xorg, which provides the open source X Window System used to provide a graphical environment.
-It then describes how to find and install a desktop environment or window manager.
+An crossref:bsdinstall[bsdinstall-synopsis,installation]
+of FreeBSD using man:bsdinstall[8]
+does not automatically install a graphical user interface.
+This chapter describes how to install and configure
+the man:Xorg[1] server, which provides the open source X Window System
+(colloquially X11) used to provide a graphical environment.
Before reading this chapter, you should:
-* Know how to install additional third-party software as described in crossref:ports[ports,Installing Applications: Packages and Ports].
+* Know how to install additional third-party software as described
+in crossref:ports[ports,Installing Applications: Packages and Ports].
After reading this chapter, you will know:
-* The various components of the X Window System, and how they interoperate.
-* How to install and configure Xorg.
-* How to use TrueType(R) fonts in Xorg.
-* How to set up your system for graphical logins (XDM).
+* How to select and install drivers for your graphics processor (GPU).
+* The various components of the X Window System,
+and how they interoperate.
+* How to install and configure the X.org server.
+* How to install fonts for the X Window System.
-[[x-install]]
-== Installing Xorg
-
-On FreeBSD, Xorg can be installed as a package or port.
-
-The binary meta package can be installed quickly but with fewer options for customization:
-
-[source,shell]
-....
-# pkg install xorg
-....
-
-Either of these installations results in the complete Xorg system being installed.
-
-The current user must be a member of the `video` group.
-To add a user to `video` group, execute the following command:
-
-[source,shell]
-....
-# pw groupmod video -m username
-....
+[[x-graphic-card-drivers]]
+== Graphics Drivers
-[TIP]
-====
-A smaller version of the X system suitable for experienced users is available in package:x11/xorg-minimal[].
-Most of the documents, libraries, and applications will not be installed.
-Some applications require these additional components to function.
-====
+_**abstract**: Identify your GPU, the port providing a driver for it,
+install it, then enable it to run at subsequent boot with man:sysrc[8]._
-[TIP]
-====
-Video cards, monitors, and input devices are automatically detected and do not require any manual configuration.
-Do not create `xorg.conf` or run a `-configure` step unless automatic configuration fails.
-====
+Before FreeBSD can render a graphical environment,
+it needs a kernel module to drive the graphics processor.
+Graphics drivers are a fast-moving, cross-platform target,
+which is why this is developed and distributed
+separately from the FreeBSD base system.
-[[x-graphic-card-drivers]]
-== Graphic card drivers
+The following table shows the different graphics processors
+supported by FreeBSD, their corresponding module,
+and which port provides it:
-The following table shows the different graphics cards supported by FreeBSD, which package should be installed and its corresponding module.
-
-.Graphic card packages
+.Supported Graphics Devices
[options="header", cols="1,1,1,1"]
|===
-| Brand | Type | Package | Module
+| Type | License | Module | Port
| Intel(R)
| Open Source
-| drm-kmod
| `i915kms`
+| package:graphics/drm-kmod[]
| AMD(R)
| Open Source
-| drm-kmod
-| `amdgpu` and `radeonkms`
+| `amdgpu` or `radeonkms`
+| package:graphics/drm-kmod[]
| NVIDIA(R)
| Proprietary
-| nvidia-driver
-| `nvidia` or `nvidia-modeset`
+| `nvidia-drm`, `nvidia-modeset`, or `nvidia`
+| package:graphics/nvidia-drm-kmod[] or +
+package:x11/nvidia-driver[]
-| VESA
+| System Console Framebuffer
| Open Source
-| xf86-video-vesa
-| vesa
+| `scfb`
+| package:x11-drivers/xf86-video-scfb[]
-| SCFB
+| VESA BIOS Extension
| Open Source
-| xf86-video-scfb
-| scfb
+| `vesa`
+| package:x11-drivers/xf86-video-vesa[]
| VirtualBox(R)
| Open Source
-| virtualbox-ose-additions
-| VirtualBox(R) OSE additions include the `vboxvideo` driver.
+| `vboxvideo`
+| package:emulators/virtualbox-ose-additions[]
| VMware(R)
| Open Source
-| xf86-video-vmware
-| vmwgfx
-
+| `vmwgfx`
+| package:x11-drivers/xf86-video-vmware[]
|===
-The following command can be used to identify which graphics card is installed in the system:
+There are several generations of driver technologies supported.
+
+* Direct Rendering drivers allowing PRIME offloading.
+PRIME allows for multiple providers of graphics processing to coexist.
+PRIME is described further in <<x-config-gpu>>.
+
+* Kernel Modesetting (crossref:glossary[kms-glossary,KMS])
+This allows the driver to directly specify the display mode.
+This is required to support suspend and resume when using the man:vt[4]
+console driver.
+
+* User Modesetting
+The oldest class of drivers is still supported, however they
+may only be used with man:sc[4] console and older versions of the
+man:Xorg[1] graphical environment.
+
+The following command can be used to identify
+which graphics processor is installed in the system:
[source,shell]
....
-% pciconf -lv|grep -B4 VGA
+% pciconf -lv | grep -B3 display
....
The output should be similar to the following:
[.programlisting]
....
-vgapci0@pci0:0:2:0: class=0x030000 rev=0x07 hdr=0x00 vendor=0x8086 device=0x2a42 subvendor=0x17aa subdevice=0x20e4
+vgapci1@pci0:0:2:0: class=0x030000 rev=0x0c hdr=0x00 vendor=0x8086 device=0x46a6 subvendor=0x1028 subdevice=0x0b29
vendor = 'Intel Corporation'
- device = 'Mobile 4 Series Chipset Integrated Graphics Controller'
+ device = 'Alder Lake-P GT2 [Iris Xe Graphics]'
class = display
- subclass = VGA
....
+Detailed instructions on installing and enabling these drivers
+are in the subsequent subsections.
+
[WARNING]
====
-If the graphics card is not supported by Intel(R), AMD(R) or NVIDIA(R) drivers, then VESA or SCFB modules should be used.
-VESA module must be used when booting in BIOS mode and SCFB module must be used when booting in UEFI mode.
+If the graphics processor is not supported by Intel(R), AMD(R),
+or NVIDIA(R) drivers, then SCFB or VESA modules should be used.
+SCFB module must be used when booting in UEFI mode.
+VESA module must be used when booting in BIOS mode.
This command can be used to check the booting mode:
@@ -183,25 +185,28 @@ The output should be similar to the following:
[.programlisting]
....
-machdep.bootmethod: BIOS
+machdep.bootmethod: UEFI
....
====
[[x-configuration-intel]]
-=== Intel(R)
+=== Intel(R) Graphics
-Intel(R) Graphics refers to the class of graphics chips that are integrated on the same die as an Intel(R) CPU.
-Wikipedia offers link:https://en.wikipedia.org/wiki/List_of_Intel_graphics_processing_units[a good overview of the variations and names used for generations of Intel HD Graphics].
+The package:graphics/drm-kmod[] package indirectly provides
+a range of kernel modules for use with Intel(R) Graphics.
+Recent versions of these modules can be used in conjunction
+with other graphics processors in PRIME with no special configuration.
-The package:graphics/drm-kmod[] package indirectly provides a range of kernel modules for use with Intel(R) Graphics cards.
-The Intel(R) driver can be installed by executing the following command:
+The Intel(R) Graphics driver can be installed
+by executing the following command:
[source,shell]
....
# pkg install drm-kmod
....
-Then add the module to `/etc/rc.conf` file, executing the following command:
+Then add the module to [.filename]#/etc/rc.conf# file,
+by executing the following command:
[source,shell]
....
@@ -209,27 +214,34 @@ Then add the module to `/etc/rc.conf` file, executing the following command:
....
[[x-configuration-amd]]
-=== AMD(R)
+=== AMD(R) Graphics
-The package:graphics/drm-kmod[] package indirectly provides a range of kernel modules for use with AMD(R) Graphics cards.
-The modules `amdgpu` and `radeonkms` can be used depending the generation of the hardware.
-The FreeBSD project maintains an link:https://wiki.freebsd.org/Graphics/AMD-GPU-Matrix[AMD graphics support matrix to determine which driver must be used].
+The package:graphics/drm-kmod[] package indirectly provides
+kernel modules for a range of AMD(R) Graphics processors.
+The modules `amdgpu` or `radeonkms` can be used
+depending the generation of the hardware.
+The FreeBSD project maintains a link:https://wiki.freebsd.org/Graphics/AMD-GPU-Matrix[AMD graphics support matrix]
+showing support levels and to determine which driver must be used.
-AMD(R) driver can be installed by executing the following command:
+The AMD(R) Graphics drivers can be installed
+by executing the following command:
[source,shell]
....
# pkg install drm-kmod
....
-For post-HD7000 or Tahiti graphic cards add the module to `/etc/rc.conf` file, executing the following command:
+Enable the current module by adding it to the [.filename]#/etc/rc.conf#
+file, executing the following command:
[source,shell]
....
# sysrc kld_list+=amdgpu
....
-For older graphic cards (pre-HD7000 or pre-Tahiti) add the module to `/etc/rc.conf` file, executing the following command:
+For older graphics (pre-HD7000/Tahiti),
+instead enable the legacy module by adding it to the
+[.filename]#/etc/rc.conf# file, executing the following command:
[source,shell]
....
@@ -237,101 +249,213 @@ For older graphic cards (pre-HD7000 or pre-Tahiti) add the module to `/etc/rc.co
....
[[x-configuration-nvidia]]
-=== NVIDIA(R)
+=== NVIDIA(R) Graphics
-FreeBSD supports different versions of the proprietary NVIDIA(R) driver.
-Users of newer graphics cards should install the package:x11/nvidia-driver[] package.
-Those with older cards will have to check below which version supports them.
+NVIDIA(R) produces standalone or discrete graphics processors,
+and provides a proprietary driver for FreeBSD.
+The FreeBSD Ports Collection provides over a decade of drivers
+for supporting generations of NVIDIA graphics.
-.Supported versions of NVIDIA(R) drivers
-[options="header", cols="1,1"]
-|===
-| Package | Supported hardware
+Administrators should install the latest driver
+supported by their hardware.
-| package:x11/nvidia-driver-304[]
-| link:https://www.nvidia.com/Download/driverResults.aspx/123712/en-us/[supported hardware]
+The following table shows the port containing the driver,
+the kernel module recommended for loading,
+and a link to the list of hardware supported by that driver:
-| package:x11/nvidia-driver-340[]
-| link:https://www.nvidia.com/Download/driverResults.aspx/156167/en-us/[supported hardware]
+.Supported versions of NVIDIA(R) Graphics drivers
+[options="header", cols="1,1,1"]
+|===
+| Port | Module | Supported hardware
-| package:x11/nvidia-driver-390[]
-| link:https://www.nvidia.com/Download/driverResults.aspx/191122/en-us/[supported hardware]
+| package:graphics/nvidia-drm-kmod[]
+| `nvidia-drm` or +
+`nvidia-modeset`
+| link:https://www.nvidia.com/Download/driverResults.aspx/210651/en-us/[supported hardware]
| package:x11/nvidia-driver-470[]
+| `nvidia-modeset`
| link:https://www.nvidia.com/Download/driverResults.aspx/194639/en-us/[supported hardware]
-| package:x11/nvidia-driver[]
-| link:https://www.nvidia.com/Download/driverResults.aspx/210651/en-us/[supported hardware]
+| package:x11/nvidia-driver-390[] or +
+package:x11/nvidia-secondary-driver-390[]
+| `nvidia-modeset`
+| link:https://www.nvidia.com/Download/driverResults.aspx/191122/en-us/[supported hardware]
+
+| package:x11/nvidia-driver-340[]
+| `nvidia`
+| link:https://www.nvidia.com/Download/driverResults.aspx/156167/en-us/[supported hardware]
+
+| package:x11/nvidia-driver-304[]
+| `nvidia`
+| link:https://www.nvidia.com/Download/driverResults.aspx/123712/en-us/[supported hardware]
|===
-[WARNING]
-====
-Version 304 of the NVIDIA(R) graphics driver (package:x11/nvidia-driver-304[]) does not support xorg-server 1.20 or later.
-====
+The latest NVIDIA(R) Graphics driver can be installed
+by running the following command:
+
+[source,shell]
+....
+# pkg install nvidia-drm-kmod
+....
+
+To enable the driver, add the module to
+[.filename]#/etc/rc.conf# file, by executing the following command:
+
+[source,shell]
+....
+# sysrc kld_list+=nvidia-drm
+....
-The latest NVIDIA(R) driver can be installed by running the following command:
+This is the direct rendering crossref:glossary[glossary-kms,KMS] driver.
+
+Kernel modesetting is the option to set the graphics mode in the kernel.
+Enable it for subsequent boots with the following man:loader.conf[5]
+tunable:
[source,shell]
....
-# pkg install nvidia-driver
+hw.nvidiadrm.modeset="1'
....
-Then add the module to `/etc/rc.conf` file, executing the following command:
+Both PRIME and crossref:wayland[wayland-synopsis,Wayland]
+require kernel modesetting.
+Prior versions of the driver do not support Direct Rendering.
+Instead use the modesetting module,
+by executing the following command:
[source,shell]
....
# sysrc kld_list+=nvidia-modeset
....
-[WARNING]
-====
-The `nvidia` driver must be used if the packages package:x11/nvidia-driver-304[] or package:x11/nvidia-driver-340[] have been installed.
+If requiring Nvidia drivers prior to 390,
+note that they do not support kernel modesetting,
+and thus they must be used with the legacy man:sc[4] console driver,
+and a package:x11/xorg-server[] version prior to 1.20.
+
+Enable them in [.filename]#/etc/rc.conf# with the following command:
[source,shell]
....
# sysrc kld_list+=nvidia
....
-====
-[[x-config]]
-== Xorg Configuration
+[[x-overview]]
+== X Window System Overview
-Xorg supports most common video cards, keyboards, and pointing devices.
+The X Window System is the heritage
+graphical stack for UNIX(R) platforms,
+supporting the latest technologies
+while maintaining support for generations of applications.
+Applications, including the components of the desktop,
+are hosted by the man:Xorg[1] server.
+This system is network aware and its various components
+can interoperate across networks.
-[WARNING]
-====
-Video cards, monitors, and input devices are automatically detected and do not require any manual configuration.
-Do not create [.filename]#xorg.conf# or run a `Xorg -configure` step unless automatic configuration fails.
-====
+[[x-install]]
+== Installing The X.org Server
-[[x-config-files]]
-=== Configuration Files
+_**abstract**: The package:x11/xorg[X.org] server
+must be installed to host the crossref:desktop[desktop-synopsis,desktop].
+Users must be added to the `video` group to use it._
+
+Once a graphics driver is installed and enabled,
+the X.org server can be installed as a meta-package,
+or compiled locally with the ports tree.
-Xorg looks in several directories for configuration files.
-[.filename]#/usr/local/etc/X11/# is the *recommended* directory for these files on FreeBSD.
-Using this directory helps keep application files separate from operating system files.
+The full meta-package can be installed quickly
+but with fewer options for customization:
-[[x-config-files-single-or-multi]]
-=== Single or Multiple Files
+[source,shell]
+....
+# pkg install xorg
+....
+
+This installation results in the complete X Window System
+being installed, including a traditional window manager, man:twm[1],
+and surrounding traditional desktop suite.
+Most users will want to install and configure a
+contemporary crossref:desktop[desktop-synopsis,desktop] of their choice.
+
+The current user must be a member of the `video` group
+to run a graphical environment.
+To add a user to the `video` group, execute the following command:
-It is easier to use multiple files that each configure a specific setting than the traditional single [.filename]#xorg.conf#.
-These files are stored in the [.filename]#/usr/local/etc/X11/xorg.conf.d/# subdirectory.
+[source,shell]
+....
+# pw groupmod video -m username
+....
+
+To run the X Window System, use man:startx[1] from package:x11/xinit[],
+or install and configure a display manager
+to start a graphical login on boot.
[TIP]
====
-The traditional single [.filename]#xorg.conf# still works, but is neither as clear nor as flexible as multiple files in the [.filename]#/usr/local/etc/X11/xorg.conf.d/# subdirectory.
+A smaller version of the X Window System suitable for experienced users
+is available in package:x11/xorg-minimal[].
+Most of the documents, libraries, and applications will not be installed.
+Some applications require these additional components to function.
====
-[[x-config-video-cards]]
-=== Video Cards
+[[x-config]]
+== X.org Configuration
+
+_**abstract**: If the defaults for your monitor or input devices,
+are not satisfactory,
+crossref:desktop[desktop-synopsis,desktops]
+include GUIs for configuring them, or they can be configured manually._
+
+The X.org server supports most common graphics processors, monitors,
+and input devices.
+First, try the defaults.
+This subsection provides an overview of their configuration.
+
+[[x-config-files]]
+=== X.org Configuration Files
+
+Historically, the X.org server was configured with files in
+[.filename]#/usr/local/etc/X11/#.
+This is still supported for edge cases,
+but conflicts with dynamic autoconfiguration.
+
+Do not create configuration for the X.org server in
+[.filename]#xorg.conf#
+or run `Xorg -configure` unless automatic configuration fails.
+
+X.org server looks in several directories for configuration files.
+[.filename]#/usr/local/etc/X11/# is the *recommended* directory
+for these files on FreeBSD.
+Using this directory helps keep application files separate from
+operating system files.
+
+It is easier to use multiple files that each configure a
+specific setting than the traditional single [.filename]#xorg.conf#.
+These files are stored in the
+[.filename]#/usr/local/etc/X11/xorg.conf.d/# subdirectory.
+
+[[x-config-gpu]]
+=== Graphics Configuration
+
+Direct rendering provides the ability to seamlessly
+use a discrete graphics processor (dGPU) alongside
+an integrated graphics processor (iGPU), called PRIME.
+The drivers will automatically offload intensive tasks to the dGPU
+when required, and power it down when able.
-The driver for the graphics card can be specified in the [.filename]#/usr/local/etc/X11/xorg.conf.d/# directory.
+To launch applications on the more powerful GPU in PRIME,
+use the `DRI_PRIME=1` enviroment variable.
+
+If multiple graphics drivers are conflicting,
+the driver for the graphics processor can be specified in the
+[.filename]#/usr/local/etc/X11/xorg.conf.d/# directory.
To configure the Intel(R) driver in a configuration file:
[[x-config-video-cards-file-intel]]
-.Select Intel(R) Video Driver in a File
+.Select Intel(R) Graphics Driver in a File
[example]
====
[.filename]#/usr/local/etc/X11/xorg.conf.d/20-intel.conf#
@@ -348,7 +472,7 @@ EndSection
To configure the AMD(R) driver in a configuration file:
[[x-config-video-cards-file-amd]]
-.Select AMD(R) Video Driver in a File
+.Select AMD(R) Graphics Driver in a File
[example]
====
[.filename]#/usr/local/etc/X11/xorg.conf.d/20-radeon.conf#
@@ -365,7 +489,7 @@ EndSection
To configure the NVIDIA(R) driver in a configuration file:
[[x-config-video-cards-file-nvidia]]
-.Select NVIDIA(R) Video Driver in a File
+.Select NVIDIA(R) Graphics Driver in a File
[example]
====
[.filename]#/usr/local/etc/X11/xorg.conf.d/20-nvidia.conf#
@@ -374,52 +498,53 @@ To configure the NVIDIA(R) driver in a configuration file:
....
Section "Device"
Identifier "Card0"
- Driver "nvidia"
+ Driver "nvidia-modeset"
EndSection
....
====
[TIP]
====
-package:x11/nvidia-xconfig[] can also be used to perform basic control over configuration options available in the NVIDIA driver.
+package:x11/nvidia-xconfig[] can also be used to perform basic control
+over configuration options available in the NVIDIA driver.
====
-To configure the VESA driver in a configuration file:
+To configure the SCFB driver in a configuration file:
-[[x-config-video-cards-file-vesa]]
-.Select VESA Video Driver in a File
+[[x-config-video-cards-file-sfcb]]
+.Select SCFB Graphics Driver in a File
[example]
====
-[.filename]#/usr/local/etc/X11/xorg.conf.d/20-vesa.conf#
+[.filename]#/usr/local/etc/X11/xorg.conf.d/20-scfb.conf#
[.programlisting]
....
Section "Device"
Identifier "Card0"
- Driver "vesa"
+ Driver "scfb"
EndSection
....
====
-To configure the SCFB driver in a configuration file:
+To configure the VESA driver in a configuration file:
-[[x-config-video-cards-file-sfcb]]
-.Select SCFB Video Driver in a File
+[[x-config-video-cards-file-vesa]]
+.Select VESA Graphics Driver in a File
[example]
====
-[.filename]#/usr/local/etc/X11/xorg.conf.d/20-scfb.conf#
+[.filename]#/usr/local/etc/X11/xorg.conf.d/20-vesa.conf#
[.programlisting]
....
Section "Device"
Identifier "Card0"
- Driver "scfb"
+ Driver "vesa"
EndSection
....
====
-To configure multiple video cards, the `BusID` can be added.
-A list of video card bus ``ID``s can be displayed by executing:
+To configure multiple graphics processors, the `BusID` can be added.
+A list of graphics processor bus ``ID``s can be displayed by executing:
[source,shell]
....
@@ -430,19 +555,19 @@ The output should be similar to the following:
[.programlisting]
....
-vgapci0@pci0:0:2:0: class=0x030000 rev=0x07 hdr=0x00 vendor=0x8086 device=0x2a42 subvendor=0x17aa subdevice=0x20e4
+vgapci0@pci0:0:2:0: class=0x030000 rev=0x0c hdr=0x00 vendor=0x8086 device=0x46a6 subvendor=0x1028 subdevice=0x0b29
vendor = 'Intel Corporation'
- device = 'Mobile 4 Series Chipset Integrated Graphics Controller'
+ device = 'Alder Lake-P GT2 [Iris Xe Graphics]'
class = display
--
-vgapci1@pci0:0:2:1: class=0x038000 rev=0x07 hdr=0x00 vendor=0x8086 device=0x2a43 subvendor=0x17aa subdevice=0x20e4
- vendor = 'Intel Corporation'
- device = 'Mobile 4 Series Chipset Integrated Graphics Controller'
+vgapci0@pci0:1:0:0: class=0x030200 rev=0xa1 hdr=0x00 vendor=0x10de device=0x25b9 subvendor=0x1028 subdevice=0x0b29
+ vendor = 'NVIDIA Corporation'
+ device = 'GA107GLM [RTX A1000 Laptop GPU]'
class = display
....
[[x-config-video-cards-file-multiple]]
-.Select Intel(R) Video Driver and NVIDIA(R) Video Driver in a File
+.Select Intel(R) Graphics Driver and NVIDIA(R) Graphics Driver in a File
[example]
====
@@ -457,26 +582,32 @@ Section "Device"
EndSection
Section "Device"
- Identifier "Card0"
- Driver "nvidia"
+ Identifier "Card1"
+ Driver "nvidia-modeset"
BusID "pci0:0:2:1"
EndSection
....
====
[[x-config-monitors]]
-=== Monitors
+=== Monitor Configuration
-Almost all monitors support the Extended Display Identification Data standard (`EDID`).
-Xorg uses `EDID` to communicate with the monitor and detect the supported resolutions and refresh rates.
-Then it selects the most appropriate combination of settings to use with that monitor.
+Almost all monitors support the Extended Display Identification Data
+standard (`EDID`).
+X.org uses `EDID` to communicate with the monitor
+and detect the supported resolutions and refresh rates.
+Then it selects the most appropriate combination of settings
+to use with that monitor.
-Other resolutions supported by the monitor can be chosen by setting the desired resolution in configuration files, or after the X server has been started with man:xrandr[1].
+Other resolutions supported by the monitor can be selected atomically
+after the X server has been started with man:xrandr[1],
+or in the X.org server configuration files.
[[x-config-monitors-xrandr]]
==== Using RandR (Resize and Rotate)
-Run man:xrandr[1] without any parameters to see a list of video outputs and detected monitor modes:
+Run man:xrandr[1] in an X session without any parameters
+to see a list of video outputs and detected monitor modes:
[source,shell]
....
@@ -517,9 +648,12 @@ DP-2 disconnected (normal left inverted right x axis y axis)
DP-3 disconnected (normal left inverted right x axis y axis)
....
-This shows that the `VGA-1` output is being used to display a screen resolution of 1280x960 pixels at a refresh rate of about 60 Hz.
-The `LVDS-1` is being used as a secondary monitor to display a screen resolution of 1280x800 pixels at a refresh rate of about 60 Hz.
-Monitors are not attached to the `HDMI-1`, `HDMI-2`, `DP-1`, `DP-2` and `DP-3` connectors.
+This shows that the `VGA-1` output is being used to display
+a screen resolution of 1280x960 pixels at a refresh rate of about 60 Hz.
+The `LVDS-1` is being used as a secondary monitor to display
+a screen resolution of 1280x800 pixels at a refresh rate of about 60 Hz.
+Monitors are not attached to the `HDMI-1`, `HDMI-2`, `DP-1`, `DP-2`, and
+`DP-3` connectors.
Any of the other display modes can be selected with man:xrandr[1].
For example, to switch to 1280x1024 at 60 Hz:
@@ -529,8 +663,14 @@ For example, to switch to 1280x1024 at 60 Hz:
% xrandr --output LVDS-1 --mode 1280x720 --rate 60
....
-[[x-config-monitors-files]]
-==== Using the Xorg configuration file
+[TIP]
+====
+Oftentimes, a black screen upon starting X can be fixed
+by adding an `xrandr --auto` step to the initialization process.
+====
+
+[[x-config-monitors-file]]
+==== Using the X.org Configuration Files
The monitor configuration can also be set in a configuration file.
@@ -554,18 +694,80 @@ EndSection
====
[[x-config-input]]
-=== Input Devices
+=== Input Configuration
+
+The package:Xorg[X.org] server provides the package:x11/libinput[]
+library, a cross-platform effort to support all touch, pointing,
+and keyboard devices under a unified library.
+Unless specified otherwise, this is loaded automatically.
+
+Individual device settings for man:libinput[4] can be tuned in your
+crossref:desktop[desktop-synopsis,desktop's] GUI,
+or manually with package:x11/xinput[xinput]
+and package:x11/setxkbmap[setxkbmap].
+
+Alternatively, there are older, lightweight, individual drivers for
+specific input devices available in the package:x11-drivers[] catagory
+named x11/xf86-input-[foo].
+This approach requires manual configuration of the X.org server.
+Both are described in this subsection.
+
+[[x-config-input-atmoic]]
+==== Using Atomic Input Configuration
+
+Devices supported by man:libinput[4] can be configured
+with graphical utilities included with your
+crossref:desktop[desktop-synopsis,desktop] of choice,
+or manually and atomically at runtime with package:x11/xinput[]
+and package:x11/setxkbmap[].
+
+To ask man:libinput[4] what devices it's currently attached to,
+run man:xinput[1] with no arguments:
+
+[source,shell]
+....
+$ xinput
+....
+
+Its output should be similar to the following:
+
+[example]
+....
+
+⎡ Virtual core pointer id=2 [master pointer (3)]
+⎜ ↳ Virtual core XTEST pointer id=4 [slave pointer (2)]
+⎜ ↳ System mouse id=7 [slave pointer (2)]
+⎜ ↳ VEN_0488:00 0488:1031 Mouse id=11 [slave pointer (2)]
+⎜ ↳ VEN_0488:00 0488:1031 TouchPad id=12 [slave pointer (2)]
+⎣ Virtual core keyboard id=3 [master keyboard (2)]
+ ↳ Virtual core XTEST keyboard id=5 [slave keyboard (3)]
+ ↳ System keyboard multiplexer id=6 [slave keyboard (3)]
+ ↳ Power Button id=8 [slave keyboard (3)]
+ ↳ Sleep Button id=9 [slave keyboard (3)]
+ ↳ AT keyboard id=10 [slave keyboard (3)]
+....
+
+All settings supported by these devices are provided as properties,
+which can be listed and set atomically.
+Pointing devices have many configurable properties, keyboards usually need none.
+
+To customize your keyboard, take a look at man:setxkbmap[1].
+
+Once satisfied with your configuration, simply add the lines to your
+X initialization script such as [.filename]#~/.Xsession# or [.filename]#~/.xinitrc#.
+
+[[x-config-input-file]]
+==== Using X.org Configuration Files
-Xorg supports the vast majority of input devices via package:x11/libinput[].
[TIP]
====
-Some desktop environments (such as KDE Plasma) provide a graphical UI for setting these parameters.
+Some desktop environments (such as crossref:desktop[kde-environment,KDE Plasma]) provide a graphical UI for setting these parameters.
Check if this is the case before resorting to manual configuration editing.
====
[[x-config-input-keyboard-layout]]
-For example, to configure the keyboard layout:
+For example, to manually configure the X.org server for the keyboard layout:
.Setting a Keyboard Layout
[example]
@@ -586,53 +788,55 @@ EndSection
====
[[x-fonts]]
-== Using Fonts in Xorg
+== Using Fonts in the X Window System
-The default fonts that ship with Xorg are less than ideal for typical desktop publishing applications.
-Large presentation fonts show up jagged and unprofessional looking, and small fonts are almost completely unintelligible.
-However, there are several free, high quality Type1 (PostScript(R)) fonts available which can be readily used with Xorg.
+_**abstract**: Additional fonts can be installed from the
+package:x11-fonts[] category or placed in [.filename]#~/.fonts#.
+They are available immediately to modern applications.
+Configuration for older applications is available and described as well._
-[[type1]]
-=== Type1 Fonts
+The X Window System provides the X FreeType interface library
+(man:Xft[3]) to render vector or outline fonts,
+as well as the traditional X Logical Font Description system
+maintaining compatibility with generations of applications and fonts.
-The URW font collection (package:x11-fonts/urwfonts[]) includes high quality versions of standard type1 fonts (Times Roman(TM), Helvetica(TM), Palatino(TM) and others).
-The Freefonts collection (package:x11-fonts/freefonts[]) includes many more fonts, but most of them are intended for use in graphics software such as the Gimp, and are not complete enough to serve as screen fonts.
-In addition, Xorg can be configured to use TrueType(R) fonts with a minimum of effort.
-For more details on this, see the man:X[7] manual page or crossref:x11[truetype, TrueType(R) Fonts].
+There are primarily two types of fonts users will be interested in:
-To install the above Type1 font collections from binary packages, run the following commands:
+* OpenType fonts or TrueType(R) fonts are for displaying on a screen.
+* Adobe(R) PostScript(R) Type 1 fonts are for printing to paper.
-[source,shell]
-....
-# pkg install urwfonts
-....
+These are both vector or outline fonts, there are also bitmap fonts.
-And likewise with the freefont or other collections.
-To have the X server detect these fonts, add an appropriate line to the X server configuration file ([.filename]#/usr/local/etc/X11/xorg.conf.d/90-fonts.conf#), which reads:
*** 117 LINES SKIPPED ***