drm: Update kerneldoc for drm_crtc.[hc]

After going through all the trouble of splitting out parts from
drm_crtc.[hc] and then properly documenting each I've entirely
forgotten to show the same TLC for CRTCs themselves!

Let's make amends asap.

v2: Review from Eric.

Reviewed-by: Eric Engestrom <eric.engestrom@imgtec.com>
Signed-off-by: Daniel Vetter <daniel.vetter@intel.com>
This commit is contained in:
Daniel Vetter 2017-01-25 07:26:57 +01:00
parent 1031548c61
commit d5d487eb07
3 changed files with 47 additions and 7 deletions

View File

@ -48,11 +48,17 @@ CRTC Abstraction
================
.. kernel-doc:: drivers/gpu/drm/drm_crtc.c
:export:
:doc: overview
CRTC Functions Reference
--------------------------------
.. kernel-doc:: include/drm/drm_crtc.h
:internal:
.. kernel-doc:: drivers/gpu/drm/drm_crtc.c
:export:
Frame Buffer Abstraction
========================

View File

@ -46,6 +46,27 @@
#include "drm_crtc_internal.h"
#include "drm_internal.h"
/**
* DOC: overview
*
* A CRTC represents the overall display pipeline. It receives pixel data from
* &drm_plane and blends them together. The &drm_display_mode is also attached
* to the CRTC, specifying display timings. On the output side the data is fed
* to one or more &drm_encoder, which are then each connected to one
* &drm_connector.
*
* To create a CRTC, a KMS drivers allocates and zeroes an instances of
* &struct drm_crtc (possibly as part of a larger structure) and registers it
* with a call to drm_crtc_init_with_planes().
*
* The CRTC is also the entry point for legacy modeset operations, see
* &drm_crtc_funcs.set_config, legacy plane operations, see
* &drm_crtc_funcs.page_flip and &drm_crtc_funcs.cursor_set2, and other legacy
* operations like &drm_crtc_funcs.gamma_set. For atomic drivers all these
* features are controlled through &drm_property and
* &drm_mode_config_funcs.atomic_check and &drm_mode_config_funcs.atomic_check.
*/
/**
* drm_crtc_from_index - find the registered CRTC at an index
* @dev: DRM device

View File

@ -641,7 +641,7 @@ struct drm_crtc {
*
* This provides a read lock for the overall crtc state (mode, dpms
* state, ...) and a write lock for everything which can be update
* without a full modeset (fb, cursor data, crtc properties ...). Full
* without a full modeset (fb, cursor data, crtc properties ...). A full
* modeset also need to grab &drm_mode_config.connection_mutex.
*/
struct drm_modeset_lock mutex;
@ -774,10 +774,8 @@ struct drm_crtc {
* @connectors: array of connectors to drive with this CRTC if possible
* @num_connectors: size of @connectors array
*
* Represents a single crtc the connectors that it drives with what mode
* and from which framebuffer it scans out from.
*
* This is used to set modes.
* This represents a modeset configuration for the legacy SETCRTC ioctl and is
* also used internally. Atomic drivers instead use &drm_atomic_state.
*/
struct drm_mode_set {
struct drm_framebuffer *fb;
@ -834,7 +832,15 @@ int drm_crtc_force_disable_all(struct drm_device *dev);
int drm_mode_set_config_internal(struct drm_mode_set *set);
struct drm_crtc *drm_crtc_from_index(struct drm_device *dev, int idx);
/* Helpers */
/**
* drm_crtc_find - look up a CRTC object from its ID
* @dev: DRM device
* @id: &drm_mode_object ID
*
* This can be used to look up a CRTC from its userspace ID. Only used by
* drivers for legacy IOCTLs and interface, nowadays extensions to the KMS
* userspace interface should be done using &drm_property.
*/
static inline struct drm_crtc *drm_crtc_find(struct drm_device *dev,
uint32_t id)
{
@ -843,6 +849,13 @@ static inline struct drm_crtc *drm_crtc_find(struct drm_device *dev,
return mo ? obj_to_crtc(mo) : NULL;
}
/**
* drm_for_each_crtc - iterate over all CRTCs
* @crtc: a &struct drm_crtc as the loop cursor
* @dev: the &struct drm_device
*
* Iterate over all CRTCs of @dev.
*/
#define drm_for_each_crtc(crtc, dev) \
list_for_each_entry(crtc, &(dev)->mode_config.crtc_list, head)