Merge branches 'for-4.4/upstream-fixes', 'for-4.5/async-suspend',...

What:		/sys/bus/scsi/drivers/st/debug_flag

Date:		October 2015

Kernel Version:	?.?

Contact:	shane.seymour@hpe.com

Description:

		This file allows you to turn debug output from the st driver

		off if you write a '0' to the file or on if you write a '1'.

		Note that debug output requires that the module be compiled

		with the #define DEBUG set to a non-zero value (this is the

		default). If DEBUG is set to 0 then this file will not

		appear in sysfs as its presence is conditional upon debug

		output support being compiled into the module.

Part Ic - DMA addressing limitations

------------------------------------

int

dma_supported(struct device *dev, u64 mask)

Checks to see if the device can support DMA to the memory described by

mask.

Returns: 1 if it can and 0 if it can't.

Notes: This routine merely tests to see if the mask is possible.  It

won't change the current mask settings.  It is more intended as an

internal API for use by the platform than an external API for use by

driver writers.

int

dma_set_mask_and_coherent(struct device *dev, u64 mask)

	    genericirq.xml s390-drivers.xml uio-howto.xml scsi.xml \

	    80211.xml debugobjects.xml sh.xml regulator.xml \

	    alsa-driver-api.xml writing-an-alsa-driver.xml \

	    tracepoint.xml drm.xml media_api.xml w1.xml \

	    tracepoint.xml gpu.xml media_api.xml w1.xml \

	    writing_musb_glue_layer.xml crypto-API.xml iio.xml

include Documentation/DocBook/media/Makefile

<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"

	"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []>

<book id="drmDevelopersGuide">

<book id="gpuDevelopersGuide">

  <bookinfo>

    <title>Linux DRM Developer's Guide</title>

    <title>Linux GPU Driver Developer's Guide</title>

    <authorgroup>

      <author>

	  </address>

	</affiliation>

      </author>

      <author>

	<firstname>Lukas</firstname>

	<surname>Wunner</surname>

	<contrib>vga_switcheroo documentation</contrib>

	<affiliation>

	  <address>

	    <email>lukas@wunner.de</email>

	  </address>

	</affiliation>

      </author>

    </authorgroup>

    <copyright>

      <year>2012</year>

      <holder>Laurent Pinchart</holder>

    </copyright>

    <copyright>

      <year>2015</year>

      <holder>Lukas Wunner</holder>

    </copyright>

    <legalnotice>

      <para>

	<revremark>Added extensive documentation about driver internals.

	</revremark>

      </revision>

      <revision>

	<revnumber>1.1</revnumber>

	<date>2015-10-11</date>

	<authorinitials>LW</authorinitials>

	<revremark>Added vga_switcheroo documentation.

	</revremark>

      </revision>

    </revhistory>

  </bookinfo>

  <title>DRM Core</title>

  <partintro>

    <para>

      This first part of the DRM Developer's Guide documents core DRM code,

      helper libraries for writing drivers and generic userspace interfaces

      exposed by DRM drivers.

      This first part of the GPU Driver Developer's Guide documents core DRM

      code, helper libraries for writing drivers and generic userspace

      interfaces exposed by DRM drivers.

    </para>

  </partintro>

    <para>

      At the core of every DRM driver is a <structname>drm_driver</structname>

      structure. Drivers typically statically initialize a drm_driver structure,

      and then pass it to one of the <function>drm_*_init()</function> functions

      to register it with the DRM subsystem.

    </para>

    <para>

      Newer drivers that no longer require a <structname>drm_bus</structname>

      structure can alternatively use the low-level device initialization and

      registration functions such as <function>drm_dev_alloc()</function> and

      <function>drm_dev_register()</function> directly.

      and then pass it to <function>drm_dev_alloc()</function> to allocate a

      device instance. After the device instance is fully initialized it can be

      registered (which makes it accessible from userspace) using

      <function>drm_dev_register()</function>.

    </para>

    <para>

      The <structname>drm_driver</structname> structure contains static

      </sect3>

    </sect2>

    <sect2>

      <title>Device Registration</title>

      <para>

        A number of functions are provided to help with device registration.

        The functions deal with PCI and platform devices, respectively.

      </para>

!Edrivers/gpu/drm/drm_pci.c

