From 3512f976d252bd5d07d04e9e157f0cd210c959a0 Mon Sep 17 00:00:00 2001 From: Ville Syrjälä Date: Wed, 24 Apr 2013 18:52:34 +0300 Subject: drm: Add struct drm_rect and assorted utility functions MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit struct drm_rect represents a simple rectangle. The utility functions are there to help driver writers. v2: Moved the region stuff into its own file, made the smaller funcs static inline, used 64bit maths in the scaled clipping function to avoid overflows (instead it will saturate to INT_MIN or INT_MAX). v3: Renamed drm_region to drm_rect, drm_region_clip to drm_rect_intersect, and drm_region_subsample to drm_rect_downscale. v4: Renamed some function parameters, improve kernel-doc comments a bit, and actually generate documentation for drm_rect.[ch]. v5: s/RETUTRNS/RETURNS/ Reviewed-by: Laurent Pinchart Reviewed-by: Chris Wilson Signed-off-by: Ville Syrjälä Acked-by: Dave Airlie Signed-off-by: Daniel Vetter --- Documentation/DocBook/drm.tmpl | 2 ++ 1 file changed, 2 insertions(+) (limited to 'Documentation/DocBook/drm.tmpl') diff --git a/Documentation/DocBook/drm.tmpl b/Documentation/DocBook/drm.tmpl index f9df3b872c16..7c7af25b330c 100644 --- a/Documentation/DocBook/drm.tmpl +++ b/Documentation/DocBook/drm.tmpl @@ -1653,6 +1653,8 @@ void intel_crt_init(struct drm_device *dev) KMS API Functions !Edrivers/gpu/drm/drm_crtc.c +!Edrivers/gpu/drm/drm_rect.c +!Finclude/drm/drm_rect.h -- cgit v1.2.3 From 039735369c8fb105d0a090c949b7f894425121d8 Mon Sep 17 00:00:00 2001 From: Ville Syrjälä Date: Wed, 8 May 2013 17:16:45 +0300 Subject: drm: Fix drm_rect documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The 'struct' keyword was missing so struct drm_rect documentation never ended up in the generated docs. Also move the drm_rect documentations to a new section alognside the various helper functions and add a short description about the intended purpose of drm_rect. v2: Move to new section and add general description Signed-off-by: Ville Syrjälä Signed-off-by: Daniel Vetter --- Documentation/DocBook/drm.tmpl | 8 ++++++-- include/drm/drm_rect.h | 9 ++++++++- 2 files changed, 14 insertions(+), 3 deletions(-) (limited to 'Documentation/DocBook/drm.tmpl') diff --git a/Documentation/DocBook/drm.tmpl b/Documentation/DocBook/drm.tmpl index 7c7af25b330c..91ee107d5d0e 100644 --- a/Documentation/DocBook/drm.tmpl +++ b/Documentation/DocBook/drm.tmpl @@ -1653,8 +1653,6 @@ void intel_crt_init(struct drm_device *dev) KMS API Functions !Edrivers/gpu/drm/drm_crtc.c -!Edrivers/gpu/drm/drm_rect.c -!Finclude/drm/drm_rect.h @@ -2163,6 +2161,12 @@ void intel_crt_init(struct drm_device *dev) EDID Helper Functions Reference !Edrivers/gpu/drm/drm_edid.c + + Rectangle Utilities Reference +!Pinclude/drm/drm_rect.h rect utils +!Iinclude/drm/drm_rect.h +!Edrivers/gpu/drm/drm_rect.c + diff --git a/include/drm/drm_rect.h b/include/drm/drm_rect.h index 64fa265c6ffb..d1286297567b 100644 --- a/include/drm/drm_rect.h +++ b/include/drm/drm_rect.h @@ -25,7 +25,14 @@ #define DRM_RECT_H /** - * drm_rect - two dimensional rectangle + * DOC: rect utils + * + * Utility functions to help manage rectangular areas for + * clipping, scaling, etc. calculations. + */ + +/** + * struct drm_rect - two dimensional rectangle * @x1: horizontal starting coordinate (inclusive) * @x2: horizontal ending coordinate (exclusive) * @y1: vertical starting coordinate (inclusive) -- cgit v1.2.3 From 02b6298541f8a711b3f9cf589f7e508bd5cb99d8 Mon Sep 17 00:00:00 2001 From: Laurent Pinchart Date: Sat, 22 Jun 2013 14:10:59 +0200 Subject: drm: Improve manual IRQ installation documentation Define the rules for using irqs from drm drivers. Signed-off-by: Laurent Pinchart Reviewed-by: Daniel Vetter Signed-off-by: Dave Airlie --- Documentation/DocBook/drm.tmpl | 118 ++++++++++++++++++++++++----------------- 1 file changed, 70 insertions(+), 48 deletions(-) (limited to 'Documentation/DocBook/drm.tmpl') diff --git a/Documentation/DocBook/drm.tmpl b/Documentation/DocBook/drm.tmpl index 91ee107d5d0e..a6080941f5e4 100644 --- a/Documentation/DocBook/drm.tmpl +++ b/Documentation/DocBook/drm.tmpl @@ -186,11 +186,12 @@ DRIVER_HAVE_IRQDRIVER_IRQ_SHARED - DRIVER_HAVE_IRQ indicates whether the driver has an IRQ handler. The - DRM core will automatically register an interrupt handler when the - flag is set. DRIVER_IRQ_SHARED indicates whether the device & - handler support shared IRQs (note that this is required of PCI - drivers). + DRIVER_HAVE_IRQ indicates whether the driver has an IRQ handler + managed by the DRM Core. The core will support simple IRQ handler + installation when the flag is set. The installation process is + described in . + DRIVER_IRQ_SHARED indicates whether the device & handler + support shared IRQs (note that this is required of PCI drivers). @@ -344,50 +345,71 @@ char *date; The DRM core tries to facilitate IRQ handler registration and unregistration by providing drm_irq_install and drm_irq_uninstall functions. Those functions only - support a single interrupt per device. - - - - Both functions get the device IRQ by calling - drm_dev_to_irq. This inline function will call a - bus-specific operation to retrieve the IRQ number. For platform devices, - platform_get_irq(..., 0) is used to retrieve the - IRQ number. - - - drm_irq_install starts by calling the - irq_preinstall driver operation. The operation - is optional and must make sure that the interrupt will not get fired by - clearing all pending interrupt flags or disabling the interrupt. - - - The IRQ will then be requested by a call to - request_irq. If the DRIVER_IRQ_SHARED driver - feature flag is set, a shared (IRQF_SHARED) IRQ handler will be - requested. - - - The IRQ handler function must be provided as the mandatory irq_handler - driver operation. It will get passed directly to - request_irq and thus has the same prototype as all - IRQ handlers. It will get called with a pointer to the DRM device as the - second argument. - - - Finally the function calls the optional - irq_postinstall driver operation. The operation - usually enables interrupts (excluding the vblank interrupt, which is - enabled separately), but drivers may choose to enable/disable interrupts - at a different time. - - - drm_irq_uninstall is similarly used to uninstall an - IRQ handler. It starts by waking up all processes waiting on a vblank - interrupt to make sure they don't hang, and then calls the optional - irq_uninstall driver operation. The operation - must disable all hardware interrupts. Finally the function frees the IRQ - by calling free_irq. + support a single interrupt per device, devices that use more than one + IRQs need to be handled manually. + + Managed IRQ Registration + + Both the drm_irq_install and + drm_irq_uninstall functions get the device IRQ by + calling drm_dev_to_irq. This inline function will + call a bus-specific operation to retrieve the IRQ number. For platform + devices, platform_get_irq(..., 0) is used to + retrieve the IRQ number. + + + drm_irq_install starts by calling the + irq_preinstall driver operation. The operation + is optional and must make sure that the interrupt will not get fired by + clearing all pending interrupt flags or disabling the interrupt. + + + The IRQ will then be requested by a call to + request_irq. If the DRIVER_IRQ_SHARED driver + feature flag is set, a shared (IRQF_SHARED) IRQ handler will be + requested. + + + The IRQ handler function must be provided as the mandatory irq_handler + driver operation. It will get passed directly to + request_irq and thus has the same prototype as all + IRQ handlers. It will get called with a pointer to the DRM device as the + second argument. + + + Finally the function calls the optional + irq_postinstall driver operation. The operation + usually enables interrupts (excluding the vblank interrupt, which is + enabled separately), but drivers may choose to enable/disable interrupts + at a different time. + + + drm_irq_uninstall is similarly used to uninstall an + IRQ handler. It starts by waking up all processes waiting on a vblank + interrupt to make sure they don't hang, and then calls the optional + irq_uninstall driver operation. The operation + must disable all hardware interrupts. Finally the function frees the IRQ + by calling free_irq. + + + + Manual IRQ Registration + + Drivers that require multiple interrupt handlers can't use the managed + IRQ registration functions. In that case IRQs must be registered and + unregistered manually (usually with the request_irq + and free_irq functions, or their devm_* equivalent). + + + When manually registering IRQs, drivers must not set the DRIVER_HAVE_IRQ + driver feature flag, and must not provide the + irq_handler driver operation. They must set the + drm_device irq_enabled + field to 1 upon registration of the IRQs, and clear it to 0 after + unregistering the IRQs. + + Memory Manager Initialization -- cgit v1.2.3 From 02c030a718e7fc6e066c6169c195f53b461df408 Mon Sep 17 00:00:00 2001 From: Laurent Pinchart Date: Sat, 22 Jun 2013 16:10:29 +0200 Subject: drm/doc: Remove outdated note about i915 driver not behaving properly The i915 driver has been fixed not to modify the mode argument of the encoder mode_fixup operation. Remove the related comment from the documentation. Signed-off-by: Laurent Pinchart Reviewed-by: Alex Deucher Signed-off-by: Dave Airlie --- Documentation/DocBook/drm.tmpl | 4 ---- 1 file changed, 4 deletions(-) (limited to 'Documentation/DocBook/drm.tmpl') diff --git a/Documentation/DocBook/drm.tmpl b/Documentation/DocBook/drm.tmpl index a6080941f5e4..cea420dc712d 100644 --- a/Documentation/DocBook/drm.tmpl +++ b/Documentation/DocBook/drm.tmpl @@ -1868,10 +1868,6 @@ void intel_crt_init(struct drm_device *dev) bool (*mode_fixup)(struct drm_encoder *encoder, const struct drm_display_mode *mode, struct drm_display_mode *adjusted_mode); - - FIXME: The mode argument be const, but the i915 driver modifies - mode->clock in intel_dp_mode_fixup. - Let encoders adjust the requested mode or reject it completely. This operation returns true if the mode is accepted (possibly after being -- cgit v1.2.3 From 421cda3e324fce40e3f7abdf3d31cae1d0deddcd Mon Sep 17 00:00:00 2001 From: Laurent Pinchart Date: Sat, 22 Jun 2013 16:10:30 +0200 Subject: drm/doc: Document the KMS property API Signed-off-by: Laurent Pinchart Reviewed-by: Alex Deucher Signed-off-by: Dave Airlie --- Documentation/DocBook/drm.tmpl | 143 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 143 insertions(+) (limited to 'Documentation/DocBook/drm.tmpl') diff --git a/Documentation/DocBook/drm.tmpl b/Documentation/DocBook/drm.tmpl index cea420dc712d..4d54ac8b2032 100644 --- a/Documentation/DocBook/drm.tmpl +++ b/Documentation/DocBook/drm.tmpl @@ -1235,6 +1235,15 @@ int max_width, max_height; Miscellaneous + + void (*set_property)(struct drm_crtc *crtc, + struct drm_property *property, uint64_t value); + + Set the value of the given CRTC property to + value. See + for more information about properties. + + void (*gamma_set)(struct drm_crtc *crtc, u16 *r, u16 *g, u16 *b, uint32_t start, uint32_t size); @@ -1385,6 +1394,15 @@ int max_width, max_height; . + + void (*set_property)(struct drm_plane *plane, + struct drm_property *property, uint64_t value); + + Set the value of the given plane property to + value. See + for more information about properties. + + @@ -1593,6 +1611,15 @@ int max_width, max_height; Miscellaneous + + void (*set_property)(struct drm_connector *connector, + struct drm_property *property, uint64_t value); + + Set the value of the given connector property to + value. See + for more information about properties. + + void (*destroy)(struct drm_connector *connector); @@ -2187,6 +2214,122 @@ void intel_crt_init(struct drm_device *dev) + + + + KMS Properties + + Drivers may need to expose additional parameters to applications than + those described in the previous sections. KMS supports attaching + properties to CRTCs, connectors and planes and offers a userspace API to + list, get and set the property values. + + + Properties are identified by a name that uniquely defines the property + purpose, and store an associated value. For all property types except blob + properties the value is a 64-bit unsigned integer. + + + KMS differentiates between properties and property instances. Drivers + first create properties and then create and associate individual instances + of those properties to objects. A property can be instantiated multiple + times and associated with different objects. Values are stored in property + instances, and all other property information are stored in the propery + and shared between all instances of the property. + + + Every property is created with a type that influences how the KMS core + handles the property. Supported property types are + + + DRM_MODE_PROP_RANGE + Range properties report their minimum and maximum + admissible values. The KMS core verifies that values set by + application fit in that range. + + + DRM_MODE_PROP_ENUM + Enumerated properties take a numerical value that + ranges from 0 to the number of enumerated values defined by the + property minus one, and associate a free-formed string name to each + value. Applications can retrieve the list of defined value-name pairs + and use the numerical value to get and set property instance values. + + + + DRM_MODE_PROP_BITMASK + Bitmask properties are enumeration properties that + additionally restrict all enumerated values to the 0..63 range. + Bitmask property instance values combine one or more of the + enumerated bits defined by the property. + + + DRM_MODE_PROP_BLOB + Blob properties store a binary blob without any format + restriction. The binary blobs are created as KMS standalone objects, + and blob property instance values store the ID of their associated + blob object. + Blob properties are only used for the connector EDID property + and cannot be created by drivers. + + + + + To create a property drivers call one of the following functions depending + on the property type. All property creation functions take property flags + and name, as well as type-specific arguments. + + + struct drm_property *drm_property_create_range(struct drm_device *dev, int flags, + const char *name, + uint64_t min, uint64_t max); + Create a range property with the given minimum and maximum + values. + + + struct drm_property *drm_property_create_enum(struct drm_device *dev, int flags, + const char *name, + const struct drm_prop_enum_list *props, + int num_values); + Create an enumerated property. The props + argument points to an array of num_values + value-name pairs. + + + struct drm_property *drm_property_create_bitmask(struct drm_device *dev, + int flags, const char *name, + const struct drm_prop_enum_list *props, + int num_values); + Create a bitmask property. The props + argument points to an array of num_values + value-name pairs. + + + + + Properties can additionally be created as immutable, in which case they + will be read-only for applications but can be modified by the driver. To + create an immutable property drivers must set the DRM_MODE_PROP_IMMUTABLE + flag at property creation time. + + + When no array of value-name pairs is readily available at property + creation time for enumerated or range properties, drivers can create + the property using the drm_property_create function + and manually add enumeration value-name pairs by calling the + drm_property_add_enum function. Care must be taken to + properly specify the property type through the flags + argument. + + + After creating properties drivers can attach property instances to CRTC, + connector and plane objects by calling the + drm_object_attach_property. The function takes a + pointer to the target object, a pointer to the previously created property + and an initial instance value. + + + -- cgit v1.2.3