From 6e3f797c9ae9bd381247e90907838da43f695306 Mon Sep 17 00:00:00 2001 From: Daniel Vetter Date: Mon, 28 Sep 2015 21:46:35 +0200 Subject: drm/doc: Update docs about device instance setup ->load is deprecated, bus functions are deprecated and everyone should use drm_dev_alloc®ister. So update the .tmpl (and pull a bunch of the overview docs into the sourcecode to increase chances that it'll stay in sync in the future) and add notes to functions which are deprecated. I didn't bother to clean up and document the unload sequence similarly since that one is still a bit a mess: drm_dev_unregister does way too much, drm_unplug_dev does what _unregister should be doing but then has the complication of promising something it doesn't actually do (it doesn't unplug existing open fds for instance, only prevents new ones). Motivated since I don't want to hunt every new driver for usage of drm_platform_init any more ;-) v2: Reword the deprecation note for ->load a bit, using Laurent's suggestion as an example (but making the wording a bit stronger even). Fix spelling in commit message. v3: More spelling fixes from Laurent. Cc: Laurent Pinchart Cc: David Herrmann Acked-by: David Herrmann (v2) Signed-off-by: Daniel Vetter Signed-off-by: Daniel Vetter --- Documentation/DocBook/drm.tmpl | 99 ++++++++---------------------------------- 1 file changed, 18 insertions(+), 81 deletions(-) (limited to 'Documentation/DocBook') diff --git a/Documentation/DocBook/drm.tmpl b/Documentation/DocBook/drm.tmpl index 30401f927156..11f5bfb68ecb 100644 --- a/Documentation/DocBook/drm.tmpl +++ b/Documentation/DocBook/drm.tmpl @@ -138,14 +138,10 @@ At the core of every DRM driver is a drm_driver structure. Drivers typically statically initialize a drm_driver structure, - and then pass it to one of the drm_*_init() functions - to register it with the DRM subsystem. - - - Newer drivers that no longer require a drm_bus - structure can alternatively use the low-level device initialization and - registration functions such as drm_dev_alloc() and - drm_dev_register() directly. + and then pass it to drm_dev_alloc() to allocate a + device instance. After the device instance is fully initialized it can be + registered (which makes it accessible from userspace) using + drm_dev_register(). The drm_driver structure contains static @@ -296,83 +292,12 @@ char *date; - Device Registration - - A number of functions are provided to help with device registration. - The functions deal with PCI and platform devices, respectively. - -!Edrivers/gpu/drm/drm_pci.c -!Edrivers/gpu/drm/drm_platform.c - - New drivers that no longer rely on the services provided by the - drm_bus structure can call the low-level - device registration functions directly. The - drm_dev_alloc() function can be used to allocate - and initialize a new drm_device structure. - Drivers will typically want to perform some additional setup on this - structure, such as allocating driver-specific data and storing a - pointer to it in the DRM device's dev_private - field. Drivers should also set the device's unique name using the - drm_dev_set_unique() function. After it has been - set up a device can be registered with the DRM subsystem by calling - drm_dev_register(). This will cause the device to - be exposed to userspace and will call the driver's - .load() implementation. When a device is - removed, the DRM device can safely be unregistered and freed by calling - drm_dev_unregister() followed by a call to - drm_dev_unref(). - + Device Instance and Driver Handling +!Pdrivers/gpu/drm/drm_drv.c driver instance overview !Edrivers/gpu/drm/drm_drv.c Driver Load - - The load method is the driver and device - initialization entry point. The method is responsible for allocating and - initializing driver private data, performing resource allocation and - mapping (e.g. acquiring - clocks, mapping registers or allocating command buffers), initializing - the memory manager (), installing - the IRQ handler (), setting up - vertical blanking handling (), mode - setting () and initial output - configuration (). - - - If compatibility is a concern (e.g. with drivers converted over from - User Mode Setting to Kernel Mode Setting), care must be taken to prevent - device initialization and control that is incompatible with currently - active userspace drivers. For instance, if user level mode setting - drivers are in use, it would be problematic to perform output discovery - & configuration at load time. Likewise, if user-level drivers - unaware of memory management are in use, memory management and command - buffer setup may need to be omitted. These requirements are - driver-specific, and care needs to be taken to keep both old and new - applications and libraries working. - - int (*load) (struct drm_device *, unsigned long flags); - - The method takes two arguments, a pointer to the newly created - drm_device and flags. The flags are used to - pass the driver_data field of the device id - corresponding to the device passed to drm_*_init(). - Only PCI devices currently use this, USB and platform DRM drivers have - their load method called with flags to 0. - - - Driver Private Data - - The driver private hangs off the main - drm_device structure and can be used for - tracking various device-specific bits of information, like register - offsets, command buffer status, register state for suspend/resume, etc. - At load time, a driver may simply allocate one and set - drm_device.dev_priv - appropriately; it should be freed and - drm_device.dev_priv - set to NULL when the driver is unloaded. - - IRQ Registration @@ -465,6 +390,18 @@ char *date; + + Bus-specific Device Registration and PCI Support + + A number of functions are provided to help with device registration. + The functions deal with PCI and platform devices respectively and are + only provided for historical reasons. These are all deprecated and + shouldn't be used in new drivers. Besides that there's a few + helpers for pci drivers. + +!Edrivers/gpu/drm/drm_pci.c +!Edrivers/gpu/drm/drm_platform.c + -- cgit v1.2.3 From 0aaf20cff6dc1b89ec9d63cb004803cf4c0efae7 Mon Sep 17 00:00:00 2001 From: Daniel Vetter Date: Tue, 8 Sep 2015 13:56:27 +0200 Subject: drm/drm_ioctl.c: kerneldoc MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit As usual pull it into the drm docbook template, too. And again as usual I've decided to only document stuff exported to drivers, so all the old leftover markup from the shared drm repo days lost the magic ** signature. Reviewed-by: David Herrmann Reviewed-by: Christian König Signed-off-by: Daniel Vetter --- Documentation/DocBook/drm.tmpl | 1 + drivers/gpu/drm/drm_ioctl.c | 76 ++++++++++++++++++++++++++++++------------ 2 files changed, 55 insertions(+), 22 deletions(-) (limited to 'Documentation/DocBook') diff --git a/Documentation/DocBook/drm.tmpl b/Documentation/DocBook/drm.tmpl index 11f5bfb68ecb..8d0cbf10cbba 100644 --- a/Documentation/DocBook/drm.tmpl +++ b/Documentation/DocBook/drm.tmpl @@ -3689,6 +3689,7 @@ int num_ioctls; +!Edrivers/gpu/drm/drm_ioctl.c diff --git a/drivers/gpu/drm/drm_ioctl.c b/drivers/gpu/drm/drm_ioctl.c index f1c8a158d65b..530c501422fd 100644 --- a/drivers/gpu/drm/drm_ioctl.c +++ b/drivers/gpu/drm/drm_ioctl.c @@ -40,7 +40,7 @@ static int drm_version(struct drm_device *dev, void *data, struct drm_file *file_priv); -/** +/* * Get the bus id. * * \param inode device inode. @@ -75,7 +75,7 @@ drm_unset_busid(struct drm_device *dev, master->unique_len = 0; } -/** +/* * Set the bus id. * * \param inode device inode. @@ -149,7 +149,7 @@ static int drm_set_busid(struct drm_device *dev, struct drm_file *file_priv) return 0; } -/** +/* * Get a mapping information. * * \param inode device inode. @@ -201,7 +201,7 @@ static int drm_getmap(struct drm_device *dev, void *data, return 0; } -/** +/* * Get client information. * * \param inode device inode. @@ -244,7 +244,7 @@ static int drm_getclient(struct drm_device *dev, void *data, } } -/** +/* * Get statistics information. * * \param inode device inode. @@ -265,7 +265,7 @@ static int drm_getstats(struct drm_device *dev, void *data, return 0; } -/** +/* * Get device/driver capabilities */ static int drm_getcap(struct drm_device *dev, void *data, struct drm_file *file_priv) @@ -318,7 +318,7 @@ static int drm_getcap(struct drm_device *dev, void *data, struct drm_file *file_ return 0; } -/** +/* * Set device/driver capabilities */ static int @@ -352,7 +352,7 @@ drm_setclientcap(struct drm_device *dev, void *data, struct drm_file *file_priv) return 0; } -/** +/* * Setversion ioctl. * * \param inode device inode. @@ -406,7 +406,18 @@ done: return retcode; } -/** No-op ioctl. */ +/** + * drm_noop - DRM no-op ioctl implemntation + * @dev: DRM device for the ioctl + * @data: data pointer for the ioctl + * @file_priv: DRM file for the ioctl call + * + * This no-op implementation for drm ioctls is useful for deprecated + * functionality where we can't return a failure code because existing userspace + * checks the result of the ioctl, but doesn't care about the action. + * + * Always returns successfully with 0. + */ int drm_noop(struct drm_device *dev, void *data, struct drm_file *file_priv) { @@ -415,6 +426,21 @@ int drm_noop(struct drm_device *dev, void *data, } EXPORT_SYMBOL(drm_noop); +/** + * drm_invalid_op - DRM invalid ioctl implemntation + * @dev: DRM device for the ioctl + * @data: data pointer for the ioctl + * @file_priv: DRM file for the ioctl call + * + * This no-op implementation for drm ioctls is useful for deprecated + * functionality where we really don't want to allow userspace to call the ioctl + * any more. This is the case for old ums interfaces for drivers that + * transitioned to kms gradually and so kept the old legacy tables around. This + * only applies to radeon and i915 kms drivers, other drivers shouldn't need to + * use this function. + * + * Always fails with a return value of -EINVAL. + */ int drm_invalid_op(struct drm_device *dev, void *data, struct drm_file *file_priv) { @@ -422,7 +448,7 @@ int drm_invalid_op(struct drm_device *dev, void *data, } EXPORT_SYMBOL(drm_invalid_op); -/** +/* * Copy and IOCTL return string to user space */ static int drm_copy_field(char __user *buf, size_t *buf_len, const char *value) @@ -445,7 +471,7 @@ static int drm_copy_field(char __user *buf, size_t *buf_len, const char *value) return 0; } -/** +/* * Get version information * * \param inode device inode. @@ -477,7 +503,7 @@ static int drm_version(struct drm_device *dev, void *data, return err; } -/** +/* * drm_ioctl_permit - Check ioctl permissions against caller * * @flags: ioctl permission flags. @@ -525,7 +551,7 @@ EXPORT_SYMBOL(drm_ioctl_permit); .name = #ioctl \ } -/** Ioctl table */ +/* Ioctl table */ static const struct drm_ioctl_desc drm_ioctls[] = { DRM_IOCTL_DEF(DRM_IOCTL_VERSION, drm_version, DRM_UNLOCKED|DRM_RENDER_ALLOW|DRM_CONTROL_ALLOW), @@ -642,16 +668,16 @@ static const struct drm_ioctl_desc drm_ioctls[] = { #define DRM_CORE_IOCTL_COUNT ARRAY_SIZE( drm_ioctls ) /** - * Called whenever a process performs an ioctl on /dev/drm. - * - * \param inode device inode. - * \param file_priv DRM file private. - * \param cmd command. - * \param arg user argument. - * \return zero on success or negative number on failure. + * drm_ioctl - ioctl callback implementation for DRM drivers + * @filp: file this ioctl is called on + * @cmd: ioctl cmd number + * @arg: user argument * * Looks up the ioctl function in the ::ioctls table, checking for root * previleges if so required, and dispatches to the respective function. + * + * Returns: + * Zero on success, negative error code on failure. */ long drm_ioctl(struct file *filp, unsigned int cmd, unsigned long arg) @@ -761,9 +787,15 @@ EXPORT_SYMBOL(drm_ioctl); /** * drm_ioctl_flags - Check for core ioctl and return ioctl permission flags + * @nr: ioctl number + * @flags: where to return the ioctl permission flags + * + * This ioctl is only used by the vmwgfx driver to augment the access checks + * done by the drm core and insofar a pretty decent layering violation. This + * shouldn't be used by any drivers. * - * @nr: Ioctl number. - * @flags: Where to return the ioctl permission flags + * Returns: + * True if the @nr corresponds to a DRM core ioctl numer, false otherwise. */ bool drm_ioctl_flags(unsigned int nr, unsigned int *flags) { -- cgit v1.2.3