!Edrivers/gpu/drm/drm_platform.c

      <para>

        New drivers that no longer rely on the services provided by the

        <structname>drm_bus</structname> structure can call the low-level

        device registration functions directly. The

        <function>drm_dev_alloc()</function> function can be used to allocate

        and initialize a new <structname>drm_device</structname> 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 <structfield>dev_private</structfield>

        field. Drivers should also set the device's unique name using the

        <function>drm_dev_set_unique()</function> function. After it has been

        set up a device can be registered with the DRM subsystem by calling

        <function>drm_dev_register()</function>. This will cause the device to

        be exposed to userspace and will call the driver's

        <structfield>.load()</structfield> implementation. When a device is

        removed, the DRM device can safely be unregistered and freed by calling

        <function>drm_dev_unregister()</function> followed by a call to

        <function>drm_dev_unref()</function>.

      </para>

      <title>Device Instance and Driver Handling</title>

!Pdrivers/gpu/drm/drm_drv.c driver instance overview

!Edrivers/gpu/drm/drm_drv.c

    </sect2>

    <sect2>

      <title>Driver Load</title>

      <para>

        The <methodname>load</methodname> 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 (<xref linkend="drm-memory-management"/>), installing

        the IRQ handler (<xref linkend="drm-irq-registration"/>), setting up

        vertical blanking handling (<xref linkend="drm-vertical-blank"/>), mode

	setting (<xref linkend="drm-mode-setting"/>) and initial output

	configuration (<xref linkend="drm-kms-init"/>).

      </para>

      <note><para>

        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.

      </para></note>

      <synopsis>int (*load) (struct drm_device *, unsigned long flags);</synopsis>

      <para>

        The method takes two arguments, a pointer to the newly created

	<structname>drm_device</structname> and flags. The flags are used to

	pass the <structfield>driver_data</structfield> field of the device id

	corresponding to the device passed to <function>drm_*_init()</function>.

	Only PCI devices currently use this, USB and platform DRM drivers have

	their <methodname>load</methodname> method called with flags to 0.

      </para>

      <sect3>

        <title>Driver Private Data</title>

        <para>

          The driver private hangs off the main

          <structname>drm_device</structname> 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

          <structname>drm_device</structname>.<structfield>dev_priv</structfield>

          appropriately; it should be freed and

          <structname>drm_device</structname>.<structfield>dev_priv</structfield>

          set to NULL when the driver is unloaded.

        </para>

      </sect3>

      <sect3 id="drm-irq-registration">

        <title>IRQ Registration</title>

        <para>

        </para>

      </sect3>

    </sect2>

    <sect2>

      <title>Bus-specific Device Registration and PCI Support</title>

      <para>

        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.

      </para>

!Edrivers/gpu/drm/drm_pci.c

!Edrivers/gpu/drm/drm_platform.c

    </sect2>

  </sect1>

  <!-- Internals: memory management -->

	plane properties to default value, so that a subsequent open of the

	device will not inherit state from the previous user. It can also be

	used to execute delayed power switching state changes, e.g. in

	conjunction with the vga-switcheroo infrastructure. Beyond that KMS

	drivers should not do any further cleanup. Only legacy UMS drivers might

	need to clean up device state so that the vga console or an independent

	fbdev driver could take over.

	conjunction with the vga_switcheroo infrastructure (see

	<xref linkend="vga_switcheroo"/>). Beyond that KMS drivers should not

	do any further cleanup. Only legacy UMS drivers might need to clean up

	device state so that the vga console or an independent fbdev driver

	could take over.

      </para>

    </sect2>

    <sect2>

	    </para></listitem>

            <listitem><para>

	      DRM_UNLOCKED - The ioctl handler will be called without locking

	      the DRM global mutex

	      the DRM global mutex. This is the enforced default for kms drivers

	      (i.e. using the DRIVER_MODESET flag) and hence shouldn't be used

	      any more for new drivers.

	    </para></listitem>

	  </itemizedlist>

	</para>

      </para>

