diff options
Diffstat (limited to 'Documentation/driver-api')
-rw-r--r-- | Documentation/driver-api/basics.rst | 21 | ||||
-rw-r--r-- | Documentation/driver-api/dmaengine/provider.rst | 38 | ||||
-rw-r--r-- | Documentation/driver-api/iio/hw-consumer.rst | 51 | ||||
-rw-r--r-- | Documentation/driver-api/iio/index.rst | 1 | ||||
-rw-r--r-- | Documentation/driver-api/pm/devices.rst | 54 | ||||
-rw-r--r-- | Documentation/driver-api/scsi.rst | 10 | ||||
-rw-r--r-- | Documentation/driver-api/usb/usb3-debug-port.rst | 52 | ||||
-rw-r--r-- | Documentation/driver-api/usb/writing_usb_driver.rst | 2 |
8 files changed, 190 insertions, 39 deletions
diff --git a/Documentation/driver-api/basics.rst b/Documentation/driver-api/basics.rst index 73fa7d42bbba..826e85d50a16 100644 --- a/Documentation/driver-api/basics.rst +++ b/Documentation/driver-api/basics.rst @@ -13,12 +13,6 @@ Driver device table .. kernel-doc:: include/linux/mod_devicetable.h :internal: -Atomic and pointer manipulation -------------------------------- - -.. kernel-doc:: arch/x86/include/asm/atomic.h - :internal: - Delaying, scheduling, and timer routines ---------------------------------------- @@ -85,6 +79,21 @@ Internal Functions .. kernel-doc:: kernel/kthread.c :export: +Reference counting +------------------ + +.. kernel-doc:: include/linux/refcount.h + :internal: + +.. kernel-doc:: lib/refcount.c + :export: + +Atomics +------- + +.. kernel-doc:: arch/x86/include/asm/atomic.h + :internal: + Kernel objects manipulation --------------------------- diff --git a/Documentation/driver-api/dmaengine/provider.rst b/Documentation/driver-api/dmaengine/provider.rst index 814acb4d2294..dfc4486b5743 100644 --- a/Documentation/driver-api/dmaengine/provider.rst +++ b/Documentation/driver-api/dmaengine/provider.rst @@ -111,40 +111,36 @@ The first thing you need to do in your driver is to allocate this structure. Any of the usual memory allocators will do, but you'll also need to initialize a few fields in there: -- channels: should be initialized as a list using the +- ``channels``: should be initialized as a list using the INIT_LIST_HEAD macro for example -- src_addr_widths: +- ``src_addr_widths``: should contain a bitmask of the supported source transfer width -- dst_addr_widths: +- ``dst_addr_widths``: should contain a bitmask of the supported destination transfer width -- directions: +- ``directions``: should contain a bitmask of the supported slave directions (i.e. excluding mem2mem transfers) -- residue_granularity: +- ``residue_granularity``: + granularity of the transfer residue reported to dma_set_residue. + This can be either: - - Granularity of the transfer residue reported to dma_set_residue. - This can be either: + - Descriptor: + your device doesn't support any kind of residue + reporting. The framework will only know that a particular + transaction descriptor is done. - - Descriptor + - Segment: + your device is able to report which chunks have been transferred - - Your device doesn't support any kind of residue - reporting. The framework will only know that a particular - transaction descriptor is done. + - Burst: + your device is able to report which burst have been transferred - - Segment - - - Your device is able to report which chunks have been transferred - - - Burst - - - Your device is able to report which burst have been transferred - - - dev: should hold the pointer to the ``struct device`` associated - to your current driver instance. +- ``dev``: should hold the pointer to the ``struct device`` associated + to your current driver instance. Supported transaction types --------------------------- diff --git a/Documentation/driver-api/iio/hw-consumer.rst b/Documentation/driver-api/iio/hw-consumer.rst new file mode 100644 index 000000000000..8facce6a6733 --- /dev/null +++ b/Documentation/driver-api/iio/hw-consumer.rst @@ -0,0 +1,51 @@ +=========== +HW consumer +=========== +An IIO device can be directly connected to another device in hardware. in this +case the buffers between IIO provider and IIO consumer are handled by hardware. +The Industrial I/O HW consumer offers a way to bond these IIO devices without +software buffer for data. The implementation can be found under +:file:`drivers/iio/buffer/hw-consumer.c` + + +* struct :c:type:`iio_hw_consumer` — Hardware consumer structure +* :c:func:`iio_hw_consumer_alloc` — Allocate IIO hardware consumer +* :c:func:`iio_hw_consumer_free` — Free IIO hardware consumer +* :c:func:`iio_hw_consumer_enable` — Enable IIO hardware consumer +* :c:func:`iio_hw_consumer_disable` — Disable IIO hardware consumer + + +HW consumer setup +================= + +As standard IIO device the implementation is based on IIO provider/consumer. +A typical IIO HW consumer setup looks like this:: + + static struct iio_hw_consumer *hwc; + + static const struct iio_info adc_info = { + .read_raw = adc_read_raw, + }; + + static int adc_read_raw(struct iio_dev *indio_dev, + struct iio_chan_spec const *chan, int *val, + int *val2, long mask) + { + ret = iio_hw_consumer_enable(hwc); + + /* Acquire data */ + + ret = iio_hw_consumer_disable(hwc); + } + + static int adc_probe(struct platform_device *pdev) + { + hwc = devm_iio_hw_consumer_alloc(&iio->dev); + } + +More details +============ +.. kernel-doc:: include/linux/iio/hw-consumer.h +.. kernel-doc:: drivers/iio/buffer/industrialio-hw-consumer.c + :export: + diff --git a/Documentation/driver-api/iio/index.rst b/Documentation/driver-api/iio/index.rst index e5c3922d1b6f..7fba341bd8b2 100644 --- a/Documentation/driver-api/iio/index.rst +++ b/Documentation/driver-api/iio/index.rst @@ -15,3 +15,4 @@ Contents: buffers triggers triggered-buffers + hw-consumer diff --git a/Documentation/driver-api/pm/devices.rst b/Documentation/driver-api/pm/devices.rst index 53c1b0b06da5..1128705a5731 100644 --- a/Documentation/driver-api/pm/devices.rst +++ b/Documentation/driver-api/pm/devices.rst @@ -777,17 +777,51 @@ The driver can indicate that by setting ``DPM_FLAG_SMART_SUSPEND`` in runtime suspend at the beginning of the ``suspend_late`` phase of system-wide suspend (or in the ``poweroff_late`` phase of hibernation), when runtime PM has been disabled for it, under the assumption that its state should not change -after that point until the system-wide transition is over. If that happens, the -driver's system-wide resume callbacks, if present, may still be invoked during -the subsequent system-wide resume transition and the device's runtime power -management status may be set to "active" before enabling runtime PM for it, -so the driver must be prepared to cope with the invocation of its system-wide -resume callbacks back-to-back with its ``->runtime_suspend`` one (without the -intervening ``->runtime_resume`` and so on) and the final state of the device -must reflect the "active" status for runtime PM in that case. +after that point until the system-wide transition is over (the PM core itself +does that for devices whose "noirq", "late" and "early" system-wide PM callbacks +are executed directly by it). If that happens, the driver's system-wide resume +callbacks, if present, may still be invoked during the subsequent system-wide +resume transition and the device's runtime power management status may be set +to "active" before enabling runtime PM for it, so the driver must be prepared to +cope with the invocation of its system-wide resume callbacks back-to-back with +its ``->runtime_suspend`` one (without the intervening ``->runtime_resume`` and +so on) and the final state of the device must reflect the "active" runtime PM +status in that case. During system-wide resume from a sleep state it's easiest to put devices into the full-power state, as explained in :file:`Documentation/power/runtime_pm.txt`. -Refer to that document for more information regarding this particular issue as +[Refer to that document for more information regarding this particular issue as well as for information on the device runtime power management framework in -general. +general.] + +However, it often is desirable to leave devices in suspend after system +transitions to the working state, especially if those devices had been in +runtime suspend before the preceding system-wide suspend (or analogous) +transition. Device drivers can use the ``DPM_FLAG_LEAVE_SUSPENDED`` flag to +indicate to the PM core (and middle-layer code) that they prefer the specific +devices handled by them to be left suspended and they have no problems with +skipping their system-wide resume callbacks for this reason. Whether or not the +devices will actually be left in suspend may depend on their state before the +given system suspend-resume cycle and on the type of the system transition under +way. In particular, devices are not left suspended if that transition is a +restore from hibernation, as device states are not guaranteed to be reflected +by the information stored in the hibernation image in that case. + +The middle-layer code involved in the handling of the device is expected to +indicate to the PM core if the device may be left in suspend by setting its +:c:member:`power.may_skip_resume` status bit which is checked by the PM core +during the "noirq" phase of the preceding system-wide suspend (or analogous) +transition. The middle layer is then responsible for handling the device as +appropriate in its "noirq" resume callback, which is executed regardless of +whether or not the device is left suspended, but the other resume callbacks +(except for ``->complete``) will be skipped automatically by the PM core if the +device really can be left in suspend. + +For devices whose "noirq", "late" and "early" driver callbacks are invoked +directly by the PM core, all of the system-wide resume callbacks are skipped if +``DPM_FLAG_LEAVE_SUSPENDED`` is set and the device is in runtime suspend during +the ``suspend_noirq`` (or analogous) phase or the transition under way is a +proper system suspend (rather than anything related to hibernation) and the +device's wakeup settings are suitable for runtime PM (that is, it cannot +generate wakeup signals at all or it is allowed to wake up the system from +sleep). diff --git a/Documentation/driver-api/scsi.rst b/Documentation/driver-api/scsi.rst index 9ae03171daca..3ae337929721 100644 --- a/Documentation/driver-api/scsi.rst +++ b/Documentation/driver-api/scsi.rst @@ -224,6 +224,14 @@ mid to lowlevel SCSI driver interface .. kernel-doc:: drivers/scsi/hosts.c :export: +drivers/scsi/scsi_common.c +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +general support functions + +.. kernel-doc:: drivers/scsi/scsi_common.c + :export: + Transport classes ----------------- @@ -332,5 +340,5 @@ todo ~~~~ Parallel (fast/wide/ultra) SCSI, USB, SATA, SAS, Fibre Channel, -FireWire, ATAPI devices, Infiniband, I20, iSCSI, Parallel ports, +FireWire, ATAPI devices, Infiniband, I2O, iSCSI, Parallel ports, netlink... diff --git a/Documentation/driver-api/usb/usb3-debug-port.rst b/Documentation/driver-api/usb/usb3-debug-port.rst index feb1a36a65b7..b9fd131f4723 100644 --- a/Documentation/driver-api/usb/usb3-debug-port.rst +++ b/Documentation/driver-api/usb/usb3-debug-port.rst @@ -98,3 +98,55 @@ you to check the sanity of the setup. cat /dev/ttyUSB0 done ===== end of bash scripts =============== + +Serial TTY +========== + +The DbC support has been added to the xHCI driver. You can get a +debug device provided by the DbC at runtime. + +In order to use this, you need to make sure your kernel has been +configured to support USB_XHCI_DBGCAP. A sysfs attribute under +the xHCI device node is used to enable or disable DbC. By default, +DbC is disabled:: + + root@target:/sys/bus/pci/devices/0000:00:14.0# cat dbc + disabled + +Enable DbC with the following command:: + + root@target:/sys/bus/pci/devices/0000:00:14.0# echo enable > dbc + +You can check the DbC state at anytime:: + + root@target:/sys/bus/pci/devices/0000:00:14.0# cat dbc + enabled + +Connect the debug target to the debug host with a USB 3.0 super- +speed A-to-A debugging cable. You can see /dev/ttyDBC0 created +on the debug target. You will see below kernel message lines:: + + root@target: tail -f /var/log/kern.log + [ 182.730103] xhci_hcd 0000:00:14.0: DbC connected + [ 191.169420] xhci_hcd 0000:00:14.0: DbC configured + [ 191.169597] xhci_hcd 0000:00:14.0: DbC now attached to /dev/ttyDBC0 + +Accordingly, the DbC state has been brought up to:: + + root@target:/sys/bus/pci/devices/0000:00:14.0# cat dbc + configured + +On the debug host, you will see the debug device has been enumerated. +You will see below kernel message lines:: + + root@host: tail -f /var/log/kern.log + [ 79.454780] usb 2-2.1: new SuperSpeed USB device number 3 using xhci_hcd + [ 79.475003] usb 2-2.1: LPM exit latency is zeroed, disabling LPM. + [ 79.475389] usb 2-2.1: New USB device found, idVendor=1d6b, idProduct=0010 + [ 79.475390] usb 2-2.1: New USB device strings: Mfr=1, Product=2, SerialNumber=3 + [ 79.475391] usb 2-2.1: Product: Linux USB Debug Target + [ 79.475392] usb 2-2.1: Manufacturer: Linux Foundation + [ 79.475393] usb 2-2.1: SerialNumber: 0001 + +The debug device works now. You can use any communication or debugging +program to talk between the host and the target. diff --git a/Documentation/driver-api/usb/writing_usb_driver.rst b/Documentation/driver-api/usb/writing_usb_driver.rst index 69f077dcdb78..4fe1c06b6a13 100644 --- a/Documentation/driver-api/usb/writing_usb_driver.rst +++ b/Documentation/driver-api/usb/writing_usb_driver.rst @@ -321,6 +321,6 @@ linux-usb-devel Mailing List Archives: http://marc.theaimsgroup.com/?l=linux-usb-devel Programming Guide for Linux USB Device Drivers: -http://usb.cs.tum.edu/usbdoc +http://lmu.web.psi.ch/docu/manuals/software_manuals/linux_sl/usb_linux_programming_guide.pdf USB Home Page: http://www.usb.org |