* [PATCH 1/6] drm/doc: Update kerneldoc for drm_crtc.h
@ 2016-05-31 21:11 Daniel Vetter
2016-05-31 21:11 ` [PATCH 2/6] drm/atomic-helper: Fixup kerneldoc for drm_atomic_helper_legacy_gamma_set Daniel Vetter
` (6 more replies)
0 siblings, 7 replies; 18+ messages in thread
From: Daniel Vetter @ 2016-05-31 21:11 UTC (permalink / raw)
To: DRI Development; +Cc: Daniel Vetter
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 */
--
2.8.1
_______________________________________________
dri-devel mailing list
dri-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/dri-devel
^ permalink raw reply related [flat|nested] 18+ messages in thread
* [PATCH 2/6] drm/atomic-helper: Fixup kerneldoc for drm_atomic_helper_legacy_gamma_set
2016-05-31 21:11 [PATCH 1/6] drm/doc: Update kerneldoc for drm_crtc.h Daniel Vetter
@ 2016-05-31 21:11 ` Daniel Vetter
2016-05-31 21:11 ` [PATCH 3/6] drm/doc: Improve kernel-doc for drm_fb_cma_helper.c Daniel Vetter
` (5 subsequent siblings)
6 siblings, 0 replies; 18+ messages in thread
From: Daniel Vetter @ 2016-05-31 21:11 UTC (permalink / raw)
To: DRI Development; +Cc: Daniel Vetter
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
--
2.8.1
_______________________________________________
dri-devel mailing list
dri-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/dri-devel
^ permalink raw reply related [flat|nested] 18+ messages in thread
* [PATCH 3/6] drm/doc: Improve kernel-doc for drm_fb_cma_helper.c
2016-05-31 21:11 [PATCH 1/6] drm/doc: Update kerneldoc for drm_crtc.h Daniel Vetter
2016-05-31 21:11 ` [PATCH 2/6] drm/atomic-helper: Fixup kerneldoc for drm_atomic_helper_legacy_gamma_set Daniel Vetter
@ 2016-05-31 21:11 ` Daniel Vetter
2016-06-02 14:31 ` Liviu Dudau
2016-06-02 22:15 ` Laurent Pinchart
2016-05-31 21:11 ` [PATCH 4/6] drm/gpu.tmpl: Don't forget to rename the include directives, too Daniel Vetter
` (4 subsequent siblings)
6 siblings, 2 replies; 18+ messages in thread
From: Daniel Vetter @ 2016-05-31 21:11 UTC (permalink / raw)
To: DRI Development; +Cc: Daniel Vetter, laurent.pinchart, Daniel Vetter
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)
{
--
2.8.1
_______________________________________________
dri-devel mailing list
dri-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/dri-devel
^ permalink raw reply related [flat|nested] 18+ messages in thread
* [PATCH 4/6] drm/gpu.tmpl: Don't forget to rename the include directives, too
2016-05-31 21:11 [PATCH 1/6] drm/doc: Update kerneldoc for drm_crtc.h Daniel Vetter
2016-05-31 21:11 ` [PATCH 2/6] drm/atomic-helper: Fixup kerneldoc for drm_atomic_helper_legacy_gamma_set Daniel Vetter
2016-05-31 21:11 ` [PATCH 3/6] drm/doc: Improve kernel-doc for drm_fb_cma_helper.c Daniel Vetter
@ 2016-05-31 21:11 ` Daniel Vetter
2016-06-02 13:52 ` Jani Nikula
2016-05-31 21:11 ` [PATCH 5/6] drm/doc: Drop kerneldoc for static functions in drm_irq.c Daniel Vetter
` (3 subsequent siblings)
6 siblings, 1 reply; 18+ messages in thread
From: Daniel Vetter @ 2016-05-31 21:11 UTC (permalink / raw)
To: DRI Development; +Cc: Daniel Vetter, Daniel Vetter
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>
--
2.8.1
_______________________________________________
dri-devel mailing list
dri-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/dri-devel
^ permalink raw reply related [flat|nested] 18+ messages in thread
* [PATCH 5/6] drm/doc: Drop kerneldoc for static functions in drm_irq.c
2016-05-31 21:11 [PATCH 1/6] drm/doc: Update kerneldoc for drm_crtc.h Daniel Vetter
` (2 preceding siblings ...)
2016-05-31 21:11 ` [PATCH 4/6] drm/gpu.tmpl: Don't forget to rename the include directives, too Daniel Vetter
@ 2016-05-31 21:11 ` Daniel Vetter
2016-05-31 21:11 ` [PATCH 6/6] drm/doc: Switch to sphinx/rst fixed-width quoting Daniel Vetter
` (2 subsequent siblings)
6 siblings, 0 replies; 18+ messages in thread
From: Daniel Vetter @ 2016-05-31 21:11 UTC (permalink / raw)
To: DRI Development; +Cc: Daniel Vetter
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
--
2.8.1
_______________________________________________
dri-devel mailing list
dri-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/dri-devel
^ permalink raw reply related [flat|nested] 18+ messages in thread
* [PATCH 6/6] drm/doc: Switch to sphinx/rst fixed-width quoting
2016-05-31 21:11 [PATCH 1/6] drm/doc: Update kerneldoc for drm_crtc.h Daniel Vetter
` (3 preceding siblings ...)
2016-05-31 21:11 ` [PATCH 5/6] drm/doc: Drop kerneldoc for static functions in drm_irq.c Daniel Vetter
@ 2016-05-31 21:11 ` Daniel Vetter
2016-06-01 8:46 ` [PATCH] " Daniel Vetter
2016-06-02 13:50 ` [PATCH 1/6] drm/doc: Update kerneldoc for drm_crtc.h Jani Nikula
2016-06-02 14:28 ` Liviu Dudau
6 siblings, 1 reply; 18+ messages in thread
From: Daniel Vetter @ 2016-05-31 21:11 UTC (permalink / raw)
To: DRI Development; +Cc: Daniel Vetter, Daniel Vetter
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
--
2.8.1
_______________________________________________
dri-devel mailing list
dri-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/dri-devel
^ permalink raw reply related [flat|nested] 18+ messages in thread
* [PATCH] drm/doc: Switch to sphinx/rst fixed-width quoting
2016-05-31 21:11 ` [PATCH 6/6] drm/doc: Switch to sphinx/rst fixed-width quoting Daniel Vetter
@ 2016-06-01 8:46 ` Daniel Vetter
2016-06-01 9:46 ` Jani Nikula
2016-06-02 14:29 ` Daniel Vetter
0 siblings, 2 replies; 18+ messages in thread
From: Daniel Vetter @ 2016-06-01 8:46 UTC (permalink / raw)
To: DRI Development; +Cc: Daniel Vetter, Daniel Vetter
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
--
2.8.1
_______________________________________________
dri-devel mailing list
dri-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/dri-devel
^ permalink raw reply related [flat|nested] 18+ messages in thread
* Re: [PATCH] drm/doc: Switch to sphinx/rst fixed-width quoting
2016-06-01 8:46 ` [PATCH] " Daniel Vetter
@ 2016-06-01 9:46 ` Jani Nikula
2016-06-01 13:33 ` Daniel Vetter
2016-06-02 14:29 ` Daniel Vetter
1 sibling, 1 reply; 18+ messages in thread
From: Jani Nikula @ 2016-06-01 9:46 UTC (permalink / raw)
To: DRI Development; +Cc: Daniel Vetter, Daniel Vetter
On Wed, 01 Jun 2016, Daniel Vetter <daniel.vetter@ffwll.ch> wrote:
> 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?
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-blocks
"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.
> 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
--
Jani Nikula, Intel Open Source Technology Center
_______________________________________________
dri-devel mailing list
dri-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/dri-devel
^ permalink raw reply [flat|nested] 18+ messages in thread
* Re: [PATCH] drm/doc: Switch to sphinx/rst fixed-width quoting
2016-06-01 9:46 ` Jani Nikula
@ 2016-06-01 13:33 ` Daniel Vetter
2016-06-01 13:46 ` Jani Nikula
0 siblings, 1 reply; 18+ messages in thread
From: Daniel Vetter @ 2016-06-01 13:33 UTC (permalink / raw)
To: Jani Nikula; +Cc: Daniel Vetter, DRI Development
On Wed, Jun 1, 2016 at 11:46 AM, Jani Nikula
<jani.nikula@linux.intel.com> wrote:
> On Wed, 01 Jun 2016, Daniel Vetter <daniel.vetter@ffwll.ch> wrote:
>> 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?
>
> 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-blocks
>
> "Blank lines are required before and after a literal block, but these
> blank lines are not included as part of the literal block."
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
--
Daniel Vetter
Software Engineer, Intel Corporation
+41 (0) 79 365 57 48 - http://blog.ffwll.ch
_______________________________________________
dri-devel mailing list
dri-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/dri-devel
^ permalink raw reply [flat|nested] 18+ messages in thread
* Re: [PATCH] drm/doc: Switch to sphinx/rst fixed-width quoting
2016-06-01 13:33 ` Daniel Vetter
@ 2016-06-01 13:46 ` Jani Nikula
2016-06-01 14:44 ` Daniel Vetter
0 siblings, 1 reply; 18+ messages in thread
From: Jani Nikula @ 2016-06-01 13:46 UTC (permalink / raw)
To: Daniel Vetter; +Cc: Daniel Vetter, DRI Development
On Wed, 01 Jun 2016, Daniel Vetter <daniel.vetter@ffwll.ch> wrote:
> On Wed, Jun 1, 2016 at 11:46 AM, Jani Nikula
> <jani.nikula@linux.intel.com> wrote:
>> On Wed, 01 Jun 2016, Daniel Vetter <daniel.vetter@ffwll.ch> wrote:
>>> 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?
>>
>> 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-blocks
>>
>> "Blank lines are required before and after a literal block, but these
>> blank lines are not included as part of the literal block."
>
> 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
What do you mean by "kernel-doc directive" exactly?
> 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.
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.
--
Jani Nikula, Intel Open Source Technology Center
_______________________________________________
dri-devel mailing list
dri-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/dri-devel
^ permalink raw reply [flat|nested] 18+ messages in thread
* Re: [PATCH] drm/doc: Switch to sphinx/rst fixed-width quoting
2016-06-01 13:46 ` Jani Nikula
@ 2016-06-01 14:44 ` Daniel Vetter
0 siblings, 0 replies; 18+ messages in thread
From: Daniel Vetter @ 2016-06-01 14:44 UTC (permalink / raw)
To: Jani Nikula; +Cc: Daniel Vetter, DRI Development, Daniel Vetter
On Wed, Jun 01, 2016 at 04:46:10PM +0300, Jani Nikula wrote:
> On Wed, 01 Jun 2016, Daniel Vetter <daniel.vetter@ffwll.ch> wrote:
> > On Wed, Jun 1, 2016 at 11:46 AM, Jani Nikula
> > <jani.nikula@linux.intel.com> wrote:
> >> On Wed, 01 Jun 2016, Daniel Vetter <daniel.vetter@ffwll.ch> wrote:
> >>> 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?
> >>
> >> 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-blocks
> >>
> >> "Blank lines are required before and after a literal block, but these
> >> blank lines are not included as part of the literal block."
> >
> > 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
>
> What do you mean by "kernel-doc directive" exactly?
>
> > 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.
>
> 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
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
--
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch
_______________________________________________
dri-devel mailing list
dri-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/dri-devel
^ permalink raw reply [flat|nested] 18+ messages in thread
* Re: [PATCH 1/6] drm/doc: Update kerneldoc for drm_crtc.h
2016-05-31 21:11 [PATCH 1/6] drm/doc: Update kerneldoc for drm_crtc.h Daniel Vetter
` (4 preceding siblings ...)
2016-05-31 21:11 ` [PATCH 6/6] drm/doc: Switch to sphinx/rst fixed-width quoting Daniel Vetter
@ 2016-06-02 13:50 ` Jani Nikula
2016-06-02 14:28 ` Liviu Dudau
6 siblings, 0 replies; 18+ messages in thread
From: Jani Nikula @ 2016-06-02 13:50 UTC (permalink / raw)
To: DRI Development; +Cc: Daniel Vetter
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:
> 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 */
--
Jani Nikula, Intel Open Source Technology Center
_______________________________________________
dri-devel mailing list
dri-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/dri-devel
^ permalink raw reply [flat|nested] 18+ messages in thread
* Re: [PATCH 4/6] drm/gpu.tmpl: Don't forget to rename the include directives, too
2016-05-31 21:11 ` [PATCH 4/6] drm/gpu.tmpl: Don't forget to rename the include directives, too Daniel Vetter
@ 2016-06-02 13:52 ` Jani Nikula
2016-06-02 14:28 ` Daniel Vetter
0 siblings, 1 reply; 18+ messages in thread
From: Jani Nikula @ 2016-06-02 13:52 UTC (permalink / raw)
To: DRI Development; +Cc: Daniel Vetter, Daniel Vetter
On Wed, 01 Jun 2016, Daniel Vetter <daniel.vetter@ffwll.ch> wrote:
> 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.
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.
>
> 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>
--
Jani Nikula, Intel Open Source Technology Center
_______________________________________________
dri-devel mailing list
dri-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/dri-devel
^ permalink raw reply [flat|nested] 18+ messages in thread
* Re: [PATCH 1/6] drm/doc: Update kerneldoc for drm_crtc.h
2016-05-31 21:11 [PATCH 1/6] drm/doc: Update kerneldoc for drm_crtc.h Daniel Vetter
` (5 preceding siblings ...)
2016-06-02 13:50 ` [PATCH 1/6] drm/doc: Update kerneldoc for drm_crtc.h Jani Nikula
@ 2016-06-02 14:28 ` Liviu Dudau
6 siblings, 0 replies; 18+ messages in thread
From: Liviu Dudau @ 2016-06-02 14:28 UTC (permalink / raw)
To: Daniel Vetter; +Cc: DRI Development
Hi Daniel,
Some review comments:
On Tue, May 31, 2016 at 11:11:10PM +0200, Daniel Vetter wrote:
> 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
s/in// ?
> + * 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.
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.
> + */
> 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
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?
> * @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 */
> --
> 2.8.1
>
> _______________________________________________
> dri-devel mailing list
> dri-devel@lists.freedesktop.org
> https://lists.freedesktop.org/mailman/listinfo/dri-devel
Otherwise, this one looks good.
Best regards,
Liviu
--
====================
| I would like to |
| fix the world, |
| but they're not |
| giving me the |
\ source code! /
---------------
¯\_(ツ)_/¯
_______________________________________________
dri-devel mailing list
dri-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/dri-devel
^ permalink raw reply [flat|nested] 18+ messages in thread
* Re: [PATCH 4/6] drm/gpu.tmpl: Don't forget to rename the include directives, too
2016-06-02 13:52 ` Jani Nikula
@ 2016-06-02 14:28 ` Daniel Vetter
0 siblings, 0 replies; 18+ messages in thread
From: Daniel Vetter @ 2016-06-02 14:28 UTC (permalink / raw)
To: Jani Nikula; +Cc: Daniel Vetter, DRI Development, Daniel Vetter
On Thu, Jun 02, 2016 at 04:52:08PM +0300, Jani Nikula wrote:
> On Wed, 01 Jun 2016, Daniel Vetter <daniel.vetter@ffwll.ch> wrote:
> > 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.
>
> 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.
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
--
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch
_______________________________________________
dri-devel mailing list
dri-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/dri-devel
^ permalink raw reply [flat|nested] 18+ messages in thread
* [PATCH] drm/doc: Switch to sphinx/rst fixed-width quoting
2016-06-01 8:46 ` [PATCH] " Daniel Vetter
2016-06-01 9:46 ` Jani Nikula
@ 2016-06-02 14:29 ` Daniel Vetter
1 sibling, 0 replies; 18+ messages in thread
From: Daniel Vetter @ 2016-06-02 14:29 UTC (permalink / raw)
To: DRI Development; +Cc: Daniel Vetter, Daniel Vetter
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
--
2.8.1
_______________________________________________
dri-devel mailing list
dri-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/dri-devel
^ permalink raw reply related [flat|nested] 18+ messages in thread
* Re: [PATCH 3/6] drm/doc: Improve kernel-doc for drm_fb_cma_helper.c
2016-05-31 21:11 ` [PATCH 3/6] drm/doc: Improve kernel-doc for drm_fb_cma_helper.c Daniel Vetter
@ 2016-06-02 14:31 ` Liviu Dudau
2016-06-02 22:15 ` Laurent Pinchart
1 sibling, 0 replies; 18+ messages in thread
From: Liviu Dudau @ 2016-06-02 14:31 UTC (permalink / raw)
To: Daniel Vetter; +Cc: Daniel Vetter, laurent.pinchart, DRI Development
On Tue, May 31, 2016 at 11:11:12PM +0200, Daniel Vetter wrote:
> 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>
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
> ---
> 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)
> {
> --
> 2.8.1
>
> _______________________________________________
> dri-devel mailing list
> dri-devel@lists.freedesktop.org
> https://lists.freedesktop.org/mailman/listinfo/dri-devel
--
====================
| I would like to |
| fix the world, |
| but they're not |
| giving me the |
\ source code! /
---------------
¯\_(ツ)_/¯
_______________________________________________
dri-devel mailing list
dri-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/dri-devel
^ permalink raw reply [flat|nested] 18+ messages in thread
* Re: [PATCH 3/6] drm/doc: Improve kernel-doc for drm_fb_cma_helper.c
2016-05-31 21:11 ` [PATCH 3/6] drm/doc: Improve kernel-doc for drm_fb_cma_helper.c Daniel Vetter
2016-06-02 14:31 ` Liviu Dudau
@ 2016-06-02 22:15 ` Laurent Pinchart
1 sibling, 0 replies; 18+ messages in thread
From: Laurent Pinchart @ 2016-06-02 22:15 UTC (permalink / raw)
To: Daniel Vetter; +Cc: Daniel Vetter, DRI Development
Hi Daniel,
Thank you for the patch.
On Tuesday 31 May 2016 23:11:12 Daniel Vetter wrote:
> 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
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.
> + * @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)
> {
--
Regards,
Laurent Pinchart
_______________________________________________
dri-devel mailing list
dri-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/dri-devel
^ permalink raw reply [flat|nested] 18+ messages in thread
end of thread, other threads:[~2016-06-02 22:15 UTC | newest]
Thread overview: 18+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2016-05-31 21:11 [PATCH 1/6] drm/doc: Update kerneldoc for drm_crtc.h Daniel Vetter
2016-05-31 21:11 ` [PATCH 2/6] drm/atomic-helper: Fixup kerneldoc for drm_atomic_helper_legacy_gamma_set Daniel Vetter
2016-05-31 21:11 ` [PATCH 3/6] drm/doc: Improve kernel-doc for drm_fb_cma_helper.c Daniel Vetter
2016-06-02 14:31 ` Liviu Dudau
2016-06-02 22:15 ` Laurent Pinchart
2016-05-31 21:11 ` [PATCH 4/6] drm/gpu.tmpl: Don't forget to rename the include directives, too Daniel Vetter
2016-06-02 13:52 ` Jani Nikula
2016-06-02 14:28 ` Daniel Vetter
2016-05-31 21:11 ` [PATCH 5/6] drm/doc: Drop kerneldoc for static functions in drm_irq.c Daniel Vetter
2016-05-31 21:11 ` [PATCH 6/6] drm/doc: Switch to sphinx/rst fixed-width quoting Daniel Vetter
2016-06-01 8:46 ` [PATCH] " Daniel Vetter
2016-06-01 9:46 ` Jani Nikula
2016-06-01 13:33 ` Daniel Vetter
2016-06-01 13:46 ` Jani Nikula
2016-06-01 14:44 ` Daniel Vetter
2016-06-02 14:29 ` Daniel Vetter
2016-06-02 13:50 ` [PATCH 1/6] drm/doc: Update kerneldoc for drm_crtc.h Jani Nikula
2016-06-02 14:28 ` Liviu Dudau
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.