Documentation/gpu/vgaarbiter.rst

Source file repositories/reference/linux-study-clean/Documentation/gpu/vgaarbiter.rst

File Facts

System
Linux kernel
Corpus path
Documentation/gpu/vgaarbiter.rst
Extension
.rst
Size
8175 bytes
Lines
192
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: documentation
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

===========
VGA Arbiter
===========

Graphic devices are accessed through ranges in I/O or memory space. While most
modern devices allow relocation of such ranges, some "Legacy" VGA devices
implemented on PCI will typically have the same "hard-decoded" addresses as
they did on ISA. For more details see "PCI Bus Binding to IEEE Std 1275-1994
Standard for Boot (Initialization Configuration) Firmware Revision 2.1"
Section 7, Legacy Devices.

The Resource Access Control (RAC) module inside the X server [0] existed for
the legacy VGA arbitration task (besides other bus management tasks) when more
than one legacy device co-exist on the same machine. But the problem happens
when these devices are trying to be accessed by different userspace clients
(e.g. two servers in parallel). Their address assignments conflict. Moreover,
ideally, being a userspace application, it is not the role of the X server to
control bus resources. Therefore an arbitration scheme outside of the X server
is needed to control the sharing of these resources. This document introduces
the operation of the VGA arbiter implemented for the Linux kernel.

vgaarb kernel/userspace ABI
---------------------------

The vgaarb is a module of the Linux Kernel. When it is initially loaded, it
scans all PCI devices and adds the VGA ones inside the arbitration. The
arbiter then enables/disables the decoding on different devices of the VGA
legacy instructions. Devices which do not want/need to use the arbiter may
explicitly tell it by calling vga_set_legacy_decoding().

The kernel exports a char device interface (/dev/vga_arbiter) to the clients,
which has the following semantics:

open
        Opens a user instance of the arbiter. By default, it's attached to the
        default VGA device of the system.

close
        Close a user instance. Release locks made by the user

read
        Return a string indicating the status of the target like:

        "<card_ID>,decodes=<io_state>,owns=<io_state>,locks=<io_state> (ic,mc)"

        An IO state string is of the form {io,mem,io+mem,none}, mc and
        ic are respectively mem and io lock counts (for debugging/
        diagnostic only). "decodes" indicate what the card currently
        decodes, "owns" indicates what is currently enabled on it, and
        "locks" indicates what is locked by this card. If the card is
        unplugged, we get "invalid" then for card_ID and an -ENODEV
        error is returned for any command until a new card is targeted.


write
        Write a command to the arbiter. List of commands:

        target <card_ID>
                switch target to card <card_ID> (see below)
        lock <io_state>
                acquires locks on target ("none" is an invalid io_state)
        trylock <io_state>
                non-blocking acquire locks on target (returns EBUSY if
                unsuccessful)
        unlock <io_state>
                release locks on target
        unlock all
                release all locks on target held by this user (not implemented
                yet)
        decodes <io_state>

Annotation

Implementation Notes