From a21ff375c697fc7560c16d0f88335a6db2c9c37a Mon Sep 17 00:00:00 2001 From: Jesse Barnes Date: Fri, 20 Apr 2007 17:03:50 -0700 Subject: Document drm_modes.c functions. --- linux-core/drm_modes.c | 169 ++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 166 insertions(+), 3 deletions(-) (limited to 'linux-core/drm_modes.c') diff --git a/linux-core/drm_modes.c b/linux-core/drm_modes.c index 44498c5e..648e85e5 100644 --- a/linux-core/drm_modes.c +++ b/linux-core/drm_modes.c @@ -33,6 +33,16 @@ #include "drm.h" #include "drm_crtc.h" +/** + * drm_mode_debug_printmodeline - debug print a mode + * @dev: DRM device + * @mode: mode to print + * + * LOCKING: + * None. + * + * Describe @mode using DRM_DEBUG. + */ void drm_mode_debug_printmodeline(struct drm_device *dev, struct drm_display_mode *mode) { @@ -45,6 +55,15 @@ void drm_mode_debug_printmodeline(struct drm_device *dev, } EXPORT_SYMBOL(drm_mode_debug_printmodeline); +/** + * drm_mode_set_name - set the name on a mode + * @mode: name will be set in this mode + * + * LOCKING: + * None. + * + * Set the name of @mode to a standard format. + */ void drm_mode_set_name(struct drm_display_mode *mode) { snprintf(mode->name, DRM_DISPLAY_MODE_LEN, "%dx%d", mode->hdisplay, @@ -52,6 +71,16 @@ void drm_mode_set_name(struct drm_display_mode *mode) } EXPORT_SYMBOL(drm_mode_set_name); +/** + * drm_mode_list_concat - move modes from one list to another + * @head: source list + * @new: dst list + * + * LOCKING: + * Caller must ensure both lists are locked. + * + * Move all the modes from @head to @new. + */ void drm_mode_list_concat(struct list_head *head, struct list_head *new) { @@ -62,6 +91,20 @@ void drm_mode_list_concat(struct list_head *head, struct list_head *new) } } +/** + * drm_mode_width - get the width of a mode + * @mode: mode + * + * LOCKING: + * None. + * + * Return @mode's width (hdisplay) value. + * + * FIXME: is this needed? + * + * RETURNS: + * @mode->hdisplay + */ int drm_mode_width(struct drm_display_mode *mode) { return mode->hdisplay; @@ -69,12 +112,40 @@ int drm_mode_width(struct drm_display_mode *mode) } EXPORT_SYMBOL(drm_mode_width); +/** + * drm_mode_height - get the height of a mode + * @mode: mode + * + * LOCKING: + * None. + * + * Return @mode's height (vdisplay) value. + * + * FIXME: is this needed? + * + * RETURNS: + * @mode->vdisplay + */ int drm_mode_height(struct drm_display_mode *mode) { return mode->vdisplay; } EXPORT_SYMBOL(drm_mode_height); +/** + * drm_mode_vrefresh - get the vrefresh of a mode + * @mode: mode + * + * LOCKING: + * None. + * + * Return @mode's vrefresh rate or calculate it if necessary. + * + * FIXME: why is this needed? + * + * RETURNS: + * Vertical refresh rate of @mode. + */ int drm_mode_vrefresh(struct drm_display_mode *mode) { int refresh = 0; @@ -94,7 +165,16 @@ int drm_mode_vrefresh(struct drm_display_mode *mode) } EXPORT_SYMBOL(drm_mode_vrefresh); - +/** + * drm_mode_set_crtcinfo - set CRTC modesetting parameters + * @p: mode + * @adjust_flags: unused? (FIXME) + * + * LOCKING: + * None. + * + * Setup the CRTC modesetting parameters for @p, adjusting if necessary. + */ void drm_mode_set_crtcinfo(struct drm_display_mode *p, int adjust_flags) { if ((p == NULL) || ((p->type & DRM_MODE_TYPE_CRTC_C) == DRM_MODE_TYPE_BUILTIN)) @@ -150,6 +230,9 @@ EXPORT_SYMBOL(drm_mode_set_crtcinfo); * drm_mode_duplicate - allocate and duplicate an existing mode * @m: mode to duplicate * + * LOCKING: + * None. + * * Just allocate a new mode, copy the existing mode into it, and return * a pointer to it. Used to create new instances of established modes. */ @@ -171,6 +254,19 @@ struct drm_display_mode *drm_mode_duplicate(struct drm_device *dev, } EXPORT_SYMBOL(drm_mode_duplicate); +/** + * drm_mode_equal - test modes for equality + * @mode1: first mode + * @mode2: second mode + * + * LOCKING: + * None. + * + * Check to see if @mode1 and @mode2 are equivalent. + * + * RETURNS: + * True if the modes are equal, false otherwise. + */ bool drm_mode_equal(struct drm_display_mode *mode1, struct drm_display_mode *mode2) { if (mode1->clock == mode2->clock && @@ -191,7 +287,21 @@ bool drm_mode_equal(struct drm_display_mode *mode1, struct drm_display_mode *mod } EXPORT_SYMBOL(drm_mode_equal); -/* caller must hold modes lock */ +/** + * drm_mode_validate_size - make sure modes adhere to size constraints + * @dev: DRM device + * @mode_list: list of modes to check + * @maxX: maximum width + * @maxY: maximum height + * @maxPitch: max pitch + * + * LOCKING: + * Caller must hold a lock protecting @mode_list. + * + * The DRM device (@dev) has size and pitch limits. Here we validate the + * modes we probed for @dev against those limits and set their status as + * necessary. + */ void drm_mode_validate_size(struct drm_device *dev, struct list_head *mode_list, int maxX, int maxY, int maxPitch) @@ -211,6 +321,22 @@ void drm_mode_validate_size(struct drm_device *dev, } EXPORT_SYMBOL(drm_mode_validate_size); +/** + * drm_mode_validate_clocks - validate modes against clock limits + * @dev: DRM device + * @mode_list: list of modes to check + * @min: minimum clock rate array + * @max: maximum clock rate array + * @n_ranges: number of clock ranges (size of arrays) + * + * LOCKING: + * Caller must hold a lock protecting @mode_list. + * + * Some code may need to check a mode list against the clock limits of the + * device in question. This function walks the mode list, testing to make + * sure each mode falls within a given range (defined by @min and @max + * arrays) and sets @mode->status as needed. + */ void drm_mode_validate_clocks(struct drm_device *dev, struct list_head *mode_list, int *min, int *max, int n_ranges) @@ -232,7 +358,19 @@ void drm_mode_validate_clocks(struct drm_device *dev, } EXPORT_SYMBOL(drm_mode_validate_clocks); -/* caller must hold modes lock */ +/** + * drm_mode_prune_invalid - remove invalid modes from mode list + * @dev: DRM device + * @mode_list: list of modes to check + * @verbose: be verbose about it + * + * LOCKING: + * Caller must hold a lock protecting @mode_list. + * + * Once mode list generation is complete, a caller can use this routine to + * remove invalid modes from a mode list. If any of the modes have a + * status other than %MODE_OK, they are removed from @mode_list and freed. + */ void drm_mode_prune_invalid(struct drm_device *dev, struct list_head *mode_list, bool verbose) { @@ -248,6 +386,21 @@ void drm_mode_prune_invalid(struct drm_device *dev, } } +/** + * drm_mode_compare - compare modes for favorability + * @lh_a: list_head for first mode + * @lh_b: list_head for second mode + * + * LOCKING: + * None. + * + * Compare two modes, given by @lh_a and @lh_b, returning a value indicating + * which is better. + * + * RETURNS: + * Negative if @lh_a is better than @lh_b, zero if they're equivalent, or + * positive if @lh_b is better than @lh_a. + */ static int drm_mode_compare(struct list_head *lh_a, struct list_head *lh_b) { struct drm_display_mode *a = list_entry(lh_a, struct drm_display_mode, head); @@ -265,6 +418,7 @@ static int drm_mode_compare(struct list_head *lh_a, struct list_head *lh_b) return diff; } +/* FIXME: what we don't have a list sort function? */ /* list sort from Mark J Roberts (mjr@znex.org) */ void list_sort(struct list_head *head, int (*cmp)(struct list_head *a, struct list_head *b)) { @@ -342,6 +496,15 @@ void list_sort(struct list_head *head, int (*cmp)(struct list_head *a, struct li list->prev = head; } +/** + * drm_mode_sort - sort mode list + * @mode_list: list to sort + * + * LOCKING: + * Caller must hold a lock protecting @mode_list. + * + * Sort @mode_list by favorability, putting good modes first. + */ void drm_mode_sort(struct list_head *mode_list) { list_sort(mode_list, drm_mode_compare); -- cgit v1.2.3