Date: Mon, 14 Jul 2025 13:24:56 GMT From: Alexander Ziaee <ziaee@FreeBSD.org> To: doc-committers@FreeBSD.org, dev-commits-doc-all@FreeBSD.org Subject: git: 654c02af03 - main - handbook/x11: refactor Message-ID: <202507141324.56EDOuRp087466@gitrepo.freebsd.org>
next in thread | raw e-mail | index | archive | help
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 ***
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?202507141324.56EDOuRp087466>