From 092d01dae09aa6779ed41c3ac637e1e3c835424b Mon Sep 17 00:00:00 2001 From: Daniel Vetter Date: Fri, 4 Dec 2015 09:45:44 +0100 Subject: drm: Reorganize helper vtables and their docs Currently we have 4 helper libraries (probe, crtc, plane & atomic) that all use the same helper vtables. And that's by necessity since we don't want to litter the core structs with one ops pointer per helper library. Also often the reuse the same hooks (like atomic does, to facilite conversion from existing drivers using crtc and plane helpers). Given all that it doesn't make sense to put the docs for these next to specific helpers. Instead extract them into a new header file and section in the docbook, and add references to them everywhere. Unfortunately kernel-doc complains when an include directive doesn't find anything (and it does by dumping crap into the output file). We have to remove the now empty includes to avoid that, instead of leaving them in for future proofing. v2: More OCD in ordering functions. v3: Spelling plus collate copyright headers properly. Signed-off-by: Daniel Vetter Link: http://patchwork.freedesktop.org/patch/msgid/1449218769-16577-4-git-send-email-daniel.vetter@ffwll.ch Reviewed-by: Thierry Reding --- Documentation/DocBook/gpu.tmpl | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) (limited to 'Documentation/DocBook') diff --git a/Documentation/DocBook/gpu.tmpl b/Documentation/DocBook/gpu.tmpl index 03f01e7..bd608d0 100644 --- a/Documentation/DocBook/gpu.tmpl +++ b/Documentation/DocBook/gpu.tmpl @@ -2303,8 +2303,12 @@ void intel_crt_init(struct drm_device *dev) !Edrivers/gpu/drm/drm_atomic_helper.c + Modeset Helper Reference for Common Vtables +!Iinclude/drm/drm_modeset_helper_vtables.h +!Pinclude/drm/drm_modeset_helper_vtables.h overview + + Modeset Helper Functions Reference -!Iinclude/drm/drm_crtc_helper.h !Edrivers/gpu/drm/drm_crtc_helper.c !Pdrivers/gpu/drm/drm_crtc_helper.c overview -- cgit v1.1 From 2be94971c759da872efce99fa823ea17cdb7cc8b Mon Sep 17 00:00:00 2001 From: Daniel Vetter Date: Fri, 4 Dec 2015 09:45:46 +0100 Subject: drm: Merge helper docbook into kerneldoc comments Duplication is bad, luckily both help texts highlighted different issues so the kerneldoc gained quite a bit! While at it also sprinkle more references to the vtable structs around and make it clear that legacy CRTC helpers are deprecated and which functions to use instead. v2: Spelling fixes and polish (Thierry). Signed-off-by: Daniel Vetter Link: http://patchwork.freedesktop.org/patch/msgid/1449218769-16577-6-git-send-email-daniel.vetter@ffwll.ch Reviewed-by: Thierry Reding --- Documentation/DocBook/gpu.tmpl | 80 ++---------------------------------------- 1 file changed, 2 insertions(+), 78 deletions(-) (limited to 'Documentation/DocBook') diff --git a/Documentation/DocBook/gpu.tmpl b/Documentation/DocBook/gpu.tmpl index bd608d0..4b5de72 100644 --- a/Documentation/DocBook/gpu.tmpl +++ b/Documentation/DocBook/gpu.tmpl @@ -1830,83 +1830,7 @@ void intel_crt_init(struct drm_device *dev) entities. - Helper Functions - - - int drm_crtc_helper_set_config(struct drm_mode_set *set); - - The drm_crtc_helper_set_config helper function - is a CRTC set_config implementation. It - first tries to locate the best encoder for each connector by calling - the connector best_encoder helper - operation. - - - After locating the appropriate encoders, the helper function will - call the mode_fixup 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. - - - If the adjusted mode is identical to the current mode but changes to - the frame buffer need to be applied, the - drm_crtc_helper_set_config function will call - the CRTC mode_set_base helper operation. If - the adjusted mode differs from the current mode, or if the - mode_set_base helper operation is not - provided, the helper function performs a full mode set sequence by - calling the prepare, - mode_set and - commit CRTC and encoder helper operations, - in that order. - - - - void drm_helper_connector_dpms(struct drm_connector *connector, int mode); - - The drm_helper_connector_dpms helper function - is a connector dpms implementation that - tracks power state of connectors. To use the function, drivers must - provide dpms helper operations for CRTCs - and encoders to apply the DPMS state to the device. - - - The mid-layer doesn't track the power state of CRTCs and encoders. - The dpms helper operations can thus be - called with a mode identical to the currently active mode. - - - - int drm_helper_probe_single_connector_modes(struct drm_connector *connector, - uint32_t maxX, uint32_t maxY); - - The drm_helper_probe_single_connector_modes helper - function is a connector fill_modes - implementation that updates the connection status for the connector - and then retrieves a list of modes by calling the connector - get_modes helper operation. - - - 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 - drm_add_modes_noedid. - - - The function then filters out modes larger than - max_width and max_height - if specified. It finally calls the optional connector - mode_valid helper operation for each mode in - the probed list to check whether the mode is valid for the connector. - - - - - - CRTC Helper Operations + Legacy CRTC Helper Operations bool (*mode_fixup)(struct drm_crtc *crtc, @@ -2308,7 +2232,7 @@ void intel_crt_init(struct drm_device *dev) !Pinclude/drm/drm_modeset_helper_vtables.h overview - Modeset Helper Functions Reference + Legacy CRTC/Modeset Helper Functions Reference !Edrivers/gpu/drm/drm_crtc_helper.c !Pdrivers/gpu/drm/drm_crtc_helper.c overview -- cgit v1.1 From 88548636406c08ef4b3d32d12d1860a216389177 Mon Sep 17 00:00:00 2001 From: Daniel Vetter Date: Fri, 4 Dec 2015 09:45:48 +0100 Subject: drm: Update drm_plane_funcs kerneldoc - Merge the docbook into the kerneldoc comments. - Spec in detail the precise semantics of the callbacks. - For consistency in wording and easier review roll out kerneldoc also for crtc, encoder and connector for the standard hooks they share with planes. v2: Suggestions from Thierry. Signed-off-by: Daniel Vetter Link: http://patchwork.freedesktop.org/patch/msgid/1449218769-16577-8-git-send-email-daniel.vetter@ffwll.ch Reviewed-by: Thierry Reding --- Documentation/DocBook/gpu.tmpl | 104 ----------------------------------------- 1 file changed, 104 deletions(-) (limited to 'Documentation/DocBook') diff --git a/Documentation/DocBook/gpu.tmpl b/Documentation/DocBook/gpu.tmpl index 4b5de72..79cdc12 100644 --- a/Documentation/DocBook/gpu.tmpl +++ b/Documentation/DocBook/gpu.tmpl @@ -1279,28 +1279,12 @@ int max_width, max_height; Miscellaneous - void (*set_property)(struct drm_crtc *crtc, - struct drm_property *property, uint64_t value); - - Set the value of the given CRTC property to - value. See - for more information about properties. - - - void (*gamma_set)(struct drm_crtc *crtc, u16 *r, u16 *g, u16 *b, uint32_t start, uint32_t size); Apply a gamma table to the device. The operation is optional. - - void (*destroy)(struct drm_crtc *crtc); - - Destroy the CRTC when not needed anymore. See - . - - @@ -1357,52 +1341,6 @@ int max_width, max_height; primary plane with standard capabilities. - - Plane Operations - - - 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); - - Enable and configure the plane to use the given CRTC and frame buffer. - - - The source rectangle in frame buffer memory coordinates is given by - the src_x, src_y, - src_w and src_h - parameters (as 16.16 fixed point values). Devices that don't support - subpixel plane coordinates can ignore the fractional part. - - - The destination rectangle in CRTC coordinates is given by the - crtc_x, crtc_y, - crtc_w and crtc_h - 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 -EINVAL error. - - - - int (*disable_plane)(struct drm_plane *plane); - - 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. - - - - void (*destroy)(struct drm_plane *plane); - - Destroy the plane when not needed anymore. See - . - - - - Encoders (struct <structname>drm_encoder</structname>) @@ -1459,27 +1397,6 @@ int max_width, max_height; encoders they want to use to a CRTC. - - Encoder Operations - - - void (*destroy)(struct drm_encoder *encoder); - - Called to destroy the encoder when not needed anymore. See - . - - - - void (*set_property)(struct drm_plane *plane, - struct drm_property *property, uint64_t value); - - Set the value of the given plane property to - value. See - for more information about properties. - - - - Connectors (struct <structname>drm_connector</structname>) @@ -1683,27 +1600,6 @@ int max_width, max_height; connector_status_unknown. - - Miscellaneous - - - void (*set_property)(struct drm_connector *connector, - struct drm_property *property, uint64_t value); - - Set the value of the given connector property to - value. See - for more information about properties. - - - - void (*destroy)(struct drm_connector *connector); - - Destroy the connector when not needed anymore. See - . - - - - -- cgit v1.1 From c0714fc907db3c427d2153b68bd29eb6d40c44fd Mon Sep 17 00:00:00 2001 From: Daniel Vetter Date: Fri, 4 Dec 2015 09:45:57 +0100 Subject: drm: Document drm_atomic_*_get_property Yes these are internal functions and not exported and we generally don't document them. But for symmetry with the _set_property functions (which are exported for the atomic helpers) I'd like to document them. Upcoming vtable kerneldoc will reference both the set and get_property functions. v2: Suggestions from Thierry. Signed-off-by: Daniel Vetter Reviewed-by: Thierry Reding Link: http://patchwork.freedesktop.org/patch/msgid/1449218769-16577-17-git-send-email-daniel.vetter@ffwll.ch --- Documentation/DocBook/gpu.tmpl | 1 + 1 file changed, 1 insertion(+) (limited to 'Documentation/DocBook') diff --git a/Documentation/DocBook/gpu.tmpl b/Documentation/DocBook/gpu.tmpl index 79cdc12..be06c9b 100644 --- a/Documentation/DocBook/gpu.tmpl +++ b/Documentation/DocBook/gpu.tmpl @@ -946,6 +946,7 @@ int max_width, max_height; Atomic Mode Setting Function Reference !Edrivers/gpu/drm/drm_atomic.c +!Idrivers/gpu/drm/drm_atomic.c Frame Buffer Creation -- cgit v1.1 From f6da8c6e5ee378c82f20ad07f84556befc7b58e9 Mon Sep 17 00:00:00 2001 From: Daniel Vetter Date: Fri, 4 Dec 2015 09:46:00 +0100 Subject: drm: document drm_crtc_funcs And merge any docbook we have into the kerneldoc comments. Since it's a legacy entry point with only two implementation (one each in atomic and legacy crtc helpers) I've made the documentation for set_config fairly sparse - no one should ever need to look at this again, all the ABI we have is baked into code. For ->page_flip otoh I kept all the extensive docs from the docbook and even extended it where it was lacking: Currently we have a pile of legacy page_flip implemantations, and even for atomic drivers there's not yet a standard implementation in the helpers. Which means every driver needs to implement this itself, and precise specs are really valuable. Otherwise there's just cursor, which really just boils down to "use at least universal planes". And gamma tables (where we have a bit a mess with the fbdev helper gamma hooks). v2: Spelling fixes (Eric). v3: Suggestions from Thierry. Cc: Eric Anholt Signed-off-by: Daniel Vetter Link: http://patchwork.freedesktop.org/patch/msgid/1449218769-16577-20-git-send-email-daniel.vetter@ffwll.ch --- Documentation/DocBook/gpu.tmpl | 117 +---------------------------------------- 1 file changed, 1 insertion(+), 116 deletions(-) (limited to 'Documentation/DocBook') diff --git a/Documentation/DocBook/gpu.tmpl b/Documentation/DocBook/gpu.tmpl index be06c9b..0ca010d 100644 --- a/Documentation/DocBook/gpu.tmpl +++ b/Documentation/DocBook/gpu.tmpl @@ -1174,121 +1174,6 @@ int max_width, max_height; pointer to CRTC functions. - - CRTC Operations - - Set Configuration - int (*set_config)(struct drm_mode_set *set); - - 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. - - - 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. - - - This operation is called with the mode config lock held. - - - 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: - drm_helper_resume_force_mode. - - - - Page Flipping - int (*page_flip)(struct drm_crtc *crtc, struct drm_framebuffer *fb, - struct drm_pending_vblank_event *event); - - Schedule a page flip to the given frame buffer for the CRTC. This - operation is called with the mode config mutex held. - - - 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 page_flip operation with a - pointer to the new frame buffer. - - - The page_flip 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. - - - If a page flip can be successfully scheduled the driver must set the - drm_crtc->fb field to the new framebuffer pointed to - by fb. This is important so that the reference counting - on framebuffers stays balanced. - - - If a page flip is already pending, the - page_flip operation must return - -EBUSY. - - - To synchronize page flip to vertical blanking the driver will likely - need to enable vertical blanking interrupts. It should call - drm_vblank_get for that purpose, and call - drm_vblank_put after the page flip completes. - - - If the application has requested to be notified when page flip completes - the page_flip operation will be called with a - non-NULL event argument pointing to a - drm_pending_vblank_event instance. Upon page - flip completion the driver must call drm_send_vblank_event - to fill in the event and send to wake up any waiting processes. - This can be performed with - event_lock, flags); - ... - drm_send_vblank_event(dev, pipe, event); - spin_unlock_irqrestore(&dev->event_lock, flags); - ]]> - - - FIXME: Could drivers that don't need to wait for rendering to complete - just add the event to dev->vblank_event_list and - let the DRM core handle everything, as for "normal" vertical blanking - events? - - - While waiting for the page flip to complete, the - event->base.link list head can be used freely by - the driver to store the pending event in a driver-specific list. - - - If the file handle is closed before the event is signaled, drivers must - take care to destroy the event in their - preclose operation (and, if needed, call - drm_vblank_put). - - - - Miscellaneous - - - void (*gamma_set)(struct drm_crtc *crtc, u16 *r, u16 *g, u16 *b, - uint32_t start, uint32_t size); - - Apply a gamma table to the device. The operation is optional. - - - - - Planes (struct <structname>drm_plane</structname>) @@ -1305,7 +1190,7 @@ int max_width, max_height; 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 . + operations described in the page_flip hook in drm_crtc_funcs. DRM_PLANE_TYPE_CURSOR represents a "cursor" plane for a CRTC. Cursor -- cgit v1.1 From 30ecad77fe849b60c9a1f8df24dca50e3f083d41 Mon Sep 17 00:00:00 2001 From: Daniel Vetter Date: Wed, 9 Dec 2015 09:29:36 +0100 Subject: drm: Move drm_display_mode an related docs into kerneldoc MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This was in the documentation for modeset helper hooks, where it is a bit misplaced. v2: Reindent the drm_mode_status enum, inspired by Ville. v3: Suggestions from Ville and Thierry. v4: Small fixup that 0day spotted. v5: Slight change to avoid accidental headings in kerneldoc output. Cc: ville.syrjala@linux.intel.com Signed-off-by: Daniel Vetter Link: http://patchwork.freedesktop.org/patch/msgid/1449218769-16577-27-git-send-email-daniel.vetter@ffwll.ch Reviewed-by: Ville Syrjälä (v3) Reviewed-by: Thierry Reding (v3) --- Documentation/DocBook/gpu.tmpl | 192 ----------------------------------------- 1 file changed, 192 deletions(-) (limited to 'Documentation/DocBook') diff --git a/Documentation/DocBook/gpu.tmpl b/Documentation/DocBook/gpu.tmpl index 0ca010d..749b8e2 100644 --- a/Documentation/DocBook/gpu.tmpl +++ b/Documentation/DocBook/gpu.tmpl @@ -1758,198 +1758,6 @@ void intel_crt_init(struct drm_device *dev) drm_add_edid_modes manually in that case. - When adding modes manually the driver creates each mode with a call to - drm_mode_create and must fill the following fields. - - - __u32 type; - - Mode type bitmask, a combination of - - - DRM_MODE_TYPE_BUILTIN - not used? - - - DRM_MODE_TYPE_CLOCK_C - not used? - - - DRM_MODE_TYPE_CRTC_C - not used? - - - - DRM_MODE_TYPE_PREFERRED - The preferred mode for the connector - - - not used? - - - - DRM_MODE_TYPE_DEFAULT - not used? - - - DRM_MODE_TYPE_USERDEF - not used? - - - DRM_MODE_TYPE_DRIVER - - - The mode has been created by the driver (as opposed to - to user-created modes). - - - - - 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. - - - - __u32 clock; - Pixel clock frequency in kHz unit - - - __u16 hdisplay, hsync_start, hsync_end, htotal; - __u16 vdisplay, vsync_start, vsync_end, vtotal; - Horizontal and vertical timing information - <----------------><-------------><--------------> - - //////////////////////| - ////////////////////// | - ////////////////////// |.................. ................ - _______________ - - <----- [hv]display -----> - <------------- [hv]sync_start ------------> - <--------------------- [hv]sync_end ---------------------> - <-------------------------------- [hv]total -----------------------------> -]]> - - - __u16 hskew; - __u16 vscan; - Unknown - - - __u32 flags; - - Mode flags, a combination of - - - DRM_MODE_FLAG_PHSYNC - - Horizontal sync is active high - - - - DRM_MODE_FLAG_NHSYNC - - Horizontal sync is active low - - - - DRM_MODE_FLAG_PVSYNC - - Vertical sync is active high - - - - DRM_MODE_FLAG_NVSYNC - - Vertical sync is active low - - - - DRM_MODE_FLAG_INTERLACE - - Mode is interlaced - - - - DRM_MODE_FLAG_DBLSCAN - - Mode uses doublescan - - - - DRM_MODE_FLAG_CSYNC - - Mode uses composite sync - - - - DRM_MODE_FLAG_PCSYNC - - Composite sync is active high - - - - DRM_MODE_FLAG_NCSYNC - - Composite sync is active low - - - - DRM_MODE_FLAG_HSKEW - - hskew provided (not used?) - - - - DRM_MODE_FLAG_BCAST - - not used? - - - - DRM_MODE_FLAG_PIXMUX - - not used? - - - - DRM_MODE_FLAG_DBLCLK - - not used? - - - - DRM_MODE_FLAG_CLKDIV2 - - ? - - - - - - Note that modes marked with the INTERLACE or DBLSCAN flags will be - filtered out by - drm_helper_probe_single_connector_modes if - the connector's interlace_allowed or - doublescan_allowed field is set to 0. - - - - char name[DRM_DISPLAY_MODE_LEN]; - - Mode name. The driver must call - drm_mode_set_name to fill the mode name from - hdisplay, - vdisplay and interlace flag after - filling the corresponding fields. - - - - - The vrefresh value is computed by drm_helper_probe_single_connector_modes. -- cgit v1.1 From fb9f7a6b0673ac65e7345b0a96b159708d413ee3 Mon Sep 17 00:00:00 2001 From: Daniel Vetter Date: Tue, 8 Dec 2015 09:49:17 +0100 Subject: drm: Documentation style guide Every time I type or review docs this seems a bit different. Try to document the common style so we can try to unify at least new docs. v2: Spelling fixes from Pierre, Laurent and Jani. v3: More spelling fixes from Lukas. Cc: Pierre Moreau Cc: Jani Nikula Cc: Laurent Pinchart Cc: Lukas Wunner Acked-by: Laurent Pinchart Signed-off-by: Daniel Vetter Link: http://patchwork.freedesktop.org/patch/msgid/1449564561-3896-1-git-send-email-daniel.vetter@ffwll.ch --- Documentation/DocBook/gpu.tmpl | 37 +++++++++++++++++++++++++++++++++++++ 1 file changed, 37 insertions(+) (limited to 'Documentation/DocBook') diff --git a/Documentation/DocBook/gpu.tmpl b/Documentation/DocBook/gpu.tmpl index 749b8e2..c66d641 100644 --- a/Documentation/DocBook/gpu.tmpl +++ b/Documentation/DocBook/gpu.tmpl @@ -124,6 +124,43 @@ [Insert diagram of typical DRM stack here] + + Style Guidelines + + 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. + + + 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. + WARN_ON(!mutex_is_locked(...));. 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. + + + Functions which have a non-void 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. + + -- cgit v1.1 From f03d8ede7a901d2425da5c21a91f6a76fe16b47f Mon Sep 17 00:00:00 2001 From: Danilo Cesar Lemes de Paula Date: Wed, 25 Nov 2015 18:07:55 +0100 Subject: drm/doc: Convert to markdown DRM Docbook is now Markdown ready. This means its doc is able to use markdown text on it. * Documentation/DocBook/drm.tmpl: Contains a table duplicated from drivers/gpu/drm/i915/i915_reg.h. This is not needed anymore * drivers/gpu/drm/drm_modeset_lock.c: had a code example that used to look pretty bad on html. Fixed by using proper code markup. * drivers/gpu/drm/drm_prime.c: Remove spaces between lines to make a proper markup list. * drivers/gpu/drm/i915/i915_reg.h: Altought pandoc supports tables, it doesn't support table cell spanning. But we can use fixed-width for those special cases. * include/drm/drm_vma_manager.h: Another code example that should be proper indented with four spaces. v2 (Daniel): Adjust name to gpu.xml due to rename. v3 (Daniel): Split out the actual enabling in the Makefile - this way we can merge the conversion, while just keeping the enabling in a drm-private tree. Signed-off-by: Danilo Cesar Lemes de Paula (v1) Cc: Randy Dunlap Cc: Daniel Vetter Cc: Laurent Pinchart Cc: Jonathan Corbet Cc: Herbert Xu Cc: Stephan Mueller Cc: Michal Marek Cc: linux-kernel@vger.kernel.org Cc: linux-doc@vger.kernel.org Cc: intel-gfx Cc: dri-devel Acked-by: Dave Airlie Signed-off-by: Daniel Vetter Link: http://patchwork.freedesktop.org/patch/msgid/1448471279-19748-2-git-send-email-daniel.vetter@ffwll.ch --- Documentation/DocBook/gpu.tmpl | 86 ------------------------------------------ 1 file changed, 86 deletions(-) (limited to 'Documentation/DocBook') diff --git a/Documentation/DocBook/gpu.tmpl b/Documentation/DocBook/gpu.tmpl index c66d641..a27bdf9 100644 --- a/Documentation/DocBook/gpu.tmpl +++ b/Documentation/DocBook/gpu.tmpl @@ -3570,92 +3570,6 @@ int num_ioctls; DPIO !Pdrivers/gpu/drm/i915/i915_reg.h DPIO - - Dual channel PHY (VLV/CHV/BXT) - - - - - - - - - - - - - - - - - - CH0 - CH1 - - - - - CMN/PLL/REF - CMN/PLL/REF - - - PCS01 - PCS23 - PCS01 - PCS23 - - - TX0 - TX1 - TX2 - TX3 - TX0 - TX1 - TX2 - TX3 - - - DDI0 - DDI1 - - - -
- - Single channel PHY (CHV/BXT) - - - - - - - - - - - CH0 - - - - - CMN/PLL/REF - - - PCS01 - PCS23 - - - TX0 - TX1 - TX2 - TX3 - - - DDI2 - - - -
-- cgit v1.1 From d55f5320c7811d3858edaef5f2d4a9a7e43b1af8 Mon Sep 17 00:00:00 2001 From: Daniel Vetter Date: Tue, 8 Dec 2015 09:49:19 +0100 Subject: drm: Move more framebuffer doc from docbook to kerneldoc I missed a few paragraphs in the docbook that need to be pulled into the fbdev vfunc docs. v2: Spelling fixes from Thierry. Cc: Thierry Reding Link: http://patchwork.freedesktop.org/patch/msgid/1449564561-3896-3-git-send-email-daniel.vetter@ffwll.ch Reviewed-by: Thierry Reding Signed-off-by: Daniel Vetter --- Documentation/DocBook/gpu.tmpl | 72 +----------------------------------------- 1 file changed, 1 insertion(+), 71 deletions(-) (limited to 'Documentation/DocBook') diff --git a/Documentation/DocBook/gpu.tmpl b/Documentation/DocBook/gpu.tmpl index a27bdf9..6c6e81a 100644 --- a/Documentation/DocBook/gpu.tmpl +++ b/Documentation/DocBook/gpu.tmpl @@ -986,10 +986,7 @@ int max_width, max_height; !Idrivers/gpu/drm/drm_atomic.c - Frame Buffer Creation - struct drm_framebuffer *(*fb_create)(struct drm_device *dev, - struct drm_file *file_priv, - struct drm_mode_fb_cmd2 *mode_cmd); + Frame Buffer Abstraction Frame buffers are abstract memory objects that provide a source of pixels to scanout to a CRTC. Applications explicitly request the @@ -1008,73 +1005,6 @@ int max_width, max_height; and so expects TTM handles in the create ioctl and not GEM handles. - Drivers must first validate the requested frame buffer parameters passed - through the mode_cmd argument. In particular this is where invalid - sizes, pixel formats or pitches can be caught. - - - If the parameters are deemed valid, drivers then create, initialize and - return an instance of struct drm_framebuffer. - If desired the instance can be embedded in a larger driver-specific - structure. Drivers must fill its width, - height, pitches, - offsets, depth, - bits_per_pixel and - pixel_format fields from the values passed - through the drm_mode_fb_cmd2 argument. They - should call the drm_helper_mode_fill_fb_struct - helper function to do so. - - - - The initialization of the new framebuffer instance is finalized with a - call to drm_framebuffer_init which takes a pointer - to DRM frame buffer operations (struct - drm_framebuffer_funcs). Note that this function - publishes the framebuffer and so from this point on it can be accessed - concurrently from other threads. Hence it must be the last step in the - driver's framebuffer initialization sequence. Frame buffer operations - are - - - int (*create_handle)(struct drm_framebuffer *fb, - struct drm_file *file_priv, unsigned int *handle); - - Create a handle to the frame buffer underlying memory object. If - the frame buffer uses a multi-plane format, the handle will - reference the memory object associated with the first plane. - - - Drivers call drm_gem_handle_create to create - the handle. - - - - void (*destroy)(struct drm_framebuffer *framebuffer); - - Destroy the frame buffer object and frees all associated - resources. Drivers must call - drm_framebuffer_cleanup to free resources - allocated by the DRM core for the frame buffer object, and must - make sure to unreference all memory objects associated with the - frame buffer. Handles created by the - create_handle operation are released by - the DRM core. - - - - int (*dirty)(struct drm_framebuffer *framebuffer, - struct drm_file *file_priv, unsigned flags, unsigned color, - struct drm_clip_rect *clips, unsigned num_clips); - - This optional operation notifies the driver that a region of the - frame buffer has changed in response to a DRM_IOCTL_MODE_DIRTYFB - ioctl call. - - - - - The lifetime of a drm framebuffer is controlled with a reference count, drivers can grab additional references with drm_framebuffer_referenceand drop them -- cgit v1.1 From 3a848662c75118e1ee4653e08e25943d8b4ab8b7 Mon Sep 17 00:00:00 2001 From: Lukas Wunner Date: Sat, 2 Jan 2016 18:47:17 +0100 Subject: vga_switcheroo: Prettify documentation Fix indentation of vga_switcheroo sections in gpu.tmpl. Change section type of API documentation from "chapter" to "sect1" so that the individual functions no longer clutter up the ToC. Group together under a new "API" chapter. Fix wording "heretoforth" -> "henceforth". Signed-off-by: Lukas Wunner Signed-off-by: Daniel Vetter --- Documentation/DocBook/gpu.tmpl | 40 ++++++++++++++++++++-------------------- 1 file changed, 20 insertions(+), 20 deletions(-) (limited to 'Documentation/DocBook') diff --git a/Documentation/DocBook/gpu.tmpl b/Documentation/DocBook/gpu.tmpl index 6c6e81a..225a246 100644 --- a/Documentation/DocBook/gpu.tmpl +++ b/Documentation/DocBook/gpu.tmpl @@ -3625,37 +3625,37 @@ int num_ioctls; Modes of Use - - Manual switching and manual power control + + Manual switching and manual power control !Pdrivers/gpu/vga/vga_switcheroo.c Manual switching and manual power control - - - Driver power control + + + Driver power control !Pdrivers/gpu/vga/vga_switcheroo.c Driver power control - + - - Public functions + + API + + Public functions !Edrivers/gpu/vga/vga_switcheroo.c - - - - Public structures + + + Public structures !Finclude/linux/vga_switcheroo.h vga_switcheroo_handler !Finclude/linux/vga_switcheroo.h vga_switcheroo_client_ops - - - - Public constants + + + Public constants !Finclude/linux/vga_switcheroo.h vga_switcheroo_client_id !Finclude/linux/vga_switcheroo.h vga_switcheroo_state - - - - Private structures + + + Private structures !Fdrivers/gpu/vga/vga_switcheroo.c vgasr_priv !Fdrivers/gpu/vga/vga_switcheroo.c vga_switcheroo_client + !Cdrivers/gpu/vga/vga_switcheroo.c -- cgit v1.1 From df7d678bea8ba8904bdb293c8e96aa9488f7dbee Mon Sep 17 00:00:00 2001 From: Daniel Vetter Date: Mon, 4 Jan 2016 07:53:36 +0100 Subject: drm/docs: more leftovers from the big vtable documentation pile Another pile of vfuncs from the old gpu.tmpl xml documentation that I've forgotten to delete. I spotted a few more things to clarify/extend in the new kerneldoc while going through this once more. v2: Spelling fixes (Thierry). v3: More spelling fixes and use Thierry's proposal to clarify why drivers need to validate modes both in ->mode_fixup and ->mode_valid. Cc: Laurent Pinchart Cc: Thierry Reding Acked-by: Thierry Reding Signed-off-by: Daniel Vetter --- Documentation/DocBook/gpu.tmpl | 188 ----------------------------------------- 1 file changed, 188 deletions(-) (limited to 'Documentation/DocBook') diff --git a/Documentation/DocBook/gpu.tmpl b/Documentation/DocBook/gpu.tmpl index 225a246..faa5e0d 100644 --- a/Documentation/DocBook/gpu.tmpl +++ b/Documentation/DocBook/gpu.tmpl @@ -1579,194 +1579,6 @@ void intel_crt_init(struct drm_device *dev) entities. - Legacy CRTC Helper Operations - - - bool (*mode_fixup)(struct drm_crtc *crtc, - const struct drm_display_mode *mode, - struct drm_display_mode *adjusted_mode); - - Let CRTCs adjust the requested mode or reject it completely. This - operation returns true if the mode is accepted (possibly after being - adjusted) or false if it is rejected. - - - The mode_fixup operation should reject the - mode if it can't reasonably use it. The definition of "reasonable" - is currently fuzzy in this context. One possible behaviour would be - to set the adjusted mode to the panel timings when a fixed-mode - panel is used with hardware capable of scaling. Another behaviour - would be to accept any input mode and adjust it to the closest mode - supported by the hardware (FIXME: This needs to be clarified). - - - - int (*mode_set_base)(struct drm_crtc *crtc, int x, int y, - struct drm_framebuffer *old_fb) - - Move the CRTC on the current frame buffer (stored in - crtc->fb) to position (x,y). Any of the frame - buffer, x position or y position may have been modified. - - - This helper operation is optional. If not provided, the - drm_crtc_helper_set_config function will fall - back to the mode_set helper operation. - - - FIXME: Why are x and y passed as arguments, as they can be accessed - through crtc->x and - crtc->y? - - - - void (*prepare)(struct drm_crtc *crtc); - - Prepare the CRTC for mode setting. This operation is called after - validating the requested mode. Drivers use it to perform - device-specific operations required before setting the new mode. - - - - int (*mode_set)(struct drm_crtc *crtc, struct drm_display_mode *mode, - struct drm_display_mode *adjusted_mode, int x, int y, - struct drm_framebuffer *old_fb); - - Set a new mode, position and frame buffer. Depending on the device - requirements, the mode can be stored internally by the driver and - applied in the commit operation, or - programmed to the hardware immediately. - - - The mode_set operation returns 0 on success - or a negative error code if an error occurs. - - - - void (*commit)(struct drm_crtc *crtc); - - Commit a mode. This operation is called after setting the new mode. - Upon return the device must use the new mode and be fully - operational. - - - - - - Encoder Helper Operations - - - bool (*mode_fixup)(struct drm_encoder *encoder, - const struct drm_display_mode *mode, - struct drm_display_mode *adjusted_mode); - - Let encoders adjust the requested mode or reject it completely. This - operation returns true if the mode is accepted (possibly after being - adjusted) or false if it is rejected. See the - mode_fixup CRTC helper - operation for an explanation of the allowed adjustments. - - - - void (*prepare)(struct drm_encoder *encoder); - - Prepare the encoder for mode setting. This operation is called after - validating the requested mode. Drivers use it to perform - device-specific operations required before setting the new mode. - - - - void (*mode_set)(struct drm_encoder *encoder, - struct drm_display_mode *mode, - struct drm_display_mode *adjusted_mode); - - Set a new mode. Depending on the device requirements, the mode can - be stored internally by the driver and applied in the - commit operation, or programmed to the - hardware immediately. - - - - void (*commit)(struct drm_encoder *encoder); - - Commit a mode. This operation is called after setting the new mode. - Upon return the device must use the new mode and be fully - operational. - - - - - - Connector Helper Operations - - - struct drm_encoder *(*best_encoder)(struct drm_connector *connector); - - Return a pointer to the best encoder for the connecter. Device that - map connectors to encoders 1:1 simply return the pointer to the - associated encoder. This operation is mandatory. - - - - int (*get_modes)(struct drm_connector *connector); - - Fill the connector's probed_modes list - by parsing EDID data with drm_add_edid_modes, - adding standard VESA DMT modes with drm_add_modes_noedid, - or calling drm_mode_probed_add directly for every - supported mode and return the number of modes it has detected. This - operation is mandatory. - - - Note that the caller function will automatically add standard VESA - DMT modes up to 1024x768 if the get_modes - helper operation returns no mode and if the connector status is - connector_status_connected. There is no need to call - drm_add_edid_modes manually in that case. - - - The vrefresh value is computed by - drm_helper_probe_single_connector_modes. - - - When parsing EDID data, drm_add_edid_modes fills the - connector display_info - width_mm and - height_mm fields. When creating modes - manually the get_modes helper operation must - set the display_info - width_mm and - height_mm fields if they haven't been set - already (for instance at initialization time when a fixed-size panel is - attached to the connector). The mode width_mm - and height_mm fields are only used internally - during EDID parsing and should not be set when creating modes manually. - - - - int (*mode_valid)(struct drm_connector *connector, - struct drm_display_mode *mode); - - Verify whether a mode is valid for the connector. Return MODE_OK for - supported modes and one of the enum drm_mode_status values (MODE_*) - for unsupported modes. This operation is optional. - - - As the mode rejection reason is currently not used beside for - immediately removing the unsupported mode, an implementation can - return MODE_BAD regardless of the exact reason why the mode is not - valid. - - - Note that the mode_valid helper operation is - only called for modes detected by the device, and - not for modes set by the user through the CRTC - set_config operation. - - - - - Atomic Modeset Helper Functions Reference Overview -- cgit v1.1 From 3d7b75fdae9c81dd71c7573dbc285af90e0924fa Mon Sep 17 00:00:00 2001 From: Lukas Wunner Date: Mon, 11 Jan 2016 00:08:35 +0100 Subject: apple-gmux: Add initial documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Document what I've learned so far about the gmux so that we can collaboratively reverse-engineer its remaining unknown bits without everyone having to start from scratch. The DOC sections are bound together in the gpu.tmpl DocBook under a new vga_switcheroo "Handlers" chapter. Eventually this should be amended with documentation about the four other handlers that exist so far (nouveau v1 DSM, nouveau Optimus DSM, radeon ATPX, amdgpu ATPX). Requires kernel-doc with asciidoc support. The EFI variable was reverse-engineered by Bruno Bierbaumer and Andreas Heider . Some of the remaining open questions: * How are vblank intervals synchronized on retinas to achieve seamless switching? Is the DP mux capable of this? It's not mentioned in the data sheets. Or is it done at the OS level, i.e. do we have to synchronize vblank intervals between DRM drivers? There's a signal coming from the panel connector and going into gmux, could this be the vblank signal as received by the panel to properly time the switch? * On retinas there's an I2C bus between gmux and the connector of the right I/O board, apparently leading to the Parade PS8401A HDMI repeater. What is this for, is it controlled via gmux registers? Data sheet: http://www.paradetech.com/products/jitter-cleaning-repeaters/ps8401/ * On retinas there's an I2C bus between gmux and the LED driver. Pre-retinas connected the LED driver to SMBUS. Are there additional gmux registers on retinas to control it? * The MacPro6,1 2013 also has a gmux, the same Renesas R4F2113 as the retina MacBook Pro. The Mac Pro doesn't have a built-in display, so what is its purpose? Power control of the dual FirePro GPUs? Switching of the external DP/Thunderbolt ports? The iFixit teardown clearly shows one TI HD3SS212 DisplayPort mux on the logic board next to one of the three Thunderbolt controllers. However six muxes would be necessary to switch all six ports between GPUs. The mux is probably necessary for one of the display configurations allowed by Apple, but which one? https://www.ifixit.com/Teardown/Mac+Pro+Late+2013+Teardown/20778 https://d3nevzfk7ii3be.cloudfront.net/igi/fELBTnt31QhnDsqq.huge https://support.apple.com/en-us/HT202801 * Registers we haven't decoded yet: 0x700 32 Bit configmap? 0x708 32 Bit power sequence? 0x712 8 Bit status of clock from panel on retinas? 0x713 8 Bit dito? 0x724 16 Bit backlight, raw value? 0x760 32 Bit backlight 0x764 32 Bit backlight 0x768 8 Bit backlight 0x76a 16 Bit backlight 0x76c 16 Bit backlight 0x76e 16 Bit backlight 0x77f edp/dp/hdmi probe? retina only. * Addition by Bruno Prémont : "Missing is also precise knowledge as to what the gmux depends on. From behavioral reports, it is somehow sensitive to VGA IO/MEM routing (it apparently needs the routing to go to integrated GPU, not discrete GPU). When the routing is inappropriate backlight control IO just reads back as 0xFF (and eventually gmux IO in general does so)." Signed-off-by: Lukas Wunner Acked-by: Darren Hart Link: http://patchwork.freedesktop.org/patch/msgid/da309e436fbeac886477d80376457b7d83ea4b2d.1452431795.git.lukas@wunner.de Signed-off-by: Daniel Vetter --- Documentation/DocBook/gpu.tmpl | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) (limited to 'Documentation/DocBook') diff --git a/Documentation/DocBook/gpu.tmpl b/Documentation/DocBook/gpu.tmpl index faa5e0d..a866933 100644 --- a/Documentation/DocBook/gpu.tmpl +++ b/Documentation/DocBook/gpu.tmpl @@ -3470,8 +3470,30 @@ int num_ioctls; + + Handlers + + apple-gmux Handler +!Pdrivers/platform/x86/apple-gmux.c Overview +!Pdrivers/platform/x86/apple-gmux.c Interrupt + + Graphics mux +!Pdrivers/platform/x86/apple-gmux.c Graphics mux + + + Power control +!Pdrivers/platform/x86/apple-gmux.c Power control + + + Backlight control +!Pdrivers/platform/x86/apple-gmux.c Backlight control + + + + !Cdrivers/gpu/vga/vga_switcheroo.c !Cinclude/linux/vga_switcheroo.h +!Cdrivers/platform/x86/apple-gmux.c -- cgit v1.1