Apparently not everyone has been super dutiful with updating this stuff.
I still decided to leave out the documentation for all the *_property pointers we have in drm_mode_config.
Signed-off-by: Daniel Vetter daniel.vetter@ffwll.ch --- include/drm/drm_crtc.h | 80 ++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 67 insertions(+), 13 deletions(-)
diff --git a/include/drm/drm_crtc.h b/include/drm/drm_crtc.h index c0edd87fa0ee..aa3f7ea41b1b 100644 --- a/include/drm/drm_crtc.h +++ b/include/drm/drm_crtc.h @@ -315,6 +315,7 @@ struct drm_plane_helper_funcs; * update to ensure framebuffer cleanup isn't done too early * @adjusted_mode: for use by helpers and drivers to compute adjusted mode timings * @mode: current mode timings + * @mode_blob: &drm_property_blob for @mode * @degamma_lut: Lookup table for converting framebuffer pixel data * before apply the conversion matrix * @ctm: Transformation matrix @@ -709,6 +710,7 @@ struct drm_crtc_funcs { * @dev: parent DRM device * @port: OF node used by drm_of_find_possible_crtcs() * @head: list management + * @name: human readable name, can be set by the driver * @mutex: per-CRTC locking * @base: base KMS object for ID tracking etc. * @primary: primary plane for this CRTC @@ -736,12 +738,13 @@ struct drm_crtc {
char *name;
- /* - * crtc mutex + /** + * @mutex: * * 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, ...) + * without a full modeset (fb, cursor data, crtc properties ...). Full + * modeset also need to grab dev->mode_config.connection_mutex. */ struct drm_modeset_lock mutex;
@@ -1149,6 +1152,7 @@ struct drm_encoder { * @head: list management * @base: base KMS object * @name: connector name + * @connector_id: compacted connector id useful indexing arrays * @connector_type: one of the %DRM_MODE_CONNECTOR_<foo> types from drm_mode.h * @connector_type_id: index into connector type enum * @interlace_allowed: can this connector handle interlaced modes? @@ -1161,7 +1165,6 @@ struct drm_encoder { * @funcs: connector control functions * @edid_blob_ptr: DRM property containing EDID if present * @properties: property tracking for this connector - * @path_blob_ptr: DRM blob property data for the DP MST path property * @polled: a %DRM_CONNECTOR_POLL_<foo> value for core driven polling * @dpms: current dpms state * @helper_private: mid-layer private data @@ -1224,8 +1227,23 @@ struct drm_connector { struct drm_property_blob *edid_blob_ptr; struct drm_object_properties properties;
+ /** + * @path_blob_ptr: + * + * DRM blob property data for the DP MST path property. + */ struct drm_property_blob *path_blob_ptr;
+ /** + * @tile_blob_ptr: + * + * DRM blob property data for the tile property (used mostly by DP MST). + * This is meant for screens which are driven through separate display + * pipelines represented by &drm_crtc, which might not be in running + * with genlocked clocks. For tiled panels which are genlocked, like + * dual-link LVDS or dual-link DSI, the driver should try to not expose + * the tiling and virtual both &drm_crtc and &drm_plane if needed. + */ struct drm_property_blob *tile_blob_ptr;
uint8_t polled; /* DRM_CONNECTOR_POLL_* */ @@ -1287,6 +1305,7 @@ struct drm_connector { * plane (in 16.16) * @src_w: width of visible portion of plane (in 16.16) * @src_h: height of visible portion of plane (in 16.16) + * @rotation: rotation of the plane * @state: backpointer to global drm_atomic_state */ struct drm_plane_state { @@ -1527,6 +1546,7 @@ enum drm_plane_type { * struct drm_plane - central DRM plane control structure * @dev: DRM device this plane belongs to * @head: for list management + * @name: human readable name, can be set by the driver * @base: base mode object * @possible_crtcs: pipes this plane can be bound to * @format_types: array of formats supported by this plane @@ -1540,6 +1560,7 @@ enum drm_plane_type { * @properties: property tracking for this plane * @type: type of plane (overlay, primary, cursor) * @state: current atomic state for this plane + * @helper_private: mid-layer private data */ struct drm_plane { struct drm_device *dev; @@ -1547,6 +1568,13 @@ struct drm_plane {
char *name;
+ /** + * @mutex: + * + * Protects modeset plane state, together with the mutex of &drm_crtc + * this plane is linked to (when active, getting actived or getting + * disabled). + */ struct drm_modeset_lock mutex;
struct drm_mode_object base; @@ -1719,6 +1747,10 @@ struct drm_bridge {
/** * struct drm_crtc_commit - track modeset commits on a CRTC + * + * This structure is used to track asynchronously running atomic commit + * operations. For an implementation of how to use this look at + * drm_atomic_helper_setup_commit() from the atomic helper library. */ struct drm_crtc_commit { /** @@ -1764,7 +1796,7 @@ struct drm_crtc_commit { struct completion hw_done;
/** - * cleanup_done: + * @cleanup_done: * * Will be signalled after old buffers have been cleaned up again by * calling drm_atomic_helper_cleanup_planes(). Since this can only @@ -1813,7 +1845,6 @@ struct __drm_connnectors_state { * @legacy_set_config: Disable conflicting encoders instead of failing with -EINVAL. * @planes: pointer to array of structures with per-plane data * @crtcs: pointer to array of CRTC pointers - * @crtc_states: pointer to array of CRTC states pointers * @num_connector: size of the @connectors and @connector_states arrays * @connectors: pointer to array of structures with per-connector data * @acquire_ctx: acquire context for this atomic modeset state update @@ -2137,8 +2168,6 @@ struct drm_mode_config_funcs { * @connection_mutex: ww mutex protecting connector state and routing * @acquire_ctx: global implicit acquire context used by atomic drivers for * legacy IOCTLs - * @idr_mutex: mutex for KMS ID allocation and management - * @crtc_idr: main KMS ID tracking object * @fb_lock: mutex to protect fb state and lists * @num_fb: number of fbs available * @fb_list: list of framebuffers available @@ -2160,6 +2189,7 @@ struct drm_mode_config_funcs { * @fb_base: base address of the framebuffer * @poll_enabled: track polling support for this device * @poll_running: track polling status for this device + * @delayed_event: track delayed poll uevent deliver for this device * @output_poll_work: delayed work for polling in process context * @property_blob_list: list of all the blob property objects * @blob_lock: mutex for blob property allocation and management @@ -2188,10 +2218,30 @@ struct drm_mode_config { struct mutex mutex; /* protects configuration (mode lists etc.) */ struct drm_modeset_lock connection_mutex; /* protects connector->encoder and encoder->crtc links */ struct drm_modeset_acquire_ctx *acquire_ctx; /* for legacy _lock_all() / _unlock_all() */ - struct mutex idr_mutex; /* for IDR management */ - struct idr crtc_idr; /* use this idr for all IDs, fb, crtc, connector, modes - just makes life easier */ - struct idr tile_idr; /* use this idr for all IDs, fb, crtc, connector, modes - just makes life easier */ - /* this is limited to one for now */ + + /** + * @idr_mutex: + * + * Mutex for KMS ID allocation and management. Protects both @crtc_idr + * and @tile_idr. + */ + struct mutex idr_mutex; + + /** + * @crtc_idr: + * + * Main KMS ID tracking object. Use this idr for all IDs, fb, crtc, + * connector, modes - just makes life easier to have only one. + */ + struct idr crtc_idr; + + /** + * @tile_idr: + * + * Use this idr for allocating new IDs for tiled sinks like use in some + * high-res DP MST screens. + */ + struct idr tile_idr;
struct mutex fb_lock; /* proctects global and per-file fb lists */ int num_fb; @@ -2293,7 +2343,11 @@ struct drm_mode_config { /* whether async page flip is supported or not */ bool async_page_flip;
- /* whether the driver supports fb modifiers */ + /** + * @allow_fb_modifiers: + * + * Whether the driver supports fb modifiers in the ADDFB2.1 ioctl call. + */ bool allow_fb_modifiers;
/* cursor size */
kernel-doc is unhappy, appease it.
Cc: Lionel Landwerlin lionel.g.landwerlin@intel.com Signed-off-by: Daniel Vetter daniel.vetter@ffwll.ch --- drivers/gpu/drm/drm_atomic_helper.c | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/drivers/gpu/drm/drm_atomic_helper.c b/drivers/gpu/drm/drm_atomic_helper.c index 290318d6f5b5..68627babb31b 100644 --- a/drivers/gpu/drm/drm_atomic_helper.c +++ b/drivers/gpu/drm/drm_atomic_helper.c @@ -3315,7 +3315,7 @@ EXPORT_SYMBOL(drm_atomic_helper_connector_destroy_state); * @red: red correction table * @green: green correction table * @blue: green correction table - * @start: + * @start: first entry, must always be 0 * @size: size of the tables * * Implements support for legacy gamma correction table for drivers
kernel-doc was unhappy, appease it.
Cc: Noralf Trønnes noralf@tronnes.org Cc: laurent.pinchart@ideasonboard.com Signed-off-by: Daniel Vetter daniel.vetter@intel.com --- drivers/gpu/drm/drm_fb_cma_helper.c | 18 ++++++++++++------ 1 file changed, 12 insertions(+), 6 deletions(-)
diff --git a/drivers/gpu/drm/drm_fb_cma_helper.c b/drivers/gpu/drm/drm_fb_cma_helper.c index 172cafe11c71..9cd23283c3a0 100644 --- a/drivers/gpu/drm/drm_fb_cma_helper.c +++ b/drivers/gpu/drm/drm_fb_cma_helper.c @@ -162,6 +162,10 @@ static struct drm_fb_cma *drm_fb_cma_alloc(struct drm_device *dev, * drm_fb_cma_create_with_funcs() - helper function for the * &drm_mode_config_funcs ->fb_create * callback function + * @dev: DRM device + * @file_priv: drm file for the ioctl call + * @mode_cmd: metadat for the framebuffer that should be created + * @funcs: vtable to be used for the new framebuffer object * * This can be used to set &drm_framebuffer_funcs for drivers that need the * dirty() callback. Use drm_fb_cma_create() if you don't need to change @@ -223,6 +227,10 @@ EXPORT_SYMBOL_GPL(drm_fb_cma_create_with_funcs);
/** * drm_fb_cma_create() - &drm_mode_config_funcs ->fb_create callback function + * @dev: DRM device + * @file_priv: drm file for the ioctl call + * @mode_cmd: metadat for the framebuffer that should be created + * * * If your hardware has special alignment or pitch requirements these should be * checked before calling this function. Use drm_fb_cma_create_with_funcs() if @@ -246,7 +254,7 @@ EXPORT_SYMBOL_GPL(drm_fb_cma_create); * This function will usually be called from the CRTC callback functions. */ struct drm_gem_cma_object *drm_fb_cma_get_gem_obj(struct drm_framebuffer *fb, - unsigned int plane) + unsigned int plane) { struct drm_fb_cma *fb_cma = to_fb_cma(fb);
@@ -258,10 +266,6 @@ struct drm_gem_cma_object *drm_fb_cma_get_gem_obj(struct drm_framebuffer *fb, EXPORT_SYMBOL_GPL(drm_fb_cma_get_gem_obj);
#ifdef CONFIG_DEBUG_FS -/* - * drm_fb_cma_describe() - Helper to dump information about a single - * CMA framebuffer object - */ static void drm_fb_cma_describe(struct drm_framebuffer *fb, struct seq_file *m) { struct drm_fb_cma *fb_cma = to_fb_cma(fb); @@ -279,7 +283,9 @@ static void drm_fb_cma_describe(struct drm_framebuffer *fb, struct seq_file *m)
/** * drm_fb_cma_debugfs_show() - Helper to list CMA framebuffer objects - * in debugfs. + * in debugfs. + * @m: output file + * @arg: private data for the callback */ int drm_fb_cma_debugfs_show(struct seq_file *m, void *arg) {
On Tue, May 31, 2016 at 11:11:12PM +0200, Daniel Vetter wrote:
On this one:
s/metadat/metadata/g
I know we are just appeasing the gods of kernel-doc here, but how about this:
@mode_cmd: metadata to be used by the framebuffer creator function ?
Best regards, Liviu
Hi Daniel,
Thank you for the patch.
On Tuesday 31 May 2016 23:11:12 Daniel Vetter wrote:
Beside the 'metadat' typo here and below,
Acked-by: Laurent Pinchart laurent.pinchart@ideasonboard.com
I'm not fond of the description of the mode_cmd parameter, but given that this function is used as a callback helper, nobody will need to understand what the parameters are.
We need to get folks to run
$ make htmldocs
more often and actually check the output. With the fancy new sphinx stuff there's hopefully no more excuses.
Fixes: 286dbb8d5d80 ("drm/atomic: Rename async parameter to nonblocking.") Cc: Maarten Lankhorst maarten.lankhorst@linux.intel.com Signed-off-by: Daniel Vetter daniel.vetter@intel.com --- Documentation/DocBook/gpu.tmpl | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/Documentation/DocBook/gpu.tmpl b/Documentation/DocBook/gpu.tmpl index cb130514cedf..053cc1f46af9 100644 --- a/Documentation/DocBook/gpu.tmpl +++ b/Documentation/DocBook/gpu.tmpl @@ -1570,7 +1570,7 @@ void intel_crt_init(struct drm_device *dev) </sect3> <sect3> <title>Implementing Asynchronous Atomic Commit</title> -!Pdrivers/gpu/drm/drm_atomic_helper.c implementing async commit +!Pdrivers/gpu/drm/drm_atomic_helper.c implementing nonblocking commit </sect3> <sect3> <title>Atomic State Reset and Initialization</title>
On Wed, 01 Jun 2016, Daniel Vetter daniel.vetter@ffwll.ch wrote:
I think we should make kernel-doc return non-zero exit code if you specify a function or doc section with -function and it's not found. This should be a build stopping error, not a warning.
BR, Jani.
On Thu, Jun 02, 2016 at 04:52:08PM +0300, Jani Nikula wrote:
There's still the trouble that if people don't build the docs, they won't notice ... Which means other people who want to type the docs will constantly stumbled over a broken doc build. Not sure how to fix that, especially since make htmldocs still takes a lot of time and fails way too often when rebuilding after the tree changed :( -Daniel
At least in drm core we only document the driver interfaces using kerneldoc. For internals an unstructured comment is good enough.
Fixes a warning from kernel-doc, too.
Signed-off-by: Daniel Vetter daniel.vetter@ffwll.ch --- drivers/gpu/drm/drm_irq.c | 12 ++---------- 1 file changed, 2 insertions(+), 10 deletions(-)
diff --git a/drivers/gpu/drm/drm_irq.c b/drivers/gpu/drm/drm_irq.c index 49d02b4f969f..032d2fa7b744 100644 --- a/drivers/gpu/drm/drm_irq.c +++ b/drivers/gpu/drm/drm_irq.c @@ -89,11 +89,7 @@ static void store_vblank(struct drm_device *dev, unsigned int pipe, write_sequnlock(&vblank->seqlock); }
-/** - * drm_reset_vblank_timestamp - reset the last timestamp to the last vblank - * @dev: DRM device - * @pipe: index of CRTC for which to reset the timestamp - * +/* * Reset the stored timestamp for the current vblank count to correspond * to the last vblank occurred. * @@ -137,11 +133,7 @@ static void drm_reset_vblank_timestamp(struct drm_device *dev, unsigned int pipe spin_unlock(&dev->vblank_time_lock); }
-/** - * drm_update_vblank_count - update the master vblank counter - * @dev: DRM device - * @pipe: counter to update - * +/* * Call back into the driver to update the appropriate vblank counter * (specified by @pipe). Deal with wraparound, if it occurred, and * update the last read value so we can deal with wraparound on the next
There's still something very fishy going on with some of these, e.g. the drm_modeset_lock Example: and the "Standard GTF Parameters:" Line somehow get treated as heading when just appending a :: at the end of those lines. But it seems to work everywhere else. Maybe the kernel-doc heading generation logic is still a bit wonky?
Signed-off-by: Daniel Vetter daniel.vetter@intel.com --- drivers/gpu/drm/drm_bridge.c | 2 +- drivers/gpu/drm/drm_fb_cma_helper.c | 2 +- drivers/gpu/drm/drm_fops.c | 2 +- drivers/gpu/drm/drm_modes.c | 5 ++++- drivers/gpu/drm/drm_modeset_lock.c | 2 +- drivers/gpu/drm/drm_vma_manager.c | 3 +++ include/drm/drm_modes.h | 2 ++ 7 files changed, 13 insertions(+), 5 deletions(-)
diff --git a/drivers/gpu/drm/drm_bridge.c b/drivers/gpu/drm/drm_bridge.c index b3654404abd0..255543086590 100644 --- a/drivers/gpu/drm/drm_bridge.c +++ b/drivers/gpu/drm/drm_bridge.c @@ -36,7 +36,7 @@ * encoder chain. * * A bridge is always attached to a single &drm_encoder at a time, but can be - * either connected to it directly, or through an intermediate bridge: + * either connected to it directly, or through an intermediate bridge:: * * encoder ---> bridge B ---> bridge A * diff --git a/drivers/gpu/drm/drm_fb_cma_helper.c b/drivers/gpu/drm/drm_fb_cma_helper.c index 9cd23283c3a0..ae0fb2754c38 100644 --- a/drivers/gpu/drm/drm_fb_cma_helper.c +++ b/drivers/gpu/drm/drm_fb_cma_helper.c @@ -52,7 +52,7 @@ struct drm_fbdev_cma { * will be set up automatically. dirty() is called by * drm_fb_helper_deferred_io() in process context (struct delayed_work). * - * Example fbdev deferred io code: + * Example fbdev deferred io code:: * * static int driver_fbdev_fb_dirty(struct drm_framebuffer *fb, * struct drm_file *file_priv, diff --git a/drivers/gpu/drm/drm_fops.c b/drivers/gpu/drm/drm_fops.c index 5921b203503a..323c238fcac7 100644 --- a/drivers/gpu/drm/drm_fops.c +++ b/drivers/gpu/drm/drm_fops.c @@ -68,7 +68,7 @@ DEFINE_MUTEX(drm_global_mutex); * specific implementations. For GEM-based drivers this is drm_gem_mmap(). * * No other file operations are supported by the DRM userspace API. Overall the - * following is an example #file_operations structure: + * following is an example #file_operations structure:: * * static const example_drm_fops = { * .owner = THIS_MODULE, diff --git a/drivers/gpu/drm/drm_modes.c b/drivers/gpu/drm/drm_modes.c index 7def3d58da18..a7f121a8fc87 100644 --- a/drivers/gpu/drm/drm_modes.c +++ b/drivers/gpu/drm/drm_modes.c @@ -552,7 +552,10 @@ EXPORT_SYMBOL(drm_gtf_mode_complex); * I also refer to the function of fb_get_mode in the file of * drivers/video/fbmon.c * - * Standard GTF parameters: + * Standard GTF parameters + * + * :: + * * M = 600 * C = 40 * K = 128 diff --git a/drivers/gpu/drm/drm_modeset_lock.c b/drivers/gpu/drm/drm_modeset_lock.c index f33ebe638a28..61146f5b4f56 100644 --- a/drivers/gpu/drm/drm_modeset_lock.c +++ b/drivers/gpu/drm/drm_modeset_lock.c @@ -37,7 +37,7 @@ * * For basic principles of &ww_mutex, see: Documentation/locking/ww-mutex-design.txt * - * The basic usage pattern is to: + * The basic usage pattern is to:: * * drm_modeset_acquire_init(&ctx) * retry: diff --git a/drivers/gpu/drm/drm_vma_manager.c b/drivers/gpu/drm/drm_vma_manager.c index 2f2ecde8285b..f306c8855978 100644 --- a/drivers/gpu/drm/drm_vma_manager.c +++ b/drivers/gpu/drm/drm_vma_manager.c @@ -127,6 +127,9 @@ EXPORT_SYMBOL(drm_vma_offset_manager_destroy); * used to implement weakly referenced lookups using kref_get_unless_zero(). * * Example: + * + * :: + * * drm_vma_offset_lock_lookup(mgr); * node = drm_vma_offset_lookup_locked(mgr); * if (node) diff --git a/include/drm/drm_modes.h b/include/drm/drm_modes.h index 625966a906f2..ff481770d76b 100644 --- a/include/drm/drm_modes.h +++ b/include/drm/drm_modes.h @@ -169,6 +169,8 @@ enum drm_mode_status { * * The horizontal and vertical timings are defined per the following diagram. * + * :: + * * * Active Front Sync Back * Region Porch Porch
There's still something very fishy going on with some of these, e.g. the drm_modeset_lock Example: and the "Standard GTF Parameters:" Line somehow get treated as heading when just appending a :: at the end of those lines. But it seems to work everywhere else. Maybe the kernel-doc heading generation logic is still a bit wonky?
v2: Found more. Also s///#/ in the vgpu ascii-art - sphinx treats those as comments and switch to variable-width, which wreaks the layout.
Signed-off-by: Daniel Vetter daniel.vetter@intel.com --- drivers/gpu/drm/drm_bridge.c | 2 +- drivers/gpu/drm/drm_fb_cma_helper.c | 2 +- drivers/gpu/drm/drm_fops.c | 2 +- drivers/gpu/drm/drm_modes.c | 5 ++++- drivers/gpu/drm/drm_modeset_lock.c | 2 +- drivers/gpu/drm/drm_vma_manager.c | 3 +++ drivers/gpu/drm/i915/i915_reg.h | 2 +- drivers/gpu/drm/i915/i915_vgpu.c | 24 ++++++++++++------------ include/drm/drm_modes.h | 2 ++ 9 files changed, 26 insertions(+), 18 deletions(-)
diff --git a/drivers/gpu/drm/drm_bridge.c b/drivers/gpu/drm/drm_bridge.c index b3654404abd0..255543086590 100644 --- a/drivers/gpu/drm/drm_bridge.c +++ b/drivers/gpu/drm/drm_bridge.c @@ -36,7 +36,7 @@ * encoder chain. * * A bridge is always attached to a single &drm_encoder at a time, but can be - * either connected to it directly, or through an intermediate bridge: + * either connected to it directly, or through an intermediate bridge:: * * encoder ---> bridge B ---> bridge A * diff --git a/drivers/gpu/drm/drm_fb_cma_helper.c b/drivers/gpu/drm/drm_fb_cma_helper.c index 2b33b191a172..c50a0ba6fdba 100644 --- a/drivers/gpu/drm/drm_fb_cma_helper.c +++ b/drivers/gpu/drm/drm_fb_cma_helper.c @@ -52,7 +52,7 @@ struct drm_fbdev_cma { * will be set up automatically. dirty() is called by * drm_fb_helper_deferred_io() in process context (struct delayed_work). * - * Example fbdev deferred io code: + * Example fbdev deferred io code:: * * static int driver_fbdev_fb_dirty(struct drm_framebuffer *fb, * struct drm_file *file_priv, diff --git a/drivers/gpu/drm/drm_fops.c b/drivers/gpu/drm/drm_fops.c index 5921b203503a..323c238fcac7 100644 --- a/drivers/gpu/drm/drm_fops.c +++ b/drivers/gpu/drm/drm_fops.c @@ -68,7 +68,7 @@ DEFINE_MUTEX(drm_global_mutex); * specific implementations. For GEM-based drivers this is drm_gem_mmap(). * * No other file operations are supported by the DRM userspace API. Overall the - * following is an example #file_operations structure: + * following is an example #file_operations structure:: * * static const example_drm_fops = { * .owner = THIS_MODULE, diff --git a/drivers/gpu/drm/drm_modes.c b/drivers/gpu/drm/drm_modes.c index e5e6f504d8cc..aae86c1857ec 100644 --- a/drivers/gpu/drm/drm_modes.c +++ b/drivers/gpu/drm/drm_modes.c @@ -552,7 +552,10 @@ EXPORT_SYMBOL(drm_gtf_mode_complex); * I also refer to the function of fb_get_mode in the file of * drivers/video/fbmon.c * - * Standard GTF parameters: + * Standard GTF parameters + * + * :: + * * M = 600 * C = 40 * K = 128 diff --git a/drivers/gpu/drm/drm_modeset_lock.c b/drivers/gpu/drm/drm_modeset_lock.c index f33ebe638a28..61146f5b4f56 100644 --- a/drivers/gpu/drm/drm_modeset_lock.c +++ b/drivers/gpu/drm/drm_modeset_lock.c @@ -37,7 +37,7 @@ * * For basic principles of &ww_mutex, see: Documentation/locking/ww-mutex-design.txt * - * The basic usage pattern is to: + * The basic usage pattern is to:: * * drm_modeset_acquire_init(&ctx) * retry: diff --git a/drivers/gpu/drm/drm_vma_manager.c b/drivers/gpu/drm/drm_vma_manager.c index 2f2ecde8285b..f306c8855978 100644 --- a/drivers/gpu/drm/drm_vma_manager.c +++ b/drivers/gpu/drm/drm_vma_manager.c @@ -127,6 +127,9 @@ EXPORT_SYMBOL(drm_vma_offset_manager_destroy); * used to implement weakly referenced lookups using kref_get_unless_zero(). * * Example: + * + * :: + * * drm_vma_offset_lock_lookup(mgr); * node = drm_vma_offset_lookup_locked(mgr); * if (node) diff --git a/drivers/gpu/drm/i915/i915_reg.h b/drivers/gpu/drm/i915/i915_reg.h index 216cc4ba74ee..d25dd1d694bc 100644 --- a/drivers/gpu/drm/i915/i915_reg.h +++ b/drivers/gpu/drm/i915/i915_reg.h @@ -886,7 +886,7 @@ enum skl_disp_power_wells { * PLLs can be routed to any transcoder A/B/C. * * Note: DDI0 is digital port B, DD1 is digital port C, and DDI2 is - * digital port D (CHV) or port A (BXT). + * digital port D (CHV) or port A (BXT). :: * * * Dual channel PHY (VLV/CHV/BXT) diff --git a/drivers/gpu/drm/i915/i915_vgpu.c b/drivers/gpu/drm/i915/i915_vgpu.c index d5a7a5e7ee7e..004326291854 100644 --- a/drivers/gpu/drm/i915/i915_vgpu.c +++ b/drivers/gpu/drm/i915/i915_vgpu.c @@ -150,28 +150,28 @@ static int vgt_balloon_space(struct drm_mm *mm, * of its graphic space being zero. Yet there are some portions ballooned out( * the shadow part, which are marked as reserved by drm allocator). From the * host point of view, the graphic address space is partitioned by multiple - * vGPUs in different VMs. + * vGPUs in different VMs. :: * * vGPU1 view Host view * 0 ------> +-----------+ +-----------+ - * ^ |///////////| | vGPU3 | - * | |///////////| +-----------+ - * | |///////////| | vGPU2 | + * ^ |###########| | vGPU3 | + * | |###########| +-----------+ + * | |###########| | vGPU2 | * | +-----------+ +-----------+ * mappable GM | available | ==> | vGPU1 | * | +-----------+ +-----------+ - * | |///////////| | | - * v |///////////| | Host | + * | |###########| | | + * v |###########| | Host | * +=======+===========+ +===========+ - * ^ |///////////| | vGPU3 | - * | |///////////| +-----------+ - * | |///////////| | vGPU2 | + * ^ |###########| | vGPU3 | + * | |###########| +-----------+ + * | |###########| | vGPU2 | * | +-----------+ +-----------+ * unmappable GM | available | ==> | vGPU1 | * | +-----------+ +-----------+ - * | |///////////| | | - * | |///////////| | Host | - * v |///////////| | | + * | |###########| | | + * | |###########| | Host | + * v |###########| | | * total GM size ------> +-----------+ +-----------+ * * Returns: diff --git a/include/drm/drm_modes.h b/include/drm/drm_modes.h index 625966a906f2..ff481770d76b 100644 --- a/include/drm/drm_modes.h +++ b/include/drm/drm_modes.h @@ -169,6 +169,8 @@ enum drm_mode_status { * * The horizontal and vertical timings are defined per the following diagram. * + * :: + * * * Active Front Sync Back * Region Porch Porch
On Wed, 01 Jun 2016, Daniel Vetter daniel.vetter@ffwll.ch wrote:
Try adding a blank line between the line with trailing :: and the actual preformatted text. Seems to do the right thing for me.
http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#literal-b...
"Blank lines are required before and after a literal block, but these blank lines are not included as part of the literal block."
BR, Jani.
On Wed, Jun 1, 2016 at 11:46 AM, Jani Nikula jani.nikula@linux.intel.com wrote:
That's not what I've meant. The following sometimes (but not always, only in the 2 places I've mentioned) becomes a kernel-doc directive and not a block quote:
* Standard GTF Parameters:: * * stuff I wanted to have block quoted.
But if I switch the :: to be on a line of it's own (like in the patch) it's totally fine. -Daniel
On Wed, 01 Jun 2016, Daniel Vetter daniel.vetter@ffwll.ch wrote:
What do you mean by "kernel-doc directive" exactly?
Odd. It does seem to work for me. What does this print near there?
$ scripts/kernel-doc -rst -function drm_gtf_mode drivers/gpu/drm/drm_modes.c
BR, Jani.
On Wed, Jun 01, 2016 at 04:46:10PM +0300, Jani Nikula wrote:
Tried again, it works now. Probably fixed through some rebasing and me being on an older version of your toolchain. I'll send out v3. -Daniel
Just fallout from switching from asciidoc to sphinx/rst.
v2: Found more. Also s///#/ in the vgpu ascii-art - sphinx treats those as comments and switch to variable-width, which wreaks the layout.
v3: Undo some of the hacks, rebasing onto latest version of Jani's series fixed it.
Signed-off-by: Daniel Vetter daniel.vetter@intel.com --- drivers/gpu/drm/drm_bridge.c | 2 +- drivers/gpu/drm/drm_fb_cma_helper.c | 2 +- drivers/gpu/drm/drm_fops.c | 2 +- drivers/gpu/drm/drm_modes.c | 3 ++- drivers/gpu/drm/drm_modeset_lock.c | 2 +- drivers/gpu/drm/drm_vma_manager.c | 3 +++ drivers/gpu/drm/i915/i915_reg.h | 2 +- drivers/gpu/drm/i915/i915_vgpu.c | 24 ++++++++++++------------ include/drm/drm_modes.h | 2 ++ 9 files changed, 24 insertions(+), 18 deletions(-)
diff --git a/drivers/gpu/drm/drm_bridge.c b/drivers/gpu/drm/drm_bridge.c index b3654404abd0..255543086590 100644 --- a/drivers/gpu/drm/drm_bridge.c +++ b/drivers/gpu/drm/drm_bridge.c @@ -36,7 +36,7 @@ * encoder chain. * * A bridge is always attached to a single &drm_encoder at a time, but can be - * either connected to it directly, or through an intermediate bridge: + * either connected to it directly, or through an intermediate bridge:: * * encoder ---> bridge B ---> bridge A * diff --git a/drivers/gpu/drm/drm_fb_cma_helper.c b/drivers/gpu/drm/drm_fb_cma_helper.c index 2b33b191a172..c50a0ba6fdba 100644 --- a/drivers/gpu/drm/drm_fb_cma_helper.c +++ b/drivers/gpu/drm/drm_fb_cma_helper.c @@ -52,7 +52,7 @@ struct drm_fbdev_cma { * will be set up automatically. dirty() is called by * drm_fb_helper_deferred_io() in process context (struct delayed_work). * - * Example fbdev deferred io code: + * Example fbdev deferred io code:: * * static int driver_fbdev_fb_dirty(struct drm_framebuffer *fb, * struct drm_file *file_priv, diff --git a/drivers/gpu/drm/drm_fops.c b/drivers/gpu/drm/drm_fops.c index 5921b203503a..323c238fcac7 100644 --- a/drivers/gpu/drm/drm_fops.c +++ b/drivers/gpu/drm/drm_fops.c @@ -68,7 +68,7 @@ DEFINE_MUTEX(drm_global_mutex); * specific implementations. For GEM-based drivers this is drm_gem_mmap(). * * No other file operations are supported by the DRM userspace API. Overall the - * following is an example #file_operations structure: + * following is an example #file_operations structure:: * * static const example_drm_fops = { * .owner = THIS_MODULE, diff --git a/drivers/gpu/drm/drm_modes.c b/drivers/gpu/drm/drm_modes.c index e5e6f504d8cc..1eb679e5fbb1 100644 --- a/drivers/gpu/drm/drm_modes.c +++ b/drivers/gpu/drm/drm_modes.c @@ -552,7 +552,8 @@ EXPORT_SYMBOL(drm_gtf_mode_complex); * I also refer to the function of fb_get_mode in the file of * drivers/video/fbmon.c * - * Standard GTF parameters: + * Standard GTF parameters:: + * * M = 600 * C = 40 * K = 128 diff --git a/drivers/gpu/drm/drm_modeset_lock.c b/drivers/gpu/drm/drm_modeset_lock.c index f33ebe638a28..61146f5b4f56 100644 --- a/drivers/gpu/drm/drm_modeset_lock.c +++ b/drivers/gpu/drm/drm_modeset_lock.c @@ -37,7 +37,7 @@ * * For basic principles of &ww_mutex, see: Documentation/locking/ww-mutex-design.txt * - * The basic usage pattern is to: + * The basic usage pattern is to:: * * drm_modeset_acquire_init(&ctx) * retry: diff --git a/drivers/gpu/drm/drm_vma_manager.c b/drivers/gpu/drm/drm_vma_manager.c index 2f2ecde8285b..f306c8855978 100644 --- a/drivers/gpu/drm/drm_vma_manager.c +++ b/drivers/gpu/drm/drm_vma_manager.c @@ -127,6 +127,9 @@ EXPORT_SYMBOL(drm_vma_offset_manager_destroy); * used to implement weakly referenced lookups using kref_get_unless_zero(). * * Example: + * + * :: + * * drm_vma_offset_lock_lookup(mgr); * node = drm_vma_offset_lookup_locked(mgr); * if (node) diff --git a/drivers/gpu/drm/i915/i915_reg.h b/drivers/gpu/drm/i915/i915_reg.h index 216cc4ba74ee..d25dd1d694bc 100644 --- a/drivers/gpu/drm/i915/i915_reg.h +++ b/drivers/gpu/drm/i915/i915_reg.h @@ -886,7 +886,7 @@ enum skl_disp_power_wells { * PLLs can be routed to any transcoder A/B/C. * * Note: DDI0 is digital port B, DD1 is digital port C, and DDI2 is - * digital port D (CHV) or port A (BXT). + * digital port D (CHV) or port A (BXT). :: * * * Dual channel PHY (VLV/CHV/BXT) diff --git a/drivers/gpu/drm/i915/i915_vgpu.c b/drivers/gpu/drm/i915/i915_vgpu.c index d5a7a5e7ee7e..004326291854 100644 --- a/drivers/gpu/drm/i915/i915_vgpu.c +++ b/drivers/gpu/drm/i915/i915_vgpu.c @@ -150,28 +150,28 @@ static int vgt_balloon_space(struct drm_mm *mm, * of its graphic space being zero. Yet there are some portions ballooned out( * the shadow part, which are marked as reserved by drm allocator). From the * host point of view, the graphic address space is partitioned by multiple - * vGPUs in different VMs. + * vGPUs in different VMs. :: * * vGPU1 view Host view * 0 ------> +-----------+ +-----------+ - * ^ |///////////| | vGPU3 | - * | |///////////| +-----------+ - * | |///////////| | vGPU2 | + * ^ |###########| | vGPU3 | + * | |###########| +-----------+ + * | |###########| | vGPU2 | * | +-----------+ +-----------+ * mappable GM | available | ==> | vGPU1 | * | +-----------+ +-----------+ - * | |///////////| | | - * v |///////////| | Host | + * | |###########| | | + * v |###########| | Host | * +=======+===========+ +===========+ - * ^ |///////////| | vGPU3 | - * | |///////////| +-----------+ - * | |///////////| | vGPU2 | + * ^ |###########| | vGPU3 | + * | |###########| +-----------+ + * | |###########| | vGPU2 | * | +-----------+ +-----------+ * unmappable GM | available | ==> | vGPU1 | * | +-----------+ +-----------+ - * | |///////////| | | - * | |///////////| | Host | - * v |///////////| | | + * | |###########| | | + * | |###########| | Host | + * v |###########| | | * total GM size ------> +-----------+ +-----------+ * * Returns: diff --git a/include/drm/drm_modes.h b/include/drm/drm_modes.h index 625966a906f2..ff481770d76b 100644 --- a/include/drm/drm_modes.h +++ b/include/drm/drm_modes.h @@ -169,6 +169,8 @@ enum drm_mode_status { * * The horizontal and vertical timings are defined per the following diagram. * + * :: + * * * Active Front Sync Back * Region Porch Porch
I didn't check that everything is in place, it's the job for the tool itself. But everything here looks sane. On the series,
Acked-by: Jani Nikula jani.nikula@intel.com
On Wed, 01 Jun 2016, Daniel Vetter daniel.vetter@ffwll.ch wrote:
Hi Daniel,
Some review comments:
On Tue, May 31, 2016 at 11:11:10PM +0200, Daniel Vetter wrote:
s/in// ?
That last sentence doesn't sound right. Maybe "the driver should try to hide the tiling and virtual (?virtualize?) both &drm_crtc and &drm_plane if needed." ?
I'm not sure what that virtual part refers to.
whenever I see these "can" sentences I automatically start to wonder what happens when that doesn't happen. Maybe a short hint on what @name value will be if not set?
Otherwise, this one looks good.
Best regards, Liviu
dri-devel@lists.freedesktop.org
-
Daniel Vetter -
Daniel Vetter -
Jani Nikula -
Laurent Pinchart -
Liviu Dudau