diff options
author | Dave Airlie <airlied@redhat.com> | 2015-12-15 10:07:07 +1000 |
---|---|---|
committer | Dave Airlie <airlied@redhat.com> | 2015-12-15 10:40:15 +1000 |
commit | b15c50be96914f84f9afcd6636ecfcd0835a9776 (patch) | |
tree | a35564b6ef69b346c684a0b0499b63fb8f6ba7e7 /Documentation | |
parent | 4526903a308640b40049df8083a0335cd6fb4ae6 (diff) | |
parent | d6e6e14fa61dcabbc05092ea124540280573720c (diff) | |
download | linux-b15c50be96914f84f9afcd6636ecfcd0835a9776.tar.gz linux-b15c50be96914f84f9afcd6636ecfcd0835a9776.tar.bz2 linux-b15c50be96914f84f9afcd6636ecfcd0835a9776.zip |
Merge tag 'topic/drm-misc-2015-12-14' of git://anongit.freedesktop.org/drm-intel into drm-next
Last (very likely at least) drm-misc pull for 4.5. 3 big things:
- piles of docs for kms vtables.
- drm.debug dmesg output prettification from Ville (i915 parts are for 4.6
I think)
- connector mode probing/validating/merging cleanup from Ville.
[airlied : fix drm_encoder_init conflict.]
* tag 'topic/drm-misc-2015-12-14' of git://anongit.freedesktop.org/drm-intel: (43 commits)
drm: modes: Revert cc344980c767 "replace simple_strtoul by kstrtouint"
drm: Expand the drm_helper_probe_single_connector_modes() docs
drm: Allow override_edid to override the firmware EDID
drm/sti: Drop bogus drm_mode_sort() call
drm: Drop drm_helper_probe_single_connector_modes_nomerge()
drm: Only merge mode type bits between new probed modes
drm: Flatten drm_mode_connector_list_update() a bit
drm: Rename MODE_UNVERIFIED to MODE_STALE
drm: Don't overwrite UNVERFIED mode status to OK
drm: Add plane->name and use it in debug prints
drm: Add crtc->name and use it in debug messages
drm: Use driver specified encoder name
drm: Pass 'name' to drm_encoder_init()
drm: Pass 'name' to drm_universal_plane_init()
drm: Pass 'name' to drm_crtc_init_with_planes()
drm: Documentation style guide
drm: Document drm_encoder/crtc_helper_funcs
drm: Move drm_display_mode an related docs into kerneldoc
drm/atomic-helper: Mention the new system/resume helpers the docs
drm: Document drm_connector_helper_funcs
...
Diffstat (limited to 'Documentation')
-rw-r--r-- | Documentation/DocBook/gpu.tmpl | 537 |
1 files changed, 46 insertions, 491 deletions
diff --git a/Documentation/DocBook/gpu.tmpl b/Documentation/DocBook/gpu.tmpl index 03f01e76add7..c66d6412f573 100644 --- a/Documentation/DocBook/gpu.tmpl +++ b/Documentation/DocBook/gpu.tmpl @@ -124,6 +124,43 @@ <para> [Insert diagram of typical DRM stack here] </para> + <sect1> + <title>Style Guidelines</title> + <para> + For consistency this documentation uses American English. Abbreviations + are written as all-uppercase, for example: DRM, KMS, IOCTL, CRTC, and so + on. To aid in reading, documentations make full use of the markup + characters kerneldoc provides: @parameter for function parameters, @member + for structure members, &structure to reference structures and + function() for functions. These all get automatically hyperlinked if + kerneldoc for the referenced objects exists. When referencing entries in + function vtables please use ->vfunc(). Note that kerneldoc does + not support referencing struct members directly, so please add a reference + to the vtable struct somewhere in the same paragraph or at least section. + </para> + <para> + Except in special situations (to separate locked from unlocked variants) + locking requirements for functions aren't documented in the kerneldoc. + Instead locking should be check at runtime using e.g. + <code>WARN_ON(!mutex_is_locked(...));</code>. Since it's much easier to + ignore documentation than runtime noise this provides more value. And on + top of that runtime checks do need to be updated when the locking rules + change, increasing the chances that they're correct. Within the + documentation the locking rules should be explained in the relevant + structures: Either in the comment for the lock explaining what it + protects, or data fields need a note about which lock protects them, or + both. + </para> + <para> + Functions which have a non-<code>void</code> return value should have a + section called "Returns" explaining the expected return values in + different cases and their meanings. Currently there's no consensus whether + that section name should be all upper-case or not, and whether it should + end in a colon or not. Go with the file-local style. Other common section + names are "Notes" with information for dangerous or tricky corner cases, + and "FIXME" where the interface could be cleaned up. + </para> + </sect1> </chapter> <!-- Internals --> @@ -946,6 +983,7 @@ int max_width, max_height;</synopsis> <sect2> <title>Atomic Mode Setting Function Reference</title> !Edrivers/gpu/drm/drm_atomic.c +!Idrivers/gpu/drm/drm_atomic.c </sect2> <sect2> <title>Frame Buffer Creation</title> @@ -1173,137 +1211,6 @@ int max_width, max_height;</synopsis> pointer to CRTC functions. </para> </sect3> - <sect3 id="drm-kms-crtcops"> - <title>CRTC Operations</title> - <sect4> - <title>Set Configuration</title> - <synopsis>int (*set_config)(struct drm_mode_set *set);</synopsis> - <para> - Apply a new CRTC configuration to the device. The configuration - specifies a CRTC, a frame buffer to scan out from, a (x,y) position in - the frame buffer, a display mode and an array of connectors to drive - with the CRTC if possible. - </para> - <para> - If the frame buffer specified in the configuration is NULL, the driver - must detach all encoders connected to the CRTC and all connectors - attached to those encoders and disable them. - </para> - <para> - This operation is called with the mode config lock held. - </para> - <note><para> - Note that the drm core has no notion of restoring the mode setting - state after resume, since all resume handling is in the full - responsibility of the driver. The common mode setting helper library - though provides a helper which can be used for this: - <function>drm_helper_resume_force_mode</function>. - </para></note> - </sect4> - <sect4> - <title>Page Flipping</title> - <synopsis>int (*page_flip)(struct drm_crtc *crtc, struct drm_framebuffer *fb, - struct drm_pending_vblank_event *event);</synopsis> - <para> - Schedule a page flip to the given frame buffer for the CRTC. This - operation is called with the mode config mutex held. - </para> - <para> - Page flipping is a synchronization mechanism that replaces the frame - buffer being scanned out by the CRTC with a new frame buffer during - vertical blanking, avoiding tearing. When an application requests a page - flip the DRM core verifies that the new frame buffer is large enough to - be scanned out by the CRTC in the currently configured mode and then - calls the CRTC <methodname>page_flip</methodname> operation with a - pointer to the new frame buffer. - </para> - <para> - The <methodname>page_flip</methodname> operation schedules a page flip. - Once any pending rendering targeting the new frame buffer has - completed, the CRTC will be reprogrammed to display that frame buffer - after the next vertical refresh. The operation must return immediately - without waiting for rendering or page flip to complete and must block - any new rendering to the frame buffer until the page flip completes. - </para> - <para> - If a page flip can be successfully scheduled the driver must set the - <code>drm_crtc->fb</code> field to the new framebuffer pointed to - by <code>fb</code>. This is important so that the reference counting - on framebuffers stays balanced. - </para> - <para> - If a page flip is already pending, the - <methodname>page_flip</methodname> operation must return - -<errorname>EBUSY</errorname>. - </para> - <para> - To synchronize page flip to vertical blanking the driver will likely - need to enable vertical blanking interrupts. It should call - <function>drm_vblank_get</function> for that purpose, and call - <function>drm_vblank_put</function> after the page flip completes. - </para> - <para> - If the application has requested to be notified when page flip completes - the <methodname>page_flip</methodname> operation will be called with a - non-NULL <parameter>event</parameter> argument pointing to a - <structname>drm_pending_vblank_event</structname> instance. Upon page - flip completion the driver must call <methodname>drm_send_vblank_event</methodname> - to fill in the event and send to wake up any waiting processes. - This can be performed with - <programlisting><![CDATA[ - spin_lock_irqsave(&dev->event_lock, flags); - ... - drm_send_vblank_event(dev, pipe, event); - spin_unlock_irqrestore(&dev->event_lock, flags); - ]]></programlisting> - </para> - <note><para> - FIXME: Could drivers that don't need to wait for rendering to complete - just add the event to <literal>dev->vblank_event_list</literal> and - let the DRM core handle everything, as for "normal" vertical blanking - events? - </para></note> - <para> - While waiting for the page flip to complete, the - <literal>event->base.link</literal> list head can be used freely by - the driver to store the pending event in a driver-specific list. - </para> - <para> - If the file handle is closed before the event is signaled, drivers must - take care to destroy the event in their - <methodname>preclose</methodname> operation (and, if needed, call - <function>drm_vblank_put</function>). - </para> - </sect4> - <sect4> - <title>Miscellaneous</title> - <itemizedlist> - <listitem> - <synopsis>void (*set_property)(struct drm_crtc *crtc, - struct drm_property *property, uint64_t value);</synopsis> - <para> - Set the value of the given CRTC property to - <parameter>value</parameter>. See <xref linkend="drm-kms-properties"/> - for more information about properties. - </para> - </listitem> - <listitem> - <synopsis>void (*gamma_set)(struct drm_crtc *crtc, u16 *r, u16 *g, u16 *b, - uint32_t start, uint32_t size);</synopsis> - <para> - Apply a gamma table to the device. The operation is optional. - </para> - </listitem> - <listitem> - <synopsis>void (*destroy)(struct drm_crtc *crtc);</synopsis> - <para> - Destroy the CRTC when not needed anymore. See - <xref linkend="drm-kms-init"/>. - </para> - </listitem> - </itemizedlist> - </sect4> - </sect3> </sect2> <sect2> <title>Planes (struct <structname>drm_plane</structname>)</title> @@ -1320,7 +1227,7 @@ int max_width, max_height;</synopsis> <listitem> DRM_PLANE_TYPE_PRIMARY represents a "main" plane for a CRTC. Primary planes are the planes operated upon by CRTC modesetting and flipping - operations described in <xref linkend="drm-kms-crtcops"/>. + operations described in the page_flip hook in <structname>drm_crtc_funcs</structname>. </listitem> <listitem> DRM_PLANE_TYPE_CURSOR represents a "cursor" plane for a CRTC. Cursor @@ -1357,52 +1264,6 @@ int max_width, max_height;</synopsis> primary plane with standard capabilities. </para> </sect3> - <sect3> - <title>Plane Operations</title> - <itemizedlist> - <listitem> - <synopsis>int (*update_plane)(struct drm_plane *plane, struct drm_crtc *crtc, - struct drm_framebuffer *fb, int crtc_x, int crtc_y, - unsigned int crtc_w, unsigned int crtc_h, - uint32_t src_x, uint32_t src_y, - uint32_t src_w, uint32_t src_h);</synopsis> - <para> - Enable and configure the plane to use the given CRTC and frame buffer. - </para> - <para> - The source rectangle in frame buffer memory coordinates is given by - the <parameter>src_x</parameter>, <parameter>src_y</parameter>, - <parameter>src_w</parameter> and <parameter>src_h</parameter> - parameters (as 16.16 fixed point values). Devices that don't support - subpixel plane coordinates can ignore the fractional part. - </para> - <para> - The destination rectangle in CRTC coordinates is given by the - <parameter>crtc_x</parameter>, <parameter>crtc_y</parameter>, - <parameter>crtc_w</parameter> and <parameter>crtc_h</parameter> - parameters (as integer values). Devices scale the source rectangle to - the destination rectangle. If scaling is not supported, and the source - rectangle size doesn't match the destination rectangle size, the - driver must return a -<errorname>EINVAL</errorname> error. - </para> - </listitem> - <listitem> - <synopsis>int (*disable_plane)(struct drm_plane *plane);</synopsis> - <para> - Disable the plane. The DRM core calls this method in response to a - DRM_IOCTL_MODE_SETPLANE ioctl call with the frame buffer ID set to 0. - Disabled planes must not be processed by the CRTC. - </para> - </listitem> - <listitem> - <synopsis>void (*destroy)(struct drm_plane *plane);</synopsis> - <para> - Destroy the plane when not needed anymore. See - <xref linkend="drm-kms-init"/>. - </para> - </listitem> - </itemizedlist> - </sect3> </sect2> <sect2> <title>Encoders (struct <structname>drm_encoder</structname>)</title> @@ -1459,27 +1320,6 @@ int max_width, max_height;</synopsis> encoders they want to use to a CRTC. </para> </sect3> - <sect3> - <title>Encoder Operations</title> - <itemizedlist> - <listitem> - <synopsis>void (*destroy)(struct drm_encoder *encoder);</synopsis> - <para> - Called to destroy the encoder when not needed anymore. See - <xref linkend="drm-kms-init"/>. - </para> - </listitem> - <listitem> - <synopsis>void (*set_property)(struct drm_plane *plane, - struct drm_property *property, uint64_t value);</synopsis> - <para> - Set the value of the given plane property to - <parameter>value</parameter>. See <xref linkend="drm-kms-properties"/> - for more information about properties. - </para> - </listitem> - </itemizedlist> - </sect3> </sect2> <sect2> <title>Connectors (struct <structname>drm_connector</structname>)</title> @@ -1683,27 +1523,6 @@ int max_width, max_height;</synopsis> connector_status_unknown. </para> </sect4> - <sect4> - <title>Miscellaneous</title> - <itemizedlist> - <listitem> - <synopsis>void (*set_property)(struct drm_connector *connector, - struct drm_property *property, uint64_t value);</synopsis> - <para> - Set the value of the given connector property to - <parameter>value</parameter>. See <xref linkend="drm-kms-properties"/> - for more information about properties. - </para> - </listitem> - <listitem> - <synopsis>void (*destroy)(struct drm_connector *connector);</synopsis> - <para> - Destroy the connector when not needed anymore. See - <xref linkend="drm-kms-init"/>. - </para> - </listitem> - </itemizedlist> - </sect4> </sect3> </sect2> <sect2> @@ -1830,83 +1649,7 @@ void intel_crt_init(struct drm_device *dev) entities. </para> <sect2> - <title>Helper Functions</title> - <itemizedlist> - <listitem> - <synopsis>int drm_crtc_helper_set_config(struct drm_mode_set *set);</synopsis> - <para> - The <function>drm_crtc_helper_set_config</function> helper function - is a CRTC <methodname>set_config</methodname> implementation. It - first tries to locate the best encoder for each connector by calling - the connector <methodname>best_encoder</methodname> helper - operation. - </para> - <para> - After locating the appropriate encoders, the helper function will - call the <methodname>mode_fixup</methodname> encoder and CRTC helper - operations to adjust the requested mode, or reject it completely in - which case an error will be returned to the application. If the new - configuration after mode adjustment is identical to the current - configuration the helper function will return without performing any - other operation. - </para> - <para> - If the adjusted mode is identical to the current mode but changes to - the frame buffer need to be applied, the - <function>drm_crtc_helper_set_config</function> function will call - the CRTC <methodname>mode_set_base</methodname> helper operation. If - the adjusted mode differs from the current mode, or if the - <methodname>mode_set_base</methodname> helper operation is not - provided, the helper function performs a full mode set sequence by - calling the <methodname>prepare</methodname>, - <methodname>mode_set</methodname> and - <methodname>commit</methodname> CRTC and encoder helper operations, - in that order. - </para> - </listitem> - <listitem> - <synopsis>void drm_helper_connector_dpms(struct drm_connector *connector, int mode);</synopsis> - <para> - The <function>drm_helper_connector_dpms</function> helper function - is a connector <methodname>dpms</methodname> implementation that - tracks power state of connectors. To use the function, drivers must - provide <methodname>dpms</methodname> helper operations for CRTCs - and encoders to apply the DPMS state to the device. - </para> - <para> - The mid-layer doesn't track the power state of CRTCs and encoders. - The <methodname>dpms</methodname> helper operations can thus be - called with a mode identical to the currently active mode. - </para> - </listitem> - <listitem> - <synopsis>int drm_helper_probe_single_connector_modes(struct drm_connector *connector, - uint32_t maxX, uint32_t maxY);</synopsis> - <para> - The <function>drm_helper_probe_single_connector_modes</function> helper - function is a connector <methodname>fill_modes</methodname> - implementation that updates the connection status for the connector - and then retrieves a list of modes by calling the connector - <methodname>get_modes</methodname> helper operation. - </para> - <para> - If the helper operation returns no mode, and if the connector status - is connector_status_connected, standard VESA DMT modes up to - 1024x768 are automatically added to the modes list by a call to - <function>drm_add_modes_noedid</function>. - </para> - <para> - The function then filters out modes larger than - <parameter>max_width</parameter> and <parameter>max_height</parameter> - if specified. It finally calls the optional connector - <methodname>mode_valid</methodname> helper operation for each mode in - the probed list to check whether the mode is valid for the connector. - </para> - </listitem> - </itemizedlist> - </sect2> - <sect2> - <title>CRTC Helper Operations</title> + <title>Legacy CRTC Helper Operations</title> <itemizedlist> <listitem id="drm-helper-crtc-mode-fixup"> <synopsis>bool (*mode_fixup)(struct drm_crtc *crtc, @@ -2052,198 +1795,6 @@ void intel_crt_init(struct drm_device *dev) <function>drm_add_edid_modes</function> manually in that case. </para> <para> - When adding modes manually the driver creates each mode with a call to - <function>drm_mode_create</function> and must fill the following fields. - <itemizedlist> - <listitem> - <synopsis>__u32 type;</synopsis> - <para> - Mode type bitmask, a combination of - <variablelist> - <varlistentry> - <term>DRM_MODE_TYPE_BUILTIN</term> - <listitem><para>not used?</para></listitem> - </varlistentry> - <varlistentry> - <term>DRM_MODE_TYPE_CLOCK_C</term> - <listitem><para>not used?</para></listitem> - </varlistentry> - <varlistentry> - <term>DRM_MODE_TYPE_CRTC_C</term> - <listitem><para>not used?</para></listitem> - </varlistentry> - <varlistentry> - <term> - DRM_MODE_TYPE_PREFERRED - The preferred mode for the connector - </term> - <listitem> - <para>not used?</para> - </listitem> - </varlistentry> - <varlistentry> - <term>DRM_MODE_TYPE_DEFAULT</term> - <listitem><para>not used?</para></listitem> - </varlistentry> - <varlistentry> - <term>DRM_MODE_TYPE_USERDEF</term> - <listitem><para>not used?</para></listitem> - </varlistentry> - <varlistentry> - <term>DRM_MODE_TYPE_DRIVER</term> - <listitem> - <para> - The mode has been created by the driver (as opposed to - to user-created modes). - </para> - </listitem> - </varlistentry> - </variablelist> - Drivers must set the DRM_MODE_TYPE_DRIVER bit for all modes they - create, and set the DRM_MODE_TYPE_PREFERRED bit for the preferred - mode. - </para> - </listitem> - <listitem> - <synopsis>__u32 clock;</synopsis> - <para>Pixel clock frequency in kHz unit</para> - </listitem> - <listitem> - <synopsis>__u16 hdisplay, hsync_start, hsync_end, htotal; - __u16 vdisplay, vsync_start, vsync_end, vtotal;</synopsis> - <para>Horizontal and vertical timing information</para> - <screen><![CDATA[ - Active Front Sync Back - Region Porch Porch - <-----------------------><----------------><-------------><--------------> - - //////////////////////| - ////////////////////// | - ////////////////////// |.................. ................ - _______________ - - <----- [hv]display -----> - <------------- [hv]sync_start ------------> - <--------------------- [hv]sync_end ---------------------> - <-------------------------------- [hv]total -----------------------------> -]]></screen> - </listitem> - <listitem> - <synopsis>__u16 hskew; - __u16 vscan;</synopsis> - <para>Unknown</para> - </listitem> - <listitem> - <synopsis>__u32 flags;</synopsis> - <para> - Mode flags, a combination of - <variablelist> - <varlistentry> - <term>DRM_MODE_FLAG_PHSYNC</term> - <listitem><para> - Horizontal sync is active high - </para></listitem> - </varlistentry> - <varlistentry> - <term>DRM_MODE_FLAG_NHSYNC</term> - <listitem><para> - Horizontal sync is active low - </para></listitem> - </varlistentry> - <varlistentry> - <term>DRM_MODE_FLAG_PVSYNC</term> - <listitem><para> - Vertical sync is active high - </para></listitem> - </varlistentry> - <varlistentry> - <term>DRM_MODE_FLAG_NVSYNC</term> - <listitem><para> - Vertical sync is active low - </para></listitem> - </varlistentry> - <varlistentry> - <term>DRM_MODE_FLAG_INTERLACE</term> - <listitem><para> - Mode is interlaced - </para></listitem> - </varlistentry> - <varlistentry> - <term>DRM_MODE_FLAG_DBLSCAN</term> - <listitem><para> - Mode uses doublescan - </para></listitem> - </varlistentry> - <varlistentry> - <term>DRM_MODE_FLAG_CSYNC</term> - <listitem><para> - Mode uses composite sync - </para></listitem> - </varlistentry> - <varlistentry> - <term>DRM_MODE_FLAG_PCSYNC</term> - <listitem><para> - Composite sync is active high - </para></listitem> - </varlistentry> - <varlistentry> - <term>DRM_MODE_FLAG_NCSYNC</term> - <listitem><para> - Composite sync is active low - </para></listitem> - </varlistentry> - <varlistentry> - <term>DRM_MODE_FLAG_HSKEW</term> - <listitem><para> - hskew provided (not used?) - </para></listitem> - </varlistentry> - <varlistentry> - <term>DRM_MODE_FLAG_BCAST</term> - <listitem><para> - not used? - </para></listitem> - </varlistentry> - <varlistentry> - <term>DRM_MODE_FLAG_PIXMUX</term> - <listitem><para> - not used? - </para></listitem> - </varlistentry> - <varlistentry> - <term>DRM_MODE_FLAG_DBLCLK</term> - <listitem><para> - not used? - </para></listitem> - </varlistentry> - <varlistentry> - <term>DRM_MODE_FLAG_CLKDIV2</term> - <listitem><para> - ? - </para></listitem> - </varlistentry> - </variablelist> - </para> - <para> - Note that modes marked with the INTERLACE or DBLSCAN flags will be - filtered out by - <function>drm_helper_probe_single_connector_modes</function> if - the connector's <structfield>interlace_allowed</structfield> or - <structfield>doublescan_allowed</structfield> field is set to 0. - </para> - </listitem> - <listitem> - <synopsis>char name[DRM_DISPLAY_MODE_LEN];</synopsis> - <para> - Mode name. The driver must call - <function>drm_mode_set_name</function> to fill the mode name from - <structfield>hdisplay</structfield>, - <structfield>vdisplay</structfield> and interlace flag after - filling the corresponding fields. - </para> - </listitem> - </itemizedlist> - </para> - <para> The <structfield>vrefresh</structfield> value is computed by <function>drm_helper_probe_single_connector_modes</function>. </para> @@ -2303,8 +1854,12 @@ void intel_crt_init(struct drm_device *dev) !Edrivers/gpu/drm/drm_atomic_helper.c </sect2> <sect2> - <title>Modeset Helper Functions Reference</title> -!Iinclude/drm/drm_crtc_helper.h + <title>Modeset Helper Reference for Common Vtables</title> +!Iinclude/drm/drm_modeset_helper_vtables.h +!Pinclude/drm/drm_modeset_helper_vtables.h overview + </sect2> + <sect2> + <title>Legacy CRTC/Modeset Helper Functions Reference</title> !Edrivers/gpu/drm/drm_crtc_helper.c !Pdrivers/gpu/drm/drm_crtc_helper.c overview </sect2> |