!Edrivers/gpu/drm/drm_ioctl.c

    </sect2>

  </sect1>

  <sect1>

  <partintro>

    <para>

      This second part of the DRM Developer's Guide documents driver code,

      implementation details and also all the driver-specific userspace

      This second part of the GPU Driver Developer's Guide documents driver

      code, implementation details and also all the driver-specific userspace

      interfaces. Especially since all hardware-acceleration interfaces to

      userspace are driver specific for efficiency and other reasons these

      interfaces can be rather substantial. Hence every driver has its own

	<title>High Definition Audio</title>

!Pdrivers/gpu/drm/i915/intel_audio.c High Definition Audio over HDMI and Display Port

!Idrivers/gpu/drm/i915/intel_audio.c

!Iinclude/drm/i915_component.h

      </sect2>

      <sect2>

	<title>Panel Self Refresh PSR (PSR/SRD)</title>

!Idrivers/gpu/drm/i915/i915_gem_shrinker.c

      </sect2>

    </sect1>

    <sect1>

      <title>GuC-based Command Submission</title>

      <sect2>

        <title>GuC</title>

!Pdrivers/gpu/drm/i915/intel_guc_loader.c GuC-specific firmware loader

!Idrivers/gpu/drm/i915/intel_guc_loader.c

      </sect2>

      <sect2>

        <title>GuC Client</title>

!Pdrivers/gpu/drm/i915/i915_guc_submission.c GuC-based command submissison

!Idrivers/gpu/drm/i915/i915_guc_submission.c

      </sect2>

    </sect1>

    <sect1>

      <title> Tracing </title>

      <para>

  </chapter>

!Cdrivers/gpu/drm/i915/i915_irq.c

</part>

<part id="vga_switcheroo">

  <title>vga_switcheroo</title>

  <partintro>

!Pdrivers/gpu/vga/vga_switcheroo.c Overview

  </partintro>

  <chapter id="modes_of_use">

    <title>Modes of Use</title>

  <sect1>

    <title>Manual switching and manual power control</title>

!Pdrivers/gpu/vga/vga_switcheroo.c Manual switching and manual power control

  </sect1>

  <sect1>

    <title>Driver power control</title>

!Pdrivers/gpu/vga/vga_switcheroo.c Driver power control

  </sect1>

  </chapter>

  <chapter id="pubfunctions">

    <title>Public functions</title>

!Edrivers/gpu/vga/vga_switcheroo.c

  </chapter>

  <chapter id="pubstructures">

    <title>Public structures</title>

!Finclude/linux/vga_switcheroo.h vga_switcheroo_handler

!Finclude/linux/vga_switcheroo.h vga_switcheroo_client_ops

  </chapter>

  <chapter id="pubconstants">

    <title>Public constants</title>

!Finclude/linux/vga_switcheroo.h vga_switcheroo_client_id

!Finclude/linux/vga_switcheroo.h vga_switcheroo_state

  </chapter>

  <chapter id="privstructures">

    <title>Private structures</title>

!Fdrivers/gpu/vga/vga_switcheroo.c vgasr_priv

!Fdrivers/gpu/vga/vga_switcheroo.c vga_switcheroo_client

  </chapter>

!Cdrivers/gpu/vga/vga_switcheroo.c

!Cinclude/linux/vga_switcheroo.h

</part>

</book>

  modprobe ipmi_watchdog timeout=<t> pretimeout=<t> action=<action type>

      preaction=<preaction type> preop=<preop type> start_now=x

      nowayout=x ifnum_to_use=n

      nowayout=x ifnum_to_use=n panic_wdt_timeout=<t>

ifnum_to_use specifies which interface the watchdog timer should use.

The default is -1, which means to pick the first one registered.

occur (if pretimeout is zero, then pretimeout will not be enabled).  Note

that the pretimeout is the time before the final timeout.  So if the

timeout is 50 seconds and the pretimeout is 10 seconds, then the pretimeout

will occur in 40 second (10 seconds before the timeout).

will occur in 40 second (10 seconds before the timeout). The panic_wdt_timeout

is the value of timeout which is set on kernel panic, in order to let actions

such as kdump to occur during panic.

The action may be "reset", "power_cycle", or "power_off", and

specifies what to do when the timer times out, and defaults to

	ipmi_watchdog.preop=<preop type>

	ipmi_watchdog.start_now=x

	ipmi_watchdog.nowayout=x

	ipmi_watchdog.panic_wdt_timeout=<t>

The options are the same as the module parameter options.