diff options
Diffstat (limited to 'Documentation/gpu')
| -rw-r--r-- | Documentation/gpu/drm-kms-helpers.rst | 211 | ||||
| -rw-r--r-- | Documentation/gpu/drm-kms.rst | 270 | ||||
| -rw-r--r-- | Documentation/gpu/drm-mm.rst | 58 | ||||
| -rw-r--r-- | Documentation/gpu/drm-uapi.rst | 3 | ||||
| -rw-r--r-- | Documentation/gpu/index.rst | 1 | ||||
| -rw-r--r-- | Documentation/gpu/vga-switcheroo.rst | 2 | ||||
| -rw-r--r-- | Documentation/gpu/vgaarbiter.rst | 191 |
7 files changed, 387 insertions, 349 deletions
diff --git a/Documentation/gpu/drm-kms-helpers.rst b/Documentation/gpu/drm-kms-helpers.rst index 0b302fedf1af..59fa3c11efab 100644 --- a/Documentation/gpu/drm-kms-helpers.rst +++ b/Documentation/gpu/drm-kms-helpers.rst @@ -2,38 +2,45 @@ Mode Setting Helper Functions ============================= -The plane, CRTC, encoder and connector functions provided by the drivers -implement the DRM API. They're called by the DRM core and ioctl handlers -to handle device state changes and configuration request. As -implementing those functions often requires logic not specific to -drivers, mid-layer helper functions are available to avoid duplicating -boilerplate code. - -The DRM core contains one mid-layer implementation. The mid-layer -provides implementations of several plane, CRTC, encoder and connector -functions (called from the top of the mid-layer) that pre-process -requests and call lower-level functions provided by the driver (at the -bottom of the mid-layer). For instance, the -:c:func:`drm_crtc_helper_set_config()` function can be used to -fill the :c:type:`struct drm_crtc_funcs <drm_crtc_funcs>` -set_config field. When called, it will split the set_config operation -in smaller, simpler operations and call the driver to handle them. - -To use the mid-layer, drivers call -:c:func:`drm_crtc_helper_add()`, -:c:func:`drm_encoder_helper_add()` and -:c:func:`drm_connector_helper_add()` functions to install their -mid-layer bottom operations handlers, and fill the :c:type:`struct -drm_crtc_funcs <drm_crtc_funcs>`, :c:type:`struct -drm_encoder_funcs <drm_encoder_funcs>` and :c:type:`struct -drm_connector_funcs <drm_connector_funcs>` structures with -pointers to the mid-layer top API functions. Installing the mid-layer -bottom operation handlers is best done right after registering the -corresponding KMS object. - -The mid-layer is not split between CRTC, encoder and connector -operations. To use it, a driver must provide bottom functions for all of -the three KMS entities. +The DRM subsystem aims for a strong separation between core code and helper +libraries. Core code takes care of general setup and teardown and decoding +userspace requests to kernel internal objects. Everything else is handled by a +large set of helper libraries, which can be combined freely to pick and choose +for each driver what fits, and avoid shared code where special behaviour is +needed. + +This distinction between core code and helpers is especially strong in the +modesetting code, where there's a shared userspace ABI for all drivers. This is +in contrast to the render side, where pretty much everything (with very few +exceptions) can be considered optional helper code. + +There are a few areas these helpers can grouped into: + +* Helpers to implement modesetting. The important ones here are the atomic + helpers. Old drivers still often use the legacy CRTC helpers. They both share + the same set of common helper vtables. For really simple drivers (anything + that would have been a great fit in the deprecated fbdev subsystem) there's + also the simple display pipe helpers. + +* There's a big pile of helpers for handling outputs. First the generic bridge + helpers for handling encoder and transcoder IP blocks. Second the panel helpers + for handling panel-related information and logic. Plus then a big set of + helpers for the various sink standards (DisplayPort, HDMI, MIPI DSI). Finally + there's also generic helpers for handling output probing, and for dealing with + EDIDs. + +* The last group of helpers concerns itself with the frontend side of a display + pipeline: Planes, handling rectangles for visibility checking and scissoring, + flip queues and assorted bits. + +Modeset Helper Reference for Common Vtables +=========================================== + +.. kernel-doc:: include/drm/drm_modeset_helper_vtables.h + :internal: + +.. kernel-doc:: include/drm/drm_modeset_helper_vtables.h + :doc: overview Atomic Modeset Helper Functions Reference ========================================= @@ -62,33 +69,27 @@ Atomic State Reset and Initialization .. kernel-doc:: drivers/gpu/drm/drm_atomic_helper.c :export: -Modeset Helper Reference for Common Vtables -=========================================== - -.. kernel-doc:: include/drm/drm_modeset_helper_vtables.h - :internal: - -.. kernel-doc:: include/drm/drm_modeset_helper_vtables.h - :doc: overview - Legacy CRTC/Modeset Helper Functions Reference ============================================== .. kernel-doc:: drivers/gpu/drm/drm_crtc_helper.c - :export: + :doc: overview .. kernel-doc:: drivers/gpu/drm/drm_crtc_helper.c - :doc: overview + :export: -Output Probing Helper Functions Reference -========================================= +Simple KMS Helper Reference +=========================== -.. kernel-doc:: drivers/gpu/drm/drm_probe_helper.c - :doc: output probing helper overview +.. kernel-doc:: include/drm/drm_simple_kms_helper.h + :internal: -.. kernel-doc:: drivers/gpu/drm/drm_probe_helper.c +.. kernel-doc:: drivers/gpu/drm/drm_simple_kms_helper.c :export: +.. kernel-doc:: drivers/gpu/drm/drm_simple_kms_helper.c + :doc: overview + fbdev Helper Functions Reference ================================ @@ -110,6 +111,36 @@ Framebuffer CMA Helper Functions Reference .. kernel-doc:: drivers/gpu/drm/drm_fb_cma_helper.c :export: +Bridges +======= + +Overview +-------- + +.. kernel-doc:: drivers/gpu/drm/drm_bridge.c + :doc: overview + +Default bridge callback sequence +-------------------------------- + +.. kernel-doc:: drivers/gpu/drm/drm_bridge.c + :doc: bridge callbacks + +.. kernel-doc:: drivers/gpu/drm/drm_bridge.c + :export: + +Panel Helper Reference +====================== + +.. kernel-doc:: include/drm/drm_panel.h + :internal: + +.. kernel-doc:: drivers/gpu/drm/drm_panel.c + :export: + +.. kernel-doc:: drivers/gpu/drm/drm_panel.c + :doc: drm panel + Display Port Helper Functions Reference ======================================= @@ -158,6 +189,15 @@ MIPI DSI Helper Functions Reference .. kernel-doc:: drivers/gpu/drm/drm_mipi_dsi.c :export: +Output Probing Helper Functions Reference +========================================= + +.. kernel-doc:: drivers/gpu/drm/drm_probe_helper.c + :doc: output probing helper overview + +.. kernel-doc:: drivers/gpu/drm/drm_probe_helper.c + :export: + EDID Helper Functions Reference =============================== @@ -176,18 +216,6 @@ Rectangle Utilities Reference .. kernel-doc:: drivers/gpu/drm/drm_rect.c :export: -Flip-work Helper Reference -========================== - -.. kernel-doc:: include/drm/drm_flip_work.h - :doc: flip utils - -.. kernel-doc:: include/drm/drm_flip_work.h - :internal: - -.. kernel-doc:: drivers/gpu/drm/drm_flip_work.c - :export: - HDMI Infoframes Helper Reference ================================ @@ -202,59 +230,40 @@ libraries and hence is also included here. .. kernel-doc:: drivers/video/hdmi.c :export: -Plane Helper Reference -====================== - -.. kernel-doc:: drivers/gpu/drm/drm_plane_helper.c - :export: - -.. kernel-doc:: drivers/gpu/drm/drm_plane_helper.c - :doc: overview +Flip-work Helper Reference +========================== -Tile group ----------- +.. kernel-doc:: include/drm/drm_flip_work.h + :doc: flip utils -.. kernel-doc:: drivers/gpu/drm/drm_crtc.c - :doc: Tile group +.. kernel-doc:: include/drm/drm_flip_work.h + :internal: -Bridges -======= +.. kernel-doc:: drivers/gpu/drm/drm_flip_work.c + :export: -Overview --------- +Plane Helper Reference +====================== -.. kernel-doc:: drivers/gpu/drm/drm_bridge.c +.. kernel-doc:: drivers/gpu/drm/drm_plane_helper.c :doc: overview -Default bridge callback sequence --------------------------------- - -.. kernel-doc:: drivers/gpu/drm/drm_bridge.c - :doc: bridge callbacks - -.. kernel-doc:: drivers/gpu/drm/drm_bridge.c +.. kernel-doc:: drivers/gpu/drm/drm_plane_helper.c :export: -Panel Helper Reference -====================== - -.. kernel-doc:: include/drm/drm_panel.h - :internal: +Tile group +========== -.. kernel-doc:: drivers/gpu/drm/drm_panel.c - :export: +# FIXME: This should probably be moved into a property documentation section -.. kernel-doc:: drivers/gpu/drm/drm_panel.c - :doc: drm panel +.. kernel-doc:: drivers/gpu/drm/drm_crtc.c + :doc: Tile group -Simple KMS Helper Reference -=========================== +Auxiliary Modeset Helpers +========================= -.. kernel-doc:: include/drm/drm_simple_kms_helper.h - :internal: +.. kernel-doc:: drivers/gpu/drm/drm_modeset_helper.c + :doc: aux kms helpers -.. kernel-doc:: drivers/gpu/drm/drm_simple_kms_helper.c +.. kernel-doc:: drivers/gpu/drm/drm_modeset_helper.c :export: - -.. kernel-doc:: drivers/gpu/drm/drm_simple_kms_helper.c - :doc: overview diff --git a/Documentation/gpu/drm-kms.rst b/Documentation/gpu/drm-kms.rst index 8dfa4b214b96..fa948b4e029b 100644 --- a/Documentation/gpu/drm-kms.rst +++ b/Documentation/gpu/drm-kms.rst @@ -2,9 +2,6 @@ Kernel Mode Setting (KMS) ========================= -Mode Setting -============ - Drivers must initialize the mode setting core by calling :c:func:`drm_mode_config_init()` on the DRM device. The function initializes the :c:type:`struct drm_device <drm_device>` @@ -18,60 +15,50 @@ be setup by initializing the following fields. - struct drm_mode_config_funcs \*funcs; Mode setting functions. -Display Modes Function Reference --------------------------------- +KMS Data Structures +=================== -.. kernel-doc:: include/drm/drm_modes.h +.. kernel-doc:: include/drm/drm_crtc.h :internal: -.. kernel-doc:: drivers/gpu/drm/drm_modes.c +KMS API Functions +================= + +.. kernel-doc:: drivers/gpu/drm/drm_crtc.c :export: Atomic Mode Setting Function Reference --------------------------------------- +====================================== .. kernel-doc:: drivers/gpu/drm/drm_atomic.c :export: -.. kernel-doc:: drivers/gpu/drm/drm_atomic.c +.. kernel-doc:: include/drm/drm_atomic.h :internal: Frame Buffer Abstraction ------------------------- - -Frame buffers are abstract memory objects that provide a source of -pixels to scanout to a CRTC. Applications explicitly request the -creation of frame buffers through the DRM_IOCTL_MODE_ADDFB(2) ioctls -and receive an opaque handle that can be passed to the KMS CRTC control, -plane configuration and page flip functions. - -Frame buffers rely on the underneath memory manager for low-level memory -operations. When creating a frame buffer applications pass a memory -handle (or a list of memory handles for multi-planar formats) through -the ``drm_mode_fb_cmd2`` argument. For drivers using GEM as their -userspace buffer management interface this would be a GEM handle. -Drivers are however free to use their own backing storage object -handles, e.g. vmwgfx directly exposes special TTM handles to userspace -and so expects TTM handles in the create ioctl and not GEM handles. - -The lifetime of a drm framebuffer is controlled with a reference count, -drivers can grab additional references with -:c:func:`drm_framebuffer_reference()`and drop them again with -:c:func:`drm_framebuffer_unreference()`. For driver-private -framebuffers for which the last reference is never dropped (e.g. for the -fbdev framebuffer when the struct :c:type:`struct drm_framebuffer -<drm_framebuffer>` is embedded into the fbdev helper struct) -drivers can manually clean up a framebuffer at module unload time with -:c:func:`drm_framebuffer_unregister_private()`. +======================== + +.. kernel-doc:: drivers/gpu/drm/drm_framebuffer.c + :doc: overview + +Frame Buffer Functions Reference +-------------------------------- + +.. kernel-doc:: drivers/gpu/drm/drm_framebuffer.c + :export: + +.. kernel-doc:: include/drm/drm_framebuffer.h + :internal: DRM Format Handling -------------------- +=================== .. kernel-doc:: drivers/gpu/drm/drm_fourcc.c :export: Dumb Buffer Objects -------------------- +=================== The KMS API doesn't standardize backing storage object creation and leaves it to driver-specific ioctls. Furthermore actually creating a @@ -114,14 +101,29 @@ Note that dumb objects may not be used for gpu acceleration, as has been attempted on some ARM embedded platforms. Such drivers really must have a hardware-specific ioctl to allocate suitable buffer objects. -Output Polling --------------- +Display Modes Function Reference +================================ + +.. kernel-doc:: include/drm/drm_modes.h + :internal: + +.. kernel-doc:: drivers/gpu/drm/drm_modes.c + :export: + +Connector Abstraction +===================== + +.. kernel-doc:: drivers/gpu/drm/drm_connector.c + :doc: overview -void (\*output_poll_changed)(struct drm_device \*dev); -This operation notifies the driver that the status of one or more -connectors has changed. Drivers that use the fb helper can just call the -:c:func:`drm_fb_helper_hotplug_event()` function to handle this -operation. +Connector Functions Reference +----------------------------- + +.. kernel-doc:: include/drm/drm_connector.h + :internal: + +.. kernel-doc:: drivers/gpu/drm/drm_connector.c + :export: KMS Initialization and Cleanup ============================== @@ -236,166 +238,6 @@ encoders unattached at initialization time. Applications (or the fbdev compatibility layer when implemented) are responsible for attaching the encoders they want to use to a CRTC. -Connectors (:c:type:`struct drm_connector <drm_connector>`) ------------------------------------------------------------ - -A connector is the final destination for pixel data on a device, and -usually connects directly to an external display device like a monitor -or laptop panel. A connector can only be attached to one encoder at a -time. The connector is also the structure where information about the -attached display is kept, so it contains fields for display data, EDID -data, DPMS & connection status, and information about modes supported on -the attached displays. - -Connector Initialization -~~~~~~~~~~~~~~~~~~~~~~~~ - -Finally a KMS driver must create, initialize, register and attach at -least one :c:type:`struct drm_connector <drm_connector>` -instance. The instance is created as other KMS objects and initialized -by setting the following fields. - -interlace_allowed - Whether the connector can handle interlaced modes. - -doublescan_allowed - Whether the connector can handle doublescan. - -display_info - Display information is filled from EDID information when a display - is detected. For non hot-pluggable displays such as flat panels in - embedded systems, the driver should initialize the - display_info.width_mm and display_info.height_mm fields with the - physical size of the display. - -polled - Connector polling mode, a combination of - - DRM_CONNECTOR_POLL_HPD - The connector generates hotplug events and doesn't need to be - periodically polled. The CONNECT and DISCONNECT flags must not - be set together with the HPD flag. - - DRM_CONNECTOR_POLL_CONNECT - Periodically poll the connector for connection. - - DRM_CONNECTOR_POLL_DISCONNECT - Periodically poll the connector for disconnection. - - Set to 0 for connectors that don't support connection status - discovery. - -The connector is then registered with a call to -:c:func:`drm_connector_init()` with a pointer to the connector -functions and a connector type, and exposed through sysfs with a call to -:c:func:`drm_connector_register()`. - -Supported connector types are - -- DRM_MODE_CONNECTOR_VGA -- DRM_MODE_CONNECTOR_DVII -- DRM_MODE_CONNECTOR_DVID -- DRM_MODE_CONNECTOR_DVIA -- DRM_MODE_CONNECTOR_Composite -- DRM_MODE_CONNECTOR_SVIDEO -- DRM_MODE_CONNECTOR_LVDS -- DRM_MODE_CONNECTOR_Component -- DRM_MODE_CONNECTOR_9PinDIN -- DRM_MODE_CONNECTOR_DisplayPort -- DRM_MODE_CONNECTOR_HDMIA -- DRM_MODE_CONNECTOR_HDMIB -- DRM_MODE_CONNECTOR_TV -- DRM_MODE_CONNECTOR_eDP -- DRM_MODE_CONNECTOR_VIRTUAL - -Connectors must be attached to an encoder to be used. For devices that -map connectors to encoders 1:1, the connector should be attached at -initialization time with a call to -:c:func:`drm_mode_connector_attach_encoder()`. The driver must -also set the :c:type:`struct drm_connector <drm_connector>` -encoder field to point to the attached encoder. - -Finally, drivers must initialize the connectors state change detection -with a call to :c:func:`drm_kms_helper_poll_init()`. If at least -one connector is pollable but can't generate hotplug interrupts -(indicated by the DRM_CONNECTOR_POLL_CONNECT and -DRM_CONNECTOR_POLL_DISCONNECT connector flags), a delayed work will -automatically be queued to periodically poll for changes. Connectors -that can generate hotplug interrupts must be marked with the -DRM_CONNECTOR_POLL_HPD flag instead, and their interrupt handler must -call :c:func:`drm_helper_hpd_irq_event()`. The function will -queue a delayed work to check the state of all connectors, but no -periodic polling will be done. - -Connector Operations -~~~~~~~~~~~~~~~~~~~~ - - **Note** - - Unless otherwise state, all operations are mandatory. - -DPMS -'''' - -void (\*dpms)(struct drm_connector \*connector, int mode); -The DPMS operation sets the power state of a connector. The mode -argument is one of - -- DRM_MODE_DPMS_ON - -- DRM_MODE_DPMS_STANDBY - -- DRM_MODE_DPMS_SUSPEND - -- DRM_MODE_DPMS_OFF - -In all but DPMS_ON mode the encoder to which the connector is attached -should put the display in low-power mode by driving its signals -appropriately. If more than one connector is attached to the encoder -care should be taken not to change the power state of other displays as -a side effect. Low-power mode should be propagated to the encoders and -CRTCs when all related connectors are put in low-power mode. - -Modes -''''' - -int (\*fill_modes)(struct drm_connector \*connector, uint32_t -max_width, uint32_t max_height); -Fill the mode list with all supported modes for the connector. If the -``max_width`` and ``max_height`` arguments are non-zero, the -implementation must ignore all modes wider than ``max_width`` or higher -than ``max_height``. - -The connector must also fill in this operation its display_info -width_mm and height_mm fields with the connected display physical size -in millimeters. The fields should be set to 0 if the value isn't known -or is not applicable (for instance for projector devices). - -Connection Status -''''''''''''''''' - -The connection status is updated through polling or hotplug events when -supported (see ?). The status value is reported to userspace through -ioctls and must not be used inside the driver, as it only gets -initialized by a call to :c:func:`drm_mode_getconnector()` from -userspace. - -enum drm_connector_status (\*detect)(struct drm_connector -\*connector, bool force); -Check to see if anything is attached to the connector. The ``force`` -parameter is set to false whilst polling or to true when checking the -connector due to user request. ``force`` can be used by the driver to -avoid expensive, destructive operations during automated probing. - -Return connector_status_connected if something is connected to the -connector, connector_status_disconnected if nothing is connected and -connector_status_unknown if the connection state isn't known. - -Drivers should only return connector_status_connected if the -connection status has really been probed as connected. Connectors that -can't detect the connection status, or failed connection status probes, -should return connector_status_unknown. - Cleanup ------- @@ -463,20 +305,8 @@ created for fetching EDID data and performing monitor detection. Once the process is complete, the new connector is registered with sysfs to make its properties available to applications. -KMS API Functions ------------------ - -.. kernel-doc:: drivers/gpu/drm/drm_crtc.c - :export: - -KMS Data Structures -------------------- - -.. kernel-doc:: include/drm/drm_crtc.h - :internal: - KMS Locking ------------ +=========== .. kernel-doc:: drivers/gpu/drm/drm_modeset_lock.c :doc: kms locking @@ -575,6 +405,12 @@ connector and plane objects by calling the pointer to the target object, a pointer to the previously created property and an initial instance value. +Blending and Z-Position properties +---------------------------------- + +.. kernel-doc:: drivers/gpu/drm/drm_blend.c + :export: + Existing KMS Properties ----------------------- diff --git a/Documentation/gpu/drm-mm.rst b/Documentation/gpu/drm-mm.rst index 59f9822fecd0..bca808535dfd 100644 --- a/Documentation/gpu/drm-mm.rst +++ b/Documentation/gpu/drm-mm.rst @@ -26,12 +26,12 @@ TTM, but has no video RAM management capabilities and is thus limited to UMA devices. The Translation Table Manager (TTM) ------------------------------------ +=================================== TTM design background and information belongs here. TTM initialization -~~~~~~~~~~~~~~~~~~ +------------------ **Warning** @@ -77,7 +77,7 @@ object, ttm_global_item_ref() is used to create an initial reference count for the TTM, which will call your initialization function. The Graphics Execution Manager (GEM) ------------------------------------- +==================================== The GEM design approach has resulted in a memory manager that doesn't provide full coverage of all (or even all common) use cases in its @@ -114,7 +114,7 @@ read & write, mapping, and domain ownership transfers are left to driver-specific ioctls. GEM Initialization -~~~~~~~~~~~~~~~~~~ +------------------ Drivers that use GEM must set the DRIVER_GEM bit in the struct :c:type:`struct drm_driver <drm_driver>` driver_features @@ -132,7 +132,7 @@ typically not managed by GEM, and must be initialized separately into its own DRM MM object. GEM Objects Creation -~~~~~~~~~~~~~~~~~~~~ +-------------------- GEM splits creation of GEM objects and allocation of the memory that backs them in two distinct operations. @@ -173,7 +173,7 @@ a call to :c:func:`drm_gem_private_object_init()` instead of must be managed by drivers. GEM Objects Lifetime -~~~~~~~~~~~~~~~~~~~~ +-------------------- All GEM objects are reference-counted by the GEM core. References can be acquired and release by :c:func:`calling @@ -196,7 +196,7 @@ resources created by the GEM core, which need to be released with :c:func:`drm_gem_object_release()`. GEM Objects Naming -~~~~~~~~~~~~~~~~~~ +------------------ Communication between userspace and the kernel refers to GEM objects using local handles, global names or, more recently, file descriptors. @@ -245,7 +245,7 @@ Furthermore PRIME also allows cross-device buffer sharing since it is based on dma-bufs. GEM Objects Mapping -~~~~~~~~~~~~~~~~~~~ +------------------- Because mapping operations are fairly heavyweight GEM favours read/write-like access to buffers, implemented through driver-specific @@ -304,7 +304,7 @@ Drivers that want to map the GEM object upfront instead of handling page faults can implement their own mmap file operation handler. Memory Coherency -~~~~~~~~~~~~~~~~ +---------------- When mapped to the device or used in a command buffer, backing pages for an object are flushed to memory and marked write combined so as to be @@ -320,7 +320,7 @@ blocks the client and waits for rendering to complete before performing any necessary flushing operations). Command Execution -~~~~~~~~~~~~~~~~~ +----------------- Perhaps the most important GEM function for GPU devices is providing a command execution interface to clients. Client programs construct @@ -348,8 +348,20 @@ GEM Function Reference .. kernel-doc:: include/drm/drm_gem.h :internal: +GEM CMA Helper Functions Reference +---------------------------------- + +.. kernel-doc:: drivers/gpu/drm/drm_gem_cma_helper.c + :doc: cma helpers + +.. kernel-doc:: drivers/gpu/drm/drm_gem_cma_helper.c + :export: + +.. kernel-doc:: include/drm/drm_gem_cma_helper.h + :internal: + VMA Offset Manager ------------------- +================== .. kernel-doc:: drivers/gpu/drm/drm_vma_manager.c :doc: vma offset manager @@ -361,14 +373,14 @@ VMA Offset Manager :internal: PRIME Buffer Sharing --------------------- +==================== PRIME is the cross device buffer sharing framework in drm, originally created for the OPTIMUS range of multi-gpu platforms. To userspace PRIME buffers are dma-buf based file descriptors. Overview and Driver Interface -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +----------------------------- Similar to GEM global names, PRIME file descriptors are also used to share buffer objects across processes. They offer additional security: @@ -406,7 +418,7 @@ struct drm_gem_object \*obj, int flags); struct drm_gem_object \* support PRIME. PRIME Helper Functions -~~~~~~~~~~~~~~~~~~~~~~ +---------------------- .. kernel-doc:: drivers/gpu/drm/drm_prime.c :doc: PRIME Helpers @@ -418,16 +430,16 @@ PRIME Function References :export: DRM MM Range Allocator ----------------------- +====================== Overview -~~~~~~~~ +-------- .. kernel-doc:: drivers/gpu/drm/drm_mm.c :doc: Overview LRU Scan/Eviction Support -~~~~~~~~~~~~~~~~~~~~~~~~~ +------------------------- .. kernel-doc:: drivers/gpu/drm/drm_mm.c :doc: lru scan roaster @@ -440,15 +452,3 @@ DRM MM Range Allocator Function References .. kernel-doc:: include/drm/drm_mm.h :internal: - -CMA Helper Functions Reference ------------------------------- - -.. kernel-doc:: drivers/gpu/drm/drm_gem_cma_helper.c - :doc: cma helpers - -.. kernel-doc:: drivers/gpu/drm/drm_gem_cma_helper.c - :export: - -.. kernel-doc:: include/drm/drm_gem_cma_helper.h - :internal: diff --git a/Documentation/gpu/drm-uapi.rst b/Documentation/gpu/drm-uapi.rst index 536bf3eaadd4..94876938aef3 100644 --- a/Documentation/gpu/drm-uapi.rst +++ b/Documentation/gpu/drm-uapi.rst @@ -33,6 +33,9 @@ Primary Nodes, DRM Master and Authentication .. kernel-doc:: include/drm/drm_auth.h :internal: +Open-Source Userspace Requirements +================================== + Render nodes ============ diff --git a/Documentation/gpu/index.rst b/Documentation/gpu/index.rst index fcac0fa72056..ba92f45abb76 100644 --- a/Documentation/gpu/index.rst +++ b/Documentation/gpu/index.rst @@ -12,3 +12,4 @@ Linux GPU Driver Developer's Guide drm-uapi i915 vga-switcheroo + vgaarbiter diff --git a/Documentation/gpu/vga-switcheroo.rst b/Documentation/gpu/vga-switcheroo.rst index cbbdb994f1dd..463a74fc40d1 100644 --- a/Documentation/gpu/vga-switcheroo.rst +++ b/Documentation/gpu/vga-switcheroo.rst @@ -1,5 +1,3 @@ -.. _vga_switcheroo: - ============== VGA Switcheroo ============== diff --git a/Documentation/gpu/vgaarbiter.rst b/Documentation/gpu/vgaarbiter.rst new file mode 100644 index 000000000000..0b41b051d021 --- /dev/null +++ b/Documentation/gpu/vgaarbiter.rst @@ -0,0 +1,191 @@ +=========== +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-exists on the same machine. But the problem happens +when these devices are trying to be accessed by different userspace clients +(e.g. two server 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> + set the legacy decoding attributes for the card + + poll + event if something changes on any card (not just the target) + + card_ID is of the form "PCI:domain:bus:dev.fn". It can be set to "default" + to go back to the system default card (TODO: not implemented yet). Currently, + only PCI is supported as a prefix, but the userland API may support other bus + types in the future, even if the current kernel implementation doesn't. + +Note about locks: + +The driver keeps track of which user has which locks on which card. It +supports stacking, like the kernel one. This complexifies the implementation +a bit, but makes the arbiter more tolerant to user space problems and able +to properly cleanup in all cases when a process dies. +Currently, a max of 16 cards can have locks simultaneously issued from +user space for a given user (file descriptor instance) of the arbiter. + +In the case of devices hot-{un,}plugged, there is a hook - pci_notify() - to +notify them being added/removed in the system and automatically added/removed +in the arbiter. + +There is also an in-kernel API of the arbiter in case DRM, vgacon, or other +drivers want to use it. + +In-kernel interface +------------------- + +.. kernel-doc:: include/linux/vgaarb.h + :internal: + +.. kernel-doc:: drivers/gpu/vga/vgaarb.c + :export: + +libpciaccess +------------ + +To use the vga arbiter char device it was implemented an API inside the +libpciaccess library. One field was added to struct pci_device (each device +on the system):: + + /* the type of resource decoded by the device */ + int vgaarb_rsrc; + +Besides it, in pci_system were added:: + + int vgaarb_fd; + int vga_count; + struct pci_device *vga_target; + struct pci_device *vga_default_dev; + +The vga_count is used to track how many cards are being arbitrated, so for +instance, if there is only one card, then it can completely escape arbitration. + +These functions below acquire VGA resources for the given card and mark those +resources as locked. If the resources requested are "normal" (and not legacy) +resources, the arbiter will first check whether the card is doing legacy +decoding for that type of resource. If yes, the lock is "converted" into a +legacy resource lock. The arbiter will first look for all VGA cards that +might conflict and disable their IOs and/or Memory access, including VGA +forwarding on P2P bridges if necessary, so that the requested resources can +be used. Then, the card is marked as locking these resources and the IO and/or +Memory access is enabled on the card (including VGA forwarding on parent +P2P bridges if any). In the case of vga_arb_lock(), the function will block +if some conflicting card is already locking one of the required resources (or +any resource on a different bus segment, since P2P bridges don't differentiate +VGA memory and IO afaik). If the card already owns the resources, the function +succeeds. vga_arb_trylock() will return (-EBUSY) instead of blocking. Nested +calls are supported (a per-resource counter is maintained). + +Set the target device of this client. :: + + int pci_device_vgaarb_set_target (struct pci_device *dev); + +For instance, in x86 if two devices on the same bus want to lock different +resources, both will succeed (lock). If devices are in different buses and +trying to lock different resources, only the first who tried succeeds. :: + + int pci_device_vgaarb_lock (void); + int pci_device_vgaarb_trylock (void); + +Unlock resources of device. :: + + int pci_device_vgaarb_unlock (void); + +Indicates to the arbiter if the card decodes legacy VGA IOs, legacy VGA +Memory, both, or none. All cards default to both, the card driver (fbdev for +example) should tell the arbiter if it has disabled legacy decoding, so the +card can be left out of the arbitration process (and can be safe to take +interrupts at any time. :: + + int pci_device_vgaarb_decodes (int new_vgaarb_rsrc); + +Connects to the arbiter device, allocates the struct :: + + int pci_device_vgaarb_init (void); + +Close the connection :: + + void pci_device_vgaarb_fini (void); + +xf86VGAArbiter (X server implementation) +---------------------------------------- + +X server basically wraps all the functions that touch VGA registers somehow. + +References +---------- + +Benjamin Herrenschmidt (IBM?) started this work when he discussed such design +with the Xorg community in 2005 [1, 2]. In the end of 2007, Paulo Zanoni and +Tiago Vignatti (both of C3SL/Federal University of Paraná) proceeded his work +enhancing the kernel code to adapt as a kernel module and also did the +implementation of the user space side [3]. Now (2009) Tiago Vignatti and Dave +Airlie finally put this work in shape and queued to Jesse Barnes' PCI tree. + +0) http://cgit.freedesktop.org/xorg/xserver/commit/?id=4b42448a2388d40f257774fbffdccaea87bd0347 +1) http://lists.freedesktop.org/archives/xorg/2005-March/006663.html +2) http://lists.freedesktop.org/archives/xorg/2005-March/006745.html +3) http://lists.freedesktop.org/archives/xorg/2007-October/029507.html |