diff options
Diffstat (limited to 'Documentation/DocBook/drm.tmpl')
| -rw-r--r-- | Documentation/DocBook/drm.tmpl | 271 |
1 files changed, 219 insertions, 52 deletions
diff --git a/Documentation/DocBook/drm.tmpl b/Documentation/DocBook/drm.tmpl index 6dd8d10d6b7e..7d1278e7a434 100644 --- a/Documentation/DocBook/drm.tmpl +++ b/Documentation/DocBook/drm.tmpl @@ -186,11 +186,12 @@ <varlistentry> <term>DRIVER_HAVE_IRQ</term><term>DRIVER_IRQ_SHARED</term> <listitem><para> - 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 <xref linkend="drm-irq-registration"/>.</para> + <para>DRIVER_IRQ_SHARED indicates whether the device & handler + support shared IRQs (note that this is required of PCI drivers). </para></listitem> </varlistentry> <varlistentry> @@ -344,50 +345,71 @@ char *date;</synopsis> The DRM core tries to facilitate IRQ handler registration and unregistration by providing <function>drm_irq_install</function> and <function>drm_irq_uninstall</function> functions. Those functions only - support a single interrupt per device. - </para> - <!--!Fdrivers/char/drm/drm_irq.c drm_irq_install--> - <para> - Both functions get the device IRQ by calling - <function>drm_dev_to_irq</function>. This inline function will call a - bus-specific operation to retrieve the IRQ number. For platform devices, - <function>platform_get_irq</function>(..., 0) is used to retrieve the - IRQ number. - </para> - <para> - <function>drm_irq_install</function> starts by calling the - <methodname>irq_preinstall</methodname> 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. - </para> - <para> - The IRQ will then be requested by a call to - <function>request_irq</function>. If the DRIVER_IRQ_SHARED driver - feature flag is set, a shared (IRQF_SHARED) IRQ handler will be - requested. - </para> - <para> - The IRQ handler function must be provided as the mandatory irq_handler - driver operation. It will get passed directly to - <function>request_irq</function> 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. - </para> - <para> - Finally the function calls the optional - <methodname>irq_postinstall</methodname> 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. - </para> - <para> - <function>drm_irq_uninstall</function> 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 - <methodname>irq_uninstall</methodname> driver operation. The operation - must disable all hardware interrupts. Finally the function frees the IRQ - by calling <function>free_irq</function>. + support a single interrupt per device, devices that use more than one + IRQs need to be handled manually. </para> + <sect4> + <title>Managed IRQ Registration</title> + <para> + Both the <function>drm_irq_install</function> and + <function>drm_irq_uninstall</function> functions get the device IRQ by + calling <function>drm_dev_to_irq</function>. This inline function will + call a bus-specific operation to retrieve the IRQ number. For platform + devices, <function>platform_get_irq</function>(..., 0) is used to + retrieve the IRQ number. + </para> + <para> + <function>drm_irq_install</function> starts by calling the + <methodname>irq_preinstall</methodname> 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. + </para> + <para> + The IRQ will then be requested by a call to + <function>request_irq</function>. If the DRIVER_IRQ_SHARED driver + feature flag is set, a shared (IRQF_SHARED) IRQ handler will be + requested. + </para> + <para> + The IRQ handler function must be provided as the mandatory irq_handler + driver operation. It will get passed directly to + <function>request_irq</function> 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. + </para> + <para> + Finally the function calls the optional + <methodname>irq_postinstall</methodname> 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. + </para> + <para> + <function>drm_irq_uninstall</function> 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 + <methodname>irq_uninstall</methodname> driver operation. The operation + must disable all hardware interrupts. Finally the function frees the IRQ + by calling <function>free_irq</function>. + </para> + </sect4> + <sect4> + <title>Manual IRQ Registration</title> + <para> + 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 <function>request_irq</function> + and <function>free_irq</function> functions, or their devm_* equivalent). + </para> + <para> + When manually registering IRQs, drivers must not set the DRIVER_HAVE_IRQ + driver feature flag, and must not provide the + <methodname>irq_handler</methodname> driver operation. They must set the + <structname>drm_device</structname> <structfield>irq_enabled</structfield> + field to 1 upon registration of the IRQs, and clear it to 0 after + unregistering the IRQs. + </para> + </sect4> </sect3> <sect3> <title>Memory Manager Initialization</title> @@ -1214,6 +1236,15 @@ int max_width, max_height;</synopsis> <title>Miscellaneous</title> <itemizedlist> <listitem> + <synopsis>void (*set_property)(struct drm_crtc *crtc, + struct drm_property *property, uint64_t value);</synopsis> + <para> + Set the value of the given CRTC property to + <parameter>value</parameter>. See <xref linkend="drm-kms-properties"/> + for more information about properties. + </para> + </listitem> + <listitem> <synopsis>void (*gamma_set)(struct drm_crtc *crtc, u16 *r, u16 *g, u16 *b, uint32_t start, uint32_t size);</synopsis> <para> @@ -1363,6 +1394,15 @@ int max_width, max_height;</synopsis> <xref linkend="drm-kms-init"/>. </para> </listitem> + <listitem> + <synopsis>void (*set_property)(struct drm_plane *plane, + struct drm_property *property, uint64_t value);</synopsis> + <para> + Set the value of the given plane property to + <parameter>value</parameter>. See <xref linkend="drm-kms-properties"/> + for more information about properties. + </para> + </listitem> </itemizedlist> </sect3> </sect2> @@ -1572,6 +1612,15 @@ int max_width, max_height;</synopsis> <title>Miscellaneous</title> <itemizedlist> <listitem> + <synopsis>void (*set_property)(struct drm_connector *connector, + struct drm_property *property, uint64_t value);</synopsis> + <para> + Set the value of the given connector property to + <parameter>value</parameter>. See <xref linkend="drm-kms-properties"/> + for more information about properties. + </para> + </listitem> + <listitem> <synopsis>void (*destroy)(struct drm_connector *connector);</synopsis> <para> Destroy the connector when not needed anymore. See @@ -1846,10 +1895,6 @@ void intel_crt_init(struct drm_device *dev) <synopsis>bool (*mode_fixup)(struct drm_encoder *encoder, const struct drm_display_mode *mode, struct drm_display_mode *adjusted_mode);</synopsis> - <note><para> - FIXME: The mode argument be const, but the i915 driver modifies - mode->clock in <function>intel_dp_mode_fixup</function>. - </para></note> <para> Let encoders adjust the requested mode or reject it completely. This operation returns true if the mode is accepted (possibly after being @@ -2161,6 +2206,128 @@ void intel_crt_init(struct drm_device *dev) <title>EDID Helper Functions Reference</title> !Edrivers/gpu/drm/drm_edid.c </sect2> + <sect2> + <title>Rectangle Utilities Reference</title> +!Pinclude/drm/drm_rect.h rect utils +!Iinclude/drm/drm_rect.h +!Edrivers/gpu/drm/drm_rect.c + </sect2> + </sect1> + + <!-- Internals: kms properties --> + + <sect1 id="drm-kms-properties"> + <title>KMS Properties</title> + <para> + 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. + </para> + <para> + 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. + </para> + <para> + 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. + </para> + <para> + Every property is created with a type that influences how the KMS core + handles the property. Supported property types are + <variablelist> + <varlistentry> + <term>DRM_MODE_PROP_RANGE</term> + <listitem><para>Range properties report their minimum and maximum + admissible values. The KMS core verifies that values set by + application fit in that range.</para></listitem> + </varlistentry> + <varlistentry> + <term>DRM_MODE_PROP_ENUM</term> + <listitem><para>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. + </para></listitem> + </varlistentry> + <varlistentry> + <term>DRM_MODE_PROP_BITMASK</term> + <listitem><para>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.</para></listitem> + </varlistentry> + <varlistentry> + <term>DRM_MODE_PROP_BLOB</term> + <listitem><para>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.</para> + <para>Blob properties are only used for the connector EDID property + and cannot be created by drivers.</para></listitem> + </varlistentry> + </variablelist> + </para> + <para> + 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. + <itemizedlist> + <listitem> + <synopsis>struct drm_property *drm_property_create_range(struct drm_device *dev, int flags, + const char *name, + uint64_t min, uint64_t max);</synopsis> + <para>Create a range property with the given minimum and maximum + values.</para> + </listitem> + <listitem> + <synopsis>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);</synopsis> + <para>Create an enumerated property. The <parameter>props</parameter> + argument points to an array of <parameter>num_values</parameter> + value-name pairs.</para> + </listitem> + <listitem> + <synopsis>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);</synopsis> + <para>Create a bitmask property. The <parameter>props</parameter> + argument points to an array of <parameter>num_values</parameter> + value-name pairs.</para> + </listitem> + </itemizedlist> + </para> + <para> + 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. + </para> + <para> + 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 <function>drm_property_create</function> function + and manually add enumeration value-name pairs by calling the + <function>drm_property_add_enum</function> function. Care must be taken to + properly specify the property type through the <parameter>flags</parameter> + argument. + </para> + <para> + After creating properties drivers can attach property instances to CRTC, + connector and plane objects by calling the + <function>drm_object_attach_property</function>. The function takes a + pointer to the target object, a pointer to the previously created property + and an initial instance value. + </para> </sect1> <!-- Internals: vertical blanking --> |