diff options
Diffstat (limited to 'Documentation')
584 files changed, 20576 insertions, 4082 deletions
diff --git a/Documentation/00-INDEX b/Documentation/00-INDEX index 1750fcef1ab4..cd077ca0e1b8 100644 --- a/Documentation/00-INDEX +++ b/Documentation/00-INDEX @@ -29,8 +29,6 @@ DMA-ISA-LPC.txt - How to do DMA with ISA (and LPC) devices. DMA-attributes.txt - listing of the various possible attributes a DMA region can have -dmatest.txt - - how to compile, configure and use the dmatest system. DocBook/ - directory with DocBook templates etc. for kernel documentation. EDID/ @@ -163,8 +161,6 @@ digsig.txt -info on the Digital Signature Verification API dma-buf-sharing.txt - the DMA Buffer Sharing API Guide -dmaengine.txt - -the DMA Engine API Guide dontdiff - file containing a list of files that should never be diff'ed. driver-model/ @@ -209,6 +205,8 @@ hid/ - directory with information on human interface devices highuid.txt - notes on the change from 16 bit to 32 bit user/group IDs. +hsi.txt + - HSI subsystem overview. hwspinlock.txt - hardware spinlock provides hardware assistance for synchronization timers/ @@ -277,6 +275,8 @@ kprobes.txt - documents the kernel probes debugging feature. kref.txt - docs on adding reference counters (krefs) to kernel objects. +kselftest.txt + - small unittests for (some) individual codepaths in the kernel. laptops/ - directory with laptop related info and laptop driver documentation. ldm.txt @@ -285,22 +285,22 @@ leds/ - directory with info about LED handling under Linux. local_ops.txt - semantics and behavior of local atomic operations. -lockdep-design.txt - - documentation on the runtime locking correctness validator. locking/ - directory with info about kernel locking primitives -lockstat.txt - - info on collecting statistics on locks (and contention). lockup-watchdogs.txt - info on soft and hard lockup detectors (aka nmi_watchdog). logo.gif - full colour GIF image of Linux logo (penguin - Tux). logo.txt - info on creator of above logo & site to get additional images from. +lzo.txt + - kernel LZO decompressor input formats m68k/ - directory with info about Linux on Motorola 68k architecture. magic-number.txt - list of magic numbers used to mark/protect kernel data structures. +mailbox.txt + - How to write drivers for the common mailbox framework (IPC). md.txt - info on boot arguments for the multiple devices driver. media-framework.txt @@ -327,8 +327,6 @@ mtd/ - directory with info about memory technology devices (flash) mono.txt - how to execute Mono-based .NET binaries with the help of BINFMT_MISC. -mutex-design.txt - - info on the generic mutex subsystem. namespaces/ - directory with various information about namespaces netlabel/ @@ -395,10 +393,6 @@ robust-futexes.txt - a description of what robust futexes are. rpmsg.txt - info on the Remote Processor Messaging (rpmsg) Framework -rt-mutex-design.txt - - description of the RealTime mutex implementation design. -rt-mutex.txt - - desc. of RT-mutex subsystem with PI (Priority Inheritance) support. rtc.txt - notes on how to use the Real Time Clock (aka CMOS clock) driver. s390/ @@ -425,8 +419,6 @@ sparse.txt - info on how to obtain and use the sparse tool for typechecking. spi/ - overview of Linux kernel Serial Peripheral Interface (SPI) support. -spinlocks.txt - - info on using spinlocks to provide exclusive access in kernel. stable_api_nonsense.txt - info on why the kernel does not have a stable in-kernel api or abi. stable_kernel_rules.txt @@ -483,10 +475,10 @@ wimax/ - directory with info about Intel Wireless Wimax Connections workqueue.txt - information on the Concurrency Managed Workqueue implementation -ww-mutex-design.txt - - Intro to Mutex wait/would deadlock handling.s x86/x86_64/ - directory with info on Linux support for AMD x86-64 (Hammer) machines. +xillybus.txt + - Overview and basic ui of xillybus driver xtensa/ - directory with documents relating to arch/xtensa port/implementation xz.txt diff --git a/Documentation/ABI/stable/sysfs-bus-usb b/Documentation/ABI/stable/sysfs-bus-usb index e2bc700a6f9c..831f15d9672f 100644 --- a/Documentation/ABI/stable/sysfs-bus-usb +++ b/Documentation/ABI/stable/sysfs-bus-usb @@ -32,10 +32,9 @@ Date: January 2008 KernelVersion: 2.6.25 Contact: Sarah Sharp <sarah.a.sharp@intel.com> Description: - If CONFIG_PM_RUNTIME is enabled then this file - is present. When read, it returns the total time (in msec) - that the USB device has been connected to the machine. This - file is read-only. + If CONFIG_PM is enabled, then this file is present. When read, + it returns the total time (in msec) that the USB device has been + connected to the machine. This file is read-only. Users: PowerTOP <powertop@lists.01.org> https://01.org/powertop/ @@ -45,10 +44,9 @@ Date: January 2008 KernelVersion: 2.6.25 Contact: Sarah Sharp <sarah.a.sharp@intel.com> Description: - If CONFIG_PM_RUNTIME is enabled then this file - is present. When read, it returns the total time (in msec) - that the USB device has been active, i.e. not in a suspended - state. This file is read-only. + If CONFIG_PM is enabled, then this file is present. When read, + it returns the total time (in msec) that the USB device has been + active, i.e. not in a suspended state. This file is read-only. Tools can use this file and the connected_duration file to compute the percentage of time that a device has been active. diff --git a/Documentation/ABI/stable/sysfs-class-tpm b/Documentation/ABI/stable/sysfs-class-tpm index a60b45e2493b..9f790eebb5d2 100644 --- a/Documentation/ABI/stable/sysfs-class-tpm +++ b/Documentation/ABI/stable/sysfs-class-tpm @@ -1,4 +1,4 @@ -What: /sys/class/misc/tpmX/device/ +What: /sys/class/tpm/tpmX/device/ Date: April 2005 KernelVersion: 2.6.12 Contact: tpmdd-devel@lists.sf.net @@ -6,7 +6,7 @@ Description: The device/ directory under a specific TPM instance exposes the properties of that TPM chip -What: /sys/class/misc/tpmX/device/active +What: /sys/class/tpm/tpmX/device/active Date: April 2006 KernelVersion: 2.6.17 Contact: tpmdd-devel@lists.sf.net @@ -18,7 +18,7 @@ Description: The "active" property prints a '1' if the TPM chip is accepting section 17 for more information on which commands are available. -What: /sys/class/misc/tpmX/device/cancel +What: /sys/class/tpm/tpmX/device/cancel Date: June 2005 KernelVersion: 2.6.13 Contact: tpmdd-devel@lists.sf.net @@ -26,7 +26,7 @@ Description: The "cancel" property allows you to cancel the currently pending TPM command. Writing any value to cancel will call the TPM vendor specific cancel operation. -What: /sys/class/misc/tpmX/device/caps +What: /sys/class/tpm/tpmX/device/caps Date: April 2005 KernelVersion: 2.6.12 Contact: tpmdd-devel@lists.sf.net @@ -43,7 +43,7 @@ Description: The "caps" property contains TPM manufacturer and version info. the chip supports. Firmware version is that of the chip and is manufacturer specific. -What: /sys/class/misc/tpmX/device/durations +What: /sys/class/tpm/tpmX/device/durations Date: March 2011 KernelVersion: 3.1 Contact: tpmdd-devel@lists.sf.net @@ -66,7 +66,7 @@ Description: The "durations" property shows the 3 vendor-specific values scaled to be displayed in usecs. In this case "[adjusted]" will be displayed in place of "[original]". -What: /sys/class/misc/tpmX/device/enabled +What: /sys/class/tpm/tpmX/device/enabled Date: April 2006 KernelVersion: 2.6.17 Contact: tpmdd-devel@lists.sf.net @@ -75,7 +75,7 @@ Description: The "enabled" property prints a '1' if the TPM chip is enabled, may be visible but produce a '0' after some operation that disables the TPM. -What: /sys/class/misc/tpmX/device/owned +What: /sys/class/tpm/tpmX/device/owned Date: April 2006 KernelVersion: 2.6.17 Contact: tpmdd-devel@lists.sf.net @@ -83,7 +83,7 @@ Description: The "owned" property produces a '1' if the TPM_TakeOwnership ordinal has been executed successfully in the chip. A '0' indicates that ownership hasn't been taken. -What: /sys/class/misc/tpmX/device/pcrs +What: /sys/class/tpm/tpmX/device/pcrs Date: April 2005 KernelVersion: 2.6.12 Contact: tpmdd-devel@lists.sf.net @@ -106,7 +106,7 @@ Description: The "pcrs" property will dump the current value of all Platform 1.2 chips, PCRs represent SHA-1 hashes, which are 20 bytes long. Use the "caps" property to determine TPM version. -What: /sys/class/misc/tpmX/device/pubek +What: /sys/class/tpm/tpmX/device/pubek Date: April 2005 KernelVersion: 2.6.12 Contact: tpmdd-devel@lists.sf.net @@ -158,7 +158,7 @@ Description: The "pubek" property will return the TPM's public endorsement Modulus Length: 256 (bytes) Modulus: The 256 byte Endorsement Key modulus -What: /sys/class/misc/tpmX/device/temp_deactivated +What: /sys/class/tpm/tpmX/device/temp_deactivated Date: April 2006 KernelVersion: 2.6.17 Contact: tpmdd-devel@lists.sf.net @@ -167,7 +167,7 @@ Description: The "temp_deactivated" property returns a '1' if the chip has cycle. Whether a warm boot (reboot) will clear a TPM chip from a temp_deactivated state is platform specific. -What: /sys/class/misc/tpmX/device/timeouts +What: /sys/class/tpm/tpmX/device/timeouts Date: March 2011 KernelVersion: 3.1 Contact: tpmdd-devel@lists.sf.net diff --git a/Documentation/ABI/stable/sysfs-class-udc b/Documentation/ABI/stable/sysfs-class-udc new file mode 100644 index 000000000000..85d3dac2e204 --- /dev/null +++ b/Documentation/ABI/stable/sysfs-class-udc @@ -0,0 +1,93 @@ +What: /sys/class/udc/<udc>/a_alt_hnp_support +Date: June 2011 +KernelVersion: 3.1 +Contact: Felipe Balbi <balbi@kernel.org> +Description: + Indicates if an OTG A-Host supports HNP at an alternate port. +Users: + +What: /sys/class/udc/<udc>/a_hnp_support +Date: June 2011 +KernelVersion: 3.1 +Contact: Felipe Balbi <balbi@kernel.org> +Description: + Indicates if an OTG A-Host supports HNP at this port. +Users: + +What: /sys/class/udc/<udc>/b_hnp_enable +Date: June 2011 +KernelVersion: 3.1 +Contact: Felipe Balbi <balbi@kernel.org> +Description: + Indicates if an OTG A-Host enabled HNP support. +Users: + +What: /sys/class/udc/<udc>/current_speed +Date: June 2011 +KernelVersion: 3.1 +Contact: Felipe Balbi <balbi@kernel.org> +Description: + Indicates the current negotiated speed at this port. +Users: + +What: /sys/class/udc/<udc>/is_a_peripheral +Date: June 2011 +KernelVersion: 3.1 +Contact: Felipe Balbi <balbi@kernel.org> +Description: + Indicates that this port is the default Host on an OTG session + but HNP was used to switch roles. +Users: + +What: /sys/class/udc/<udc>/is_otg +Date: June 2011 +KernelVersion: 3.1 +Contact: Felipe Balbi <balbi@kernel.org> +Description: + Indicates that this port support OTG. +Users: + +What: /sys/class/udc/<udc>/maximum_speed +Date: June 2011 +KernelVersion: 3.1 +Contact: Felipe Balbi <balbi@kernel.org> +Description: + Indicates the maximum USB speed supported by this port. +Users: + +What: /sys/class/udc/<udc>/maximum_speed +Date: June 2011 +KernelVersion: 3.1 +Contact: Felipe Balbi <balbi@kernel.org> +Description: + Indicates the maximum USB speed supported by this port. +Users: + +What: /sys/class/udc/<udc>/soft_connect +Date: June 2011 +KernelVersion: 3.1 +Contact: Felipe Balbi <balbi@kernel.org> +Description: + Allows users to disconnect data pullup resistors thus causing a + logical disconnection from the USB Host. +Users: + +What: /sys/class/udc/<udc>/srp +Date: June 2011 +KernelVersion: 3.1 +Contact: Felipe Balbi <balbi@kernel.org> +Description: + Allows users to manually start Session Request Protocol. +Users: + +What: /sys/class/udc/<udc>/state +Date: June 2011 +KernelVersion: 3.1 +Contact: Felipe Balbi <balbi@kernel.org> +Description: + Indicates current state of the USB Device Controller. Valid + states are: 'not-attached', 'attached', 'powered', + 'reconnecting', 'unauthenticated', 'default', 'addressed', + 'configured', and 'suspended'; however not all USB Device + Controllers support reporting all states. +Users: diff --git a/Documentation/ABI/stable/sysfs-driver-ib_srp b/Documentation/ABI/stable/sysfs-driver-ib_srp index b9688de8455b..7049a2b50359 100644 --- a/Documentation/ABI/stable/sysfs-driver-ib_srp +++ b/Documentation/ABI/stable/sysfs-driver-ib_srp @@ -55,12 +55,12 @@ Description: Interface for making ib_srp connect to a new target. only safe with partial memory descriptor list support enabled (allow_ext_sg=1). * comp_vector, a number in the range 0..n-1 specifying the - MSI-X completion vector. Some HCA's allocate multiple (n) - MSI-X vectors per HCA port. If the IRQ affinity masks of - these interrupts have been configured such that each MSI-X - interrupt is handled by a different CPU then the comp_vector - parameter can be used to spread the SRP completion workload - over multiple CPU's. + MSI-X completion vector of the first RDMA channel. Some + HCA's allocate multiple (n) MSI-X vectors per HCA port. If + the IRQ affinity masks of these interrupts have been + configured such that each MSI-X interrupt is handled by a + different CPU then the comp_vector parameter can be used to + spread the SRP completion workload over multiple CPU's. * tl_retry_count, a number in the range 2..7 specifying the IB RC retry count. * queue_size, the maximum number of commands that the @@ -88,6 +88,13 @@ Description: Whether ib_srp is allowed to include a partial memory descriptor list in an SRP_CMD when communicating with an SRP target. +What: /sys/class/scsi_host/host<n>/ch_count +Date: April 1, 2015 +KernelVersion: 3.19 +Contact: linux-rdma@vger.kernel.org +Description: Number of RDMA channels used for communication with the SRP + target. + What: /sys/class/scsi_host/host<n>/cmd_sg_entries Date: May 19, 2011 KernelVersion: 2.6.39 @@ -95,6 +102,12 @@ Contact: linux-rdma@vger.kernel.org Description: Maximum number of data buffer descriptors that may be sent to the target in a single SRP_CMD request. +What: /sys/class/scsi_host/host<n>/comp_vector +Date: September 2, 2013 +KernelVersion: 3.11 +Contact: linux-rdma@vger.kernel.org +Description: Completion vector used for the first RDMA channel. + What: /sys/class/scsi_host/host<n>/dgid Date: June 17, 2006 KernelVersion: 2.6.17 diff --git a/Documentation/ABI/testing/configfs-usb-gadget-hid b/Documentation/ABI/testing/configfs-usb-gadget-hid new file mode 100644 index 000000000000..f12e00e6baa3 --- /dev/null +++ b/Documentation/ABI/testing/configfs-usb-gadget-hid @@ -0,0 +1,11 @@ +What: /config/usb-gadget/gadget/functions/hid.name +Date: Nov 2014 +KernelVersion: 3.19 +Description: + The attributes: + + protocol - HID protocol to use + report_desc - blob corresponding to HID report descriptors + except the data passed through /dev/hidg<N> + report_length - HID report length + subclass - HID device subclass to use diff --git a/Documentation/ABI/testing/configfs-usb-gadget-midi b/Documentation/ABI/testing/configfs-usb-gadget-midi new file mode 100644 index 000000000000..6b341df7249c --- /dev/null +++ b/Documentation/ABI/testing/configfs-usb-gadget-midi @@ -0,0 +1,12 @@ +What: /config/usb-gadget/gadget/functions/midi.name +Date: Nov 2014 +KernelVersion: 3.19 +Description: + The attributes: + + index - index value for the USB MIDI adapter + id - ID string for the USB MIDI adapter + buflen - MIDI buffer length + qlen - USB read request queue length + in_ports - number of MIDI input ports + out_ports - number of MIDI output ports diff --git a/Documentation/ABI/testing/configfs-usb-gadget-uvc b/Documentation/ABI/testing/configfs-usb-gadget-uvc new file mode 100644 index 000000000000..2f4a0051b32d --- /dev/null +++ b/Documentation/ABI/testing/configfs-usb-gadget-uvc @@ -0,0 +1,265 @@ +What: /config/usb-gadget/gadget/functions/uvc.name +Date: Dec 2014 +KernelVersion: 3.20 +Description: UVC function directory + + streaming_maxburst - 0..15 (ss only) + streaming_maxpacket - 1..1023 (fs), 1..3072 (hs/ss) + streaming_interval - 1..16 + +What: /config/usb-gadget/gadget/functions/uvc.name/control +Date: Dec 2014 +KernelVersion: 3.20 +Description: Control descriptors + +What: /config/usb-gadget/gadget/functions/uvc.name/control/class +Date: Dec 2014 +KernelVersion: 3.20 +Description: Class descriptors + +What: /config/usb-gadget/gadget/functions/uvc.name/control/class/ss +Date: Dec 2014 +KernelVersion: 3.20 +Description: Super speed control class descriptors + +What: /config/usb-gadget/gadget/functions/uvc.name/control/class/fs +Date: Dec 2014 +KernelVersion: 3.20 +Description: Full speed control class descriptors + +What: /config/usb-gadget/gadget/functions/uvc.name/control/terminal +Date: Dec 2014 +KernelVersion: 3.20 +Description: Terminal descriptors + +What: /config/usb-gadget/gadget/functions/uvc.name/control/terminal/output +Date: Dec 2014 +KernelVersion: 3.20 +Description: Output terminal descriptors + +What: /config/usb-gadget/gadget/functions/uvc.name/control/terminal/output/default +Date: Dec 2014 +KernelVersion: 3.20 +Description: Default output terminal descriptors + + All attributes read only: + iTerminal - index of string descriptor + bSourceID - id of the terminal to which this terminal + is connected + bAssocTerminal - id of the input terminal to which this output + terminal is associated + wTerminalType - terminal type + bTerminalID - a non-zero id of this terminal + +What: /config/usb-gadget/gadget/functions/uvc.name/control/terminal/camera +Date: Dec 2014 +KernelVersion: 3.20 +Description: Camera terminal descriptors + +What: /config/usb-gadget/gadget/functions/uvc.name/control/terminal/camera/default +Date: Dec 2014 +KernelVersion: 3.20 +Description: Default camera terminal descriptors + + All attributes read only: + bmControls - bitmap specifying which controls are + supported for the video stream + wOcularFocalLength - the value of Locular + wObjectiveFocalLengthMax- the value of Lmin + wObjectiveFocalLengthMin- the value of Lmax + iTerminal - index of string descriptor + bAssocTerminal - id of the output terminal to which + this terminal is connected + wTerminalType - terminal type + bTerminalID - a non-zero id of this terminal + +What: /config/usb-gadget/gadget/functions/uvc.name/control/processing +Date: Dec 2014 +KernelVersion: 3.20 +Description: Processing unit descriptors + +What: /config/usb-gadget/gadget/functions/uvc.name/control/processing/default +Date: Dec 2014 +KernelVersion: 3.20 +Description: Default processing unit descriptors + + All attributes read only: + iProcessing - index of string descriptor + bmControls - bitmap specifying which controls are + supported for the video stream + wMaxMultiplier - maximum digital magnification x100 + bSourceID - id of the terminal to which this unit is + connected + bUnitID - a non-zero id of this unit + +What: /config/usb-gadget/gadget/functions/uvc.name/control/header +Date: Dec 2014 +KernelVersion: 3.20 +Description: Control header descriptors + +What: /config/usb-gadget/gadget/functions/uvc.name/control/header/name +Date: Dec 2014 +KernelVersion: 3.20 +Description: Specific control header descriptors + +dwClockFrequency +bcdUVC +What: /config/usb-gadget/gadget/functions/uvc.name/streaming +Date: Dec 2014 +KernelVersion: 3.20 +Description: Streaming descriptors + +What: /config/usb-gadget/gadget/functions/uvc.name/streaming/class +Date: Dec 2014 +KernelVersion: 3.20 +Description: Streaming class descriptors + +What: /config/usb-gadget/gadget/functions/uvc.name/streaming/class/ss +Date: Dec 2014 +KernelVersion: 3.20 +Description: Super speed streaming class descriptors + +What: /config/usb-gadget/gadget/functions/uvc.name/streaming/class/hs +Date: Dec 2014 +KernelVersion: 3.20 +Description: High speed streaming class descriptors + +What: /config/usb-gadget/gadget/functions/uvc.name/streaming/class/fs +Date: Dec 2014 +KernelVersion: 3.20 +Description: Full speed streaming class descriptors + +What: /config/usb-gadget/gadget/functions/uvc.name/streaming/color_matching +Date: Dec 2014 +KernelVersion: 3.20 +Description: Color matching descriptors + +What: /config/usb-gadget/gadget/functions/uvc.name/streaming/color_matching/default +Date: Dec 2014 +KernelVersion: 3.20 +Description: Default color matching descriptors + + All attributes read only: + bMatrixCoefficients - matrix used to compute luma and + chroma values from the color primaries + bTransferCharacteristics- optoelectronic transfer + characteristic of the source picutre, + also called the gamma function + bColorPrimaries - color primaries and the reference + white + +What: /config/usb-gadget/gadget/functions/uvc.name/streaming/mjpeg +Date: Dec 2014 +KernelVersion: 3.20 +Description: MJPEG format descriptors + +What: /config/usb-gadget/gadget/functions/uvc.name/streaming/mjpeg/name +Date: Dec 2014 +KernelVersion: 3.20 +Description: Specific MJPEG format descriptors + + All attributes read only, + except bmaControls and bDefaultFrameIndex: + bmaControls - this format's data for bmaControls in + the streaming header + bmInterfaceFlags - specifies interlace information, + read-only + bAspectRatioY - the X dimension of the picture aspect + ratio, read-only + bAspectRatioX - the Y dimension of the picture aspect + ratio, read-only + bmFlags - characteristics of this format, + read-only + bDefaultFrameIndex - optimum frame index for this stream + +What: /config/usb-gadget/gadget/functions/uvc.name/streaming/mjpeg/name/name +Date: Dec 2014 +KernelVersion: 3.20 +Description: Specific MJPEG frame descriptors + + dwFrameInterval - indicates how frame interval can be + programmed; a number of values + separated by newline can be specified + dwDefaultFrameInterval - the frame interval the device would + like to use as default + dwMaxVideoFrameBufferSize- the maximum number of bytes the + compressor will produce for a video + frame or still image + dwMaxBitRate - the maximum bit rate at the shortest + frame interval in bps + dwMinBitRate - the minimum bit rate at the longest + frame interval in bps + wHeight - height of decoded bitmap frame in px + wWidth - width of decoded bitmam frame in px + bmCapabilities - still image support, fixed frame-rate + support + +What: /config/usb-gadget/gadget/functions/uvc.name/streaming/uncompressed +Date: Dec 2014 +KernelVersion: 3.20 +Description: Uncompressed format descriptors + +What: /config/usb-gadget/gadget/functions/uvc.name/streaming/uncompressed/name +Date: Dec 2014 +KernelVersion: 3.20 +Description: Specific uncompressed format descriptors + + bmaControls - this format's data for bmaControls in + the streaming header + bmInterfaceFlags - specifies interlace information, + read-only + bAspectRatioY - the X dimension of the picture aspect + ratio, read-only + bAspectRatioX - the Y dimension of the picture aspect + ratio, read-only + bDefaultFrameIndex - optimum frame index for this stream + bBitsPerPixel - number of bits per pixel used to + specify color in the decoded video + frame + guidFormat - globally unique id used to identify + stream-encoding format + +What: /config/usb-gadget/gadget/functions/uvc.name/streaming/uncompressed/name/name +Date: Dec 2014 +KernelVersion: 3.20 +Description: Specific uncompressed frame descriptors + + dwFrameInterval - indicates how frame interval can be + programmed; a number of values + separated by newline can be specified + dwDefaultFrameInterval - the frame interval the device would + like to use as default + dwMaxVideoFrameBufferSize- the maximum number of bytes the + compressor will produce for a video + frame or still image + dwMaxBitRate - the maximum bit rate at the shortest + frame interval in bps + dwMinBitRate - the minimum bit rate at the longest + frame interval in bps + wHeight - height of decoded bitmap frame in px + wWidth - width of decoded bitmam frame in px + bmCapabilities - still image support, fixed frame-rate + support + +What: /config/usb-gadget/gadget/functions/uvc.name/streaming/header +Date: Dec 2014 +KernelVersion: 3.20 +Description: Streaming header descriptors + +What: /config/usb-gadget/gadget/functions/uvc.name/streaming/header/name +Date: Dec 2014 +KernelVersion: 3.20 +Description: Specific streaming header descriptors + + All attributes read only: + bTriggerUsage - how the host software will respond to + a hardware trigger interrupt event + bTriggerSupport - flag specifying if hardware + triggering is supported + bStillCaptureMethod - method of still image caputre + supported + bTerminalLink - id of the output terminal to which + the video endpoint of this interface + is connected + bmInfo - capabilities of this video streaming + interface diff --git a/Documentation/ABI/testing/sysfs-bus-amba b/Documentation/ABI/testing/sysfs-bus-amba new file mode 100644 index 000000000000..e7b54677cfbe --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-amba @@ -0,0 +1,20 @@ +What: /sys/bus/amba/devices/.../driver_override +Date: September 2014 +Contact: Antonios Motakis <a.motakis@virtualopensystems.com> +Description: + This file allows the driver for a device to be specified which + will override standard OF, ACPI, ID table, and name matching. + When specified, only a driver with a name matching the value + written to driver_override will have an opportunity to bind to + the device. The override is specified by writing a string to the + driver_override file (echo vfio-amba > driver_override) and may + be cleared with an empty string (echo > driver_override). + This returns the device to standard matching rules binding. + Writing to driver_override does not automatically unbind the + device from its current driver or make any attempt to + automatically load the specified driver. If no driver with a + matching name is currently loaded in the kernel, the device will + not bind to any driver. This also allows devices to opt-out of + driver binding using a driver_override name such as "none". + Only a single driver may be specified in the override, there is + no support for parsing delimiters. diff --git a/Documentation/ABI/testing/sysfs-bus-coresight-devices-etb10 b/Documentation/ABI/testing/sysfs-bus-coresight-devices-etb10 new file mode 100644 index 000000000000..4b8d6ec92e2b --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-coresight-devices-etb10 @@ -0,0 +1,24 @@ +What: /sys/bus/coresight/devices/<memory_map>.etb/enable_sink +Date: November 2014 +KernelVersion: 3.19 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) Add/remove a sink from a trace path. There can be multiple + source for a single sink. + ex: echo 1 > /sys/bus/coresight/devices/20010000.etb/enable_sink + +What: /sys/bus/coresight/devices/<memory_map>.etb/status +Date: November 2014 +KernelVersion: 3.19 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (R) List various control and status registers. The specific + layout and content is driver specific. + +What: /sys/bus/coresight/devices/<memory_map>.etb/trigger_cntr +Date: November 2014 +KernelVersion: 3.19 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) Disables write access to the Trace RAM by stopping the + formatter after a defined number of words have been stored + following the trigger event. The number of 32-bit words written + into the Trace RAM following the trigger event is equal to the + value stored in this register+1 (from ARM ETB-TRM). diff --git a/Documentation/ABI/testing/sysfs-bus-coresight-devices-etm3x b/Documentation/ABI/testing/sysfs-bus-coresight-devices-etm3x new file mode 100644 index 000000000000..b4d0b99afffb --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-coresight-devices-etm3x @@ -0,0 +1,253 @@ +What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/enable_source +Date: November 2014 +KernelVersion: 3.19 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) Enable/disable tracing on this specific trace entiry. + Enabling a source implies the source has been configured + properly and a sink has been identidifed for it. The path + of coresight components linking the source to the sink is + configured and managed automatically by the coresight framework. + +What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/status +Date: November 2014 +KernelVersion: 3.19 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (R) List various control and status registers. The specific + layout and content is driver specific. + +What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/addr_idx +Date: November 2014 +KernelVersion: 3.19 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: Select which address comparator or pair (of comparators) to + work with. + +What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/addr_acctype +Date: November 2014 +KernelVersion: 3.19 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) Used in conjunction with @addr_idx. Specifies + characteristics about the address comparator being configure, + for example the access type, the kind of instruction to trace, + processor contect ID to trigger on, etc. Individual fields in + the access type register may vary on the version of the trace + entity. + +What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/addr_range +Date: November 2014 +KernelVersion: 3.19 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) Used in conjunction with @addr_idx. Specifies the range of + addresses to trigger on. Inclusion or exclusion is specificed + in the corresponding access type register. + +What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/addr_single +Date: November 2014 +KernelVersion: 3.19 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) Used in conjunction with @addr_idx. Specifies the single + address to trigger on, highly influenced by the configuration + options of the corresponding access type register. + +What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/addr_start +Date: November 2014 +KernelVersion: 3.19 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) Used in conjunction with @addr_idx. Specifies the single + address to start tracing on, highly influenced by the + configuration options of the corresponding access type register. + +What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/addr_stop +Date: November 2014 +KernelVersion: 3.19 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) Used in conjunction with @addr_idx. Specifies the single + address to stop tracing on, highly influenced by the + configuration options of the corresponding access type register. + +What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/cntr_idx +Date: November 2014 +KernelVersion: 3.19 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) Specifies the counter to work on. + +What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/cntr_event +Date: November 2014 +KernelVersion: 3.19 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) Used in conjunction with cntr_idx, give access to the + counter event register. + +What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/cntr_val +Date: November 2014 +KernelVersion: 3.19 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) Used in conjunction with cntr_idx, give access to the + counter value register. + +What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/cntr_rld_val +Date: November 2014 +KernelVersion: 3.19 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) Used in conjunction with cntr_idx, give access to the + counter reload value register. + +What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/cntr_rld_event +Date: November 2014 +KernelVersion: 3.19 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) Used in conjunction with cntr_idx, give access to the + counter reload event register. + +What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/ctxid_idx +Date: November 2014 +KernelVersion: 3.19 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) Specifies the index of the context ID register to be + selected. + +What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/ctxid_mask +Date: November 2014 +KernelVersion: 3.19 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) Mask to apply to all the context ID comparator. + +What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/ctxid_val +Date: November 2014 +KernelVersion: 3.19 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) Used with the ctxid_idx, specify with context ID to trigger + on. + +What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/enable_event +Date: November 2014 +KernelVersion: 3.19 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) Defines which event triggers a trace. + +What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/etmsr +Date: November 2014 +KernelVersion: 3.19 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) Gives access to the ETM status register, which holds + programming information and status on certains events. + +What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/fifofull_level +Date: November 2014 +KernelVersion: 3.19 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) Number of byte left in the fifo before considering it full. + Depending on the tracer's version, can also hold threshold for + data suppression. + +What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/mode +Date: November 2014 +KernelVersion: 3.19 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) Interface with the driver's 'mode' field, controlling + various aspect of the trace entity such as time stamping, + context ID size and cycle accurate tracing. Driver specific + and bound to change depending on the driver. + +What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/nr_addr_cmp +Date: November 2014 +KernelVersion: 3.19 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (R) Provides the number of address comparators pairs accessible + on a trace unit, as specified by bit 3:0 of register ETMCCR. + +What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/nr_cntr +Date: November 2014 +KernelVersion: 3.19 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (R) Provides the number of counters accessible on a trace unit, + as specified by bit 15:13 of register ETMCCR. + +What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/nr_ctxid_cmp +Date: November 2014 +KernelVersion: 3.19 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (R) Provides the number of context ID comparator available on a + trace unit, as specified by bit 25:24 of register ETMCCR. + +What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/reset +Date: November 2014 +KernelVersion: 3.19 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (W) Cancels all configuration on a trace unit and set it back + to its boot configuration. + +What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/seq_12_event +Date: November 2014 +KernelVersion: 3.19 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) Defines the event that causes the sequencer to transition + from state 1 to state 2. + +What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/seq_13_event +Date: November 2014 +KernelVersion: 3.19 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) Defines the event that causes the sequencer to transition + from state 1 to state 3. + +What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/seq_21_event +Date: November 2014 +KernelVersion: 3.19 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) Defines the event that causes the sequencer to transition + from state 2 to state 1. + +What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/seq_23_event +Date: November 2014 +KernelVersion: 3.19 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) Defines the event that causes the sequencer to transition + from state 2 to state 3. + +What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/seq_31_event +Date: November 2014 +KernelVersion: 3.19 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) Defines the event that causes the sequencer to transition + from state 3 to state 1. + +What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/seq_32_event +Date: November 2014 +KernelVersion: 3.19 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) Defines the event that causes the sequencer to transition + from state 3 to state 2. + +What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/curr_seq_state +Date: November 2014 +KernelVersion: 3.19 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (R) Holds the current state of the sequencer. + +What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/sync_freq +Date: November 2014 +KernelVersion: 3.19 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) Holds the trace synchronization frequency value - must be + programmed with the various implementation behavior in mind. + +What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/timestamp_event +Date: November 2014 +KernelVersion: 3.19 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) Defines an event that requests the insertion of a timestamp + into the trace stream. + +What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/traceid +Date: November 2014 +KernelVersion: 3.19 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) Holds the trace ID that will appear in the trace stream + coming from this trace entity. + +What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/trigger_event +Date: November 2014 +KernelVersion: 3.19 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) Define the event that controls the trigger. diff --git a/Documentation/ABI/testing/sysfs-bus-coresight-devices-funnel b/Documentation/ABI/testing/sysfs-bus-coresight-devices-funnel new file mode 100644 index 000000000000..d75acda5e1b3 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-coresight-devices-funnel @@ -0,0 +1,12 @@ +What: /sys/bus/coresight/devices/<memory_map>.funnel/funnel_ctrl +Date: November 2014 +KernelVersion: 3.19 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) Enables the slave ports and defines the hold time of the + slave ports. + +What: /sys/bus/coresight/devices/<memory_map>.funnel/priority +Date: November 2014 +KernelVersion: 3.19 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) Defines input port priority order. diff --git a/Documentation/ABI/testing/sysfs-bus-coresight-devices-tmc b/Documentation/ABI/testing/sysfs-bus-coresight-devices-tmc new file mode 100644 index 000000000000..f38cded5fa22 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-coresight-devices-tmc @@ -0,0 +1,8 @@ +What: /sys/bus/coresight/devices/<memory_map>.tmc/trigger_cntr +Date: November 2014 +KernelVersion: 3.19 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) Disables write access to the Trace RAM by stopping the + formatter after a defined number of words have been stored + following the trigger event. Additional interface for this + driver are expected to be added as it matures. diff --git a/Documentation/ABI/testing/sysfs-bus-event_source-devices-events b/Documentation/ABI/testing/sysfs-bus-event_source-devices-events index 20979f8b3edb..505f080d20a1 100644 --- a/Documentation/ABI/testing/sysfs-bus-event_source-devices-events +++ b/Documentation/ABI/testing/sysfs-bus-event_source-devices-events @@ -52,12 +52,18 @@ Description: Per-pmu performance monitoring events specific to the running syste event=0x2abc event=0x423,inv,cmask=0x3 domain=0x1,offset=0x8,starting_index=0xffff + domain=0x1,offset=0x8,core=? Each of the assignments indicates a value to be assigned to a particular set of bits (as defined by the format file corresponding to the <term>) in the perf_event structure passed to the perf_open syscall. + In the case of the last example, a value replacing "?" would + need to be provided by the user selecting the particular event. + This is referred to as "event parameterization". Event + parameters have the format 'param=?'. + What: /sys/bus/event_source/devices/<pmu>/events/<event>.unit Date: 2014/02/24 Contact: Linux kernel mailing list <linux-kernel@vger.kernel.org> diff --git a/Documentation/ABI/testing/sysfs-bus-event_source-devices-hv_24x7 b/Documentation/ABI/testing/sysfs-bus-event_source-devices-hv_24x7 index 32f3f5f8bba2..f893337570c1 100644 --- a/Documentation/ABI/testing/sysfs-bus-event_source-devices-hv_24x7 +++ b/Documentation/ABI/testing/sysfs-bus-event_source-devices-hv_24x7 @@ -21,3 +21,25 @@ Contact: Linux on PowerPC Developer List <linuxppc-dev@lists.ozlabs.org> Description: Exposes the "version" field of the 24x7 catalog. This is also extractable from the provided binary "catalog" sysfs entry. + +What: /sys/bus/event_source/devices/hv_24x7/event_descs/<event-name> +Date: February 2014 +Contact: Linux on PowerPC Developer List <linuxppc-dev@lists.ozlabs.org> +Description: + Provides the description of a particular event as provided by + the firmware. If firmware does not provide a description, no + file will be created. + + Note that the event-name lacks the domain suffix appended for + events in the events/ dir. + +What: /sys/bus/event_source/devices/hv_24x7/event_long_descs/<event-name> +Date: February 2014 +Contact: Linux on PowerPC Developer List <linuxppc-dev@lists.ozlabs.org> +Description: + Provides the "long" description of a particular event as + provided by the firmware. If firmware does not provide a + description, no file will be created. + + Note that the event-name lacks the domain suffix appended for + events in the events/ dir. diff --git a/Documentation/ABI/testing/sysfs-bus-iio b/Documentation/ABI/testing/sysfs-bus-iio index d760b0224ef7..9a70c31619ea 100644 --- a/Documentation/ABI/testing/sysfs-bus-iio +++ b/Documentation/ABI/testing/sysfs-bus-iio @@ -92,6 +92,18 @@ Description: is required is a consistent labeling. Units after application of scale and offset are millivolts. +What: /sys/bus/iio/devices/iio:deviceX/in_currentY_raw +What: /sys/bus/iio/devices/iio:deviceX/in_currentY_supply_raw +KernelVersion: 3.17 +Contact: linux-iio@vger.kernel.org +Description: + Raw (unscaled no bias removal etc.) current measurement from + channel Y. In special cases where the channel does not + correspond to externally available input one of the named + versions may be used. The number must always be specified and + unique to allow association with event codes. Units after + application of scale and offset are milliamps. + What: /sys/bus/iio/devices/iio:deviceX/in_capacitanceY_raw KernelVersion: 3.2 Contact: linux-iio@vger.kernel.org @@ -200,6 +212,13 @@ Description: Raw pressure measurement from channel Y. Units after application of scale and offset are kilopascal. +What: /sys/bus/iio/devices/iio:deviceX/in_pressureY_input +What: /sys/bus/iio/devices/iio:deviceX/in_pressure_input +KernelVersion: 3.8 +Contact: linux-iio@vger.kernel.org +Description: + Scaled pressure measurement from channel Y, in kilopascal. + What: /sys/bus/iio/devices/iio:deviceX/in_humidityrelative_raw KernelVersion: 3.14 Contact: linux-iio@vger.kernel.org @@ -227,10 +246,13 @@ What: /sys/bus/iio/devices/iio:deviceX/in_accel_y_offset What: /sys/bus/iio/devices/iio:deviceX/in_accel_z_offset What: /sys/bus/iio/devices/iio:deviceX/in_voltageY_offset What: /sys/bus/iio/devices/iio:deviceX/in_voltage_offset +What: /sys/bus/iio/devices/iio:deviceX/in_currentY_offset +What: /sys/bus/iio/devices/iio:deviceX/in_current_offset What: /sys/bus/iio/devices/iio:deviceX/in_tempY_offset What: /sys/bus/iio/devices/iio:deviceX/in_temp_offset What: /sys/bus/iio/devices/iio:deviceX/in_pressureY_offset What: /sys/bus/iio/devices/iio:deviceX/in_pressure_offset +What: /sys/bus/iio/devices/iio:deviceX/in_humidityrelative_offset KernelVersion: 2.6.35 Contact: linux-iio@vger.kernel.org Description: @@ -251,11 +273,17 @@ Description: What: /sys/bus/iio/devices/iio:deviceX/in_voltageY_scale What: /sys/bus/iio/devices/iio:deviceX/in_voltageY_supply_scale What: /sys/bus/iio/devices/iio:deviceX/in_voltage_scale +What: /sys/bus/iio/devices/iio:deviceX/in_voltage-voltage_scale What: /sys/bus/iio/devices/iio:deviceX/out_voltageY_scale What: /sys/bus/iio/devices/iio:deviceX/out_altvoltageY_scale +What: /sys/bus/iio/devices/iio:deviceX/in_currentY_scale +What: /sys/bus/iio/devices/iio:deviceX/in_currentY_supply_scale +What: /sys/bus/iio/devices/iio:deviceX/in_current_scale What: /sys/bus/iio/devices/iio:deviceX/in_accel_scale What: /sys/bus/iio/devices/iio:deviceX/in_accel_peak_scale What: /sys/bus/iio/devices/iio:deviceX/in_anglvel_scale +What: /sys/bus/iio/devices/iio:deviceX/in_energy_scale +What: /sys/bus/iio/devices/iio:deviceX/in_distance_scale What: /sys/bus/iio/devices/iio:deviceX/in_magn_scale What: /sys/bus/iio/devices/iio:deviceX/in_magn_x_scale What: /sys/bus/iio/devices/iio:deviceX/in_magn_y_scale @@ -266,6 +294,8 @@ What: /sys/bus/iio/devices/iio:deviceX/in_rot_from_north_magnetic_tilt_comp_sca What: /sys/bus/iio/devices/iio:deviceX/in_rot_from_north_true_tilt_comp_scale What: /sys/bus/iio/devices/iio:deviceX/in_pressureY_scale What: /sys/bus/iio/devices/iio:deviceX/in_pressure_scale +What: /sys/bus/iio/devices/iio:deviceX/in_humidityrelative_scale +What: /sys/bus/iio/devices/iio:deviceX/in_velocity_sqrt(x^2+y^2+z^2)_scale KernelVersion: 2.6.35 Contact: linux-iio@vger.kernel.org Description: @@ -313,6 +343,44 @@ Description: production inaccuracies). If shared across all channels, <type>_calibscale is used. +What: /sys/bus/iio/devices/iio:deviceX/in_activity_calibgender +What: /sys/bus/iio/devices/iio:deviceX/in_energy_calibgender +What: /sys/bus/iio/devices/iio:deviceX/in_distance_calibgender +What: /sys/bus/iio/devices/iio:deviceX/in_velocity_calibgender +KernelVersion: 3.20 +Contact: linux-iio@vger.kernel.org +Description: + Gender of the user (e.g.: male, female) used by some pedometers + to compute the stride length, distance, speed and activity + type. + +What: /sys/bus/iio/devices/iio:deviceX/in_activity_calibgender_available +What: /sys/bus/iio/devices/iio:deviceX/in_energy_calibgender_available +What: /sys/bus/iio/devices/iio:deviceX/in_distance_calibgender_available +What: /sys/bus/iio/devices/iio:deviceX/in_velocity_calibgender_available +KernelVersion: 3.20 +Contact: linux-iio@vger.kernel.org +Description: + Lists all available gender values (e.g.: male, female). + +What: /sys/bus/iio/devices/iio:deviceX/in_activity_calibheight +What: /sys/bus/iio/devices/iio:deviceX/in_energy_calibheight +What: /sys/bus/iio/devices/iio:deviceX/in_distance_calibheight +What: /sys/bus/iio/devices/iio:deviceX/in_velocity_calibheight +KernelVersion: 3.19 +Contact: linux-iio@vger.kernel.org +Description: + Height of the user (in meters) used by some pedometers + to compute the stride length, distance, speed and activity + type. + +What: /sys/bus/iio/devices/iio:deviceX/in_energy_calibweight +KernelVersion: 3.20 +Contact: linux-iio@vger.kernel.org +Description: + Weight of the user (in kg). It is needed by some pedometers + to compute the calories burnt by the user. + What: /sys/bus/iio/devices/iio:deviceX/in_accel_scale_available What: /sys/.../iio:deviceX/in_voltageX_scale_available What: /sys/.../iio:deviceX/in_voltage-voltage_scale_available @@ -328,6 +396,10 @@ Description: are listed in this attribute. What /sys/bus/iio/devices/iio:deviceX/out_voltageY_hardwaregain +What: /sys/bus/iio/devices/iio:deviceX/in_intensity_red_hardwaregain +What: /sys/bus/iio/devices/iio:deviceX/in_intensity_green_hardwaregain +What: /sys/bus/iio/devices/iio:deviceX/in_intensity_blue_hardwaregain +What: /sys/bus/iio/devices/iio:deviceX/in_intensity_clear_hardwaregain KernelVersion: 2.6.35 Contact: linux-iio@vger.kernel.org Description: @@ -769,6 +841,14 @@ What: /sys/.../events/in_tempY_roc_falling_period What: /sys/.../events/in_accel_x&y&z_mag_falling_period What: /sys/.../events/in_intensity0_thresh_period What: /sys/.../events/in_proximity0_thresh_period +What: /sys/.../events/in_activity_still_thresh_rising_period +What: /sys/.../events/in_activity_still_thresh_falling_period +What: /sys/.../events/in_activity_walking_thresh_rising_period +What: /sys/.../events/in_activity_walking_thresh_falling_period +What: /sys/.../events/in_activity_jogging_thresh_rising_period +What: /sys/.../events/in_activity_jogging_thresh_falling_period +What: /sys/.../events/in_activity_running_thresh_rising_period +What: /sys/.../events/in_activity_running_thresh_falling_period KernelVersion: 2.6.37 Contact: linux-iio@vger.kernel.org Description: @@ -776,6 +856,40 @@ Description: met before an event is generated. If direction is not specified then this period applies to both directions. +What: /sys/.../events/in_activity_still_thresh_rising_en +What: /sys/.../events/in_activity_still_thresh_falling_en +What: /sys/.../events/in_activity_walking_thresh_rising_en +What: /sys/.../events/in_activity_walking_thresh_falling_en +What: /sys/.../events/in_activity_jogging_thresh_rising_en +What: /sys/.../events/in_activity_jogging_thresh_falling_en +What: /sys/.../events/in_activity_running_thresh_rising_en +What: /sys/.../events/in_activity_running_thresh_falling_en +KernelVersion: 3.19 +Contact: linux-iio@vger.kernel.org +Description: + Enables or disables activitity events. Depending on direction + an event is generated when sensor ENTERS or LEAVES a given state. + +What: /sys/.../events/in_activity_still_thresh_rising_value +What: /sys/.../events/in_activity_still_thresh_falling_value +What: /sys/.../events/in_activity_walking_thresh_rising_value +What: /sys/.../events/in_activity_walking_thresh_falling_value +What: /sys/.../events/in_activity_jogging_thresh_rising_value +What: /sys/.../events/in_activity_jogging_thresh_falling_value +What: /sys/.../events/in_activity_running_thresh_rising_value +What: /sys/.../events/in_activity_running_thresh_falling_value +KernelVersion: 3.19 +Contact: linux-iio@vger.kernel.org +Description: + Confidence value (in units as percentage) to be used + for deciding when an event should be generated. E.g for + running: If the confidence value reported by the sensor + is greater than in_activity_running_thresh_rising_value + then the sensor ENTERS running state. Conversely, if the + confidence value reported by the sensor is lower than + in_activity_running_thresh_falling_value then the sensor + is LEAVING running state. + What: /sys/.../iio:deviceX/events/in_accel_mag_en What: /sys/.../iio:deviceX/events/in_accel_mag_rising_en What: /sys/.../iio:deviceX/events/in_accel_mag_falling_en @@ -808,6 +922,25 @@ Description: number or direction is not specified, applies to all channels of this type. +What: /sys/.../events/in_steps_change_en +KernelVersion: 3.20 +Contact: linux-iio@vger.kernel.org +Description: + Event generated when channel passes a threshold on the absolute + change in value. E.g. for steps: a step change event is + generated each time the user takes N steps, where N is set using + in_steps_change_value. + +What: /sys/.../events/in_steps_change_value +KernelVersion: 3.20 +Contact: linux-iio@vger.kernel.org +Description: + Specifies the value of change threshold that the + device is comparing against for the events enabled by + <type>[Y][_name]_roc[_rising|falling|]_en. E.g. for steps: + if set to 3, a step change event will be generated every 3 + steps. + What: /sys/bus/iio/devices/iio:deviceX/trigger/current_trigger KernelVersion: 2.6.35 Contact: linux-iio@vger.kernel.org @@ -942,6 +1075,16 @@ Description: and the relevant _type attributes to establish the data storage format. +What: /sys/.../iio:deviceX/in_activity_still_input +What: /sys/.../iio:deviceX/in_activity_walking_input +What: /sys/.../iio:deviceX/in_activity_jogging_input +What: /sys/.../iio:deviceX/in_activity_running_input +KernelVersion: 3.19 +Contact: linux-iio@vger.kernel.org +Description: + This attribute is used to read the confidence for an activity + expressed in units as percentage. + What: /sys/.../iio:deviceX/in_anglvel_z_quadrature_correction_raw KernelVersion: 2.6.38 Contact: linux-iio@vger.kernel.org @@ -959,6 +1102,24 @@ Description: For a list of available output power modes read in_accel_power_mode_available. +What: /sys/.../iio:deviceX/in_energy_input +What: /sys/.../iio:deviceX/in_energy_raw +KernelVersion: 3.20 +Contact: linux-iio@vger.kernel.org +Description: + This attribute is used to read the energy value reported by the + device (e.g.: human activity sensors report energy burnt by the + user). Units after application of scale are Joules. + +What: /sys/.../iio:deviceX/in_distance_input +What: /sys/.../iio:deviceX/in_distance_raw +KernelVersion: 3.20 +Contact: linux-iio@vger.kernel.org +Description: + This attribute is used to read the distance covered by the user + since the last reboot while activated. Units after application + of scale are meters. + What: /sys/bus/iio/devices/iio:deviceX/store_eeprom KernelVersion: 3.4.0 Contact: linux-iio@vger.kernel.org @@ -978,7 +1139,9 @@ Description: reflectivity of infrared or ultrasound emitted. Often these sensors are unit less and as such conversion to SI units is not possible. Where it is, the units should - be meters. + be meters. If such a conversion is not possible, the reported + values should behave in the same way as a distance, i.e. lower + values indicate something is closer to the sensor. What: /sys/.../iio:deviceX/in_illuminanceY_input What: /sys/.../iio:deviceX/in_illuminanceY_raw @@ -1010,6 +1173,12 @@ Description: This attribute is used to get/set the integration time in seconds. +What: /sys/.../iio:deviceX/in_velocity_sqrt(x^2+y^2+z^2)_integration_time +KernelVersion: 3.20 +Contact: linux-iio@vger.kernel.org +Description: + Number of seconds in which to compute speed. + What: /sys/bus/iio/devices/iio:deviceX/in_rot_quaternion_raw KernelVersion: 3.15 Contact: linux-iio@vger.kernel.org @@ -1028,3 +1197,55 @@ Contact: linux-iio@vger.kernel.org Description: Raw value of rotation from true/magnetic north measured with or without compensation from tilt sensors. + +What: /sys/bus/iio/devices/iio:deviceX/in_currentX_raw +KernelVersion: 3.18 +Contact: linux-iio@vger.kernel.org +Description: + Raw current measurement from channel X. Units are in milliamps + after application of scale and offset. If no offset or scale is + present, output should be considered as processed with the + unit in milliamps. + +What: /sys/.../iio:deviceX/in_energy_en +What: /sys/.../iio:deviceX/in_distance_en +What: /sys/.../iio:deviceX/in_velocity_sqrt(x^2+y^2+z^2)_en +What: /sys/.../iio:deviceX/in_steps_en +KernelVersion: 3.19 +Contact: linux-iio@vger.kernel.org +Description: + Activates a device feature that runs in firmware/hardware. + E.g. for steps: the pedometer saves power while not used; + when activated, it will count the steps taken by the user in + firmware and export them through in_steps_input. + +What: /sys/.../iio:deviceX/in_steps_input +KernelVersion: 3.19 +Contact: linux-iio@vger.kernel.org +Description: + This attribute is used to read the number of steps taken by the user + since the last reboot while activated. + +What: /sys/.../iio:deviceX/in_velocity_sqrt(x^2+y^2+z^2)_input +What: /sys/.../iio:deviceX/in_velocity_sqrt(x^2+y^2+z^2)_raw +KernelVersion: 3.19 +Contact: linux-iio@vger.kernel.org +Description: + This attribute is used to read the current speed value of the + user (which is the norm or magnitude of the velocity vector). + Units after application of scale are m/s. + +What: /sys/.../iio:deviceX/in_steps_debounce_count +KernelVersion: 3.20 +Contact: linux-iio@vger.kernel.org +Description: + Specifies the number of steps that must occur within + in_steps_filter_debounce_time for the pedometer to decide the + consumer is making steps. + +What: /sys/.../iio:deviceX/in_steps_debounce_time +KernelVersion: 3.20 +Contact: linux-iio@vger.kernel.org +Description: + Specifies number of seconds in which we compute the steps + that occur in order to decide if the consumer is making steps. diff --git a/Documentation/ABI/testing/sysfs-bus-pci b/Documentation/ABI/testing/sysfs-bus-pci index ee6c04036492..b3bc50f650ee 100644 --- a/Documentation/ABI/testing/sysfs-bus-pci +++ b/Documentation/ABI/testing/sysfs-bus-pci @@ -281,3 +281,16 @@ Description: opt-out of driver binding using a driver_override name such as "none". Only a single driver may be specified in the override, there is no support for parsing delimiters. + +What: /sys/bus/pci/devices/.../numa_node +Date: Oct 2014 +Contact: Prarit Bhargava <prarit@redhat.com> +Description: + This file contains the NUMA node to which the PCI device is + attached, or -1 if the node is unknown. The initial value + comes from an ACPI _PXM method or a similar firmware + source. If that is missing or incorrect, this file can be + written to override the node. In that case, please report + a firmware bug to the system vendor. Writing to this file + taints the kernel with TAINT_FIRMWARE_WORKAROUND, which + reduces the supportability of your system. diff --git a/Documentation/ABI/testing/sysfs-bus-usb b/Documentation/ABI/testing/sysfs-bus-usb index 614d451cee41..e5cc7633d013 100644 --- a/Documentation/ABI/testing/sysfs-bus-usb +++ b/Documentation/ABI/testing/sysfs-bus-usb @@ -104,16 +104,15 @@ What: /sys/bus/usb/devices/.../power/usb2_hardware_lpm Date: September 2011 Contact: Andiry Xu <andiry.xu@amd.com> Description: - If CONFIG_PM_RUNTIME is set and a USB 2.0 lpm-capable device - is plugged in to a xHCI host which support link PM, it will - perform a LPM test; if the test is passed and host supports - USB2 hardware LPM (xHCI 1.0 feature), USB2 hardware LPM will - be enabled for the device and the USB device directory will - contain a file named power/usb2_hardware_lpm. The file holds - a string value (enable or disable) indicating whether or not - USB2 hardware LPM is enabled for the device. Developer can - write y/Y/1 or n/N/0 to the file to enable/disable the - feature. + If CONFIG_PM is set and a USB 2.0 lpm-capable device is plugged + in to a xHCI host which support link PM, it will perform a LPM + test; if the test is passed and host supports USB2 hardware LPM + (xHCI 1.0 feature), USB2 hardware LPM will be enabled for the + device and the USB device directory will contain a file named + power/usb2_hardware_lpm. The file holds a string value (enable + or disable) indicating whether or not USB2 hardware LPM is + enabled for the device. Developer can write y/Y/1 or n/N/0 to + the file to enable/disable the feature. What: /sys/bus/usb/devices/.../removable Date: February 2012 diff --git a/Documentation/ABI/testing/sysfs-class-cxl b/Documentation/ABI/testing/sysfs-class-cxl index 554405ec1955..3680364b4048 100644 --- a/Documentation/ABI/testing/sysfs-class-cxl +++ b/Documentation/ABI/testing/sysfs-class-cxl @@ -1,3 +1,9 @@ +Note: Attributes that are shared between devices are stored in the directory +pointed to by the symlink device/. +Example: The real path of the attribute /sys/class/cxl/afu0.0s/irqs_max is +/sys/class/cxl/afu0.0s/device/irqs_max, i.e. /sys/class/cxl/afu0.0/irqs_max. + + Slave contexts (eg. /sys/class/cxl/afu0.0s): What: /sys/class/cxl/<afu>/irqs_max @@ -67,7 +73,7 @@ Contact: linuxppc-dev@lists.ozlabs.org Description: read only Decimal value of the current version of the kernel/user API. -What: /sys/class/cxl/<afu>/api_version_com +What: /sys/class/cxl/<afu>/api_version_compatible Date: September 2014 Contact: linuxppc-dev@lists.ozlabs.org Description: read only @@ -75,6 +81,42 @@ Description: read only this this kernel supports. +AFU configuration records (eg. /sys/class/cxl/afu0.0/cr0): + +An AFU may optionally export one or more PCIe like configuration records, known +as AFU configuration records, which will show up here (if present). + +What: /sys/class/cxl/<afu>/cr<config num>/vendor +Date: February 2015 +Contact: linuxppc-dev@lists.ozlabs.org +Description: read only + Hexadecimal value of the vendor ID found in this AFU + configuration record. + +What: /sys/class/cxl/<afu>/cr<config num>/device +Date: February 2015 +Contact: linuxppc-dev@lists.ozlabs.org +Description: read only + Hexadecimal value of the device ID found in this AFU + configuration record. + +What: /sys/class/cxl/<afu>/cr<config num>/vendor +Date: February 2015 +Contact: linuxppc-dev@lists.ozlabs.org +Description: read only + Hexadecimal value of the class code found in this AFU + configuration record. + +What: /sys/class/cxl/<afu>/cr<config num>/config +Date: February 2015 +Contact: linuxppc-dev@lists.ozlabs.org +Description: read only + This binary file provides raw access to the AFU configuration + record. The format is expected to match the either the standard + or extended configuration space defined by the PCIe + specification. + + Master contexts (eg. /sys/class/cxl/afu0.0m) @@ -106,7 +148,7 @@ Contact: linuxppc-dev@lists.ozlabs.org Description: read only Identifies the CAIA Version the card implements. -What: /sys/class/cxl/<card>/psl_version +What: /sys/class/cxl/<card>/psl_revision Date: September 2014 Contact: linuxppc-dev@lists.ozlabs.org Description: read only @@ -127,3 +169,24 @@ Contact: linuxppc-dev@lists.ozlabs.org Description: read only Will return "user" or "factory" depending on the image loaded onto the card. + +What: /sys/class/cxl/<card>/load_image_on_perst +Date: December 2014 +Contact: linuxppc-dev@lists.ozlabs.org +Description: read/write + Valid entries are "none", "user", and "factory". + "none" means PERST will not cause image to be loaded to the + card. A power cycle is required to load the image. + "none" could be useful for debugging because the trace arrays + are preserved. + "user" and "factory" means PERST will cause either the user or + user or factory image to be loaded. + Default is to reload on PERST whichever image the card has + loaded. + +What: /sys/class/cxl/<card>/reset +Date: October 2014 +Contact: linuxppc-dev@lists.ozlabs.org +Description: write only + Writing 1 will issue a PERST to card which may cause the card + to reload the FPGA depending on load_image_on_perst. diff --git a/Documentation/ABI/testing/sysfs-class-mei b/Documentation/ABI/testing/sysfs-class-mei index 0ec8b8178c41..80d9888a8ece 100644 --- a/Documentation/ABI/testing/sysfs-class-mei +++ b/Documentation/ABI/testing/sysfs-class-mei @@ -14,3 +14,18 @@ Description: The /sys/class/mei/meiN directory is created for each probed mei device +What: /sys/class/mei/meiN/fw_status +Date: Nov 2014 +KernelVersion: 3.19 +Contact: Tomas Winkler <tomas.winkler@intel.com> +Description: Display fw status registers content + + The ME FW writes its status information into fw status + registers for BIOS and OS to monitor fw health. + + The register contains running state, power management + state, error codes, and others. The way the registers + are decoded depends on PCH or SoC generation. + Also number of registers varies between 1 and 6 + depending on generation. + diff --git a/Documentation/ABI/testing/sysfs-class-net b/Documentation/ABI/testing/sysfs-class-net index e1b2e785bba8..beb8ec4dabbc 100644 --- a/Documentation/ABI/testing/sysfs-class-net +++ b/Documentation/ABI/testing/sysfs-class-net @@ -216,3 +216,11 @@ Contact: netdev@vger.kernel.org Description: Indicates the interface protocol type as a decimal value. See include/uapi/linux/if_arp.h for all possible values. + +What: /sys/class/net/<iface>/phys_switch_id +Date: November 2014 +KernelVersion: 3.19 +Contact: netdev@vger.kernel.org +Description: + Indicates the unique physical switch identifier of a switch this + port belongs to, as a string. diff --git a/Documentation/ABI/testing/sysfs-class-power b/Documentation/ABI/testing/sysfs-class-power index 909e7602c717..369d2a2d7d3e 100644 --- a/Documentation/ABI/testing/sysfs-class-power +++ b/Documentation/ABI/testing/sysfs-class-power @@ -32,3 +32,45 @@ Description: Valid values: - 5, 6 or 7 (hours), - 0: disabled. + +What: /sys/class/power_supply/max77693-charger/device/fast_charge_timer +Date: January 2015 +KernelVersion: 3.19.0 +Contact: Krzysztof Kozlowski <k.kozlowski@samsung.com> +Description: + This entry shows and sets the maximum time the max77693 + charger operates in fast-charge mode. When the timer expires + the device will terminate fast-charge mode (charging current + will drop to 0 A) and will trigger interrupt. + + Valid values: + - 4 - 16 (hours), step by 2 (rounded down) + - 0: disabled. + +What: /sys/class/power_supply/max77693-charger/device/top_off_threshold_current +Date: January 2015 +KernelVersion: 3.19.0 +Contact: Krzysztof Kozlowski <k.kozlowski@samsung.com> +Description: + This entry shows and sets the charging current threshold for + entering top-off charging mode. When charging current in fast + charge mode drops below this value, the charger will trigger + interrupt and start top-off charging mode. + + Valid values: + - 100000 - 200000 (microamps), step by 25000 (rounded down) + - 200000 - 350000 (microamps), step by 50000 (rounded down) + - 0: disabled. + +What: /sys/class/power_supply/max77693-charger/device/top_off_timer +Date: January 2015 +KernelVersion: 3.19.0 +Contact: Krzysztof Kozlowski <k.kozlowski@samsung.com> +Description: + This entry shows and sets the maximum time the max77693 + charger operates in top-off charge mode. When the timer expires + the device will terminate top-off charge mode (charging current + will drop to 0 A) and will trigger interrupt. + + Valid values: + - 0 - 70 (minutes), step by 10 (rounded down) diff --git a/Documentation/ABI/testing/sysfs-devices-system-cpu b/Documentation/ABI/testing/sysfs-devices-system-cpu index acb9bfc89b48..99983e67c13c 100644 --- a/Documentation/ABI/testing/sysfs-devices-system-cpu +++ b/Documentation/ABI/testing/sysfs-devices-system-cpu @@ -224,3 +224,50 @@ Description: Parameters for the Intel P-state driver frequency range. More details can be found in Documentation/cpu-freq/intel-pstate.txt + +What: /sys/devices/system/cpu/cpu*/cache/index*/<set_of_attributes_mentioned_below> +Date: July 2014(documented, existed before August 2008) +Contact: Sudeep Holla <sudeep.holla@arm.com> + Linux kernel mailing list <linux-kernel@vger.kernel.org> +Description: Parameters for the CPU cache attributes + + allocation_policy: + - WriteAllocate: allocate a memory location to a cache line + on a cache miss because of a write + - ReadAllocate: allocate a memory location to a cache line + on a cache miss because of a read + - ReadWriteAllocate: both writeallocate and readallocate + + attributes: LEGACY used only on IA64 and is same as write_policy + + coherency_line_size: the minimum amount of data in bytes that gets + transferred from memory to cache + + level: the cache hierarcy in the multi-level cache configuration + + number_of_sets: total number of sets in the cache, a set is a + collection of cache lines with the same cache index + + physical_line_partition: number of physical cache line per cache tag + + shared_cpu_list: the list of logical cpus sharing the cache + + shared_cpu_map: logical cpu mask containing the list of cpus sharing + the cache + + size: the total cache size in kB + + type: + - Instruction: cache that only holds instructions + - Data: cache that only caches data + - Unified: cache that holds both data and instructions + + ways_of_associativity: degree of freedom in placing a particular block + of memory in the cache + + write_policy: + - WriteThrough: data is written to both the cache line + and to the block in the lower-level memory + - WriteBack: data is written only to the cache line and + the modified cache line is written to main + memory only when it is replaced diff --git a/Documentation/ABI/testing/sysfs-driver-input-axp-pek b/Documentation/ABI/testing/sysfs-driver-input-axp-pek new file mode 100644 index 000000000000..a5e671b9fa79 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-driver-input-axp-pek @@ -0,0 +1,11 @@ +What: /sys/class/input/input(x)/device/startup +Date: March 2014 +Contact: Carlo Caione <carlo@caione.org> +Description: Startup time in us. Board is powered on if the button is pressed + for more than <startup_time> + +What: /sys/class/input/input(x)/device/shutdown +Date: March 2014 +Contact: Carlo Caione <carlo@caione.org> +Description: Shutdown time in us. Board is powered off if the button is pressed + for more than <shutdown_time> diff --git a/Documentation/ABI/testing/sysfs-fs-f2fs b/Documentation/ABI/testing/sysfs-fs-f2fs index 6f9157f16725..2c4cc42006e8 100644 --- a/Documentation/ABI/testing/sysfs-fs-f2fs +++ b/Documentation/ABI/testing/sysfs-fs-f2fs @@ -74,3 +74,9 @@ Date: March 2014 Contact: "Jaegeuk Kim" <jaegeuk.kim@samsung.com> Description: Controls the memory footprint used by f2fs. + +What: /sys/fs/f2fs/<disk>/trim_sections +Date: February 2015 +Contact: "Jaegeuk Kim" <jaegeuk@kernel.org> +Description: + Controls the trimming rate in batch mode. diff --git a/Documentation/ABI/testing/sysfs-kernel-livepatch b/Documentation/ABI/testing/sysfs-kernel-livepatch new file mode 100644 index 000000000000..5bf42a840b22 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-kernel-livepatch @@ -0,0 +1,44 @@ +What: /sys/kernel/livepatch +Date: Nov 2014 +KernelVersion: 3.19.0 +Contact: live-patching@vger.kernel.org +Description: + Interface for kernel live patching + + The /sys/kernel/livepatch directory contains subdirectories for + each loaded live patch module. + +What: /sys/kernel/livepatch/<patch> +Date: Nov 2014 +KernelVersion: 3.19.0 +Contact: live-patching@vger.kernel.org +Description: + The patch directory contains subdirectories for each kernel + object (vmlinux or a module) in which it patched functions. + +What: /sys/kernel/livepatch/<patch>/enabled +Date: Nov 2014 +KernelVersion: 3.19.0 +Contact: live-patching@vger.kernel.org +Description: + A writable attribute that indicates whether the patched + code is currently applied. Writing 0 will disable the patch + while writing 1 will re-enable the patch. + +What: /sys/kernel/livepatch/<patch>/<object> +Date: Nov 2014 +KernelVersion: 3.19.0 +Contact: live-patching@vger.kernel.org +Description: + The object directory contains subdirectories for each function + that is patched within the object. + +What: /sys/kernel/livepatch/<patch>/<object>/<function> +Date: Nov 2014 +KernelVersion: 3.19.0 +Contact: live-patching@vger.kernel.org +Description: + The function directory contains attributes regarding the + properties and state of the patched function. + + There are currently no such attributes. diff --git a/Documentation/Changes b/Documentation/Changes index 1de131bb49fb..646cdaa6e9d1 100644 --- a/Documentation/Changes +++ b/Documentation/Changes @@ -21,8 +21,8 @@ running a Linux kernel. Also, not all tools are necessary on all systems; obviously, if you don't have any ISDN hardware, for example, you probably needn't concern yourself with isdn4k-utils. -o Gnu C 3.2 # gcc --version -o Gnu make 3.80 # make --version +o GNU C 3.2 # gcc --version +o GNU make 3.80 # make --version o binutils 2.12 # ld -v o util-linux 2.10o # fdformat --version o module-init-tools 0.9.10 # depmod -V @@ -57,7 +57,7 @@ computer. Make ---- -You will need Gnu make 3.80 or later to build the kernel. +You will need GNU make 3.80 or later to build the kernel. Binutils -------- @@ -383,7 +383,7 @@ o <http://www.iptables.org/downloads.html> Ip-route2 --------- -o <ftp://ftp.tux.org/pub/net/ip-routing/iproute2-2.2.4-now-ss991023.tar.gz> +o <https://www.kernel.org/pub/linux/utils/net/iproute2/> OProfile -------- diff --git a/Documentation/CodingStyle b/Documentation/CodingStyle index 3171822c22a5..449a8a19fc21 100644 --- a/Documentation/CodingStyle +++ b/Documentation/CodingStyle @@ -392,7 +392,12 @@ The goto statement comes in handy when a function exits from multiple locations and some common work such as cleanup has to be done. If there is no cleanup needed then just return directly. -The rationale is: +Choose label names which say what the goto does or why the goto exists. An +example of a good name could be "out_buffer:" if the goto frees "buffer". Avoid +using GW-BASIC names like "err1:" and "err2:". Also don't name them after the +goto location like "err_kmalloc_failed:" + +The rationale for using gotos is: - unconditional statements are easier to understand and follow - nesting is reduced @@ -403,9 +408,10 @@ The rationale is: int fun(int a) { int result = 0; - char *buffer = kmalloc(SIZE); + char *buffer; - if (buffer == NULL) + buffer = kmalloc(SIZE, GFP_KERNEL); + if (!buffer) return -ENOMEM; if (condition1) { @@ -413,14 +419,25 @@ int fun(int a) ... } result = 1; - goto out; + goto out_buffer; } ... -out: +out_buffer: kfree(buffer); return result; } +A common type of bug to be aware of it "one err bugs" which look like this: + +err: + kfree(foo->bar); + kfree(foo); + return ret; + +The bug in this code is that on some exit paths "foo" is NULL. Normally the +fix for this is to split it up into two error labels "err_bar:" and "err_foo:". + + Chapter 8: Commenting Comments are good, but there is also a danger of over-commenting. NEVER @@ -510,6 +527,7 @@ values. To do the latter, you can stick the following in your .emacs file: (string-match (expand-file-name "~/src/linux-trees") filename)) (setq indent-tabs-mode t) + (setq show-trailing-whitespace t) (c-set-style "linux-tabs-only"))))) This will make emacs go better with the kernel coding style for C @@ -845,6 +863,49 @@ next instruction in the assembly output: : /* outputs */ : /* inputs */ : /* clobbers */); + Chapter 20: Conditional Compilation + +Wherever possible, don't use preprocessor conditionals (#if, #ifdef) in .c +files; doing so makes code harder to read and logic harder to follow. Instead, +use such conditionals in a header file defining functions for use in those .c +files, providing no-op stub versions in the #else case, and then call those +functions unconditionally from .c files. The compiler will avoid generating +any code for the stub calls, producing identical results, but the logic will +remain easy to follow. + +Prefer to compile out entire functions, rather than portions of functions or +portions of expressions. Rather than putting an ifdef in an expression, factor +out part or all of the expression into a separate helper function and apply the +conditional to that function. + +If you have a function or variable which may potentially go unused in a +particular configuration, and the compiler would warn about its definition +going unused, mark the definition as __maybe_unused rather than wrapping it in +a preprocessor conditional. (However, if a function or variable *always* goes +unused, delete it.) + +Within code, where possible, use the IS_ENABLED macro to convert a Kconfig +symbol into a C boolean expression, and use it in a normal C conditional: + + if (IS_ENABLED(CONFIG_SOMETHING)) { + ... + } + +The compiler will constant-fold the conditional away, and include or exclude +the block of code just as with an #ifdef, so this will not add any runtime +overhead. However, this approach still allows the C compiler to see the code +inside the block, and check it for correctness (syntax, types, symbol +references, etc). Thus, you still have to use an #ifdef if the code inside the +block references symbols that will not exist if the condition is not met. + +At the end of any non-trivial #if or #ifdef block (more than a few lines), +place a comment after the #endif on the same line, noting the conditional +expression used. For instance: + +#ifdef CONFIG_SOMETHING +... +#endif /* CONFIG_SOMETHING */ + Appendix I: References diff --git a/Documentation/DocBook/80211.tmpl b/Documentation/DocBook/80211.tmpl index d9b9416c989f..aac9357d4866 100644 --- a/Documentation/DocBook/80211.tmpl +++ b/Documentation/DocBook/80211.tmpl @@ -113,7 +113,6 @@ !Finclude/net/cfg80211.h cfg80211_beacon_data !Finclude/net/cfg80211.h cfg80211_ap_settings !Finclude/net/cfg80211.h station_parameters -!Finclude/net/cfg80211.h station_info_flags !Finclude/net/cfg80211.h rate_info_flags !Finclude/net/cfg80211.h rate_info !Finclude/net/cfg80211.h station_info @@ -435,7 +434,6 @@ <section id="ps-client"> <title>support for powersaving clients</title> !Pinclude/net/mac80211.h AP support for powersaving clients - </section> !Finclude/net/mac80211.h ieee80211_get_buffered_bc !Finclude/net/mac80211.h ieee80211_beacon_get !Finclude/net/mac80211.h ieee80211_sta_eosp @@ -444,6 +442,7 @@ !Finclude/net/mac80211.h ieee80211_sta_ps_transition_ni !Finclude/net/mac80211.h ieee80211_sta_set_buffered !Finclude/net/mac80211.h ieee80211_sta_block_awake + </section> </chapter> <chapter id="multi-iface"> @@ -488,8 +487,8 @@ <title>RX A-MPDU aggregation</title> !Pnet/mac80211/agg-rx.c RX A-MPDU aggregation !Cnet/mac80211/agg-rx.c - </sect1> !Finclude/net/mac80211.h ieee80211_ampdu_mlme_action + </sect1> </chapter> <chapter id="smps"> diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile index bec06659e0eb..b6a6a2e0dd3b 100644 --- a/Documentation/DocBook/Makefile +++ b/Documentation/DocBook/Makefile @@ -15,7 +15,7 @@ DOCBOOKS := z8530book.xml device-drivers.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 \ - writing_musb_glue_layer.xml + writing_musb_glue_layer.xml crypto-API.xml include Documentation/DocBook/media/Makefile @@ -56,7 +56,7 @@ htmldocs: $(HTML) MAN := $(patsubst %.xml, %.9, $(BOOKS)) mandocs: $(MAN) - $(if $(wildcard $(obj)/man/*.9),gzip -f $(obj)/man/*.9) + find $(obj)/man -name '*.9' | xargs gzip -f installmandocs: mandocs mkdir -p /usr/local/man/man9/ diff --git a/Documentation/DocBook/alsa-driver-api.tmpl b/Documentation/DocBook/alsa-driver-api.tmpl index 0230a96f0564..71f9246127ec 100644 --- a/Documentation/DocBook/alsa-driver-api.tmpl +++ b/Documentation/DocBook/alsa-driver-api.tmpl @@ -57,6 +57,7 @@ !Esound/core/pcm.c !Esound/core/pcm_lib.c !Esound/core/pcm_native.c +!Iinclude/sound/pcm.h </sect1> <sect1><title>PCM Format Helpers</title> !Esound/core/pcm_misc.c @@ -64,6 +65,10 @@ <sect1><title>PCM Memory Management</title> !Esound/core/pcm_memory.c </sect1> + <sect1><title>PCM DMA Engine API</title> +!Esound/core/pcm_dmaengine.c +!Iinclude/sound/dmaengine_pcm.h + </sect1> </chapter> <chapter><title>Control/Mixer API</title> <sect1><title>General Control Interface</title> @@ -91,12 +96,38 @@ !Esound/core/info.c </sect1> </chapter> + <chapter><title>Compress Offload</title> + <sect1><title>Compress Offload API</title> +!Esound/core/compress_offload.c +!Iinclude/uapi/sound/compress_offload.h +!Iinclude/uapi/sound/compress_params.h +!Iinclude/sound/compress_driver.h + </sect1> + </chapter> + <chapter><title>ASoC</title> + <sect1><title>ASoC Core API</title> +!Iinclude/sound/soc.h +!Esound/soc/soc-core.c +!Esound/soc/soc-cache.c +!Esound/soc/soc-devres.c +!Esound/soc/soc-io.c +!Esound/soc/soc-pcm.c + </sect1> + <sect1><title>ASoC DAPM API</title> +!Esound/soc/soc-dapm.c + </sect1> + <sect1><title>ASoC DMA Engine API</title> +!Esound/soc/soc-generic-dmaengine-pcm.c + </sect1> + </chapter> <chapter><title>Miscellaneous Functions</title> <sect1><title>Hardware-Dependent Devices API</title> !Esound/core/hwdep.c </sect1> <sect1><title>Jack Abstraction Layer API</title> +!Iinclude/sound/jack.h !Esound/core/jack.c +!Esound/soc/soc-jack.c </sect1> <sect1><title>ISA DMA Helpers</title> !Esound/core/isadma.c diff --git a/Documentation/DocBook/crypto-API.tmpl b/Documentation/DocBook/crypto-API.tmpl new file mode 100644 index 000000000000..04a8c24ead47 --- /dev/null +++ b/Documentation/DocBook/crypto-API.tmpl @@ -0,0 +1,1253 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!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="KernelCryptoAPI"> + <bookinfo> + <title>Linux Kernel Crypto API</title> + + <authorgroup> + <author> + <firstname>Stephan</firstname> + <surname>Mueller</surname> + <affiliation> + <address> + <email>smueller@chronox.de</email> + </address> + </affiliation> + </author> + <author> + <firstname>Marek</firstname> + <surname>Vasut</surname> + <affiliation> + <address> + <email>marek@denx.de</email> + </address> + </affiliation> + </author> + </authorgroup> + + <copyright> + <year>2014</year> + <holder>Stephan Mueller</holder> + </copyright> + + + <legalnotice> + <para> + This documentation is free software; you can redistribute + it and/or modify it under the terms of the GNU General Public + License as published by the Free Software Foundation; either + version 2 of the License, or (at your option) any later + version. + </para> + + <para> + This program is distributed in the hope that it will be + useful, but WITHOUT ANY WARRANTY; without even the implied + warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. + See the GNU General Public License for more details. + </para> + + <para> + You should have received a copy of the GNU General Public + License along with this program; if not, write to the Free + Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, + MA 02111-1307 USA + </para> + + <para> + For more details see the file COPYING in the source + distribution of Linux. + </para> + </legalnotice> + </bookinfo> + + <toc></toc> + + <chapter id="Intro"> + <title>Kernel Crypto API Interface Specification</title> + + <sect1><title>Introduction</title> + + <para> + The kernel crypto API offers a rich set of cryptographic ciphers as + well as other data transformation mechanisms and methods to invoke + these. This document contains a description of the API and provides + example code. + </para> + + <para> + To understand and properly use the kernel crypto API a brief + explanation of its structure is given. Based on the architecture, + the API can be separated into different components. Following the + architecture specification, hints to developers of ciphers are + provided. Pointers to the API function call documentation are + given at the end. + </para> + + <para> + The kernel crypto API refers to all algorithms as "transformations". + Therefore, a cipher handle variable usually has the name "tfm". + Besides cryptographic operations, the kernel crypto API also knows + compression transformations and handles them the same way as ciphers. + </para> + + <para> + The kernel crypto API serves the following entity types: + + <itemizedlist> + <listitem> + <para>consumers requesting cryptographic services</para> + </listitem> + <listitem> + <para>data transformation implementations (typically ciphers) + that can be called by consumers using the kernel crypto + API</para> + </listitem> + </itemizedlist> + </para> + + <para> + This specification is intended for consumers of the kernel crypto + API as well as for developers implementing ciphers. This API + specification, however, does not discuss all API calls available + to data transformation implementations (i.e. implementations of + ciphers and other transformations (such as CRC or even compression + algorithms) that can register with the kernel crypto API). + </para> + + <para> + Note: The terms "transformation" and cipher algorithm are used + interchangably. + </para> + </sect1> + + <sect1><title>Terminology</title> + <para> + The transformation implementation is an actual code or interface + to hardware which implements a certain transformation with precisely + defined behavior. + </para> + + <para> + The transformation object (TFM) is an instance of a transformation + implementation. There can be multiple transformation objects + associated with a single transformation implementation. Each of + those transformation objects is held by a crypto API consumer or + another transformation. Transformation object is allocated when a + crypto API consumer requests a transformation implementation. + The consumer is then provided with a structure, which contains + a transformation object (TFM). + </para> + + <para> + The structure that contains transformation objects may also be + referred to as a "cipher handle". Such a cipher handle is always + subject to the following phases that are reflected in the API calls + applicable to such a cipher handle: + </para> + + <orderedlist> + <listitem> + <para>Initialization of a cipher handle.</para> + </listitem> + <listitem> + <para>Execution of all intended cipher operations applicable + for the handle where the cipher handle must be furnished to + every API call.</para> + </listitem> + <listitem> + <para>Destruction of a cipher handle.</para> + </listitem> + </orderedlist> + + <para> + When using the initialization API calls, a cipher handle is + created and returned to the consumer. Therefore, please refer + to all initialization API calls that refer to the data + structure type a consumer is expected to receive and subsequently + to use. The initialization API calls have all the same naming + conventions of crypto_alloc_*. + </para> + + <para> + The transformation context is private data associated with + the transformation object. + </para> + </sect1> + </chapter> + + <chapter id="Architecture"><title>Kernel Crypto API Architecture</title> + <sect1><title>Cipher algorithm types</title> + <para> + The kernel crypto API provides different API calls for the + following cipher types: + + <itemizedlist> + <listitem><para>Symmetric ciphers</para></listitem> + <listitem><para>AEAD ciphers</para></listitem> + <listitem><para>Message digest, including keyed message digest</para></listitem> + <listitem><para>Random number generation</para></listitem> + <listitem><para>User space interface</para></listitem> + </itemizedlist> + </para> + </sect1> + + <sect1><title>Ciphers And Templates</title> + <para> + The kernel crypto API provides implementations of single block + ciphers and message digests. In addition, the kernel crypto API + provides numerous "templates" that can be used in conjunction + with the single block ciphers and message digests. Templates + include all types of block chaining mode, the HMAC mechanism, etc. + </para> + + <para> + Single block ciphers and message digests can either be directly + used by a caller or invoked together with a template to form + multi-block ciphers or keyed message digests. + </para> + + <para> + A single block cipher may even be called with multiple templates. + However, templates cannot be used without a single cipher. + </para> + + <para> + See /proc/crypto and search for "name". For example: + + <itemizedlist> + <listitem><para>aes</para></listitem> + <listitem><para>ecb(aes)</para></listitem> + <listitem><para>cmac(aes)</para></listitem> + <listitem><para>ccm(aes)</para></listitem> + <listitem><para>rfc4106(gcm(aes))</para></listitem> + <listitem><para>sha1</para></listitem> + <listitem><para>hmac(sha1)</para></listitem> + <listitem><para>authenc(hmac(sha1),cbc(aes))</para></listitem> + </itemizedlist> + </para> + + <para> + In these examples, "aes" and "sha1" are the ciphers and all + others are the templates. + </para> + </sect1> + + <sect1><title>Synchronous And Asynchronous Operation</title> + <para> + The kernel crypto API provides synchronous and asynchronous + API operations. + </para> + + <para> + When using the synchronous API operation, the caller invokes + a cipher operation which is performed synchronously by the + kernel crypto API. That means, the caller waits until the + cipher operation completes. Therefore, the kernel crypto API + calls work like regular function calls. For synchronous + operation, the set of API calls is small and conceptually + similar to any other crypto library. + </para> + + <para> + Asynchronous operation is provided by the kernel crypto API + which implies that the invocation of a cipher operation will + complete almost instantly. That invocation triggers the + cipher operation but it does not signal its completion. Before + invoking a cipher operation, the caller must provide a callback + function the kernel crypto API can invoke to signal the + completion of the cipher operation. Furthermore, the caller + must ensure it can handle such asynchronous events by applying + appropriate locking around its data. The kernel crypto API + does not perform any special serialization operation to protect + the caller's data integrity. + </para> + </sect1> + + <sect1><title>Crypto API Cipher References And Priority</title> + <para> + A cipher is referenced by the caller with a string. That string + has the following semantics: + + <programlisting> + template(single block cipher) + </programlisting> + + where "template" and "single block cipher" is the aforementioned + template and single block cipher, respectively. If applicable, + additional templates may enclose other templates, such as + + <programlisting> + template1(template2(single block cipher))) + </programlisting> + </para> + + <para> + The kernel crypto API may provide multiple implementations of a + template or a single block cipher. For example, AES on newer + Intel hardware has the following implementations: AES-NI, + assembler implementation, or straight C. Now, when using the + string "aes" with the kernel crypto API, which cipher + implementation is used? The answer to that question is the + priority number assigned to each cipher implementation by the + kernel crypto API. When a caller uses the string to refer to a + cipher during initialization of a cipher handle, the kernel + crypto API looks up all implementations providing an + implementation with that name and selects the implementation + with the highest priority. + </para> + + <para> + Now, a caller may have the need to refer to a specific cipher + implementation and thus does not want to rely on the + priority-based selection. To accommodate this scenario, the + kernel crypto API allows the cipher implementation to register + a unique name in addition to common names. When using that + unique name, a caller is therefore always sure to refer to + the intended cipher implementation. + </para> + + <para> + The list of available ciphers is given in /proc/crypto. However, + that list does not specify all possible permutations of + templates and ciphers. Each block listed in /proc/crypto may + contain the following information -- if one of the components + listed as follows are not applicable to a cipher, it is not + displayed: + </para> + + <itemizedlist> + <listitem> + <para>name: the generic name of the cipher that is subject + to the priority-based selection -- this name can be used by + the cipher allocation API calls (all names listed above are + examples for such generic names)</para> + </listitem> + <listitem> + <para>driver: the unique name of the cipher -- this name can + be used by the cipher allocation API calls</para> + </listitem> + <listitem> + <para>module: the kernel module providing the cipher + implementation (or "kernel" for statically linked ciphers)</para> + </listitem> + <listitem> + <para>priority: the priority value of the cipher implementation</para> + </listitem> + <listitem> + <para>refcnt: the reference count of the respective cipher + (i.e. the number of current consumers of this cipher)</para> + </listitem> + <listitem> + <para>selftest: specification whether the self test for the + cipher passed</para> + </listitem> + <listitem> + <para>type: + <itemizedlist> + <listitem> + <para>blkcipher for synchronous block ciphers</para> + </listitem> + <listitem> + <para>ablkcipher for asynchronous block ciphers</para> + </listitem> + <listitem> + <para>cipher for single block ciphers that may be used with + an additional template</para> + </listitem> + <listitem> + <para>shash for synchronous message digest</para> + </listitem> + <listitem> + <para>ahash for asynchronous message digest</para> + </listitem> + <listitem> + <para>aead for AEAD cipher type</para> + </listitem> + <listitem> + <para>compression for compression type transformations</para> + </listitem> + <listitem> + <para>rng for random number generator</para> + </listitem> + <listitem> + <para>givcipher for cipher with associated IV generator + (see the geniv entry below for the specification of the + IV generator type used by the cipher implementation)</para> + </listitem> + </itemizedlist> + </para> + </listitem> + <listitem> + <para>blocksize: blocksize of cipher in bytes</para> + </listitem> + <listitem> + <para>keysize: key size in bytes</para> + </listitem> + <listitem> + <para>ivsize: IV size in bytes</para> + </listitem> + <listitem> + <para>seedsize: required size of seed data for random number + generator</para> + </listitem> + <listitem> + <para>digestsize: output size of the message digest</para> + </listitem> + <listitem> + <para>geniv: IV generation type: + <itemizedlist> + <listitem> + <para>eseqiv for encrypted sequence number based IV + generation</para> + </listitem> + <listitem> + <para>seqiv for sequence number based IV generation</para> + </listitem> + <listitem> + <para>chainiv for chain iv generation</para> + </listitem> + <listitem> + <para><builtin> is a marker that the cipher implements + IV generation and handling as it is specific to the given + cipher</para> + </listitem> + </itemizedlist> + </para> + </listitem> + </itemizedlist> + </sect1> + + <sect1><title>Key Sizes</title> + <para> + When allocating a cipher handle, the caller only specifies the + cipher type. Symmetric ciphers, however, typically support + multiple key sizes (e.g. AES-128 vs. AES-192 vs. AES-256). + These key sizes are determined with the length of the provided + key. Thus, the kernel crypto API does not provide a separate + way to select the particular symmetric cipher key size. + </para> + </sect1> + + <sect1><title>Cipher Allocation Type And Masks</title> + <para> + The different cipher handle allocation functions allow the + specification of a type and mask flag. Both parameters have + the following meaning (and are therefore not covered in the + subsequent sections). + </para> + + <para> + The type flag specifies the type of the cipher algorithm. + The caller usually provides a 0 when the caller wants the + default handling. Otherwise, the caller may provide the + following selections which match the the aforementioned + cipher types: + </para> + + <itemizedlist> + <listitem> + <para>CRYPTO_ALG_TYPE_CIPHER Single block cipher</para> + </listitem> + <listitem> + <para>CRYPTO_ALG_TYPE_COMPRESS Compression</para> + </listitem> + <listitem> + <para>CRYPTO_ALG_TYPE_AEAD Authenticated Encryption with + Associated Data (MAC)</para> + </listitem> + <listitem> + <para>CRYPTO_ALG_TYPE_BLKCIPHER Synchronous multi-block cipher</para> + </listitem> + <listitem> + <para>CRYPTO_ALG_TYPE_ABLKCIPHER Asynchronous multi-block cipher</para> + </listitem> + <listitem> + <para>CRYPTO_ALG_TYPE_GIVCIPHER Asynchronous multi-block + cipher packed together with an IV generator (see geniv field + in the /proc/crypto listing for the known IV generators)</para> + </listitem> + <listitem> + <para>CRYPTO_ALG_TYPE_DIGEST Raw message digest</para> + </listitem> + <listitem> + <para>CRYPTO_ALG_TYPE_HASH Alias for CRYPTO_ALG_TYPE_DIGEST</para> + </listitem> + <listitem> + <para>CRYPTO_ALG_TYPE_SHASH Synchronous multi-block hash</para> + </listitem> + <listitem> + <para>CRYPTO_ALG_TYPE_AHASH Asynchronous multi-block hash</para> + </listitem> + <listitem> + <para>CRYPTO_ALG_TYPE_RNG Random Number Generation</para> + </listitem> + <listitem> + <para>CRYPTO_ALG_TYPE_PCOMPRESS Enhanced version of + CRYPTO_ALG_TYPE_COMPRESS allowing for segmented compression / + decompression instead of performing the operation on one + segment only. CRYPTO_ALG_TYPE_PCOMPRESS is intended to replace + CRYPTO_ALG_TYPE_COMPRESS once existing consumers are converted.</para> + </listitem> + </itemizedlist> + + <para> + The mask flag restricts the type of cipher. The only allowed + flag is CRYPTO_ALG_ASYNC to restrict the cipher lookup function + to asynchronous ciphers. Usually, a caller provides a 0 for the + mask flag. + </para> + + <para> + When the caller provides a mask and type specification, the + caller limits the search the kernel crypto API can perform for + a suitable cipher implementation for the given cipher name. + That means, even when a caller uses a cipher name that exists + during its initialization call, the kernel crypto API may not + select it due to the used type and mask field. + </para> + </sect1> + </chapter> + + <chapter id="Development"><title>Developing Cipher Algorithms</title> + <sect1><title>Registering And Unregistering Transformation</title> + <para> + There are three distinct types of registration functions in + the Crypto API. One is used to register a generic cryptographic + transformation, while the other two are specific to HASH + transformations and COMPRESSion. We will discuss the latter + two in a separate chapter, here we will only look at the + generic ones. + </para> + + <para> + Before discussing the register functions, the data structure + to be filled with each, struct crypto_alg, must be considered + -- see below for a description of this data structure. + </para> + + <para> + The generic registration functions can be found in + include/linux/crypto.h and their definition can be seen below. + The former function registers a single transformation, while + the latter works on an array of transformation descriptions. + The latter is useful when registering transformations in bulk. + </para> + + <programlisting> + int crypto_register_alg(struct crypto_alg *alg); + int crypto_register_algs(struct crypto_alg *algs, int count); + </programlisting> + + <para> + The counterparts to those functions are listed below. + </para> + + <programlisting> + int crypto_unregister_alg(struct crypto_alg *alg); + int crypto_unregister_algs(struct crypto_alg *algs, int count); + </programlisting> + + <para> + Notice that both registration and unregistration functions + do return a value, so make sure to handle errors. A return + code of zero implies success. Any return code < 0 implies + an error. + </para> + + <para> + The bulk registration / unregistration functions require + that struct crypto_alg is an array of count size. These + functions simply loop over that array and register / + unregister each individual algorithm. If an error occurs, + the loop is terminated at the offending algorithm definition. + That means, the algorithms prior to the offending algorithm + are successfully registered. Note, the caller has no way of + knowing which cipher implementations have successfully + registered. If this is important to know, the caller should + loop through the different implementations using the single + instance *_alg functions for each individual implementation. + </para> + </sect1> + + <sect1><title>Single-Block Symmetric Ciphers [CIPHER]</title> + <para> + Example of transformations: aes, arc4, ... + </para> + + <para> + This section describes the simplest of all transformation + implementations, that being the CIPHER type used for symmetric + ciphers. The CIPHER type is used for transformations which + operate on exactly one block at a time and there are no + dependencies between blocks at all. + </para> + + <sect2><title>Registration specifics</title> + <para> + The registration of [CIPHER] algorithm is specific in that + struct crypto_alg field .cra_type is empty. The .cra_u.cipher + has to be filled in with proper callbacks to implement this + transformation. + </para> + + <para> + See struct cipher_alg below. + </para> + </sect2> + + <sect2><title>Cipher Definition With struct cipher_alg</title> + <para> + Struct cipher_alg defines a single block cipher. + </para> + + <para> + Here are schematics of how these functions are called when + operated from other part of the kernel. Note that the + .cia_setkey() call might happen before or after any of these + schematics happen, but must not happen during any of these + are in-flight. + </para> + + <para> + <programlisting> + KEY ---. PLAINTEXT ---. + v v + .cia_setkey() -> .cia_encrypt() + | + '-----> CIPHERTEXT + </programlisting> + </para> + + <para> + Please note that a pattern where .cia_setkey() is called + multiple times is also valid: + </para> + + <para> + <programlisting> + + KEY1 --. PLAINTEXT1 --. KEY2 --. PLAINTEXT2 --. + v v v v + .cia_setkey() -> .cia_encrypt() -> .cia_setkey() -> .cia_encrypt() + | | + '---> CIPHERTEXT1 '---> CIPHERTEXT2 + </programlisting> + </para> + + </sect2> + </sect1> + + <sect1><title>Multi-Block Ciphers [BLKCIPHER] [ABLKCIPHER]</title> + <para> + Example of transformations: cbc(aes), ecb(arc4), ... + </para> + + <para> + This section describes the multi-block cipher transformation + implementations for both synchronous [BLKCIPHER] and + asynchronous [ABLKCIPHER] case. The multi-block ciphers are + used for transformations which operate on scatterlists of + data supplied to the transformation functions. They output + the result into a scatterlist of data as well. + </para> + + <sect2><title>Registration Specifics</title> + + <para> + The registration of [BLKCIPHER] or [ABLKCIPHER] algorithms + is one of the most standard procedures throughout the crypto API. + </para> + + <para> + Note, if a cipher implementation requires a proper alignment + of data, the caller should use the functions of + crypto_blkcipher_alignmask() or crypto_ablkcipher_alignmask() + respectively to identify a memory alignment mask. The kernel + crypto API is able to process requests that are unaligned. + This implies, however, additional overhead as the kernel + crypto API needs to perform the realignment of the data which + may imply moving of data. + </para> + </sect2> + + <sect2><title>Cipher Definition With struct blkcipher_alg and ablkcipher_alg</title> + <para> + Struct blkcipher_alg defines a synchronous block cipher whereas + struct ablkcipher_alg defines an asynchronous block cipher. + </para> + + <para> + Please refer to the single block cipher description for schematics + of the block cipher usage. The usage patterns are exactly the same + for [ABLKCIPHER] and [BLKCIPHER] as they are for plain [CIPHER]. + </para> + </sect2> + + <sect2><title>Specifics Of Asynchronous Multi-Block Cipher</title> + <para> + There are a couple of specifics to the [ABLKCIPHER] interface. + </para> + + <para> + First of all, some of the drivers will want to use the + Generic ScatterWalk in case the hardware needs to be fed + separate chunks of the scatterlist which contains the + plaintext and will contain the ciphertext. Please refer + to the ScatterWalk interface offered by the Linux kernel + scatter / gather list implementation. + </para> + </sect2> + </sect1> + + <sect1><title>Hashing [HASH]</title> + + <para> + Example of transformations: crc32, md5, sha1, sha256,... + </para> + + <sect2><title>Registering And Unregistering The Transformation</title> + + <para> + There are multiple ways to register a HASH transformation, + depending on whether the transformation is synchronous [SHASH] + or asynchronous [AHASH] and the amount of HASH transformations + we are registering. You can find the prototypes defined in + include/crypto/internal/hash.h: + </para> + + <programlisting> + int crypto_register_ahash(struct ahash_alg *alg); + + int crypto_register_shash(struct shash_alg *alg); + int crypto_register_shashes(struct shash_alg *algs, int count); + </programlisting> + + <para> + The respective counterparts for unregistering the HASH + transformation are as follows: + </para> + + <programlisting> + int crypto_unregister_ahash(struct ahash_alg *alg); + + int crypto_unregister_shash(struct shash_alg *alg); + int crypto_unregister_shashes(struct shash_alg *algs, int count); + </programlisting> + </sect2> + + <sect2><title>Cipher Definition With struct shash_alg and ahash_alg</title> + <para> + Here are schematics of how these functions are called when + operated from other part of the kernel. Note that the .setkey() + call might happen before or after any of these schematics happen, + but must not happen during any of these are in-flight. Please note + that calling .init() followed immediately by .finish() is also a + perfectly valid transformation. + </para> + + <programlisting> + I) DATA -----------. + v + .init() -> .update() -> .final() ! .update() might not be called + ^ | | at all in this scenario. + '----' '---> HASH + + II) DATA -----------.-----------. + v v + .init() -> .update() -> .finup() ! .update() may not be called + ^ | | at all in this scenario. + '----' '---> HASH + + III) DATA -----------. + v + .digest() ! The entire process is handled + | by the .digest() call. + '---------------> HASH + </programlisting> + + <para> + Here is a schematic of how the .export()/.import() functions are + called when used from another part of the kernel. + </para> + + <programlisting> + KEY--. DATA--. + v v ! .update() may not be called + .setkey() -> .init() -> .update() -> .export() at all in this scenario. + ^ | | + '-----' '--> PARTIAL_HASH + + ----------- other transformations happen here ----------- + + PARTIAL_HASH--. DATA1--. + v v + .import -> .update() -> .final() ! .update() may not be called + ^ | | at all in this scenario. + '----' '--> HASH1 + + PARTIAL_HASH--. DATA2-. + v v + .import -> .finup() + | + '---------------> HASH2 + </programlisting> + </sect2> + + <sect2><title>Specifics Of Asynchronous HASH Transformation</title> + <para> + Some of the drivers will want to use the Generic ScatterWalk + in case the implementation needs to be fed separate chunks of the + scatterlist which contains the input data. The buffer containing + the resulting hash will always be properly aligned to + .cra_alignmask so there is no need to worry about this. + </para> + </sect2> + </sect1> + </chapter> + + <chapter id="API"><title>Programming Interface</title> + <sect1><title>Block Cipher Context Data Structures</title> +!Pinclude/linux/crypto.h Block Cipher Context Data Structures +!Finclude/linux/crypto.h aead_request + </sect1> + <sect1><title>Block Cipher Algorithm Definitions</title> +!Pinclude/linux/crypto.h Block Cipher Algorithm Definitions +!Finclude/linux/crypto.h crypto_alg +!Finclude/linux/crypto.h ablkcipher_alg +!Finclude/linux/crypto.h aead_alg +!Finclude/linux/crypto.h blkcipher_alg +!Finclude/linux/crypto.h cipher_alg +!Finclude/linux/crypto.h rng_alg + </sect1> + <sect1><title>Asynchronous Block Cipher API</title> +!Pinclude/linux/crypto.h Asynchronous Block Cipher API +!Finclude/linux/crypto.h crypto_alloc_ablkcipher +!Finclude/linux/crypto.h crypto_free_ablkcipher +!Finclude/linux/crypto.h crypto_has_ablkcipher +!Finclude/linux/crypto.h crypto_ablkcipher_ivsize +!Finclude/linux/crypto.h crypto_ablkcipher_blocksize +!Finclude/linux/crypto.h crypto_ablkcipher_setkey +!Finclude/linux/crypto.h crypto_ablkcipher_reqtfm +!Finclude/linux/crypto.h crypto_ablkcipher_encrypt +!Finclude/linux/crypto.h crypto_ablkcipher_decrypt + </sect1> + <sect1><title>Asynchronous Cipher Request Handle</title> +!Pinclude/linux/crypto.h Asynchronous Cipher Request Handle +!Finclude/linux/crypto.h crypto_ablkcipher_reqsize +!Finclude/linux/crypto.h ablkcipher_request_set_tfm +!Finclude/linux/crypto.h ablkcipher_request_alloc +!Finclude/linux/crypto.h ablkcipher_request_free +!Finclude/linux/crypto.h ablkcipher_request_set_callback +!Finclude/linux/crypto.h ablkcipher_request_set_crypt + </sect1> + <sect1><title>Authenticated Encryption With Associated Data (AEAD) Cipher API</title> +!Pinclude/linux/crypto.h Authenticated Encryption With Associated Data (AEAD) Cipher API +!Finclude/linux/crypto.h crypto_alloc_aead +!Finclude/linux/crypto.h crypto_free_aead +!Finclude/linux/crypto.h crypto_aead_ivsize +!Finclude/linux/crypto.h crypto_aead_authsize +!Finclude/linux/crypto.h crypto_aead_blocksize +!Finclude/linux/crypto.h crypto_aead_setkey +!Finclude/linux/crypto.h crypto_aead_setauthsize +!Finclude/linux/crypto.h crypto_aead_encrypt +!Finclude/linux/crypto.h crypto_aead_decrypt + </sect1> + <sect1><title>Asynchronous AEAD Request Handle</title> +!Pinclude/linux/crypto.h Asynchronous AEAD Request Handle +!Finclude/linux/crypto.h crypto_aead_reqsize +!Finclude/linux/crypto.h aead_request_set_tfm +!Finclude/linux/crypto.h aead_request_alloc +!Finclude/linux/crypto.h aead_request_free +!Finclude/linux/crypto.h aead_request_set_callback +!Finclude/linux/crypto.h aead_request_set_crypt +!Finclude/linux/crypto.h aead_request_set_assoc + </sect1> + <sect1><title>Synchronous Block Cipher API</title> +!Pinclude/linux/crypto.h Synchronous Block Cipher API +!Finclude/linux/crypto.h crypto_alloc_blkcipher +!Finclude/linux/crypto.h crypto_free_blkcipher +!Finclude/linux/crypto.h crypto_has_blkcipher +!Finclude/linux/crypto.h crypto_blkcipher_name +!Finclude/linux/crypto.h crypto_blkcipher_ivsize +!Finclude/linux/crypto.h crypto_blkcipher_blocksize +!Finclude/linux/crypto.h crypto_blkcipher_setkey +!Finclude/linux/crypto.h crypto_blkcipher_encrypt +!Finclude/linux/crypto.h crypto_blkcipher_encrypt_iv +!Finclude/linux/crypto.h crypto_blkcipher_decrypt +!Finclude/linux/crypto.h crypto_blkcipher_decrypt_iv +!Finclude/linux/crypto.h crypto_blkcipher_set_iv +!Finclude/linux/crypto.h crypto_blkcipher_get_iv + </sect1> + <sect1><title>Single Block Cipher API</title> +!Pinclude/linux/crypto.h Single Block Cipher API +!Finclude/linux/crypto.h crypto_alloc_cipher +!Finclude/linux/crypto.h crypto_free_cipher +!Finclude/linux/crypto.h crypto_has_cipher +!Finclude/linux/crypto.h crypto_cipher_blocksize +!Finclude/linux/crypto.h crypto_cipher_setkey +!Finclude/linux/crypto.h crypto_cipher_encrypt_one +!Finclude/linux/crypto.h crypto_cipher_decrypt_one + </sect1> + <sect1><title>Synchronous Message Digest API</title> +!Pinclude/linux/crypto.h Synchronous Message Digest API +!Finclude/linux/crypto.h crypto_alloc_hash +!Finclude/linux/crypto.h crypto_free_hash +!Finclude/linux/crypto.h crypto_has_hash +!Finclude/linux/crypto.h crypto_hash_blocksize +!Finclude/linux/crypto.h crypto_hash_digestsize +!Finclude/linux/crypto.h crypto_hash_init +!Finclude/linux/crypto.h crypto_hash_update +!Finclude/linux/crypto.h crypto_hash_final +!Finclude/linux/crypto.h crypto_hash_digest +!Finclude/linux/crypto.h crypto_hash_setkey + </sect1> + <sect1><title>Message Digest Algorithm Definitions</title> +!Pinclude/crypto/hash.h Message Digest Algorithm Definitions +!Finclude/crypto/hash.h hash_alg_common +!Finclude/crypto/hash.h ahash_alg +!Finclude/crypto/hash.h shash_alg + </sect1> + <sect1><title>Asynchronous Message Digest API</title> +!Pinclude/crypto/hash.h Asynchronous Message Digest API +!Finclude/crypto/hash.h crypto_alloc_ahash +!Finclude/crypto/hash.h crypto_free_ahash +!Finclude/crypto/hash.h crypto_ahash_init +!Finclude/crypto/hash.h crypto_ahash_digestsize +!Finclude/crypto/hash.h crypto_ahash_reqtfm +!Finclude/crypto/hash.h crypto_ahash_reqsize +!Finclude/crypto/hash.h crypto_ahash_setkey +!Finclude/crypto/hash.h crypto_ahash_finup +!Finclude/crypto/hash.h crypto_ahash_final +!Finclude/crypto/hash.h crypto_ahash_digest +!Finclude/crypto/hash.h crypto_ahash_export +!Finclude/crypto/hash.h crypto_ahash_import + </sect1> + <sect1><title>Asynchronous Hash Request Handle</title> +!Pinclude/crypto/hash.h Asynchronous Hash Request Handle +!Finclude/crypto/hash.h ahash_request_set_tfm +!Finclude/crypto/hash.h ahash_request_alloc +!Finclude/crypto/hash.h ahash_request_free +!Finclude/crypto/hash.h ahash_request_set_callback +!Finclude/crypto/hash.h ahash_request_set_crypt + </sect1> + <sect1><title>Synchronous Message Digest API</title> +!Pinclude/crypto/hash.h Synchronous Message Digest API +!Finclude/crypto/hash.h crypto_alloc_shash +!Finclude/crypto/hash.h crypto_free_shash +!Finclude/crypto/hash.h crypto_shash_blocksize +!Finclude/crypto/hash.h crypto_shash_digestsize +!Finclude/crypto/hash.h crypto_shash_descsize +!Finclude/crypto/hash.h crypto_shash_setkey +!Finclude/crypto/hash.h crypto_shash_digest +!Finclude/crypto/hash.h crypto_shash_export +!Finclude/crypto/hash.h crypto_shash_import +!Finclude/crypto/hash.h crypto_shash_init +!Finclude/crypto/hash.h crypto_shash_update +!Finclude/crypto/hash.h crypto_shash_final +!Finclude/crypto/hash.h crypto_shash_finup + </sect1> + <sect1><title>Crypto API Random Number API</title> +!Pinclude/crypto/rng.h Random number generator API +!Finclude/crypto/rng.h crypto_alloc_rng +!Finclude/crypto/rng.h crypto_rng_alg +!Finclude/crypto/rng.h crypto_free_rng +!Finclude/crypto/rng.h crypto_rng_get_bytes +!Finclude/crypto/rng.h crypto_rng_reset +!Finclude/crypto/rng.h crypto_rng_seedsize +!Cinclude/crypto/rng.h + </sect1> + </chapter> + + <chapter id="Code"><title>Code Examples</title> + <sect1><title>Code Example For Asynchronous Block Cipher Operation</title> + <programlisting> + +struct tcrypt_result { + struct completion completion; + int err; +}; + +/* tie all data structures together */ +struct ablkcipher_def { + struct scatterlist sg; + struct crypto_ablkcipher *tfm; + struct ablkcipher_request *req; + struct tcrypt_result result; +}; + +/* Callback function */ +static void test_ablkcipher_cb(struct crypto_async_request *req, int error) +{ + struct tcrypt_result *result = req->data; + + if (error == -EINPROGRESS) + return; + result->err = error; + complete(&result->completion); + pr_info("Encryption finished successfully\n"); +} + +/* Perform cipher operation */ +static unsigned int test_ablkcipher_encdec(struct ablkcipher_def *ablk, + int enc) +{ + int rc = 0; + + if (enc) + rc = crypto_ablkcipher_encrypt(ablk->req); + else + rc = crypto_ablkcipher_decrypt(ablk->req); + + switch (rc) { + case 0: + break; + case -EINPROGRESS: + case -EBUSY: + rc = wait_for_completion_interruptible( + &ablk->result.completion); + if (!rc && !ablk->result.err) { + reinit_completion(&ablk->result.completion); + break; + } + default: + pr_info("ablkcipher encrypt returned with %d result %d\n", + rc, ablk->result.err); + break; + } + init_completion(&ablk->result.completion); + + return rc; +} + +/* Initialize and trigger cipher operation */ +static int test_ablkcipher(void) +{ + struct ablkcipher_def ablk; + struct crypto_ablkcipher *ablkcipher = NULL; + struct ablkcipher_request *req = NULL; + char *scratchpad = NULL; + char *ivdata = NULL; + unsigned char key[32]; + int ret = -EFAULT; + + ablkcipher = crypto_alloc_ablkcipher("cbc-aes-aesni", 0, 0); + if (IS_ERR(ablkcipher)) { + pr_info("could not allocate ablkcipher handle\n"); + return PTR_ERR(ablkcipher); + } + + req = ablkcipher_request_alloc(ablkcipher, GFP_KERNEL); + if (IS_ERR(req)) { + pr_info("could not allocate request queue\n"); + ret = PTR_ERR(req); + goto out; + } + + ablkcipher_request_set_callback(req, CRYPTO_TFM_REQ_MAY_BACKLOG, + test_ablkcipher_cb, + &ablk.result); + + /* AES 256 with random key */ + get_random_bytes(&key, 32); + if (crypto_ablkcipher_setkey(ablkcipher, key, 32)) { + pr_info("key could not be set\n"); + ret = -EAGAIN; + goto out; + } + + /* IV will be random */ + ivdata = kmalloc(16, GFP_KERNEL); + if (!ivdata) { + pr_info("could not allocate ivdata\n"); + goto out; + } + get_random_bytes(ivdata, 16); + + /* Input data will be random */ + scratchpad = kmalloc(16, GFP_KERNEL); + if (!scratchpad) { + pr_info("could not allocate scratchpad\n"); + goto out; + } + get_random_bytes(scratchpad, 16); + + ablk.tfm = ablkcipher; + ablk.req = req; + + /* We encrypt one block */ + sg_init_one(&ablk.sg, scratchpad, 16); + ablkcipher_request_set_crypt(req, &ablk.sg, &ablk.sg, 16, ivdata); + init_completion(&ablk.result.completion); + + /* encrypt data */ + ret = test_ablkcipher_encdec(&ablk, 1); + if (ret) + goto out; + + pr_info("Encryption triggered successfully\n"); + +out: + if (ablkcipher) + crypto_free_ablkcipher(ablkcipher); + if (req) + ablkcipher_request_free(req); + if (ivdata) + kfree(ivdata); + if (scratchpad) + kfree(scratchpad); + return ret; +} + </programlisting> + </sect1> + + <sect1><title>Code Example For Synchronous Block Cipher Operation</title> + <programlisting> + +static int test_blkcipher(void) +{ + struct crypto_blkcipher *blkcipher = NULL; + char *cipher = "cbc(aes)"; + // AES 128 + charkey = +"\x12\x34\x56\x78\x90\xab\xcd\xef\x12\x34\x56\x78\x90\xab\xcd\xef"; + chariv = +"\x12\x34\x56\x78\x90\xab\xcd\xef\x12\x34\x56\x78\x90\xab\xcd\xef"; + unsigned int ivsize = 0; + char *scratchpad = NULL; // holds plaintext and ciphertext + struct scatterlist sg; + struct blkcipher_desc desc; + int ret = -EFAULT; + + blkcipher = crypto_alloc_blkcipher(cipher, 0, 0); + if (IS_ERR(blkcipher)) { + printk("could not allocate blkcipher handle for %s\n", cipher); + return -PTR_ERR(blkcipher); + } + + if (crypto_blkcipher_setkey(blkcipher, key, strlen(key))) { + printk("key could not be set\n"); + ret = -EAGAIN; + goto out; + } + + ivsize = crypto_blkcipher_ivsize(blkcipher); + if (ivsize) { + if (ivsize != strlen(iv)) + printk("IV length differs from expected length\n"); + crypto_blkcipher_set_iv(blkcipher, iv, ivsize); + } + + scratchpad = kmalloc(crypto_blkcipher_blocksize(blkcipher), GFP_KERNEL); + if (!scratchpad) { + printk("could not allocate scratchpad for %s\n", cipher); + goto out; + } + /* get some random data that we want to encrypt */ + get_random_bytes(scratchpad, crypto_blkcipher_blocksize(blkcipher)); + + desc.flags = 0; + desc.tfm = blkcipher; + sg_init_one(&sg, scratchpad, crypto_blkcipher_blocksize(blkcipher)); + + /* encrypt data in place */ + crypto_blkcipher_encrypt(&desc, &sg, &sg, + crypto_blkcipher_blocksize(blkcipher)); + + /* decrypt data in place + * crypto_blkcipher_decrypt(&desc, &sg, &sg, + */ crypto_blkcipher_blocksize(blkcipher)); + + + printk("Cipher operation completed\n"); + return 0; + +out: + if (blkcipher) + crypto_free_blkcipher(blkcipher); + if (scratchpad) + kzfree(scratchpad); + return ret; +} + </programlisting> + </sect1> + + <sect1><title>Code Example For Use of Operational State Memory With SHASH</title> + <programlisting> + +struct sdesc { + struct shash_desc shash; + char ctx[]; +}; + +static struct sdescinit_sdesc(struct crypto_shash *alg) +{ + struct sdescsdesc; + int size; + + size = sizeof(struct shash_desc) + crypto_shash_descsize(alg); + sdesc = kmalloc(size, GFP_KERNEL); + if (!sdesc) + return ERR_PTR(-ENOMEM); + sdesc->shash.tfm = alg; + sdesc->shash.flags = 0x0; + return sdesc; +} + +static int calc_hash(struct crypto_shashalg, + const unsigned chardata, unsigned int datalen, + unsigned chardigest) { + struct sdescsdesc; + int ret; + + sdesc = init_sdesc(alg); + if (IS_ERR(sdesc)) { + pr_info("trusted_key: can't alloc %s\n", hash_alg); + return PTR_ERR(sdesc); + } + + ret = crypto_shash_digest(&sdesc->shash, data, datalen, digest); + kfree(sdesc); + return ret; +} + </programlisting> + </sect1> + + <sect1><title>Code Example For Random Number Generator Usage</title> + <programlisting> + +static int get_random_numbers(u8 *buf, unsigned int len) +{ + struct crypto_rngrng = NULL; + chardrbg = "drbg_nopr_sha256"; /* Hash DRBG with SHA-256, no PR */ + int ret; + + if (!buf || !len) { + pr_debug("No output buffer provided\n"); + return -EINVAL; + } + + rng = crypto_alloc_rng(drbg, 0, 0); + if (IS_ERR(rng)) { + pr_debug("could not allocate RNG handle for %s\n", drbg); + return -PTR_ERR(rng); + } + + ret = crypto_rng_get_bytes(rng, buf, len); + if (ret < 0) + pr_debug("generation of random numbers failed\n"); + else if (ret == 0) + pr_debug("RNG returned no data"); + else + pr_debug("RNG returned %d bytes of data\n", ret); + +out: + crypto_free_rng(rng); + return ret; +} + </programlisting> + </sect1> + </chapter> + </book> diff --git a/Documentation/DocBook/device-drivers.tmpl b/Documentation/DocBook/device-drivers.tmpl index f2130586ef5d..faf09d4a0ea8 100644 --- a/Documentation/DocBook/device-drivers.tmpl +++ b/Documentation/DocBook/device-drivers.tmpl @@ -190,23 +190,6 @@ X!Edrivers/pnp/system.c !Idrivers/message/fusion/mptfc.c !Idrivers/message/fusion/mptlan.c </sect1> - <sect1><title>I2O message devices</title> -!Iinclude/linux/i2o.h -!Idrivers/message/i2o/core.h -!Edrivers/message/i2o/iop.c -!Idrivers/message/i2o/iop.c -!Idrivers/message/i2o/config-osm.c -!Edrivers/message/i2o/exec-osm.c -!Idrivers/message/i2o/exec-osm.c -!Idrivers/message/i2o/bus-osm.c -!Edrivers/message/i2o/device.c -!Idrivers/message/i2o/device.c -!Idrivers/message/i2o/driver.c -!Idrivers/message/i2o/pci.c -!Idrivers/message/i2o/i2o_block.c -!Idrivers/message/i2o/i2o_scsi.c -!Idrivers/message/i2o/i2o_proc.c - </sect1> </chapter> <chapter id="snddev"> diff --git a/Documentation/DocBook/drm.tmpl b/Documentation/DocBook/drm.tmpl index be35bc328b77..03f1985a4bd1 100644 --- a/Documentation/DocBook/drm.tmpl +++ b/Documentation/DocBook/drm.tmpl @@ -239,6 +239,14 @@ Driver supports dedicated render nodes. </para></listitem> </varlistentry> + <varlistentry> + <term>DRIVER_ATOMIC</term> + <listitem><para> + Driver supports atomic properties. In this case the driver + must implement appropriate obj->atomic_get_property() vfuncs + for any modeset objects with driver specific properties. + </para></listitem> + </varlistentry> </variablelist> </sect3> <sect3> @@ -492,10 +500,10 @@ char *date;</synopsis> <sect2> <title>The Translation Table Manager (TTM)</title> <para> - TTM design background and information belongs here. + TTM design background and information belongs here. </para> <sect3> - <title>TTM initialization</title> + <title>TTM initialization</title> <warning><para>This section is outdated.</para></warning> <para> Drivers wishing to support TTM must fill out a drm_bo_driver @@ -503,42 +511,42 @@ char *date;</synopsis> pointers for initializing the TTM, allocating and freeing memory, waiting for command completion and fence synchronization, and memory migration. See the radeon_ttm.c file for an example of usage. - </para> - <para> - The ttm_global_reference structure is made up of several fields: - </para> - <programlisting> - struct ttm_global_reference { - enum ttm_global_types global_type; - size_t size; - void *object; - int (*init) (struct ttm_global_reference *); - void (*release) (struct ttm_global_reference *); - }; - </programlisting> - <para> - There should be one global reference structure for your memory - manager as a whole, and there will be others for each object - created by the memory manager at runtime. Your global TTM should - have a type of TTM_GLOBAL_TTM_MEM. The size field for the global - object should be sizeof(struct ttm_mem_global), and the init and - release hooks should point at your driver-specific init and - release routines, which probably eventually call - ttm_mem_global_init and ttm_mem_global_release, respectively. - </para> - <para> - Once your global TTM accounting structure is set up and initialized - by calling ttm_global_item_ref() on it, - you need to create a buffer object TTM to - provide a pool for buffer object allocation by clients and the - kernel itself. The type of this object should be TTM_GLOBAL_TTM_BO, - and its size should be sizeof(struct ttm_bo_global). Again, - driver-specific init and release functions may be provided, - likely eventually calling ttm_bo_global_init() and - ttm_bo_global_release(), respectively. Also, like the previous - object, ttm_global_item_ref() is used to create an initial reference - count for the TTM, which will call your initialization function. - </para> + </para> + <para> + The ttm_global_reference structure is made up of several fields: + </para> + <programlisting> + struct ttm_global_reference { + enum ttm_global_types global_type; + size_t size; + void *object; + int (*init) (struct ttm_global_reference *); + void (*release) (struct ttm_global_reference *); + }; + </programlisting> + <para> + There should be one global reference structure for your memory + manager as a whole, and there will be others for each object + created by the memory manager at runtime. Your global TTM should + have a type of TTM_GLOBAL_TTM_MEM. The size field for the global + object should be sizeof(struct ttm_mem_global), and the init and + release hooks should point at your driver-specific init and + release routines, which probably eventually call + ttm_mem_global_init and ttm_mem_global_release, respectively. + </para> + <para> + Once your global TTM accounting structure is set up and initialized + by calling ttm_global_item_ref() on it, + you need to create a buffer object TTM to + provide a pool for buffer object allocation by clients and the + kernel itself. The type of this object should be TTM_GLOBAL_TTM_BO, + and its size should be sizeof(struct ttm_bo_global). Again, + driver-specific init and release functions may be provided, + likely eventually calling ttm_bo_global_init() and + ttm_bo_global_release(), respectively. Also, like the previous + object, ttm_global_item_ref() is used to create an initial reference + count for the TTM, which will call your initialization function. + </para> </sect3> </sect2> <sect2 id="drm-gem"> @@ -566,19 +574,19 @@ char *date;</synopsis> using driver-specific ioctls. </para> <para> - On a fundamental level, GEM involves several operations: - <itemizedlist> - <listitem>Memory allocation and freeing</listitem> - <listitem>Command execution</listitem> - <listitem>Aperture management at command execution time</listitem> - </itemizedlist> - Buffer object allocation is relatively straightforward and largely + On a fundamental level, GEM involves several operations: + <itemizedlist> + <listitem>Memory allocation and freeing</listitem> + <listitem>Command execution</listitem> + <listitem>Aperture management at command execution time</listitem> + </itemizedlist> + Buffer object allocation is relatively straightforward and largely provided by Linux's shmem layer, which provides memory to back each object. </para> <para> Device-specific operations, such as command execution, pinning, buffer - read & write, mapping, and domain ownership transfers are left to + read & write, mapping, and domain ownership transfers are left to driver-specific ioctls. </para> <sect3> @@ -738,16 +746,16 @@ char *date;</synopsis> respectively. The conversion is handled by the DRM core without any driver-specific support. </para> - <para> - GEM also supports buffer sharing with dma-buf file descriptors through - PRIME. GEM-based drivers must use the provided helpers functions to - implement the exporting and importing correctly. See <xref linkend="drm-prime-support" />. - Since sharing file descriptors is inherently more secure than the - easily guessable and global GEM names it is the preferred buffer - sharing mechanism. Sharing buffers through GEM names is only supported - for legacy userspace. Furthermore PRIME also allows cross-device - buffer sharing since it is based on dma-bufs. - </para> + <para> + GEM also supports buffer sharing with dma-buf file descriptors through + PRIME. GEM-based drivers must use the provided helpers functions to + implement the exporting and importing correctly. See <xref linkend="drm-prime-support" />. + Since sharing file descriptors is inherently more secure than the + easily guessable and global GEM names it is the preferred buffer + sharing mechanism. Sharing buffers through GEM names is only supported + for legacy userspace. Furthermore PRIME also allows cross-device + buffer sharing since it is based on dma-bufs. + </para> </sect3> <sect3 id="drm-gem-objects-mapping"> <title>GEM Objects Mapping</title> @@ -852,7 +860,7 @@ char *date;</synopsis> <sect3> <title>Command Execution</title> <para> - Perhaps the most important GEM function for GPU devices is providing a + Perhaps the most important GEM function for GPU devices is providing a command execution interface to clients. Client programs construct command buffers containing references to previously allocated memory objects, and then submit them to GEM. At that point, GEM takes care to @@ -874,95 +882,101 @@ char *date;</synopsis> <title>GEM Function Reference</title> !Edrivers/gpu/drm/drm_gem.c </sect3> - </sect2> - <sect2> - <title>VMA Offset Manager</title> + </sect2> + <sect2> + <title>VMA Offset Manager</title> !Pdrivers/gpu/drm/drm_vma_manager.c vma offset manager !Edrivers/gpu/drm/drm_vma_manager.c !Iinclude/drm/drm_vma_manager.h - </sect2> - <sect2 id="drm-prime-support"> - <title>PRIME Buffer Sharing</title> - <para> - PRIME is the cross device buffer sharing framework in drm, originally - created for the OPTIMUS range of multi-gpu platforms. To userspace - PRIME buffers are dma-buf based file descriptors. - </para> - <sect3> - <title>Overview and Driver Interface</title> - <para> - Similar to GEM global names, PRIME file descriptors are - also used to share buffer objects across processes. They offer - additional security: as file descriptors must be explicitly sent over - UNIX domain sockets to be shared between applications, they can't be - guessed like the globally unique GEM names. - </para> - <para> - Drivers that support the PRIME - API must set the DRIVER_PRIME bit in the struct - <structname>drm_driver</structname> - <structfield>driver_features</structfield> field, and implement the - <methodname>prime_handle_to_fd</methodname> and - <methodname>prime_fd_to_handle</methodname> operations. - </para> - <para> - <synopsis>int (*prime_handle_to_fd)(struct drm_device *dev, - struct drm_file *file_priv, uint32_t handle, - uint32_t flags, int *prime_fd); + </sect2> + <sect2 id="drm-prime-support"> + <title>PRIME Buffer Sharing</title> + <para> + PRIME is the cross device buffer sharing framework in drm, originally + created for the OPTIMUS range of multi-gpu platforms. To userspace + PRIME buffers are dma-buf based file descriptors. + </para> + <sect3> + <title>Overview and Driver Interface</title> + <para> + Similar to GEM global names, PRIME file descriptors are + also used to share buffer objects across processes. They offer + additional security: as file descriptors must be explicitly sent over + UNIX domain sockets to be shared between applications, they can't be + guessed like the globally unique GEM names. + </para> + <para> + Drivers that support the PRIME + API must set the DRIVER_PRIME bit in the struct + <structname>drm_driver</structname> + <structfield>driver_features</structfield> field, and implement the + <methodname>prime_handle_to_fd</methodname> and + <methodname>prime_fd_to_handle</methodname> operations. + </para> + <para> + <synopsis>int (*prime_handle_to_fd)(struct drm_device *dev, + struct drm_file *file_priv, uint32_t handle, + uint32_t flags, int *prime_fd); int (*prime_fd_to_handle)(struct drm_device *dev, - struct drm_file *file_priv, int prime_fd, - uint32_t *handle);</synopsis> - Those two operations convert a handle to a PRIME file descriptor and - vice versa. Drivers must use the kernel dma-buf buffer sharing framework - to manage the PRIME file descriptors. Similar to the mode setting - API PRIME is agnostic to the underlying buffer object manager, as - long as handles are 32bit unsigned integers. - </para> - <para> - While non-GEM drivers must implement the operations themselves, GEM - drivers must use the <function>drm_gem_prime_handle_to_fd</function> - and <function>drm_gem_prime_fd_to_handle</function> helper functions. - Those helpers rely on the driver - <methodname>gem_prime_export</methodname> and - <methodname>gem_prime_import</methodname> operations to create a dma-buf - instance from a GEM object (dma-buf exporter role) and to create a GEM - object from a dma-buf instance (dma-buf importer role). - </para> - <para> - <synopsis>struct dma_buf * (*gem_prime_export)(struct drm_device *dev, - struct drm_gem_object *obj, - int flags); + struct drm_file *file_priv, int prime_fd, + uint32_t *handle);</synopsis> + Those two operations convert a handle to a PRIME file descriptor and + vice versa. Drivers must use the kernel dma-buf buffer sharing framework + to manage the PRIME file descriptors. Similar to the mode setting + API PRIME is agnostic to the underlying buffer object manager, as + long as handles are 32bit unsigned integers. + </para> + <para> + While non-GEM drivers must implement the operations themselves, GEM + drivers must use the <function>drm_gem_prime_handle_to_fd</function> + and <function>drm_gem_prime_fd_to_handle</function> helper functions. + Those helpers rely on the driver + <methodname>gem_prime_export</methodname> and + <methodname>gem_prime_import</methodname> operations to create a dma-buf + instance from a GEM object (dma-buf exporter role) and to create a GEM + object from a dma-buf instance (dma-buf importer role). + </para> + <para> + <synopsis>struct dma_buf * (*gem_prime_export)(struct drm_device *dev, + struct drm_gem_object *obj, + int flags); struct drm_gem_object * (*gem_prime_import)(struct drm_device *dev, - struct dma_buf *dma_buf);</synopsis> - These two operations are mandatory for GEM drivers that support - PRIME. - </para> - </sect3> - <sect3> - <title>PRIME Helper Functions</title> -!Pdrivers/gpu/drm/drm_prime.c PRIME Helpers + struct dma_buf *dma_buf);</synopsis> + These two operations are mandatory for GEM drivers that support + PRIME. + </para> </sect3> - </sect2> - <sect2> - <title>PRIME Function References</title> + <sect3> + <title>PRIME Helper Functions</title> +!Pdrivers/gpu/drm/drm_prime.c PRIME Helpers + </sect3> + </sect2> + <sect2> + <title>PRIME Function References</title> !Edrivers/gpu/drm/drm_prime.c - </sect2> - <sect2> - <title>DRM MM Range Allocator</title> - <sect3> - <title>Overview</title> + </sect2> + <sect2> + <title>DRM MM Range Allocator</title> + <sect3> + <title>Overview</title> !Pdrivers/gpu/drm/drm_mm.c Overview - </sect3> - <sect3> - <title>LRU Scan/Eviction Support</title> + </sect3> + <sect3> + <title>LRU Scan/Eviction Support</title> !Pdrivers/gpu/drm/drm_mm.c lru scan roaster - </sect3> + </sect3> </sect2> - <sect2> - <title>DRM MM Range Allocator Function References</title> + <sect2> + <title>DRM MM Range Allocator Function References</title> !Edrivers/gpu/drm/drm_mm.c !Iinclude/drm/drm_mm.h - </sect2> + </sect2> + <sect2> + <title>CMA Helper Functions Reference</title> +!Pdrivers/gpu/drm/drm_gem_cma_helper.c cma helpers +!Edrivers/gpu/drm/drm_gem_cma_helper.c +!Iinclude/drm/drm_gem_cma_helper.h + </sect2> </sect1> <!-- Internals: mode setting --> @@ -996,6 +1010,10 @@ int max_width, max_height;</synopsis> !Edrivers/gpu/drm/drm_modes.c </sect2> <sect2> + <title>Atomic Mode Setting Function Reference</title> +!Edrivers/gpu/drm/drm_atomic.c + </sect2> + <sect2> <title>Frame Buffer Creation</title> <synopsis>struct drm_framebuffer *(*fb_create)(struct drm_device *dev, struct drm_file *file_priv, @@ -1367,7 +1385,7 @@ int max_width, max_height;</synopsis> <itemizedlist> <listitem> DRM_PLANE_TYPE_PRIMARY represents a "main" plane for a CRTC. Primary - planes are the planes operated upon by by CRTC modesetting and flipping + planes are the planes operated upon by CRTC modesetting and flipping operations described in <xref linkend="drm-kms-crtcops"/>. </listitem> <listitem> @@ -1827,6 +1845,10 @@ void intel_crt_init(struct drm_device *dev) !Edrivers/gpu/drm/drm_crtc.c </sect2> <sect2> + <title>KMS Data Structures</title> +!Iinclude/drm/drm_crtc.h + </sect2> + <sect2> <title>KMS Locking</title> !Pdrivers/gpu/drm/drm_modeset_lock.c kms locking !Iinclude/drm/drm_modeset_lock.h @@ -1933,10 +1955,16 @@ void intel_crt_init(struct drm_device *dev) and then retrieves a list of modes by calling the connector <methodname>get_modes</methodname> helper operation. </para> + <para> + If the helper operation returns no mode, and if the connector status + is connector_status_connected, standard VESA DMT modes up to + 1024x768 are automatically added to the modes list by a call to + <function>drm_add_modes_noedid</function>. + </para> <para> - The function filters out modes larger than + The function then filters out modes larger than <parameter>max_width</parameter> and <parameter>max_height</parameter> - if specified. It then calls the optional connector + if specified. It finally calls the optional connector <methodname>mode_valid</methodname> helper operation for each mode in the probed list to check whether the mode is valid for the connector. </para> @@ -2076,12 +2104,20 @@ void intel_crt_init(struct drm_device *dev) <synopsis>int (*get_modes)(struct drm_connector *connector);</synopsis> <para> Fill the connector's <structfield>probed_modes</structfield> list - by parsing EDID data with <function>drm_add_edid_modes</function> or - calling <function>drm_mode_probed_add</function> directly for every + by parsing EDID data with <function>drm_add_edid_modes</function>, + adding standard VESA DMT modes with <function>drm_add_modes_noedid</function>, + or calling <function>drm_mode_probed_add</function> directly for every supported mode and return the number of modes it has detected. This operation is mandatory. </para> <para> + Note that the caller function will automatically add standard VESA + DMT modes up to 1024x768 if the <methodname>get_modes</methodname> + helper operation returns no mode and if the connector status is + connector_status_connected. There is no need to call + <function>drm_add_edid_modes</function> manually in that case. + </para> + <para> When adding modes manually the driver creates each mode with a call to <function>drm_mode_create</function> and must fill the following fields. <itemizedlist> @@ -2278,7 +2314,7 @@ void intel_crt_init(struct drm_device *dev) <function>drm_helper_probe_single_connector_modes</function>. </para> <para> - When parsing EDID data, <function>drm_add_edid_modes</function> fill the + When parsing EDID data, <function>drm_add_edid_modes</function> fills the connector <structfield>display_info</structfield> <structfield>width_mm</structfield> and <structfield>height_mm</structfield> fields. When creating modes @@ -2316,8 +2352,27 @@ void intel_crt_init(struct drm_device *dev) </itemizedlist> </sect2> <sect2> + <title>Atomic Modeset Helper Functions Reference</title> + <sect3> + <title>Overview</title> +!Pdrivers/gpu/drm/drm_atomic_helper.c overview + </sect3> + <sect3> + <title>Implementing Asynchronous Atomic Commit</title> +!Pdrivers/gpu/drm/drm_atomic_helper.c implementing async commit + </sect3> + <sect3> + <title>Atomic State Reset and Initialization</title> +!Pdrivers/gpu/drm/drm_atomic_helper.c atomic state reset and initialization + </sect3> +!Iinclude/drm/drm_atomic_helper.h +!Edrivers/gpu/drm/drm_atomic_helper.c + </sect2> + <sect2> <title>Modeset Helper Functions Reference</title> +!Iinclude/drm/drm_crtc_helper.h !Edrivers/gpu/drm/drm_crtc_helper.c +!Pdrivers/gpu/drm/drm_crtc_helper.c overview </sect2> <sect2> <title>Output Probing Helper Functions Reference</title> @@ -2343,6 +2398,12 @@ void intel_crt_init(struct drm_device *dev) !Edrivers/gpu/drm/drm_dp_mst_topology.c </sect2> <sect2> + <title>MIPI DSI Helper Functions Reference</title> +!Pdrivers/gpu/drm/drm_mipi_dsi.c dsi helpers +!Iinclude/drm/drm_mipi_dsi.h +!Edrivers/gpu/drm/drm_mipi_dsi.c + </sect2> + <sect2> <title>EDID Helper Functions Reference</title> !Edrivers/gpu/drm/drm_edid.c </sect2> @@ -2371,7 +2432,12 @@ void intel_crt_init(struct drm_device *dev) </sect2> <sect2> <title id="drm-kms-planehelpers">Plane Helper Reference</title> -!Edrivers/gpu/drm/drm_plane_helper.c Plane Helpers +!Edrivers/gpu/drm/drm_plane_helper.c +!Pdrivers/gpu/drm/drm_plane_helper.c overview + </sect2> + <sect2> + <title>Tile group</title> +!Pdrivers/gpu/drm/drm_crtc.c Tile group </sect2> </sect1> @@ -2507,8 +2573,8 @@ void intel_crt_init(struct drm_device *dev) <td valign="top" >Description/Restrictions</td> </tr> <tr> - <td rowspan="21" valign="top" >DRM</td> - <td rowspan="2" valign="top" >Generic</td> + <td rowspan="36" valign="top" >DRM</td> + <td rowspan="5" valign="top" >Connector</td> <td valign="top" >“EDID”</td> <td valign="top" >BLOB | IMMUTABLE</td> <td valign="top" >0</td> @@ -2523,7 +2589,28 @@ void intel_crt_init(struct drm_device *dev) <td valign="top" >Contains DPMS operation mode value.</td> </tr> <tr> - <td rowspan="1" valign="top" >Plane</td> + <td valign="top" >“PATH”</td> + <td valign="top" >BLOB | IMMUTABLE</td> + <td valign="top" >0</td> + <td valign="top" >Connector</td> + <td valign="top" >Contains topology path to a connector.</td> + </tr> + <tr> + <td valign="top" >“TILE”</td> + <td valign="top" >BLOB | IMMUTABLE</td> + <td valign="top" >0</td> + <td valign="top" >Connector</td> + <td valign="top" >Contains tiling information for a connector.</td> + </tr> + <tr> + <td valign="top" >“CRTC_ID”</td> + <td valign="top" >OBJECT</td> + <td valign="top" >DRM_MODE_OBJECT_CRTC</td> + <td valign="top" >Connector</td> + <td valign="top" >CRTC that connector is attached to (atomic)</td> + </tr> + <tr> + <td rowspan="11" valign="top" >Plane</td> <td valign="top" >“type”</td> <td valign="top" >ENUM | IMMUTABLE</td> <td valign="top" >{ "Overlay", "Primary", "Cursor" }</td> @@ -2531,6 +2618,76 @@ void intel_crt_init(struct drm_device *dev) <td valign="top" >Plane type</td> </tr> <tr> + <td valign="top" >“SRC_X”</td> + <td valign="top" >RANGE</td> + <td valign="top" >Min=0, Max=UINT_MAX</td> + <td valign="top" >Plane</td> + <td valign="top" >Scanout source x coordinate in 16.16 fixed point (atomic)</td> + </tr> + <tr> + <td valign="top" >“SRC_Y”</td> + <td valign="top" >RANGE</td> + <td valign="top" >Min=0, Max=UINT_MAX</td> + <td valign="top" >Plane</td> + <td valign="top" >Scanout source y coordinate in 16.16 fixed point (atomic)</td> + </tr> + <tr> + <td valign="top" >“SRC_W”</td> + <td valign="top" >RANGE</td> + <td valign="top" >Min=0, Max=UINT_MAX</td> + <td valign="top" >Plane</td> + <td valign="top" >Scanout source width in 16.16 fixed point (atomic)</td> + </tr> + <tr> + <td valign="top" >“SRC_H”</td> + <td valign="top" >RANGE</td> + <td valign="top" >Min=0, Max=UINT_MAX</td> + <td valign="top" >Plane</td> + <td valign="top" >Scanout source height in 16.16 fixed point (atomic)</td> + </tr> + <tr> + <td valign="top" >“CRTC_X”</td> + <td valign="top" >SIGNED_RANGE</td> + <td valign="top" >Min=INT_MIN, Max=INT_MAX</td> + <td valign="top" >Plane</td> + <td valign="top" >Scanout CRTC (destination) x coordinate (atomic)</td> + </tr> + <tr> + <td valign="top" >“CRTC_Y”</td> + <td valign="top" >SIGNED_RANGE</td> + <td valign="top" >Min=INT_MIN, Max=INT_MAX</td> + <td valign="top" >Plane</td> + <td valign="top" >Scanout CRTC (destination) y coordinate (atomic)</td> + </tr> + <tr> + <td valign="top" >“CRTC_W”</td> + <td valign="top" >RANGE</td> + <td valign="top" >Min=0, Max=UINT_MAX</td> + <td valign="top" >Plane</td> + <td valign="top" >Scanout CRTC (destination) width (atomic)</td> + </tr> + <tr> + <td valign="top" >“CRTC_H”</td> + <td valign="top" >RANGE</td> + <td valign="top" >Min=0, Max=UINT_MAX</td> + <td valign="top" >Plane</td> + <td valign="top" >Scanout CRTC (destination) height (atomic)</td> + </tr> + <tr> + <td valign="top" >“FB_ID”</td> + <td valign="top" >OBJECT</td> + <td valign="top" >DRM_MODE_OBJECT_FB</td> + <td valign="top" >Plane</td> + <td valign="top" >Scanout framebuffer (atomic)</td> + </tr> + <tr> + <td valign="top" >“CRTC_ID”</td> + <td valign="top" >OBJECT</td> + <td valign="top" >DRM_MODE_OBJECT_CRTC</td> + <td valign="top" >Plane</td> + <td valign="top" >CRTC that plane is attached to (atomic)</td> + </tr> + <tr> <td rowspan="2" valign="top" >DVI-I</td> <td valign="top" >“subconnector”</td> <td valign="top" >ENUM</td> @@ -2638,6 +2795,21 @@ void intel_crt_init(struct drm_device *dev) <td valign="top" >TBD</td> </tr> <tr> + <td rowspan="2" valign="top" >Virtual GPU</td> + <td valign="top" >“suggested X”</td> + <td valign="top" >RANGE</td> + <td valign="top" >Min=0, Max=0xffffffff</td> + <td valign="top" >Connector</td> + <td valign="top" >property to suggest an X offset for a connector</td> + </tr> + <tr> + <td valign="top" >“suggested Y”</td> + <td valign="top" >RANGE</td> + <td valign="top" >Min=0, Max=0xffffffff</td> + <td valign="top" >Connector</td> + <td valign="top" >property to suggest an Y offset for a connector</td> + </tr> + <tr> <td rowspan="3" valign="top" >Optional</td> <td valign="top" >“scaling mode”</td> <td valign="top" >ENUM</td> @@ -3788,6 +3960,27 @@ int num_ioctls;</synopsis> those have basic support through the gma500 drm driver. </para> <sect1> + <title>Core Driver Infrastructure</title> + <para> + This section covers core driver infrastructure used by both the display + and the GEM parts of the driver. + </para> + <sect2> + <title>Runtime Power Management</title> +!Pdrivers/gpu/drm/i915/intel_runtime_pm.c runtime pm +!Idrivers/gpu/drm/i915/intel_runtime_pm.c +!Idrivers/gpu/drm/i915/intel_uncore.c + </sect2> + <sect2> + <title>Interrupt Handling</title> +!Pdrivers/gpu/drm/i915/i915_irq.c interrupt handling +!Fdrivers/gpu/drm/i915/i915_irq.c intel_irq_init intel_irq_init_hw intel_hpd_init +!Fdrivers/gpu/drm/i915/i915_irq.c intel_irq_fini +!Fdrivers/gpu/drm/i915/i915_irq.c intel_runtime_pm_disable_interrupts +!Fdrivers/gpu/drm/i915/i915_irq.c intel_runtime_pm_enable_interrupts + </sect2> + </sect1> + <sect1> <title>Display Hardware Handling</title> <para> This section covers everything related to the display hardware including @@ -3804,6 +3997,18 @@ int num_ioctls;</synopsis> </para> </sect2> <sect2> + <title>Frontbuffer Tracking</title> +!Pdrivers/gpu/drm/i915/intel_frontbuffer.c frontbuffer tracking +!Idrivers/gpu/drm/i915/intel_frontbuffer.c +!Fdrivers/gpu/drm/i915/intel_drv.h intel_frontbuffer_flip +!Fdrivers/gpu/drm/i915/i915_gem.c i915_gem_track_fb + </sect2> + <sect2> + <title>Display FIFO Underrun Reporting</title> +!Pdrivers/gpu/drm/i915/intel_fifo_underrun.c fifo underrun handling +!Idrivers/gpu/drm/i915/intel_fifo_underrun.c + </sect2> + <sect2> <title>Plane Configuration</title> <para> This section covers plane configuration and composition with the @@ -3814,6 +4019,11 @@ int num_ioctls;</synopsis> </para> </sect2> <sect2> + <title>Atomic Plane Helpers</title> +!Pdrivers/gpu/drm/i915/intel_atomic_plane.c atomic plane helpers +!Idrivers/gpu/drm/i915/intel_atomic_plane.c + </sect2> + <sect2> <title>Output Probing</title> <para> This section covers output probing and related infrastructure like the @@ -3823,6 +4033,21 @@ int num_ioctls;</synopsis> </para> </sect2> <sect2> + <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 + </sect2> + <sect2> + <title>Panel Self Refresh PSR (PSR/SRD)</title> +!Pdrivers/gpu/drm/i915/intel_psr.c Panel Self Refresh (PSR/SRD) +!Idrivers/gpu/drm/i915/intel_psr.c + </sect2> + <sect2> + <title>Frame Buffer Compression (FBC)</title> +!Pdrivers/gpu/drm/i915/intel_fbc.c Frame Buffer Compression (FBC) +!Idrivers/gpu/drm/i915/intel_fbc.c + </sect2> + <sect2> <title>DPIO</title> !Pdrivers/gpu/drm/i915/i915_reg.h DPIO <table id="dpiox2"> @@ -3926,11 +4151,54 @@ int num_ioctls;</synopsis> !Idrivers/gpu/drm/i915/i915_cmd_parser.c </sect2> <sect2> + <title>Batchbuffer Pools</title> +!Pdrivers/gpu/drm/i915/i915_gem_batch_pool.c batch pool +!Idrivers/gpu/drm/i915/i915_gem_batch_pool.c + </sect2> + <sect2> <title>Logical Rings, Logical Ring Contexts and Execlists</title> !Pdrivers/gpu/drm/i915/intel_lrc.c Logical Rings, Logical Ring Contexts and Execlists !Idrivers/gpu/drm/i915/intel_lrc.c </sect2> + <sect2> + <title>Global GTT views</title> +!Pdrivers/gpu/drm/i915/i915_gem_gtt.c Global GTT views +!Idrivers/gpu/drm/i915/i915_gem_gtt.c + </sect2> + <sect2> + <title>Buffer Object Eviction</title> + <para> + This section documents the interface function for evicting buffer + objects to make space available in the virtual gpu address spaces. + Note that this is mostly orthogonal to shrinking buffer objects + caches, which has the goal to make main memory (shared with the gpu + through the unified memory architecture) available. + </para> +!Idrivers/gpu/drm/i915/i915_gem_evict.c + </sect2> </sect1> + + <sect1> + <title> Tracing </title> + <para> + This sections covers all things related to the tracepoints implemented in + the i915 driver. + </para> + <sect2> + <title> i915_ppgtt_create and i915_ppgtt_release </title> +!Pdrivers/gpu/drm/i915/i915_trace.h i915_ppgtt_create and i915_ppgtt_release tracepoints + </sect2> + <sect2> + <title> i915_context_create and i915_context_free </title> +!Pdrivers/gpu/drm/i915/i915_trace.h i915_context_create and i915_context_free tracepoints + </sect2> + <sect2> + <title> switch_mm </title> +!Pdrivers/gpu/drm/i915/i915_trace.h switch_mm tracepoint + </sect2> + </sect1> + </chapter> +!Cdrivers/gpu/drm/i915/i915_irq.c </part> </book> diff --git a/Documentation/DocBook/kgdb.tmpl b/Documentation/DocBook/kgdb.tmpl index f77358f96930..2428cc04dbc8 100644 --- a/Documentation/DocBook/kgdb.tmpl +++ b/Documentation/DocBook/kgdb.tmpl @@ -75,7 +75,7 @@ a development machine and the other is the target machine. The kernel to be debugged runs on the target machine. The development machine runs an instance of gdb against the vmlinux file which - contains the symbols (not boot image such as bzImage, zImage, + contains the symbols (not a boot image such as bzImage, zImage, uImage...). In gdb the developer specifies the connection parameters and connects to kgdb. The type of connection a developer makes with gdb depends on the availability of kgdb I/O @@ -95,7 +95,7 @@ <title>Kernel config options for kgdb</title> <para> To enable <symbol>CONFIG_KGDB</symbol> you should look under - "Kernel debugging" and select "KGDB: kernel debugger". + "Kernel hacking" / "Kernel debugging" and select "KGDB: kernel debugger". </para> <para> While it is not a hard requirement that you have symbols in your @@ -105,7 +105,7 @@ kernel with debug info" in the config menu. </para> <para> - It is advised, but not required that you turn on the + It is advised, but not required, that you turn on the <symbol>CONFIG_FRAME_POINTER</symbol> kernel option which is called "Compile the kernel with frame pointers" in the config menu. This option inserts code to into the compiled executable which saves the frame @@ -181,7 +181,7 @@ <para>This section describes the various runtime kernel parameters that affect the configuration of the kernel debugger. The following chapter covers using kdb and kgdb as well as - provides some examples of the configuration parameters.</para> + providing some examples of the configuration parameters.</para> <sect1 id="kgdboc"> <title>Kernel parameter: kgdboc</title> <para>The kgdboc driver was originally an abbreviation meant to @@ -219,8 +219,8 @@ <listitem><para>kbd = Keyboard</para></listitem> </itemizedlist> </para> - <para>You can configure kgdboc to use the keyboard, and or a serial - device depending on if you are using kdb and or kgdb, in one of the + <para>You can configure kgdboc to use the keyboard, and/or a serial + device depending on if you are using kdb and/or kgdb, in one of the following scenarios. The order listed above must be observed if you use any of the optional configurations together. Using kms + only gdb is generally not a useful combination.</para> @@ -261,11 +261,8 @@ </sect3> <sect3 id="kgdbocArgs3"> <title>More examples</title> - <para>You can configure kgdboc to use the keyboard, and or a serial - device depending on if you are using kdb and or kgdb, in one of the - following scenarios.</para> - <para>You can configure kgdboc to use the keyboard, and or a serial device - depending on if you are using kdb and or kgdb, in one of the + <para>You can configure kgdboc to use the keyboard, and/or a serial device + depending on if you are using kdb and/or kgdb, in one of the following scenarios. <orderedlist> <listitem><para>kdb and kgdb over only a serial port</para> @@ -315,7 +312,7 @@ <para> The Kernel command line option <constant>kgdbwait</constant> makes kgdb wait for a debugger connection during booting of a kernel. You - can only use this option you compiled a kgdb I/O driver into the + can only use this option if you compiled a kgdb I/O driver into the kernel and you specified the I/O driver configuration as a kernel command line option. The kgdbwait parameter should always follow the configuration parameter for the kgdb I/O driver in the kernel @@ -354,7 +351,7 @@ </listitem> </orderedlist> <para>IMPORTANT NOTE: You cannot use kgdboc + kgdbcon on a tty that is an - active system console. An example incorrect usage is <constant>console=ttyS0,115200 kgdboc=ttyS0 kgdbcon</constant> + active system console. An example of incorrect usage is <constant>console=ttyS0,115200 kgdboc=ttyS0 kgdbcon</constant> </para> <para>It is possible to use this option with kgdboc on a tty that is not a system console. </para> @@ -386,12 +383,12 @@ <title>Quick start for kdb on a serial port</title> <para>This is a quick example of how to use kdb.</para> <para><orderedlist> - <listitem><para>Boot kernel with arguments: + <listitem><para>Configure kgdboc at boot using kernel parameters: <itemizedlist> <listitem><para><constant>console=ttyS0,115200 kgdboc=ttyS0,115200</constant></para></listitem> </itemizedlist></para> <para>OR</para> - <para>Configure kgdboc after the kernel booted; assuming you are using a serial port console: + <para>Configure kgdboc after the kernel has booted; assuming you are using a serial port console: <itemizedlist> <listitem><para><constant>echo ttyS0 > /sys/module/kgdboc/parameters/kgdboc</constant></para></listitem> </itemizedlist> @@ -442,12 +439,12 @@ <title>Quick start for kdb using a keyboard connected console</title> <para>This is a quick example of how to use kdb with a keyboard.</para> <para><orderedlist> - <listitem><para>Boot kernel with arguments: + <listitem><para>Configure kgdboc at boot using kernel parameters: <itemizedlist> <listitem><para><constant>kgdboc=kbd</constant></para></listitem> </itemizedlist></para> <para>OR</para> - <para>Configure kgdboc after the kernel booted: + <para>Configure kgdboc after the kernel has booted: <itemizedlist> <listitem><para><constant>echo kbd > /sys/module/kgdboc/parameters/kgdboc</constant></para></listitem> </itemizedlist> @@ -501,12 +498,12 @@ <title>Connecting with gdb to a serial port</title> <orderedlist> <listitem><para>Configure kgdboc</para> - <para>Boot kernel with arguments: + <para>Configure kgdboc at boot using kernel parameters: <itemizedlist> <listitem><para><constant>kgdboc=ttyS0,115200</constant></para></listitem> </itemizedlist></para> <para>OR</para> - <para>Configure kgdboc after the kernel booted: + <para>Configure kgdboc after the kernel has booted: <itemizedlist> <listitem><para><constant>echo ttyS0 > /sys/module/kgdboc/parameters/kgdboc</constant></para></listitem> </itemizedlist></para> @@ -536,7 +533,7 @@ </para> </listitem> <listitem> - <para>Connect from from gdb</para> + <para>Connect from gdb</para> <para> Example (using a directly connected port): </para> @@ -584,7 +581,7 @@ <para> There are two ways to switch from kgdb to kdb: you can use gdb to issue a maintenance packet, or you can blindly type the command $3#33. - Whenever kernel debugger stops in kgdb mode it will print the + Whenever the kernel debugger stops in kgdb mode it will print the message <constant>KGDB or $3#33 for KDB</constant>. It is important to note that you have to type the sequence correctly in one pass. You cannot type a backspace or delete because kgdb will interpret @@ -704,7 +701,7 @@ Task Addr Pid Parent [*] cpu State Thread Command <listitem><para>Registration and unregistration of architecture specific trap hooks</para></listitem> <listitem><para>Any special exception handling and cleanup</para></listitem> <listitem><para>NMI exception handling and cleanup</para></listitem> - <listitem><para>(optional)HW breakpoints</para></listitem> + <listitem><para>(optional) HW breakpoints</para></listitem> </itemizedlist> </para> </listitem> @@ -760,7 +757,7 @@ Task Addr Pid Parent [*] cpu State Thread Command a kgdb I/O driver for characters when it needs input. The I/O driver is expected to return immediately if there is no data available. Doing so allows for the future possibility to touch - watch dog hardware in such a way as to have a target system not + watchdog hardware in such a way as to have a target system not reset when these are enabled. </para> </listitem> @@ -779,21 +776,25 @@ Task Addr Pid Parent [*] cpu State Thread Command their <asm/kgdb.h> file. These are: <itemizedlist> <listitem> - <para> - NUMREGBYTES: The size in bytes of all of the registers, so - that we can ensure they will all fit into a packet. - </para> - <para> - BUFMAX: The size in bytes of the buffer GDB will read into. - This must be larger than NUMREGBYTES. - </para> - <para> - CACHE_FLUSH_IS_SAFE: Set to 1 if it is always safe to call - flush_cache_range or flush_icache_range. On some architectures, - these functions may not be safe to call on SMP since we keep other - CPUs in a holding pattern. - </para> - </listitem> + <para> + NUMREGBYTES: The size in bytes of all of the registers, so + that we can ensure they will all fit into a packet. + </para> + </listitem> + <listitem> + <para> + BUFMAX: The size in bytes of the buffer GDB will read into. + This must be larger than NUMREGBYTES. + </para> + </listitem> + <listitem> + <para> + CACHE_FLUSH_IS_SAFE: Set to 1 if it is always safe to call + flush_cache_range or flush_icache_range. On some architectures, + these functions may not be safe to call on SMP since we keep other + CPUs in a holding pattern. + </para> + </listitem> </itemizedlist> </para> <para> @@ -812,8 +813,8 @@ Task Addr Pid Parent [*] cpu State Thread Command <para> The kgdboc driver is actually a very thin driver that relies on the underlying low level to the hardware driver having "polling hooks" - which the to which the tty driver is attached. In the initial - implementation of kgdboc it the serial_core was changed to expose a + to which the tty driver is attached. In the initial + implementation of kgdboc the serial_core was changed to expose a low level UART hook for doing polled mode reading and writing of a single character while in an atomic context. When kgdb makes an I/O request to the debugger, kgdboc invokes a callback in the serial diff --git a/Documentation/DocBook/media/dvb/dvbproperty.xml b/Documentation/DocBook/media/dvb/dvbproperty.xml index 948ddaab592e..3018564ddfd9 100644 --- a/Documentation/DocBook/media/dvb/dvbproperty.xml +++ b/Documentation/DocBook/media/dvb/dvbproperty.xml @@ -120,8 +120,8 @@ struct dtv_properties { </para> <informaltable><tgroup cols="1"><tbody><row><entry align="char"> -<para>This ioctl call sets one or more frontend properties. This call only - requires read-only access to the device.</para> +<para>This ioctl call sets one or more frontend properties. This call + requires read/write access to the device.</para> </entry> </row></tbody></tgroup></informaltable> <para>SYNOPSIS diff --git a/Documentation/DocBook/media/v4l/biblio.xml b/Documentation/DocBook/media/v4l/biblio.xml index d2eb79e41a01..7ff01a23c2fe 100644 --- a/Documentation/DocBook/media/v4l/biblio.xml +++ b/Documentation/DocBook/media/v4l/biblio.xml @@ -178,6 +178,75 @@ Signal - NTSC for Studio Applications"</title> 1125-Line High-Definition Production"</title> </biblioentry> + <biblioentry id="srgb"> + <abbrev>sRGB</abbrev> + <authorgroup> + <corpauthor>International Electrotechnical Commission +(<ulink url="http://www.iec.ch">http://www.iec.ch</ulink>)</corpauthor> + </authorgroup> + <title>IEC 61966-2-1 ed1.0 "Multimedia systems and equipment - Colour measurement +and management - Part 2-1: Colour management - Default RGB colour space - sRGB"</title> + </biblioentry> + + <biblioentry id="sycc"> + <abbrev>sYCC</abbrev> + <authorgroup> + <corpauthor>International Electrotechnical Commission +(<ulink url="http://www.iec.ch">http://www.iec.ch</ulink>)</corpauthor> + </authorgroup> + <title>IEC 61966-2-1-am1 ed1.0 "Amendment 1 - Multimedia systems and equipment - Colour measurement +and management - Part 2-1: Colour management - Default RGB colour space - sRGB"</title> + </biblioentry> + + <biblioentry id="xvycc"> + <abbrev>xvYCC</abbrev> + <authorgroup> + <corpauthor>International Electrotechnical Commission +(<ulink url="http://www.iec.ch">http://www.iec.ch</ulink>)</corpauthor> + </authorgroup> + <title>IEC 61966-2-4 ed1.0 "Multimedia systems and equipment - Colour measurement +and management - Part 2-4: Colour management - Extended-gamut YCC colour space for video +applications - xvYCC"</title> + </biblioentry> + + <biblioentry id="adobergb"> + <abbrev>AdobeRGB</abbrev> + <authorgroup> + <corpauthor>Adobe Systems Incorporated (<ulink url="http://www.adobe.com">http://www.adobe.com</ulink>)</corpauthor> + </authorgroup> + <title>Adobe© RGB (1998) Color Image Encoding Version 2005-05</title> + </biblioentry> + + <biblioentry id="oprgb"> + <abbrev>opRGB</abbrev> + <authorgroup> + <corpauthor>International Electrotechnical Commission +(<ulink url="http://www.iec.ch">http://www.iec.ch</ulink>)</corpauthor> + </authorgroup> + <title>IEC 61966-2-5 "Multimedia systems and equipment - Colour measurement +and management - Part 2-5: Colour management - Optional RGB colour space - opRGB"</title> + </biblioentry> + + <biblioentry id="itu2020"> + <abbrev>ITU BT.2020</abbrev> + <authorgroup> + <corpauthor>International Telecommunication Union (<ulink +url="http://www.itu.ch">http://www.itu.ch</ulink>)</corpauthor> + </authorgroup> + <title>ITU-R Recommendation BT.2020 (08/2012) "Parameter values for ultra-high +definition television systems for production and international programme exchange" +</title> + </biblioentry> + + <biblioentry id="tech3213"> + <abbrev>EBU Tech 3213</abbrev> + <authorgroup> + <corpauthor>European Broadcast Union (<ulink +url="http://www.ebu.ch">http://www.ebu.ch</ulink>)</corpauthor> + </authorgroup> + <title>E.B.U. Standard for Chromaticity Tolerances for Studio Monitors"</title> + </biblioentry> + <biblioentry id="iec62106"> <abbrev>IEC 62106</abbrev> <authorgroup> @@ -266,4 +335,20 @@ in the frequency range from 87,5 to 108,0 MHz</title> <subtitle>Version 1, Revision 2</subtitle> </biblioentry> + <biblioentry id="poynton"> + <abbrev>poynton</abbrev> + <authorgroup> + <corpauthor>Charles Poynton</corpauthor> + </authorgroup> + <title>Digital Video and HDTV, Algorithms and Interfaces</title> + </biblioentry> + + <biblioentry id="colimg"> + <abbrev>colimg</abbrev> + <authorgroup> + <corpauthor>Erik Reinhard et al.</corpauthor> + </authorgroup> + <title>Color Imaging: Fundamentals and Applications</title> + </biblioentry> + </bibliography> diff --git a/Documentation/DocBook/media/v4l/compat.xml b/Documentation/DocBook/media/v4l/compat.xml index 0a2debfa68f6..350dfb3d71ea 100644 --- a/Documentation/DocBook/media/v4l/compat.xml +++ b/Documentation/DocBook/media/v4l/compat.xml @@ -2579,6 +2579,18 @@ fields changed from _s32 to _u32. </orderedlist> </section> + <section> + <title>V4L2 in Linux 3.19</title> + <orderedlist> + <listitem> + <para>Rewrote Colorspace chapter, added new &v4l2-ycbcr-encoding; +and &v4l2-quantization; fields to &v4l2-pix-format;, &v4l2-pix-format-mplane; +and &v4l2-mbus-framefmt;. + </para> + </listitem> + </orderedlist> + </section> + <section id="other"> <title>Relation of V4L2 to other Linux multimedia APIs</title> diff --git a/Documentation/DocBook/media/v4l/controls.xml b/Documentation/DocBook/media/v4l/controls.xml index e013e4bf244c..4e9462f1ab4c 100644 --- a/Documentation/DocBook/media/v4l/controls.xml +++ b/Documentation/DocBook/media/v4l/controls.xml @@ -2692,12 +2692,11 @@ in the S5P family of SoCs by Samsung. <row><entry></entry></row> <row> <entry spanname="id"><constant>V4L2_CID_MPEG_MFC51_VIDEO_DECODER_H264_DISPLAY_DELAY_ENABLE</constant> </entry> - <entry>integer</entry> - </row><row><entry spanname="descr">If the display delay is enabled then the decoder has to return a -CAPTURE buffer after processing a certain number of OUTPUT buffers. If this number is low, then it may result in -buffers not being dequeued in display order. In addition hardware may still use those buffers as reference, thus -application should not write to those buffers. This feature can be used for example for generating thumbnails of videos. -Applicable to the H264 decoder. + <entry>boolean</entry> + </row><row><entry spanname="descr">If the display delay is enabled then the decoder is forced to return a +CAPTURE buffer (decoded frame) after processing a certain number of OUTPUT buffers. The delay can be set through +<constant>V4L2_CID_MPEG_MFC51_VIDEO_DECODER_H264_DISPLAY_DELAY</constant>. This feature can be used for example +for generating thumbnails of videos. Applicable to the H264 decoder. </entry> </row> <row><entry></entry></row> diff --git a/Documentation/DocBook/media/v4l/dev-subdev.xml b/Documentation/DocBook/media/v4l/dev-subdev.xml index d15aaf83f56f..4f0ba58c9bd9 100644 --- a/Documentation/DocBook/media/v4l/dev-subdev.xml +++ b/Documentation/DocBook/media/v4l/dev-subdev.xml @@ -195,53 +195,59 @@ <title>Sample Pipeline Configuration</title> <tgroup cols="3"> <colspec colname="what"/> - <colspec colname="sensor-0" /> - <colspec colname="frontend-0" /> - <colspec colname="frontend-1" /> - <colspec colname="scaler-0" /> - <colspec colname="scaler-1" /> + <colspec colname="sensor-0 format" /> + <colspec colname="frontend-0 format" /> + <colspec colname="frontend-1 format" /> + <colspec colname="scaler-0 format" /> + <colspec colname="scaler-0 compose" /> + <colspec colname="scaler-1 format" /> <thead> <row> <entry></entry> - <entry>Sensor/0</entry> - <entry>Frontend/0</entry> - <entry>Frontend/1</entry> - <entry>Scaler/0</entry> - <entry>Scaler/1</entry> + <entry>Sensor/0 format</entry> + <entry>Frontend/0 format</entry> + <entry>Frontend/1 format</entry> + <entry>Scaler/0 format</entry> + <entry>Scaler/0 compose selection rectangle</entry> + <entry>Scaler/1 format</entry> </row> </thead> <tbody valign="top"> <row> <entry>Initial state</entry> - <entry>2048x1536</entry> - <entry>-</entry> - <entry>-</entry> - <entry>-</entry> - <entry>-</entry> + <entry>2048x1536/SGRBG8_1X8</entry> + <entry>(default)</entry> + <entry>(default)</entry> + <entry>(default)</entry> + <entry>(default)</entry> + <entry>(default)</entry> </row> <row> - <entry>Configure frontend input</entry> - <entry>2048x1536</entry> - <entry><emphasis>2048x1536</emphasis></entry> - <entry><emphasis>2046x1534</emphasis></entry> - <entry>-</entry> - <entry>-</entry> + <entry>Configure frontend sink format</entry> + <entry>2048x1536/SGRBG8_1X8</entry> + <entry><emphasis>2048x1536/SGRBG8_1X8</emphasis></entry> + <entry><emphasis>2046x1534/SGRBG8_1X8</emphasis></entry> + <entry>(default)</entry> + <entry>(default)</entry> + <entry>(default)</entry> </row> <row> - <entry>Configure scaler input</entry> - <entry>2048x1536</entry> - <entry>2048x1536</entry> - <entry>2046x1534</entry> - <entry><emphasis>2046x1534</emphasis></entry> - <entry><emphasis>2046x1534</emphasis></entry> + <entry>Configure scaler sink format</entry> + <entry>2048x1536/SGRBG8_1X8</entry> + <entry>2048x1536/SGRBG8_1X8</entry> + <entry>2046x1534/SGRBG8_1X8</entry> + <entry><emphasis>2046x1534/SGRBG8_1X8</emphasis></entry> + <entry><emphasis>0,0/2046x1534</emphasis></entry> + <entry><emphasis>2046x1534/SGRBG8_1X8</emphasis></entry> </row> <row> - <entry>Configure scaler output</entry> - <entry>2048x1536</entry> - <entry>2048x1536</entry> - <entry>2046x1534</entry> - <entry>2046x1534</entry> - <entry><emphasis>1280x960</emphasis></entry> + <entry>Configure scaler sink compose selection</entry> + <entry>2048x1536/SGRBG8_1X8</entry> + <entry>2048x1536/SGRBG8_1X8</entry> + <entry>2046x1534/SGRBG8_1X8</entry> + <entry>2046x1534/SGRBG8_1X8</entry> + <entry><emphasis>0,0/1280x960</emphasis></entry> + <entry><emphasis>1280x960/SGRBG8_1X8</emphasis></entry> </row> </tbody> </tgroup> @@ -249,19 +255,30 @@ <para> <orderedlist> - <listitem><para>Initial state. The sensor output is set to its native 3MP - resolution. Resolutions on the host frontend and scaler input and output - pads are undefined.</para></listitem> - <listitem><para>The application configures the frontend input pad resolution to - 2048x1536. The driver propagates the format to the frontend output pad. - Note that the propagated output format can be different, as in this case, - than the input format, as the hardware might need to crop pixels (for - instance when converting a Bayer filter pattern to RGB or YUV).</para></listitem> - <listitem><para>The application configures the scaler input pad resolution to - 2046x1534 to match the frontend output resolution. The driver propagates - the format to the scaler output pad.</para></listitem> - <listitem><para>The application configures the scaler output pad resolution to - 1280x960.</para></listitem> + <listitem><para>Initial state. The sensor source pad format is + set to its native 3MP size and V4L2_MBUS_FMT_SGRBG8_1X8 + media bus code. Formats on the host frontend and scaler sink + and source pads have the default values, as well as the + compose rectangle on the scaler's sink pad.</para></listitem> + + <listitem><para>The application configures the frontend sink + pad format's size to 2048x1536 and its media bus code to + V4L2_MBUS_FMT_SGRBG_1X8. The driver propagates the format to + the frontend source pad.</para></listitem> + + <listitem><para>The application configures the scaler sink pad + format's size to 2046x1534 and the media bus code to + V4L2_MBUS_FMT_SGRBG_1X8 to match the frontend source size and + media bus code. The media bus code on the sink pad is set to + V4L2_MBUS_FMT_SGRBG_1X8. The driver propagates the size to the + compose selection rectangle on the scaler's sink pad, and the + format to the scaler source pad.</para></listitem> + + <listitem><para>The application configures the size of the compose + selection rectangle of the scaler's sink pad 1280x960. The driver + propagates the size to the scaler's source pad + format.</para></listitem> + </orderedlist> </para> diff --git a/Documentation/DocBook/media/v4l/io.xml b/Documentation/DocBook/media/v4l/io.xml index e5e8325aa3d7..1c17f802b471 100644 --- a/Documentation/DocBook/media/v4l/io.xml +++ b/Documentation/DocBook/media/v4l/io.xml @@ -1422,7 +1422,10 @@ one of the <constant>V4L2_FIELD_NONE</constant>, <constant>V4L2_FIELD_BOTTOM</constant>, or <constant>V4L2_FIELD_INTERLACED</constant> formats is acceptable. Drivers choose depending on hardware capabilities or e. g. the -requested image size, and return the actual field order. &v4l2-buffer; +requested image size, and return the actual field order. Drivers must +never return <constant>V4L2_FIELD_ANY</constant>. If multiple +field orders are possible the driver must choose one of the possible +field orders during &VIDIOC-S-FMT; or &VIDIOC-TRY-FMT;. &v4l2-buffer; <structfield>field</structfield> can never be <constant>V4L2_FIELD_ANY</constant>.</entry> </row> diff --git a/Documentation/DocBook/media/v4l/pixfmt-srggb10.xml b/Documentation/DocBook/media/v4l/pixfmt-srggb10.xml index c1c62a9acc2a..f34d03ebda3a 100644 --- a/Documentation/DocBook/media/v4l/pixfmt-srggb10.xml +++ b/Documentation/DocBook/media/v4l/pixfmt-srggb10.xml @@ -17,7 +17,7 @@ <refsect1> <title>Description</title> - <para>The following four pixel formats are raw sRGB / Bayer formats with + <para>These four pixel formats are raw sRGB / Bayer formats with 10 bits per colour. Each colour component is stored in a 16-bit word, with 6 unused high bits filled with zeros. Each n-pixel row contains n/2 green samples and n/2 blue or red samples, with alternating red and blue rows. Bytes are diff --git a/Documentation/DocBook/media/v4l/pixfmt-srggb10alaw8.xml b/Documentation/DocBook/media/v4l/pixfmt-srggb10alaw8.xml index 29acc2098cc2..d2e5845e57fb 100644 --- a/Documentation/DocBook/media/v4l/pixfmt-srggb10alaw8.xml +++ b/Documentation/DocBook/media/v4l/pixfmt-srggb10alaw8.xml @@ -25,7 +25,7 @@ </refnamediv> <refsect1> <title>Description</title> - <para>The following four pixel formats are raw sRGB / Bayer + <para>These four pixel formats are raw sRGB / Bayer formats with 10 bits per color compressed to 8 bits each, using the A-LAW algorithm. Each color component consumes 8 bits of memory. In other respects this format is similar to diff --git a/Documentation/DocBook/media/v4l/pixfmt-srggb10dpcm8.xml b/Documentation/DocBook/media/v4l/pixfmt-srggb10dpcm8.xml index 2d3f0b1aefe0..bde89878c5c5 100644 --- a/Documentation/DocBook/media/v4l/pixfmt-srggb10dpcm8.xml +++ b/Documentation/DocBook/media/v4l/pixfmt-srggb10dpcm8.xml @@ -18,7 +18,7 @@ <refsect1> <title>Description</title> - <para>The following four pixel formats are raw sRGB / Bayer formats + <para>These four pixel formats are raw sRGB / Bayer formats with 10 bits per colour compressed to 8 bits each, using DPCM compression. DPCM, differential pulse-code modulation, is lossy. Each colour component consumes 8 bits of memory. In other respects diff --git a/Documentation/DocBook/media/v4l/pixfmt-srggb10p.xml b/Documentation/DocBook/media/v4l/pixfmt-srggb10p.xml new file mode 100644 index 000000000000..30aa63581fe3 --- /dev/null +++ b/Documentation/DocBook/media/v4l/pixfmt-srggb10p.xml @@ -0,0 +1,99 @@ + <refentry id="pixfmt-srggb10p"> + <refmeta> + <refentrytitle>V4L2_PIX_FMT_SRGGB10P ('pRAA'), + V4L2_PIX_FMT_SGRBG10P ('pgAA'), + V4L2_PIX_FMT_SGBRG10P ('pGAA'), + V4L2_PIX_FMT_SBGGR10P ('pBAA'), + </refentrytitle> + &manvol; + </refmeta> + <refnamediv> + <refname id="V4L2-PIX-FMT-SRGGB10P"><constant>V4L2_PIX_FMT_SRGGB10P</constant></refname> + <refname id="V4L2-PIX-FMT-SGRBG10P"><constant>V4L2_PIX_FMT_SGRBG10P</constant></refname> + <refname id="V4L2-PIX-FMT-SGBRG10P"><constant>V4L2_PIX_FMT_SGBRG10P</constant></refname> + <refname id="V4L2-PIX-FMT-SBGGR10P"><constant>V4L2_PIX_FMT_SBGGR10P</constant></refname> + <refpurpose>10-bit packed Bayer formats</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + + <para>These four pixel formats are packed raw sRGB / + Bayer formats with 10 bits per colour. Every four consecutive + colour components are packed into 5 bytes. Each of the first 4 + bytes contain the 8 high order bits of the pixels, and the + fifth byte contains the two least significants bits of each + pixel, in the same order.</para> + + <para>Each n-pixel row contains n/2 green samples and n/2 blue + or red samples, with alternating green-red and green-blue + rows. They are conventionally described as GRGR... BGBG..., + RGRG... GBGB..., etc. Below is an example of one of these + formats:</para> + + <example> + <title><constant>V4L2_PIX_FMT_SBGGR10P</constant> 4 × 4 + pixel image</title> + + <formalpara> + <title>Byte Order.</title> + <para>Each cell is one byte. + <informaltable frame="topbot" colsep="1" rowsep="1"> + <tgroup cols="5" align="center" border="1"> + <colspec align="left" colwidth="2*" /> + <tbody valign="top"> + <row> + <entry>start + 0:</entry> + <entry>B<subscript>00high</subscript></entry> + <entry>G<subscript>01high</subscript></entry> + <entry>B<subscript>02high</subscript></entry> + <entry>G<subscript>03high</subscript></entry> + <entry>B<subscript>00low</subscript>(bits 7--6) + G<subscript>01low</subscript>(bits 5--4) + B<subscript>02low</subscript>(bits 3--2) + G<subscript>03low</subscript>(bits 1--0) + </entry> + </row> + <row> + <entry>start + 5:</entry> + <entry>G<subscript>10high</subscript></entry> + <entry>R<subscript>11high</subscript></entry> + <entry>G<subscript>12high</subscript></entry> + <entry>R<subscript>13high</subscript></entry> + <entry>G<subscript>10low</subscript>(bits 7--6) + R<subscript>11low</subscript>(bits 5--4) + G<subscript>12low</subscript>(bits 3--2) + R<subscript>13low</subscript>(bits 1--0) + </entry> + </row> + <row> + <entry>start + 10:</entry> + <entry>B<subscript>20high</subscript></entry> + <entry>G<subscript>21high</subscript></entry> + <entry>B<subscript>22high</subscript></entry> + <entry>G<subscript>23high</subscript></entry> + <entry>B<subscript>20low</subscript>(bits 7--6) + G<subscript>21low</subscript>(bits 5--4) + B<subscript>22low</subscript>(bits 3--2) + G<subscript>23low</subscript>(bits 1--0) + </entry> + </row> + <row> + <entry>start + 15:</entry> + <entry>G<subscript>30high</subscript></entry> + <entry>R<subscript>31high</subscript></entry> + <entry>G<subscript>32high</subscript></entry> + <entry>R<subscript>33high</subscript></entry> + <entry>G<subscript>30low</subscript>(bits 7--6) + R<subscript>31low</subscript>(bits 5--4) + G<subscript>32low</subscript>(bits 3--2) + R<subscript>33low</subscript>(bits 1--0) + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + </para> + </formalpara> + </example> + </refsect1> +</refentry> diff --git a/Documentation/DocBook/media/v4l/pixfmt-srggb12.xml b/Documentation/DocBook/media/v4l/pixfmt-srggb12.xml index 96947f17fca1..0c8e4adf417f 100644 --- a/Documentation/DocBook/media/v4l/pixfmt-srggb12.xml +++ b/Documentation/DocBook/media/v4l/pixfmt-srggb12.xml @@ -17,7 +17,7 @@ <refsect1> <title>Description</title> - <para>The following four pixel formats are raw sRGB / Bayer formats with + <para>These four pixel formats are raw sRGB / Bayer formats with 12 bits per colour. Each colour component is stored in a 16-bit word, with 4 unused high bits filled with zeros. Each n-pixel row contains n/2 green samples and n/2 blue or red samples, with alternating red and blue rows. Bytes are diff --git a/Documentation/DocBook/media/v4l/pixfmt.xml b/Documentation/DocBook/media/v4l/pixfmt.xml index df5b23d46552..5e0352c50324 100644 --- a/Documentation/DocBook/media/v4l/pixfmt.xml +++ b/Documentation/DocBook/media/v4l/pixfmt.xml @@ -138,9 +138,25 @@ applicable values.</para></entry> <row> <entry>__u32</entry> <entry><structfield>flags</structfield></entry> - <entry>Flags set by the application or driver, see <xref + <entry>Flags set by the application or driver, see <xref linkend="format-flags" />.</entry> </row> + <row> + <entry>&v4l2-ycbcr-encoding;</entry> + <entry><structfield>ycbcr_enc</structfield></entry> + <entry>This information supplements the +<structfield>colorspace</structfield> and must be set by the driver for +capture streams and by the application for output streams, +see <xref linkend="colorspaces" />.</entry> + </row> + <row> + <entry>&v4l2-quantization;</entry> + <entry><structfield>quantization</structfield></entry> + <entry>This information supplements the +<structfield>colorspace</structfield> and must be set by the driver for +capture streams and by the application for output streams, +see <xref linkend="colorspaces" />.</entry> + </row> </tbody> </tgroup> </table> @@ -232,9 +248,25 @@ codes can be used.</entry> <entry>Flags set by the application or driver, see <xref linkend="format-flags" />.</entry> </row> + <row> + <entry>&v4l2-ycbcr-encoding;</entry> + <entry><structfield>ycbcr_enc</structfield></entry> + <entry>This information supplements the +<structfield>colorspace</structfield> and must be set by the driver for +capture streams and by the application for output streams, +see <xref linkend="colorspaces" />.</entry> + </row> + <row> + <entry>&v4l2-quantization;</entry> + <entry><structfield>quantization</structfield></entry> + <entry>This information supplements the +<structfield>colorspace</structfield> and must be set by the driver for +capture streams and by the application for output streams, +see <xref linkend="colorspaces" />.</entry> + </row> <row> <entry>__u8</entry> - <entry><structfield>reserved[10]</structfield></entry> + <entry><structfield>reserved[8]</structfield></entry> <entry>Reserved for future extensions. Should be zeroed by the application.</entry> </row> @@ -296,345 +328,1005 @@ in the 2-planar version or with each component in its own buffer in the <section id="colorspaces"> <title>Colorspaces</title> - <para>[intro]</para> + <para>'Color' is a very complex concept and depends on physics, chemistry and +biology. Just because you have three numbers that describe the 'red', 'green' +and 'blue' components of the color of a pixel does not mean that you can accurately +display that color. A colorspace defines what it actually <emphasis>means</emphasis> +to have an RGB value of e.g. (255, 0, 0). That is, which color should be +reproduced on the screen in a perfectly calibrated environment.</para> - <!-- See proposal by Billy Biggs, video4linux-list@redhat.com -on 11 Oct 2002, subject: "Re: [V4L] Re: v4l2 api", and -http://vektor.theorem.ca/graphics/ycbcr/ and -http://www.poynton.com/notes/colour_and_gamma/ColorFAQ.html --> + <para>In order to do that we first need to have a good definition of +color, i.e. some way to uniquely and unambiguously define a color so that someone +else can reproduce it. Human color vision is trichromatic since the human eye has +color receptors that are sensitive to three different wavelengths of light. Hence +the need to use three numbers to describe color. Be glad you are not a mantis shrimp +as those are sensitive to 12 different wavelengths, so instead of RGB we would be +using the ABCDEFGHIJKL colorspace...</para> - <para> - <variablelist> - <varlistentry> - <term>Gamma Correction</term> - <listitem> - <para>[to do]</para> - <para>E'<subscript>R</subscript> = f(R)</para> - <para>E'<subscript>G</subscript> = f(G)</para> - <para>E'<subscript>B</subscript> = f(B)</para> - </listitem> - </varlistentry> - <varlistentry> - <term>Construction of luminance and color-difference -signals</term> - <listitem> - <para>[to do]</para> - <para>E'<subscript>Y</subscript> = -Coeff<subscript>R</subscript> E'<subscript>R</subscript> -+ Coeff<subscript>G</subscript> E'<subscript>G</subscript> -+ Coeff<subscript>B</subscript> E'<subscript>B</subscript></para> - <para>(E'<subscript>R</subscript> - E'<subscript>Y</subscript>) = E'<subscript>R</subscript> -- Coeff<subscript>R</subscript> E'<subscript>R</subscript> -- Coeff<subscript>G</subscript> E'<subscript>G</subscript> -- Coeff<subscript>B</subscript> E'<subscript>B</subscript></para> - <para>(E'<subscript>B</subscript> - E'<subscript>Y</subscript>) = E'<subscript>B</subscript> -- Coeff<subscript>R</subscript> E'<subscript>R</subscript> -- Coeff<subscript>G</subscript> E'<subscript>G</subscript> -- Coeff<subscript>B</subscript> E'<subscript>B</subscript></para> - </listitem> - </varlistentry> - <varlistentry> - <term>Re-normalized color-difference signals</term> - <listitem> - <para>The color-difference signals are scaled back to unity -range [-0.5;+0.5]:</para> - <para>K<subscript>B</subscript> = 0.5 / (1 - Coeff<subscript>B</subscript>)</para> - <para>K<subscript>R</subscript> = 0.5 / (1 - Coeff<subscript>R</subscript>)</para> - <para>P<subscript>B</subscript> = -K<subscript>B</subscript> (E'<subscript>B</subscript> - E'<subscript>Y</subscript>) = - 0.5 (Coeff<subscript>R</subscript> / Coeff<subscript>B</subscript>) E'<subscript>R</subscript> -+ 0.5 (Coeff<subscript>G</subscript> / Coeff<subscript>B</subscript>) E'<subscript>G</subscript> -+ 0.5 E'<subscript>B</subscript></para> - <para>P<subscript>R</subscript> = -K<subscript>R</subscript> (E'<subscript>R</subscript> - E'<subscript>Y</subscript>) = - 0.5 E'<subscript>R</subscript> -+ 0.5 (Coeff<subscript>G</subscript> / Coeff<subscript>R</subscript>) E'<subscript>G</subscript> -+ 0.5 (Coeff<subscript>B</subscript> / Coeff<subscript>R</subscript>) E'<subscript>B</subscript></para> - </listitem> - </varlistentry> - <varlistentry> - <term>Quantization</term> - <listitem> - <para>[to do]</para> - <para>Y' = (Lum. Levels - 1) · E'<subscript>Y</subscript> + Lum. Offset</para> - <para>C<subscript>B</subscript> = (Chrom. Levels - 1) -· P<subscript>B</subscript> + Chrom. Offset</para> - <para>C<subscript>R</subscript> = (Chrom. Levels - 1) -· P<subscript>R</subscript> + Chrom. Offset</para> - <para>Rounding to the nearest integer and clamping to the range -[0;255] finally yields the digital color components Y'CbCr -stored in YUV images.</para> - </listitem> - </varlistentry> - </variablelist> - </para> - - <example> - <title>ITU-R Rec. BT.601 color conversion</title> - - <para>Forward Transformation</para> - - <programlisting> -int ER, EG, EB; /* gamma corrected RGB input [0;255] */ -int Y1, Cb, Cr; /* output [0;255] */ - -double r, g, b; /* temporaries */ -double y1, pb, pr; - -int -clamp (double x) -{ - int r = x; /* round to nearest */ - - if (r < 0) return 0; - else if (r > 255) return 255; - else return r; -} - -r = ER / 255.0; -g = EG / 255.0; -b = EB / 255.0; - -y1 = 0.299 * r + 0.587 * g + 0.114 * b; -pb = -0.169 * r - 0.331 * g + 0.5 * b; -pr = 0.5 * r - 0.419 * g - 0.081 * b; - -Y1 = clamp (219 * y1 + 16); -Cb = clamp (224 * pb + 128); -Cr = clamp (224 * pr + 128); - -/* or shorter */ - -y1 = 0.299 * ER + 0.587 * EG + 0.114 * EB; - -Y1 = clamp ( (219 / 255.0) * y1 + 16); -Cb = clamp (((224 / 255.0) / (2 - 2 * 0.114)) * (EB - y1) + 128); -Cr = clamp (((224 / 255.0) / (2 - 2 * 0.299)) * (ER - y1) + 128); - </programlisting> - - <para>Inverse Transformation</para> - - <programlisting> -int Y1, Cb, Cr; /* gamma pre-corrected input [0;255] */ -int ER, EG, EB; /* output [0;255] */ - -double r, g, b; /* temporaries */ -double y1, pb, pr; - -int -clamp (double x) -{ - int r = x; /* round to nearest */ - - if (r < 0) return 0; - else if (r > 255) return 255; - else return r; -} - -y1 = (Y1 - 16) / 219.0; -pb = (Cb - 128) / 224.0; -pr = (Cr - 128) / 224.0; - -r = 1.0 * y1 + 0 * pb + 1.402 * pr; -g = 1.0 * y1 - 0.344 * pb - 0.714 * pr; -b = 1.0 * y1 + 1.772 * pb + 0 * pr; - -ER = clamp (r * 255); /* [ok? one should prob. limit y1,pb,pr] */ -EG = clamp (g * 255); -EB = clamp (b * 255); - </programlisting> - </example> - - <table pgwide="1" id="v4l2-colorspace" orient="land"> - <title>enum v4l2_colorspace</title> - <tgroup cols="11" align="center"> - <colspec align="left" /> - <colspec align="center" /> - <colspec align="left" /> - <colspec colname="cr" /> - <colspec colname="cg" /> - <colspec colname="cb" /> - <colspec colname="wp" /> - <colspec colname="gc" /> - <colspec colname="lum" /> - <colspec colname="qy" /> - <colspec colname="qc" /> - <spanspec namest="cr" nameend="cb" spanname="chrom" /> - <spanspec namest="qy" nameend="qc" spanname="quant" /> - <spanspec namest="lum" nameend="qc" spanname="spam" /> + <para>Color exists only in the eye and brain and is the result of how strongly +color receptors are stimulated. This is based on the Spectral +Power Distribution (SPD) which is a graph showing the intensity (radiant power) +of the light at wavelengths covering the visible spectrum as it enters the eye. +The science of colorimetry is about the relationship between the SPD and color as +perceived by the human brain.</para> + + <para>Since the human eye has only three color receptors it is perfectly +possible that different SPDs will result in the same stimulation of those receptors +and are perceived as the same color, even though the SPD of the light is +different.</para> + + <para>In the 1920s experiments were devised to determine the relationship +between SPDs and the perceived color and that resulted in the CIE 1931 standard +that defines spectral weighting functions that model the perception of color. +Specifically that standard defines functions that can take an SPD and calculate +the stimulus for each color receptor. After some further mathematical transforms +these stimuli are known as the <emphasis>CIE XYZ tristimulus</emphasis> values +and these X, Y and Z values describe a color as perceived by a human unambiguously. +These X, Y and Z values are all in the range [0…1].</para> + + <para>The Y value in the CIE XYZ colorspace corresponds to luminance. Often +the CIE XYZ colorspace is transformed to the normalized CIE xyY colorspace:</para> + + <para>x = X / (X + Y + Z)</para> + <para>y = Y / (X + Y + Z)</para> + + <para>The x and y values are the chromaticity coordinates and can be used to +define a color without the luminance component Y. It is very confusing to +have such similar names for these colorspaces. Just be aware that if colors +are specified with lower case 'x' and 'y', then the CIE xyY colorspace is +used. Upper case 'X' and 'Y' refer to the CIE XYZ colorspace. Also, y has nothing +to do with luminance. Together x and y specify a color, and Y the luminance. +That is really all you need to remember from a practical point of view. At +the end of this section you will find reading resources that go into much more +detail if you are interested. +</para> + + <para>A monitor or TV will reproduce colors by emitting light at three +different wavelengths, the combination of which will stimulate the color receptors +in the eye and thus cause the perception of color. Historically these wavelengths +were defined by the red, green and blue phosphors used in the displays. These +<emphasis>color primaries</emphasis> are part of what defines a colorspace.</para> + + <para>Different display devices will have different primaries and some +primaries are more suitable for some display technologies than others. This has +resulted in a variety of colorspaces that are used for different display +technologies or uses. To define a colorspace you need to define the three +color primaries (these are typically defined as x, y chromaticity coordinates +from the CIE xyY colorspace) but also the white reference: that is the color obtained +when all three primaries are at maximum power. This determines the relative power +or energy of the primaries. This is usually chosen to be close to daylight which has +been defined as the CIE D65 Illuminant.</para> + + <para>To recapitulate: the CIE XYZ colorspace uniquely identifies colors. +Other colorspaces are defined by three chromaticity coordinates defined in the +CIE xyY colorspace. Based on those a 3x3 matrix can be constructed that +transforms CIE XYZ colors to colors in the new colorspace. +</para> + + <para>Both the CIE XYZ and the RGB colorspace that are derived from the +specific chromaticity primaries are linear colorspaces. But neither the eye, +nor display technology is linear. Doubling the values of all components in +the linear colorspace will not be perceived as twice the intensity of the color. +So each colorspace also defines a transfer function that takes a linear color +component value and transforms it to the non-linear component value, which is a +closer match to the non-linear performance of both the eye and displays. Linear +component values are denoted RGB, non-linear are denoted as R'G'B'. In general +colors used in graphics are all R'G'B', except in openGL which uses linear RGB. +Special care should be taken when dealing with openGL to provide linear RGB colors +or to use the built-in openGL support to apply the inverse transfer function.</para> + + <para>The final piece that defines a colorspace is a function that +transforms non-linear R'G'B' to non-linear Y'CbCr. This function is determined +by the so-called luma coefficients. There may be multiple possible Y'CbCr +encodings allowed for the same colorspace. Many encodings of color +prefer to use luma (Y') and chroma (CbCr) instead of R'G'B'. Since the human +eye is more sensitive to differences in luminance than in color this encoding +allows one to reduce the amount of color information compared to the luma +data. Note that the luma (Y') is unrelated to the Y in the CIE XYZ colorspace. +Also note that Y'CbCr is often called YCbCr or YUV even though these are +strictly speaking wrong.</para> + + <para>Sometimes people confuse Y'CbCr as being a colorspace. This is not +correct, it is just an encoding of an R'G'B' color into luma and chroma +values. The underlying colorspace that is associated with the R'G'B' color +is also associated with the Y'CbCr color.</para> + + <para>The final step is how the RGB, R'G'B' or Y'CbCr values are +quantized. The CIE XYZ colorspace where X, Y and Z are in the range +[0…1] describes all colors that humans can perceive, but the transform to +another colorspace will produce colors that are outside the [0…1] range. +Once clamped to the [0…1] range those colors can no longer be reproduced +in that colorspace. This clamping is what reduces the extent or gamut of the +colorspace. How the range of [0…1] is translated to integer values in the +range of [0…255] (or higher, depending on the color depth) is called the +quantization. This is <emphasis>not</emphasis> part of the colorspace +definition. In practice RGB or R'G'B' values are full range, i.e. they +use the full [0…255] range. Y'CbCr values on the other hand are limited +range with Y' using [16…235] and Cb and Cr using [16…240].</para> + + <para>Unfortunately, in some cases limited range RGB is also used +where the components use the range [16…235]. And full range Y'CbCr also exists +using the [0…255] range.</para> + + <para>In order to correctly interpret a color you need to know the +quantization range, whether it is R'G'B' or Y'CbCr, the used Y'CbCr encoding +and the colorspace. +From that information you can calculate the corresponding CIE XYZ color +and map that again to whatever colorspace your display device uses.</para> + + <para>The colorspace definition itself consists of the three +chromaticity primaries, the white reference chromaticity, a transfer +function and the luma coefficients needed to transform R'G'B' to Y'CbCr. While +some colorspace standards correctly define all four, quite often the colorspace +standard only defines some, and you have to rely on other standards for +the missing pieces. The fact that colorspaces are often a mix of different +standards also led to very confusing naming conventions where the name of +a standard was used to name a colorspace when in fact that standard was +part of various other colorspaces as well.</para> + + <para>If you want to read more about colors and colorspaces, then the +following resources are useful: <xref linkend="poynton" /> is a good practical +book for video engineers, <xref linkend="colimg" /> has a much broader scope and +describes many more aspects of color (physics, chemistry, biology, etc.). +The <ulink url="http://www.brucelindbloom.com">http://www.brucelindbloom.com</ulink> +website is an excellent resource, especially with respect to the mathematics behind +colorspace conversions. The wikipedia <ulink url="http://en.wikipedia.org/wiki/CIE_1931_color_space#CIE_xy_chromaticity_diagram_and_the_CIE_xyY_color_space">CIE 1931 colorspace</ulink> article +is also very useful.</para> + </section> + + <section> + <title>Defining Colorspaces in V4L2</title> + <para>In V4L2 colorspaces are defined by three values. The first is the colorspace +identifier (&v4l2-colorspace;) which defines the chromaticities, the transfer +function, the default Y'CbCr encoding and the default quantization method. The second +is the Y'CbCr encoding identifier (&v4l2-ycbcr-encoding;) to specify non-standard +Y'CbCr encodings and the third is the quantization identifier (&v4l2-quantization;) +to specify non-standard quantization methods. Most of the time only the colorspace +field of &v4l2-pix-format; or &v4l2-pix-format-mplane; needs to be filled in. Note +that the default R'G'B' quantization is always full range for all colorspaces, +so this won't be mentioned explicitly for each colorspace description.</para> + + <table pgwide="1" frame="none" id="v4l2-colorspace"> + <title>V4L2 Colorspaces</title> + <tgroup cols="2" align="left"> + &cs-def; <thead> <row> - <entry morerows="1">Identifier</entry> - <entry morerows="1">Value</entry> - <entry morerows="1">Description</entry> - <entry spanname="chrom">Chromaticities<footnote> - <para>The coordinates of the color primaries are -given in the CIE system (1931)</para> - </footnote></entry> - <entry morerows="1">White Point</entry> - <entry morerows="1">Gamma Correction</entry> - <entry morerows="1">Luminance E'<subscript>Y</subscript></entry> - <entry spanname="quant">Quantization</entry> - </row> - <row> - <entry>Red</entry> - <entry>Green</entry> - <entry>Blue</entry> - <entry>Y'</entry> - <entry>Cb, Cr</entry> + <entry>Identifier</entry> + <entry>Details</entry> </row> </thead> <tbody valign="top"> <row> <entry><constant>V4L2_COLORSPACE_SMPTE170M</constant></entry> - <entry>1</entry> - <entry>NTSC/PAL according to <xref linkend="smpte170m" />, -<xref linkend="itu601" /></entry> - <entry>x = 0.630, y = 0.340</entry> - <entry>x = 0.310, y = 0.595</entry> - <entry>x = 0.155, y = 0.070</entry> - <entry>x = 0.3127, y = 0.3290, - Illuminant D<subscript>65</subscript></entry> - <entry>E' = 4.5 I for I ≤0.018, -1.099 I<superscript>0.45</superscript> - 0.099 for 0.018 < I</entry> - <entry>0.299 E'<subscript>R</subscript> -+ 0.587 E'<subscript>G</subscript> -+ 0.114 E'<subscript>B</subscript></entry> - <entry>219 E'<subscript>Y</subscript> + 16</entry> - <entry>224 P<subscript>B,R</subscript> + 128</entry> + <entry>See <xref linkend="col-smpte-170m" />.</entry> </row> <row> - <entry><constant>V4L2_COLORSPACE_SMPTE240M</constant></entry> - <entry>2</entry> - <entry>1125-Line (US) HDTV, see <xref -linkend="smpte240m" /></entry> - <entry>x = 0.630, y = 0.340</entry> - <entry>x = 0.310, y = 0.595</entry> - <entry>x = 0.155, y = 0.070</entry> - <entry>x = 0.3127, y = 0.3290, - Illuminant D<subscript>65</subscript></entry> - <entry>E' = 4 I for I ≤0.0228, -1.1115 I<superscript>0.45</superscript> - 0.1115 for 0.0228 < I</entry> - <entry>0.212 E'<subscript>R</subscript> -+ 0.701 E'<subscript>G</subscript> -+ 0.087 E'<subscript>B</subscript></entry> - <entry>219 E'<subscript>Y</subscript> + 16</entry> - <entry>224 P<subscript>B,R</subscript> + 128</entry> + <entry><constant>V4L2_COLORSPACE_REC709</constant></entry> + <entry>See <xref linkend="col-rec709" />.</entry> </row> <row> - <entry><constant>V4L2_COLORSPACE_REC709</constant></entry> - <entry>3</entry> - <entry>HDTV and modern devices, see <xref -linkend="itu709" /></entry> - <entry>x = 0.640, y = 0.330</entry> - <entry>x = 0.300, y = 0.600</entry> - <entry>x = 0.150, y = 0.060</entry> - <entry>x = 0.3127, y = 0.3290, - Illuminant D<subscript>65</subscript></entry> - <entry>E' = 4.5 I for I ≤0.018, -1.099 I<superscript>0.45</superscript> - 0.099 for 0.018 < I</entry> - <entry>0.2125 E'<subscript>R</subscript> -+ 0.7154 E'<subscript>G</subscript> -+ 0.0721 E'<subscript>B</subscript></entry> - <entry>219 E'<subscript>Y</subscript> + 16</entry> - <entry>224 P<subscript>B,R</subscript> + 128</entry> + <entry><constant>V4L2_COLORSPACE_SRGB</constant></entry> + <entry>See <xref linkend="col-srgb" />.</entry> </row> <row> - <entry><constant>V4L2_COLORSPACE_BT878</constant></entry> - <entry>4</entry> - <entry>Broken Bt878 extents<footnote> - <para>The ubiquitous Bt878 video capture chip -quantizes E'<subscript>Y</subscript> to 238 levels, yielding a range -of Y' = 16 … 253, unlike Rec. 601 Y' = 16 … -235. This is not a typo in the Bt878 documentation, it has been -implemented in silicon. The chroma extents are unclear.</para> - </footnote>, <xref linkend="itu601" /></entry> - <entry>?</entry> - <entry>?</entry> - <entry>?</entry> - <entry>?</entry> - <entry>?</entry> - <entry>0.299 E'<subscript>R</subscript> -+ 0.587 E'<subscript>G</subscript> -+ 0.114 E'<subscript>B</subscript></entry> - <entry><emphasis>237</emphasis> E'<subscript>Y</subscript> + 16</entry> - <entry>224 P<subscript>B,R</subscript> + 128 (probably)</entry> + <entry><constant>V4L2_COLORSPACE_ADOBERGB</constant></entry> + <entry>See <xref linkend="col-adobergb" />.</entry> + </row> + <row> + <entry><constant>V4L2_COLORSPACE_BT2020</constant></entry> + <entry>See <xref linkend="col-bt2020" />.</entry> + </row> + <row> + <entry><constant>V4L2_COLORSPACE_SMPTE240M</constant></entry> + <entry>See <xref linkend="col-smpte-240m" />.</entry> </row> <row> <entry><constant>V4L2_COLORSPACE_470_SYSTEM_M</constant></entry> - <entry>5</entry> - <entry>M/NTSC<footnote> - <para>No identifier exists for M/PAL which uses -the chromaticities of M/NTSC, the remaining parameters are equal to B and -G/PAL.</para> - </footnote> according to <xref linkend="itu470" />, <xref - linkend="itu601" /></entry> - <entry>x = 0.67, y = 0.33</entry> - <entry>x = 0.21, y = 0.71</entry> - <entry>x = 0.14, y = 0.08</entry> - <entry>x = 0.310, y = 0.316, Illuminant C</entry> - <entry>?</entry> - <entry>0.299 E'<subscript>R</subscript> -+ 0.587 E'<subscript>G</subscript> -+ 0.114 E'<subscript>B</subscript></entry> - <entry>219 E'<subscript>Y</subscript> + 16</entry> - <entry>224 P<subscript>B,R</subscript> + 128</entry> + <entry>See <xref linkend="col-sysm" />.</entry> </row> <row> <entry><constant>V4L2_COLORSPACE_470_SYSTEM_BG</constant></entry> - <entry>6</entry> - <entry>625-line PAL and SECAM systems according to <xref -linkend="itu470" />, <xref linkend="itu601" /></entry> - <entry>x = 0.64, y = 0.33</entry> - <entry>x = 0.29, y = 0.60</entry> - <entry>x = 0.15, y = 0.06</entry> - <entry>x = 0.313, y = 0.329, -Illuminant D<subscript>65</subscript></entry> - <entry>?</entry> - <entry>0.299 E'<subscript>R</subscript> -+ 0.587 E'<subscript>G</subscript> -+ 0.114 E'<subscript>B</subscript></entry> - <entry>219 E'<subscript>Y</subscript> + 16</entry> - <entry>224 P<subscript>B,R</subscript> + 128</entry> + <entry>See <xref linkend="col-sysbg" />.</entry> </row> <row> <entry><constant>V4L2_COLORSPACE_JPEG</constant></entry> - <entry>7</entry> - <entry>JPEG Y'CbCr, see <xref linkend="jfif" />, <xref linkend="itu601" /></entry> - <entry>?</entry> - <entry>?</entry> - <entry>?</entry> - <entry>?</entry> - <entry>?</entry> - <entry>0.299 E'<subscript>R</subscript> -+ 0.587 E'<subscript>G</subscript> -+ 0.114 E'<subscript>B</subscript></entry> - <entry>256 E'<subscript>Y</subscript> + 16<footnote> - <para>Note JFIF quantizes -Y'P<subscript>B</subscript>P<subscript>R</subscript> in range [0;+1] and -[-0.5;+0.5] to <emphasis>257</emphasis> levels, however Y'CbCr signals -are still clamped to [0;255].</para> - </footnote></entry> - <entry>256 P<subscript>B,R</subscript> + 128</entry> + <entry>See <xref linkend="col-jpeg" />.</entry> </row> + </tbody> + </tgroup> + </table> + + <table pgwide="1" frame="none" id="v4l2-ycbcr-encoding"> + <title>V4L2 Y'CbCr Encodings</title> + <tgroup cols="2" align="left"> + &cs-def; + <thead> <row> - <entry><constant>V4L2_COLORSPACE_SRGB</constant></entry> - <entry>8</entry> - <entry>[?]</entry> - <entry>x = 0.640, y = 0.330</entry> - <entry>x = 0.300, y = 0.600</entry> - <entry>x = 0.150, y = 0.060</entry> - <entry>x = 0.3127, y = 0.3290, - Illuminant D<subscript>65</subscript></entry> - <entry>E' = 4.5 I for I ≤0.018, -1.099 I<superscript>0.45</superscript> - 0.099 for 0.018 < I</entry> - <entry spanname="spam">n/a</entry> + <entry>Identifier</entry> + <entry>Details</entry> + </row> + </thead> + <tbody valign="top"> + <row> + <entry><constant>V4L2_YCBCR_ENC_DEFAULT</constant></entry> + <entry>Use the default Y'CbCr encoding as defined by the colorspace.</entry> + </row> + <row> + <entry><constant>V4L2_YCBCR_ENC_601</constant></entry> + <entry>Use the BT.601 Y'CbCr encoding.</entry> + </row> + <row> + <entry><constant>V4L2_YCBCR_ENC_709</constant></entry> + <entry>Use the Rec. 709 Y'CbCr encoding.</entry> + </row> + <row> + <entry><constant>V4L2_YCBCR_ENC_XV601</constant></entry> + <entry>Use the extended gamut xvYCC BT.601 encoding.</entry> + </row> + <row> + <entry><constant>V4L2_YCBCR_ENC_XV709</constant></entry> + <entry>Use the extended gamut xvYCC Rec. 709 encoding.</entry> + </row> + <row> + <entry><constant>V4L2_YCBCR_ENC_SYCC</constant></entry> + <entry>Use the extended gamut sYCC encoding.</entry> + </row> + <row> + <entry><constant>V4L2_YCBCR_ENC_BT2020</constant></entry> + <entry>Use the default non-constant luminance BT.2020 Y'CbCr encoding.</entry> + </row> + <row> + <entry><constant>V4L2_YCBCR_ENC_BT2020_CONST_LUM</constant></entry> + <entry>Use the constant luminance BT.2020 Yc'CbcCrc encoding.</entry> + </row> + </tbody> + </tgroup> + </table> + + <table pgwide="1" frame="none" id="v4l2-quantization"> + <title>V4L2 Quantization Methods</title> + <tgroup cols="2" align="left"> + &cs-def; + <thead> + <row> + <entry>Identifier</entry> + <entry>Details</entry> + </row> + </thead> + <tbody valign="top"> + <row> + <entry><constant>V4L2_QUANTIZATION_DEFAULT</constant></entry> + <entry>Use the default quantization encoding as defined by the colorspace. +This is always full range for R'G'B' and usually limited range for Y'CbCr.</entry> + </row> + <row> + <entry><constant>V4L2_QUANTIZATION_FULL_RANGE</constant></entry> + <entry>Use the full range quantization encoding. I.e. the range [0…1] +is mapped to [0…255] (with possible clipping to [1…254] to avoid the +0x00 and 0xff values). Cb and Cr are mapped from [-0.5…0.5] to [0…255] +(with possible clipping to [1…254] to avoid the 0x00 and 0xff values).</entry> + </row> + <row> + <entry><constant>V4L2_QUANTIZATION_LIM_RANGE</constant></entry> + <entry>Use the limited range quantization encoding. I.e. the range [0…1] +is mapped to [16…235]. Cb and Cr are mapped from [-0.5…0.5] to [16…240]. +</entry> </row> </tbody> </tgroup> </table> </section> + <section> + <title>Detailed Colorspace Descriptions</title> + <section> + <title id="col-smpte-170m">Colorspace SMPTE 170M (<constant>V4L2_COLORSPACE_SMPTE170M</constant>)</title> + <para>The <xref linkend="smpte170m" /> standard defines the colorspace used by NTSC and PAL and by SDTV +in general. The default Y'CbCr encoding is <constant>V4L2_YCBCR_ENC_601</constant>. +The default Y'CbCr quantization is limited range. The chromaticities of the primary colors and +the white reference are:</para> + <table frame="none"> + <title>SMPTE 170M Chromaticities</title> + <tgroup cols="3" align="left"> + &cs-str; + <thead> + <row> + <entry>Color</entry> + <entry>x</entry> + <entry>y</entry> + </row> + </thead> + <tbody valign="top"> + <row> + <entry>Red</entry> + <entry>0.630</entry> + <entry>0.340</entry> + </row> + <row> + <entry>Green</entry> + <entry>0.310</entry> + <entry>0.595</entry> + </row> + <row> + <entry>Blue</entry> + <entry>0.155</entry> + <entry>0.070</entry> + </row> + <row> + <entry>White Reference (D65)</entry> + <entry>0.3127</entry> + <entry>0.3290</entry> + </row> + </tbody> + </tgroup> + </table> + <para>The red, green and blue chromaticities are also often referred to +as the SMPTE C set, so this colorspace is sometimes called SMPTE C as well.</para> + <variablelist> + <varlistentry> + <term>The transfer function defined for SMPTE 170M is the same as the +one defined in Rec. 709. Normally L is in the range [0…1], but for the extended +gamut xvYCC encoding values outside that range are allowed.</term> + <listitem> + <para>L' = -1.099(-L)<superscript>0.45</superscript> + 0.099 for L ≤ -0.018</para> + <para>L' = 4.5L for -0.018 < L < 0.018</para> + <para>L' = 1.099L<superscript>0.45</superscript> - 0.099 for L ≥ 0.018</para> + </listitem> + </varlistentry> + </variablelist> + <variablelist> + <varlistentry> + <term>Inverse Transfer function:</term> + <listitem> + <para>L = -((L' - 0.099) / -1.099)<superscript>1/0.45</superscript> for L' ≤ -0.081</para> + <para>L = L' / 4.5 for -0.081 < L' < 0.081</para> + <para>L = ((L' + 0.099) / 1.099)<superscript>1/0.45</superscript> for L' ≥ 0.081</para> + </listitem> + </varlistentry> + </variablelist> + <variablelist> + <varlistentry> + <term>The luminance (Y') and color difference (Cb and Cr) are obtained with +the following <constant>V4L2_YCBCR_ENC_601</constant> encoding:</term> + <listitem> + <para>Y' = 0.299R' + 0.587G' + 0.114B'</para> + <para>Cb = -0.169R' - 0.331G' + 0.5B'</para> + <para>Cr = 0.5R' - 0.419G' - 0.081B'</para> + </listitem> + </varlistentry> + </variablelist> + <para>Y' is clamped to the range [0…1] and Cb and Cr are +clamped to the range [-0.5…0.5]. This conversion to Y'CbCr is identical to the one +defined in the <xref linkend="itu601" /> standard and this colorspace is sometimes called BT.601 as well, even +though BT.601 does not mention any color primaries.</para> + <para>The default quantization is limited range, but full range is possible although +rarely seen.</para> + <para>The <constant>V4L2_YCBCR_ENC_601</constant> encoding as described above is the +default for this colorspace, but it can be overridden with <constant>V4L2_YCBCR_ENC_709</constant>, +in which case the Rec. 709 Y'CbCr encoding is used.</para> + <variablelist> + <varlistentry> + <term>The xvYCC 601 encoding (<constant>V4L2_YCBCR_ENC_XV601</constant>, <xref linkend="xvycc" />) is similar +to the BT.601 encoding, but it allows for R', G' and B' values that are outside the range +[0…1]. The resulting Y', Cb and Cr values are scaled and offset:</term> + <listitem> + <para>Y' = (219 / 255) * (0.299R' + 0.587G' + 0.114B') + (16 / 255)</para> + <para>Cb = (224 / 255) * (-0.169R' - 0.331G' + 0.5B')</para> + <para>Cr = (224 / 255) * (0.5R' - 0.419G' - 0.081B')</para> + </listitem> + </varlistentry> + </variablelist> + <para>Y' is clamped to the range [0…1] and Cb and Cr are clamped +to the range [-0.5…0.5]. The non-standard xvYCC 709 encoding can also be used by selecting +<constant>V4L2_YCBCR_ENC_XV709</constant>. The xvYCC encodings always use full range +quantization.</para> + </section> + + <section> + <title id="col-rec709">Colorspace Rec. 709 (<constant>V4L2_COLORSPACE_REC709</constant>)</title> + <para>The <xref linkend="itu709" /> standard defines the colorspace used by HDTV in general. The default +Y'CbCr encoding is <constant>V4L2_YCBCR_ENC_709</constant>. The default Y'CbCr quantization is +limited range. The chromaticities of the primary colors and the white reference are:</para> + <table frame="none"> + <title>Rec. 709 Chromaticities</title> + <tgroup cols="3" align="left"> + &cs-str; + <thead> + <row> + <entry>Color</entry> + <entry>x</entry> + <entry>y</entry> + </row> + </thead> + <tbody valign="top"> + <row> + <entry>Red</entry> + <entry>0.640</entry> + <entry>0.330</entry> + </row> + <row> + <entry>Green</entry> + <entry>0.300</entry> + <entry>0.600</entry> + </row> + <row> + <entry>Blue</entry> + <entry>0.150</entry> + <entry>0.060</entry> + </row> + <row> + <entry>White Reference (D65)</entry> + <entry>0.3127</entry> + <entry>0.3290</entry> + </row> + </tbody> + </tgroup> + </table> + <para>The full name of this standard is Rec. ITU-R BT.709-5.</para> + <variablelist> + <varlistentry> + <term>Transfer function. Normally L is in the range [0…1], but for the extended +gamut xvYCC encoding values outside that range are allowed.</term> + <listitem> + <para>L' = -1.099(-L)<superscript>0.45</superscript> + 0.099 for L ≤ -0.018</para> + <para>L' = 4.5L for -0.018 < L < 0.018</para> + <para>L' = 1.099L<superscript>0.45</superscript> - 0.099 for L ≥ 0.018</para> + </listitem> + </varlistentry> + </variablelist> + <variablelist> + <varlistentry> + <term>Inverse Transfer function:</term> + <listitem> + <para>L = -((L' - 0.099) / -1.099)<superscript>1/0.45</superscript> for L' ≤ -0.081</para> + <para>L = L' / 4.5 for -0.081 < L' < 0.081</para> + <para>L = ((L' + 0.099) / 1.099)<superscript>1/0.45</superscript> for L' ≥ 0.081</para> + </listitem> + </varlistentry> + </variablelist> + <variablelist> + <varlistentry> + <term>The luminance (Y') and color difference (Cb and Cr) are obtained with the following +<constant>V4L2_YCBCR_ENC_709</constant> encoding:</term> + <listitem> + <para>Y' = 0.2126R' + 0.7152G' + 0.0722B'</para> + <para>Cb = -0.1146R' - 0.3854G' + 0.5B'</para> + <para>Cr = 0.5R' - 0.4542G' - 0.0458B'</para> + </listitem> + </varlistentry> + </variablelist> + <para>Y' is clamped to the range [0…1] and Cb and Cr are +clamped to the range [-0.5…0.5].</para> + <para>The default quantization is limited range, but full range is possible although +rarely seen.</para> + <para>The <constant>V4L2_YCBCR_ENC_709</constant> encoding described above is the default +for this colorspace, but it can be overridden with <constant>V4L2_YCBCR_ENC_601</constant>, in which +case the BT.601 Y'CbCr encoding is used.</para> + <variablelist> + <varlistentry> + <term>The xvYCC 709 encoding (<constant>V4L2_YCBCR_ENC_XV709</constant>, <xref linkend="xvycc" />) +is similar to the Rec. 709 encoding, but it allows for R', G' and B' values that are outside the range +[0…1]. The resulting Y', Cb and Cr values are scaled and offset:</term> + <listitem> + <para>Y' = (219 / 255) * (0.2126R' + 0.7152G' + 0.0722B') + (16 / 255)</para> + <para>Cb = (224 / 255) * (-0.1146R' - 0.3854G' + 0.5B')</para> + <para>Cr = (224 / 255) * (0.5R' - 0.4542G' - 0.0458B')</para> + </listitem> + </varlistentry> + </variablelist> + <para>Y' is clamped to the range [0…1] and Cb and Cr are clamped +to the range [-0.5…0.5]. The non-standard xvYCC 601 encoding can also be used by +selecting <constant>V4L2_YCBCR_ENC_XV601</constant>. The xvYCC encodings always use full +range quantization.</para> + </section> + + <section> + <title id="col-srgb">Colorspace sRGB (<constant>V4L2_COLORSPACE_SRGB</constant>)</title> + <para>The <xref linkend="srgb" /> standard defines the colorspace used by most webcams and computer graphics. The +default Y'CbCr encoding is <constant>V4L2_YCBCR_ENC_SYCC</constant>. The default Y'CbCr quantization +is full range. The chromaticities of the primary colors and the white reference are:</para> + <table frame="none"> + <title>sRGB Chromaticities</title> + <tgroup cols="3" align="left"> + &cs-str; + <thead> + <row> + <entry>Color</entry> + <entry>x</entry> + <entry>y</entry> + </row> + </thead> + <tbody valign="top"> + <row> + <entry>Red</entry> + <entry>0.640</entry> + <entry>0.330</entry> + </row> + <row> + <entry>Green</entry> + <entry>0.300</entry> + <entry>0.600</entry> + </row> + <row> + <entry>Blue</entry> + <entry>0.150</entry> + <entry>0.060</entry> + </row> + <row> + <entry>White Reference (D65)</entry> + <entry>0.3127</entry> + <entry>0.3290</entry> + </row> + </tbody> + </tgroup> + </table> + <para>These chromaticities are identical to the Rec. 709 colorspace.</para> + <variablelist> + <varlistentry> + <term>Transfer function. Note that negative values for L are only used by the Y'CbCr conversion.</term> + <listitem> + <para>L' = -1.055(-L)<superscript>1/2.4</superscript> + 0.055 for L < -0.0031308</para> + <para>L' = 12.92L for -0.0031308 ≤ L ≤ 0.0031308</para> + <para>L' = 1.055L<superscript>1/2.4</superscript> - 0.055 for 0.0031308 < L ≤ 1</para> + </listitem> + </varlistentry> + <varlistentry> + <term>Inverse Transfer function:</term> + <listitem> + <para>L = -((-L' + 0.055) / 1.055)<superscript>2.4</superscript> for L' < -0.04045</para> + <para>L = L' / 12.92 for -0.04045 ≤ L' ≤ 0.04045</para> + <para>L = ((L' + 0.055) / 1.055)<superscript>2.4</superscript> for L' > 0.04045</para> + </listitem> + </varlistentry> + </variablelist> + <variablelist> + <varlistentry> + <term>The luminance (Y') and color difference (Cb and Cr) are obtained with the following +<constant>V4L2_YCBCR_ENC_SYCC</constant> encoding as defined by <xref linkend="sycc" />:</term> + <listitem> + <para>Y' = 0.2990R' + 0.5870G' + 0.1140B'</para> + <para>Cb = -0.1687R' - 0.3313G' + 0.5B'</para> + <para>Cr = 0.5R' - 0.4187G' - 0.0813B'</para> + </listitem> + </varlistentry> + </variablelist> + <para>Y' is clamped to the range [0…1] and Cb and Cr are clamped +to the range [-0.5…0.5]. The <constant>V4L2_YCBCR_ENC_SYCC</constant> quantization is always +full range. Although this Y'CbCr encoding looks very similar to the <constant>V4L2_YCBCR_ENC_XV601</constant> +encoding, it is not. The <constant>V4L2_YCBCR_ENC_XV601</constant> scales and offsets the Y'CbCr +values before quantization, but this encoding does not do that.</para> + </section> + + <section> + <title id="col-adobergb">Colorspace Adobe RGB (<constant>V4L2_COLORSPACE_ADOBERGB</constant>)</title> + <para>The <xref linkend="adobergb" /> standard defines the colorspace used by computer graphics +that use the AdobeRGB colorspace. This is also known as the <xref linkend="oprgb" /> standard. +The default Y'CbCr encoding is <constant>V4L2_YCBCR_ENC_601</constant>. The default Y'CbCr +quantization is limited range. The chromaticities of the primary colors and the white reference +are:</para> + <table frame="none"> + <title>Adobe RGB Chromaticities</title> + <tgroup cols="3" align="left"> + &cs-str; + <thead> + <row> + <entry>Color</entry> + <entry>x</entry> + <entry>y</entry> + </row> + </thead> + <tbody valign="top"> + <row> + <entry>Red</entry> + <entry>0.6400</entry> + <entry>0.3300</entry> + </row> + <row> + <entry>Green</entry> + <entry>0.2100</entry> + <entry>0.7100</entry> + </row> + <row> + <entry>Blue</entry> + <entry>0.1500</entry> + <entry>0.0600</entry> + </row> + <row> + <entry>White Reference (D65)</entry> + <entry>0.3127</entry> + <entry>0.3290</entry> + </row> + </tbody> + </tgroup> + </table> + <variablelist> + <varlistentry> + <term>Transfer function:</term> + <listitem> + <para>L' = L<superscript>1/2.19921875</superscript></para> + </listitem> + </varlistentry> + <varlistentry> + <term>Inverse Transfer function:</term> + <listitem> + <para>L = L'<superscript>2.19921875</superscript></para> + </listitem> + </varlistentry> + </variablelist> + <variablelist> + <varlistentry> + <term>The luminance (Y') and color difference (Cb and Cr) are obtained with the +following <constant>V4L2_YCBCR_ENC_601</constant> encoding:</term> + <listitem> + <para>Y' = 0.299R' + 0.587G' + 0.114B'</para> + <para>Cb = -0.169R' - 0.331G' + 0.5B'</para> + <para>Cr = 0.5R' - 0.419G' - 0.081B'</para> + </listitem> + </varlistentry> + </variablelist> + <para>Y' is clamped to the range [0…1] and Cb and Cr are +clamped to the range [-0.5…0.5]. This transform is identical to one defined in +SMPTE 170M/BT.601. The Y'CbCr quantization is limited range.</para> + </section> + + <section> + <title id="col-bt2020">Colorspace BT.2020 (<constant>V4L2_COLORSPACE_BT2020</constant>)</title> + <para>The <xref linkend="itu2020" /> standard defines the colorspace used by Ultra-high definition +television (UHDTV). The default Y'CbCr encoding is <constant>V4L2_YCBCR_ENC_BT2020</constant>. +The default Y'CbCr quantization is limited range. The chromaticities of the primary colors and +the white reference are:</para> + <table frame="none"> + <title>BT.2020 Chromaticities</title> + <tgroup cols="3" align="left"> + &cs-str; + <thead> + <row> + <entry>Color</entry> + <entry>x</entry> + <entry>y</entry> + </row> + </thead> + <tbody valign="top"> + <row> + <entry>Red</entry> + <entry>0.708</entry> + <entry>0.292</entry> + </row> + <row> + <entry>Green</entry> + <entry>0.170</entry> + <entry>0.797</entry> + </row> + <row> + <entry>Blue</entry> + <entry>0.131</entry> + <entry>0.046</entry> + </row> + <row> + <entry>White Reference (D65)</entry> + <entry>0.3127</entry> + <entry>0.3290</entry> + </row> + </tbody> + </tgroup> + </table> + <variablelist> + <varlistentry> + <term>Transfer function (same as Rec. 709):</term> + <listitem> + <para>L' = 4.5L for 0 ≤ L < 0.018</para> + <para>L' = 1.099L<superscript>0.45</superscript> - 0.099 for 0.018 ≤ L ≤ 1</para> + </listitem> + </varlistentry> + <varlistentry> + <term>Inverse Transfer function:</term> + <listitem> + <para>L = L' / 4.5 for L' < 0.081</para> + <para>L = ((L' + 0.099) / 1.099)<superscript>1/0.45</superscript> for L' ≥ 0.081</para> + </listitem> + </varlistentry> + </variablelist> + <variablelist> + <varlistentry> + <term>The luminance (Y') and color difference (Cb and Cr) are obtained with the +following <constant>V4L2_YCBCR_ENC_BT2020</constant> encoding:</term> + <listitem> + <para>Y' = 0.2627R' + 0.6789G' + 0.0593B'</para> + <para>Cb = -0.1396R' - 0.3604G' + 0.5B'</para> + <para>Cr = 0.5R' - 0.4598G' - 0.0402B'</para> + </listitem> + </varlistentry> + </variablelist> + <para>Y' is clamped to the range [0…1] and Cb and Cr are +clamped to the range [-0.5…0.5]. The Y'CbCr quantization is limited range.</para> + <para>There is also an alternate constant luminance R'G'B' to Yc'CbcCrc +(<constant>V4L2_YCBCR_ENC_BT2020_CONST_LUM</constant>) encoding:</para> + <variablelist> + <varlistentry> + <term>Luma:</term> + <listitem> + <para>Yc' = (0.2627R + 0.6789G + 0.0593B)'</para> + </listitem> + </varlistentry> + </variablelist> + <variablelist> + <varlistentry> + <term>B' - Yc' ≤ 0:</term> + <listitem> + <para>Cbc = (B' - Y') / 1.9404</para> + </listitem> + </varlistentry> + </variablelist> + <variablelist> + <varlistentry> + <term>B' - Yc' > 0:</term> + <listitem> + <para>Cbc = (B' - Y') / 1.5816</para> + </listitem> + </varlistentry> + </variablelist> + <variablelist> + <varlistentry> + <term>R' - Yc' ≤ 0:</term> + <listitem> + <para>Crc = (R' - Y') / 1.7184</para> + </listitem> + </varlistentry> + </variablelist> + <variablelist> + <varlistentry> + <term>R' - Yc' > 0:</term> + <listitem> + <para>Crc = (R' - Y') / 0.9936</para> + </listitem> + </varlistentry> + </variablelist> + <para>Yc' is clamped to the range [0…1] and Cbc and Crc are +clamped to the range [-0.5…0.5]. The Yc'CbcCrc quantization is limited range.</para> + </section> + + <section> + <title id="col-smpte-240m">Colorspace SMPTE 240M (<constant>V4L2_COLORSPACE_SMPTE240M</constant>)</title> + <para>The <xref linkend="smpte240m" /> standard was an interim standard used during the early days of HDTV (1988-1998). +It has been superseded by Rec. 709. The default Y'CbCr encoding is <constant>V4L2_YCBCR_ENC_SMPTE240M</constant>. +The default Y'CbCr quantization is limited range. The chromaticities of the primary colors and the +white reference are:</para> + <table frame="none"> + <title>SMPTE 240M Chromaticities</title> + <tgroup cols="3" align="left"> + &cs-str; + <thead> + <row> + <entry>Color</entry> + <entry>x</entry> + <entry>y</entry> + </row> + </thead> + <tbody valign="top"> + <row> + <entry>Red</entry> + <entry>0.630</entry> + <entry>0.340</entry> + </row> + <row> + <entry>Green</entry> + <entry>0.310</entry> + <entry>0.595</entry> + </row> + <row> + <entry>Blue</entry> + <entry>0.155</entry> + <entry>0.070</entry> + </row> + <row> + <entry>White Reference (D65)</entry> + <entry>0.3127</entry> + <entry>0.3290</entry> + </row> + </tbody> + </tgroup> + </table> + <para>These chromaticities are identical to the SMPTE 170M colorspace.</para> + <variablelist> + <varlistentry> + <term>Transfer function:</term> + <listitem> + <para>L' = 4L for 0 ≤ L < 0.0228</para> + <para>L' = 1.1115L<superscript>0.45</superscript> - 0.1115 for 0.0228 ≤ L ≤ 1</para> + </listitem> + </varlistentry> + <varlistentry> + <term>Inverse Transfer function:</term> + <listitem> + <para>L = L' / 4 for 0 ≤ L' < 0.0913</para> + <para>L = ((L' + 0.1115) / 1.1115)<superscript>1/0.45</superscript> for L' ≥ 0.0913</para> + </listitem> + </varlistentry> + </variablelist> + <variablelist> + <varlistentry> + <term>The luminance (Y') and color difference (Cb and Cr) are obtained with the +following <constant>V4L2_YCBCR_ENC_SMPTE240M</constant> encoding:</term> + <listitem> + <para>Y' = 0.2122R' + 0.7013G' + 0.0865B'</para> + <para>Cb = -0.1161R' - 0.3839G' + 0.5B'</para> + <para>Cr = 0.5R' - 0.4451G' - 0.0549B'</para> + </listitem> + </varlistentry> + </variablelist> + <para>Yc' is clamped to the range [0…1] and Cbc and Crc are +clamped to the range [-0.5…0.5]. The Y'CbCr quantization is limited range.</para> + </section> + + <section> + <title id="col-sysm">Colorspace NTSC 1953 (<constant>V4L2_COLORSPACE_470_SYSTEM_M</constant>)</title> + <para>This standard defines the colorspace used by NTSC in 1953. In practice this +colorspace is obsolete and SMPTE 170M should be used instead. The default Y'CbCr encoding +is <constant>V4L2_YCBCR_ENC_601</constant>. The default Y'CbCr quantization is limited range. +The chromaticities of the primary colors and the white reference are:</para> + <table frame="none"> + <title>NTSC 1953 Chromaticities</title> + <tgroup cols="3" align="left"> + &cs-str; + <thead> + <row> + <entry>Color</entry> + <entry>x</entry> + <entry>y</entry> + </row> + </thead> + <tbody valign="top"> + <row> + <entry>Red</entry> + <entry>0.67</entry> + <entry>0.33</entry> + </row> + <row> + <entry>Green</entry> + <entry>0.21</entry> + <entry>0.71</entry> + </row> + <row> + <entry>Blue</entry> + <entry>0.14</entry> + <entry>0.08</entry> + </row> + <row> + <entry>White Reference (C)</entry> + <entry>0.310</entry> + <entry>0.316</entry> + </row> + </tbody> + </tgroup> + </table> + <para>Note that this colorspace uses Illuminant C instead of D65 as the +white reference. To correctly convert an image in this colorspace to another +that uses D65 you need to apply a chromatic adaptation algorithm such as the +Bradford method.</para> + <variablelist> + <varlistentry> + <term>The transfer function was never properly defined for NTSC 1953. The +Rec. 709 transfer function is recommended in the literature:</term> + <listitem> + <para>L' = 4.5L for 0 ≤ L < 0.018</para> + <para>L' = 1.099L<superscript>0.45</superscript> - 0.099 for 0.018 ≤ L ≤ 1</para> + </listitem> + </varlistentry> + <varlistentry> + <term>Inverse Transfer function:</term> + <listitem> + <para>L = L' / 4.5 for L' < 0.081</para> + <para>L = ((L' + 0.099) / 1.099)<superscript>1/0.45</superscript> for L' ≥ 0.081</para> + </listitem> + </varlistentry> + </variablelist> + <variablelist> + <varlistentry> + <term>The luminance (Y') and color difference (Cb and Cr) are obtained with the +following <constant>V4L2_YCBCR_ENC_601</constant> encoding:</term> + <listitem> + <para>Y' = 0.299R' + 0.587G' + 0.114B'</para> + <para>Cb = -0.169R' - 0.331G' + 0.5B'</para> + <para>Cr = 0.5R' - 0.419G' - 0.081B'</para> + </listitem> + </varlistentry> + </variablelist> + <para>Y' is clamped to the range [0…1] and Cb and Cr are +clamped to the range [-0.5…0.5]. The Y'CbCr quantization is limited range. +This transform is identical to one defined in SMPTE 170M/BT.601.</para> + </section> + + <section> + <title id="col-sysbg">Colorspace EBU Tech. 3213 (<constant>V4L2_COLORSPACE_470_SYSTEM_BG</constant>)</title> + <para>The <xref linkend="tech3213" /> standard defines the colorspace used by PAL/SECAM in 1975. In practice this +colorspace is obsolete and SMPTE 170M should be used instead. The default Y'CbCr encoding +is <constant>V4L2_YCBCR_ENC_601</constant>. The default Y'CbCr quantization is limited range. +The chromaticities of the primary colors and the white reference are:</para> + <table frame="none"> + <title>EBU Tech. 3213 Chromaticities</title> + <tgroup cols="3" align="left"> + &cs-str; + <thead> + <row> + <entry>Color</entry> + <entry>x</entry> + <entry>y</entry> + </row> + </thead> + <tbody valign="top"> + <row> + <entry>Red</entry> + <entry>0.64</entry> + <entry>0.33</entry> + </row> + <row> + <entry>Green</entry> + <entry>0.29</entry> + <entry>0.60</entry> + </row> + <row> + <entry>Blue</entry> + <entry>0.15</entry> + <entry>0.06</entry> + </row> + <row> + <entry>White Reference (D65)</entry> + <entry>0.3127</entry> + <entry>0.3290</entry> + </row> + </tbody> + </tgroup> + </table> + <variablelist> + <varlistentry> + <term>The transfer function was never properly defined for this colorspace. +The Rec. 709 transfer function is recommended in the literature:</term> + <listitem> + <para>L' = 4.5L for 0 ≤ L < 0.018</para> + <para>L' = 1.099L<superscript>0.45</superscript> - 0.099 for 0.018 ≤ L ≤ 1</para> + </listitem> + </varlistentry> + <varlistentry> + <term>Inverse Transfer function:</term> + <listitem> + <para>L = L' / 4.5 for L' < 0.081</para> + <para>L = ((L' + 0.099) / 1.099)<superscript>1/0.45</superscript> for L' ≥ 0.081</para> + </listitem> + </varlistentry> + </variablelist> + <variablelist> + <varlistentry> + <term>The luminance (Y') and color difference (Cb and Cr) are obtained with the +following <constant>V4L2_YCBCR_ENC_601</constant> encoding:</term> + <listitem> + <para>Y' = 0.299R' + 0.587G' + 0.114B'</para> + <para>Cb = -0.169R' - 0.331G' + 0.5B'</para> + <para>Cr = 0.5R' - 0.419G' - 0.081B'</para> + </listitem> + </varlistentry> + </variablelist> + <para>Y' is clamped to the range [0…1] and Cb and Cr are +clamped to the range [-0.5…0.5]. The Y'CbCr quantization is limited range. +This transform is identical to one defined in SMPTE 170M/BT.601.</para> + </section> + + <section> + <title id="col-jpeg">Colorspace JPEG (<constant>V4L2_COLORSPACE_JPEG</constant>)</title> + <para>This colorspace defines the colorspace used by most (Motion-)JPEG formats. The chromaticities +of the primary colors and the white reference are identical to sRGB. The Y'CbCr encoding is +<constant>V4L2_YCBCR_ENC_601</constant> with full range quantization where +Y' is scaled to [0…255] and Cb/Cr are scaled to [-128…128] and +then clipped to [-128…127].</para> + <para>Note that the JPEG standard does not actually store colorspace information. +So if something other than sRGB is used, then the driver will have to set that information +explicitly. Effectively <constant>V4L2_COLORSPACE_JPEG</constant> can be considered to be +an abbreviation for <constant>V4L2_COLORSPACE_SRGB</constant>, <constant>V4L2_YCBCR_ENC_601</constant> +and <constant>V4L2_QUANTIZATION_FULL_RANGE</constant>.</para> + </section> + + </section> + <section id="pixfmt-indexed"> <title>Indexed Format</title> @@ -713,6 +1405,7 @@ access the palette, this must be done with ioctls of the Linux framebuffer API.< &sub-srggb8; &sub-sbggr16; &sub-srggb10; + &sub-srggb10p; &sub-srggb10alaw8; &sub-srggb10dpcm8; &sub-srggb12; diff --git a/Documentation/DocBook/media/v4l/selections-common.xml b/Documentation/DocBook/media/v4l/selections-common.xml index 7502f784b8cc..d6d56fb6f9c0 100644 --- a/Documentation/DocBook/media/v4l/selections-common.xml +++ b/Documentation/DocBook/media/v4l/selections-common.xml @@ -63,6 +63,22 @@ <entry>Yes</entry> </row> <row> + <entry><constant>V4L2_SEL_TGT_NATIVE_SIZE</constant></entry> + <entry>0x0003</entry> + <entry>The native size of the device, e.g. a sensor's + pixel array. <structfield>left</structfield> and + <structfield>top</structfield> fields are zero for this + target. Setting the native size will generally only make + sense for memory to memory devices where the software can + create a canvas of a given size in which for example a + video frame can be composed. In that case + V4L2_SEL_TGT_NATIVE_SIZE can be used to configure the size + of that canvas. + </entry> + <entry>Yes</entry> + <entry>Yes</entry> + </row> + <row> <entry><constant>V4L2_SEL_TGT_COMPOSE</constant></entry> <entry>0x0100</entry> <entry>Compose rectangle. Used to configure scaling diff --git a/Documentation/DocBook/media/v4l/subdev-formats.xml b/Documentation/DocBook/media/v4l/subdev-formats.xml index b2d5a0363cba..c5ea868e3909 100644 --- a/Documentation/DocBook/media/v4l/subdev-formats.xml +++ b/Documentation/DocBook/media/v4l/subdev-formats.xml @@ -34,8 +34,24 @@ <xref linkend="colorspaces" /> for details.</entry> </row> <row> + <entry>&v4l2-ycbcr-encoding;</entry> + <entry><structfield>ycbcr_enc</structfield></entry> + <entry>This information supplements the +<structfield>colorspace</structfield> and must be set by the driver for +capture streams and by the application for output streams, +see <xref linkend="colorspaces" />.</entry> + </row> + <row> + <entry>&v4l2-quantization;</entry> + <entry><structfield>quantization</structfield></entry> + <entry>This information supplements the +<structfield>colorspace</structfield> and must be set by the driver for +capture streams and by the application for output streams, +see <xref linkend="colorspaces" />.</entry> + </row> + <row> <entry>__u32</entry> - <entry><structfield>reserved</structfield>[7]</entry> + <entry><structfield>reserved</structfield>[6]</entry> <entry>Reserved for future extensions. Applications and drivers must set the array to zero.</entry> </row> @@ -86,7 +102,7 @@ green and 5-bit blue values padded on the high bit, transferred as 2 8-bit samples per pixel with the most significant bits (padding, red and half of the green value) transferred first will be named - <constant>V4L2_MBUS_FMT_RGB555_2X8_PADHI_BE</constant>. + <constant>MEDIA_BUS_FMT_RGB555_2X8_PADHI_BE</constant>. </para> <para>The following tables list existing packed RGB formats.</para> @@ -176,8 +192,8 @@ </row> </thead> <tbody valign="top"> - <row id="V4L2-MBUS-FMT-RGB444-2X8-PADHI-BE"> - <entry>V4L2_MBUS_FMT_RGB444_2X8_PADHI_BE</entry> + <row id="MEDIA-BUS-FMT-RGB444-2X8-PADHI-BE"> + <entry>MEDIA_BUS_FMT_RGB444_2X8_PADHI_BE</entry> <entry>0x1001</entry> <entry></entry> &dash-ent-24; @@ -204,8 +220,8 @@ <entry>b<subscript>1</subscript></entry> <entry>b<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-RGB444-2X8-PADHI-LE"> - <entry>V4L2_MBUS_FMT_RGB444_2X8_PADHI_LE</entry> + <row id="MEDIA-BUS-FMT-RGB444-2X8-PADHI-LE"> + <entry>MEDIA_BUS_FMT_RGB444_2X8_PADHI_LE</entry> <entry>0x1002</entry> <entry></entry> &dash-ent-24; @@ -232,8 +248,8 @@ <entry>r<subscript>1</subscript></entry> <entry>r<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-RGB555-2X8-PADHI-BE"> - <entry>V4L2_MBUS_FMT_RGB555_2X8_PADHI_BE</entry> + <row id="MEDIA-BUS-FMT-RGB555-2X8-PADHI-BE"> + <entry>MEDIA_BUS_FMT_RGB555_2X8_PADHI_BE</entry> <entry>0x1003</entry> <entry></entry> &dash-ent-24; @@ -260,8 +276,8 @@ <entry>b<subscript>1</subscript></entry> <entry>b<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-RGB555-2X8-PADHI-LE"> - <entry>V4L2_MBUS_FMT_RGB555_2X8_PADHI_LE</entry> + <row id="MEDIA-BUS-FMT-RGB555-2X8-PADHI-LE"> + <entry>MEDIA_BUS_FMT_RGB555_2X8_PADHI_LE</entry> <entry>0x1004</entry> <entry></entry> &dash-ent-24; @@ -288,8 +304,8 @@ <entry>g<subscript>4</subscript></entry> <entry>g<subscript>3</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-BGR565-2X8-BE"> - <entry>V4L2_MBUS_FMT_BGR565_2X8_BE</entry> + <row id="MEDIA-BUS-FMT-BGR565-2X8-BE"> + <entry>MEDIA_BUS_FMT_BGR565_2X8_BE</entry> <entry>0x1005</entry> <entry></entry> &dash-ent-24; @@ -316,8 +332,8 @@ <entry>r<subscript>1</subscript></entry> <entry>r<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-BGR565-2X8-LE"> - <entry>V4L2_MBUS_FMT_BGR565_2X8_LE</entry> + <row id="MEDIA-BUS-FMT-BGR565-2X8-LE"> + <entry>MEDIA_BUS_FMT_BGR565_2X8_LE</entry> <entry>0x1006</entry> <entry></entry> &dash-ent-24; @@ -344,8 +360,8 @@ <entry>g<subscript>4</subscript></entry> <entry>g<subscript>3</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-RGB565-2X8-BE"> - <entry>V4L2_MBUS_FMT_RGB565_2X8_BE</entry> + <row id="MEDIA-BUS-FMT-RGB565-2X8-BE"> + <entry>MEDIA_BUS_FMT_RGB565_2X8_BE</entry> <entry>0x1007</entry> <entry></entry> &dash-ent-24; @@ -372,8 +388,8 @@ <entry>b<subscript>1</subscript></entry> <entry>b<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-RGB565-2X8-LE"> - <entry>V4L2_MBUS_FMT_RGB565_2X8_LE</entry> + <row id="MEDIA-BUS-FMT-RGB565-2X8-LE"> + <entry>MEDIA_BUS_FMT_RGB565_2X8_LE</entry> <entry>0x1008</entry> <entry></entry> &dash-ent-24; @@ -400,8 +416,8 @@ <entry>g<subscript>4</subscript></entry> <entry>g<subscript>3</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-RGB666-1X18"> - <entry>V4L2_MBUS_FMT_RGB666_1X18</entry> + <row id="MEDIA-BUS-FMT-RGB666-1X18"> + <entry>MEDIA_BUS_FMT_RGB666_1X18</entry> <entry>0x1009</entry> <entry></entry> &dash-ent-14; @@ -424,8 +440,8 @@ <entry>b<subscript>1</subscript></entry> <entry>b<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-RGB888-1X24"> - <entry>V4L2_MBUS_FMT_RGB888_1X24</entry> + <row id="MEDIA-BUS-FMT-RGB888-1X24"> + <entry>MEDIA_BUS_FMT_RGB888_1X24</entry> <entry>0x100a</entry> <entry></entry> &dash-ent-8; @@ -454,8 +470,8 @@ <entry>b<subscript>1</subscript></entry> <entry>b<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-RGB888-2X12-BE"> - <entry>V4L2_MBUS_FMT_RGB888_2X12_BE</entry> + <row id="MEDIA-BUS-FMT-RGB888-2X12-BE"> + <entry>MEDIA_BUS_FMT_RGB888_2X12_BE</entry> <entry>0x100b</entry> <entry></entry> &dash-ent-20; @@ -490,8 +506,8 @@ <entry>b<subscript>1</subscript></entry> <entry>b<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-RGB888-2X12-LE"> - <entry>V4L2_MBUS_FMT_RGB888_2X12_LE</entry> + <row id="MEDIA-BUS-FMT-RGB888-2X12-LE"> + <entry>MEDIA_BUS_FMT_RGB888_2X12_LE</entry> <entry>0x100c</entry> <entry></entry> &dash-ent-20; @@ -526,8 +542,8 @@ <entry>g<subscript>5</subscript></entry> <entry>g<subscript>4</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-ARGB888-1X32"> - <entry>V4L2_MBUS_FMT_ARGB888_1X32</entry> + <row id="MEDIA-BUS-FMT-ARGB888-1X32"> + <entry>MEDIA_BUS_FMT_ARGB888_1X32</entry> <entry>0x100d</entry> <entry></entry> <entry>a<subscript>7</subscript></entry> @@ -600,7 +616,7 @@ <para>For instance, a format with uncompressed 10-bit Bayer components arranged in a red, green, green, blue pattern transferred as 2 8-bit samples per pixel with the least significant bits transferred first will - be named <constant>V4L2_MBUS_FMT_SRGGB10_2X8_PADHI_LE</constant>. + be named <constant>MEDIA_BUS_FMT_SRGGB10_2X8_PADHI_LE</constant>. </para> <figure id="bayer-patterns"> @@ -663,8 +679,8 @@ </row> </thead> <tbody valign="top"> - <row id="V4L2-MBUS-FMT-SBGGR8-1X8"> - <entry>V4L2_MBUS_FMT_SBGGR8_1X8</entry> + <row id="MEDIA-BUS-FMT-SBGGR8-1X8"> + <entry>MEDIA_BUS_FMT_SBGGR8_1X8</entry> <entry>0x3001</entry> <entry></entry> <entry>-</entry> @@ -680,8 +696,8 @@ <entry>b<subscript>1</subscript></entry> <entry>b<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-SGBRG8-1X8"> - <entry>V4L2_MBUS_FMT_SGBRG8_1X8</entry> + <row id="MEDIA-BUS-FMT-SGBRG8-1X8"> + <entry>MEDIA_BUS_FMT_SGBRG8_1X8</entry> <entry>0x3013</entry> <entry></entry> <entry>-</entry> @@ -697,8 +713,8 @@ <entry>g<subscript>1</subscript></entry> <entry>g<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-SGRBG8-1X8"> - <entry>V4L2_MBUS_FMT_SGRBG8_1X8</entry> + <row id="MEDIA-BUS-FMT-SGRBG8-1X8"> + <entry>MEDIA_BUS_FMT_SGRBG8_1X8</entry> <entry>0x3002</entry> <entry></entry> <entry>-</entry> @@ -714,8 +730,8 @@ <entry>g<subscript>1</subscript></entry> <entry>g<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-SRGGB8-1X8"> - <entry>V4L2_MBUS_FMT_SRGGB8_1X8</entry> + <row id="MEDIA-BUS-FMT-SRGGB8-1X8"> + <entry>MEDIA_BUS_FMT_SRGGB8_1X8</entry> <entry>0x3014</entry> <entry></entry> <entry>-</entry> @@ -731,8 +747,8 @@ <entry>r<subscript>1</subscript></entry> <entry>r<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-SBGGR10-ALAW8-1X8"> - <entry>V4L2_MBUS_FMT_SBGGR10_ALAW8_1X8</entry> + <row id="MEDIA-BUS-FMT-SBGGR10-ALAW8-1X8"> + <entry>MEDIA_BUS_FMT_SBGGR10_ALAW8_1X8</entry> <entry>0x3015</entry> <entry></entry> <entry>-</entry> @@ -748,8 +764,8 @@ <entry>b<subscript>1</subscript></entry> <entry>b<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-SGBRG10-ALAW8-1X8"> - <entry>V4L2_MBUS_FMT_SGBRG10_ALAW8_1X8</entry> + <row id="MEDIA-BUS-FMT-SGBRG10-ALAW8-1X8"> + <entry>MEDIA_BUS_FMT_SGBRG10_ALAW8_1X8</entry> <entry>0x3016</entry> <entry></entry> <entry>-</entry> @@ -765,8 +781,8 @@ <entry>g<subscript>1</subscript></entry> <entry>g<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-SGRBG10-ALAW8-1X8"> - <entry>V4L2_MBUS_FMT_SGRBG10_ALAW8_1X8</entry> + <row id="MEDIA-BUS-FMT-SGRBG10-ALAW8-1X8"> + <entry>MEDIA_BUS_FMT_SGRBG10_ALAW8_1X8</entry> <entry>0x3017</entry> <entry></entry> <entry>-</entry> @@ -782,8 +798,8 @@ <entry>g<subscript>1</subscript></entry> <entry>g<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-SRGGB10-ALAW8-1X8"> - <entry>V4L2_MBUS_FMT_SRGGB10_ALAW8_1X8</entry> + <row id="MEDIA-BUS-FMT-SRGGB10-ALAW8-1X8"> + <entry>MEDIA_BUS_FMT_SRGGB10_ALAW8_1X8</entry> <entry>0x3018</entry> <entry></entry> <entry>-</entry> @@ -799,8 +815,8 @@ <entry>r<subscript>1</subscript></entry> <entry>r<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-SBGGR10-DPCM8-1X8"> - <entry>V4L2_MBUS_FMT_SBGGR10_DPCM8_1X8</entry> + <row id="MEDIA-BUS-FMT-SBGGR10-DPCM8-1X8"> + <entry>MEDIA_BUS_FMT_SBGGR10_DPCM8_1X8</entry> <entry>0x300b</entry> <entry></entry> <entry>-</entry> @@ -816,8 +832,8 @@ <entry>b<subscript>1</subscript></entry> <entry>b<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-SGBRG10-DPCM8-1X8"> - <entry>V4L2_MBUS_FMT_SGBRG10_DPCM8_1X8</entry> + <row id="MEDIA-BUS-FMT-SGBRG10-DPCM8-1X8"> + <entry>MEDIA_BUS_FMT_SGBRG10_DPCM8_1X8</entry> <entry>0x300c</entry> <entry></entry> <entry>-</entry> @@ -833,8 +849,8 @@ <entry>g<subscript>1</subscript></entry> <entry>g<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-SGRBG10-DPCM8-1X8"> - <entry>V4L2_MBUS_FMT_SGRBG10_DPCM8_1X8</entry> + <row id="MEDIA-BUS-FMT-SGRBG10-DPCM8-1X8"> + <entry>MEDIA_BUS_FMT_SGRBG10_DPCM8_1X8</entry> <entry>0x3009</entry> <entry></entry> <entry>-</entry> @@ -850,8 +866,8 @@ <entry>g<subscript>1</subscript></entry> <entry>g<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-SRGGB10-DPCM8-1X8"> - <entry>V4L2_MBUS_FMT_SRGGB10_DPCM8_1X8</entry> + <row id="MEDIA-BUS-FMT-SRGGB10-DPCM8-1X8"> + <entry>MEDIA_BUS_FMT_SRGGB10_DPCM8_1X8</entry> <entry>0x300d</entry> <entry></entry> <entry>-</entry> @@ -867,8 +883,8 @@ <entry>r<subscript>1</subscript></entry> <entry>r<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-SBGGR10-2X8-PADHI-BE"> - <entry>V4L2_MBUS_FMT_SBGGR10_2X8_PADHI_BE</entry> + <row id="MEDIA-BUS-FMT-SBGGR10-2X8-PADHI-BE"> + <entry>MEDIA_BUS_FMT_SBGGR10_2X8_PADHI_BE</entry> <entry>0x3003</entry> <entry></entry> <entry>-</entry> @@ -901,8 +917,8 @@ <entry>b<subscript>1</subscript></entry> <entry>b<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-SBGGR10-2X8-PADHI-LE"> - <entry>V4L2_MBUS_FMT_SBGGR10_2X8_PADHI_LE</entry> + <row id="MEDIA-BUS-FMT-SBGGR10-2X8-PADHI-LE"> + <entry>MEDIA_BUS_FMT_SBGGR10_2X8_PADHI_LE</entry> <entry>0x3004</entry> <entry></entry> <entry>-</entry> @@ -935,8 +951,8 @@ <entry>b<subscript>9</subscript></entry> <entry>b<subscript>8</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-SBGGR10-2X8-PADLO-BE"> - <entry>V4L2_MBUS_FMT_SBGGR10_2X8_PADLO_BE</entry> + <row id="MEDIA-BUS-FMT-SBGGR10-2X8-PADLO-BE"> + <entry>MEDIA_BUS_FMT_SBGGR10_2X8_PADLO_BE</entry> <entry>0x3005</entry> <entry></entry> <entry>-</entry> @@ -969,8 +985,8 @@ <entry>0</entry> <entry>0</entry> </row> - <row id="V4L2-MBUS-FMT-SBGGR10-2X8-PADLO-LE"> - <entry>V4L2_MBUS_FMT_SBGGR10_2X8_PADLO_LE</entry> + <row id="MEDIA-BUS-FMT-SBGGR10-2X8-PADLO-LE"> + <entry>MEDIA_BUS_FMT_SBGGR10_2X8_PADLO_LE</entry> <entry>0x3006</entry> <entry></entry> <entry>-</entry> @@ -1003,8 +1019,8 @@ <entry>b<subscript>3</subscript></entry> <entry>b<subscript>2</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-SBGGR10-1X10"> - <entry>V4L2_MBUS_FMT_SBGGR10_1X10</entry> + <row id="MEDIA-BUS-FMT-SBGGR10-1X10"> + <entry>MEDIA_BUS_FMT_SBGGR10_1X10</entry> <entry>0x3007</entry> <entry></entry> <entry>-</entry> @@ -1020,8 +1036,8 @@ <entry>b<subscript>1</subscript></entry> <entry>b<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-SGBRG10-1X10"> - <entry>V4L2_MBUS_FMT_SGBRG10_1X10</entry> + <row id="MEDIA-BUS-FMT-SGBRG10-1X10"> + <entry>MEDIA_BUS_FMT_SGBRG10_1X10</entry> <entry>0x300e</entry> <entry></entry> <entry>-</entry> @@ -1037,8 +1053,8 @@ <entry>g<subscript>1</subscript></entry> <entry>g<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-SGRBG10-1X10"> - <entry>V4L2_MBUS_FMT_SGRBG10_1X10</entry> + <row id="MEDIA-BUS-FMT-SGRBG10-1X10"> + <entry>MEDIA_BUS_FMT_SGRBG10_1X10</entry> <entry>0x300a</entry> <entry></entry> <entry>-</entry> @@ -1054,8 +1070,8 @@ <entry>g<subscript>1</subscript></entry> <entry>g<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-SRGGB10-1X10"> - <entry>V4L2_MBUS_FMT_SRGGB10_1X10</entry> + <row id="MEDIA-BUS-FMT-SRGGB10-1X10"> + <entry>MEDIA_BUS_FMT_SRGGB10_1X10</entry> <entry>0x300f</entry> <entry></entry> <entry>-</entry> @@ -1071,8 +1087,8 @@ <entry>r<subscript>1</subscript></entry> <entry>r<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-SBGGR12-1X12"> - <entry>V4L2_MBUS_FMT_SBGGR12_1X12</entry> + <row id="MEDIA-BUS-FMT-SBGGR12-1X12"> + <entry>MEDIA_BUS_FMT_SBGGR12_1X12</entry> <entry>0x3008</entry> <entry></entry> <entry>b<subscript>11</subscript></entry> @@ -1088,8 +1104,8 @@ <entry>b<subscript>1</subscript></entry> <entry>b<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-SGBRG12-1X12"> - <entry>V4L2_MBUS_FMT_SGBRG12_1X12</entry> + <row id="MEDIA-BUS-FMT-SGBRG12-1X12"> + <entry>MEDIA_BUS_FMT_SGBRG12_1X12</entry> <entry>0x3010</entry> <entry></entry> <entry>g<subscript>11</subscript></entry> @@ -1105,8 +1121,8 @@ <entry>g<subscript>1</subscript></entry> <entry>g<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-SGRBG12-1X12"> - <entry>V4L2_MBUS_FMT_SGRBG12_1X12</entry> + <row id="MEDIA-BUS-FMT-SGRBG12-1X12"> + <entry>MEDIA_BUS_FMT_SGRBG12_1X12</entry> <entry>0x3011</entry> <entry></entry> <entry>g<subscript>11</subscript></entry> @@ -1122,8 +1138,8 @@ <entry>g<subscript>1</subscript></entry> <entry>g<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-SRGGB12-1X12"> - <entry>V4L2_MBUS_FMT_SRGGB12_1X12</entry> + <row id="MEDIA-BUS-FMT-SRGGB12-1X12"> + <entry>MEDIA_BUS_FMT_SRGGB12_1X12</entry> <entry>0x3012</entry> <entry></entry> <entry>r<subscript>11</subscript></entry> @@ -1175,7 +1191,7 @@ <para>For instance, a format where pixels are encoded as 8-bit YUV values downsampled to 4:2:2 and transferred as 2 8-bit bus samples per pixel in the - U, Y, V, Y order will be named <constant>V4L2_MBUS_FMT_UYVY8_2X8</constant>. + U, Y, V, Y order will be named <constant>MEDIA_BUS_FMT_UYVY8_2X8</constant>. </para> <para><xref linkend="v4l2-mbus-pixelcode-yuv8"/> lists existing packed YUV @@ -1280,8 +1296,8 @@ </row> </thead> <tbody valign="top"> - <row id="V4L2-MBUS-FMT-Y8-1X8"> - <entry>V4L2_MBUS_FMT_Y8_1X8</entry> + <row id="MEDIA-BUS-FMT-Y8-1X8"> + <entry>MEDIA_BUS_FMT_Y8_1X8</entry> <entry>0x2001</entry> <entry></entry> &dash-ent-24; @@ -1294,8 +1310,8 @@ <entry>y<subscript>1</subscript></entry> <entry>y<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-UV8-1X8"> - <entry>V4L2_MBUS_FMT_UV8_1X8</entry> + <row id="MEDIA-BUS-FMT-UV8-1X8"> + <entry>MEDIA_BUS_FMT_UV8_1X8</entry> <entry>0x2015</entry> <entry></entry> &dash-ent-24; @@ -1322,8 +1338,8 @@ <entry>v<subscript>1</subscript></entry> <entry>v<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-UYVY8-1_5X8"> - <entry>V4L2_MBUS_FMT_UYVY8_1_5X8</entry> + <row id="MEDIA-BUS-FMT-UYVY8-1_5X8"> + <entry>MEDIA_BUS_FMT_UYVY8_1_5X8</entry> <entry>0x2002</entry> <entry></entry> &dash-ent-24; @@ -1406,8 +1422,8 @@ <entry>y<subscript>1</subscript></entry> <entry>y<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-VYUY8-1_5X8"> - <entry>V4L2_MBUS_FMT_VYUY8_1_5X8</entry> + <row id="MEDIA-BUS-FMT-VYUY8-1_5X8"> + <entry>MEDIA_BUS_FMT_VYUY8_1_5X8</entry> <entry>0x2003</entry> <entry></entry> &dash-ent-24; @@ -1490,8 +1506,8 @@ <entry>y<subscript>1</subscript></entry> <entry>y<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-YUYV8-1_5X8"> - <entry>V4L2_MBUS_FMT_YUYV8_1_5X8</entry> + <row id="MEDIA-BUS-FMT-YUYV8-1_5X8"> + <entry>MEDIA_BUS_FMT_YUYV8_1_5X8</entry> <entry>0x2004</entry> <entry></entry> &dash-ent-24; @@ -1574,8 +1590,8 @@ <entry>v<subscript>1</subscript></entry> <entry>v<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-YVYU8-1_5X8"> - <entry>V4L2_MBUS_FMT_YVYU8_1_5X8</entry> + <row id="MEDIA-BUS-FMT-YVYU8-1_5X8"> + <entry>MEDIA_BUS_FMT_YVYU8_1_5X8</entry> <entry>0x2005</entry> <entry></entry> &dash-ent-24; @@ -1658,8 +1674,8 @@ <entry>u<subscript>1</subscript></entry> <entry>u<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-UYVY8-2X8"> - <entry>V4L2_MBUS_FMT_UYVY8_2X8</entry> + <row id="MEDIA-BUS-FMT-UYVY8-2X8"> + <entry>MEDIA_BUS_FMT_UYVY8_2X8</entry> <entry>0x2006</entry> <entry></entry> &dash-ent-24; @@ -1714,8 +1730,8 @@ <entry>y<subscript>1</subscript></entry> <entry>y<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-VYUY8-2X8"> - <entry>V4L2_MBUS_FMT_VYUY8_2X8</entry> + <row id="MEDIA-BUS-FMT-VYUY8-2X8"> + <entry>MEDIA_BUS_FMT_VYUY8_2X8</entry> <entry>0x2007</entry> <entry></entry> &dash-ent-24; @@ -1770,8 +1786,8 @@ <entry>y<subscript>1</subscript></entry> <entry>y<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-YUYV8-2X8"> - <entry>V4L2_MBUS_FMT_YUYV8_2X8</entry> + <row id="MEDIA-BUS-FMT-YUYV8-2X8"> + <entry>MEDIA_BUS_FMT_YUYV8_2X8</entry> <entry>0x2008</entry> <entry></entry> &dash-ent-24; @@ -1826,8 +1842,8 @@ <entry>v<subscript>1</subscript></entry> <entry>v<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-YVYU8-2X8"> - <entry>V4L2_MBUS_FMT_YVYU8_2X8</entry> + <row id="MEDIA-BUS-FMT-YVYU8-2X8"> + <entry>MEDIA_BUS_FMT_YVYU8_2X8</entry> <entry>0x2009</entry> <entry></entry> &dash-ent-24; @@ -1882,8 +1898,8 @@ <entry>u<subscript>1</subscript></entry> <entry>u<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-Y10-1X10"> - <entry>V4L2_MBUS_FMT_Y10_1X10</entry> + <row id="MEDIA-BUS-FMT-Y10-1X10"> + <entry>MEDIA_BUS_FMT_Y10_1X10</entry> <entry>0x200a</entry> <entry></entry> &dash-ent-22; @@ -1898,8 +1914,8 @@ <entry>y<subscript>1</subscript></entry> <entry>y<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-UYVY10-2X10"> - <entry>V4L2_MBUS_FMT_UYVY10_2X10</entry> + <row id="MEDIA-BUS-FMT-UYVY10-2X10"> + <entry>MEDIA_BUS_FMT_UYVY10_2X10</entry> <entry>0x2018</entry> <entry></entry> &dash-ent-22; @@ -1962,8 +1978,8 @@ <entry>y<subscript>1</subscript></entry> <entry>y<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-VYUY10-2X10"> - <entry>V4L2_MBUS_FMT_VYUY10_2X10</entry> + <row id="MEDIA-BUS-FMT-VYUY10-2X10"> + <entry>MEDIA_BUS_FMT_VYUY10_2X10</entry> <entry>0x2019</entry> <entry></entry> &dash-ent-22; @@ -2026,8 +2042,8 @@ <entry>y<subscript>1</subscript></entry> <entry>y<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-YUYV10-2X10"> - <entry>V4L2_MBUS_FMT_YUYV10_2X10</entry> + <row id="MEDIA-BUS-FMT-YUYV10-2X10"> + <entry>MEDIA_BUS_FMT_YUYV10_2X10</entry> <entry>0x200b</entry> <entry></entry> &dash-ent-22; @@ -2090,8 +2106,8 @@ <entry>v<subscript>1</subscript></entry> <entry>v<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-YVYU10-2X10"> - <entry>V4L2_MBUS_FMT_YVYU10_2X10</entry> + <row id="MEDIA-BUS-FMT-YVYU10-2X10"> + <entry>MEDIA_BUS_FMT_YVYU10_2X10</entry> <entry>0x200c</entry> <entry></entry> &dash-ent-22; @@ -2154,8 +2170,8 @@ <entry>u<subscript>1</subscript></entry> <entry>u<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-Y12-1X12"> - <entry>V4L2_MBUS_FMT_Y12_1X12</entry> + <row id="MEDIA-BUS-FMT-Y12-1X12"> + <entry>MEDIA_BUS_FMT_Y12_1X12</entry> <entry>0x2013</entry> <entry></entry> &dash-ent-20; @@ -2172,8 +2188,8 @@ <entry>y<subscript>1</subscript></entry> <entry>y<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-UYVY8-1X16"> - <entry>V4L2_MBUS_FMT_UYVY8_1X16</entry> + <row id="MEDIA-BUS-FMT-UYVY8-1X16"> + <entry>MEDIA_BUS_FMT_UYVY8_1X16</entry> <entry>0x200f</entry> <entry></entry> &dash-ent-16; @@ -2216,8 +2232,8 @@ <entry>y<subscript>1</subscript></entry> <entry>y<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-VYUY8-1X16"> - <entry>V4L2_MBUS_FMT_VYUY8_1X16</entry> + <row id="MEDIA-BUS-FMT-VYUY8-1X16"> + <entry>MEDIA_BUS_FMT_VYUY8_1X16</entry> <entry>0x2010</entry> <entry></entry> &dash-ent-16; @@ -2260,8 +2276,8 @@ <entry>y<subscript>1</subscript></entry> <entry>y<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-YUYV8-1X16"> - <entry>V4L2_MBUS_FMT_YUYV8_1X16</entry> + <row id="MEDIA-BUS-FMT-YUYV8-1X16"> + <entry>MEDIA_BUS_FMT_YUYV8_1X16</entry> <entry>0x2011</entry> <entry></entry> &dash-ent-16; @@ -2304,8 +2320,8 @@ <entry>v<subscript>1</subscript></entry> <entry>v<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-YVYU8-1X16"> - <entry>V4L2_MBUS_FMT_YVYU8_1X16</entry> + <row id="MEDIA-BUS-FMT-YVYU8-1X16"> + <entry>MEDIA_BUS_FMT_YVYU8_1X16</entry> <entry>0x2012</entry> <entry></entry> &dash-ent-16; @@ -2348,8 +2364,8 @@ <entry>u<subscript>1</subscript></entry> <entry>u<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-YDYUYDYV8-1X16"> - <entry>V4L2_MBUS_FMT_YDYUYDYV8_1X16</entry> + <row id="MEDIA-BUS-FMT-YDYUYDYV8-1X16"> + <entry>MEDIA_BUS_FMT_YDYUYDYV8_1X16</entry> <entry>0x2014</entry> <entry></entry> &dash-ent-16; @@ -2436,8 +2452,8 @@ <entry>v<subscript>1</subscript></entry> <entry>v<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-UYVY10-1X20"> - <entry>V4L2_MBUS_FMT_UYVY10_1X20</entry> + <row id="MEDIA-BUS-FMT-UYVY10-1X20"> + <entry>MEDIA_BUS_FMT_UYVY10_1X20</entry> <entry>0x201a</entry> <entry></entry> &dash-ent-12; @@ -2488,8 +2504,8 @@ <entry>y<subscript>1</subscript></entry> <entry>y<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-VYUY10-1X20"> - <entry>V4L2_MBUS_FMT_VYUY10_1X20</entry> + <row id="MEDIA-BUS-FMT-VYUY10-1X20"> + <entry>MEDIA_BUS_FMT_VYUY10_1X20</entry> <entry>0x201b</entry> <entry></entry> &dash-ent-12; @@ -2540,8 +2556,8 @@ <entry>y<subscript>1</subscript></entry> <entry>y<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-YUYV10-1X20"> - <entry>V4L2_MBUS_FMT_YUYV10_1X20</entry> + <row id="MEDIA-BUS-FMT-YUYV10-1X20"> + <entry>MEDIA_BUS_FMT_YUYV10_1X20</entry> <entry>0x200d</entry> <entry></entry> &dash-ent-12; @@ -2592,8 +2608,8 @@ <entry>v<subscript>1</subscript></entry> <entry>v<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-YVYU10-1X20"> - <entry>V4L2_MBUS_FMT_YVYU10_1X20</entry> + <row id="MEDIA-BUS-FMT-YVYU10-1X20"> + <entry>MEDIA_BUS_FMT_YVYU10_1X20</entry> <entry>0x200e</entry> <entry></entry> &dash-ent-12; @@ -2644,8 +2660,8 @@ <entry>u<subscript>1</subscript></entry> <entry>u<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-YUV10-1X30"> - <entry>V4L2_MBUS_FMT_YUV10_1X30</entry> + <row id="MEDIA-BUS-FMT-YUV10-1X30"> + <entry>MEDIA_BUS_FMT_YUV10_1X30</entry> <entry>0x2016</entry> <entry></entry> <entry>-</entry> @@ -2681,8 +2697,8 @@ <entry>v<subscript>1</subscript></entry> <entry>v<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-AYUV8-1X32"> - <entry>V4L2_MBUS_FMT_AYUV8_1X32</entry> + <row id="MEDIA-BUS-FMT-AYUV8-1X32"> + <entry>MEDIA_BUS_FMT_AYUV8_1X32</entry> <entry>0x2017</entry> <entry></entry> <entry>a<subscript>7</subscript></entry> @@ -2718,8 +2734,8 @@ <entry>v<subscript>1</subscript></entry> <entry>v<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-UYVY12-2X12"> - <entry>V4L2_MBUS_FMT_UYVY12_2X12</entry> + <row id="MEDIA-BUS-FMT-UYVY12-2X12"> + <entry>MEDIA_BUS_FMT_UYVY12_2X12</entry> <entry>0x201c</entry> <entry></entry> &dash-ent-20; @@ -2790,8 +2806,8 @@ <entry>y<subscript>1</subscript></entry> <entry>y<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-VYUY12-2X12"> - <entry>V4L2_MBUS_FMT_VYUY12_2X12</entry> + <row id="MEDIA-BUS-FMT-VYUY12-2X12"> + <entry>MEDIA_BUS_FMT_VYUY12_2X12</entry> <entry>0x201d</entry> <entry></entry> &dash-ent-20; @@ -2862,8 +2878,8 @@ <entry>y<subscript>1</subscript></entry> <entry>y<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-YUYV12-2X12"> - <entry>V4L2_MBUS_FMT_YUYV12_2X12</entry> + <row id="MEDIA-BUS-FMT-YUYV12-2X12"> + <entry>MEDIA_BUS_FMT_YUYV12_2X12</entry> <entry>0x201e</entry> <entry></entry> &dash-ent-20; @@ -2934,8 +2950,8 @@ <entry>v<subscript>1</subscript></entry> <entry>v<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-YVYU12-2X12"> - <entry>V4L2_MBUS_FMT_YVYU12_2X12</entry> + <row id="MEDIA-BUS-FMT-YVYU12-2X12"> + <entry>MEDIA_BUS_FMT_YVYU12_2X12</entry> <entry>0x201f</entry> <entry></entry> &dash-ent-20; @@ -3006,8 +3022,8 @@ <entry>u<subscript>1</subscript></entry> <entry>u<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-UYVY12-1X24"> - <entry>V4L2_MBUS_FMT_UYVY12_1X24</entry> + <row id="MEDIA-BUS-FMT-UYVY12-1X24"> + <entry>MEDIA_BUS_FMT_UYVY12_1X24</entry> <entry>0x2020</entry> <entry></entry> &dash-ent-8; @@ -3066,8 +3082,8 @@ <entry>y<subscript>1</subscript></entry> <entry>y<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-VYUY12-1X24"> - <entry>V4L2_MBUS_FMT_VYUY12_1X24</entry> + <row id="MEDIA-BUS-FMT-VYUY12-1X24"> + <entry>MEDIA_BUS_FMT_VYUY12_1X24</entry> <entry>0x2021</entry> <entry></entry> &dash-ent-8; @@ -3126,8 +3142,8 @@ <entry>y<subscript>1</subscript></entry> <entry>y<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-YUYV12-1X24"> - <entry>V4L2_MBUS_FMT_YUYV12_1X24</entry> + <row id="MEDIA-BUS-FMT-YUYV12-1X24"> + <entry>MEDIA_BUS_FMT_YUYV12_1X24</entry> <entry>0x2022</entry> <entry></entry> &dash-ent-8; @@ -3186,8 +3202,8 @@ <entry>v<subscript>1</subscript></entry> <entry>v<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-YVYU12-1X24"> - <entry>V4L2_MBUS_FMT_YVYU12_1X24</entry> + <row id="MEDIA-BUS-FMT-YVYU12-1X24"> + <entry>MEDIA_BUS_FMT_YVYU12_1X24</entry> <entry>0x2023</entry> <entry></entry> &dash-ent-8; @@ -3366,8 +3382,8 @@ </row> </thead> <tbody valign="top"> - <row id="V4L2-MBUS-FMT-AHSV8888-1X32"> - <entry>V4L2_MBUS_FMT_AHSV8888_1X32</entry> + <row id="MEDIA-BUS-FMT-AHSV8888-1X32"> + <entry>MEDIA_BUS_FMT_AHSV8888_1X32</entry> <entry>0x6001</entry> <entry></entry> <entry>a<subscript>7</subscript></entry> @@ -3422,7 +3438,7 @@ </para> <para>For instance, for a JPEG baseline process and an 8-bit bus width - the format will be named <constant>V4L2_MBUS_FMT_JPEG_1X8</constant>. + the format will be named <constant>MEDIA_BUS_FMT_JPEG_1X8</constant>. </para> <para>The following table lists existing JPEG compressed formats.</para> @@ -3441,8 +3457,8 @@ </row> </thead> <tbody valign="top"> - <row id="V4L2-MBUS-FMT-JPEG-1X8"> - <entry>V4L2_MBUS_FMT_JPEG_1X8</entry> + <row id="MEDIA-BUS-FMT-JPEG-1X8"> + <entry>MEDIA_BUS_FMT_JPEG_1X8</entry> <entry>0x4001</entry> <entry>Besides of its usage for the parallel bus this format is recommended for transmission of JPEG data over MIPI CSI bus @@ -3484,8 +3500,8 @@ interface and may change in the future.</para> </row> </thead> <tbody valign="top"> - <row id="V4L2-MBUS-FMT-S5C-UYVY-JPEG-1X8"> - <entry>V4L2_MBUS_FMT_S5C_UYVY_JPEG_1X8</entry> + <row id="MEDIA-BUS-FMT-S5C-UYVY-JPEG-1X8"> + <entry>MEDIA_BUS_FMT_S5C_UYVY_JPEG_1X8</entry> <entry>0x5001</entry> <entry> Interleaved raw UYVY and JPEG image format with embedded diff --git a/Documentation/DocBook/media/v4l/v4l2.xml b/Documentation/DocBook/media/v4l/v4l2.xml index 7cfe618f754d..ac0f8d9d2a49 100644 --- a/Documentation/DocBook/media/v4l/v4l2.xml +++ b/Documentation/DocBook/media/v4l/v4l2.xml @@ -152,6 +152,15 @@ structs, ioctls) must be noted in more detail in the history chapter applications. --> <revision> + <revnumber>3.19</revnumber> + <date>2014-12-05</date> + <authorinitials>hv</authorinitials> + <revremark>Rewrote Colorspace chapter, added new &v4l2-ycbcr-encoding; and &v4l2-quantization; fields +to &v4l2-pix-format;, &v4l2-pix-format-mplane; and &v4l2-mbus-framefmt;. + </revremark> + </revision> + + <revision> <revnumber>3.17</revnumber> <date>2014-08-04</date> <authorinitials>lp, hv</authorinitials> @@ -539,7 +548,7 @@ and discussions on the V4L mailing list.</revremark> </partinfo> <title>Video for Linux Two API Specification</title> - <subtitle>Revision 3.17</subtitle> + <subtitle>Revision 3.19</subtitle> <chapter id="common"> &sub-common; diff --git a/Documentation/DocBook/media/v4l/vidioc-dv-timings-cap.xml b/Documentation/DocBook/media/v4l/vidioc-dv-timings-cap.xml index 28a8c1e1c705..a2017bfcaed2 100644 --- a/Documentation/DocBook/media/v4l/vidioc-dv-timings-cap.xml +++ b/Documentation/DocBook/media/v4l/vidioc-dv-timings-cap.xml @@ -212,11 +212,3 @@ standards set in the <structfield>standards</structfield> field. &return-value; </refsect1> </refentry> - -<!-- -Local Variables: -mode: sgml -sgml-parent-document: "v4l2.sgml" -indent-tabs-mode: nil -End: ---> diff --git a/Documentation/DocBook/media/v4l/vidioc-enum-dv-timings.xml b/Documentation/DocBook/media/v4l/vidioc-enum-dv-timings.xml index b9fdfeacdbcb..6e3cadd4e1f9 100644 --- a/Documentation/DocBook/media/v4l/vidioc-enum-dv-timings.xml +++ b/Documentation/DocBook/media/v4l/vidioc-enum-dv-timings.xml @@ -131,11 +131,3 @@ is out of bounds or the <structfield>pad</structfield> number is invalid.</para> </variablelist> </refsect1> </refentry> - -<!-- -Local Variables: -mode: sgml -sgml-parent-document: "v4l2.sgml" -indent-tabs-mode: nil -End: ---> diff --git a/Documentation/DocBook/media/v4l/vidioc-enuminput.xml b/Documentation/DocBook/media/v4l/vidioc-enuminput.xml index 493a39a8ef21..603fecef9083 100644 --- a/Documentation/DocBook/media/v4l/vidioc-enuminput.xml +++ b/Documentation/DocBook/media/v4l/vidioc-enuminput.xml @@ -287,6 +287,14 @@ input/output interface to linux-media@vger.kernel.org on 19 Oct 2009. <entry>0x00000004</entry> <entry>This input supports setting the TV standard by using VIDIOC_S_STD.</entry> </row> + <row> + <entry><constant>V4L2_IN_CAP_NATIVE_SIZE</constant></entry> + <entry>0x00000008</entry> + <entry>This input supports setting the native size using + the <constant>V4L2_SEL_TGT_NATIVE_SIZE</constant> + selection target, see <xref + linkend="v4l2-selections-common"/>.</entry> + </row> </tbody> </tgroup> </table> diff --git a/Documentation/DocBook/media/v4l/vidioc-enumoutput.xml b/Documentation/DocBook/media/v4l/vidioc-enumoutput.xml index 2654e097df39..773fb1258c24 100644 --- a/Documentation/DocBook/media/v4l/vidioc-enumoutput.xml +++ b/Documentation/DocBook/media/v4l/vidioc-enumoutput.xml @@ -172,6 +172,14 @@ input/output interface to linux-media@vger.kernel.org on 19 Oct 2009. <entry>0x00000004</entry> <entry>This output supports setting the TV standard by using VIDIOC_S_STD.</entry> </row> + <row> + <entry><constant>V4L2_OUT_CAP_NATIVE_SIZE</constant></entry> + <entry>0x00000008</entry> + <entry>This output supports setting the native size using + the <constant>V4L2_SEL_TGT_NATIVE_SIZE</constant> + selection target, see <xref + linkend="v4l2-selections-common"/>.</entry> + </row> </tbody> </tgroup> </table> diff --git a/Documentation/DocBook/uio-howto.tmpl b/Documentation/DocBook/uio-howto.tmpl index bbe9c1fd5cef..cd0e452dfed5 100644 --- a/Documentation/DocBook/uio-howto.tmpl +++ b/Documentation/DocBook/uio-howto.tmpl @@ -540,7 +540,7 @@ appears in sysfs. </para></listitem> <listitem><para> -<varname>unsigned long size</varname>: Fill in the size of the +<varname>resource_size_t size</varname>: Fill in the size of the memory block that <varname>addr</varname> points to. If <varname>size</varname> is zero, the mapping is considered unused. Note that you <emphasis>must</emphasis> initialize <varname>size</varname> with zero for @@ -719,7 +719,7 @@ framework to set up sysfs files for this region. Simply leave it alone. </para> </sect1> -<sect1 id="using uio_dmem_genirq"> +<sect1 id="using-uio_dmem_genirq"> <title>Using uio_dmem_genirq for platform devices</title> <para> In addition to statically allocated memory ranges, they may also be @@ -746,16 +746,16 @@ framework to set up sysfs files for this region. Simply leave it alone. following elements: </para> <itemizedlist> - <listitem><varname>struct uio_info uioinfo</varname>: The same + <listitem><para><varname>struct uio_info uioinfo</varname>: The same structure used as the <varname>uio_pdrv_genirq</varname> platform - data</listitem> - <listitem><varname>unsigned int *dynamic_region_sizes</varname>: + data</para></listitem> + <listitem><para><varname>unsigned int *dynamic_region_sizes</varname>: Pointer to list of sizes of dynamic memory regions to be mapped into user space. - </listitem> - <listitem><varname>unsigned int num_dynamic_regions</varname>: + </para></listitem> + <listitem><para><varname>unsigned int num_dynamic_regions</varname>: Number of elements in <varname>dynamic_region_sizes</varname> array. - </listitem> + </para></listitem> </itemizedlist> <para> The dynamic regions defined in the platform data will be appended to diff --git a/Documentation/DocBook/writing-an-alsa-driver.tmpl b/Documentation/DocBook/writing-an-alsa-driver.tmpl index 784793df81ed..84ef6a90131c 100644 --- a/Documentation/DocBook/writing-an-alsa-driver.tmpl +++ b/Documentation/DocBook/writing-an-alsa-driver.tmpl @@ -3658,6 +3658,29 @@ struct _snd_pcm_runtime { </para> <para> + The above callback can be simplified with a helper function, + <function>snd_ctl_enum_info</function>. The final code + looks like below. + (You can pass ARRAY_SIZE(texts) instead of 4 in the third + argument; it's a matter of taste.) + + <informalexample> + <programlisting> +<![CDATA[ + static int snd_myctl_enum_info(struct snd_kcontrol *kcontrol, + struct snd_ctl_elem_info *uinfo) + { + static char *texts[4] = { + "First", "Second", "Third", "Fourth" + }; + return snd_ctl_enum_info(uinfo, 1, 4, texts); + } +]]> + </programlisting> + </informalexample> + </para> + + <para> Some common info callbacks are available for your convenience: <function>snd_ctl_boolean_mono_info()</function> and <function>snd_ctl_boolean_stereo_info()</function>. diff --git a/Documentation/IPMI.txt b/Documentation/IPMI.txt index f13c9132e9f2..653d5d739d7f 100644 --- a/Documentation/IPMI.txt +++ b/Documentation/IPMI.txt @@ -42,7 +42,13 @@ The driver interface depends on your hardware. If your system properly provides the SMBIOS info for IPMI, the driver will detect it and just work. If you have a board with a standard interface (These will generally be either "KCS", "SMIC", or "BT", consult your hardware -manual), choose the 'IPMI SI handler' option. +manual), choose the 'IPMI SI handler' option. A driver also exists +for direct I2C access to the IPMI management controller. Some boards +support this, but it is unknown if it will work on every board. For +this, choose 'IPMI SMBus handler', but be ready to try to do some +figuring to see if it will work on your system if the SMBIOS/APCI +information is wrong or not present. It is fairly safe to have both +these enabled and let the drivers auto-detect what is present. You should generally enable ACPI on your system, as systems with IPMI can have ACPI tables describing them. @@ -52,7 +58,8 @@ their job correctly, the IPMI controller should be automatically detected (via ACPI or SMBIOS tables) and should just work. Sadly, many boards do not have this information. The driver attempts standard defaults, but they may not work. If you fall into this -situation, you need to read the section below named 'The SI Driver'. +situation, you need to read the section below named 'The SI Driver' or +"The SMBus Driver" on how to hand-configure your system. IPMI defines a standard watchdog timer. You can enable this with the 'IPMI Watchdog Timer' config option. If you compile the driver into @@ -97,7 +104,12 @@ driver, each open file for this device ties in to the message handler as an IPMI user. ipmi_si - A driver for various system interfaces. This supports KCS, -SMIC, and BT interfaces. +SMIC, and BT interfaces. Unless you have an SMBus interface or your +own custom interface, you probably need to use this. + +ipmi_ssif - A driver for accessing BMCs on the SMBus. It uses the +I2C kernel driver's SMBus interfaces to send and receive IPMI messages +over the SMBus. ipmi_watchdog - IPMI requires systems to have a very capable watchdog timer. This driver implements the standard Linux watchdog timer @@ -476,6 +488,62 @@ for specifying an interface. Note that when removing an interface, only the first three parameters (si type, address type, and address) are used for the comparison. Any options are ignored for removing. +The SMBus Driver (SSIF) +----------------------- + +The SMBus driver allows up to 4 SMBus devices to be configured in the +system. By default, the driver will only register with something it +finds in DMI or ACPI tables. You can change this +at module load time (for a module) with: + + modprobe ipmi_ssif.o + addr=<i2caddr1>[,<i2caddr2>[,...]] + adapter=<adapter1>[,<adapter2>[...]] + dbg=<flags1>,<flags2>... + slave_addrs=<addr1>,<addr2>,... + [dbg_probe=1] + +The addresses are normal I2C addresses. The adapter is the string +name of the adapter, as shown in /sys/class/i2c-adapter/i2c-<n>/name. +It is *NOT* i2c-<n> itself. + +The debug flags are bit flags for each BMC found, they are: +IPMI messages: 1, driver state: 2, timing: 4, I2C probe: 8 + +Setting dbg_probe to 1 will enable debugging of the probing and +detection process for BMCs on the SMBusses. + +The slave_addrs specifies the IPMI address of the local BMC. This is +usually 0x20 and the driver defaults to that, but in case it's not, it +can be specified when the driver starts up. + +Discovering the IPMI compliant BMC on the SMBus can cause devices on +the I2C bus to fail. The SMBus driver writes a "Get Device ID" IPMI +message as a block write to the I2C bus and waits for a response. +This action can be detrimental to some I2C devices. It is highly +recommended that the known I2C address be given to the SMBus driver in +the smb_addr parameter unless you have DMI or ACPI data to tell the +driver what to use. + +When compiled into the kernel, the addresses can be specified on the +kernel command line as: + + ipmb_ssif.addr=<i2caddr1>[,<i2caddr2>[...]] + ipmi_ssif.adapter=<adapter1>[,<adapter2>[...]] + ipmi_ssif.dbg=<flags1>[,<flags2>[...]] + ipmi_ssif.dbg_probe=1 + ipmi_ssif.slave_addrs=<addr1>[,<addr2>[...]] + +These are the same options as on the module command line. + +The I2C driver does not support non-blocking access or polling, so +this driver cannod to IPMI panic events, extend the watchdog at panic +time, or other panic-related IPMI functions without special kernel +patches and driver modifications. You can get those at the openipmi +web page. + +The driver supports a hot add and remove of interfaces through the I2C +sysfs interface. Other Pieces ------------ diff --git a/Documentation/IRQ-domain.txt b/Documentation/IRQ-domain.txt index 8a8b82c9ca53..39cfa72732ff 100644 --- a/Documentation/IRQ-domain.txt +++ b/Documentation/IRQ-domain.txt @@ -151,3 +151,74 @@ used and no descriptor gets allocated it is very important to make sure that the driver using the simple domain call irq_create_mapping() before any irq_find_mapping() since the latter will actually work for the static IRQ assignment case. + +==== Hierarchy IRQ domain ==== +On some architectures, there may be multiple interrupt controllers +involved in delivering an interrupt from the device to the target CPU. +Let's look at a typical interrupt delivering path on x86 platforms: + +Device --> IOAPIC -> Interrupt remapping Controller -> Local APIC -> CPU + +There are three interrupt controllers involved: +1) IOAPIC controller +2) Interrupt remapping controller +3) Local APIC controller + +To support such a hardware topology and make software architecture match +hardware architecture, an irq_domain data structure is built for each +interrupt controller and those irq_domains are organized into hierarchy. +When building irq_domain hierarchy, the irq_domain near to the device is +child and the irq_domain near to CPU is parent. So a hierarchy structure +as below will be built for the example above. + CPU Vector irq_domain (root irq_domain to manage CPU vectors) + ^ + | + Interrupt Remapping irq_domain (manage irq_remapping entries) + ^ + | + IOAPIC irq_domain (manage IOAPIC delivery entries/pins) + +There are four major interfaces to use hierarchy irq_domain: +1) irq_domain_alloc_irqs(): allocate IRQ descriptors and interrupt + controller related resources to deliver these interrupts. +2) irq_domain_free_irqs(): free IRQ descriptors and interrupt controller + related resources associated with these interrupts. +3) irq_domain_activate_irq(): activate interrupt controller hardware to + deliver the interrupt. +3) irq_domain_deactivate_irq(): deactivate interrupt controller hardware + to stop delivering the interrupt. + +Following changes are needed to support hierarchy irq_domain. +1) a new field 'parent' is added to struct irq_domain; it's used to + maintain irq_domain hierarchy information. +2) a new field 'parent_data' is added to struct irq_data; it's used to + build hierarchy irq_data to match hierarchy irq_domains. The irq_data + is used to store irq_domain pointer and hardware irq number. +3) new callbacks are added to struct irq_domain_ops to support hierarchy + irq_domain operations. + +With support of hierarchy irq_domain and hierarchy irq_data ready, an +irq_domain structure is built for each interrupt controller, and an +irq_data structure is allocated for each irq_domain associated with an +IRQ. Now we could go one step further to support stacked(hierarchy) +irq_chip. That is, an irq_chip is associated with each irq_data along +the hierarchy. A child irq_chip may implement a required action by +itself or by cooperating with its parent irq_chip. + +With stacked irq_chip, interrupt controller driver only needs to deal +with the hardware managed by itself and may ask for services from its +parent irq_chip when needed. So we could achieve a much cleaner +software architecture. + +For an interrupt controller driver to support hierarchy irq_domain, it +needs to: +1) Implement irq_domain_ops.alloc and irq_domain_ops.free +2) Optionally implement irq_domain_ops.activate and + irq_domain_ops.deactivate. +3) Optionally implement an irq_chip to manage the interrupt controller + hardware. +4) No need to implement irq_domain_ops.map and irq_domain_ops.unmap, + they are unused with hierarchy irq_domain. + +Hierarchy irq_domain may also be used to support other architectures, +such as ARM, ARM64 etc. diff --git a/Documentation/RCU/rcu.txt b/Documentation/RCU/rcu.txt index bf778332a28f..745f429fda79 100644 --- a/Documentation/RCU/rcu.txt +++ b/Documentation/RCU/rcu.txt @@ -36,7 +36,7 @@ o How can the updater tell when a grace period has completed executed in user mode, or executed in the idle loop, we can safely free up that item. - Preemptible variants of RCU (CONFIG_TREE_PREEMPT_RCU) get the + Preemptible variants of RCU (CONFIG_PREEMPT_RCU) get the same effect, but require that the readers manipulate CPU-local counters. These counters allow limited types of blocking within RCU read-side critical sections. SRCU also uses CPU-local @@ -81,7 +81,7 @@ o I hear that RCU is patented? What is with that? o I hear that RCU needs work in order to support realtime kernels? This work is largely completed. Realtime-friendly RCU can be - enabled via the CONFIG_TREE_PREEMPT_RCU kernel configuration + enabled via the CONFIG_PREEMPT_RCU kernel configuration parameter. However, work is in progress for enabling priority boosting of preempted RCU read-side critical sections. This is needed if you have CPU-bound realtime threads. diff --git a/Documentation/RCU/stallwarn.txt b/Documentation/RCU/stallwarn.txt index ef5a2fd4ff70..b57c0c1cdac6 100644 --- a/Documentation/RCU/stallwarn.txt +++ b/Documentation/RCU/stallwarn.txt @@ -15,7 +15,7 @@ CONFIG_RCU_CPU_STALL_TIMEOUT 21 seconds. This configuration parameter may be changed at runtime via the - /sys/module/rcutree/parameters/rcu_cpu_stall_timeout, however + /sys/module/rcupdate/parameters/rcu_cpu_stall_timeout, however this parameter is checked only at the beginning of a cycle. So if you are 10 seconds into a 40-second stall, setting this sysfs parameter to (say) five will shorten the timeout for the @@ -26,12 +26,6 @@ CONFIG_RCU_CPU_STALL_TIMEOUT Stall-warning messages may be enabled and disabled completely via /sys/module/rcupdate/parameters/rcu_cpu_stall_suppress. -CONFIG_RCU_CPU_STALL_VERBOSE - - This kernel configuration parameter causes the stall warning to - also dump the stacks of any tasks that are blocking the current - RCU-preempt grace period. - CONFIG_RCU_CPU_STALL_INFO This kernel configuration parameter causes the stall warning to @@ -77,7 +71,7 @@ This message indicates that CPU 5 detected that it was causing a stall, and that the stall was affecting RCU-sched. This message will normally be followed by a stack dump of the offending CPU. On TREE_RCU kernel builds, RCU and RCU-sched are implemented by the same underlying mechanism, -while on TREE_PREEMPT_RCU kernel builds, RCU is instead implemented +while on PREEMPT_RCU kernel builds, RCU is instead implemented by rcu_preempt_state. On the other hand, if the offending CPU fails to print out a stall-warning @@ -89,7 +83,7 @@ INFO: rcu_bh_state detected stalls on CPUs/tasks: { 3 5 } (detected by 2, 2502 j This message indicates that CPU 2 detected that CPUs 3 and 5 were both causing stalls, and that the stall was affecting RCU-bh. This message will normally be followed by stack dumps for each CPU. Please note that -TREE_PREEMPT_RCU builds can be stalled by tasks as well as by CPUs, +PREEMPT_RCU builds can be stalled by tasks as well as by CPUs, and that the tasks will be indicated by PID, for example, "P3421". It is even possible for a rcu_preempt_state stall to be caused by both CPUs -and- tasks, in which case the offending CPUs and tasks will all @@ -158,6 +152,15 @@ no non-lazy callbacks ("." is printed otherwise, as shown above) and "D" indicates that dyntick-idle processing is enabled ("." is printed otherwise, for example, if disabled via the "nohz=" kernel boot parameter). +If the relevant grace-period kthread has been unable to run prior to +the stall warning, the following additional line is printed: + + rcu_preempt kthread starved for 2023 jiffies! + +Starving the grace-period kthreads of CPU time can of course result in +RCU CPU stall warnings even when all CPUs and tasks have passed through +the required quiescent states. + Multiple Warnings From One Stall @@ -193,6 +196,11 @@ o For !CONFIG_PREEMPT kernels, a CPU looping anywhere in the behavior, you might need to replace some of the cond_resched() calls with calls to cond_resched_rcu_qs(). +o Anything that prevents RCU's grace-period kthreads from running. + This can result in the "All QSes seen" console-log message. + This message will include information on when the kthread last + ran and how often it should be expected to run. + o A CPU-bound real-time task in a CONFIG_PREEMPT kernel, which might happen to preempt a low-priority task in the middle of an RCU read-side critical section. This is especially damaging if @@ -205,10 +213,10 @@ o A CPU-bound real-time task in a CONFIG_PREEMPT kernel, which might o A CPU-bound real-time task in a CONFIG_PREEMPT_RT kernel that is running at a higher priority than the RCU softirq threads. This will prevent RCU callbacks from ever being invoked, - and in a CONFIG_TREE_PREEMPT_RCU kernel will further prevent + and in a CONFIG_PREEMPT_RCU kernel will further prevent RCU grace periods from ever completing. Either way, the system will eventually run out of memory and hang. In the - CONFIG_TREE_PREEMPT_RCU case, you might see stall-warning + CONFIG_PREEMPT_RCU case, you might see stall-warning messages. o A hardware or software issue shuts off the scheduler-clock diff --git a/Documentation/RCU/trace.txt b/Documentation/RCU/trace.txt index 910870b15acd..08651da15448 100644 --- a/Documentation/RCU/trace.txt +++ b/Documentation/RCU/trace.txt @@ -8,7 +8,7 @@ The following sections describe the debugfs files and formats, first for rcutree and next for rcutiny. -CONFIG_TREE_RCU and CONFIG_TREE_PREEMPT_RCU debugfs Files and Formats +CONFIG_TREE_RCU and CONFIG_PREEMPT_RCU debugfs Files and Formats These implementations of RCU provide several debugfs directories under the top-level directory "rcu": @@ -18,7 +18,7 @@ rcu/rcu_preempt rcu/rcu_sched Each directory contains files for the corresponding flavor of RCU. -Note that rcu/rcu_preempt is only present for CONFIG_TREE_PREEMPT_RCU. +Note that rcu/rcu_preempt is only present for CONFIG_PREEMPT_RCU. For CONFIG_TREE_RCU, the RCU flavor maps onto the RCU-sched flavor, so that activity for both appears in rcu/rcu_sched. @@ -56,14 +56,14 @@ rcuboost: The output of "cat rcu/rcu_preempt/rcudata" looks as follows: - 0!c=30455 g=30456 pq=1 qp=1 dt=126535/140000000000000/0 df=2002 of=4 ql=0/0 qs=N... b=10 ci=74572 nci=0 co=1131 ca=716 - 1!c=30719 g=30720 pq=1 qp=0 dt=132007/140000000000000/0 df=1874 of=10 ql=0/0 qs=N... b=10 ci=123209 nci=0 co=685 ca=982 - 2!c=30150 g=30151 pq=1 qp=1 dt=138537/140000000000000/0 df=1707 of=8 ql=0/0 qs=N... b=10 ci=80132 nci=0 co=1328 ca=1458 - 3 c=31249 g=31250 pq=1 qp=0 dt=107255/140000000000000/0 df=1749 of=6 ql=0/450 qs=NRW. b=10 ci=151700 nci=0 co=509 ca=622 - 4!c=29502 g=29503 pq=1 qp=1 dt=83647/140000000000000/0 df=965 of=5 ql=0/0 qs=N... b=10 ci=65643 nci=0 co=1373 ca=1521 - 5 c=31201 g=31202 pq=1 qp=1 dt=70422/0/0 df=535 of=7 ql=0/0 qs=.... b=10 ci=58500 nci=0 co=764 ca=698 - 6!c=30253 g=30254 pq=1 qp=1 dt=95363/140000000000000/0 df=780 of=5 ql=0/0 qs=N... b=10 ci=100607 nci=0 co=1414 ca=1353 - 7 c=31178 g=31178 pq=1 qp=0 dt=91536/0/0 df=547 of=4 ql=0/0 qs=.... b=10 ci=109819 nci=0 co=1115 ca=969 + 0!c=30455 g=30456 pq=1/0 qp=1 dt=126535/140000000000000/0 df=2002 of=4 ql=0/0 qs=N... b=10 ci=74572 nci=0 co=1131 ca=716 + 1!c=30719 g=30720 pq=1/0 qp=0 dt=132007/140000000000000/0 df=1874 of=10 ql=0/0 qs=N... b=10 ci=123209 nci=0 co=685 ca=982 + 2!c=30150 g=30151 pq=1/1 qp=1 dt=138537/140000000000000/0 df=1707 of=8 ql=0/0 qs=N... b=10 ci=80132 nci=0 co=1328 ca=1458 + 3 c=31249 g=31250 pq=1/1 qp=0 dt=107255/140000000000000/0 df=1749 of=6 ql=0/450 qs=NRW. b=10 ci=151700 nci=0 co=509 ca=622 + 4!c=29502 g=29503 pq=1/0 qp=1 dt=83647/140000000000000/0 df=965 of=5 ql=0/0 qs=N... b=10 ci=65643 nci=0 co=1373 ca=1521 + 5 c=31201 g=31202 pq=1/0 qp=1 dt=70422/0/0 df=535 of=7 ql=0/0 qs=.... b=10 ci=58500 nci=0 co=764 ca=698 + 6!c=30253 g=30254 pq=1/0 qp=1 dt=95363/140000000000000/0 df=780 of=5 ql=0/0 qs=N... b=10 ci=100607 nci=0 co=1414 ca=1353 + 7 c=31178 g=31178 pq=1/0 qp=0 dt=91536/0/0 df=547 of=4 ql=0/0 qs=.... b=10 ci=109819 nci=0 co=1115 ca=969 This file has one line per CPU, or eight for this 8-CPU system. The fields are as follows: @@ -188,14 +188,14 @@ o "ca" is the number of RCU callbacks that have been adopted by this Kernels compiled with CONFIG_RCU_BOOST=y display the following from /debug/rcu/rcu_preempt/rcudata: - 0!c=12865 g=12866 pq=1 qp=1 dt=83113/140000000000000/0 df=288 of=11 ql=0/0 qs=N... kt=0/O ktl=944 b=10 ci=60709 nci=0 co=748 ca=871 - 1 c=14407 g=14408 pq=1 qp=0 dt=100679/140000000000000/0 df=378 of=7 ql=0/119 qs=NRW. kt=0/W ktl=9b6 b=10 ci=109740 nci=0 co=589 ca=485 - 2 c=14407 g=14408 pq=1 qp=0 dt=105486/0/0 df=90 of=9 ql=0/89 qs=NRW. kt=0/W ktl=c0c b=10 ci=83113 nci=0 co=533 ca=490 - 3 c=14407 g=14408 pq=1 qp=0 dt=107138/0/0 df=142 of=8 ql=0/188 qs=NRW. kt=0/W ktl=b96 b=10 ci=121114 nci=0 co=426 ca=290 - 4 c=14405 g=14406 pq=1 qp=1 dt=50238/0/0 df=706 of=7 ql=0/0 qs=.... kt=0/W ktl=812 b=10 ci=34929 nci=0 co=643 ca=114 - 5!c=14168 g=14169 pq=1 qp=0 dt=45465/140000000000000/0 df=161 of=11 ql=0/0 qs=N... kt=0/O ktl=b4d b=10 ci=47712 nci=0 co=677 ca=722 - 6 c=14404 g=14405 pq=1 qp=0 dt=59454/0/0 df=94 of=6 ql=0/0 qs=.... kt=0/W ktl=e57 b=10 ci=55597 nci=0 co=701 ca=811 - 7 c=14407 g=14408 pq=1 qp=1 dt=68850/0/0 df=31 of=8 ql=0/0 qs=.... kt=0/W ktl=14bd b=10 ci=77475 nci=0 co=508 ca=1042 + 0!c=12865 g=12866 pq=1/0 qp=1 dt=83113/140000000000000/0 df=288 of=11 ql=0/0 qs=N... kt=0/O ktl=944 b=10 ci=60709 nci=0 co=748 ca=871 + 1 c=14407 g=14408 pq=1/0 qp=0 dt=100679/140000000000000/0 df=378 of=7 ql=0/119 qs=NRW. kt=0/W ktl=9b6 b=10 ci=109740 nci=0 co=589 ca=485 + 2 c=14407 g=14408 pq=1/0 qp=0 dt=105486/0/0 df=90 of=9 ql=0/89 qs=NRW. kt=0/W ktl=c0c b=10 ci=83113 nci=0 co=533 ca=490 + 3 c=14407 g=14408 pq=1/0 qp=0 dt=107138/0/0 df=142 of=8 ql=0/188 qs=NRW. kt=0/W ktl=b96 b=10 ci=121114 nci=0 co=426 ca=290 + 4 c=14405 g=14406 pq=1/0 qp=1 dt=50238/0/0 df=706 of=7 ql=0/0 qs=.... kt=0/W ktl=812 b=10 ci=34929 nci=0 co=643 ca=114 + 5!c=14168 g=14169 pq=1/0 qp=0 dt=45465/140000000000000/0 df=161 of=11 ql=0/0 qs=N... kt=0/O ktl=b4d b=10 ci=47712 nci=0 co=677 ca=722 + 6 c=14404 g=14405 pq=1/0 qp=0 dt=59454/0/0 df=94 of=6 ql=0/0 qs=.... kt=0/W ktl=e57 b=10 ci=55597 nci=0 co=701 ca=811 + 7 c=14407 g=14408 pq=1/0 qp=1 dt=68850/0/0 df=31 of=8 ql=0/0 qs=.... kt=0/W ktl=14bd b=10 ci=77475 nci=0 co=508 ca=1042 This is similar to the output discussed above, but contains the following additional fields: diff --git a/Documentation/RCU/whatisRCU.txt b/Documentation/RCU/whatisRCU.txt index e48c57f1943b..88dfce182f66 100644 --- a/Documentation/RCU/whatisRCU.txt +++ b/Documentation/RCU/whatisRCU.txt @@ -137,7 +137,7 @@ rcu_read_lock() Used by a reader to inform the reclaimer that the reader is entering an RCU read-side critical section. It is illegal to block while in an RCU read-side critical section, though - kernels built with CONFIG_TREE_PREEMPT_RCU can preempt RCU + kernels built with CONFIG_PREEMPT_RCU can preempt RCU read-side critical sections. Any RCU-protected data structure accessed during an RCU read-side critical section is guaranteed to remain unreclaimed for the full duration of that critical section. diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index 1fa1caa198eb..447671bd2927 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -10,27 +10,49 @@ kernel, the process can sometimes be daunting if you're not familiar with "the system." This text is a collection of suggestions which can greatly increase the chances of your change being accepted. -Read Documentation/SubmitChecklist for a list of items to check -before submitting code. If you are submitting a driver, also read -Documentation/SubmittingDrivers. +This document contains a large number of suggestions in a relatively terse +format. For detailed information on how the kernel development process +works, see Documentation/development-process. Also, read +Documentation/SubmitChecklist for a list of items to check before +submitting code. If you are submitting a driver, also read +Documentation/SubmittingDrivers; for device tree binding patches, read +Documentation/devicetree/bindings/submitting-patches.txt. Many of these steps describe the default behavior of the git version control system; if you use git to prepare your patches, you'll find much of the mechanical work done for you, though you'll still need to prepare -and document a sensible set of patches. +and document a sensible set of patches. In general, use of git will make +your life as a kernel developer easier. -------------------------------------------- SECTION 1 - CREATING AND SENDING YOUR CHANGE -------------------------------------------- +0) Obtain a current source tree +------------------------------- + +If you do not have a repository with the current kernel source handy, use +git to obtain one. You'll want to start with the mainline repository, +which can be grabbed with: + + git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git + +Note, however, that you may not want to develop against the mainline tree +directly. Most subsystem maintainers run their own trees and want to see +patches prepared against those trees. See the "T:" entry for the subsystem +in the MAINTAINERS file to find that tree, or simply ask the maintainer if +the tree is not listed there. + +It is still possible to download kernel releases via tarballs (as described +in the next section), but that is the hard way to do kernel development. 1) "diff -up" ------------ -Use "diff -up" or "diff -uprN" to create patches. git generates patches -in this form by default; if you're using git, you can skip this section -entirely. +If you must generate your patches by hand, use "diff -up" or "diff -uprN" +to create patches. Git generates patches in this form by default; if +you're using git, you can skip this section entirely. All changes to the Linux kernel occur in the form of patches, as generated by diff(1). When creating your patch, make sure to create it @@ -42,7 +64,7 @@ not in any lower subdirectory. To create a patch for a single file, it is often sufficient to do: - SRCTREE= linux-2.6 + SRCTREE= linux MYFILE= drivers/net/mydriver.c cd $SRCTREE @@ -55,17 +77,16 @@ To create a patch for multiple files, you should unpack a "vanilla", or unmodified kernel source tree, and generate a diff against your own source tree. For example: - MYSRC= /devel/linux-2.6 + MYSRC= /devel/linux - tar xvfz linux-2.6.12.tar.gz - mv linux-2.6.12 linux-2.6.12-vanilla - diff -uprN -X linux-2.6.12-vanilla/Documentation/dontdiff \ - linux-2.6.12-vanilla $MYSRC > /tmp/patch + tar xvfz linux-3.19.tar.gz + mv linux-3.19 linux-3.19-vanilla + diff -uprN -X linux-3.19-vanilla/Documentation/dontdiff \ + linux-3.19-vanilla $MYSRC > /tmp/patch "dontdiff" is a list of files which are generated by the kernel during the build process, and should be ignored in any diff(1)-generated -patch. The "dontdiff" file is included in the kernel tree in -2.6.12 and later. +patch. Make sure your patch does not include any extra files which do not belong in a patch submission. Make sure to review your patch -after- @@ -83,6 +104,7 @@ is another popular alternative. 2) Describe your changes. +------------------------- Describe your problem. Whether your patch is a one-line bug fix or 5000 lines of a new feature, there must be an underlying problem that @@ -124,10 +146,10 @@ See #3, next. When you submit or resubmit a patch or patch series, include the complete patch description and justification for it. Don't just say that this is version N of the patch (series). Don't expect the -patch merger to refer back to earlier patch versions or referenced +subsystem maintainer to refer back to earlier patch versions or referenced URLs to find the patch description and put that into the patch. I.e., the patch (series) and its description should be self-contained. -This benefits both the patch merger(s) and reviewers. Some reviewers +This benefits both the maintainers and reviewers. Some reviewers probably didn't even receive earlier versions of the patch. Describe your changes in imperative mood, e.g. "make xyzzy do frotz" @@ -156,10 +178,15 @@ Example: platform_set_drvdata(), but left the variable "dev" unused, delete it. +You should also be sure to use at least the first twelve characters of the +SHA-1 ID. The kernel repository holds a *lot* of objects, making +collisions with shorter IDs a real possibility. Bear in mind that, even if +there is no collision with your six-character ID now, that condition may +change five years from now. + If your patch fixes a bug in a specific commit, e.g. you found an issue using git-bisect, please use the 'Fixes:' tag with the first 12 characters of the -SHA-1 ID, and the one line summary. -Example: +SHA-1 ID, and the one line summary. For example: Fixes: e21d2170f366 ("video: remove unnecessary platform_set_drvdata()") @@ -172,8 +199,9 @@ outputting the above style in the git log or git show commands fixes = Fixes: %h (\"%s\") 3) Separate your changes. +------------------------- -Separate _logical changes_ into a single patch file. +Separate each _logical change_ into a separate patch. For example, if your changes include both bug fixes and performance enhancements for a single driver, separate those changes into two @@ -184,90 +212,116 @@ On the other hand, if you make a single change to numerous files, group those changes into a single patch. Thus a single logical change is contained within a single patch. +The point to remember is that each patch should make an easily understood +change that can be verified by reviewers. Each patch should be justifiable +on its own merits. + If one patch depends on another patch in order for a change to be complete, that is OK. Simply note "this patch depends on patch X" in your patch description. +When dividing your change into a series of patches, take special care to +ensure that the kernel builds and runs properly after each patch in the +series. Developers using "git bisect" to track down a problem can end up +splitting your patch series at any point; they will not thank you if you +introduce bugs in the middle. + If you cannot condense your patch set into a smaller set of patches, then only post say 15 or so at a time and wait for review and integration. -4) Style check your changes. +4) Style-check your changes. +---------------------------- Check your patch for basic style violations, details of which can be found in Documentation/CodingStyle. Failure to do so simply wastes the reviewers time and will get your patch rejected, probably without even being read. -At a minimum you should check your patches with the patch style -checker prior to submission (scripts/checkpatch.pl). You should -be able to justify all violations that remain in your patch. - - +One significant exception is when moving code from one file to +another -- in this case you should not modify the moved code at all in +the same patch which moves it. This clearly delineates the act of +moving the code and your changes. This greatly aids review of the +actual differences and allows tools to better track the history of +the code itself. -5) Select e-mail destination. +Check your patches with the patch style checker prior to submission +(scripts/checkpatch.pl). Note, though, that the style checker should be +viewed as a guide, not as a replacement for human judgment. If your code +looks better with a violation then its probably best left alone. -Look through the MAINTAINERS file and the source code, and determine -if your change applies to a specific subsystem of the kernel, with -an assigned maintainer. If so, e-mail that person. The script -scripts/get_maintainer.pl can be very useful at this step. +The checker reports at three levels: + - ERROR: things that are very likely to be wrong + - WARNING: things requiring careful review + - CHECK: things requiring thought -If no maintainer is listed, or the maintainer does not respond, send -your patch to the primary Linux kernel developer's mailing list, -linux-kernel@vger.kernel.org. Most kernel developers monitor this -e-mail list, and can comment on your changes. +You should be able to justify all violations that remain in your +patch. -Do not send more than 15 patches at once to the vger mailing lists!!! +5) Select the recipients for your patch. +---------------------------------------- +You should always copy the appropriate subsystem maintainer(s) on any patch +to code that they maintain; look through the MAINTAINERS file and the +source code revision history to see who those maintainers are. The +script scripts/get_maintainer.pl can be very useful at this step. If you +cannot find a maintainer for the subsystem your are working on, Andrew +Morton (akpm@linux-foundation.org) serves as a maintainer of last resort. -Linus Torvalds is the final arbiter of all changes accepted into the -Linux kernel. His e-mail address is <torvalds@linux-foundation.org>. -He gets a lot of e-mail, so typically you should do your best to -avoid- -sending him e-mail. +You should also normally choose at least one mailing list to receive a copy +of your patch set. linux-kernel@vger.kernel.org functions as a list of +last resort, but the volume on that list has caused a number of developers +to tune it out. Look in the MAINTAINERS file for a subsystem-specific +list; your patch will probably get more attention there. Please do not +spam unrelated lists, though. -Patches which are bug fixes, are "obvious" changes, or similarly -require little discussion should be sent or CC'd to Linus. Patches -which require discussion or do not have a clear advantage should -usually be sent first to linux-kernel. Only after the patch is -discussed should the patch then be submitted to Linus. +Many kernel-related lists are hosted on vger.kernel.org; you can find a +list of them at http://vger.kernel.org/vger-lists.html. There are +kernel-related lists hosted elsewhere as well, though. +Do not send more than 15 patches at once to the vger mailing lists!!! +Linus Torvalds is the final arbiter of all changes accepted into the +Linux kernel. His e-mail address is <torvalds@linux-foundation.org>. +He gets a lot of e-mail, and, at this point, very few patches go through +Linus directly, so typically you should do your best to -avoid- +sending him e-mail. -6) Select your CC (e-mail carbon copy) list. +If you have a patch that fixes an exploitable security bug, send that patch +to security@kernel.org. For severe bugs, a short embargo may be considered +to allow distrbutors to get the patch out to users; in such cases, +obviously, the patch should not be sent to any public lists. -Unless you have a reason NOT to do so, CC linux-kernel@vger.kernel.org. +Patches that fix a severe bug in a released kernel should be directed +toward the stable maintainers by putting a line like this: -Other kernel developers besides Linus need to be aware of your change, -so that they may comment on it and offer code review and suggestions. -linux-kernel is the primary Linux kernel developer mailing list. -Other mailing lists are available for specific subsystems, such as -USB, framebuffer devices, the VFS, the SCSI subsystem, etc. See the -MAINTAINERS file for a mailing list that relates specifically to -your change. + Cc: stable@vger.kernel.org -Majordomo lists of VGER.KERNEL.ORG at: - <http://vger.kernel.org/vger-lists.html> +into your patch. -If changes affect userland-kernel interfaces, please send -the MAN-PAGES maintainer (as listed in the MAINTAINERS file) -a man-pages patch, or at least a notification of the change, -so that some information makes its way into the manual pages. +Note, however, that some subsystem maintainers want to come to their own +conclusions on which patches should go to the stable trees. The networking +maintainer, in particular, would rather not see individual developers +adding lines like the above to their patches. -Even if the maintainer did not respond in step #5, make sure to ALWAYS -copy the maintainer when you change their code. +If changes affect userland-kernel interfaces, please send the MAN-PAGES +maintainer (as listed in the MAINTAINERS file) a man-pages patch, or at +least a notification of the change, so that some information makes its way +into the manual pages. User-space API changes should also be copied to +linux-api@vger.kernel.org. For small patches you may want to CC the Trivial Patch Monkey trivial@kernel.org which collects "trivial" patches. Have a look into the MAINTAINERS file for its current manager. Trivial patches must qualify for one of the following rules: Spelling fixes in documentation - Spelling fixes which could break grep(1) + Spelling fixes for errors which could break grep(1) Warning fixes (cluttering with useless warnings is bad) Compilation fixes (only if they are actually correct) Runtime fixes (only if they actually fix things) - Removing use of deprecated functions/macros (eg. check_region) + Removing use of deprecated functions/macros Contact detail and documentation fixes Non-portable code replaced by portable code (even in arch-specific, since people copy, as long as it's trivial) @@ -276,7 +330,8 @@ Trivial patches must qualify for one of the following rules: -7) No MIME, no links, no compression, no attachments. Just plain text. +6) No MIME, no links, no compression, no attachments. Just plain text. +----------------------------------------------------------------------- Linus and other kernel developers need to be able to read and comment on the changes you are submitting. It is important for a kernel @@ -299,54 +354,48 @@ you to re-send them using MIME. See Documentation/email-clients.txt for hints about configuring your e-mail client so that it sends your patches untouched. -8) E-mail size. - -When sending patches to Linus, always follow step #7. +7) E-mail size. +--------------- Large changes are not appropriate for mailing lists, and some maintainers. If your patch, uncompressed, exceeds 300 kB in size, it is preferred that you store your patch on an Internet-accessible -server, and provide instead a URL (link) pointing to your patch. +server, and provide instead a URL (link) pointing to your patch. But note +that if your patch exceeds 300 kB, it almost certainly needs to be broken up +anyway. +8) Respond to review comments. +------------------------------ +Your patch will almost certainly get comments from reviewers on ways in +which the patch can be improved. You must respond to those comments; +ignoring reviewers is a good way to get ignored in return. Review comments +or questions that do not lead to a code change should almost certainly +bring about a comment or changelog entry so that the next reviewer better +understands what is going on. -9) Name your kernel version. +Be sure to tell the reviewers what changes you are making and to thank them +for their time. Code review is a tiring and time-consuming process, and +reviewers sometimes get grumpy. Even in that case, though, respond +politely and address the problems they have pointed out. -It is important to note, either in the subject line or in the patch -description, the kernel version to which this patch applies. -If the patch does not apply cleanly to the latest kernel version, -Linus will not apply it. +9) Don't get discouraged - or impatient. +---------------------------------------- +After you have submitted your change, be patient and wait. Reviewers are +busy people and may not get to your patch right away. +Once upon a time, patches used to disappear into the void without comment, +but the development process works more smoothly than that now. You should +receive comments within a week or so; if that does not happen, make sure +that you have sent your patches to the right place. Wait for a minimum of +one week before resubmitting or pinging reviewers - possibly longer during +busy times like merge windows. -10) Don't get discouraged. Re-submit. -After you have submitted your change, be patient and wait. If Linus -likes your change and applies it, it will appear in the next version -of the kernel that he releases. - -However, if your change doesn't appear in the next version of the -kernel, there could be any number of reasons. It's YOUR job to -narrow down those reasons, correct what was wrong, and submit your -updated change. - -It is quite common for Linus to "drop" your patch without comment. -That's the nature of the system. If he drops your patch, it could be -due to -* Your patch did not apply cleanly to the latest kernel version. -* Your patch was not sufficiently discussed on linux-kernel. -* A style issue (see section 2). -* An e-mail formatting issue (re-read this section). -* A technical problem with your change. -* He gets tons of e-mail, and yours got lost in the shuffle. -* You are being annoying. - -When in doubt, solicit comments on linux-kernel mailing list. - - - -11) Include PATCH in the subject +10) Include PATCH in the subject +-------------------------------- Due to high e-mail traffic to Linus, and to linux-kernel, it is common convention to prefix your subject line with [PATCH]. This lets Linus @@ -355,7 +404,8 @@ e-mail discussions. -12) Sign your work +11) Sign your work +------------------ To improve tracking of who did what, especially with patches that can percolate to their final resting place in the kernel through several @@ -387,11 +437,11 @@ can certify the below: person who certified (a), (b) or (c) and I have not modified it. - (d) I understand and agree that this project and the contribution - are public and that a record of the contribution (including all - personal information I submit with it, including my sign-off) is - maintained indefinitely and may be redistributed consistent with - this project or the open source license(s) involved. + (d) I understand and agree that this project and the contribution + are public and that a record of the contribution (including all + personal information I submit with it, including my sign-off) is + maintained indefinitely and may be redistributed consistent with + this project or the open source license(s) involved. then you just add a line saying @@ -401,7 +451,7 @@ using your real name (sorry, no pseudonyms or anonymous contributions.) Some people also put extra tags at the end. They'll just be ignored for now, but you can do this to mark internal company procedures or just -point out some special detail about the sign-off. +point out some special detail about the sign-off. If you are a subsystem or branch maintainer, sometimes you need to slightly modify patches you receive in order to merge them, because the code is not @@ -429,15 +479,15 @@ which appears in the changelog. Special note to back-porters: It seems to be a common and useful practice to insert an indication of the origin of a patch at the top of the commit message (just after the subject line) to facilitate tracking. For instance, -here's what we see in 2.6-stable : +here's what we see in a 3.x-stable release: - Date: Tue May 13 19:10:30 2008 +0000 +Date: Tue Oct 7 07:26:38 2014 -0400 - SCSI: libiscsi regression in 2.6.25: fix nop timer handling + libata: Un-break ATA blacklist - commit 4cf1043593db6a337f10e006c23c69e5fc93e722 upstream + commit 1c40279960bcd7d52dbdf1d466b20d24b99176c8 upstream. -And here's what appears in 2.4 : +And here's what might appear in an older kernel once a patch is backported: Date: Tue May 13 22:12:27 2008 +0200 @@ -446,18 +496,19 @@ And here's what appears in 2.4 : [backport of 2.6 commit b7acbdfbd1f277c1eb23f344f899cfa4cd0bf36a] Whatever the format, this information provides a valuable help to people -tracking your trees, and to people trying to trouble-shoot bugs in your +tracking your trees, and to people trying to troubleshoot bugs in your tree. -13) When to use Acked-by: and Cc: +12) When to use Acked-by: and Cc: +--------------------------------- The Signed-off-by: tag indicates that the signer was involved in the development of the patch, or that he/she was in the patch's delivery path. If a person was not directly involved in the preparation or handling of a patch but wishes to signify and record their approval of it then they can -arrange to have an Acked-by: line added to the patch's changelog. +ask to have an Acked-by: line added to the patch's changelog. Acked-by: is often used by the maintainer of the affected code when that maintainer neither contributed to nor forwarded the patch. @@ -465,7 +516,8 @@ maintainer neither contributed to nor forwarded the patch. Acked-by: is not as formal as Signed-off-by:. It is a record that the acker has at least reviewed the patch and has indicated acceptance. Hence patch mergers will sometimes manually convert an acker's "yep, looks good to me" -into an Acked-by:. +into an Acked-by: (but note that it is usually better to ask for an +explicit ack). Acked-by: does not necessarily indicate acknowledgement of the entire patch. For example, if a patch affects multiple subsystems and has an Acked-by: from @@ -477,11 +529,13 @@ list archives. If a person has had the opportunity to comment on a patch, but has not provided such comments, you may optionally add a "Cc:" tag to the patch. This is the only tag which might be added without an explicit action by the -person it names. This tag documents that potentially interested parties -have been included in the discussion +person it names - but it should indicate that this person was copied on the +patch. This tag documents that potentially interested parties +have been included in the discussion. -14) Using Reported-by:, Tested-by:, Reviewed-by:, Suggested-by: and Fixes: +13) Using Reported-by:, Tested-by:, Reviewed-by:, Suggested-by: and Fixes: +-------------------------------------------------------------------------- The Reported-by tag gives credit to people who find bugs and report them and it hopefully inspires them to help us again in the future. Please note that if @@ -541,7 +595,13 @@ which stable kernel versions should receive your fix. This is the preferred method for indicating a bug fixed by the patch. See #2 above for more details. -15) The canonical patch format +14) The canonical patch format +------------------------------ + +This section describes how the patch itself should be formatted. Note +that, if you have your patches stored in a git repository, proper patch +formatting can be had with "git format-patch". The tools cannot create +the necessary text, though, so read the instructions below anyway. The canonical patch subject line is: @@ -549,7 +609,8 @@ The canonical patch subject line is: The canonical patch message body contains the following: - - A "from" line specifying the patch author. + - A "from" line specifying the patch author (only needed if the person + sending the patch is not the author). - An empty line. @@ -656,128 +717,63 @@ See more details on the proper patch format in the following references. -16) Sending "git pull" requests (from Linus emails) - -Please write the git repo address and branch name alone on the same line -so that I can't even by mistake pull from the wrong branch, and so -that a triple-click just selects the whole thing. - -So the proper format is something along the lines of: - - "Please pull from - - git://jdelvare.pck.nerim.net/jdelvare-2.6 i2c-for-linus - - to get these changes:" - -so that I don't have to hunt-and-peck for the address and inevitably -get it wrong (actually, I've only gotten it wrong a few times, and -checking against the diffstat tells me when I get it wrong, but I'm -just a lot more comfortable when I don't have to "look for" the right -thing to pull, and double-check that I have the right branch-name). - - -Please use "git diff -M --stat --summary" to generate the diffstat: -the -M enables rename detection, and the summary enables a summary of -new/deleted or renamed files. - -With rename detection, the statistics are rather different [...] -because git will notice that a fair number of the changes are renames. - ------------------------------------ -SECTION 2 - HINTS, TIPS, AND TRICKS ------------------------------------ - -This section lists many of the common "rules" associated with code -submitted to the kernel. There are always exceptions... but you must -have a really good reason for doing so. You could probably call this -section Linus Computer Science 101. - - - -1) Read Documentation/CodingStyle - -Nuff said. If your code deviates too much from this, it is likely -to be rejected without further review, and without comment. - -One significant exception is when moving code from one file to -another -- in this case you should not modify the moved code at all in -the same patch which moves it. This clearly delineates the act of -moving the code and your changes. This greatly aids review of the -actual differences and allows tools to better track the history of -the code itself. - -Check your patches with the patch style checker prior to submission -(scripts/checkpatch.pl). The style checker should be viewed as -a guide not as the final word. If your code looks better with -a violation then its probably best left alone. - -The checker reports at three levels: - - ERROR: things that are very likely to be wrong - - WARNING: things requiring careful review - - CHECK: things requiring thought - -You should be able to justify all violations that remain in your -patch. - - - -2) #ifdefs are ugly - -Code cluttered with ifdefs is difficult to read and maintain. Don't do -it. Instead, put your ifdefs in a header, and conditionally define -'static inline' functions, or macros, which are used in the code. -Let the compiler optimize away the "no-op" case. - -Simple example, of poor code: - - dev = alloc_etherdev (sizeof(struct funky_private)); - if (!dev) - return -ENODEV; - #ifdef CONFIG_NET_FUNKINESS - init_funky_net(dev); - #endif - -Cleaned-up example: - -(in header) - #ifndef CONFIG_NET_FUNKINESS - static inline void init_funky_net (struct net_device *d) {} - #endif +15) Sending "git pull" requests +------------------------------- -(in the code itself) - dev = alloc_etherdev (sizeof(struct funky_private)); - if (!dev) - return -ENODEV; - init_funky_net(dev); +If you have a series of patches, it may be most convenient to have the +maintainer pull them directly into the subsystem repository with a +"git pull" operation. Note, however, that pulling patches from a developer +requires a higher degree of trust than taking patches from a mailing list. +As a result, many subsystem maintainers are reluctant to take pull +requests, especially from new, unknown developers. If in doubt you can use +the pull request as the cover letter for a normal posting of the patch +series, giving the maintainer the option of using either. +A pull request should have [GIT] or [PULL] in the subject line. The +request itself should include the repository name and the branch of +interest on a single line; it should look something like: + Please pull from -3) 'static inline' is better than a macro + git://jdelvare.pck.nerim.net/jdelvare-2.6 i2c-for-linus -Static inline functions are greatly preferred over macros. -They provide type safety, have no length limitations, no formatting -limitations, and under gcc they are as cheap as macros. + to get these changes:" -Macros should only be used for cases where a static inline is clearly -suboptimal [there are a few, isolated cases of this in fast paths], -or where it is impossible to use a static inline function [such as -string-izing]. +A pull request should also include an overall message saying what will be +included in the request, a "git shortlog" listing of the patches +themselves, and a diffstat showing the overall effect of the patch series. +The easiest way to get all this information together is, of course, to let +git do it for you with the "git request-pull" command. -'static inline' is preferred over 'static __inline__', 'extern inline', -and 'extern __inline__'. +Some maintainers (including Linus) want to see pull requests from signed +commits; that increases their confidence that the request actually came +from you. Linus, in particular, will not pull from public hosting sites +like GitHub in the absence of a signed tag. +The first step toward creating such tags is to make a GNUPG key and get it +signed by one or more core kernel developers. This step can be hard for +new developers, but there is no way around it. Attending conferences can +be a good way to find developers who can sign your key. +Once you have prepared a patch series in git that you wish to have somebody +pull, create a signed tag with "git tag -s". This will create a new tag +identifying the last commit in the series and containing a signature +created with your private key. You will also have the opportunity to add a +changelog-style message to the tag; this is an ideal place to describe the +effects of the pull request as a whole. -4) Don't over-design. +If the tree the maintainer will be pulling from is not the repository you +are working from, don't forget to push the signed tag explicitly to the +public tree. -Don't try to anticipate nebulous future cases which may or may not -be useful: "Make it as simple as you can, and no simpler." +When generating your pull request, use the signed tag as the target. A +command like this will do the trick: + git request-pull master git://my.public.tree/linux.git my-signed-tag ---------------------- -SECTION 3 - REFERENCES +SECTION 2 - REFERENCES ---------------------- Andrew Morton, "The perfect patch" (tpp). diff --git a/Documentation/acpi/enumeration.txt b/Documentation/acpi/enumeration.txt index b60d2ab69497..9b121a569ab4 100644 --- a/Documentation/acpi/enumeration.txt +++ b/Documentation/acpi/enumeration.txt @@ -243,7 +243,7 @@ input driver: .owner = THIS_MODULE, .pm = &mpu3050_pm, .of_match_table = mpu3050_of_match, - .acpi_match_table ACPI_PTR(mpu3050_acpi_match), + .acpi_match_table = ACPI_PTR(mpu3050_acpi_match), }, .probe = mpu3050_probe, .remove = mpu3050_remove, diff --git a/Documentation/acpi/gpio-properties.txt b/Documentation/acpi/gpio-properties.txt new file mode 100644 index 000000000000..ae36fcf86dc7 --- /dev/null +++ b/Documentation/acpi/gpio-properties.txt @@ -0,0 +1,96 @@ +_DSD Device Properties Related to GPIO +-------------------------------------- + +With the release of ACPI 5.1 and the _DSD configuration objecte names +can finally be given to GPIOs (and other things as well) returned by +_CRS. Previously, we were only able to use an integer index to find +the corresponding GPIO, which is pretty error prone (it depends on +the _CRS output ordering, for example). + +With _DSD we can now query GPIOs using a name instead of an integer +index, like the ASL example below shows: + + // Bluetooth device with reset and shutdown GPIOs + Device (BTH) + { + Name (_HID, ...) + + Name (_CRS, ResourceTemplate () + { + GpioIo (Exclusive, PullUp, 0, 0, IoRestrictionInputOnly, + "\\_SB.GPO0", 0, ResourceConsumer) {15} + GpioIo (Exclusive, PullUp, 0, 0, IoRestrictionInputOnly, + "\\_SB.GPO0", 0, ResourceConsumer) {27, 31} + }) + + Name (_DSD, Package () + { + ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"), + Package () + { + Package () {"reset-gpio", Package() {^BTH, 1, 1, 0 }}, + Package () {"shutdown-gpio", Package() {^BTH, 0, 0, 0 }}, + } + }) + } + +The format of the supported GPIO property is: + + Package () { "name", Package () { ref, index, pin, active_low }} + + ref - The device that has _CRS containing GpioIo()/GpioInt() resources, + typically this is the device itself (BTH in our case). + index - Index of the GpioIo()/GpioInt() resource in _CRS starting from zero. + pin - Pin in the GpioIo()/GpioInt() resource. Typically this is zero. + active_low - If 1 the GPIO is marked as active_low. + +Since ACPI GpioIo() resource does not have a field saying whether it is +active low or high, the "active_low" argument can be used here. Setting +it to 1 marks the GPIO as active low. + +In our Bluetooth example the "reset-gpio" refers to the second GpioIo() +resource, second pin in that resource with the GPIO number of 31. + +ACPI GPIO Mappings Provided by Drivers +-------------------------------------- + +There are systems in which the ACPI tables do not contain _DSD but provide _CRS +with GpioIo()/GpioInt() resources and device drivers still need to work with +them. + +In those cases ACPI device identification objects, _HID, _CID, _CLS, _SUB, _HRV, +available to the driver can be used to identify the device and that is supposed +to be sufficient to determine the meaning and purpose of all of the GPIO lines +listed by the GpioIo()/GpioInt() resources returned by _CRS. In other words, +the driver is supposed to know what to use the GpioIo()/GpioInt() resources for +once it has identified the device. Having done that, it can simply assign names +to the GPIO lines it is going to use and provide the GPIO subsystem with a +mapping between those names and the ACPI GPIO resources corresponding to them. + +To do that, the driver needs to define a mapping table as a NULL-terminated +array of struct acpi_gpio_mapping objects that each contain a name, a pointer +to an array of line data (struct acpi_gpio_params) objects and the size of that +array. Each struct acpi_gpio_params object consists of three fields, +crs_entry_index, line_index, active_low, representing the index of the target +GpioIo()/GpioInt() resource in _CRS starting from zero, the index of the target +line in that resource starting from zero, and the active-low flag for that line, +respectively, in analogy with the _DSD GPIO property format specified above. + +For the example Bluetooth device discussed previously the data structures in +question would look like this: + +static const struct acpi_gpio_params reset_gpio = { 1, 1, false }; +static const struct acpi_gpio_params shutdown_gpio = { 0, 0, false }; + +static const struct acpi_gpio_mapping bluetooth_acpi_gpios[] = { + { "reset-gpio", &reset_gpio, 1 }, + { "shutdown-gpio", &shutdown_gpio, 1 }, + { }, +}; + +Next, the mapping table needs to be passed as the second argument to +acpi_dev_add_driver_gpios() that will register it with the ACPI device object +pointed to by its first argument. That should be done in the driver's .probe() +routine. On removal, the driver should unregister its GPIO mapping table by +calling acpi_dev_remove_driver_gpios() on the ACPI device object where that +table was previously registered. diff --git a/Documentation/arm/00-INDEX b/Documentation/arm/00-INDEX index 3b08bc2b04cf..8edb9007844e 100644 --- a/Documentation/arm/00-INDEX +++ b/Documentation/arm/00-INDEX @@ -2,11 +2,15 @@ - this file Booting - requirements for booting +CCN.txt + - Cache Coherent Network ring-bus and perf PMU driver. Interrupts - ARM Interrupt subsystem documentation IXP4xx - Intel IXP4xx Network processor. -msm +Makefile + - Build sourcefiles as part of the Documentation-build for arm +msm/ - MSM specific documentation Netwinder - Netwinder specific documentation @@ -18,11 +22,9 @@ README - General ARM documentation SA1100/ - SA1100 documentation -Samsung-S3C24XX +Samsung-S3C24XX/ - S3C24XX ARM Linux Overview -Sharp-LH - - Linux on Sharp LH79524 and LH7A40X System On a Chip (SOC) -SPEAr +SPEAr/ - ST SPEAr platform Linux Overview VFP/ - Release notes for Linux Kernel Vector Floating Point support code diff --git a/Documentation/arm/Atmel/README b/Documentation/arm/Atmel/README new file mode 100644 index 000000000000..c53a19b4aab2 --- /dev/null +++ b/Documentation/arm/Atmel/README @@ -0,0 +1,124 @@ +ARM Atmel SoCs (aka AT91) +========================= + + +Introduction +------------ +This document gives useful information about the ARM Atmel SoCs that are +currently supported in Linux Mainline (you know, the one on kernel.org). + +It is important to note that the Atmel | SMART ARM-based MPU product line is +historically named "AT91" or "at91" throughout the Linux kernel development +process even if this product prefix has completely disappeared from the +official Atmel product name. Anyway, files, directories, git trees, +git branches/tags and email subject always contain this "at91" sub-string. + + +AT91 SoCs +--------- +Documentation and detailled datasheet for each product are available on +the Atmel website: http://www.atmel.com. + + Flavors: + * ARM 920 based SoC + - at91rm9200 + + Datasheet + http://www.atmel.com/Images/doc1768.pdf + + * ARM 926 based SoCs + - at91sam9260 + + Datasheet + http://www.atmel.com/Images/doc6221.pdf + + - at91sam9xe + + Datasheet + http://www.atmel.com/Images/Atmel-6254-32-bit-ARM926EJ-S-Embedded-Microprocessor-SAM9XE_Datasheet.pdf + + - at91sam9261 + + Datasheet + http://www.atmel.com/Images/doc6062.pdf + + - at91sam9263 + + Datasheet + http://www.atmel.com/Images/Atmel_6249_32-bit-ARM926EJ-S-Microcontroller_SAM9263_Datasheet.pdf + + - at91sam9rl + + Datasheet + http://www.atmel.com/Images/doc6289.pdf + + - at91sam9g20 + + Datasheet + http://www.atmel.com/Images/doc6384.pdf + + - at91sam9g45 family + - at91sam9g45 + - at91sam9g46 + - at91sam9m10 + - at91sam9m11 (device superset) + + Datasheet + http://www.atmel.com/Images/Atmel-6437-32-bit-ARM926-Embedded-Microprocessor-SAM9M11_Datasheet.pdf + + - at91sam9x5 family (aka "The 5 series") + - at91sam9g15 + - at91sam9g25 + - at91sam9g35 + - at91sam9x25 + - at91sam9x35 + + Datasheet (can be considered as covering the whole family) + http://www.atmel.com/Images/Atmel_11055_32-bit-ARM926EJ-S-Microcontroller_SAM9X35_Datasheet.pdf + + - at91sam9n12 + + Datasheet + http://www.atmel.com/Images/Atmel_11063_32-bit-ARM926EJ-S-Microcontroller_SAM9N12CN11CN12_Datasheet.pdf + + * ARM Cortex-A5 based SoCs + - sama5d3 family + - sama5d31 + - sama5d33 + - sama5d34 + - sama5d35 + - sama5d36 (device superset) + + Datasheet + http://www.atmel.com/Images/Atmel-11121-32-bit-Cortex-A5-Microcontroller-SAMA5D3_Datasheet.pdf + + * ARM Cortex-A5 + NEON based SoCs + - sama5d4 family + - sama5d41 + - sama5d42 + - sama5d43 + - sama5d44 (device superset) + + Datasheet + http://www.atmel.com/Images/Atmel-11238-32-bit-Cortex-A5-Microcontroller-SAMA5D4_Datasheet.pdf + + +Linux kernel information +------------------------ +Linux kernel mach directory: arch/arm/mach-at91 +MAINTAINERS entry is: "ARM/ATMEL AT91RM9200 AND AT91SAM ARM ARCHITECTURES" + + +Device Tree for AT91 SoCs and boards +------------------------------------ +All AT91 SoCs are converted to Device Tree. Since Linux 3.19, these products +must use this method to boot the Linux kernel. + +Work In Progress statement: +Device Tree files and Device Tree bindings that apply to AT91 SoCs and boards are +considered as "Unstable". To be completely clear, any at91 binding can change at +any time. So, be sure to use a Device Tree Binary and a Kernel Image generated from +the same source tree. +Please refer to the Documentation/devicetree/bindings/ABI.txt file for a +definition of a "Stable" binding/ABI. +This statement will be removed by AT91 MAINTAINERS when appropriate. + +Naming conventions and best practice: +- SoCs Device Tree Source Include files are named after the official name of + the product (at91sam9g20.dtsi or sama5d33.dtsi for instance). +- Device Tree Source Include files (.dtsi) are used to collect common nodes that can be + shared across SoCs or boards (sama5d3.dtsi or at91sam9x5cm.dtsi for instance). + When collecting nodes for a particular peripheral or topic, the identifier have to + be placed at the end of the file name, separated with a "_" (at91sam9x5_can.dtsi + or sama5d3_gmac.dtsi for example). +- board Device Tree Source files (.dts) are prefixed by the string "at91-" so + that they can be identified easily. Note that some files are historical exceptions + to this rule (sama5d3[13456]ek.dts, usb_a9g20.dts or animeo_ip.dts for example). diff --git a/Documentation/arm/Samsung-S3C24XX/DMA.txt b/Documentation/arm/Samsung-S3C24XX/DMA.txt deleted file mode 100644 index 3ed82383efea..000000000000 --- a/Documentation/arm/Samsung-S3C24XX/DMA.txt +++ /dev/null @@ -1,46 +0,0 @@ - S3C2410 DMA - =========== - -Introduction ------------- - - The kernel provides an interface to manage DMA transfers - using the DMA channels in the CPU, so that the central - duty of managing channel mappings, and programming the - channel generators is in one place. - - -DMA Channel Ordering --------------------- - - Many of the range do not have connections for the DMA - channels to all sources, which means that some devices - have a restricted number of channels that can be used. - - To allow flexibility for each CPU type and board, the - DMA code can be given a DMA ordering structure which - allows the order of channel search to be specified, as - well as allowing the prohibition of certain claims. - - struct s3c24xx_dma_order has a list of channels, and - each channel within has a slot for a list of DMA - channel numbers. The slots are searched in order for - the presence of a DMA channel number with DMA_CH_VALID - or-ed in. - - If the order has the flag DMA_CH_NEVER set, then after - checking the channel list, the system will return no - found channel, thus denying the request. - - A board support file can call s3c24xx_dma_order_set() - to register a complete ordering set. The routine will - copy the data, so the original can be discarded with - __initdata. - - -Authour -------- - -Ben Dooks, -Copyright (c) 2007 Ben Dooks, Simtec Electronics -Licensed under the GPL v2 diff --git a/Documentation/arm/firmware.txt b/Documentation/arm/firmware.txt index c2e468fe7b0b..da6713adac8a 100644 --- a/Documentation/arm/firmware.txt +++ b/Documentation/arm/firmware.txt @@ -7,32 +7,14 @@ world, which changes the way some things have to be initialized. This makes a need to provide an interface for such platforms to specify available firmware operations and call them when needed. -Firmware operations can be specified using struct firmware_ops - - struct firmware_ops { - /* - * Enters CPU idle mode - */ - int (*do_idle)(void); - /* - * Sets boot address of specified physical CPU - */ - int (*set_cpu_boot_addr)(int cpu, unsigned long boot_addr); - /* - * Boots specified physical CPU - */ - int (*cpu_boot)(int cpu); - /* - * Initializes L2 cache - */ - int (*l2x0_init)(void); - }; - -and then registered with register_firmware_ops function +Firmware operations can be specified by filling in a struct firmware_ops +with appropriate callbacks and then registering it with register_firmware_ops() +function. void register_firmware_ops(const struct firmware_ops *ops) -the ops pointer must be non-NULL. +The ops pointer must be non-NULL. More information about struct firmware_ops +and its members can be found in arch/arm/include/asm/firmware.h header. There is a default, empty set of operations provided, so there is no need to set anything if platform does not require firmware operations. diff --git a/Documentation/arm/memory.txt b/Documentation/arm/memory.txt index 38dc06d0a791..4178ebda6e66 100644 --- a/Documentation/arm/memory.txt +++ b/Documentation/arm/memory.txt @@ -41,7 +41,7 @@ fffe8000 fffeffff DTCM mapping area for platforms with fffe0000 fffe7fff ITCM mapping area for platforms with ITCM mounted inside the CPU. -ffc00000 ffdfffff Fixmap mapping region. Addresses provided +ffc00000 ffefffff Fixmap mapping region. Addresses provided by fix_to_virt() will be located here. fee00000 feffffff Mapping of PCI I/O space. This is a static diff --git a/Documentation/arm/sti/stih418-overview.txt b/Documentation/arm/sti/stih418-overview.txt new file mode 100644 index 000000000000..1cd8fc80646d --- /dev/null +++ b/Documentation/arm/sti/stih418-overview.txt @@ -0,0 +1,20 @@ + STiH418 Overview + ================ + +Introduction +------------ + + The STiH418 is the new generation of SoC for UHDp60 set-top boxes + and server/connected client application for satellite, cable, terrestrial + and IP-STB markets. + + Features + - ARM Cortex-A9 1.5 GHz quad core CPU (28nm) + - SATA2, USB 3.0, PCIe, Gbit Ethernet + - HEVC L5.1 Main 10 + - VP9 + + Document Author + --------------- + + Maxime Coquelin <maxime.coquelin@st.com>, (c) 2015 ST Microelectronics diff --git a/Documentation/arm/sunxi/README b/Documentation/arm/sunxi/README index 7945238453ed..1fe2d7fd4108 100644 --- a/Documentation/arm/sunxi/README +++ b/Documentation/arm/sunxi/README @@ -37,16 +37,25 @@ SunXi family http://dl.linux-sunxi.org/A20/A20%20User%20Manual%202013-03-22.pdf - Allwinner A23 - + Not Supported + + Datasheet + http://dl.linux-sunxi.org/A23/A23%20Datasheet%20V1.0%2020130830.pdf + + User Manual + http://dl.linux-sunxi.org/A23/A23%20User%20Manual%20V1.0%2020130830.pdf * Quad ARM Cortex-A7 based SoCs - Allwinner A31 (sun6i) + Datasheet - http://dl.linux-sunxi.org/A31/A31%20Datasheet%20-%20v1.00%20(2012-12-24).pdf + http://dl.linux-sunxi.org/A31/A3x_release_document/A31/IC/A31%20datasheet%20V1.3%2020131106.pdf + + User Manual + http://dl.linux-sunxi.org/A31/A3x_release_document/A31/IC/A31%20user%20manual%20V1.1%2020130630.pdf - Allwinner A31s (sun6i) - + Not Supported + + Datasheet + http://dl.linux-sunxi.org/A31/A3x_release_document/A31s/IC/A31s%20datasheet%20V1.3%2020131106.pdf + + User Manual + http://dl.linux-sunxi.org/A31/A3x_release_document/A31s/IC/A31s%20User%20Manual%20%20V1.0%2020130322.pdf * Quad ARM Cortex-A15, Quad ARM Cortex-A7 based SoCs - Allwinner A80 - + Not Supported
\ No newline at end of file + + Datasheet + http://dl.linux-sunxi.org/A80/A80_Datasheet_Revision_1.0_0404.pdf diff --git a/Documentation/arm64/legacy_instructions.txt b/Documentation/arm64/legacy_instructions.txt new file mode 100644 index 000000000000..01bf3d9fac85 --- /dev/null +++ b/Documentation/arm64/legacy_instructions.txt @@ -0,0 +1,57 @@ +The arm64 port of the Linux kernel provides infrastructure to support +emulation of instructions which have been deprecated, or obsoleted in +the architecture. The infrastructure code uses undefined instruction +hooks to support emulation. Where available it also allows turning on +the instruction execution in hardware. + +The emulation mode can be controlled by writing to sysctl nodes +(/proc/sys/abi). The following explains the different execution +behaviours and the corresponding values of the sysctl nodes - + +* Undef + Value: 0 + Generates undefined instruction abort. Default for instructions that + have been obsoleted in the architecture, e.g., SWP + +* Emulate + Value: 1 + Uses software emulation. To aid migration of software, in this mode + usage of emulated instruction is traced as well as rate limited + warnings are issued. This is the default for deprecated + instructions, .e.g., CP15 barriers + +* Hardware Execution + Value: 2 + Although marked as deprecated, some implementations may support the + enabling/disabling of hardware support for the execution of these + instructions. Using hardware execution generally provides better + performance, but at the loss of ability to gather runtime statistics + about the use of the deprecated instructions. + +The default mode depends on the status of the instruction in the +architecture. Deprecated instructions should default to emulation +while obsolete instructions must be undefined by default. + +Note: Instruction emulation may not be possible in all cases. See +individual instruction notes for further information. + +Supported legacy instructions +----------------------------- +* SWP{B} +Node: /proc/sys/abi/swp +Status: Obsolete +Default: Undef (0) + +* CP15 Barriers +Node: /proc/sys/abi/cp15_barrier +Status: Deprecated +Default: Emulate (1) + +* SETEND +Node: /proc/sys/abi/setend +Status: Deprecated +Default: Emulate (1)* +Note: All the cpus on the system must have mixed endian support at EL0 +for this feature to be enabled. If a new CPU - which doesn't support mixed +endian - is hotplugged in after this feature has been enabled, there could +be unexpected results in the application. diff --git a/Documentation/atomic_ops.txt b/Documentation/atomic_ops.txt index 68542fe13b85..183e41bdcb69 100644 --- a/Documentation/atomic_ops.txt +++ b/Documentation/atomic_ops.txt @@ -7,12 +7,13 @@ maintainers on how to implement atomic counter, bitops, and spinlock interfaces properly. - The atomic_t type should be defined as a signed integer. -Also, it should be made opaque such that any kind of cast to a normal -C integer type will fail. Something like the following should -suffice: + The atomic_t type should be defined as a signed integer and +the atomic_long_t type as a signed long integer. Also, they should +be made opaque such that any kind of cast to a normal C integer type +will fail. Something like the following should suffice: typedef struct { int counter; } atomic_t; + typedef struct { long counter; } atomic_long_t; Historically, counter has been declared volatile. This is now discouraged. See Documentation/volatile-considered-harmful.txt for the complete rationale. @@ -37,6 +38,9 @@ initializer is used before runtime. If the initializer is used at runtime, a proper implicit or explicit read memory barrier is needed before reading the value with atomic_read from another thread. +As with all of the atomic_ interfaces, replace the leading "atomic_" +with "atomic_long_" to operate on atomic_long_t. + The second interface can be used at runtime, as in: struct foo { atomic_t counter; }; diff --git a/Documentation/blackfin/Makefile b/Documentation/blackfin/Makefile index c7e6c99bad81..03f78059d6f5 100644 --- a/Documentation/blackfin/Makefile +++ b/Documentation/blackfin/Makefile @@ -1,3 +1,5 @@ ifneq ($(CONFIG_BLACKFIN),) +ifneq ($(CONFIG_BFIN_GPTIMERS,) obj-m := gptimers-example.o endif +endif diff --git a/Documentation/block/biodoc.txt b/Documentation/block/biodoc.txt index 2101e718670d..5aabc08de811 100644 --- a/Documentation/block/biodoc.txt +++ b/Documentation/block/biodoc.txt @@ -827,10 +827,6 @@ but in the event of any barrier requests in the tag queue we need to ensure that requests are restarted in the order they were queue. This may happen if the driver needs to use blk_queue_invalidate_tags(). -Tagging also defines a new request flag, REQ_QUEUED. This is set whenever -a request is currently tagged. You should not use this flag directly, -blk_rq_tagged(rq) is the portable way to do so. - 3.3 I/O Submission The routine submit_bio() is used to submit a single io. Higher level i/o @@ -946,7 +942,11 @@ elevator_allow_merge_fn called whenever the block layer determines request safely. The io scheduler may still want to stop a merge at this point if it results in some sort of conflict internally, - this hook allows it to do that. + this hook allows it to do that. Note however + that two *requests* can still be merged at later + time. Currently the io scheduler has no way to + prevent that. It can only learn about the fact + from elevator_merge_req_fn callback. elevator_dispatch_fn* fills the dispatch queue with ready requests. I/O schedulers are free to postpone requests by diff --git a/Documentation/cachetlb.txt b/Documentation/cachetlb.txt index d79b008e4a32..3f9f808b5119 100644 --- a/Documentation/cachetlb.txt +++ b/Documentation/cachetlb.txt @@ -317,10 +317,10 @@ maps this page at its virtual address. about doing this. The idea is, first at flush_dcache_page() time, if - page->mapping->i_mmap is an empty tree and ->i_mmap_nonlinear - an empty list, just mark the architecture private page flag bit. - Later, in update_mmu_cache(), a check is made of this flag bit, - and if set the flush is done and the flag bit is cleared. + page->mapping->i_mmap is an empty tree, just mark the architecture + private page flag bit. Later, in update_mmu_cache(), a check is + made of this flag bit, and if set the flush is done and the flag + bit is cleared. IMPORTANT NOTE: It is often important, if you defer the flush, that the actual flush occurs on the same CPU diff --git a/Documentation/cgroups/00-INDEX b/Documentation/cgroups/00-INDEX index bc461b6425a7..96ce071a3633 100644 --- a/Documentation/cgroups/00-INDEX +++ b/Documentation/cgroups/00-INDEX @@ -24,3 +24,5 @@ net_prio.txt - Network priority cgroups details and usages. resource_counter.txt - Resource Counter API. +unified-hierarchy.txt + - Description the new/next cgroup interface. diff --git a/Documentation/cgroups/cgroups.txt b/Documentation/cgroups/cgroups.txt index 10c949b293e4..f935fac1e73b 100644 --- a/Documentation/cgroups/cgroups.txt +++ b/Documentation/cgroups/cgroups.txt @@ -312,10 +312,10 @@ the "cpuset" cgroup subsystem, the steps are something like: 2) mkdir /sys/fs/cgroup/cpuset 3) mount -t cgroup -ocpuset cpuset /sys/fs/cgroup/cpuset 4) Create the new cgroup by doing mkdir's and write's (or echo's) in - the /sys/fs/cgroup virtual file system. + the /sys/fs/cgroup/cpuset virtual file system. 5) Start a task that will be the "founding father" of the new job. 6) Attach that task to the new cgroup by writing its PID to the - /sys/fs/cgroup/cpuset/tasks file for that cgroup. + /sys/fs/cgroup/cpuset tasks file for that cgroup. 7) fork, exec or clone the job tasks from this founding father task. For example, the following sequence of commands will setup a cgroup diff --git a/Documentation/cgroups/cpusets.txt b/Documentation/cgroups/cpusets.txt index 3c94ff3f9693..f2235a162529 100644 --- a/Documentation/cgroups/cpusets.txt +++ b/Documentation/cgroups/cpusets.txt @@ -445,7 +445,7 @@ across partially overlapping sets of CPUs would risk unstable dynamics that would be beyond our understanding. So if each of two partially overlapping cpusets enables the flag 'cpuset.sched_load_balance', then we form a single sched domain that is a superset of both. We won't move -a task to a CPU outside it cpuset, but the scheduler load balancing +a task to a CPU outside its cpuset, but the scheduler load balancing code might waste some compute cycles considering that possibility. This mismatch is why there is not a simple one-to-one relation @@ -552,8 +552,8 @@ otherwise initial value -1 that indicates the cpuset has no request. 1 : search siblings (hyperthreads in a core). 2 : search cores in a package. 3 : search cpus in a node [= system wide on non-NUMA system] - ( 4 : search nodes in a chunk of node [on NUMA system] ) - ( 5 : search system wide [on NUMA system] ) + 4 : search nodes in a chunk of node [on NUMA system] + 5 : search system wide [on NUMA system] The system default is architecture dependent. The system default can be changed using the relax_domain_level= boot parameter. diff --git a/Documentation/cgroups/hugetlb.txt b/Documentation/cgroups/hugetlb.txt index a9faaca1f029..106245c3aecc 100644 --- a/Documentation/cgroups/hugetlb.txt +++ b/Documentation/cgroups/hugetlb.txt @@ -29,7 +29,7 @@ Brief summary of control files hugetlb.<hugepagesize>.limit_in_bytes # set/show limit of "hugepagesize" hugetlb usage hugetlb.<hugepagesize>.max_usage_in_bytes # show max "hugepagesize" hugetlb usage recorded - hugetlb.<hugepagesize>.usage_in_bytes # show current res_counter usage for "hugepagesize" hugetlb + hugetlb.<hugepagesize>.usage_in_bytes # show current usage for "hugepagesize" hugetlb hugetlb.<hugepagesize>.failcnt # show the number of allocation failure due to HugeTLB limit For a system supporting two hugepage size (16M and 16G) the control diff --git a/Documentation/cgroups/memory.txt b/Documentation/cgroups/memory.txt index 02ab997a1ed2..a22df3ad35ff 100644 --- a/Documentation/cgroups/memory.txt +++ b/Documentation/cgroups/memory.txt @@ -1,5 +1,10 @@ Memory Resource Controller +NOTE: This document is hopelessly outdated and it asks for a complete + rewrite. It still contains a useful information so we are keeping it + here but make sure to check the current code if you need a deeper + understanding. + NOTE: The Memory Resource Controller has generically been referred to as the memory controller in this document. Do not confuse memory controller used here with the memory controller that is used in hardware. @@ -52,9 +57,9 @@ Brief summary of control files. tasks # attach a task(thread) and show list of threads cgroup.procs # show list of processes cgroup.event_control # an interface for event_fd() - memory.usage_in_bytes # show current res_counter usage for memory + memory.usage_in_bytes # show current usage for memory (See 5.5 for details) - memory.memsw.usage_in_bytes # show current res_counter usage for memory+Swap + memory.memsw.usage_in_bytes # show current usage for memory+Swap (See 5.5 for details) memory.limit_in_bytes # set/show limit of memory usage memory.memsw.limit_in_bytes # set/show limit of memory+Swap usage @@ -116,16 +121,16 @@ The memory controller is the first controller developed. 2.1. Design -The core of the design is a counter called the res_counter. The res_counter -tracks the current memory usage and limit of the group of processes associated -with the controller. Each cgroup has a memory controller specific data -structure (mem_cgroup) associated with it. +The core of the design is a counter called the page_counter. The +page_counter tracks the current memory usage and limit of the group of +processes associated with the controller. Each cgroup has a memory controller +specific data structure (mem_cgroup) associated with it. 2.2. Accounting +--------------------+ - | mem_cgroup | - | (res_counter) | + | mem_cgroup | + | (page_counter) | +--------------------+ / ^ \ / | \ @@ -321,7 +326,7 @@ per cgroup, instead of globally. * tcp memory pressure: sockets memory pressure for the tcp protocol. -2.7.3 Common use cases +2.7.2 Common use cases Because the "kmem" counter is fed to the main user counter, kernel memory can never be limited completely independently of user memory. Say "U" is the user @@ -349,20 +354,19 @@ set: 3. User Interface -0. Configuration +3.0. Configuration a. Enable CONFIG_CGROUPS -b. Enable CONFIG_RESOURCE_COUNTERS -c. Enable CONFIG_MEMCG -d. Enable CONFIG_MEMCG_SWAP (to use swap extension) +b. Enable CONFIG_MEMCG +c. Enable CONFIG_MEMCG_SWAP (to use swap extension) d. Enable CONFIG_MEMCG_KMEM (to use kmem extension) -1. Prepare the cgroups (see cgroups.txt, Why are cgroups needed?) +3.1. Prepare the cgroups (see cgroups.txt, Why are cgroups needed?) # mount -t tmpfs none /sys/fs/cgroup # mkdir /sys/fs/cgroup/memory # mount -t cgroup none /sys/fs/cgroup/memory -o memory -2. Make the new group and move bash into it +3.2. Make the new group and move bash into it # mkdir /sys/fs/cgroup/memory/0 # echo $$ > /sys/fs/cgroup/memory/0/tasks diff --git a/Documentation/cgroups/resource_counter.txt b/Documentation/cgroups/resource_counter.txt deleted file mode 100644 index 762ca54eb929..000000000000 --- a/Documentation/cgroups/resource_counter.txt +++ /dev/null @@ -1,197 +0,0 @@ - - The Resource Counter - -The resource counter, declared at include/linux/res_counter.h, -is supposed to facilitate the resource management by controllers -by providing common stuff for accounting. - -This "stuff" includes the res_counter structure and routines -to work with it. - - - -1. Crucial parts of the res_counter structure - - a. unsigned long long usage - - The usage value shows the amount of a resource that is consumed - by a group at a given time. The units of measurement should be - determined by the controller that uses this counter. E.g. it can - be bytes, items or any other unit the controller operates on. - - b. unsigned long long max_usage - - The maximal value of the usage over time. - - This value is useful when gathering statistical information about - the particular group, as it shows the actual resource requirements - for a particular group, not just some usage snapshot. - - c. unsigned long long limit - - The maximal allowed amount of resource to consume by the group. In - case the group requests for more resources, so that the usage value - would exceed the limit, the resource allocation is rejected (see - the next section). - - d. unsigned long long failcnt - - The failcnt stands for "failures counter". This is the number of - resource allocation attempts that failed. - - c. spinlock_t lock - - Protects changes of the above values. - - - -2. Basic accounting routines - - a. void res_counter_init(struct res_counter *rc, - struct res_counter *rc_parent) - - Initializes the resource counter. As usual, should be the first - routine called for a new counter. - - The struct res_counter *parent can be used to define a hierarchical - child -> parent relationship directly in the res_counter structure, - NULL can be used to define no relationship. - - c. int res_counter_charge(struct res_counter *rc, unsigned long val, - struct res_counter **limit_fail_at) - - When a resource is about to be allocated it has to be accounted - with the appropriate resource counter (controller should determine - which one to use on its own). This operation is called "charging". - - This is not very important which operation - resource allocation - or charging - is performed first, but - * if the allocation is performed first, this may create a - temporary resource over-usage by the time resource counter is - charged; - * if the charging is performed first, then it should be uncharged - on error path (if the one is called). - - If the charging fails and a hierarchical dependency exists, the - limit_fail_at parameter is set to the particular res_counter element - where the charging failed. - - d. u64 res_counter_uncharge(struct res_counter *rc, unsigned long val) - - When a resource is released (freed) it should be de-accounted - from the resource counter it was accounted to. This is called - "uncharging". The return value of this function indicate the amount - of charges still present in the counter. - - The _locked routines imply that the res_counter->lock is taken. - - e. u64 res_counter_uncharge_until - (struct res_counter *rc, struct res_counter *top, - unsigned long val) - - Almost same as res_counter_uncharge() but propagation of uncharge - stops when rc == top. This is useful when kill a res_counter in - child cgroup. - - 2.1 Other accounting routines - - There are more routines that may help you with common needs, like - checking whether the limit is reached or resetting the max_usage - value. They are all declared in include/linux/res_counter.h. - - - -3. Analyzing the resource counter registrations - - a. If the failcnt value constantly grows, this means that the counter's - limit is too tight. Either the group is misbehaving and consumes too - many resources, or the configuration is not suitable for the group - and the limit should be increased. - - b. The max_usage value can be used to quickly tune the group. One may - set the limits to maximal values and either load the container with - a common pattern or leave one for a while. After this the max_usage - value shows the amount of memory the container would require during - its common activity. - - Setting the limit a bit above this value gives a pretty good - configuration that works in most of the cases. - - c. If the max_usage is much less than the limit, but the failcnt value - is growing, then the group tries to allocate a big chunk of resource - at once. - - d. If the max_usage is much less than the limit, but the failcnt value - is 0, then this group is given too high limit, that it does not - require. It is better to lower the limit a bit leaving more resource - for other groups. - - - -4. Communication with the control groups subsystem (cgroups) - -All the resource controllers that are using cgroups and resource counters -should provide files (in the cgroup filesystem) to work with the resource -counter fields. They are recommended to adhere to the following rules: - - a. File names - - Field name File name - --------------------------------------------------- - usage usage_in_<unit_of_measurement> - max_usage max_usage_in_<unit_of_measurement> - limit limit_in_<unit_of_measurement> - failcnt failcnt - lock no file :) - - b. Reading from file should show the corresponding field value in the - appropriate format. - - c. Writing to file - - Field Expected behavior - ---------------------------------- - usage prohibited - max_usage reset to usage - limit set the limit - failcnt reset to zero - - - -5. Usage example - - a. Declare a task group (take a look at cgroups subsystem for this) and - fold a res_counter into it - - struct my_group { - struct res_counter res; - - <other fields> - } - - b. Put hooks in resource allocation/release paths - - int alloc_something(...) - { - if (res_counter_charge(res_counter_ptr, amount) < 0) - return -ENOMEM; - - <allocate the resource and return to the caller> - } - - void release_something(...) - { - res_counter_uncharge(res_counter_ptr, amount); - - <release the resource> - } - - In order to keep the usage value self-consistent, both the - "res_counter_ptr" and the "amount" in release_something() should be - the same as they were in the alloc_something() when the releasing - resource was allocated. - - c. Provide the way to read res_counter values and set them (the cgroups - still can help with it). - - c. Compile and run :) diff --git a/Documentation/cgroups/unified-hierarchy.txt b/Documentation/cgroups/unified-hierarchy.txt index 4f4563277864..71daa35ec2d9 100644 --- a/Documentation/cgroups/unified-hierarchy.txt +++ b/Documentation/cgroups/unified-hierarchy.txt @@ -327,6 +327,85 @@ supported and the interface files "release_agent" and - use_hierarchy is on by default and the cgroup file for the flag is not created. +- The original lower boundary, the soft limit, is defined as a limit + that is per default unset. As a result, the set of cgroups that + global reclaim prefers is opt-in, rather than opt-out. The costs + for optimizing these mostly negative lookups are so high that the + implementation, despite its enormous size, does not even provide the + basic desirable behavior. First off, the soft limit has no + hierarchical meaning. All configured groups are organized in a + global rbtree and treated like equal peers, regardless where they + are located in the hierarchy. This makes subtree delegation + impossible. Second, the soft limit reclaim pass is so aggressive + that it not just introduces high allocation latencies into the + system, but also impacts system performance due to overreclaim, to + the point where the feature becomes self-defeating. + + The memory.low boundary on the other hand is a top-down allocated + reserve. A cgroup enjoys reclaim protection when it and all its + ancestors are below their low boundaries, which makes delegation of + subtrees possible. Secondly, new cgroups have no reserve per + default and in the common case most cgroups are eligible for the + preferred reclaim pass. This allows the new low boundary to be + efficiently implemented with just a minor addition to the generic + reclaim code, without the need for out-of-band data structures and + reclaim passes. Because the generic reclaim code considers all + cgroups except for the ones running low in the preferred first + reclaim pass, overreclaim of individual groups is eliminated as + well, resulting in much better overall workload performance. + +- The original high boundary, the hard limit, is defined as a strict + limit that can not budge, even if the OOM killer has to be called. + But this generally goes against the goal of making the most out of + the available memory. The memory consumption of workloads varies + during runtime, and that requires users to overcommit. But doing + that with a strict upper limit requires either a fairly accurate + prediction of the working set size or adding slack to the limit. + Since working set size estimation is hard and error prone, and + getting it wrong results in OOM kills, most users tend to err on the + side of a looser limit and end up wasting precious resources. + + The memory.high boundary on the other hand can be set much more + conservatively. When hit, it throttles allocations by forcing them + into direct reclaim to work off the excess, but it never invokes the + OOM killer. As a result, a high boundary that is chosen too + aggressively will not terminate the processes, but instead it will + lead to gradual performance degradation. The user can monitor this + and make corrections until the minimal memory footprint that still + gives acceptable performance is found. + + In extreme cases, with many concurrent allocations and a complete + breakdown of reclaim progress within the group, the high boundary + can be exceeded. But even then it's mostly better to satisfy the + allocation from the slack available in other groups or the rest of + the system than killing the group. Otherwise, memory.max is there + to limit this type of spillover and ultimately contain buggy or even + malicious applications. + +- The original control file names are unwieldy and inconsistent in + many different ways. For example, the upper boundary hit count is + exported in the memory.failcnt file, but an OOM event count has to + be manually counted by listening to memory.oom_control events, and + lower boundary / soft limit events have to be counted by first + setting a threshold for that value and then counting those events. + Also, usage and limit files encode their units in the filename. + That makes the filenames very long, even though this is not + information that a user needs to be reminded of every time they type + out those names. + + To address these naming issues, as well as to signal clearly that + the new interface carries a new configuration model, the naming + conventions in it necessarily differ from the old interface. + +- The original limit files indicate the state of an unset limit with a + Very High Number, and a configured limit can be unset by echoing -1 + into those files. But that very high number is implementation and + architecture dependent and not very descriptive. And while -1 can + be understood as an underflow into the highest possible value, -2 or + -10M etc. do not work, so it's not consistent. + + memory.low, memory.high, and memory.max will use the string + "infinity" to indicate and set the highest possible value. 5. Planned Changes diff --git a/Documentation/clk.txt b/Documentation/clk.txt index 1fee72f4d331..4ff84623d5e1 100644 --- a/Documentation/clk.txt +++ b/Documentation/clk.txt @@ -74,7 +74,7 @@ the operations defined in clk.h: long (*determine_rate)(struct clk_hw *hw, unsigned long rate, unsigned long *best_parent_rate, - struct clk **best_parent_clk); + struct clk_hw **best_parent_clk); int (*set_parent)(struct clk_hw *hw, u8 index); u8 (*get_parent)(struct clk_hw *hw); int (*set_rate)(struct clk_hw *hw, diff --git a/Documentation/cpu-freq/intel-pstate.txt b/Documentation/cpu-freq/intel-pstate.txt index a69ffe1d54d5..655750743fb0 100644 --- a/Documentation/cpu-freq/intel-pstate.txt +++ b/Documentation/cpu-freq/intel-pstate.txt @@ -1,17 +1,28 @@ Intel P-state driver -------------------- -This driver implements a scaling driver with an internal governor for -Intel Core processors. The driver follows the same model as the -Transmeta scaling driver (longrun.c) and implements the setpolicy() -instead of target(). Scaling drivers that implement setpolicy() are -assumed to implement internal governors by the cpufreq core. All the -logic for selecting the current P state is contained within the -driver; no external governor is used by the cpufreq core. +This driver provides an interface to control the P state selection for +SandyBridge+ Intel processors. The driver can operate two different +modes based on the processor model legacy and Hardware P state (HWP) +mode. -Intel SandyBridge+ processors are supported. +In legacy mode the driver implements a scaling driver with an internal +governor for Intel Core processors. The driver follows the same model +as the Transmeta scaling driver (longrun.c) and implements the +setpolicy() instead of target(). Scaling drivers that implement +setpolicy() are assumed to implement internal governors by the cpufreq +core. All the logic for selecting the current P state is contained +within the driver; no external governor is used by the cpufreq core. -New sysfs files for controlling P state selection have been added to +In HWP mode P state selection is implemented in the processor +itself. The driver provides the interfaces between the cpufreq core and +the processor to control P state selection based on user preferences +and reporting frequency to the cpufreq core. In this mode the +internal governor code is disabled. + +In addtion to the interfaces provided by the cpufreq core for +controlling frequency the driver provides sysfs files for +controlling P state selection. These files have been added to /sys/devices/system/cpu/intel_pstate/ max_perf_pct: limits the maximum P state that will be requested by @@ -26,6 +37,14 @@ New sysfs files for controlling P state selection have been added to no_turbo: limits the driver to selecting P states below the turbo frequency range. + turbo_pct: displays the percentage of the total performance that + is supported by hardware that is in the turbo range. This number + is independent of whether turbo has been disabled or not. + + num_pstates: displays the number of pstates that are supported + by hardware. This number is independent of whether turbo has + been disabled or not. + For contemporary Intel processors, the frequency is controlled by the processor itself and the P-states exposed to software are related to performance levels. The idea that frequency can be set to a single @@ -33,7 +52,9 @@ frequency is fiction for Intel Core processors. Even if the scaling driver selects a single P state the actual frequency the processor will run at is selected by the processor itself. -New debugfs files have also been added to /sys/kernel/debug/pstate_snb/ +For legacy mode debugfs files have also been added to allow tuning of +the internal governor algorythm. These files are located at +/sys/kernel/debug/pstate_snb/ These files are NOT present in HWP mode. deadband d_gain_pct diff --git a/Documentation/crypto/crypto-API-userspace.txt b/Documentation/crypto/crypto-API-userspace.txt new file mode 100644 index 000000000000..ac619cd90300 --- /dev/null +++ b/Documentation/crypto/crypto-API-userspace.txt @@ -0,0 +1,205 @@ +Introduction +============ + +The concepts of the kernel crypto API visible to kernel space is fully +applicable to the user space interface as well. Therefore, the kernel crypto API +high level discussion for the in-kernel use cases applies here as well. + +The major difference, however, is that user space can only act as a consumer +and never as a provider of a transformation or cipher algorithm. + +The following covers the user space interface exported by the kernel crypto +API. A working example of this description is libkcapi that can be obtained from +[1]. That library can be used by user space applications that require +cryptographic services from the kernel. + +Some details of the in-kernel kernel crypto API aspects do not +apply to user space, however. This includes the difference between synchronous +and asynchronous invocations. The user space API call is fully synchronous. +In addition, only a subset of all cipher types are available as documented +below. + + +User space API general remarks +============================== + +The kernel crypto API is accessible from user space. Currently, the following +ciphers are accessible: + + * Message digest including keyed message digest (HMAC, CMAC) + + * Symmetric ciphers + +Note, AEAD ciphers are currently not supported via the symmetric cipher +interface. + +The interface is provided via Netlink using the type AF_ALG. In addition, the +setsockopt option type is SOL_ALG. In case the user space header files do not +export these flags yet, use the following macros: + +#ifndef AF_ALG +#define AF_ALG 38 +#endif +#ifndef SOL_ALG +#define SOL_ALG 279 +#endif + +A cipher is accessed with the same name as done for the in-kernel API calls. +This includes the generic vs. unique naming schema for ciphers as well as the +enforcement of priorities for generic names. + +To interact with the kernel crypto API, a Netlink socket must be created by +the user space application. User space invokes the cipher operation with the +send/write system call family. The result of the cipher operation is obtained +with the read/recv system call family. + +The following API calls assume that the Netlink socket descriptor is already +opened by the user space application and discusses only the kernel crypto API +specific invocations. + +To initialize a Netlink interface, the following sequence has to be performed +by the consumer: + + 1. Create a socket of type AF_ALG with the struct sockaddr_alg parameter + specified below for the different cipher types. + + 2. Invoke bind with the socket descriptor + + 3. Invoke accept with the socket descriptor. The accept system call + returns a new file descriptor that is to be used to interact with + the particular cipher instance. When invoking send/write or recv/read + system calls to send data to the kernel or obtain data from the + kernel, the file descriptor returned by accept must be used. + +In-place cipher operation +========================= + +Just like the in-kernel operation of the kernel crypto API, the user space +interface allows the cipher operation in-place. That means that the input buffer +used for the send/write system call and the output buffer used by the read/recv +system call may be one and the same. This is of particular interest for +symmetric cipher operations where a copying of the output data to its final +destination can be avoided. + +If a consumer on the other hand wants to maintain the plaintext and the +ciphertext in different memory locations, all a consumer needs to do is to +provide different memory pointers for the encryption and decryption operation. + +Message digest API +================== + +The message digest type to be used for the cipher operation is selected when +invoking the bind syscall. bind requires the caller to provide a filled +struct sockaddr data structure. This data structure must be filled as follows: + +struct sockaddr_alg sa = { + .salg_family = AF_ALG, + .salg_type = "hash", /* this selects the hash logic in the kernel */ + .salg_name = "sha1" /* this is the cipher name */ +}; + +The salg_type value "hash" applies to message digests and keyed message digests. +Though, a keyed message digest is referenced by the appropriate salg_name. +Please see below for the setsockopt interface that explains how the key can be +set for a keyed message digest. + +Using the send() system call, the application provides the data that should be +processed with the message digest. The send system call allows the following +flags to be specified: + + * MSG_MORE: If this flag is set, the send system call acts like a + message digest update function where the final hash is not + yet calculated. If the flag is not set, the send system call + calculates the final message digest immediately. + +With the recv() system call, the application can read the message digest from +the kernel crypto API. If the buffer is too small for the message digest, the +flag MSG_TRUNC is set by the kernel. + +In order to set a message digest key, the calling application must use the +setsockopt() option of ALG_SET_KEY. If the key is not set the HMAC operation is +performed without the initial HMAC state change caused by the key. + + +Symmetric cipher API +==================== + +The operation is very similar to the message digest discussion. During +initialization, the struct sockaddr data structure must be filled as follows: + +struct sockaddr_alg sa = { + .salg_family = AF_ALG, + .salg_type = "skcipher", /* this selects the symmetric cipher */ + .salg_name = "cbc(aes)" /* this is the cipher name */ +}; + +Before data can be sent to the kernel using the write/send system call family, +the consumer must set the key. The key setting is described with the setsockopt +invocation below. + +Using the sendmsg() system call, the application provides the data that should +be processed for encryption or decryption. In addition, the IV is specified +with the data structure provided by the sendmsg() system call. + +The sendmsg system call parameter of struct msghdr is embedded into the +struct cmsghdr data structure. See recv(2) and cmsg(3) for more information +on how the cmsghdr data structure is used together with the send/recv system +call family. That cmsghdr data structure holds the following information +specified with a separate header instances: + + * specification of the cipher operation type with one of these flags: + ALG_OP_ENCRYPT - encryption of data + ALG_OP_DECRYPT - decryption of data + + * specification of the IV information marked with the flag ALG_SET_IV + +The send system call family allows the following flag to be specified: + + * MSG_MORE: If this flag is set, the send system call acts like a + cipher update function where more input data is expected + with a subsequent invocation of the send system call. + +Note: The kernel reports -EINVAL for any unexpected data. The caller must +make sure that all data matches the constraints given in /proc/crypto for the +selected cipher. + +With the recv() system call, the application can read the result of the +cipher operation from the kernel crypto API. The output buffer must be at least +as large as to hold all blocks of the encrypted or decrypted data. If the output +data size is smaller, only as many blocks are returned that fit into that +output buffer size. + +Setsockopt interface +==================== + +In addition to the read/recv and send/write system call handling to send and +retrieve data subject to the cipher operation, a consumer also needs to set +the additional information for the cipher operation. This additional information +is set using the setsockopt system call that must be invoked with the file +descriptor of the open cipher (i.e. the file descriptor returned by the +accept system call). + +Each setsockopt invocation must use the level SOL_ALG. + +The setsockopt interface allows setting the following data using the mentioned +optname: + + * ALG_SET_KEY -- Setting the key. Key setting is applicable to: + + - the skcipher cipher type (symmetric ciphers) + + - the hash cipher type (keyed message digests) + +User space API example +====================== + +Please see [1] for libkcapi which provides an easy-to-use wrapper around the +aforementioned Netlink kernel interface. [1] also contains a test application +that invokes all libkcapi API calls. + +[1] http://www.chronox.de/libkcapi.html + +Author +====== + +Stephan Mueller <smueller@chronox.de> diff --git a/Documentation/device-mapper/cache-policies.txt b/Documentation/device-mapper/cache-policies.txt index 66c2774c0c64..0d124a971801 100644 --- a/Documentation/device-mapper/cache-policies.txt +++ b/Documentation/device-mapper/cache-policies.txt @@ -47,20 +47,26 @@ Message and constructor argument pairs are: 'discard_promote_adjustment <value>' The sequential threshold indicates the number of contiguous I/Os -required before a stream is treated as sequential. The random threshold +required before a stream is treated as sequential. Once a stream is +considered sequential it will bypass the cache. The random threshold is the number of intervening non-contiguous I/Os that must be seen before the stream is treated as random again. The sequential and random thresholds default to 512 and 4 respectively. -Large, sequential ios are probably better left on the origin device -since spindles tend to have good bandwidth. The io_tracker counts -contiguous I/Os to try to spot when the io is in one of these sequential -modes. - -Internally the mq policy maintains a promotion threshold variable. If -the hit count of a block not in the cache goes above this threshold it -gets promoted to the cache. The read, write and discard promote adjustment +Large, sequential I/Os are probably better left on the origin device +since spindles tend to have good sequential I/O bandwidth. The +io_tracker counts contiguous I/Os to try to spot when the I/O is in one +of these sequential modes. But there are use-cases for wanting to +promote sequential blocks to the cache (e.g. fast application startup). +If sequential threshold is set to 0 the sequential I/O detection is +disabled and sequential I/O will no longer implicitly bypass the cache. +Setting the random threshold to 0 does _not_ disable the random I/O +stream detection. + +Internally the mq policy determines a promotion threshold. If the hit +count of a block not in the cache goes above this threshold it gets +promoted to the cache. The read, write and discard promote adjustment tunables allow you to tweak the promotion threshold by adding a small value based on the io type. They default to 4, 8 and 1 respectively. If you're trying to quickly warm a new cache device you may wish to diff --git a/Documentation/devicetree/bindings/arm/amlogic.txt b/Documentation/devicetree/bindings/arm/amlogic.txt index 7eece72b1a35..8fe815046140 100644 --- a/Documentation/devicetree/bindings/arm/amlogic.txt +++ b/Documentation/devicetree/bindings/arm/amlogic.txt @@ -2,7 +2,9 @@ Amlogic MesonX device tree bindings ------------------------------------------- Boards with the Amlogic Meson6 SoC shall have the following properties: + Required root node property: + compatible: "amlogic,meson6" -Required root node property: - -compatible = "amlogic,meson6"; +Boards with the Amlogic Meson8 SoC shall have the following properties: + Required root node property: + compatible: "amlogic,meson8"; diff --git a/Documentation/devicetree/bindings/arm/arch_timer.txt b/Documentation/devicetree/bindings/arm/arch_timer.txt index 37b2cafa4e52..256b4d8bab7b 100644 --- a/Documentation/devicetree/bindings/arm/arch_timer.txt +++ b/Documentation/devicetree/bindings/arm/arch_timer.txt @@ -22,6 +22,14 @@ to deliver its interrupts via SPIs. - always-on : a boolean property. If present, the timer is powered through an always-on power domain, therefore it never loses context. +** Optional properties: + +- arm,cpu-registers-not-fw-configured : Firmware does not initialize + any of the generic timer CPU registers, which contain their + architecturally-defined reset values. Only supported for 32-bit + systems which follow the ARMv7 architected reset values. + + Example: timer { diff --git a/Documentation/devicetree/bindings/arm/arm-boards b/Documentation/devicetree/bindings/arm/arm-boards index c554ed3d44fb..b78564b2b201 100644 --- a/Documentation/devicetree/bindings/arm/arm-boards +++ b/Documentation/devicetree/bindings/arm/arm-boards @@ -23,7 +23,7 @@ Required nodes: range of 0x200 bytes. - syscon: the root node of the Integrator platforms must have a - system controller node pointong to the control registers, + system controller node pointing to the control registers, with the compatible string "arm,integrator-ap-syscon" "arm,integrator-cp-syscon" @@ -92,3 +92,68 @@ Required nodes: - core-module: the root node to the Versatile platforms must have a core-module with regs and the compatible strings "arm,core-module-versatile", "syscon" + +ARM RealView Boards +------------------- +The RealView boards cover tailored evaluation boards that are used to explore +the ARM11 and Cortex A-8 and Cortex A-9 processors. + +Required properties (in root node): + /* RealView Emulation Baseboard */ + compatible = "arm,realview-eb"; + /* RealView Platform Baseboard for ARM1176JZF-S */ + compatible = "arm,realview-pb1176"; + /* RealView Platform Baseboard for ARM11 MPCore */ + compatible = "arm,realview-pb11mp"; + /* RealView Platform Baseboard for Cortex A-8 */ + compatible = "arm,realview-pba8"; + /* RealView Platform Baseboard Explore for Cortex A-9 */ + compatible = "arm,realview-pbx"; + +Required nodes: + +- soc: some node of the RealView platforms must be the SoC + node that contain the SoC-specific devices, withe the compatible + string set to one of these tuples: + "arm,realview-eb-soc", "simple-bus" + "arm,realview-pb1176-soc", "simple-bus" + "arm,realview-pb11mp-soc", "simple-bus" + "arm,realview-pba8-soc", "simple-bus" + "arm,realview-pbx-soc", "simple-bus" + +- syscon: some subnode of the RealView SoC node must be a + system controller node pointing to the control registers, + with the compatible string set to one of these tuples: + "arm,realview-eb-syscon", "syscon" + "arm,realview-pb1176-syscon", "syscon" + "arm,realview-pb11mp-syscon", "syscon" + "arm,realview-pba8-syscon", "syscon" + "arm,realview-pbx-syscon", "syscon" + + Required properties for the system controller: + - regs: the location and size of the system controller registers, + one range of 0x1000 bytes. + +Example: + +/dts-v1/; +#include <dt-bindings/interrupt-controller/irq.h> +#include "skeleton.dtsi" + +/ { + model = "ARM RealView PB1176 with device tree"; + compatible = "arm,realview-pb1176"; + + soc { + #address-cells = <1>; + #size-cells = <1>; + compatible = "arm,realview-pb1176-soc", "simple-bus"; + ranges; + + syscon: syscon@10000000 { + compatible = "arm,realview-syscon", "syscon"; + reg = <0x10000000 0x1000>; + }; + + }; +}; diff --git a/Documentation/devicetree/bindings/arm/armada-38x.txt b/Documentation/devicetree/bindings/arm/armada-38x.txt index ad9f8ed4d9bd..202953f1887e 100644 --- a/Documentation/devicetree/bindings/arm/armada-38x.txt +++ b/Documentation/devicetree/bindings/arm/armada-38x.txt @@ -15,6 +15,13 @@ Required root node property: compatible: must contain "marvell,armada385" +In addition, boards using the Marvell Armada 388 SoC shall have the +following property before the previous one: + +Required root node property: + +compatible: must contain "marvell,armada388" + Example: compatible = "marvell,a385-rd", "marvell,armada385", "marvell,armada380"; diff --git a/Documentation/devicetree/bindings/arm/atmel-at91.txt b/Documentation/devicetree/bindings/arm/atmel-at91.txt index 562cda9d86d9..ad319f84f560 100644 --- a/Documentation/devicetree/bindings/arm/atmel-at91.txt +++ b/Documentation/devicetree/bindings/arm/atmel-at91.txt @@ -24,6 +24,7 @@ compatible: must be one of: o "atmel,at91sam9g45" o "atmel,at91sam9n12" o "atmel,at91sam9rl" + o "atmel,at91sam9xe" * "atmel,sama5" for SoCs using a Cortex-A5, shall be extended with the specific SoC family: o "atmel,sama5d3" shall be extended with the specific SoC compatible: @@ -136,3 +137,19 @@ Example: compatible = "atmel,at91sam9260-rstc"; reg = <0xfffffd00 0x10>; }; + +Special Function Registers (SFR) + +Special Function Registers (SFR) manage specific aspects of the integrated +memory, bridge implementations, processor and other functionality not controlled +elsewhere. + +required properties: +- compatible: Should be "atmel,<chip>-sfr", "syscon". + <chip> can be "sama5d3" or "sama5d4". +- reg: Should contain registers location and length + + sfr@f0038000 { + compatible = "atmel,sama5d3-sfr", "syscon"; + reg = <0xf0038000 0x60>; + }; diff --git a/Documentation/devicetree/bindings/arm/bcm/cygnus.txt b/Documentation/devicetree/bindings/arm/bcm/cygnus.txt new file mode 100644 index 000000000000..4c77169bb534 --- /dev/null +++ b/Documentation/devicetree/bindings/arm/bcm/cygnus.txt @@ -0,0 +1,31 @@ +Broadcom Cygnus device tree bindings +------------------------------------ + + +Boards with Cygnus SoCs shall have the following properties: + +Required root node property: + +BCM11300 +compatible = "brcm,bcm11300", "brcm,cygnus"; + +BCM11320 +compatible = "brcm,bcm11320", "brcm,cygnus"; + +BCM11350 +compatible = "brcm,bcm11350", "brcm,cygnus"; + +BCM11360 +compatible = "brcm,bcm11360", "brcm,cygnus"; + +BCM58300 +compatible = "brcm,bcm58300", "brcm,cygnus"; + +BCM58302 +compatible = "brcm,bcm58302", "brcm,cygnus"; + +BCM58303 +compatible = "brcm,bcm58303", "brcm,cygnus"; + +BCM58305 +compatible = "brcm,bcm58305", "brcm,cygnus"; diff --git a/Documentation/devicetree/bindings/arm/brcm-brcmstb.txt b/Documentation/devicetree/bindings/arm/brcm-brcmstb.txt index 3c436cc4f35d..430608ec09f0 100644 --- a/Documentation/devicetree/bindings/arm/brcm-brcmstb.txt +++ b/Documentation/devicetree/bindings/arm/brcm-brcmstb.txt @@ -79,7 +79,9 @@ reboot Required properties - compatible - The string property "brcm,brcmstb-reboot". + The string property "brcm,brcmstb-reboot" for 40nm/28nm chips with + the new SYS_CTRL interface, or "brcm,bcm7038-reboot" for 65nm + chips with the old SUN_TOP_CTRL interface. - syscon A phandle / integer array that points to the syscon node which describes diff --git a/Documentation/devicetree/bindings/arm/coresight.txt b/Documentation/devicetree/bindings/arm/coresight.txt new file mode 100644 index 000000000000..a3089359aaa6 --- /dev/null +++ b/Documentation/devicetree/bindings/arm/coresight.txt @@ -0,0 +1,200 @@ +* CoreSight Components: + +CoreSight components are compliant with the ARM CoreSight architecture +specification and can be connected in various topologies to suit a particular +SoCs tracing needs. These trace components can generally be classified as +sinks, links and sources. Trace data produced by one or more sources flows +through the intermediate links connecting the source to the currently selected +sink. Each CoreSight component device should use these properties to describe +its hardware characteristcs. + +* Required properties for all components *except* non-configurable replicators: + + * compatible: These have to be supplemented with "arm,primecell" as + drivers are using the AMBA bus interface. Possible values include: + - "arm,coresight-etb10", "arm,primecell"; + - "arm,coresight-tpiu", "arm,primecell"; + - "arm,coresight-tmc", "arm,primecell"; + - "arm,coresight-funnel", "arm,primecell"; + - "arm,coresight-etm3x", "arm,primecell"; + + * reg: physical base address and length of the register + set(s) of the component. + + * clocks: the clock associated to this component. + + * clock-names: the name of the clock as referenced by the code. + Since we are using the AMBA framework, the name should be + "apb_pclk". + + * port or ports: The representation of the component's port + layout using the generic DT graph presentation found in + "bindings/graph.txt". + +* Required properties for devices that don't show up on the AMBA bus, such as + non-configurable replicators: + + * compatible: Currently supported value is (note the absence of the + AMBA markee): + - "arm,coresight-replicator" + + * port or ports: same as above. + +* Optional properties for ETM/PTMs: + + * arm,cp14: must be present if the system accesses ETM/PTM management + registers via co-processor 14. + + * cpu: the cpu phandle this ETM/PTM is affined to. When omitted the + source is considered to belong to CPU0. + +* Optional property for TMC: + + * arm,buffer-size: size of contiguous buffer space for TMC ETR + (embedded trace router) + + +Example: + +1. Sinks + etb@20010000 { + compatible = "arm,coresight-etb10", "arm,primecell"; + reg = <0 0x20010000 0 0x1000>; + + coresight-default-sink; + clocks = <&oscclk6a>; + clock-names = "apb_pclk"; + port { + etb_in_port: endpoint@0 { + slave-mode; + remote-endpoint = <&replicator_out_port0>; + }; + }; + }; + + tpiu@20030000 { + compatible = "arm,coresight-tpiu", "arm,primecell"; + reg = <0 0x20030000 0 0x1000>; + + clocks = <&oscclk6a>; + clock-names = "apb_pclk"; + port { + tpiu_in_port: endpoint@0 { + slave-mode; + remote-endpoint = <&replicator_out_port1>; + }; + }; + }; + +2. Links + replicator { + /* non-configurable replicators don't show up on the + * AMBA bus. As such no need to add "arm,primecell". + */ + compatible = "arm,coresight-replicator"; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + /* replicator output ports */ + port@0 { + reg = <0>; + replicator_out_port0: endpoint { + remote-endpoint = <&etb_in_port>; + }; + }; + + port@1 { + reg = <1>; + replicator_out_port1: endpoint { + remote-endpoint = <&tpiu_in_port>; + }; + }; + + /* replicator input port */ + port@2 { + reg = <0>; + replicator_in_port0: endpoint { + slave-mode; + remote-endpoint = <&funnel_out_port0>; + }; + }; + }; + }; + + funnel@20040000 { + compatible = "arm,coresight-funnel", "arm,primecell"; + reg = <0 0x20040000 0 0x1000>; + + clocks = <&oscclk6a>; + clock-names = "apb_pclk"; + ports { + #address-cells = <1>; + #size-cells = <0>; + + /* funnel output port */ + port@0 { + reg = <0>; + funnel_out_port0: endpoint { + remote-endpoint = + <&replicator_in_port0>; + }; + }; + + /* funnel input ports */ + port@1 { + reg = <0>; + funnel_in_port0: endpoint { + slave-mode; + remote-endpoint = <&ptm0_out_port>; + }; + }; + + port@2 { + reg = <1>; + funnel_in_port1: endpoint { + slave-mode; + remote-endpoint = <&ptm1_out_port>; + }; + }; + + port@3 { + reg = <2>; + funnel_in_port2: endpoint { + slave-mode; + remote-endpoint = <&etm0_out_port>; + }; + }; + + }; + }; + +3. Sources + ptm@2201c000 { + compatible = "arm,coresight-etm3x", "arm,primecell"; + reg = <0 0x2201c000 0 0x1000>; + + cpu = <&cpu0>; + clocks = <&oscclk6a>; + clock-names = "apb_pclk"; + port { + ptm0_out_port: endpoint { + remote-endpoint = <&funnel_in_port0>; + }; + }; + }; + + ptm@2201d000 { + compatible = "arm,coresight-etm3x", "arm,primecell"; + reg = <0 0x2201d000 0 0x1000>; + + cpu = <&cpu1>; + clocks = <&oscclk6a>; + clock-names = "apb_pclk"; + port { + ptm1_out_port: endpoint { + remote-endpoint = <&funnel_in_port1>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/arm/cpus.txt b/Documentation/devicetree/bindings/arm/cpus.txt index fc446347ab6d..8b9e0a95de31 100644 --- a/Documentation/devicetree/bindings/arm/cpus.txt +++ b/Documentation/devicetree/bindings/arm/cpus.txt @@ -175,6 +175,7 @@ nodes to be present and contain the properties described below. "marvell,pj4a" "marvell,pj4b" "marvell,sheeva-v5" + "nvidia,tegra132-denver" "qcom,krait" "qcom,scorpion" - enable-method @@ -227,6 +228,15 @@ nodes to be present and contain the properties described below. # List of phandles to idle state nodes supported by this cpu [3]. + - rockchip,pmu + Usage: optional for systems that have an "enable-method" + property value of "rockchip,rk3066-smp" + While optional, it is the preferred way to get access to + the cpu-core power-domains. + Value type: <phandle> + Definition: Specifies the syscon node controlling the cpu core + power domains. + Example 1 (dual-cluster big.LITTLE system 32-bit): cpus { diff --git a/Documentation/devicetree/bindings/arm/digicolor.txt b/Documentation/devicetree/bindings/arm/digicolor.txt new file mode 100644 index 000000000000..658553f40b23 --- /dev/null +++ b/Documentation/devicetree/bindings/arm/digicolor.txt @@ -0,0 +1,6 @@ +Conexant Digicolor Platforms Device Tree Bindings + +Each device tree must specify which Conexant Digicolor SoC it uses. +Must be the following compatible string: + + cnxt,cx92755 diff --git a/Documentation/devicetree/bindings/arm/exynos/power_domain.txt b/Documentation/devicetree/bindings/arm/exynos/power_domain.txt index abde1ea8a119..f4445e5a2bbb 100644 --- a/Documentation/devicetree/bindings/arm/exynos/power_domain.txt +++ b/Documentation/devicetree/bindings/arm/exynos/power_domain.txt @@ -23,7 +23,7 @@ Optional Properties: devices in this power domain. Maximum of 4 pairs (N = 0 to 3) are supported currently. -Node of a device using power domains must have a samsung,power-domain property +Node of a device using power domains must have a power-domains property defined with a phandle to respective power domain. Example: diff --git a/Documentation/devicetree/bindings/arm/fsl.txt b/Documentation/devicetree/bindings/arm/fsl.txt index e935d7d4ac43..a5462b6b3c30 100644 --- a/Documentation/devicetree/bindings/arm/fsl.txt +++ b/Documentation/devicetree/bindings/arm/fsl.txt @@ -74,3 +74,61 @@ Required root node properties: i.MX6q generic board Required root node properties: - compatible = "fsl,imx6q"; + +Freescale Vybrid Platform Device Tree Bindings +---------------------------------------------- + +For the Vybrid SoC familiy all variants with DDR controller are supported, +which is the VF5xx and VF6xx series. Out of historical reasons, in most +places the kernel uses vf610 to refer to the whole familiy. + +Required root node compatible property (one of them): + - compatible = "fsl,vf500"; + - compatible = "fsl,vf510"; + - compatible = "fsl,vf600"; + - compatible = "fsl,vf610"; + +Freescale LS1021A Platform Device Tree Bindings +------------------------------------------------ + +Required root node compatible properties: + - compatible = "fsl,ls1021a"; + +Freescale LS1021A SoC-specific Device Tree Bindings +------------------------------------------- + +Freescale SCFG + SCFG is the supplemental configuration unit, that provides SoC specific +configuration and status registers for the chip. Such as getting PEX port +status. + Required properties: + - compatible: should be "fsl,ls1021a-scfg" + - reg: should contain base address and length of SCFG memory-mapped registers + +Example: + scfg: scfg@1570000 { + compatible = "fsl,ls1021a-scfg"; + reg = <0x0 0x1570000 0x0 0x10000>; + }; + +Freescale DCFG + DCFG is the device configuration unit, that provides general purpose +configuration and status for the device. Such as setting the secondary +core start address and release the secondary core from holdoff and startup. + Required properties: + - compatible: should be "fsl,ls1021a-dcfg" + - reg : should contain base address and length of DCFG memory-mapped registers + +Example: + dcfg: dcfg@1ee0000 { + compatible = "fsl,ls1021a-dcfg"; + reg = <0x0 0x1ee0000 0x0 0x10000>; + }; + +Freescale LS2085A SoC Device Tree Bindings +------------------------------------------ + +LS2085A ARMv8 based Simulator model +Required root node properties: + - compatible = "fsl,ls2085a-simu", "fsl,ls2085a"; + diff --git a/Documentation/devicetree/bindings/arm/fw-cfg.txt b/Documentation/devicetree/bindings/arm/fw-cfg.txt new file mode 100644 index 000000000000..953fb640d9c4 --- /dev/null +++ b/Documentation/devicetree/bindings/arm/fw-cfg.txt @@ -0,0 +1,72 @@ +* QEMU Firmware Configuration bindings for ARM + +QEMU's arm-softmmu and aarch64-softmmu emulation / virtualization targets +provide the following Firmware Configuration interface on the "virt" machine +type: + +- A write-only, 16-bit wide selector (or control) register, +- a read-write, 64-bit wide data register. + +QEMU exposes the control and data register to ARM guests as memory mapped +registers; their location is communicated to the guest's UEFI firmware in the +DTB that QEMU places at the bottom of the guest's DRAM. + +The guest writes a selector value (a key) to the selector register, and then +can read the corresponding data (produced by QEMU) via the data register. If +the selected entry is writable, the guest can rewrite it through the data +register. + +The selector register takes keys in big endian byte order. + +The data register allows accesses with 8, 16, 32 and 64-bit width (only at +offset 0 of the register). Accesses larger than a byte are interpreted as +arrays, bundled together only for better performance. The bytes constituting +such a word, in increasing address order, correspond to the bytes that would +have been transferred by byte-wide accesses in chronological order. + +The interface allows guest firmware to download various parameters and blobs +that affect how the firmware works and what tables it installs for the guest +OS. For example, boot order of devices, ACPI tables, SMBIOS tables, kernel and +initrd images for direct kernel booting, virtual machine UUID, SMP information, +virtual NUMA topology, and so on. + +The authoritative registry of the valid selector values and their meanings is +the QEMU source code; the structure of the data blobs corresponding to the +individual key values is also defined in the QEMU source code. + +The presence of the registers can be verified by selecting the "signature" blob +with key 0x0000, and reading four bytes from the data register. The returned +signature is "QEMU". + +The outermost protocol (involving the write / read sequences of the control and +data registers) is expected to be versioned, and/or described by feature bits. +The interface revision / feature bitmap can be retrieved with key 0x0001. The +blob to be read from the data register has size 4, and it is to be interpreted +as a uint32_t value in little endian byte order. The current value +(corresponding to the above outer protocol) is zero. + +The guest kernel is not expected to use these registers (although it is +certainly allowed to); the device tree bindings are documented here because +this is where device tree bindings reside in general. + +Required properties: + +- compatible: "qemu,fw-cfg-mmio". + +- reg: the MMIO region used by the device. + * Bytes 0x0 to 0x7 cover the data register. + * Bytes 0x8 to 0x9 cover the selector register. + * Further registers may be appended to the region in case of future interface + revisions / feature bits. + +Example: + +/ { + #size-cells = <0x2>; + #address-cells = <0x2>; + + fw-cfg@9020000 { + compatible = "qemu,fw-cfg-mmio"; + reg = <0x0 0x9020000 0x0 0xa>; + }; +}; diff --git a/Documentation/devicetree/bindings/arm/gic-v3.txt b/Documentation/devicetree/bindings/arm/gic-v3.txt index 33cd05e6c125..ddfade40ac59 100644 --- a/Documentation/devicetree/bindings/arm/gic-v3.txt +++ b/Documentation/devicetree/bindings/arm/gic-v3.txt @@ -49,11 +49,29 @@ Optional occupied by the redistributors. Required if more than one such region is present. +Sub-nodes: + +GICv3 has one or more Interrupt Translation Services (ITS) that are +used to route Message Signalled Interrupts (MSI) to the CPUs. + +These nodes must have the following properties: +- compatible : Should at least contain "arm,gic-v3-its". +- msi-controller : Boolean property. Identifies the node as an MSI controller +- reg: Specifies the base physical address and size of the ITS + registers. + +The main GIC node must contain the appropriate #address-cells, +#size-cells and ranges properties for the reg property of all ITS +nodes. + Examples: gic: interrupt-controller@2cf00000 { compatible = "arm,gic-v3"; #interrupt-cells = <3>; + #address-cells = <2>; + #size-cells = <2>; + ranges; interrupt-controller; reg = <0x0 0x2f000000 0 0x10000>, // GICD <0x0 0x2f100000 0 0x200000>, // GICR @@ -61,11 +79,20 @@ Examples: <0x0 0x2c010000 0 0x2000>, // GICH <0x0 0x2c020000 0 0x2000>; // GICV interrupts = <1 9 4>; + + gic-its@2c200000 { + compatible = "arm,gic-v3-its"; + msi-controller; + reg = <0x0 0x2c200000 0 0x200000>; + }; }; gic: interrupt-controller@2c010000 { compatible = "arm,gic-v3"; #interrupt-cells = <3>; + #address-cells = <2>; + #size-cells = <2>; + ranges; interrupt-controller; redistributor-stride = <0x0 0x40000>; // 256kB stride #redistributor-regions = <2>; @@ -76,4 +103,16 @@ Examples: <0x0 0x2c060000 0 0x2000>, // GICH <0x0 0x2c080000 0 0x2000>; // GICV interrupts = <1 9 4>; + + gic-its@2c200000 { + compatible = "arm,gic-v3-its"; + msi-controller; + reg = <0x0 0x2c200000 0 0x200000>; + }; + + gic-its@2c400000 { + compatible = "arm,gic-v3-its"; + msi-controller; + reg = <0x0 0x2c400000 0 0x200000>; + }; }; diff --git a/Documentation/devicetree/bindings/arm/gic.txt b/Documentation/devicetree/bindings/arm/gic.txt index c7d2fa156678..c97484b73e72 100644 --- a/Documentation/devicetree/bindings/arm/gic.txt +++ b/Documentation/devicetree/bindings/arm/gic.txt @@ -17,6 +17,7 @@ Main node required properties: "arm,cortex-a7-gic" "arm,arm11mp-gic" "brcm,brahma-b15-gic" + "arm,arm1176jzf-devchip-gic" - interrupt-controller : Identifies the node as an interrupt controller - #interrupt-cells : Specifies the number of cells needed to encode an interrupt source. The type shall be a <u32> and the value shall be 3. @@ -31,12 +32,16 @@ Main node required properties: The 3rd cell is the flags, encoded as follows: bits[3:0] trigger type and level flags. 1 = low-to-high edge triggered - 2 = high-to-low edge triggered + 2 = high-to-low edge triggered (invalid for SPIs) 4 = active high level-sensitive - 8 = active low level-sensitive + 8 = active low level-sensitive (invalid for SPIs). bits[15:8] PPI interrupt cpu mask. Each bit corresponds to each of the 8 possible cpus attached to the GIC. A bit set to '1' indicated the interrupt is wired to that CPU. Only valid for PPI interrupts. + Also note that the configurability of PPI interrupts is IMPLEMENTATION + DEFINED and as such not guaranteed to be present (most SoC available + in 2014 seem to ignore the setting of this flag and use the hardware + default value). - reg : Specifies base physical address(s) and size of the GIC registers. The first region is the GIC distributor register base and size. The 2nd region is @@ -96,3 +101,56 @@ Example: <0x2c006000 0x2000>; interrupts = <1 9 0xf04>; }; + + +* GICv2m extension for MSI/MSI-x support (Optional) + +Certain revisions of GIC-400 supports MSI/MSI-x via V2M register frame(s). +This is enabled by specifying v2m sub-node(s). + +Required properties: + +- compatible : The value here should contain "arm,gic-v2m-frame". + +- msi-controller : Identifies the node as an MSI controller. + +- reg : GICv2m MSI interface register base and size + +Optional properties: + +- arm,msi-base-spi : When the MSI_TYPER register contains an incorrect + value, this property should contain the SPI base of + the MSI frame, overriding the HW value. + +- arm,msi-num-spis : When the MSI_TYPER register contains an incorrect + value, this property should contain the number of + SPIs assigned to the frame, overriding the HW value. + +Example: + + interrupt-controller@e1101000 { + compatible = "arm,gic-400"; + #interrupt-cells = <3>; + #address-cells = <2>; + #size-cells = <2>; + interrupt-controller; + interrupts = <1 8 0xf04>; + ranges = <0 0 0 0xe1100000 0 0x100000>; + reg = <0x0 0xe1110000 0 0x01000>, + <0x0 0xe112f000 0 0x02000>, + <0x0 0xe1140000 0 0x10000>, + <0x0 0xe1160000 0 0x10000>; + v2m0: v2m@0x8000 { + compatible = "arm,gic-v2m-frame"; + msi-controller; + reg = <0x0 0x80000 0 0x1000>; + }; + + .... + + v2mN: v2m@0x9000 { + compatible = "arm,gic-v2m-frame"; + msi-controller; + reg = <0x0 0x90000 0 0x1000>; + }; + }; diff --git a/Documentation/devicetree/bindings/arm/hisilicon/hisilicon.txt b/Documentation/devicetree/bindings/arm/hisilicon/hisilicon.txt index f717c7b48603..35b1bd49cfa1 100644 --- a/Documentation/devicetree/bindings/arm/hisilicon/hisilicon.txt +++ b/Documentation/devicetree/bindings/arm/hisilicon/hisilicon.txt @@ -9,6 +9,10 @@ HiP04 D01 Board Required root node properties: - compatible = "hisilicon,hip04-d01"; +HiP01 ca9x2 Board +Required root node properties: + - compatible = "hisilicon,hip01-ca9x2"; + Hisilicon system controller @@ -37,6 +41,27 @@ Example: }; ----------------------------------------------------------------------- +Hisilicon HiP01 system controller + +Required properties: +- compatible : "hisilicon,hip01-sysctrl" +- reg : Register address and size + +The HiP01 system controller is mostly compatible with hisilicon +system controller,but it has some specific control registers for +HIP01 SoC family, such as slave core boot, and also some same +registers located at different offset. + +Example: + + /* for hip01-ca9x2 */ + sysctrl: system-controller@10000000 { + compatible = "hisilicon,hip01-sysctrl", "hisilicon,sysctrl"; + reg = <0x10000000 0x1000>; + reboot-offset = <0x4>; + }; + +----------------------------------------------------------------------- Hisilicon CPU controller Required properties: diff --git a/Documentation/devicetree/bindings/arm/idle-states.txt b/Documentation/devicetree/bindings/arm/idle-states.txt index 37375c7f3ccc..a8274eabae2e 100644 --- a/Documentation/devicetree/bindings/arm/idle-states.txt +++ b/Documentation/devicetree/bindings/arm/idle-states.txt @@ -317,6 +317,26 @@ follows: In such systems entry-latency-us + exit-latency-us will exceed wakeup-latency-us by this duration. + - status: + Usage: Optional + Value type: <string> + Definition: A standard device tree property [5] that indicates + the operational status of an idle-state. + If present, it shall be: + "okay": to indicate that the idle state is + operational. + "disabled": to indicate that the idle state has + been disabled in firmware so it is not + operational. + If the property is not present the idle-state must + be considered operational. + + - idle-state-name: + Usage: Optional + Value type: <string> + Definition: A string used as a descriptive name for the idle + state. + In addition to the properties listed above, a state node may require additional properties specifics to the entry-method defined in the idle-states node, please refer to the entry-method bindings diff --git a/Documentation/devicetree/bindings/arm/l2cc.txt b/Documentation/devicetree/bindings/arm/l2cc.txt index 292ef7ca3058..0dbabe9a6b0a 100644 --- a/Documentation/devicetree/bindings/arm/l2cc.txt +++ b/Documentation/devicetree/bindings/arm/l2cc.txt @@ -57,6 +57,16 @@ Optional properties: - cache-id-part: cache id part number to be used if it is not present on hardware - wt-override: If present then L2 is forced to Write through mode +- arm,double-linefill : Override double linefill enable setting. Enable if + non-zero, disable if zero. +- arm,double-linefill-incr : Override double linefill on INCR read. Enable + if non-zero, disable if zero. +- arm,double-linefill-wrap : Override double linefill on WRAP read. Enable + if non-zero, disable if zero. +- arm,prefetch-drop : Override prefetch drop enable setting. Enable if non-zero, + disable if zero. +- arm,prefetch-offset : Override prefetch offset value. Valid values are + 0-7, 15, 23, and 31. Example: diff --git a/Documentation/devicetree/bindings/arm/marvell,berlin.txt b/Documentation/devicetree/bindings/arm/marvell,berlin.txt index 904de5781f44..a99eb9eb14c0 100644 --- a/Documentation/devicetree/bindings/arm/marvell,berlin.txt +++ b/Documentation/devicetree/bindings/arm/marvell,berlin.txt @@ -106,11 +106,21 @@ Required subnode-properties: - groups: a list of strings describing the group names. - function: a string describing the function used to mux the groups. +* Reset controller binding + +A reset controller is part of the chip control registers set. The chip control +node also provides the reset. The register set is not at the same offset between +Berlin SoCs. + +Required property: +- #reset-cells: must be set to 2 + Example: chip: chip-control@ea0000 { compatible = "marvell,berlin2-chip-ctrl"; #clock-cells = <1>; + #reset-cells = <2>; reg = <0xea0000 0x400>; clocks = <&refclk>, <&externaldev 0>; clock-names = "refclk", "video_ext0"; diff --git a/Documentation/devicetree/bindings/arm/mediatek.txt b/Documentation/devicetree/bindings/arm/mediatek.txt index fa252261dfaf..dd7550a29db6 100644 --- a/Documentation/devicetree/bindings/arm/mediatek.txt +++ b/Documentation/devicetree/bindings/arm/mediatek.txt @@ -1,10 +1,15 @@ -Mediatek MT6589 Platforms Device Tree Bindings +MediaTek mt65xx & mt81xx Platforms Device Tree Bindings -Boards with a SoC of the Mediatek MT6589 shall have the following property: +Boards with a MediaTek mt65xx/mt81xx SoC shall have the following property: Required root node property: -compatible: must contain "mediatek,mt6589" +compatible: Must contain one of + "mediatek,mt6589" + "mediatek,mt6592" + "mediatek,mt8127" + "mediatek,mt8135" + "mediatek,mt8173" Supported boards: @@ -12,3 +17,15 @@ Supported boards: - bq Aquaris5 smart phone: Required root node properties: - compatible = "mundoreader,bq-aquaris5", "mediatek,mt6589"; +- Evaluation board for MT6592: + Required root node properties: + - compatible = "mediatek,mt6592-evb", "mediatek,mt6592"; +- MTK mt8127 tablet moose EVB: + Required root node properties: + - compatible = "mediatek,mt8127-moose", "mediatek,mt8127"; +- MTK mt8135 tablet EVB: + Required root node properties: + - compatible = "mediatek,mt8135-evbp1", "mediatek,mt8135"; +- MTK mt8173 tablet EVB: + Required root node properties: + - compatible = "mediatek,mt8173-evb", "mediatek,mt8173"; diff --git a/Documentation/devicetree/bindings/arm/mediatek/mediatek,sysirq.txt b/Documentation/devicetree/bindings/arm/mediatek/mediatek,sysirq.txt new file mode 100644 index 000000000000..4f5a5352ccd8 --- /dev/null +++ b/Documentation/devicetree/bindings/arm/mediatek/mediatek,sysirq.txt @@ -0,0 +1,30 @@ +Mediatek 65xx/81xx sysirq + +Mediatek SOCs sysirq support controllable irq inverter for each GIC SPI +interrupt. + +Required properties: +- compatible: should be one of: + "mediatek,mt8173-sysirq" + "mediatek,mt8135-sysirq" + "mediatek,mt8127-sysirq" + "mediatek,mt6592-sysirq" + "mediatek,mt6589-sysirq" + "mediatek,mt6582-sysirq" + "mediatek,mt6577-sysirq" +- interrupt-controller : Identifies the node as an interrupt controller +- #interrupt-cells : Use the same format as specified by GIC in + Documentation/devicetree/bindings/arm/gic.txt +- interrupt-parent: phandle of irq parent for sysirq. The parent must + use the same interrupt-cells format as GIC. +- reg: Physical base address of the intpol registers and length of memory + mapped region. + +Example: + sysirq: interrupt-controller@10200100 { + compatible = "mediatek,mt6589-sysirq", "mediatek,mt6577-sysirq"; + interrupt-controller; + #interrupt-cells = <3>; + interrupt-parent = <&gic>; + reg = <0 0x10200100 0 0x1c>; + }; diff --git a/Documentation/devicetree/bindings/arm/msm/timer.txt b/Documentation/devicetree/bindings/arm/msm/timer.txt index c6ef8f13dc7e..74607b6c1117 100644 --- a/Documentation/devicetree/bindings/arm/msm/timer.txt +++ b/Documentation/devicetree/bindings/arm/msm/timer.txt @@ -8,7 +8,7 @@ Properties: "qcom,kpss-timer" - krait subsystem "qcom,scss-timer" - scorpion subsystem -- interrupts : Interrupts for the the debug timer, the first general purpose +- interrupts : Interrupts for the debug timer, the first general purpose timer, and optionally a second general purpose timer in that order. diff --git a/Documentation/devicetree/bindings/arm/omap/omap.txt b/Documentation/devicetree/bindings/arm/omap/omap.txt index ddd9bcdf889c..4f6a82cef1d1 100644 --- a/Documentation/devicetree/bindings/arm/omap/omap.txt +++ b/Documentation/devicetree/bindings/arm/omap/omap.txt @@ -132,6 +132,9 @@ Boards: - AM335X Bone : Low cost community board compatible = "ti,am335x-bone", "ti,am33xx", "ti,omap3" +- AM335X OrionLXm : Substation Automation Platform + compatible = "novatech,am335x-lxm", "ti,am33xx" + - OMAP5 EVM : Evaluation Module compatible = "ti,omap5-evm", "ti,omap5" diff --git a/Documentation/devicetree/bindings/arm/rockchip.txt b/Documentation/devicetree/bindings/arm/rockchip.txt index 857f12636eb2..6809e4e51ed2 100644 --- a/Documentation/devicetree/bindings/arm/rockchip.txt +++ b/Documentation/devicetree/bindings/arm/rockchip.txt @@ -1,10 +1,24 @@ Rockchip platforms device tree bindings --------------------------------------- +- MarsBoard RK3066 board: + Required root node properties: + - compatible = "haoyu,marsboard-rk3066", "rockchip,rk3066a"; + - bq Curie 2 tablet: Required root node properties: - compatible = "mundoreader,bq-curie2", "rockchip,rk3066a"; +- ChipSPARK Rayeager PX2 board: + Required root node properties: + - compatible = "chipspark,rayeager-px2", "rockchip,rk3066a"; + - Radxa Rock board: Required root node properties: - compatible = "radxa,rock", "rockchip,rk3188"; + +- Firefly Firefly-RK3288 board: + Required root node properties: + - compatible = "firefly,firefly-rk3288", "rockchip,rk3288"; + or + - compatible = "firefly,firefly-rk3288-beta", "rockchip,rk3288"; diff --git a/Documentation/devicetree/bindings/arm/rockchip/pmu-sram.txt b/Documentation/devicetree/bindings/arm/rockchip/pmu-sram.txt new file mode 100644 index 000000000000..6b42fda306ff --- /dev/null +++ b/Documentation/devicetree/bindings/arm/rockchip/pmu-sram.txt @@ -0,0 +1,16 @@ +Rockchip SRAM for pmu: +------------------------------ + +The sram of pmu is used to store the function of resume from maskrom(the 1st +level loader). This is a common use of the "pmu-sram" because it keeps power +even in low power states in the system. + +Required node properties: +- compatible : should be "rockchip,rk3288-pmu-sram" +- reg : physical base address and the size of the registers window + +Example: + sram@ff720000 { + compatible = "rockchip,rk3288-pmu-sram", "mmio-sram"; + reg = <0xff720000 0x1000>; + }; diff --git a/Documentation/devicetree/bindings/arm/samsung-boards.txt b/Documentation/devicetree/bindings/arm/samsung-boards.txt index 2168ed31e1b0..43589d2466a7 100644 --- a/Documentation/devicetree/bindings/arm/samsung-boards.txt +++ b/Documentation/devicetree/bindings/arm/samsung-boards.txt @@ -1,11 +1,20 @@ -* Samsung's Exynos4210 based SMDKV310 evaluation board - -SMDKV310 evaluation board is based on Samsung's Exynos4210 SoC. +* Samsung's Exynos SoC based boards Required root node properties: - compatible = should be one or more of the following. - (a) "samsung,smdkv310" - for Samsung's SMDKV310 eval board. - (b) "samsung,exynos4210" - for boards based on Exynos4210 SoC. + - "samsung,monk" - for Exynos3250-based Samsung Simband board. + - "samsung,rinato" - for Exynos3250-based Samsung Gear2 board. + - "samsung,smdkv310" - for Exynos4210-based Samsung SMDKV310 eval board. + - "samsung,trats" - for Exynos4210-based Tizen Reference board. + - "samsung,universal_c210" - for Exynos4210-based Samsung board. + - "samsung,smdk4412", - for Exynos4412-based Samsung SMDK4412 eval board. + - "samsung,trats2" - for Exynos4412-based Tizen Reference board. + - "samsung,smdk5250" - for Exynos5250-based Samsung SMDK5250 eval board. + - "samsung,xyref5260" - for Exynos5260-based Samsung board. + - "samsung,smdk5410" - for Exynos5410-based Samsung SMDK5410 eval board. + - "samsung,smdk5420" - for Exynos5420-based Samsung SMDK5420 eval board. + - "samsung,sd5v1" - for Exynos5440-based Samsung board. + - "samsung,ssdk5440" - for Exynos5440-based Samsung board. Optional: - firmware node, specifying presence and type of secure firmware: diff --git a/Documentation/devicetree/bindings/arm/samsung/exynos-adc.txt b/Documentation/devicetree/bindings/arm/samsung/exynos-adc.txt index 709efaa30841..f46ca9a316a2 100644 --- a/Documentation/devicetree/bindings/arm/samsung/exynos-adc.txt +++ b/Documentation/devicetree/bindings/arm/samsung/exynos-adc.txt @@ -16,6 +16,8 @@ Required properties: future controllers. Must be "samsung,exynos3250-adc" for controllers compatible with ADC of Exynos3250. + Must be "samsung,exynos7-adc" for + the ADC in Exynos7 and compatibles Must be "samsung,s3c2410-adc" for the ADC in s3c2410 and compatibles Must be "samsung,s3c2416-adc" for @@ -43,13 +45,16 @@ Required properties: compatible ADC block) - vdd-supply VDD input supply. +- samsung,syscon-phandle Contains the PMU system controller node + (To access the ADC_PHY register on Exynos5250/5420/5800/3250) + Note: child nodes can be added for auto probing from device tree. Example: adding device info in dtsi file adc: adc@12D10000 { compatible = "samsung,exynos-adc-v1"; - reg = <0x12D10000 0x100>, <0x10040718 0x4>; + reg = <0x12D10000 0x100>; interrupts = <0 106 0>; #io-channel-cells = <1>; io-channel-ranges; @@ -58,13 +63,14 @@ adc: adc@12D10000 { clock-names = "adc"; vdd-supply = <&buck5_reg>; + samsung,syscon-phandle = <&pmu_system_controller>; }; Example: adding device info in dtsi file for Exynos3250 with additional sclk adc: adc@126C0000 { compatible = "samsung,exynos3250-adc", "samsung,exynos-adc-v2; - reg = <0x126C0000 0x100>, <0x10020718 0x4>; + reg = <0x126C0000 0x100>; interrupts = <0 137 0>; #io-channel-cells = <1>; io-channel-ranges; @@ -73,6 +79,7 @@ adc: adc@126C0000 { clock-names = "adc", "sclk"; vdd-supply = <&buck5_reg>; + samsung,syscon-phandle = <&pmu_system_controller>; }; Example: Adding child nodes in dts file diff --git a/Documentation/devicetree/bindings/arm/samsung/exynos-chipid.txt b/Documentation/devicetree/bindings/arm/samsung/exynos-chipid.txt new file mode 100644 index 000000000000..85c5dfd4a720 --- /dev/null +++ b/Documentation/devicetree/bindings/arm/samsung/exynos-chipid.txt @@ -0,0 +1,12 @@ +SAMSUNG Exynos SoCs Chipid driver. + +Required properties: +- compatible : Should at least contain "samsung,exynos4210-chipid". + +- reg: offset and length of the register set + +Example: + chipid@10000000 { + compatible = "samsung,exynos4210-chipid"; + reg = <0x10000000 0x100>; + }; diff --git a/Documentation/devicetree/bindings/arm/samsung/pmu.txt b/Documentation/devicetree/bindings/arm/samsung/pmu.txt index 1e1979b229ff..67b211381f2b 100644 --- a/Documentation/devicetree/bindings/arm/samsung/pmu.txt +++ b/Documentation/devicetree/bindings/arm/samsung/pmu.txt @@ -10,6 +10,7 @@ Properties: - "samsung,exynos5260-pmu" - for Exynos5260 SoC. - "samsung,exynos5410-pmu" - for Exynos5410 SoC, - "samsung,exynos5420-pmu" - for Exynos5420 SoC. + - "samsung,exynos7-pmu" - for Exynos7 SoC. second value must be always "syscon". - reg : offset and length of the register set. diff --git a/Documentation/devicetree/bindings/arm/sirf.txt b/Documentation/devicetree/bindings/arm/sirf.txt index c6ba6d3c747f..7b28ee6fee91 100644 --- a/Documentation/devicetree/bindings/arm/sirf.txt +++ b/Documentation/devicetree/bindings/arm/sirf.txt @@ -3,7 +3,9 @@ CSR SiRFprimaII and SiRFmarco device tree bindings. Required root node properties: - compatible: + - "sirf,atlas6-cb" : atlas6 "cb" evaluation board + - "sirf,atlas6" : atlas6 device based board + - "sirf,atlas7-cb" : atlas7 "cb" evaluation board + - "sirf,atlas7" : atlas7 device based board - "sirf,prima2-cb" : prima2 "cb" evaluation board - - "sirf,marco-cb" : marco "cb" evaluation board - "sirf,prima2" : prima2 device based board - - "sirf,marco" : marco device based board diff --git a/Documentation/devicetree/bindings/arm/sprd.txt b/Documentation/devicetree/bindings/arm/sprd.txt new file mode 100644 index 000000000000..31a629dc75b8 --- /dev/null +++ b/Documentation/devicetree/bindings/arm/sprd.txt @@ -0,0 +1,11 @@ +Spreadtrum SoC Platforms Device Tree Bindings +---------------------------------------------------- + +Sharkl64 is a Spreadtrum's SoC Platform which is based +on ARM 64-bit processor. + +SC9836 openphone board with SC9836 SoC based on the +Sharkl64 Platform shall have the following properties. + +Required root node properties: + - compatible = "sprd,sc9836-openphone", "sprd,sc9836"; diff --git a/Documentation/devicetree/bindings/arm/ste-nomadik.txt b/Documentation/devicetree/bindings/arm/ste-nomadik.txt index 6256ec31666d..2fdff5a806cf 100644 --- a/Documentation/devicetree/bindings/arm/ste-nomadik.txt +++ b/Documentation/devicetree/bindings/arm/ste-nomadik.txt @@ -10,6 +10,12 @@ Required root node property: src Boards with the Nomadik SoC include: +Nomadik NHK-15 board manufactured by ST Microelectronics: + +Required root node property: + +compatible="st,nomadik-nhk-15"; + S8815 "MiniKit" manufactured by Calao Systems: Required root node property: diff --git a/Documentation/devicetree/bindings/arm/sti.txt b/Documentation/devicetree/bindings/arm/sti.txt index 92f16c78bb69..d70ec358736c 100644 --- a/Documentation/devicetree/bindings/arm/sti.txt +++ b/Documentation/devicetree/bindings/arm/sti.txt @@ -13,3 +13,7 @@ Boards with the ST STiH407 SoC shall have the following properties: Required root node property: compatible = "st,stih407"; +Boards with the ST STiH418 SoC shall have the following properties: +Required root node property: +compatible = "st,stih418"; + diff --git a/Documentation/devicetree/bindings/arm/sunxi.txt b/Documentation/devicetree/bindings/arm/sunxi.txt new file mode 100644 index 000000000000..42941fdefb11 --- /dev/null +++ b/Documentation/devicetree/bindings/arm/sunxi.txt @@ -0,0 +1,12 @@ +Allwinner sunXi Platforms Device Tree Bindings + +Each device tree must specify which Allwinner SoC it uses, +using one of the following compatible strings: + + allwinner,sun4i-a10 + allwinner,sun5i-a10s + allwinner,sun5i-a13 + allwinner,sun6i-a31 + allwinner,sun7i-a20 + allwinner,sun8i-a23 + allwinner,sun9i-a80 diff --git a/Documentation/devicetree/bindings/arm/tegra/nvidia,tegra20-ahb.txt b/Documentation/devicetree/bindings/arm/tegra/nvidia,tegra20-ahb.txt index 234406d41c12..067c9790062f 100644 --- a/Documentation/devicetree/bindings/arm/tegra/nvidia,tegra20-ahb.txt +++ b/Documentation/devicetree/bindings/arm/tegra/nvidia,tegra20-ahb.txt @@ -1,7 +1,10 @@ NVIDIA Tegra AHB Required properties: -- compatible : "nvidia,tegra20-ahb" or "nvidia,tegra30-ahb" +- compatible : For Tegra20, must contain "nvidia,tegra20-ahb". For + Tegra30, must contain "nvidia,tegra30-ahb". Otherwise, must contain + '"nvidia,<chip>-ahb", "nvidia,tegra30-ahb"' where <chip> is tegra124, + tegra132, or tegra210. - reg : Should contain 1 register ranges(address and length) Example: diff --git a/Documentation/devicetree/bindings/arm/tegra/nvidia,tegra20-pmc.txt b/Documentation/devicetree/bindings/arm/tegra/nvidia,tegra20-pmc.txt index 68ac65f82a1c..02c27004d4a8 100644 --- a/Documentation/devicetree/bindings/arm/tegra/nvidia,tegra20-pmc.txt +++ b/Documentation/devicetree/bindings/arm/tegra/nvidia,tegra20-pmc.txt @@ -6,7 +6,11 @@ modes. It provides power-gating controllers for SoC and CPU power-islands. Required properties: - name : Should be pmc -- compatible : Should contain "nvidia,tegra<chip>-pmc". +- compatible : For Tegra20, must contain "nvidia,tegra20-pmc". For Tegra30, + must contain "nvidia,tegra30-pmc". For Tegra114, must contain + "nvidia,tegra114-pmc". For Tegra124, must contain "nvidia,tegra124-pmc". + Otherwise, must contain "nvidia,<chip>-pmc", plus at least one of the + above, where <chip> is tegra132. - reg : Offset and length of the register set for the device - clocks : Must contain an entry for each entry in clock-names. See ../clocks/clock-bindings.txt for details. @@ -47,6 +51,23 @@ Required properties when nvidia,suspend-mode=<0>: sleep mode, the warm boot code will restore some PLLs, clocks and then bring up CPU0 for resuming the system. +Hardware-triggered thermal reset: +On Tegra30, Tegra114 and Tegra124, if the 'i2c-thermtrip' subnode exists, +hardware-triggered thermal reset will be enabled. + +Required properties for hardware-triggered thermal reset (inside 'i2c-thermtrip'): +- nvidia,i2c-controller-id : ID of I2C controller to send poweroff command to. Valid values are + described in section 9.2.148 "APBDEV_PMC_SCRATCH53_0" of the + Tegra K1 Technical Reference Manual. +- nvidia,bus-addr : Bus address of the PMU on the I2C bus +- nvidia,reg-addr : I2C register address to write poweroff command to +- nvidia,reg-data : Poweroff command to write to PMU + +Optional properties for hardware-triggered thermal reset (inside 'i2c-thermtrip'): +- nvidia,pinmux-id : Pinmux used by the hardware when issuing poweroff command. + Defaults to 0. Valid values are described in section 12.5.2 + "Pinmux Support" of the Tegra4 Technical Reference Manual. + Example: / SoC dts including file @@ -69,6 +90,15 @@ pmc@7000f400 { / Tegra board dts file { ... + pmc@7000f400 { + i2c-thermtrip { + nvidia,i2c-controller-id = <4>; + nvidia,bus-addr = <0x40>; + nvidia,reg-addr = <0x36>; + nvidia,reg-data = <0x2>; + }; + }; + ... clocks { compatible = "simple-bus"; #address-cells = <1>; diff --git a/Documentation/devicetree/bindings/arm/ux500/power_domain.txt b/Documentation/devicetree/bindings/arm/ux500/power_domain.txt new file mode 100644 index 000000000000..5679d1742d3e --- /dev/null +++ b/Documentation/devicetree/bindings/arm/ux500/power_domain.txt @@ -0,0 +1,35 @@ +* ST-Ericsson UX500 PM Domains + +UX500 supports multiple PM domains which are used to gate power to one or +more peripherals on the SOC. + +The implementation of PM domains for UX500 are based upon the generic PM domain +and use the corresponding DT bindings. + +==PM domain providers== + +Required properties: + - compatible: Must be "stericsson,ux500-pm-domains". + - #power-domain-cells : Number of cells in a power domain specifier, must be 1. + +Example: + pm_domains: pm_domains0 { + compatible = "stericsson,ux500-pm-domains"; + #power-domain-cells = <1>; + }; + +==PM domain consumers== + +Required properties: + - power-domains: A phandle and PM domain specifier. Below are the list of + valid specifiers: + + Index Specifier + ----- --------- + 0 DOMAIN_VAPE + +Example: + sdi0_per1@80126000 { + compatible = "arm,pl18x", "arm,primecell"; + power-domains = <&pm_domains DOMAIN_VAPE> + }; diff --git a/Documentation/devicetree/bindings/arm/versatile-sysreg.txt b/Documentation/devicetree/bindings/arm/versatile-sysreg.txt new file mode 100644 index 000000000000..a4f15262d717 --- /dev/null +++ b/Documentation/devicetree/bindings/arm/versatile-sysreg.txt @@ -0,0 +1,10 @@ +ARM Versatile system registers +-------------------------------------- + +This is a system control registers block, providing multiple low level +platform functions like board detection and identification, software +interrupt generation, MMC and NOR Flash control etc. + +Required node properties: +- compatible value : = "arm,versatile-sysreg", "syscon" +- reg : physical base address and the size of the registers window diff --git a/Documentation/devicetree/bindings/ata/ahci-platform.txt b/Documentation/devicetree/bindings/ata/ahci-platform.txt index 4ab09f2202d4..c2340eeeb97f 100644 --- a/Documentation/devicetree/bindings/ata/ahci-platform.txt +++ b/Documentation/devicetree/bindings/ata/ahci-platform.txt @@ -37,9 +37,10 @@ Required properties when using sub-nodes: Sub-nodes required properties: -- reg : the port number -- phys : reference to the SATA PHY node - +- reg : the port number +And at least one of the following properties: +- phys : reference to the SATA PHY node +- target-supply : regulator for SATA target power Examples: sata@ffe08000 { @@ -68,10 +69,12 @@ With sub-nodes: sata0: sata-port@0 { reg = <0>; phys = <&sata_phy 0>; + target-supply = <®_sata0>; }; sata1: sata-port@1 { reg = <1>; phys = <&sata_phy 1>; + target-supply = <®_sata1>;; }; }; diff --git a/Documentation/devicetree/bindings/ata/cavium-compact-flash.txt b/Documentation/devicetree/bindings/ata/cavium-compact-flash.txt index 93986a5a8018..3bacc8e0931e 100644 --- a/Documentation/devicetree/bindings/ata/cavium-compact-flash.txt +++ b/Documentation/devicetree/bindings/ata/cavium-compact-flash.txt @@ -9,7 +9,7 @@ Properties: Compatibility with many Cavium evaluation boards. -- reg: The base address of the the CF chip select banks. Depending on +- reg: The base address of the CF chip select banks. Depending on the device configuration, there may be one or two banks. - cavium,bus-width: The width of the connection to the CF devices. Valid diff --git a/Documentation/devicetree/bindings/ata/marvell.txt b/Documentation/devicetree/bindings/ata/marvell.txt index 1c8351604d38..b460edd12766 100644 --- a/Documentation/devicetree/bindings/ata/marvell.txt +++ b/Documentation/devicetree/bindings/ata/marvell.txt @@ -6,11 +6,17 @@ Required Properties: - interrupts : Interrupt controller is using - nr-ports : Number of SATA ports in use. +Optional Properties: +- phys : List of phandles to sata phys +- phy-names : Should be "0", "1", etc, one number per phandle + Example: sata@80000 { compatible = "marvell,orion-sata"; reg = <0x80000 0x5000>; interrupts = <21>; + phys = <&sata_phy0>, <&sata_phy1>; + phy-names = "0", "1"; nr-ports = <2>; } diff --git a/Documentation/devicetree/bindings/ata/sata_rcar.txt b/Documentation/devicetree/bindings/ata/sata_rcar.txt index 80ae87a0784b..2493a5a31655 100644 --- a/Documentation/devicetree/bindings/ata/sata_rcar.txt +++ b/Documentation/devicetree/bindings/ata/sata_rcar.txt @@ -3,18 +3,21 @@ Required properties: - compatible : should contain one of the following: - "renesas,sata-r8a7779" for R-Car H1 + ("renesas,rcar-sata" is deprecated) - "renesas,sata-r8a7790-es1" for R-Car H2 ES1 - "renesas,sata-r8a7790" for R-Car H2 other than ES1 - "renesas,sata-r8a7791" for R-Car M2-W - "renesas,sata-r8a7793" for R-Car M2-N - reg : address and length of the SATA registers; - interrupts : must consist of one interrupt specifier. +- clocks : must contain a reference to the functional clock. Example: -sata: sata@fc600000 { - compatible = "renesas,sata-r8a7779"; - reg = <0xfc600000 0x2000>; +sata0: sata@ee300000 { + compatible = "renesas,sata-r8a7791"; + reg = <0 0xee300000 0 0x2000>; interrupt-parent = <&gic>; - interrupts = <0 100 IRQ_TYPE_LEVEL_HIGH>; + interrupts = <0 105 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&mstp8_clks R8A7791_CLK_SATA0>; }; diff --git a/Documentation/devicetree/bindings/ata/tegra-sata.txt b/Documentation/devicetree/bindings/ata/tegra-sata.txt index 946f2072570b..66c83c3e8915 100644 --- a/Documentation/devicetree/bindings/ata/tegra-sata.txt +++ b/Documentation/devicetree/bindings/ata/tegra-sata.txt @@ -1,7 +1,9 @@ Tegra124 SoC SATA AHCI controller Required properties : -- compatible : "nvidia,tegra124-ahci". +- compatible : For Tegra124, must contain "nvidia,tegra124-ahci". Otherwise, + must contain '"nvidia,<chip>-ahci", "nvidia,tegra124-ahci"', where <chip> + is tegra132. - reg : Should contain 2 entries: - AHCI register set (SATA BAR5) - SATA register set diff --git a/Documentation/devicetree/bindings/btmrvl.txt b/Documentation/devicetree/bindings/btmrvl.txt new file mode 100644 index 000000000000..58f964bb0a52 --- /dev/null +++ b/Documentation/devicetree/bindings/btmrvl.txt @@ -0,0 +1,29 @@ +btmrvl +------ + +Required properties: + + - compatible : must be "btmrvl,cfgdata" + +Optional properties: + + - btmrvl,cal-data : Calibration data downloaded to the device during + initialization. This is an array of 28 values(u8). + + - btmrvl,gpio-gap : gpio and gap (in msecs) combination to be + configured. + +Example: + +GPIO pin 13 is configured as a wakeup source and GAP is set to 100 msecs +in below example. + +btmrvl { + compatible = "btmrvl,cfgdata"; + + btmrvl,cal-data = /bits/ 8 < + 0x37 0x01 0x1c 0x00 0xff 0xff 0xff 0xff 0x01 0x7f 0x04 0x02 + 0x00 0x00 0xba 0xce 0xc0 0xc6 0x2d 0x00 0x00 0x00 0x00 0x00 + 0x00 0x00 0xf0 0x00>; + btmrvl,gpio-gap = <0x0d64>; +}; diff --git a/Documentation/devicetree/bindings/bus/bcma.txt b/Documentation/devicetree/bindings/bus/bcma.txt index 62a48348ac15..edd44d802139 100644 --- a/Documentation/devicetree/bindings/bus/bcma.txt +++ b/Documentation/devicetree/bindings/bus/bcma.txt @@ -8,6 +8,11 @@ Required properties: The cores on the AXI bus are automatically detected by bcma with the memory ranges they are using and they get registered afterwards. +Automatic detection of the IRQ number is not working on +BCM47xx/BCM53xx ARM SoCs. To assign IRQ numbers to the cores, provide +them manually through device tree. Use an interrupt-map to specify the +IRQ used by the devices on the bus. The first address is just an index, +because we do not have any special register. The top-level axi bus may contain children representing attached cores (devices). This is needed since some hardware details can't be auto @@ -22,6 +27,22 @@ Example: ranges = <0x00000000 0x18000000 0x00100000>; #address-cells = <1>; #size-cells = <1>; + #interrupt-cells = <1>; + interrupt-map-mask = <0x000fffff 0xffff>; + interrupt-map = + /* Ethernet Controller 0 */ + <0x00024000 0 &gic GIC_SPI 147 IRQ_TYPE_LEVEL_HIGH>, + + /* Ethernet Controller 1 */ + <0x00025000 0 &gic GIC_SPI 148 IRQ_TYPE_LEVEL_HIGH>; + + /* PCIe Controller 0 */ + <0x00012000 0 &gic GIC_SPI 126 IRQ_TYPE_LEVEL_HIGH>, + <0x00012000 1 &gic GIC_SPI 127 IRQ_TYPE_LEVEL_HIGH>, + <0x00012000 2 &gic GIC_SPI 128 IRQ_TYPE_LEVEL_HIGH>, + <0x00012000 3 &gic GIC_SPI 129 IRQ_TYPE_LEVEL_HIGH>, + <0x00012000 4 &gic GIC_SPI 130 IRQ_TYPE_LEVEL_HIGH>, + <0x00012000 5 &gic GIC_SPI 131 IRQ_TYPE_LEVEL_HIGH>; chipcommon { reg = <0x00000000 0x1000>; diff --git a/Documentation/devicetree/bindings/bus/brcm,gisb-arb.txt b/Documentation/devicetree/bindings/bus/brcm,gisb-arb.txt index e2d501d20c9a..1eceefb20f01 100644 --- a/Documentation/devicetree/bindings/bus/brcm,gisb-arb.txt +++ b/Documentation/devicetree/bindings/bus/brcm,gisb-arb.txt @@ -2,7 +2,11 @@ Broadcom GISB bus Arbiter controller Required properties: -- compatible: should be "brcm,gisb-arb" +- compatible: + "brcm,gisb-arb" or "brcm,bcm7445-gisb-arb" for 28nm chips + "brcm,bcm7435-gisb-arb" for newer 40nm chips + "brcm,bcm7400-gisb-arb" for older 40nm chips and all 65nm chips + "brcm,bcm7038-gisb-arb" for 130nm chips - reg: specifies the base physical address and size of the registers - interrupt-parent: specifies the phandle to the parent interrupt controller this arbiter gets interrupt line from diff --git a/Documentation/devicetree/bindings/bus/mvebu-mbus.txt b/Documentation/devicetree/bindings/bus/mvebu-mbus.txt index 5fa44f52a0b8..fa6cde41b460 100644 --- a/Documentation/devicetree/bindings/bus/mvebu-mbus.txt +++ b/Documentation/devicetree/bindings/bus/mvebu-mbus.txt @@ -6,8 +6,8 @@ Required properties: - compatible: Should be set to one of the following: marvell,armada370-mbus marvell,armadaxp-mbus - marvell,armada370-mbus - marvell,armadaxp-mbus + marvell,armada375-mbus + marvell,armada380-mbus marvell,kirkwood-mbus marvell,dove-mbus marvell,orion5x-88f5281-mbus @@ -48,9 +48,12 @@ Required properties: - compatible: Should be set to "marvell,mbus-controller". - reg: Device's register space. - Two entries are expected (see the examples below): - the first one controls the devices decoding window and - the second one controls the SDRAM decoding window. + Two or three entries are expected (see the examples below): + the first one controls the devices decoding window, + the second one controls the SDRAM decoding window and + the third controls the MBus bridge (only with the + marvell,armada370-mbus and marvell,armadaxp-mbus + compatible strings) Example: @@ -67,7 +70,7 @@ Example: mbusc: mbus-controller@20000 { compatible = "marvell,mbus-controller"; - reg = <0x20000 0x100>, <0x20180 0x20>; + reg = <0x20000 0x100>, <0x20180 0x20>, <0x20250 0x8>; }; /* more children ...*/ @@ -126,7 +129,7 @@ are skipped. mbusc: mbus-controller@20000 { compatible = "marvell,mbus-controller"; - reg = <0x20000 0x100>, <0x20180 0x20>; + reg = <0x20000 0x100>, <0x20180 0x20>, <0x20250 0x8>; }; /* more children ...*/ @@ -170,7 +173,7 @@ Using this macro, the above example would be: mbusc: mbus-controller@20000 { compatible = "marvell,mbus-controller"; - reg = <0x20000 0x100>, <0x20180 0x20>; + reg = <0x20000 0x100>, <0x20180 0x20>, <0x20250 0x8>; }; /* other children */ @@ -266,7 +269,7 @@ See the example below, where a more complete device tree is shown: ranges = <0 MBUS_ID(0xf0, 0x01) 0 0x100000>; mbusc: mbus-controller@20000 { - reg = <0x20000 0x100>, <0x20180 0x20>; + reg = <0x20000 0x100>, <0x20180 0x20>, <0x20250 0x8>; }; interrupt-controller@20000 { diff --git a/Documentation/devicetree/bindings/c6x/dscr.txt b/Documentation/devicetree/bindings/c6x/dscr.txt index b0e97144cfb1..92672235de57 100644 --- a/Documentation/devicetree/bindings/c6x/dscr.txt +++ b/Documentation/devicetree/bindings/c6x/dscr.txt @@ -12,7 +12,7 @@ configuration register for writes. These configuration register may be used to enable (and disable in some cases) SoC pin drivers, select peripheral clock sources (internal or pin), etc. In some cases, a configuration register is write once or the individual bits are write once. In addition to device config, -the DSCR block may provide registers which which are used to reset peripherals, +the DSCR block may provide registers which are used to reset peripherals, provide device ID information, provide ethernet MAC addresses, as well as other miscellaneous functions. diff --git a/Documentation/devicetree/bindings/chosen.txt b/Documentation/devicetree/bindings/chosen.txt new file mode 100644 index 000000000000..ed838f453f7a --- /dev/null +++ b/Documentation/devicetree/bindings/chosen.txt @@ -0,0 +1,46 @@ +The chosen node +--------------- + +The chosen node does not represent a real device, but serves as a place +for passing data between firmware and the operating system, like boot +arguments. Data in the chosen node does not represent the hardware. + + +stdout-path property +-------------------- + +Device trees may specify the device to be used for boot console output +with a stdout-path property under /chosen, as described in ePAPR, e.g. + +/ { + chosen { + stdout-path = "/serial@f00:115200"; + }; + + serial@f00 { + compatible = "vendor,some-uart"; + reg = <0xf00 0x10>; + }; +}; + +If the character ":" is present in the value, this terminates the path. +The meaning of any characters following the ":" is device-specific, and +must be specified in the relevant binding documentation. + +For UART devices, the preferred binding is a string in the form: + + <baud>{<parity>{<bits>{<flow>}}} + +where + + baud - baud rate in decimal + parity - 'n' (none), 'o', (odd) or 'e' (even) + bits - number of data bits + flow - 'r' (rts) + +For example: 115200n8r + +Implementation note: Linux will look for the property "linux,stdout-path" or +on PowerPC "stdout" if "stdout-path" is not found. However, the +"linux,stdout-path" and "stdout" properties are deprecated. New platforms +should only use the "stdout-path" property. diff --git a/Documentation/devicetree/bindings/clock/alphascale,acc.txt b/Documentation/devicetree/bindings/clock/alphascale,acc.txt new file mode 100644 index 000000000000..62e67e883e76 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/alphascale,acc.txt @@ -0,0 +1,115 @@ +Alphascale Clock Controller + +The ACC (Alphascale Clock Controller) is responsible of choising proper +clock source, setting deviders and clock gates. + +Required properties for the ACC node: + - compatible: must be "alphascale,asm9260-clock-controller" + - reg: must contain the ACC register base and size + - #clock-cells : shall be set to 1. + +Simple one-cell clock specifier format is used, where the only cell is used +as an index of the clock inside the provider. +It is encouraged to use dt-binding for clock index definitions. SoC specific +dt-binding should be included to the device tree descriptor. For example +Alphascale ASM9260: +#include <dt-bindings/clock/alphascale,asm9260.h> + +This binding contains two types of clock providers: + _AHB_ - AHB gate; + _SYS_ - adjustable clock source. Not all peripheral have _SYS_ clock provider. +All clock specific details can be found in the SoC documentation. +CLKID_AHB_ROM 0 +CLKID_AHB_RAM 1 +CLKID_AHB_GPIO 2 +CLKID_AHB_MAC 3 +CLKID_AHB_EMI 4 +CLKID_AHB_USB0 5 +CLKID_AHB_USB1 6 +CLKID_AHB_DMA0 7 +CLKID_AHB_DMA1 8 +CLKID_AHB_UART0 9 +CLKID_AHB_UART1 10 +CLKID_AHB_UART2 11 +CLKID_AHB_UART3 12 +CLKID_AHB_UART4 13 +CLKID_AHB_UART5 14 +CLKID_AHB_UART6 15 +CLKID_AHB_UART7 16 +CLKID_AHB_UART8 17 +CLKID_AHB_UART9 18 +CLKID_AHB_I2S0 19 +CLKID_AHB_I2C0 20 +CLKID_AHB_I2C1 21 +CLKID_AHB_SSP0 22 +CLKID_AHB_IOCONFIG 23 +CLKID_AHB_WDT 24 +CLKID_AHB_CAN0 25 +CLKID_AHB_CAN1 26 +CLKID_AHB_MPWM 27 +CLKID_AHB_SPI0 28 +CLKID_AHB_SPI1 29 +CLKID_AHB_QEI 30 +CLKID_AHB_QUADSPI0 31 +CLKID_AHB_CAMIF 32 +CLKID_AHB_LCDIF 33 +CLKID_AHB_TIMER0 34 +CLKID_AHB_TIMER1 35 +CLKID_AHB_TIMER2 36 +CLKID_AHB_TIMER3 37 +CLKID_AHB_IRQ 38 +CLKID_AHB_RTC 39 +CLKID_AHB_NAND 40 +CLKID_AHB_ADC0 41 +CLKID_AHB_LED 42 +CLKID_AHB_DAC0 43 +CLKID_AHB_LCD 44 +CLKID_AHB_I2S1 45 +CLKID_AHB_MAC1 46 + +CLKID_SYS_CPU 47 +CLKID_SYS_AHB 48 +CLKID_SYS_I2S0M 49 +CLKID_SYS_I2S0S 50 +CLKID_SYS_I2S1M 51 +CLKID_SYS_I2S1S 52 +CLKID_SYS_UART0 53 +CLKID_SYS_UART1 54 +CLKID_SYS_UART2 55 +CLKID_SYS_UART3 56 +CLKID_SYS_UART4 56 +CLKID_SYS_UART5 57 +CLKID_SYS_UART6 58 +CLKID_SYS_UART7 59 +CLKID_SYS_UART8 60 +CLKID_SYS_UART9 61 +CLKID_SYS_SPI0 62 +CLKID_SYS_SPI1 63 +CLKID_SYS_QUADSPI 64 +CLKID_SYS_SSP0 65 +CLKID_SYS_NAND 66 +CLKID_SYS_TRACE 67 +CLKID_SYS_CAMM 68 +CLKID_SYS_WDT 69 +CLKID_SYS_CLKOUT 70 +CLKID_SYS_MAC 71 +CLKID_SYS_LCD 72 +CLKID_SYS_ADCANA 73 + +Example of clock consumer with _SYS_ and _AHB_ sinks. +uart4: serial@80010000 { + compatible = "alphascale,asm9260-uart"; + reg = <0x80010000 0x4000>; + clocks = <&acc CLKID_SYS_UART4>, <&acc CLKID_AHB_UART4>; + interrupts = <19>; + status = "disabled"; +}; + +Clock consumer with only one, _AHB_ sink. +timer0: timer@80088000 { + compatible = "alphascale,asm9260-timer"; + reg = <0x80088000 0x4000>; + clocks = <&acc CLKID_AHB_TIMER0>; + interrupts = <29>; +}; + diff --git a/Documentation/devicetree/bindings/clock/bcm-cygnus-clock.txt b/Documentation/devicetree/bindings/clock/bcm-cygnus-clock.txt new file mode 100644 index 000000000000..00d26edec8bc --- /dev/null +++ b/Documentation/devicetree/bindings/clock/bcm-cygnus-clock.txt @@ -0,0 +1,34 @@ +Broadcom Cygnus Clocks + +This binding uses the common clock binding: +Documentation/devicetree/bindings/clock/clock-bindings.txt + +Currently various "fixed" clocks are declared for peripheral drivers that use +the common clock framework to reference their core clocks. Proper support of +these clocks will be added later + +Device tree example: + + clocks { + #address-cells = <1>; + #size-cells = <1>; + ranges; + + osc: oscillator { + compatible = "fixed-clock"; + #clock-cells = <1>; + clock-frequency = <25000000>; + }; + + apb_clk: apb_clk { + compatible = "fixed-clock"; + #clock-cells = <0>; + clock-frequency = <1000000000>; + }; + + periph_clk: periph_clk { + compatible = "fixed-clock"; + #clock-cells = <0>; + clock-frequency = <500000000>; + }; + }; diff --git a/Documentation/devicetree/bindings/clock/exynos4415-clock.txt b/Documentation/devicetree/bindings/clock/exynos4415-clock.txt new file mode 100644 index 000000000000..847d98bae8cf --- /dev/null +++ b/Documentation/devicetree/bindings/clock/exynos4415-clock.txt @@ -0,0 +1,38 @@ +* Samsung Exynos4415 Clock Controller + +The Exynos4415 clock controller generates and supplies clock to various +consumer devices within the Exynos4415 SoC. + +Required properties: + +- compatible: should be one of the following: + - "samsung,exynos4415-cmu" - for the main system clocks controller + (CMU_LEFTBUS, CMU_RIGHTBUS, CMU_TOP, CMU_CPU clock domains). + - "samsung,exynos4415-cmu-dmc" - for the Exynos4415 SoC DRAM Memory + Controller (DMC) domain clock controller. + +- reg: physical base address of the controller and length of memory mapped + region. + +- #clock-cells: should be 1. + +Each clock is assigned an identifier and client nodes can use this identifier +to specify the clock which they consume. + +All available clocks are defined as preprocessor macros in +dt-bindings/clock/exynos4415.h header and can be used in device +tree sources. + +Example 1: An example of a clock controller node is listed below. + + cmu: clock-controller@10030000 { + compatible = "samsung,exynos4415-cmu"; + reg = <0x10030000 0x18000>; + #clock-cells = <1>; + }; + + cmu-dmc: clock-controller@105C0000 { + compatible = "samsung,exynos4415-cmu-dmc"; + reg = <0x105C0000 0x3000>; + #clock-cells = <1>; + }; diff --git a/Documentation/devicetree/bindings/clock/exynos7-clock.txt b/Documentation/devicetree/bindings/clock/exynos7-clock.txt new file mode 100644 index 000000000000..6d3d5f80c1c3 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/exynos7-clock.txt @@ -0,0 +1,93 @@ +* Samsung Exynos7 Clock Controller + +Exynos7 clock controller has various blocks which are instantiated +independently from the device-tree. These clock controllers +generate and supply clocks to various hardware blocks within +the SoC. + +Each clock is assigned an identifier and client nodes can use +this identifier to specify the clock which they consume. All +available clocks are defined as preprocessor macros in +dt-bindings/clock/exynos7-clk.h header and can be used in +device tree sources. + +External clocks: + +There are several clocks that are generated outside the SoC. It +is expected that they are defined using standard clock bindings +with following clock-output-names: + + - "fin_pll" - PLL input clock from XXTI + +Required Properties for Clock Controller: + + - compatible: clock controllers will use one of the following + compatible strings to indicate the clock controller + functionality. + + - "samsung,exynos7-clock-topc" + - "samsung,exynos7-clock-top0" + - "samsung,exynos7-clock-top1" + - "samsung,exynos7-clock-ccore" + - "samsung,exynos7-clock-peric0" + - "samsung,exynos7-clock-peric1" + - "samsung,exynos7-clock-peris" + - "samsung,exynos7-clock-fsys0" + - "samsung,exynos7-clock-fsys1" + + - reg: physical base address of the controller and the length of + memory mapped region. + + - #clock-cells: should be 1. + + - clocks: list of clock identifiers which are fed as the input to + the given clock controller. Please refer the next section to + find the input clocks for a given controller. + +- clock-names: list of names of clocks which are fed as the input + to the given clock controller. + +Input clocks for top0 clock controller: + - fin_pll + - dout_sclk_bus0_pll + - dout_sclk_bus1_pll + - dout_sclk_cc_pll + - dout_sclk_mfc_pll + +Input clocks for top1 clock controller: + - fin_pll + - dout_sclk_bus0_pll + - dout_sclk_bus1_pll + - dout_sclk_cc_pll + - dout_sclk_mfc_pll + +Input clocks for ccore clock controller: + - fin_pll + - dout_aclk_ccore_133 + +Input clocks for peric0 clock controller: + - fin_pll + - dout_aclk_peric0_66 + - sclk_uart0 + +Input clocks for peric1 clock controller: + - fin_pll + - dout_aclk_peric1_66 + - sclk_uart1 + - sclk_uart2 + - sclk_uart3 + +Input clocks for peris clock controller: + - fin_pll + - dout_aclk_peris_66 + +Input clocks for fsys0 clock controller: + - fin_pll + - dout_aclk_fsys0_200 + - dout_sclk_mmc2 + +Input clocks for fsys1 clock controller: + - fin_pll + - dout_aclk_fsys1_200 + - dout_sclk_mmc0 + - dout_sclk_mmc1 diff --git a/Documentation/devicetree/bindings/clock/marvell,mmp2.txt b/Documentation/devicetree/bindings/clock/marvell,mmp2.txt new file mode 100644 index 000000000000..af376a01f2b7 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/marvell,mmp2.txt @@ -0,0 +1,21 @@ +* Marvell MMP2 Clock Controller + +The MMP2 clock subsystem generates and supplies clock to various +controllers within the MMP2 SoC. + +Required Properties: + +- compatible: should be one of the following. + - "marvell,mmp2-clock" - controller compatible with MMP2 SoC. + +- reg: physical base address of the clock subsystem and length of memory mapped + region. There are 3 places in SOC has clock control logic: + "mpmu", "apmu", "apbc". So three reg spaces need to be defined. + +- #clock-cells: should be 1. +- #reset-cells: should be 1. + +Each clock is assigned an identifier and client nodes use this identifier +to specify the clock which they consume. + +All these identifier could be found in <dt-bindings/clock/marvell-mmp2.h>. diff --git a/Documentation/devicetree/bindings/clock/marvell,pxa168.txt b/Documentation/devicetree/bindings/clock/marvell,pxa168.txt new file mode 100644 index 000000000000..c62eb1d173a6 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/marvell,pxa168.txt @@ -0,0 +1,21 @@ +* Marvell PXA168 Clock Controller + +The PXA168 clock subsystem generates and supplies clock to various +controllers within the PXA168 SoC. + +Required Properties: + +- compatible: should be one of the following. + - "marvell,pxa168-clock" - controller compatible with PXA168 SoC. + +- reg: physical base address of the clock subsystem and length of memory mapped + region. There are 3 places in SOC has clock control logic: + "mpmu", "apmu", "apbc". So three reg spaces need to be defined. + +- #clock-cells: should be 1. +- #reset-cells: should be 1. + +Each clock is assigned an identifier and client nodes use this identifier +to specify the clock which they consume. + +All these identifier could be found in <dt-bindings/clock/marvell,pxa168.h>. diff --git a/Documentation/devicetree/bindings/clock/marvell,pxa910.txt b/Documentation/devicetree/bindings/clock/marvell,pxa910.txt new file mode 100644 index 000000000000..d9f41f3c03a0 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/marvell,pxa910.txt @@ -0,0 +1,21 @@ +* Marvell PXA910 Clock Controller + +The PXA910 clock subsystem generates and supplies clock to various +controllers within the PXA910 SoC. + +Required Properties: + +- compatible: should be one of the following. + - "marvell,pxa910-clock" - controller compatible with PXA910 SoC. + +- reg: physical base address of the clock subsystem and length of memory mapped + region. There are 4 places in SOC has clock control logic: + "mpmu", "apmu", "apbc", "apbcp". So four reg spaces need to be defined. + +- #clock-cells: should be 1. +- #reset-cells: should be 1. + +Each clock is assigned an identifier and client nodes use this identifier +to specify the clock which they consume. + +All these identifier could be found in <dt-bindings/clock/marvell-pxa910.h>. diff --git a/Documentation/devicetree/bindings/clock/qoriq-clock.txt b/Documentation/devicetree/bindings/clock/qoriq-clock.txt index 5666812fc42b..266ff9d23229 100644 --- a/Documentation/devicetree/bindings/clock/qoriq-clock.txt +++ b/Documentation/devicetree/bindings/clock/qoriq-clock.txt @@ -62,6 +62,8 @@ Required properties: It takes parent's clock-frequency as its clock. * "fsl,qoriq-sysclk-2.0": for input system clock (v2.0). It takes parent's clock-frequency as its clock. + * "fsl,qoriq-platform-pll-1.0" for the platform PLL clock (v1.0) + * "fsl,qoriq-platform-pll-2.0" for the platform PLL clock (v2.0) - #clock-cells: From common clock binding. The number of cells in a clock-specifier. Should be <0> for "fsl,qoriq-sysclk-[1,2].0" clocks, or <1> for "fsl,qoriq-core-pll-[1,2].0" clocks. @@ -128,8 +130,16 @@ Example for clock block and clock provider: clock-names = "pll0", "pll0-div2", "pll1", "pll1-div2"; clock-output-names = "cmux1"; }; + + platform-pll: platform-pll@c00 { + #clock-cells = <1>; + reg = <0xc00 0x4>; + compatible = "fsl,qoriq-platform-pll-1.0"; + clocks = <&sysclk>; + clock-output-names = "platform-pll", "platform-pll-div2"; + }; }; - } +}; Example for clock consumer: @@ -139,4 +149,4 @@ Example for clock consumer: clocks = <&mux0>; ... }; - } +}; diff --git a/Documentation/devicetree/bindings/clock/renesas,cpg-div6-clocks.txt b/Documentation/devicetree/bindings/clock/renesas,cpg-div6-clocks.txt index 952e373178d2..054f65f9319c 100644 --- a/Documentation/devicetree/bindings/clock/renesas,cpg-div6-clocks.txt +++ b/Documentation/devicetree/bindings/clock/renesas,cpg-div6-clocks.txt @@ -7,11 +7,16 @@ to 64. Required Properties: - compatible: Must be one of the following + - "renesas,r8a73a4-div6-clock" for R8A73A4 (R-Mobile APE6) DIV6 clocks + - "renesas,r8a7740-div6-clock" for R8A7740 (R-Mobile A1) DIV6 clocks - "renesas,r8a7790-div6-clock" for R8A7790 (R-Car H2) DIV6 clocks - "renesas,r8a7791-div6-clock" for R8A7791 (R-Car M2) DIV6 clocks + - "renesas,sh73a0-div6-clock" for SH73A0 (SH-Mobile AG5) DIV6 clocks - "renesas,cpg-div6-clock" for generic DIV6 clocks - reg: Base address and length of the memory resource used by the DIV6 clock - - clocks: Reference to the parent clock + - clocks: Reference to the parent clock(s); either one, four, or eight + clocks must be specified. For clocks with multiple parents, invalid + settings must be specified as "<0>". - #clock-cells: Must be 0 - clock-output-names: The name of the clock as a free-form string @@ -19,10 +24,11 @@ Required Properties: Example ------- - sd2_clk: sd2_clk@e6150078 { - compatible = "renesas,r8a7790-div6-clock", "renesas,cpg-div6-clock"; - reg = <0 0xe6150078 0 4>; - clocks = <&pll1_div2_clk>; + sdhi2_clk: sdhi2_clk@e615007c { + compatible = "renesas,r8a73a4-div6-clock", "renesas,cpg-div6-clock"; + reg = <0 0xe615007c 0 4>; + clocks = <&pll1_div2_clk>, <&cpg_clocks R8A73A4_CLK_PLL2S>, + <0>, <&extal2_clk>; #clock-cells = <0>; - clock-output-names = "sd2"; + clock-output-names = "sdhi2ck"; }; diff --git a/Documentation/devicetree/bindings/clock/renesas,cpg-mstp-clocks.txt b/Documentation/devicetree/bindings/clock/renesas,cpg-mstp-clocks.txt index a5f52238c80d..2e18676bd4b5 100644 --- a/Documentation/devicetree/bindings/clock/renesas,cpg-mstp-clocks.txt +++ b/Documentation/devicetree/bindings/clock/renesas,cpg-mstp-clocks.txt @@ -26,11 +26,11 @@ Required Properties: must appear in the same order as the output clocks. - #clock-cells: Must be 1 - clock-output-names: The name of the clocks as free-form strings - - renesas,clock-indices: Indices of the gate clocks into the group (0 to 31) + - clock-indices: Indices of the gate clocks into the group (0 to 31) -The clocks, clock-output-names and renesas,clock-indices properties contain one -entry per gate clock. The MSTP groups are sparsely populated. Unimplemented -gate clocks must not be declared. +The clocks, clock-output-names and clock-indices properties contain one entry +per gate clock. The MSTP groups are sparsely populated. Unimplemented gate +clocks must not be declared. Example diff --git a/Documentation/devicetree/bindings/clock/renesas,sh73a0-cpg-clocks.txt b/Documentation/devicetree/bindings/clock/renesas,sh73a0-cpg-clocks.txt new file mode 100644 index 000000000000..a8978ec94831 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/renesas,sh73a0-cpg-clocks.txt @@ -0,0 +1,35 @@ +These bindings should be considered EXPERIMENTAL for now. + +* Renesas SH73A0 Clock Pulse Generator (CPG) + +The CPG generates core clocks for the SH73A0 SoC. It includes four PLLs +and several fixed ratio dividers. + +Required Properties: + + - compatible: Must be "renesas,sh73a0-cpg-clocks" + + - reg: Base address and length of the memory resource used by the CPG + + - clocks: Reference to the parent clocks ("extal1" and "extal2") + + - #clock-cells: Must be 1 + + - clock-output-names: The names of the clocks. Supported clocks are "main", + "pll0", "pll1", "pll2", "pll3", "dsi0phy", "dsi1phy", "zg", "m3", "b", + "m1", "m2", "z", "zx", and "hp". + + +Example +------- + + cpg_clocks: cpg_clocks@e6150000 { + compatible = "renesas,sh73a0-cpg-clocks"; + reg = <0 0xe6150000 0 0x10000>; + clocks = <&extal1_clk>, <&extal2_clk>; + #clock-cells = <1>; + clock-output-names = "main", "pll0", "pll1", "pll2", + "pll3", "dsi0phy", "dsi1phy", + "zg", "m3", "b", "m1", "m2", + "z", "zx", "hp"; + }; diff --git a/Documentation/devicetree/bindings/clock/st/st,flexgen.txt b/Documentation/devicetree/bindings/clock/st/st,flexgen.txt index 1d3ace088172..b7ee5c7e0f75 100644 --- a/Documentation/devicetree/bindings/clock/st/st,flexgen.txt +++ b/Documentation/devicetree/bindings/clock/st/st,flexgen.txt @@ -11,7 +11,7 @@ Please find an example below: Clockgen block diagram ------------------------------------------------------------------- - | Flexgen stucture | + | Flexgen structure | | --------------------------------------------- | | | ------- -------- -------- | | clk_sysin | | | | | | | | | diff --git a/Documentation/devicetree/bindings/clock/sunxi.txt b/Documentation/devicetree/bindings/clock/sunxi.txt index ed116df9c3e7..67b2b99f2b33 100644 --- a/Documentation/devicetree/bindings/clock/sunxi.txt +++ b/Documentation/devicetree/bindings/clock/sunxi.txt @@ -10,14 +10,17 @@ Required properties: "allwinner,sun4i-a10-pll1-clk" - for the main PLL clock and PLL4 "allwinner,sun6i-a31-pll1-clk" - for the main PLL clock on A31 "allwinner,sun8i-a23-pll1-clk" - for the main PLL clock on A23 + "allwinner,sun9i-a80-pll4-clk" - for the peripheral PLLs on A80 "allwinner,sun4i-a10-pll5-clk" - for the PLL5 clock "allwinner,sun4i-a10-pll6-clk" - for the PLL6 clock "allwinner,sun6i-a31-pll6-clk" - for the PLL6 clock on A31 + "allwinner,sun9i-a80-gt-clk" - for the GT bus clock on A80 "allwinner,sun4i-a10-cpu-clk" - for the CPU multiplexer clock "allwinner,sun4i-a10-axi-clk" - for the AXI clock "allwinner,sun8i-a23-axi-clk" - for the AXI clock on A23 "allwinner,sun4i-a10-axi-gates-clk" - for the AXI gates "allwinner,sun4i-a10-ahb-clk" - for the AHB clock + "allwinner,sun9i-a80-ahb-clk" - for the AHB bus clocks on A80 "allwinner,sun4i-a10-ahb-gates-clk" - for the AHB gates on A10 "allwinner,sun5i-a13-ahb-gates-clk" - for the AHB gates on A13 "allwinner,sun5i-a10s-ahb-gates-clk" - for the AHB gates on A10s @@ -26,24 +29,29 @@ Required properties: "allwinner,sun6i-a31-ahb1-mux-clk" - for the AHB1 multiplexer on A31 "allwinner,sun6i-a31-ahb1-gates-clk" - for the AHB1 gates on A31 "allwinner,sun8i-a23-ahb1-gates-clk" - for the AHB1 gates on A23 + "allwinner,sun9i-a80-ahb0-gates-clk" - for the AHB0 gates on A80 + "allwinner,sun9i-a80-ahb1-gates-clk" - for the AHB1 gates on A80 + "allwinner,sun9i-a80-ahb2-gates-clk" - for the AHB2 gates on A80 "allwinner,sun4i-a10-apb0-clk" - for the APB0 clock "allwinner,sun6i-a31-apb0-clk" - for the APB0 clock on A31 "allwinner,sun8i-a23-apb0-clk" - for the APB0 clock on A23 + "allwinner,sun9i-a80-apb0-clk" - for the APB0 bus clock on A80 "allwinner,sun4i-a10-apb0-gates-clk" - for the APB0 gates on A10 "allwinner,sun5i-a13-apb0-gates-clk" - for the APB0 gates on A13 "allwinner,sun5i-a10s-apb0-gates-clk" - for the APB0 gates on A10s "allwinner,sun6i-a31-apb0-gates-clk" - for the APB0 gates on A31 "allwinner,sun7i-a20-apb0-gates-clk" - for the APB0 gates on A20 "allwinner,sun8i-a23-apb0-gates-clk" - for the APB0 gates on A23 + "allwinner,sun9i-a80-apb0-gates-clk" - for the APB0 gates on A80 "allwinner,sun4i-a10-apb1-clk" - for the APB1 clock - "allwinner,sun4i-a10-apb1-mux-clk" - for the APB1 clock muxing + "allwinner,sun9i-a80-apb1-clk" - for the APB1 bus clock on A80 "allwinner,sun4i-a10-apb1-gates-clk" - for the APB1 gates on A10 "allwinner,sun5i-a13-apb1-gates-clk" - for the APB1 gates on A13 "allwinner,sun5i-a10s-apb1-gates-clk" - for the APB1 gates on A10s "allwinner,sun6i-a31-apb1-gates-clk" - for the APB1 gates on A31 "allwinner,sun7i-a20-apb1-gates-clk" - for the APB1 gates on A20 "allwinner,sun8i-a23-apb1-gates-clk" - for the APB1 gates on A23 - "allwinner,sun6i-a31-apb2-div-clk" - for the APB2 gates on A31 + "allwinner,sun9i-a80-apb1-gates-clk" - for the APB1 gates on A80 "allwinner,sun6i-a31-apb2-gates-clk" - for the APB2 gates on A31 "allwinner,sun8i-a23-apb2-gates-clk" - for the APB2 gates on A23 "allwinner,sun5i-a13-mbus-clk" - for the MBUS clock on A13 @@ -63,8 +71,9 @@ Required properties for all clocks: multiplexed clocks, the list order must match the hardware programming order. - #clock-cells : from common clock binding; shall be set to 0 except for - "allwinner,*-gates-clk", "allwinner,sun4i-pll5-clk" and - "allwinner,sun4i-pll6-clk" where it shall be set to 1 + the following compatibles where it shall be set to 1: + "allwinner,*-gates-clk", "allwinner,sun4i-pll5-clk", + "allwinner,sun4i-pll6-clk", "allwinner,sun6i-a31-pll6-clk" - clock-output-names : shall be the corresponding names of the outputs. If the clock module only has one output, the name shall be the module name. @@ -79,6 +88,12 @@ Clock consumers should specify the desired clocks they use with a "clocks" phandle cell. Consumers that are using a gated clock should provide an additional ID in their clock property. This ID is the offset of the bit controlling this particular gate in the register. +For the other clocks with "#clock-cells" = 1, the additional ID shall +refer to the index of the output. + +For "allwinner,sun6i-a31-pll6-clk", there are 2 outputs. The first output +is the normal PLL6 output, or "pll6". The second output is rate doubled +PLL6, or "pll6x2". For example: @@ -106,6 +121,14 @@ pll5: clk@01c20020 { clock-output-names = "pll5_ddr", "pll5_other"; }; +pll6: clk@01c20028 { + #clock-cells = <1>; + compatible = "allwinner,sun6i-a31-pll6-clk"; + reg = <0x01c20028 0x4>; + clocks = <&osc24M>; + clock-output-names = "pll6", "pll6x2"; +}; + cpu: cpu@01c20054 { #clock-cells = <0>; compatible = "allwinner,sun4i-a10-cpu-clk"; diff --git a/Documentation/devicetree/bindings/clock/vf610-clock.txt b/Documentation/devicetree/bindings/clock/vf610-clock.txt index c80863d344ac..63f9f1ac3439 100644 --- a/Documentation/devicetree/bindings/clock/vf610-clock.txt +++ b/Documentation/devicetree/bindings/clock/vf610-clock.txt @@ -5,6 +5,19 @@ Required properties: - reg: Address and length of the register set - #clock-cells: Should be <1> +Optional properties: +- clocks: list of clock identifiers which are external input clocks to the + given clock controller. Please refer the next section to find + the input clocks for a given controller. +- clock-names: list of names of clocks which are exteral input clocks to the + given clock controller. + +Input clocks for top clock controller: + - sxosc (external crystal oscillator 32KHz, recommended) + - fxosc (external crystal oscillator 24MHz, recommended) + - audio_ext + - enet_ext + The clock consumer should specify the desired clock by having the clock ID in its "clocks" phandle cell. See include/dt-bindings/clock/vf610-clock.h for the full list of VF610 clock IDs. @@ -15,6 +28,8 @@ clks: ccm@4006b000 { compatible = "fsl,vf610-ccm"; reg = <0x4006b000 0x1000>; #clock-cells = <1>; + clocks = <&sxosc>, <&fxosc>; + clock-names = "sxosc", "fxosc"; }; uart1: serial@40028000 { diff --git a/Documentation/devicetree/bindings/crypto/fsl-imx-sahara.txt b/Documentation/devicetree/bindings/crypto/fsl-imx-sahara.txt index 5c65eccd0e56..e8a35c71e947 100644 --- a/Documentation/devicetree/bindings/crypto/fsl-imx-sahara.txt +++ b/Documentation/devicetree/bindings/crypto/fsl-imx-sahara.txt @@ -1,5 +1,5 @@ Freescale SAHARA Cryptographic Accelerator included in some i.MX chips. -Currently only i.MX27 is supported. +Currently only i.MX27 and i.MX53 are supported. Required properties: - compatible : Should be "fsl,<soc>-sahara" diff --git a/Documentation/devicetree/bindings/devfreq/event/exynos-ppmu.txt b/Documentation/devicetree/bindings/devfreq/event/exynos-ppmu.txt new file mode 100644 index 000000000000..b54bf3a2ff57 --- /dev/null +++ b/Documentation/devicetree/bindings/devfreq/event/exynos-ppmu.txt @@ -0,0 +1,110 @@ + +* Samsung Exynos PPMU (Platform Performance Monitoring Unit) device + +The Samsung Exynos SoC has PPMU (Platform Performance Monitoring Unit) for +each IP. PPMU provides the primitive values to get performance data. These +PPMU events provide information of the SoC's behaviors so that you may +use to analyze system performance, to make behaviors visible and to count +usages of each IP (DMC, CPU, RIGHTBUS, LEFTBUS, CAM interface, LCD, G3D, MFC). +The Exynos PPMU driver uses the devfreq-event class to provide event data +to various devfreq devices. The devfreq devices would use the event data when +derterming the current state of each IP. + +Required properties: +- compatible: Should be "samsung,exynos-ppmu". +- reg: physical base address of each PPMU and length of memory mapped region. + +Optional properties: +- clock-names : the name of clock used by the PPMU, "ppmu" +- clocks : phandles for clock specified in "clock-names" property +- #clock-cells: should be 1. + +Example1 : PPMU nodes in exynos3250.dtsi are listed below. + + ppmu_dmc0: ppmu_dmc0@106a0000 { + compatible = "samsung,exynos-ppmu"; + reg = <0x106a0000 0x2000>; + status = "disabled"; + }; + + ppmu_dmc1: ppmu_dmc1@106b0000 { + compatible = "samsung,exynos-ppmu"; + reg = <0x106b0000 0x2000>; + status = "disabled"; + }; + + ppmu_cpu: ppmu_cpu@106c0000 { + compatible = "samsung,exynos-ppmu"; + reg = <0x106c0000 0x2000>; + status = "disabled"; + }; + + ppmu_rightbus: ppmu_rightbus@112a0000 { + compatible = "samsung,exynos-ppmu"; + reg = <0x112a0000 0x2000>; + clocks = <&cmu CLK_PPMURIGHT>; + clock-names = "ppmu"; + status = "disabled"; + }; + + ppmu_leftbus: ppmu_leftbus0@116a0000 { + compatible = "samsung,exynos-ppmu"; + reg = <0x116a0000 0x2000>; + clocks = <&cmu CLK_PPMULEFT>; + clock-names = "ppmu"; + status = "disabled"; + }; + +Example2 : Events of each PPMU node in exynos3250-rinato.dts are listed below. + + &ppmu_dmc0 { + status = "okay"; + + events { + ppmu_dmc0_3: ppmu-event3-dmc0 { + event-name = "ppmu-event3-dmc0"; + }; + + ppmu_dmc0_2: ppmu-event2-dmc0 { + event-name = "ppmu-event2-dmc0"; + }; + + ppmu_dmc0_1: ppmu-event1-dmc0 { + event-name = "ppmu-event1-dmc0"; + }; + + ppmu_dmc0_0: ppmu-event0-dmc0 { + event-name = "ppmu-event0-dmc0"; + }; + }; + }; + + &ppmu_dmc1 { + status = "okay"; + + events { + ppmu_dmc1_3: ppmu-event3-dmc1 { + event-name = "ppmu-event3-dmc1"; + }; + }; + }; + + &ppmu_leftbus { + status = "okay"; + + events { + ppmu_leftbus_3: ppmu-event3-leftbus { + event-name = "ppmu-event3-leftbus"; + }; + }; + }; + + &ppmu_rightbus { + status = "okay"; + + events { + ppmu_rightbus_3: ppmu-event3-rightbus { + event-name = "ppmu-event3-rightbus"; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/dma/atmel-xdma.txt b/Documentation/devicetree/bindings/dma/atmel-xdma.txt new file mode 100644 index 000000000000..0eb2b3207e08 --- /dev/null +++ b/Documentation/devicetree/bindings/dma/atmel-xdma.txt @@ -0,0 +1,54 @@ +* Atmel Extensible Direct Memory Access Controller (XDMAC) + +* XDMA Controller +Required properties: +- compatible: Should be "atmel,<chip>-dma". + <chip> compatible description: + - sama5d4: first SoC adding the XDMAC +- reg: Should contain DMA registers location and length. +- interrupts: Should contain DMA interrupt. +- #dma-cells: Must be <1>, used to represent the number of integer cells in +the dmas property of client devices. + - The 1st cell specifies the channel configuration register: + - bit 13: SIF, source interface identifier, used to get the memory + interface identifier, + - bit 14: DIF, destination interface identifier, used to get the peripheral + interface identifier, + - bit 30-24: PERID, peripheral identifier. + +Example: + +dma1: dma-controller@f0004000 { + compatible = "atmel,sama5d4-dma"; + reg = <0xf0004000 0x200>; + interrupts = <50 4 0>; + #dma-cells = <1>; +}; + + +* DMA clients +DMA clients connected to the Atmel XDMA controller must use the format +described in the dma.txt file, using a one-cell specifier for each channel. +The two cells in order are: +1. A phandle pointing to the DMA controller. +2. Channel configuration register. Configurable fields are: + - bit 13: SIF, source interface identifier, used to get the memory + interface identifier, + - bit 14: DIF, destination interface identifier, used to get the peripheral + interface identifier, + - bit 30-24: PERID, peripheral identifier. + +Example: + +i2c2: i2c@f8024000 { + compatible = "atmel,at91sam9x5-i2c"; + reg = <0xf8024000 0x4000>; + interrupts = <34 4 6>; + dmas = <&dma1 + (AT91_XDMAC_DT_MEM_IF(0) | AT91_XDMAC_DT_PER_IF(1) + | AT91_XDMAC_DT_PERID(6))>, + <&dma1 + (AT91_XDMAC_DT_MEM_IF(0) | AT91_XDMAC_DT_PER_IF(1) + | AT91_XDMAC_DT_PERID(7))>; + dma-names = "tx", "rx"; +}; diff --git a/Documentation/devicetree/bindings/dma/fsl-imx-sdma.txt b/Documentation/devicetree/bindings/dma/fsl-imx-sdma.txt index 4659fd952301..dc8d3aac1aa9 100644 --- a/Documentation/devicetree/bindings/dma/fsl-imx-sdma.txt +++ b/Documentation/devicetree/bindings/dma/fsl-imx-sdma.txt @@ -48,6 +48,7 @@ The full ID of peripheral types can be found below. 21 ESAI 22 SSI Dual FIFO (needs firmware ver >= 2) 23 Shared ASRC + 24 SAI The third cell specifies the transfer priority as below. diff --git a/Documentation/devicetree/bindings/dma/qcom_bam_dma.txt b/Documentation/devicetree/bindings/dma/qcom_bam_dma.txt index d75a9d767022..f8c3311b7153 100644 --- a/Documentation/devicetree/bindings/dma/qcom_bam_dma.txt +++ b/Documentation/devicetree/bindings/dma/qcom_bam_dma.txt @@ -1,7 +1,9 @@ QCOM BAM DMA controller Required properties: -- compatible: must contain "qcom,bam-v1.4.0" for MSM8974 +- compatible: must be one of the following: + * "qcom,bam-v1.4.0" for MSM8974, APQ8074 and APQ8084 + * "qcom,bam-v1.3.0" for APQ8064, IPQ8064 and MSM8960 - reg: Address range for DMA registers - interrupts: Should contain the one interrupt shared by all channels - #dma-cells: must be <1>, the cell in the dmas property of the client device diff --git a/Documentation/devicetree/bindings/dma/renesas,rcar-dmac.txt b/Documentation/devicetree/bindings/dma/renesas,rcar-dmac.txt index df0f48bcf75a..f7e21b1c2a05 100644 --- a/Documentation/devicetree/bindings/dma/renesas,rcar-dmac.txt +++ b/Documentation/devicetree/bindings/dma/renesas,rcar-dmac.txt @@ -1,6 +1,6 @@ * Renesas R-Car DMA Controller Device Tree bindings -Renesas R-Car Generation 2 SoCs have have multiple multi-channel DMA +Renesas R-Car Generation 2 SoCs have multiple multi-channel DMA controller instances named DMAC capable of serving multiple clients. Channels can be dedicated to specific clients or shared between a large number of clients. diff --git a/Documentation/devicetree/bindings/dma/sun6i-dma.txt b/Documentation/devicetree/bindings/dma/sun6i-dma.txt index 3e145c1675b1..9cdcba24d7c3 100644 --- a/Documentation/devicetree/bindings/dma/sun6i-dma.txt +++ b/Documentation/devicetree/bindings/dma/sun6i-dma.txt @@ -4,7 +4,7 @@ This driver follows the generic DMA bindings defined in dma.txt. Required properties: -- compatible: Must be "allwinner,sun6i-a31-dma" +- compatible: Must be "allwinner,sun6i-a31-dma" or "allwinner,sun8i-a23-dma" - reg: Should contain the registers base address and length - interrupts: Should contain a reference to the interrupt used by this device - clocks: Should contain a reference to the parent AHB clock diff --git a/Documentation/devicetree/bindings/dma/xilinx/xilinx_vdma.txt b/Documentation/devicetree/bindings/dma/xilinx/xilinx_vdma.txt index 1405ed071bb4..e4c4d47f8137 100644 --- a/Documentation/devicetree/bindings/dma/xilinx/xilinx_vdma.txt +++ b/Documentation/devicetree/bindings/dma/xilinx/xilinx_vdma.txt @@ -25,7 +25,7 @@ Required child node properties: - compatible: It should be either "xlnx,axi-vdma-mm2s-channel" or "xlnx,axi-vdma-s2mm-channel". - interrupts: Should contain per channel VDMA interrupts. -- xlnx,data-width: Should contain the stream data width, take values +- xlnx,datawidth: Should contain the stream data width, take values {32,64...1024}. Optional child node properties: diff --git a/Documentation/devicetree/bindings/drm/atmel/hlcdc-dc.txt b/Documentation/devicetree/bindings/drm/atmel/hlcdc-dc.txt new file mode 100644 index 000000000000..ebc1a914bda3 --- /dev/null +++ b/Documentation/devicetree/bindings/drm/atmel/hlcdc-dc.txt @@ -0,0 +1,53 @@ +Device-Tree bindings for Atmel's HLCDC (High LCD Controller) DRM driver + +The Atmel HLCDC Display Controller is subdevice of the HLCDC MFD device. +See ../mfd/atmel-hlcdc.txt for more details. + +Required properties: + - compatible: value should be "atmel,hlcdc-display-controller" + - pinctrl-names: the pin control state names. Should contain "default". + - pinctrl-0: should contain the default pinctrl states. + - #address-cells: should be set to 1. + - #size-cells: should be set to 0. + +Required children nodes: + Children nodes are encoding available output ports and their connections + to external devices using the OF graph reprensentation (see ../graph.txt). + At least one port node is required. + +Example: + + hlcdc: hlcdc@f0030000 { + compatible = "atmel,sama5d3-hlcdc"; + reg = <0xf0030000 0x2000>; + interrupts = <36 IRQ_TYPE_LEVEL_HIGH 0>; + clocks = <&lcdc_clk>, <&lcdck>, <&clk32k>; + clock-names = "periph_clk","sys_clk", "slow_clk"; + status = "disabled"; + + hlcdc-display-controller { + compatible = "atmel,hlcdc-display-controller"; + pinctrl-names = "default"; + pinctrl-0 = <&pinctrl_lcd_base &pinctrl_lcd_rgb888>; + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + #address-cells = <1>; + #size-cells = <0>; + reg = <0>; + + hlcdc_panel_output: endpoint@0 { + reg = <0>; + remote-endpoint = <&panel_input>; + }; + }; + }; + + hlcdc_pwm: hlcdc-pwm { + compatible = "atmel,hlcdc-pwm"; + pinctrl-names = "default"; + pinctrl-0 = <&pinctrl_lcd_pwm>; + #pwm-cells = <3>; + }; + }; diff --git a/Documentation/devicetree/bindings/drm/bridge/dw_hdmi.txt b/Documentation/devicetree/bindings/drm/bridge/dw_hdmi.txt new file mode 100644 index 000000000000..a905c1413558 --- /dev/null +++ b/Documentation/devicetree/bindings/drm/bridge/dw_hdmi.txt @@ -0,0 +1,50 @@ +DesignWare HDMI bridge bindings + +Required properties: +- compatible: platform specific such as: + * "snps,dw-hdmi-tx" + * "fsl,imx6q-hdmi" + * "fsl,imx6dl-hdmi" + * "rockchip,rk3288-dw-hdmi" +- reg: Physical base address and length of the controller's registers. +- interrupts: The HDMI interrupt number +- clocks, clock-names : must have the phandles to the HDMI iahb and isfr clocks, + as described in Documentation/devicetree/bindings/clock/clock-bindings.txt, + the clocks are soc specific, the clock-names should be "iahb", "isfr" +-port@[X]: SoC specific port nodes with endpoint definitions as defined + in Documentation/devicetree/bindings/media/video-interfaces.txt, + please refer to the SoC specific binding document: + * Documentation/devicetree/bindings/drm/imx/hdmi.txt + * Documentation/devicetree/bindings/video/dw_hdmi-rockchip.txt + +Optional properties +- reg-io-width: the width of the reg:1,4, default set to 1 if not present +- ddc-i2c-bus: phandle of an I2C controller used for DDC EDID probing +- clocks, clock-names: phandle to the HDMI CEC clock, name should be "cec" + +Example: + hdmi: hdmi@0120000 { + compatible = "fsl,imx6q-hdmi"; + reg = <0x00120000 0x9000>; + interrupts = <0 115 0x04>; + gpr = <&gpr>; + clocks = <&clks 123>, <&clks 124>; + clock-names = "iahb", "isfr"; + ddc-i2c-bus = <&i2c2>; + + port@0 { + reg = <0>; + + hdmi_mux_0: endpoint { + remote-endpoint = <&ipu1_di0_hdmi>; + }; + }; + + port@1 { + reg = <1>; + + hdmi_mux_1: endpoint { + remote-endpoint = <&ipu1_di1_hdmi>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/staging/imx-drm/fsl-imx-drm.txt b/Documentation/devicetree/bindings/drm/imx/fsl-imx-drm.txt index e75f0e549fff..e75f0e549fff 100644 --- a/Documentation/devicetree/bindings/staging/imx-drm/fsl-imx-drm.txt +++ b/Documentation/devicetree/bindings/drm/imx/fsl-imx-drm.txt diff --git a/Documentation/devicetree/bindings/staging/imx-drm/hdmi.txt b/Documentation/devicetree/bindings/drm/imx/hdmi.txt index 1b756cf9afb0..1b756cf9afb0 100644 --- a/Documentation/devicetree/bindings/staging/imx-drm/hdmi.txt +++ b/Documentation/devicetree/bindings/drm/imx/hdmi.txt diff --git a/Documentation/devicetree/bindings/staging/imx-drm/ldb.txt b/Documentation/devicetree/bindings/drm/imx/ldb.txt index 443bcb6134d5..443bcb6134d5 100644 --- a/Documentation/devicetree/bindings/staging/imx-drm/ldb.txt +++ b/Documentation/devicetree/bindings/drm/imx/ldb.txt diff --git a/Documentation/devicetree/bindings/drm/msm/hdmi.txt b/Documentation/devicetree/bindings/drm/msm/hdmi.txt index aca917fe2ba7..a29a55f3d937 100644 --- a/Documentation/devicetree/bindings/drm/msm/hdmi.txt +++ b/Documentation/devicetree/bindings/drm/msm/hdmi.txt @@ -2,6 +2,8 @@ Qualcomm adreno/snapdragon hdmi output Required properties: - compatible: one of the following + * "qcom,hdmi-tx-8084" + * "qcom,hdmi-tx-8074" * "qcom,hdmi-tx-8660" * "qcom,hdmi-tx-8960" - reg: Physical base address and length of the controller's registers diff --git a/Documentation/devicetree/bindings/fpga/altera-socfpga-fpga-mgr.txt b/Documentation/devicetree/bindings/fpga/altera-socfpga-fpga-mgr.txt new file mode 100644 index 000000000000..9b027a615486 --- /dev/null +++ b/Documentation/devicetree/bindings/fpga/altera-socfpga-fpga-mgr.txt @@ -0,0 +1,17 @@ +Altera SOCFPGA FPGA Manager + +Required properties: +- compatible : should contain "altr,socfpga-fpga-mgr" +- reg : base address and size for memory mapped io. + - The first index is for FPGA manager register access. + - The second index is for writing FPGA configuration data. +- interrupts : interrupt for the FPGA Manager device. + +Example: + + hps_0_fpgamgr: fpgamgr@0xff706000 { + compatible = "altr,socfpga-fpga-mgr"; + reg = <0xFF706000 0x1000 + 0xFFB90000 0x1000>; + interrupts = <0 175 4>; + }; diff --git a/Documentation/devicetree/bindings/fuse/nvidia,tegra20-fuse.txt b/Documentation/devicetree/bindings/fuse/nvidia,tegra20-fuse.txt index d8c98c7614d0..23e1d3194174 100644 --- a/Documentation/devicetree/bindings/fuse/nvidia,tegra20-fuse.txt +++ b/Documentation/devicetree/bindings/fuse/nvidia,tegra20-fuse.txt @@ -1,11 +1,11 @@ NVIDIA Tegra20/Tegra30/Tegr114/Tegra124 fuse block. Required properties: -- compatible : should be: - "nvidia,tegra20-efuse" - "nvidia,tegra30-efuse" - "nvidia,tegra114-efuse" - "nvidia,tegra124-efuse" +- compatible : For Tegra20, must contain "nvidia,tegra20-efuse". For Tegra30, + must contain "nvidia,tegra30-efuse". For Tegra114, must contain + "nvidia,tegra114-efuse". For Tegra124, must contain "nvidia,tegra124-efuse". + Otherwise, must contain "nvidia,<chip>-efuse", plus one of the above, where + <chip> is tegra132. Details: nvidia,tegra20-efuse: Tegra20 requires using APB DMA to read the fuse data due to a hardware bug. Tegra20 also lacks certain information which is diff --git a/Documentation/devicetree/bindings/gpio/fujitsu,mb86s70-gpio.txt b/Documentation/devicetree/bindings/gpio/fujitsu,mb86s70-gpio.txt new file mode 100644 index 000000000000..bef353f370d8 --- /dev/null +++ b/Documentation/devicetree/bindings/gpio/fujitsu,mb86s70-gpio.txt @@ -0,0 +1,20 @@ +Fujitsu MB86S7x GPIO Controller +------------------------------- + +Required properties: +- compatible: Should be "fujitsu,mb86s70-gpio" +- reg: Base address and length of register space +- clocks: Specify the clock +- gpio-controller: Marks the device node as a gpio controller. +- #gpio-cells: Should be <2>. The first cell is the pin number and the + second cell is used to specify optional parameters: + - bit 0 specifies polarity (0 for normal, 1 for inverted). + +Examples: + gpio0: gpio@31000000 { + compatible = "fujitsu,mb86s70-gpio"; + reg = <0 0x31000000 0x10000>; + gpio-controller; + #gpio-cells = <2>; + clocks = <&clk 0 2 1>; + }; diff --git a/Documentation/devicetree/bindings/gpio/gpio-74xx-mmio.txt b/Documentation/devicetree/bindings/gpio/gpio-74xx-mmio.txt new file mode 100644 index 000000000000..7bb1a9d60133 --- /dev/null +++ b/Documentation/devicetree/bindings/gpio/gpio-74xx-mmio.txt @@ -0,0 +1,30 @@ +* 74XX MMIO GPIO driver + +Required properties: +- compatible: Should contain one of the following: + "ti,741g125": for 741G125 (1-bit Input), + "ti,741g174": for 741G74 (1-bit Output), + "ti,742g125": for 742G125 (2-bit Input), + "ti,7474" : for 7474 (2-bit Output), + "ti,74125" : for 74125 (4-bit Input), + "ti,74175" : for 74175 (4-bit Output), + "ti,74365" : for 74365 (6-bit Input), + "ti,74174" : for 74174 (6-bit Output), + "ti,74244" : for 74244 (8-bit Input), + "ti,74273" : for 74273 (8-bit Output), + "ti,741624" : for 741624 (16-bit Input), + "ti,7416374": for 7416374 (16-bit Output). +- reg: Physical base address and length where IC resides. +- gpio-controller: Marks the device node as a gpio controller. +- #gpio-cells: Should be two. The first cell is the pin number and + the second cell is used to specify the GPIO polarity: + 0 = Active High, + 1 = Active Low. + +Example: + ctrl: gpio@30008004 { + compatible = "ti,74174"; + reg = <0x30008004 0x1>; + gpio-controller; + #gpio-cells = <2>; + }; diff --git a/Documentation/devicetree/bindings/gpio/gpio-max732x.txt b/Documentation/devicetree/bindings/gpio/gpio-max732x.txt new file mode 100644 index 000000000000..5fdc843b4542 --- /dev/null +++ b/Documentation/devicetree/bindings/gpio/gpio-max732x.txt @@ -0,0 +1,59 @@ +* MAX732x-compatible I/O expanders + +Required properties: + - compatible: Should be one of the following: + - "maxim,max7319": For the Maxim MAX7319 + - "maxim,max7320": For the Maxim MAX7320 + - "maxim,max7321": For the Maxim MAX7321 + - "maxim,max7322": For the Maxim MAX7322 + - "maxim,max7323": For the Maxim MAX7323 + - "maxim,max7324": For the Maxim MAX7324 + - "maxim,max7325": For the Maxim MAX7325 + - "maxim,max7326": For the Maxim MAX7326 + - "maxim,max7327": For the Maxim MAX7327 + - reg: I2C slave address for this device. + - gpio-controller: Marks the device node as a GPIO controller. + - #gpio-cells: Should be 2. + - first cell is the GPIO number + - second cell specifies GPIO flags, as defined in <dt-bindings/gpio/gpio.h>. + Only the GPIO_ACTIVE_HIGH and GPIO_ACTIVE_LOW flags are supported. + +Optional properties: + + The I/O expander can detect input state changes, and thus optionally act as + an interrupt controller. When the expander interrupt line is connected all the + following properties must be set. For more information please see the + interrupt controller device tree bindings documentation available at + Documentation/devicetree/bindings/interrupt-controller/interrupts.txt. + + - interrupt-controller: Identifies the node as an interrupt controller. + - #interrupt-cells: Number of cells to encode an interrupt source, shall be 2. + - first cell is the pin number + - second cell is used to specify flags + - interrupt-parent: phandle of the parent interrupt controller. + - interrupts: Interrupt specifier for the controllers interrupt. + +Please refer to gpio.txt in this directory for details of the common GPIO +bindings used by client devices. + +Example 1. MAX7325 with interrupt support enabled (CONFIG_GPIO_MAX732X_IRQ=y): + + expander: max7325@6d { + compatible = "maxim,max7325"; + reg = <0x6d>; + gpio-controller; + #gpio-cells = <2>; + interrupt-controller; + #interrupt-cells = <2>; + interrupt-parent = <&gpio4>; + interrupts = <29 IRQ_TYPE_EDGE_FALLING>; + }; + +Example 2. MAX7325 with interrupt support disabled (CONFIG_GPIO_MAX732X_IRQ=n): + + expander: max7325@6d { + compatible = "maxim,max7325"; + reg = <0x6d>; + gpio-controller; + #gpio-cells = <2>; + }; diff --git a/Documentation/devicetree/bindings/gpio/gpio-mcp23s08.txt b/Documentation/devicetree/bindings/gpio/gpio-mcp23s08.txt index c306a2d0f2b1..f3332b9a8ed4 100644 --- a/Documentation/devicetree/bindings/gpio/gpio-mcp23s08.txt +++ b/Documentation/devicetree/bindings/gpio/gpio-mcp23s08.txt @@ -57,6 +57,8 @@ Optional device specific properties: occurred on. If it is not set, the interrupt are only generated for the bank they belong to. On devices with only one interrupt output this property is useless. +- microchip,irq-active-high: Sets the INTPOL flag in the IOCON register. This + configures the IRQ output polarity as active high. Example I2C (with interrupt): gpiom1: gpio@20 { diff --git a/Documentation/devicetree/bindings/gpio/gpio-pcf857x.txt b/Documentation/devicetree/bindings/gpio/gpio-pcf857x.txt index d63194a2c848..ada4e2973323 100644 --- a/Documentation/devicetree/bindings/gpio/gpio-pcf857x.txt +++ b/Documentation/devicetree/bindings/gpio/gpio-pcf857x.txt @@ -39,7 +39,7 @@ Optional Properties: - lines-initial-states: Bitmask that specifies the initial state of each line. When a bit is set to zero, the corresponding line will be initialized to the input (pulled-up) state. When the bit is set to one, the line will be - initialized the the low-level output state. If the property is not specified + initialized the low-level output state. If the property is not specified all lines will be initialized to the input state. The I/O expander can detect input state changes, and thus optionally act as diff --git a/Documentation/devicetree/bindings/gpio/gpio-sx150x.txt b/Documentation/devicetree/bindings/gpio/gpio-sx150x.txt new file mode 100644 index 000000000000..ba2bb84eeac3 --- /dev/null +++ b/Documentation/devicetree/bindings/gpio/gpio-sx150x.txt @@ -0,0 +1,40 @@ +SEMTECH SX150x GPIO expander bindings + + +Required properties: + +- compatible: should be "semtech,sx1506q", + "semtech,sx1508q", + "semtech,sx1509q". + +- reg: The I2C slave address for this device. + +- interrupt-parent: phandle of the parent interrupt controller. + +- interrupts: Interrupt specifier for the controllers interrupt. + +- #gpio-cells: Should be 2. The first cell is the GPIO number and the + second cell is used to specify optional parameters: + bit 0: polarity (0: normal, 1: inverted) + +- gpio-controller: Marks the device as a GPIO controller. + +- interrupt-controller: Marks the device as a interrupt controller. + +The GPIO expander can optionally be used as an interrupt controller, in +which case it uses the default two cell specifier as described in +Documentation/devicetree/bindings/interrupt-controller/interrupts.txt. + +Example: + + i2c_gpio_expander@20{ + #gpio-cells = <2>; + #interrupt-cells = <2>; + compatible = "semtech,sx1506q"; + reg = <0x20>; + interrupt-parent = <&gpio_1>; + interrupts = <16 0>; + + gpio-controller; + interrupt-controller; + }; diff --git a/Documentation/devicetree/bindings/gpio/gpio-vf610.txt b/Documentation/devicetree/bindings/gpio/gpio-vf610.txt new file mode 100644 index 000000000000..436cc99c6598 --- /dev/null +++ b/Documentation/devicetree/bindings/gpio/gpio-vf610.txt @@ -0,0 +1,55 @@ +* Freescale VF610 PORT/GPIO module + +The Freescale PORT/GPIO modules are two adjacent modules providing GPIO +functionality. Each pair serves 32 GPIOs. The VF610 has 5 instances of +each, and each PORT module has its own interrupt. + +Required properties for GPIO node: +- compatible : Should be "fsl,<soc>-gpio", currently "fsl,vf610-gpio" +- reg : The first reg tuple represents the PORT module, the second tuple + the GPIO module. +- interrupts : Should be the port interrupt shared by all 32 pins. +- gpio-controller : Marks the device node as a gpio controller. +- #gpio-cells : Should be two. The first cell is the pin number and + the second cell is used to specify the gpio polarity: + 0 = active high + 1 = active low +- interrupt-controller: Marks the device node as an interrupt controller. +- #interrupt-cells : Should be 2. The first cell is the GPIO number. + The second cell bits[3:0] is used to specify trigger type and level flags: + 1 = low-to-high edge triggered. + 2 = high-to-low edge triggered. + 4 = active high level-sensitive. + 8 = active low level-sensitive. + +Note: Each GPIO port should have an alias correctly numbered in "aliases" +node. + +Examples: + +aliases { + gpio0 = &gpio1; + gpio1 = &gpio2; +}; + +gpio1: gpio@40049000 { + compatible = "fsl,vf610-gpio"; + reg = <0x40049000 0x1000 0x400ff000 0x40>; + interrupts = <0 107 IRQ_TYPE_LEVEL_HIGH>; + gpio-controller; + #gpio-cells = <2>; + interrupt-controller; + #interrupt-cells = <2>; + gpio-ranges = <&iomuxc 0 0 32>; +}; + +gpio2: gpio@4004a000 { + compatible = "fsl,vf610-gpio"; + reg = <0x4004a000 0x1000 0x400ff040 0x40>; + interrupts = <0 108 IRQ_TYPE_LEVEL_HIGH>; + gpio-controller; + #gpio-cells = <2>; + interrupt-controller; + #interrupt-cells = <2>; + gpio-ranges = <&iomuxc 0 32 32>; +}; diff --git a/Documentation/devicetree/bindings/gpio/gpio-xgene-sb.txt b/Documentation/devicetree/bindings/gpio/gpio-xgene-sb.txt new file mode 100644 index 000000000000..dae130060537 --- /dev/null +++ b/Documentation/devicetree/bindings/gpio/gpio-xgene-sb.txt @@ -0,0 +1,32 @@ +APM X-Gene Standby GPIO controller bindings + +This is a gpio controller in the standby domain. + +There are 20 GPIO pins from 0..21. There is no GPIO_DS14 or GPIO_DS15, +only GPIO_DS8..GPIO_DS13 support interrupts. The IRQ mapping +is currently 1-to-1 on interrupts 0x28 thru 0x2d. + +Required properties: +- compatible: "apm,xgene-gpio-sb" for the X-Gene Standby GPIO controller +- reg: Physical base address and size of the controller's registers +- #gpio-cells: Should be two. + - first cell is the pin number + - second cell is used to specify the gpio polarity: + 0 = active high + 1 = active low +- gpio-controller: Marks the device node as a GPIO controller. +- interrupts: Shall contain exactly 6 interrupts. + +Example: + sbgpio: sbgpio@17001000 { + compatible = "apm,xgene-gpio-sb"; + reg = <0x0 0x17001000 0x0 0x400>; + #gpio-cells = <2>; + gpio-controller; + interrupts = <0x0 0x28 0x1>, + <0x0 0x29 0x1>, + <0x0 0x2a 0x1>, + <0x0 0x2b 0x1>, + <0x0 0x2c 0x1>, + <0x0 0x2d 0x1>; + }; diff --git a/Documentation/devicetree/bindings/gpio/gpio.txt b/Documentation/devicetree/bindings/gpio/gpio.txt index 3fb8f53071b8..f7a158d85862 100644 --- a/Documentation/devicetree/bindings/gpio/gpio.txt +++ b/Documentation/devicetree/bindings/gpio/gpio.txt @@ -13,13 +13,22 @@ properties, each containing a 'gpio-list': gpio-specifier : Array of #gpio-cells specifying specific gpio (controller specific) -GPIO properties should be named "[<name>-]gpios". The exact -meaning of each gpios property must be documented in the device tree -binding for each device. +GPIO properties should be named "[<name>-]gpios", with <name> being the purpose +of this GPIO for the device. While a non-existent <name> is considered valid +for compatibility reasons (resolving to the "gpios" property), it is not allowed +for new bindings. -For example, the following could be used to describe GPIO pins used -as chip select lines; with chip selects 0, 1 and 3 populated, and chip -select 2 left empty: +GPIO properties can contain one or more GPIO phandles, but only in exceptional +cases should they contain more than one. If your device uses several GPIOs with +distinct functions, reference each of them under its own property, giving it a +meaningful name. The only case where an array of GPIOs is accepted is when +several GPIOs serve the same function (e.g. a parallel data line). + +The exact purpose of each gpios property must be documented in the device tree +binding of the device. + +The following example could be used to describe GPIO pins used as device enable +and bit-banged data signals: gpio1: gpio1 { gpio-controller @@ -30,10 +39,12 @@ select 2 left empty: #gpio-cells = <1>; }; [...] - chipsel-gpios = <&gpio1 12 0>, - <&gpio1 13 0>, - <0>, /* holes are permitted, means no GPIO 2 */ - <&gpio2 2>; + + enable-gpios = <&gpio2 2>; + data-gpios = <&gpio1 12 0>, + <&gpio1 13 0>, + <&gpio1 14 0>, + <&gpio1 15 0>; Note that gpio-specifier length is controller dependent. In the above example, &gpio1 uses 2 cells to specify a gpio, while &gpio2 @@ -42,22 +53,24 @@ only uses one. gpio-specifier may encode: bank, pin position inside the bank, whether pin is open-drain and whether pin is logically inverted. Exact meaning of each specifier cell is controller specific, and must -be documented in the device tree binding for the device. +be documented in the device tree binding for the device. Use the macros +defined in include/dt-bindings/gpio/gpio.h whenever possible: Example of a node using GPIOs: node { - gpios = <&qe_pio_e 18 0>; + enable-gpios = <&qe_pio_e 18 GPIO_ACTIVE_HIGH>; }; -In this example gpio-specifier is "18 0" and encodes GPIO pin number, -and GPIO flags as accepted by the "qe_pio_e" gpio-controller. +GPIO_ACTIVE_HIGH is 0, so in this example gpio-specifier is "18 0" and encodes +GPIO pin number, and GPIO flags as accepted by the "qe_pio_e" gpio-controller. 1.1) GPIO specifier best practices ---------------------------------- A gpio-specifier should contain a flag indicating the GPIO polarity; active- -high or active-low. If it does, the follow best practices should be followed: +high or active-low. If it does, the following best practices should be +followed: The gpio-specifier's polarity flag should represent the physical level at the GPIO controller that achieves (or represents, for inputs) a logically asserted @@ -135,7 +148,7 @@ contains information structures as follows: numeric-gpio-range ::= <pinctrl-phandle> <gpio-base> <pinctrl-base> <count> named-gpio-range ::= <pinctrl-phandle> <gpio-base> '<0 0>' - gpio-phandle : phandle to pin controller node. + pinctrl-phandle : phandle to pin controller node gpio-base : Base GPIO ID in the GPIO controller pinctrl-base : Base pinctrl pin ID in the pin controller count : The number of GPIOs/pins in this range diff --git a/Documentation/devicetree/bindings/gpio/mrvl-gpio.txt b/Documentation/devicetree/bindings/gpio/mrvl-gpio.txt index b2afdb27adeb..67a2e4e414a5 100644 --- a/Documentation/devicetree/bindings/gpio/mrvl-gpio.txt +++ b/Documentation/devicetree/bindings/gpio/mrvl-gpio.txt @@ -3,8 +3,8 @@ Required properties: - compatible : Should be "intel,pxa25x-gpio", "intel,pxa26x-gpio", "intel,pxa27x-gpio", "intel,pxa3xx-gpio", - "marvell,pxa93x-gpio", "marvell,mmp-gpio" or - "marvell,mmp2-gpio". + "marvell,pxa93x-gpio", "marvell,mmp-gpio", + "marvell,mmp2-gpio" or marvell,pxa1928-gpio. - reg : Address and length of the register set for the device - interrupts : Should be the port interrupt shared by all gpio pins. There're three gpio interrupts in arch-pxa, and they're gpio0, diff --git a/Documentation/devicetree/bindings/gpio/pl061-gpio.txt b/Documentation/devicetree/bindings/gpio/pl061-gpio.txt index a2c416bcbccc..89058d375b7c 100644 --- a/Documentation/devicetree/bindings/gpio/pl061-gpio.txt +++ b/Documentation/devicetree/bindings/gpio/pl061-gpio.txt @@ -7,4 +7,4 @@ Required properties: - bit 0 specifies polarity (0 for normal, 1 for inverted) - gpio-controller : Marks the device node as a GPIO controller. - interrupts : Interrupt mapping for GPIO IRQ. - +- gpio-ranges : Interaction with the PINCTRL subsystem. diff --git a/Documentation/devicetree/bindings/gpio/renesas,gpio-rcar.txt b/Documentation/devicetree/bindings/gpio/renesas,gpio-rcar.txt index 941a26aa4322..38fb86f28ba2 100644 --- a/Documentation/devicetree/bindings/gpio/renesas,gpio-rcar.txt +++ b/Documentation/devicetree/bindings/gpio/renesas,gpio-rcar.txt @@ -6,7 +6,9 @@ Required Properties: - "renesas,gpio-r8a7778": for R8A7778 (R-Mobile M1) compatible GPIO controller. - "renesas,gpio-r8a7779": for R8A7779 (R-Car H1) compatible GPIO controller. - "renesas,gpio-r8a7790": for R8A7790 (R-Car H2) compatible GPIO controller. - - "renesas,gpio-r8a7791": for R8A7791 (R-Car M2) compatible GPIO controller. + - "renesas,gpio-r8a7791": for R8A7791 (R-Car M2-W) compatible GPIO controller. + - "renesas,gpio-r8a7793": for R8A7793 (R-Car M2-N) compatible GPIO controller. + - "renesas,gpio-r8a7794": for R8A7794 (R-Car E2) compatible GPIO controller. - "renesas,gpio-rcar": for generic R-Car GPIO controller. - reg: Base address and length of each memory resource used by the GPIO diff --git a/Documentation/devicetree/bindings/gpu/nvidia,tegra20-host1x.txt b/Documentation/devicetree/bindings/gpu/nvidia,tegra20-host1x.txt index b48f4ef31d93..009f4bfa1590 100644 --- a/Documentation/devicetree/bindings/gpu/nvidia,tegra20-host1x.txt +++ b/Documentation/devicetree/bindings/gpu/nvidia,tegra20-host1x.txt @@ -191,11 +191,15 @@ of the following host1x client modules: - nvidia,hpd-gpio: specifies a GPIO used for hotplug detection - nvidia,edid: supplies a binary EDID blob - nvidia,panel: phandle of a display panel + - nvidia,ganged-mode: contains a phandle to a second DSI controller to gang + up with in order to support up to 8 data lanes - sor: serial output resource Required properties: - - compatible: "nvidia,tegra124-sor" + - compatible: For Tegra124, must contain "nvidia,tegra124-sor". Otherwise, + must contain '"nvidia,<chip>-sor", "nvidia,tegra124-sor"', where <chip> + is tegra132. - reg: Physical base address and length of the controller's registers. - interrupts: The interrupt outputs from the controller. - clocks: Must contain an entry for each entry in clock-names. @@ -220,7 +224,9 @@ of the following host1x client modules: - nvidia,dpaux: phandle to a DispayPort AUX interface - dpaux: DisplayPort AUX interface - - compatible: "nvidia,tegra124-dpaux" + - compatible: For Tegra124, must contain "nvidia,tegra124-dpaux". Otherwise, + must contain '"nvidia,<chip>-dpaux", "nvidia,tegra124-dpaux"', where + <chip> is tegra132. - reg: Physical base address and length of the controller's registers. - interrupts: The interrupt outputs from the controller. - clocks: Must contain an entry for each entry in clock-names. diff --git a/Documentation/devicetree/bindings/gpu/st,stih4xx.txt b/Documentation/devicetree/bindings/gpu/st,stih4xx.txt index 2d150c311a05..6b1d75f1a529 100644 --- a/Documentation/devicetree/bindings/gpu/st,stih4xx.txt +++ b/Documentation/devicetree/bindings/gpu/st,stih4xx.txt @@ -68,7 +68,7 @@ STMicroelectronics stih4xx platforms number of clocks may depend of the SoC type. - clock-names: names of the clocks listed in clocks property in the same order. - - hdmi,hpd-gpio: gpio id to detect if an hdmi cable is plugged or not. + - ddc: phandle of an I2C controller used for DDC EDID probing sti-hda: Required properties: @@ -83,6 +83,38 @@ sti-hda: - clock-names: names of the clocks listed in clocks property in the same order. +sti-dvo: + Required properties: + must be a child of sti-tvout + - compatible: "st,stih<chip>-dvo" + - reg: Physical base address of the IP registers and length of memory mapped region. + - reg-names: names of the mapped memory regions listed in regs property in + the same order. + - clocks: from common clock binding: handle hardware IP needed clocks, the + number of clocks may depend of the SoC type. + See ../clocks/clock-bindings.txt for details. + - clock-names: names of the clocks listed in clocks property in the same + order. + - pinctrl-0: pin control handle + - pinctrl-name: names of the pin control to use + - sti,panel: phandle of the panel connected to the DVO output + +sti-hqvdp: + must be a child of sti-display-subsystem + Required properties: + - compatible: "st,stih<chip>-hqvdp" + - reg: Physical base address of the IP registers and length of memory mapped region. + - clocks: from common clock binding: handle hardware IP needed clocks, the + number of clocks may depend of the SoC type. + See ../clocks/clock-bindings.txt for details. + - clock-names: names of the clocks listed in clocks property in the same + order. + - resets: resets to be used by the device + See ../reset/reset.txt for details. + - reset-names: names of the resets listed in resets property in the same + order. + - st,vtg: phandle on vtg main device node. + Example: / { @@ -173,7 +205,6 @@ Example: interrupt-names = "irq"; clock-names = "pix", "tmds", "phy", "audio"; clocks = <&clockgen_c_vcc CLK_S_PIX_HDMI>, <&clockgen_c_vcc CLK_S_TMDS_HDMI>, <&clockgen_c_vcc CLK_S_HDMI_REJECT_PLL>, <&clockgen_b1 CLK_S_PCM_0>; - hdmi,hpd-gpio = <&PIO2 5>; }; sti-hda@fe85a000 { @@ -183,7 +214,30 @@ Example: clock-names = "pix", "hddac"; clocks = <&clockgen_c_vcc CLK_S_PIX_HD>, <&clockgen_c_vcc CLK_S_HDDAC>; }; + + sti-dvo@8d00400 { + compatible = "st,stih407-dvo"; + reg = <0x8d00400 0x200>; + reg-names = "dvo-reg"; + clock-names = "dvo_pix", "dvo", + "main_parent", "aux_parent"; + clocks = <&clk_s_d2_flexgen CLK_PIX_DVO>, <&clk_s_d2_flexgen CLK_DVO>, + <&clk_s_d2_quadfs 0>, <&clk_s_d2_quadfs 1>; + pinctrl-names = "default"; + pinctrl-0 = <&pinctrl_dvo>; + sti,panel = <&panel_dvo>; + }; }; + + sti-hqvdp@9c000000 { + compatible = "st,stih407-hqvdp"; + reg = <0x9C00000 0x100000>; + clock-names = "hqvdp", "pix_main"; + clocks = <&clk_s_c0_flexgen CLK_MAIN_DISP>, <&clk_s_d2_flexgen CLK_PIX_MAIN_DISP>; + reset-names = "hqvdp"; + resets = <&softreset STIH407_HDQVDP_SOFTRESET>; + st,vtg = <&vtg_main>; + }; }; ... }; diff --git a/Documentation/devicetree/bindings/graph.txt b/Documentation/devicetree/bindings/graph.txt index 1a69c078adf2..fcb1c6a4787b 100644 --- a/Documentation/devicetree/bindings/graph.txt +++ b/Documentation/devicetree/bindings/graph.txt @@ -19,7 +19,7 @@ type of the connections, they just map their existence. Specific properties may be described by specialized bindings depending on the type of connection. To see how this binding applies to video pipelines, for example, see -Documentation/device-tree/bindings/media/video-interfaces.txt. +Documentation/devicetree/bindings/media/video-interfaces.txt. Here the ports describe data interfaces, and the links between them are the connecting data buses. A single port with multiple connections can correspond to multiple devices being connected to the same physical bus. diff --git a/Documentation/devicetree/bindings/hwmon/ltc2978.txt b/Documentation/devicetree/bindings/hwmon/ltc2978.txt new file mode 100644 index 000000000000..ed2f09dc2483 --- /dev/null +++ b/Documentation/devicetree/bindings/hwmon/ltc2978.txt @@ -0,0 +1,39 @@ +ltc2978 + +Required properties: +- compatible: should contain one of: + * "lltc,ltc2974" + * "lltc,ltc2977" + * "lltc,ltc2978" + * "lltc,ltc3880" + * "lltc,ltc3883" + * "lltc,ltm4676" +- reg: I2C slave address + +Optional properties: +- regulators: A node that houses a sub-node for each regulator controlled by + the device. Each sub-node is identified using the node's name, with valid + values listed below. The content of each sub-node is defined by the + standard binding for regulators; see regulator.txt. + +Valid names of regulators depend on number of supplies supported per device: + * ltc2974 : vout0 - vout3 + * ltc2977 : vout0 - vout7 + * ltc2978 : vout0 - vout7 + * ltc3880 : vout0 - vout1 + * ltc3883 : vout0 + * ltm4676 : vout0 - vout1 + +Example: +ltc2978@5e { + compatible = "lltc,ltc2978"; + reg = <0x5e>; + regulators { + vout0 { + regulator-name = "FPGA-2.5V"; + }; + vout2 { + regulator-name = "FPGA-1.5V"; + }; + }; +}; diff --git a/Documentation/devicetree/bindings/hwrng/atmel-trng.txt b/Documentation/devicetree/bindings/hwrng/atmel-trng.txt new file mode 100644 index 000000000000..4ac5aaa2d024 --- /dev/null +++ b/Documentation/devicetree/bindings/hwrng/atmel-trng.txt @@ -0,0 +1,16 @@ +Atmel TRNG (True Random Number Generator) block + +Required properties: +- compatible : Should be "atmel,at91sam9g45-trng" +- reg : Offset and length of the register set of this block +- interrupts : the interrupt number for the TRNG block +- clocks: should contain the TRNG clk source + +Example: + +trng@fffcc000 { + compatible = "atmel,at91sam9g45-trng"; + reg = <0xfffcc000 0x4000>; + interrupts = <6 IRQ_TYPE_LEVEL_HIGH 0>; + clocks = <&trng_clk>; +}; diff --git a/Documentation/devicetree/bindings/i2c/i2c-designware.txt b/Documentation/devicetree/bindings/i2c/i2c-designware.txt index 5199b0c8cf7a..fee26dc3e858 100644 --- a/Documentation/devicetree/bindings/i2c/i2c-designware.txt +++ b/Documentation/devicetree/bindings/i2c/i2c-designware.txt @@ -14,10 +14,10 @@ Optional properties : - i2c-sda-hold-time-ns : should contain the SDA hold time in nanoseconds. This option is only supported in hardware blocks version 1.11a or newer. - - i2c-scl-falling-time : should contain the SCL falling time in nanoseconds. + - i2c-scl-falling-time-ns : should contain the SCL falling time in nanoseconds. This value which is by default 300ns is used to compute the tLOW period. - - i2c-sda-falling-time : should contain the SDA falling time in nanoseconds. + - i2c-sda-falling-time-ns : should contain the SDA falling time in nanoseconds. This value which is by default 300ns is used to compute the tHIGH period. Example : diff --git a/Documentation/devicetree/bindings/i2c/i2c-img-scb.txt b/Documentation/devicetree/bindings/i2c/i2c-img-scb.txt new file mode 100644 index 000000000000..b6461602dca5 --- /dev/null +++ b/Documentation/devicetree/bindings/i2c/i2c-img-scb.txt @@ -0,0 +1,26 @@ +IMG Serial Control Bus (SCB) I2C Controller + +Required Properties: +- compatible: "img,scb-i2c" +- reg: Physical base address and length of controller registers +- interrupts: Interrupt number used by the controller +- clocks : Should contain a clock specifier for each entry in clock-names +- clock-names : Should contain the following entries: + "scb", for the SCB core clock. + "sys", for the system clock. +- clock-frequency: The I2C bus frequency in Hz +- #address-cells: Should be <1> +- #size-cells: Should be <0> + +Example: + +i2c@18100000 { + compatible = "img,scb-i2c"; + reg = <0x18100000 0x200>; + interrupts = <GIC_SHARED 2 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&i2c0_clk>, <&system_clk>; + clock-names = "scb", "sys"; + clock-frequency = <400000>; + #address-cells = <1>; + #size-cells = <0>; +}; diff --git a/Documentation/devicetree/bindings/i2c/i2c-imx.txt b/Documentation/devicetree/bindings/i2c/i2c-imx.txt index 4a8513e44740..52d37fd8d3e5 100644 --- a/Documentation/devicetree/bindings/i2c/i2c-imx.txt +++ b/Documentation/devicetree/bindings/i2c/i2c-imx.txt @@ -11,6 +11,8 @@ Required properties: Optional properties: - clock-frequency : Constains desired I2C/HS-I2C bus clock frequency in Hz. The absence of the propoerty indicates the default frequency 100 kHz. +- dmas: A list of two dma specifiers, one for each entry in dma-names. +- dma-names: should contain "tx" and "rx". Examples: @@ -26,3 +28,12 @@ i2c@70038000 { /* HS-I2C on i.MX51 */ interrupts = <64>; clock-frequency = <400000>; }; + +i2c0: i2c@40066000 { /* i2c0 on vf610 */ + compatible = "fsl,vf610-i2c"; + reg = <0x40066000 0x1000>; + interrupts =<0 71 0x04>; + dmas = <&edma0 0 50>, + <&edma0 0 51>; + dma-names = "rx","tx"; +}; diff --git a/Documentation/devicetree/bindings/i2c/i2c-meson.txt b/Documentation/devicetree/bindings/i2c/i2c-meson.txt new file mode 100644 index 000000000000..682f9a6f766e --- /dev/null +++ b/Documentation/devicetree/bindings/i2c/i2c-meson.txt @@ -0,0 +1,24 @@ +Amlogic Meson I2C controller + +Required properties: + - compatible: must be "amlogic,meson6-i2c" + - reg: physical address and length of the device registers + - interrupts: a single interrupt specifier + - clocks: clock for the device + - #address-cells: should be <1> + - #size-cells: should be <0> + +Optional properties: +- clock-frequency: the desired I2C bus clock frequency in Hz; in + absence of this property the default value is used (100 kHz). + +Examples: + + i2c@c8100500 { + compatible = "amlogic,meson6-i2c"; + reg = <0xc8100500 0x20>; + interrupts = <0 92 1>; + clocks = <&clk81>; + #address-cells = <1>; + #size-cells = <0>; + }; diff --git a/Documentation/devicetree/bindings/i2c/i2c-opal.txt b/Documentation/devicetree/bindings/i2c/i2c-opal.txt new file mode 100644 index 000000000000..12bc61465ee5 --- /dev/null +++ b/Documentation/devicetree/bindings/i2c/i2c-opal.txt @@ -0,0 +1,37 @@ +Device-tree bindings for I2C OPAL driver +---------------------------------------- + +Most of the device node and properties layout is specific to the firmware and +used by the firmware itself for configuring the port. From the linux +perspective, the properties of use are "ibm,port-name" and "ibm,opal-id". + +Required properties: + +- reg: Port-id within a given master +- compatible: must be "ibm,opal-i2c" +- ibm,opal-id: Refers to a specific bus and used to identify it when calling + the relevant OPAL functions. +- bus-frequency: Operating frequency of the i2c bus (in HZ). Informational for + linux, used by the FW though. + +Optional properties: +- ibm,port-name: Firmware provides this name that uniquely identifies the i2c + port. + +The node contains a number of other properties that are used by the FW itself +and depend on the specific hardware implementation. The example below depicts +a P8 on-chip bus. + +Example: + +i2c-bus@0 { + reg = <0x0>; + bus-frequency = <0x61a80>; + compatible = "ibm,power8-i2c-port", "ibm,opal-i2c"; + ibm,opal-id = <0x1>; + ibm,port-name = "p8_00000000_e1p0"; + #address-cells = <0x1>; + phandle = <0x10000006>; + #size-cells = <0x0>; + linux,phandle = <0x10000006>; +}; diff --git a/Documentation/devicetree/bindings/i2c/i2c-s3c2410.txt b/Documentation/devicetree/bindings/i2c/i2c-s3c2410.txt index 278de8e64bbf..89b3250f049b 100644 --- a/Documentation/devicetree/bindings/i2c/i2c-s3c2410.txt +++ b/Documentation/devicetree/bindings/i2c/i2c-s3c2410.txt @@ -32,6 +32,7 @@ Optional properties: specified, default value is 0. - samsung,i2c-max-bus-freq: Desired frequency in Hz of the bus. If not specified, the default value in Hz is 100000. + - samsung,sysreg-phandle - handle to syscon used to control the system registers Example: diff --git a/Documentation/devicetree/bindings/i2c/i2c-sh_mobile.txt b/Documentation/devicetree/bindings/i2c/i2c-sh_mobile.txt index d2153ce36fa8..2bfc6e7ed094 100644 --- a/Documentation/devicetree/bindings/i2c/i2c-sh_mobile.txt +++ b/Documentation/devicetree/bindings/i2c/i2c-sh_mobile.txt @@ -2,6 +2,15 @@ Device tree configuration for Renesas IIC (sh_mobile) driver Required properties: - compatible : "renesas,iic-<soctype>". "renesas,rmobile-iic" as fallback + Examples with soctypes are: + - "renesas,iic-r8a73a4" (R-Mobile APE6) + - "renesas,iic-r8a7740" (R-Mobile A1) + - "renesas,iic-r8a7790" (R-Car H2) + - "renesas,iic-r8a7791" (R-Car M2-W) + - "renesas,iic-r8a7792" (R-Car V2H) + - "renesas,iic-r8a7793" (R-Car M2-N) + - "renesas,iic-r8a7794" (R-Car E2) + - "renesas,iic-sh73a0" (SH-Mobile AG5) - reg : address start and address range size of device - interrupts : interrupt of device - clocks : clock for device @@ -10,6 +19,11 @@ Required properties: Optional properties: - clock-frequency : frequency of bus clock in Hz. Default 100kHz if unset. +- dmas : Must contain a list of two references to DMA + specifiers, one for transmission, and one for + reception. +- dma-names : Must contain a list of two DMA names, "tx" and "rx". + Pinctrl properties might be needed, too. See there. diff --git a/Documentation/devicetree/bindings/i2c/i2c-st.txt b/Documentation/devicetree/bindings/i2c/i2c-st.txt index 437e0db3823c..4c26fda3844a 100644 --- a/Documentation/devicetree/bindings/i2c/i2c-st.txt +++ b/Documentation/devicetree/bindings/i2c/i2c-st.txt @@ -31,7 +31,7 @@ i2c0: i2c@fed40000 { compatible = "st,comms-ssc4-i2c"; reg = <0xfed40000 0x110>; interrupts = <GIC_SPI 187 IRQ_TYPE_LEVEL_HIGH>; - clocks = <&CLK_S_ICN_REG_0>; + clocks = <&clk_s_a0_ls CLK_ICN_REG>; clock-names = "ssc"; clock-frequency = <400000>; pinctrl-names = "default"; diff --git a/Documentation/devicetree/bindings/i2c/nvidia,tegra20-i2c.txt b/Documentation/devicetree/bindings/i2c/nvidia,tegra20-i2c.txt index 87507e9ce6db..656716b72cc4 100644 --- a/Documentation/devicetree/bindings/i2c/nvidia,tegra20-i2c.txt +++ b/Documentation/devicetree/bindings/i2c/nvidia,tegra20-i2c.txt @@ -1,11 +1,11 @@ NVIDIA Tegra20/Tegra30/Tegra114 I2C controller driver. Required properties: -- compatible : should be: - "nvidia,tegra114-i2c" - "nvidia,tegra30-i2c" - "nvidia,tegra20-i2c" - "nvidia,tegra20-i2c-dvc" +- compatible : For Tegra20, must be one of "nvidia,tegra20-i2c-dvc" or + "nvidia,tegra20-i2c". For Tegra30, must be "nvidia,tegra30-i2c". + For Tegra114, must be "nvidia,tegra114-i2c". Otherwise, must be + "nvidia,<chip>-i2c", plus at least one of the above, where <chip> is + tegra124, tegra132, or tegra210. Details of compatible are as follows: nvidia,tegra20-i2c-dvc: Tegra20 has specific I2C controller called as DVC I2C controller. This only support master mode of I2C communication. Register diff --git a/Documentation/devicetree/bindings/i2c/trivial-devices.txt b/Documentation/devicetree/bindings/i2c/trivial-devices.txt index fbde415078e6..4dcd88d5f7ca 100644 --- a/Documentation/devicetree/bindings/i2c/trivial-devices.txt +++ b/Documentation/devicetree/bindings/i2c/trivial-devices.txt @@ -9,6 +9,7 @@ document for it just like any other devices. Compatible Vendor / Chip ========== ============= +abracon,abb5zes3 AB-RTCMC-32.768kHz-B5ZE-S3: Real Time Clock/Calendar Module with I2C Interface ad,ad7414 SMBus/I2C Digital Temperature Sensor in 6-Pin SOT with SMBus Alert and Over Temperature Pin ad,adm9240 ADM9240: Complete System Hardware Monitor for uProcessor-Based Systems adi,adt7461 +/-1C TDM Extended Temp Range I.C @@ -17,6 +18,9 @@ adi,adt7473 +/-1C TDM Extended Temp Range I.C adi,adt7475 +/-1C TDM Extended Temp Range I.C adi,adt7476 +/-1C TDM Extended Temp Range I.C adi,adt7490 +/-1C TDM Extended Temp Range I.C +adi,adxl345 Three-Axis Digital Accelerometer +adi,adxl346 Three-Axis Digital Accelerometer +adi,adxl34x Three-Axis Digital Accelerometer at,24c08 i2c serial eeprom (24cxx) atmel,24c00 i2c serial eeprom (24cxx) atmel,24c01 i2c serial eeprom (24cxx) @@ -31,6 +35,7 @@ atmel,24c512 i2c serial eeprom (24cxx) atmel,24c1024 i2c serial eeprom (24cxx) atmel,at97sc3204t i2c trusted platform module (TPM) capella,cm32181 CM32181: Ambient Light Sensor +capella,cm3232 CM3232: Ambient Light Sensor catalyst,24c32 i2c serial eeprom cirrus,cs42l51 Cirrus Logic CS42L51 audio codec dallas,ds1307 64 x 8, Serial, I2C Real-Time Clock @@ -44,6 +49,7 @@ dallas,ds3232 Extremely Accurate I²C RTC with Integrated Crystal and SRAM dallas,ds4510 CPU Supervisor with Nonvolatile Memory and Programmable I/O dallas,ds75 Digital Thermometer and Thermostat dlg,da9053 DA9053: flexible system level PMIC with multicore support +dlg,da9063 DA9063: system PMIC for quad-core application processors epson,rx8025 High-Stability. I2C-Bus INTERFACE REAL TIME CLOCK MODULE epson,rx8581 I2C-BUS INTERFACE REAL TIME CLOCK MODULE fsl,mag3110 MAG3110: Xtrinsic High Accuracy, 3D Magnetometer @@ -56,6 +62,8 @@ gmt,g751 G751: Digital Temperature Sensor and Thermal Watchdog with Two-Wire In infineon,slb9635tt Infineon SLB9635 (Soft-) I2C TPM (old protocol, max 100khz) infineon,slb9645tt Infineon SLB9645 I2C TPM (new protocol, max 400khz) isl,isl12057 Intersil ISL12057 I2C RTC Chip +isil,isl29028 (deprecated, use isl) +isl,isl29028 Intersil ISL29028 Ambient Light and Proximity Sensor maxim,ds1050 5 Bit Programmable, Pulse-Width Modulator maxim,max1237 Low-Power, 4-/12-Channel, 2-Wire Serial, 12-Bit ADCs maxim,max6625 9-Bit/12-Bit Temperature Sensors with I²C-Compatible Serial Interface @@ -74,7 +82,12 @@ ovti,ov5642 OV5642: Color CMOS QSXGA (5-megapixel) Image Sensor with OmniBSI an pericom,pt7c4338 Real-time Clock Module plx,pex8648 48-Lane, 12-Port PCI Express Gen 2 (5.0 GT/s) Switch ramtron,24c64 i2c serial eeprom (24cxx) +ricoh,r2025sd I2C bus SERIAL INTERFACE REAL-TIME CLOCK IC +ricoh,r2221tl I2C bus SERIAL INTERFACE REAL-TIME CLOCK IC ricoh,rs5c372a I2C bus SERIAL INTERFACE REAL-TIME CLOCK IC +ricoh,rs5c372b I2C bus SERIAL INTERFACE REAL-TIME CLOCK IC +ricoh,rv5c386 I2C bus SERIAL INTERFACE REAL-TIME CLOCK IC +ricoh,rv5c387a I2C bus SERIAL INTERFACE REAL-TIME CLOCK IC samsung,24ad0xd1 S524AD0XF1 (128K/256K-bit Serial EEPROM for Low Power) sii,s35390a 2-wire CMOS real-time clock st-micro,24c256 i2c serial eeprom (24cxx) diff --git a/Documentation/devicetree/bindings/iio/adc/cc10001_adc.txt b/Documentation/devicetree/bindings/iio/adc/cc10001_adc.txt new file mode 100644 index 000000000000..904f76de9055 --- /dev/null +++ b/Documentation/devicetree/bindings/iio/adc/cc10001_adc.txt @@ -0,0 +1,22 @@ +* Cosmic Circuits - Analog to Digital Converter (CC-10001-ADC) + +Required properties: + - compatible: Should be "cosmic,10001-adc" + - reg: Should contain adc registers location and length. + - clock-names: Should contain "adc". + - clocks: Should contain a clock specifier for each entry in clock-names + - vref-supply: The regulator supply ADC reference voltage. + +Optional properties: + - adc-reserved-channels: Bitmask of reserved channels, + i.e. channels that cannot be used by the OS. + +Example: +adc: adc@18101600 { + compatible = "cosmic,10001-adc"; + reg = <0x18101600 0x24>; + adc-reserved-channels = <0x2>; + clocks = <&adc_clk>; + clock-names = "adc"; + vref-supply = <®_1v8>; +}; diff --git a/Documentation/devicetree/bindings/iio/adc/qcom,spmi-iadc.txt b/Documentation/devicetree/bindings/iio/adc/qcom,spmi-iadc.txt new file mode 100644 index 000000000000..4e36d6e2f7b6 --- /dev/null +++ b/Documentation/devicetree/bindings/iio/adc/qcom,spmi-iadc.txt @@ -0,0 +1,46 @@ +Qualcomm's SPMI PMIC current ADC + +QPNP PMIC current ADC (IADC) provides interface to clients to read current. +A 16 bit ADC is used for current measurements. IADC can measure the current +through an external resistor (channel 1) or internal (built-in) resistor +(channel 0). When using an external resistor it is to be described by +qcom,external-resistor-micro-ohms property. + +IADC node: + +- compatible: + Usage: required + Value type: <string> + Definition: Should contain "qcom,spmi-iadc". + +- reg: + Usage: required + Value type: <prop-encoded-array> + Definition: IADC base address and length in the SPMI PMIC register map + +- interrupts: + Usage: optional + Value type: <prop-encoded-array> + Definition: End of ADC conversion. + +- qcom,external-resistor-micro-ohms: + Usage: optional + Value type: <u32> + Definition: Sense resister value in micro Ohm. + If not defined value of 10000 micro Ohms will be used. + +Example: + /* IADC node */ + pmic_iadc: iadc@3600 { + compatible = "qcom,spmi-iadc"; + reg = <0x3600 0x100>; + interrupts = <0x0 0x36 0x0 IRQ_TYPE_EDGE_RISING>; + qcom,external-resistor-micro-ohms = <10000>; + #io-channel-cells = <1>; + }; + + /* IIO client node */ + bat { + io-channels = <&pmic_iadc 0>; + io-channel-names = "iadc"; + }; diff --git a/Documentation/devicetree/bindings/iio/adc/qcom,spmi-vadc.txt b/Documentation/devicetree/bindings/iio/adc/qcom,spmi-vadc.txt new file mode 100644 index 000000000000..0fb46137f936 --- /dev/null +++ b/Documentation/devicetree/bindings/iio/adc/qcom,spmi-vadc.txt @@ -0,0 +1,129 @@ +Qualcomm's SPMI PMIC voltage ADC + +SPMI PMIC voltage ADC (VADC) provides interface to clients to read +voltage. The VADC is a 15-bit sigma-delta ADC. + +VADC node: + +- compatible: + Usage: required + Value type: <string> + Definition: Should contain "qcom,spmi-vadc". + +- reg: + Usage: required + Value type: <prop-encoded-array> + Definition: VADC base address and length in the SPMI PMIC register map. + +- #address-cells: + Usage: required + Value type: <u32> + Definition: Must be one. Child node 'reg' property should define ADC + channel number. + +- #size-cells: + Usage: required + Value type: <u32> + Definition: Must be zero. + +- #io-channel-cells: + Usage: required + Value type: <u32> + Definition: Must be one. For details about IIO bindings see: + Documentation/devicetree/bindings/iio/iio-bindings.txt + +- interrupts: + Usage: optional + Value type: <prop-encoded-array> + Definition: End of conversion interrupt. + +Channel node properties: + +- reg: + Usage: required + Value type: <u32> + Definition: ADC channel number. + See include/dt-bindings/iio/qcom,spmi-vadc.h + +- qcom,decimation: + Usage: optional + Value type: <u32> + Definition: This parameter is used to decrease ADC sampling rate. + Quicker measurements can be made by reducing decimation ratio. + Valid values are 512, 1024, 2048, 4096. + If property is not found, default value of 512 will be used. + +- qcom,pre-scaling: + Usage: optional + Value type: <u32 array> + Definition: Used for scaling the channel input signal before the signal is + fed to VADC. The configuration for this node is to know the + pre-determined ratio and use it for post scaling. Select one from + the following options. + <1 1>, <1 3>, <1 4>, <1 6>, <1 20>, <1 8>, <10 81>, <1 10> + If property is not found default value depending on chip will be used. + +- qcom,ratiometric: + Usage: optional + Value type: <empty> + Definition: Channel calibration type. If this property is specified + VADC will use the VDD reference (1.8V) and GND for channel + calibration. If property is not found, channel will be + calibrated with 0.625V and 1.25V reference channels, also + known as absolute calibration. + +- qcom,hw-settle-time: + Usage: optional + Value type: <u32> + Definition: Time between AMUX getting configured and the ADC starting + conversion. Delay = 100us * (value) for value < 11, and + 2ms * (value - 10) otherwise. + Valid values are: 0, 100, 200, 300, 400, 500, 600, 700, 800, + 900 us and 1, 2, 4, 6, 8, 10 ms + If property is not found, channel will use 0us. + +- qcom,avg-samples: + Usage: optional + Value type: <u32> + Definition: Number of samples to be used for measurement. + Averaging provides the option to obtain a single measurement + from the ADC that is an average of multiple samples. The value + selected is 2^(value). + Valid values are: 1, 2, 4, 8, 16, 32, 64, 128, 256, 512 + If property is not found, 1 sample will be used. + +NOTE: + +Following channels, also known as reference point channels, are used for +result calibration and their channel configuration nodes should be defined: +VADC_REF_625MV and/or VADC_SPARE1(based on PMIC version) VADC_REF_1250MV, +VADC_GND_REF and VADC_VDD_VADC. + +Example: + + /* VADC node */ + pmic_vadc: vadc@3100 { + compatible = "qcom,spmi-vadc"; + reg = <0x3100 0x100>; + interrupts = <0x0 0x31 0x0 IRQ_TYPE_EDGE_RISING>; + #address-cells = <1>; + #size-cells = <0>; + #io-channel-cells = <1>; + io-channel-ranges; + + /* Channel node */ + usb_id_nopull { + reg = <VADC_LR_MUX10_USB_ID>; + qcom,decimation = <512>; + qcom,ratiometric; + qcom,hw-settle-time = <200>; + qcom,avg-samples = <1>; + qcom,pre-scaling = <1 3>; + }; + }; + + /* IIO client node */ + usb { + io-channels = <&pmic_vadc VADC_LR_MUX10_USB_ID>; + io-channel-names = "vadc"; + }; diff --git a/Documentation/devicetree/bindings/iio/adc/rockchip-saradc.txt b/Documentation/devicetree/bindings/iio/adc/rockchip-saradc.txt index 5d3ec1df226d..a9a5fe19ff2a 100644 --- a/Documentation/devicetree/bindings/iio/adc/rockchip-saradc.txt +++ b/Documentation/devicetree/bindings/iio/adc/rockchip-saradc.txt @@ -1,7 +1,7 @@ Rockchip Successive Approximation Register (SAR) A/D Converter bindings Required properties: -- compatible: Should be "rockchip,saradc" +- compatible: Should be "rockchip,saradc" or "rockchip,rk3066-tsadc" - reg: physical base address of the controller and length of memory mapped region. - interrupts: The interrupt number to the cpu. The interrupt specifier format diff --git a/Documentation/devicetree/bindings/iio/adc/xilinx-xadc.txt b/Documentation/devicetree/bindings/iio/adc/xilinx-xadc.txt index d9ee909d2b78..d71258e2d456 100644 --- a/Documentation/devicetree/bindings/iio/adc/xilinx-xadc.txt +++ b/Documentation/devicetree/bindings/iio/adc/xilinx-xadc.txt @@ -59,7 +59,7 @@ Optional properties: Each child node represents one channel and has the following properties: Required properties: - * reg: Pair of pins the the channel is connected to. + * reg: Pair of pins the channel is connected to. 0: VP/VN 1: VAUXP[0]/VAUXN[0] 2: VAUXP[1]/VAUXN[1] diff --git a/Documentation/devicetree/bindings/iio/sensorhub.txt b/Documentation/devicetree/bindings/iio/sensorhub.txt new file mode 100644 index 000000000000..8d57571d5c0b --- /dev/null +++ b/Documentation/devicetree/bindings/iio/sensorhub.txt @@ -0,0 +1,25 @@ +Samsung Sensorhub driver + +Sensorhub is a MCU which manages several sensors and also plays the role +of a virtual sensor device. + +Required properties: +- compatible: "samsung,sensorhub-rinato" or "samsung,sensorhub-thermostat" +- spi-max-frequency: max SPI clock frequency +- interrupt-parent: interrupt parent +- interrupts: communication interrupt +- ap-mcu-gpios: [out] ap to sensorhub line - used during communication +- mcu-ap-gpios: [in] sensorhub to ap - used during communication +- mcu-reset-gpios: [out] sensorhub reset + +Example: + + shub_spi: shub { + compatible = "samsung,sensorhub-rinato"; + spi-max-frequency = <5000000>; + interrupt-parent = <&gpx0>; + interrupts = <2 0>; + ap-mcu-gpios = <&gpx0 0 0>; + mcu-ap-gpios = <&gpx0 4 0>; + mcu-reset-gpios = <&gpx0 5 0>; + }; diff --git a/Documentation/devicetree/bindings/input/cap1106.txt b/Documentation/devicetree/bindings/input/cap11xx.txt index 4b463904cba0..7d0a3009771b 100644 --- a/Documentation/devicetree/bindings/input/cap1106.txt +++ b/Documentation/devicetree/bindings/input/cap11xx.txt @@ -1,14 +1,16 @@ -Device tree bindings for Microchip CAP1106, 6 channel capacitive touch sensor +Device tree bindings for Microchip CAP11xx based capacitive touch sensors -The node for this driver must be a child of a I2C controller node, as the +The node for this device must be a child of a I2C controller node, as the device communication via I2C only. Required properties: - compatible: Must be "microchip,cap1106" + compatible: Must contain one of: + "microchip,cap1106" + "microchip,cap1126" + "microchip,cap1188" reg: The I2C slave address of the device. - Only 0x28 is valid. interrupts: Property describing the interrupt line the device's ALERT#/CM_IRQ# pin is connected to. @@ -26,6 +28,10 @@ Optional properties: Valid values are 1, 2, 4, and 8. By default, a gain of 1 is set. + microchip,irq-active-high: By default the interrupt pin is active low + open drain. This property allows using the active + high push-pull output. + linux,keycodes: Specifies an array of numeric keycode values to be used for the channels. If this property is omitted, KEY_A, KEY_B, etc are used as @@ -43,11 +49,11 @@ i2c_controller { autorepeat; microchip,sensor-gain = <2>; - linux,keycodes = <103 /* KEY_UP */ - 106 /* KEY_RIGHT */ - 108 /* KEY_DOWN */ - 105 /* KEY_LEFT */ - 109 /* KEY_PAGEDOWN */ - 104>; /* KEY_PAGEUP */ + linux,keycodes = <103>, /* KEY_UP */ + <106>, /* KEY_RIGHT */ + <108>, /* KEY_DOWN */ + <105>, /* KEY_LEFT */ + <109>, /* KEY_PAGEDOWN */ + <104>; /* KEY_PAGEUP */ }; } diff --git a/Documentation/devicetree/bindings/input/e3x0-button.txt b/Documentation/devicetree/bindings/input/e3x0-button.txt new file mode 100644 index 000000000000..751665e8e47a --- /dev/null +++ b/Documentation/devicetree/bindings/input/e3x0-button.txt @@ -0,0 +1,25 @@ +National Instruments Ettus Research USRP E3x0 button driver + +This module is part of the NI Ettus Research USRP E3x0 SDR. + +This module provides a simple power button event via two interrupts. + +Required properties: +- compatible: should be one of the following + - "ettus,e3x0-button": For devices such as the NI Ettus Research USRP E3x0 +- interrupt-parent: + - a phandle to the interrupt controller that it is attached to. +- interrupts: should be one of the following + - <0 30 1>, <0 31 1>: For devices such as the NI Ettus Research USRP E3x0 +- interrupt-names: should be one of the following + - "press", "release": For devices such as the NI Ettus Research USRP E3x0 + +Note: Interrupt numbers might vary depending on the FPGA configuration. + +Example: + button { + compatible = "ettus,e3x0-button"; + interrupt-parent = <&intc>; + interrupts = <0 30 1>, <0 31 1>; + interrupt-names = "press", "release"; + } diff --git a/Documentation/devicetree/bindings/input/elan_i2c.txt b/Documentation/devicetree/bindings/input/elan_i2c.txt new file mode 100644 index 000000000000..ee3242c4ba67 --- /dev/null +++ b/Documentation/devicetree/bindings/input/elan_i2c.txt @@ -0,0 +1,34 @@ +Elantech I2C Touchpad + +Required properties: +- compatible: must be "elan,ekth3000". +- reg: I2C address of the chip. +- interrupt-parent: a phandle for the interrupt controller (see interrupt + binding[0]). +- interrupts: interrupt to which the chip is connected (see interrupt + binding[0]). + +Optional properties: +- wakeup-source: touchpad can be used as a wakeup source. +- pinctrl-names: should be "default" (see pinctrl binding [1]). +- pinctrl-0: a phandle pointing to the pin settings for the device (see + pinctrl binding [1]). +- vcc-supply: a phandle for the regulator supplying 3.3V power. + +[0]: Documentation/devicetree/bindings/interrupt-controller/interrupts.txt +[1]: Documentation/devicetree/bindings/pinctrl/pinctrl-bindings.txt + +Example: + &i2c1 { + /* ... */ + + touchpad@15 { + compatible = "elan,ekth3000"; + reg = <0x15>; + interrupt-parent = <&gpio4>; + interrupts = <0x0 IRQ_TYPE_EDGE_FALLING>; + wakeup-source; + }; + + /* ... */ + }; diff --git a/Documentation/devicetree/bindings/input/elants_i2c.txt b/Documentation/devicetree/bindings/input/elants_i2c.txt new file mode 100644 index 000000000000..a765232e6446 --- /dev/null +++ b/Documentation/devicetree/bindings/input/elants_i2c.txt @@ -0,0 +1,33 @@ +Elantech I2C Touchscreen + +Required properties: +- compatible: must be "elan,ekth3500". +- reg: I2C address of the chip. +- interrupt-parent: a phandle for the interrupt controller (see interrupt + binding[0]). +- interrupts: interrupt to which the chip is connected (see interrupt + binding[0]). + +Optional properties: +- wakeup-source: touchscreen can be used as a wakeup source. +- pinctrl-names: should be "default" (see pinctrl binding [1]). +- pinctrl-0: a phandle pointing to the pin settings for the device (see + pinctrl binding [1]). + +[0]: Documentation/devicetree/bindings/interrupt-controller/interrupts.txt +[1]: Documentation/devicetree/bindings/pinctrl/pinctrl-bindings.txt + +Example: + &i2c1 { + /* ... */ + + touchscreen@10 { + compatible = "elan,ekth3500"; + reg = <0x10>; + interrupt-parent = <&gpio4>; + interrupts = <0x0 IRQ_TYPE_EDGE_FALLING>; + wakeup-source; + }; + + /* ... */ + }; diff --git a/Documentation/devicetree/bindings/input/gpio-keys.txt b/Documentation/devicetree/bindings/input/gpio-keys.txt index 5c2c02140a62..44b705767aca 100644 --- a/Documentation/devicetree/bindings/input/gpio-keys.txt +++ b/Documentation/devicetree/bindings/input/gpio-keys.txt @@ -11,15 +11,22 @@ Each button (key) is represented as a sub-node of "gpio-keys": Subnode properties: - gpios: OF device-tree gpio specification. + - interrupts: the interrupt line for that input. - label: Descriptive name of the key. - linux,code: Keycode to emit. +Note that either "interrupts" or "gpios" properties can be omitted, but not +both at the same time. Specifying both properties is allowed. + Optional subnode-properties: - linux,input-type: Specify event type this button/key generates. If not specified defaults to <1> == EV_KEY. - debounce-interval: Debouncing interval time in milliseconds. If not specified defaults to 5. - gpio-key,wakeup: Boolean, button can wake-up the system. + - linux,can-disable: Boolean, indicates that button is connected + to dedicated (not shared) interrupt which can be disabled to + suppress events from the button. Example nodes: @@ -33,4 +40,9 @@ Example nodes: linux,code = <103>; gpios = <&gpio1 0 1>; }; + button@22 { + label = "GPIO Key DOWN"; + linux,code = <108>; + interrupts = <1 IRQ_TYPE_LEVEL_HIGH 7>; + }; ... diff --git a/Documentation/devicetree/bindings/input/regulator-haptic.txt b/Documentation/devicetree/bindings/input/regulator-haptic.txt new file mode 100644 index 000000000000..3ed1c7eb2f97 --- /dev/null +++ b/Documentation/devicetree/bindings/input/regulator-haptic.txt @@ -0,0 +1,21 @@ +* Regulator Haptic Device Tree Bindings + +Required Properties: + - compatible : Should be "regulator-haptic" + - haptic-supply : Power supply to the haptic motor. + [*] refer Documentation/devicetree/bindings/regulator/regulator.txt + + - max-microvolt : The maximum voltage value supplied to the haptic motor. + [The unit of the voltage is a micro] + + - min-microvolt : The minimum voltage value supplied to the haptic motor. + [The unit of the voltage is a micro] + +Example: + + haptics { + compatible = "regulator-haptic"; + haptic-supply = <&motor_regulator>; + max-microvolt = <2700000>; + min-microvolt = <1100000>; + }; diff --git a/Documentation/devicetree/bindings/input/stmpe-keypad.txt b/Documentation/devicetree/bindings/input/stmpe-keypad.txt index 1b97222e8a0b..12bb771d66d4 100644 --- a/Documentation/devicetree/bindings/input/stmpe-keypad.txt +++ b/Documentation/devicetree/bindings/input/stmpe-keypad.txt @@ -8,6 +8,8 @@ Optional properties: - debounce-interval : Debouncing interval time in milliseconds - st,scan-count : Scanning cycles elapsed before key data is updated - st,no-autorepeat : If specified device will not autorepeat + - keypad,num-rows : See ./matrix-keymap.txt + - keypad,num-columns : See ./matrix-keymap.txt Example: diff --git a/Documentation/devicetree/bindings/input/sun4i-lradc-keys.txt b/Documentation/devicetree/bindings/input/sun4i-lradc-keys.txt new file mode 100644 index 000000000000..b9c32f6fd687 --- /dev/null +++ b/Documentation/devicetree/bindings/input/sun4i-lradc-keys.txt @@ -0,0 +1,62 @@ +Allwinner sun4i low res adc attached tablet keys +------------------------------------------------ + +Required properties: + - compatible: "allwinner,sun4i-a10-lradc-keys" + - reg: mmio address range of the chip + - interrupts: interrupt to which the chip is connected + - vref-supply: powersupply for the lradc reference voltage + +Each key is represented as a sub-node of "allwinner,sun4i-a10-lradc-keys": + +Required subnode-properties: + - label: Descriptive name of the key. + - linux,code: Keycode to emit. + - channel: Channel this key is attached to, mut be 0 or 1. + - voltage: Voltage in µV at lradc input when this key is pressed. + +Example: + +#include <dt-bindings/input/input.h> + + lradc: lradc@01c22800 { + compatible = "allwinner,sun4i-a10-lradc-keys"; + reg = <0x01c22800 0x100>; + interrupts = <31>; + vref-supply = <®_vcc3v0>; + + button@191 { + label = "Volume Up"; + linux,code = <KEY_VOLUMEUP>; + channel = <0>; + voltage = <191274>; + }; + + button@392 { + label = "Volume Down"; + linux,code = <KEY_VOLUMEDOWN>; + channel = <0>; + voltage = <392644>; + }; + + button@601 { + label = "Menu"; + linux,code = <KEY_MENU>; + channel = <0>; + voltage = <601151>; + }; + + button@795 { + label = "Enter"; + linux,code = <KEY_ENTER>; + channel = <0>; + voltage = <795090>; + }; + + button@987 { + label = "Home"; + linux,code = <KEY_HOMEPAGE>; + channel = <0>; + voltage = <987387>; + }; + }; diff --git a/Documentation/devicetree/bindings/input/touchscreen/sun4i.txt b/Documentation/devicetree/bindings/input/touchscreen/sun4i.txt index aef57791f40b..433332d3b2ba 100644 --- a/Documentation/devicetree/bindings/input/touchscreen/sun4i.txt +++ b/Documentation/devicetree/bindings/input/touchscreen/sun4i.txt @@ -2,9 +2,10 @@ sun4i resistive touchscreen controller -------------------------------------- Required properties: - - compatible: "allwinner,sun4i-a10-ts" + - compatible: "allwinner,sun4i-a10-ts" or "allwinner,sun6i-a31-ts" - reg: mmio address range of the chip - interrupts: interrupt to which the chip is connected + - #thermal-sensor-cells: shall be 0 Optional properties: - allwinner,ts-attached: boolean indicating that an actual touchscreen is @@ -17,4 +18,5 @@ Example: reg = <0x01c25000 0x100>; interrupts = <29>; allwinner,ts-attached; + #thermal-sensor-cells = <0>; }; diff --git a/Documentation/devicetree/bindings/input/touchscreen/ti-tsc-adc.txt b/Documentation/devicetree/bindings/input/touchscreen/ti-tsc-adc.txt index 878549ba814d..6c4fb34823d3 100644 --- a/Documentation/devicetree/bindings/input/touchscreen/ti-tsc-adc.txt +++ b/Documentation/devicetree/bindings/input/touchscreen/ti-tsc-adc.txt @@ -28,6 +28,20 @@ Required properties: ti,adc-channels: List of analog inputs available for ADC. AIN0 = 0, AIN1 = 1 and so on till AIN7 = 7. +Optional properties: +- child "tsc" + ti,charge-delay: Length of touch screen charge delay step in terms of + ADC clock cycles. Charge delay value should be large + in order to avoid false pen-up events. This value + effects the overall sampling speed, hence need to be + kept as low as possible, while avoiding false pen-up + event. Start from a lower value, say 0x400, and + increase value until false pen-up events are avoided. + The pen-up detection happens immediately after the + charge step, so this does in fact function as a + hardware knob for adjusting the amount of "settling + time". + Example: tscadc: tscadc@44e0d000 { compatible = "ti,am3359-tscadc"; @@ -36,6 +50,7 @@ Example: ti,x-plate-resistance = <200>; ti,coordiante-readouts = <5>; ti,wire-config = <0x00 0x11 0x22 0x33>; + ti,charge-delay = <0x400>; }; adc { diff --git a/Documentation/devicetree/bindings/input/tps65218-pwrbutton.txt b/Documentation/devicetree/bindings/input/tps65218-pwrbutton.txt new file mode 100644 index 000000000000..e30e0b93f2b3 --- /dev/null +++ b/Documentation/devicetree/bindings/input/tps65218-pwrbutton.txt @@ -0,0 +1,17 @@ +Texas Instruments TPS65218 power button + +This driver provides a simple power button event via an Interrupt. + +Required properties: +- compatible: should be "ti,tps65218-pwrbutton" +- interrupts: should be one of the following + - <3 IRQ_TYPE_EDGE_BOTH>: For controllers compatible with tps65218 + +Example: + +&tps { + power-button { + compatible = "ti,tps65218-pwrbutton"; + interrupts = <3 IRQ_TYPE_EDGE_BOTH>; + }; +}; diff --git a/Documentation/devicetree/bindings/interrupt-controller/brcm,bcm7120-l2-intc.txt b/Documentation/devicetree/bindings/interrupt-controller/brcm,bcm7120-l2-intc.txt index ff812a8a82bc..bae1f2187226 100644 --- a/Documentation/devicetree/bindings/interrupt-controller/brcm,bcm7120-l2-intc.txt +++ b/Documentation/devicetree/bindings/interrupt-controller/brcm,bcm7120-l2-intc.txt @@ -13,7 +13,12 @@ Such an interrupt controller has the following hardware design: or if they will output an interrupt signal at this 2nd level interrupt controller, in particular for UARTs -- not all 32-bits within the interrupt controller actually map to an interrupt +- typically has one 32-bit enable word and one 32-bit status word, but on + some hardware may have more than one enable/status pair + +- no atomic set/clear operations + +- not all bits within the interrupt controller actually map to an interrupt The typical hardware layout for this controller is represented below: @@ -48,7 +53,9 @@ The typical hardware layout for this controller is represented below: Required properties: - compatible: should be "brcm,bcm7120-l2-intc" -- reg: specifies the base physical address and size of the registers +- reg: specifies the base physical address and size of the registers; + multiple pairs may be specified, with the first pair handling IRQ offsets + 0..31 and the second pair handling 32..63 - interrupt-controller: identifies the node as an interrupt controller - #interrupt-cells: specifies the number of cells needed to encode an interrupt source, should be 1. @@ -59,18 +66,21 @@ Required properties: - brcm,int-map-mask: 32-bits bit mask describing how many and which interrupts are wired to this 2nd level interrupt controller, and how they match their respective interrupt parents. Should match exactly the number of interrupts - specified in the 'interrupts' property. + specified in the 'interrupts' property, multiplied by the number of + enable/status register pairs implemented by this controller. For + multiple parent IRQs with multiple enable/status words, this looks like: + <irq0_w0 irq0_w1 irq1_w0 irq1_w1 ...> Optional properties: - brcm,irq-can-wake: if present, this means the L2 controller can be used as a wakeup source for system suspend/resume. -- brcm,int-fwd-mask: if present, a 32-bits bit mask to configure for the - interrupts which have a mux gate, typically UARTs. Setting these bits will - make their respective interrupts outputs bypass this 2nd level interrupt - controller completely, it completely transparent for the interrupt controller - parent +- brcm,int-fwd-mask: if present, a bit mask to configure the interrupts which + have a mux gate, typically UARTs. Setting these bits will make their + respective interrupt outputs bypass this 2nd level interrupt controller + completely; it is completely transparent for the interrupt controller + parent. This should have one 32-bit word per enable/status pair. Example: diff --git a/Documentation/devicetree/bindings/interrupt-controller/digicolor-ic.txt b/Documentation/devicetree/bindings/interrupt-controller/digicolor-ic.txt new file mode 100644 index 000000000000..42d41ec84c7b --- /dev/null +++ b/Documentation/devicetree/bindings/interrupt-controller/digicolor-ic.txt @@ -0,0 +1,21 @@ +Conexant Digicolor Interrupt Controller + +Required properties: + +- compatible : should be "cnxt,cx92755-ic" +- reg : Specifies base physical address and size of the interrupt controller + registers (IC) area +- interrupt-controller : Identifies the node as an interrupt controller +- #interrupt-cells : Specifies the number of cells needed to encode an + interrupt source. The value shall be 1. +- syscon: A phandle to the syscon node describing UC registers + +Example: + + intc: interrupt-controller@f0000040 { + compatible = "cnxt,cx92755-ic"; + interrupt-controller; + #interrupt-cells = <1>; + reg = <0xf0000040 0x40>; + syscon = <&uc_regs>; + }; diff --git a/Documentation/devicetree/bindings/interrupt-controller/mips-gic.txt b/Documentation/devicetree/bindings/interrupt-controller/mips-gic.txt new file mode 100644 index 000000000000..5a65478e5d40 --- /dev/null +++ b/Documentation/devicetree/bindings/interrupt-controller/mips-gic.txt @@ -0,0 +1,55 @@ +MIPS Global Interrupt Controller (GIC) + +The MIPS GIC routes external interrupts to individual VPEs and IRQ pins. +It also supports local (per-processor) interrupts and software-generated +interrupts which can be used as IPIs. The GIC also includes a free-running +global timer, per-CPU count/compare timers, and a watchdog. + +Required properties: +- compatible : Should be "mti,gic". +- interrupt-controller : Identifies the node as an interrupt controller +- #interrupt-cells : Specifies the number of cells needed to encode an + interrupt specifier. Should be 3. + - The first cell is the type of interrupt, local or shared. + See <include/dt-bindings/interrupt-controller/mips-gic.h>. + - The second cell is the GIC interrupt number. + - The third cell encodes the interrupt flags. + See <include/dt-bindings/interrupt-controller/irq.h> for a list of valid + flags. + +Optional properties: +- reg : Base address and length of the GIC registers. If not present, + the base address reported by the hardware GCR_GIC_BASE will be used. +- mti,reserved-cpu-vectors : Specifies the list of CPU interrupt vectors + to which the GIC may not route interrupts. Valid values are 2 - 7. + This property is ignored if the CPU is started in EIC mode. + +Required properties for timer sub-node: +- compatible : Should be "mti,gic-timer". +- interrupts : Interrupt for the GIC local timer. +- clock-frequency : Clock frequency at which the GIC timers operate. + +Example: + + gic: interrupt-controller@1bdc0000 { + compatible = "mti,gic"; + reg = <0x1bdc0000 0x20000>; + + interrupt-controller; + #interrupt-cells = <3>; + + mti,reserved-cpu-vectors = <7>; + + timer { + compatible = "mti,gic-timer"; + interrupts = <GIC_LOCAL 1 IRQ_TYPE_NONE>; + clock-frequency = <50000000>; + }; + }; + + uart@18101400 { + ... + interrupt-parent = <&gic>; + interrupts = <GIC_SHARED 24 IRQ_TYPE_LEVEL_HIGH>; + ... + }; diff --git a/Documentation/devicetree/bindings/interrupt-controller/renesas,intc-irqpin.txt b/Documentation/devicetree/bindings/interrupt-controller/renesas,intc-irqpin.txt index c73acd060093..4f7946ae8adc 100644 --- a/Documentation/devicetree/bindings/interrupt-controller/renesas,intc-irqpin.txt +++ b/Documentation/devicetree/bindings/interrupt-controller/renesas,intc-irqpin.txt @@ -9,6 +9,11 @@ Required properties: - "renesas,intc-irqpin-r8a7778" (R-Car M1A) - "renesas,intc-irqpin-r8a7779" (R-Car H1) - "renesas,intc-irqpin-sh73a0" (SH-Mobile AG5) + +- reg: Base address and length of each register bank used by the external + IRQ pins driven by the interrupt controller hardware module. The base + addresses, length and number of required register banks varies with soctype. + - #interrupt-cells: has to be <2>: an interrupt index and flags, as defined in interrupts.txt in this directory diff --git a/Documentation/devicetree/bindings/interrupt-controller/ti,omap-intc-irq.txt b/Documentation/devicetree/bindings/interrupt-controller/ti,omap-intc-irq.txt new file mode 100644 index 000000000000..38ce5d037722 --- /dev/null +++ b/Documentation/devicetree/bindings/interrupt-controller/ti,omap-intc-irq.txt @@ -0,0 +1,28 @@ +Omap2/3 intc controller + +On TI omap2 and 3 the intc interrupt controller can provide +96 or 128 IRQ signals to the ARM host depending on the SoC. + +Required Properties: +- compatible: should be one of + "ti,omap2-intc" + "ti,omap3-intc" + "ti,dm814-intc" + "ti,dm816-intc" + "ti,am33xx-intc" + +- interrupt-controller : Identifies the node as an interrupt controller +- #interrupt-cells : Specifies the number of cells needed to encode interrupt + source, should be 1 for intc +- interrupts: interrupt reference to primary interrupt controller + +Please refer to interrupts.txt in this directory for details of the common +Interrupt Controllers bindings used by client devices. + +Example: + intc: interrupt-controller@48200000 { + compatible = "ti,omap3-intc"; + interrupt-controller; + #interrupt-cells = <1>; + reg = <0x48200000 0x1000>; + }; diff --git a/Documentation/devicetree/bindings/iommu/renesas,ipmmu-vmsa.txt b/Documentation/devicetree/bindings/iommu/renesas,ipmmu-vmsa.txt new file mode 100644 index 000000000000..cd29083e16ec --- /dev/null +++ b/Documentation/devicetree/bindings/iommu/renesas,ipmmu-vmsa.txt @@ -0,0 +1,41 @@ +* Renesas VMSA-Compatible IOMMU + +The IPMMU is an IOMMU implementation compatible with the ARM VMSA page tables. +It provides address translation for bus masters outside of the CPU, each +connected to the IPMMU through a port called micro-TLB. + + +Required Properties: + + - compatible: Must contain "renesas,ipmmu-vmsa". + - reg: Base address and size of the IPMMU registers. + - interrupts: Specifiers for the MMU fault interrupts. For instances that + support secure mode two interrupts must be specified, for non-secure and + secure mode, in that order. For instances that don't support secure mode a + single interrupt must be specified. + + - #iommu-cells: Must be 1. + +Each bus master connected to an IPMMU must reference the IPMMU in its device +node with the following property: + + - iommus: A reference to the IPMMU in two cells. The first cell is a phandle + to the IPMMU and the second cell the number of the micro-TLB that the + device is connected to. + + +Example: R8A7791 IPMMU-MX and VSP1-D0 bus master + + ipmmu_mx: mmu@fe951000 { + compatible = "renasas,ipmmu-vmsa"; + reg = <0 0xfe951000 0 0x1000>; + interrupts = <0 222 IRQ_TYPE_LEVEL_HIGH>, + <0 221 IRQ_TYPE_LEVEL_HIGH>; + #iommu-cells = <1>; + }; + + vsp1@fe928000 { + ... + iommus = <&ipmmu_mx 13>; + ... + }; diff --git a/Documentation/devicetree/bindings/iommu/rockchip,iommu.txt b/Documentation/devicetree/bindings/iommu/rockchip,iommu.txt new file mode 100644 index 000000000000..9a55ac3735e5 --- /dev/null +++ b/Documentation/devicetree/bindings/iommu/rockchip,iommu.txt @@ -0,0 +1,26 @@ +Rockchip IOMMU +============== + +A Rockchip DRM iommu translates io virtual addresses to physical addresses for +its master device. Each slave device is bound to a single master device, and +shares its clocks, power domain and irq. + +Required properties: +- compatible : Should be "rockchip,iommu" +- reg : Address space for the configuration registers +- interrupts : Interrupt specifier for the IOMMU instance +- interrupt-names : Interrupt name for the IOMMU instance +- #iommu-cells : Should be <0>. This indicates the iommu is a + "single-master" device, and needs no additional information + to associate with its master device. See: + Documentation/devicetree/bindings/iommu/iommu.txt + +Example: + + vopl_mmu: iommu@ff940300 { + compatible = "rockchip,iommu"; + reg = <0xff940300 0x100>; + interrupts = <GIC_SPI 16 IRQ_TYPE_LEVEL_HIGH>; + interrupt-names = "vopl_mmu"; + #iommu-cells = <0>; + }; diff --git a/Documentation/devicetree/bindings/iommu/samsung,sysmmu.txt b/Documentation/devicetree/bindings/iommu/samsung,sysmmu.txt index 6fa4c737af23..729543c47046 100644 --- a/Documentation/devicetree/bindings/iommu/samsung,sysmmu.txt +++ b/Documentation/devicetree/bindings/iommu/samsung,sysmmu.txt @@ -45,7 +45,7 @@ Required properties: Exynos4 SoCs, there needs no "master" clock. Exynos5 SoCs, some System MMUs must have "master" clocks. - clocks: Required if the System MMU is needed to gate its clock. -- samsung,power-domain: Required if the System MMU is needed to gate its power. +- power-domains: Required if the System MMU is needed to gate its power. Please refer to the following document: Documentation/devicetree/bindings/arm/exynos/power_domain.txt @@ -54,7 +54,7 @@ Examples: compatible = "samsung,exynos5-gsc"; reg = <0x13e00000 0x1000>; interrupts = <0 85 0>; - samsung,power-domain = <&pd_gsc>; + power-domains = <&pd_gsc>; clocks = <&clock CLK_GSCL0>; clock-names = "gscl"; }; @@ -66,5 +66,5 @@ Examples: interrupts = <2 0>; clock-names = "sysmmu", "master"; clocks = <&clock CLK_SMMU_GSCL0>, <&clock CLK_GSCL0>; - samsung,power-domain = <&pd_gsc>; + power-domains = <&pd_gsc>; }; diff --git a/Documentation/devicetree/bindings/leds/common.txt b/Documentation/devicetree/bindings/leds/common.txt index 2d88816dd550..34811c57db69 100644 --- a/Documentation/devicetree/bindings/leds/common.txt +++ b/Documentation/devicetree/bindings/leds/common.txt @@ -1,6 +1,19 @@ Common leds properties. +LED and flash LED devices provide the same basic functionality as current +regulators, but extended with LED and flash LED specific features like +blinking patterns, flash timeout, flash faults and external flash strobe mode. + +Many LED devices expose more than one current output that can be connected +to one or more discrete LED component. Since the arrangement of connections +can influence the way of the LED device initialization, the LED components +have to be tightly coupled with the LED device binding. They are represented +by child nodes of the parent LED device binding. + Optional properties for child nodes: +- led-sources : List of device current outputs the LED is connected to. The + outputs are identified by the numbers that must be defined + in the LED device binding documentation. - label : The label for this LED. If omitted, the label is taken from the node name (excluding the unit address). @@ -14,6 +27,15 @@ Optional properties for child nodes: "ide-disk" - LED indicates disk activity "timer" - LED flashes at a fixed, configurable rate +- max-microamp : maximum intensity in microamperes of the LED + (torch LED for flash devices) +- flash-max-microamp : maximum intensity in microamperes of the + flash LED; it is mandatory if the LED should + support the flash mode +- flash-timeout-us : timeout in microseconds after which the flash + LED is turned off + + Examples: system-status { @@ -21,3 +43,11 @@ system-status { linux,default-trigger = "heartbeat"; ... }; + +camera-flash { + label = "Flash"; + led-sources = <0>, <1>; + max-microamp = <50000>; + flash-max-microamp = <320000>; + flash-timeout-us = <500000>; +}; diff --git a/Documentation/devicetree/bindings/leds/leds-lp8860.txt b/Documentation/devicetree/bindings/leds/leds-lp8860.txt new file mode 100644 index 000000000000..aad38dd94d4b --- /dev/null +++ b/Documentation/devicetree/bindings/leds/leds-lp8860.txt @@ -0,0 +1,29 @@ +* Texas Instruments - lp8860 4-Channel LED Driver + +The LP8860-Q1 is an high-efficiency LED +driver with boost controller. It has 4 high-precision +current sinks that can be controlled by a PWM input +signal, a SPI/I2C master, or both. + +Required properties: + - compatible: + "ti,lp8860" + - reg - I2C slave address + - label - Used for naming LEDs + +Optional properties: + - enable-gpio - gpio pin to enable/disable the device. + - supply - "vled" - LED supply + +Example: + +leds: leds@6 { + compatible = "ti,lp8860"; + reg = <0x2d>; + label = "display_cluster"; + enable-gpio = <&gpio1 28 GPIO_ACTIVE_HIGH>; + vled-supply = <&vbatt>; +} + +For more product information please see the link below: +http://www.ti.com/product/lp8860-q1 diff --git a/Documentation/devicetree/bindings/mailbox/altera-mailbox.txt b/Documentation/devicetree/bindings/mailbox/altera-mailbox.txt new file mode 100644 index 000000000000..c2619797ce0c --- /dev/null +++ b/Documentation/devicetree/bindings/mailbox/altera-mailbox.txt @@ -0,0 +1,49 @@ +Altera Mailbox Driver +===================== + +Required properties: +- compatible : "altr,mailbox-1.0". +- reg : physical base address of the mailbox and length of + memory mapped region. +- #mbox-cells: Common mailbox binding property to identify the number + of cells required for the mailbox specifier. Should be 1. + +Optional properties: +- interrupt-parent : interrupt source phandle. +- interrupts : interrupt number. The interrupt specifier format + depends on the interrupt controller parent. + +Example: + mbox_tx: mailbox@0x100 { + compatible = "altr,mailbox-1.0"; + reg = <0x100 0x8>; + interrupt-parent = < &gic_0 >; + interrupts = <5>; + #mbox-cells = <1>; + }; + + mbox_rx: mailbox@0x200 { + compatible = "altr,mailbox-1.0"; + reg = <0x200 0x8>; + interrupt-parent = < &gic_0 >; + interrupts = <6>; + #mbox-cells = <1>; + }; + +Mailbox client +=============== +"mboxes" and the optional "mbox-names" (please see +Documentation/devicetree/bindings/mailbox/mailbox.txt for details). Each value +of the mboxes property should contain a phandle to the mailbox controller +device node and second argument is the channel index. It must be 0 (hardware +support only one channel).The equivalent "mbox-names" property value can be +used to give a name to the communication channel to be used by the client user. + +Example: + mclient0: mclient0@0x400 { + compatible = "client-1.0"; + reg = <0x400 0x10>; + mbox-names = "mbox-tx", "mbox-rx"; + mboxes = <&mbox_tx 0>, + <&mbox_rx 0>; + }; diff --git a/Documentation/devicetree/bindings/mailbox/omap-mailbox.txt b/Documentation/devicetree/bindings/mailbox/omap-mailbox.txt index 48edc4b92afb..d1a043339c11 100644 --- a/Documentation/devicetree/bindings/mailbox/omap-mailbox.txt +++ b/Documentation/devicetree/bindings/mailbox/omap-mailbox.txt @@ -43,6 +43,9 @@ Required properties: device. The format is dependent on which interrupt controller the OMAP device uses - ti,hwmods: Name of the hwmod associated with the mailbox +- #mbox-cells: Common mailbox binding property to identify the number + of cells required for the mailbox specifier. Should be + 1 - ti,mbox-num-users: Number of targets (processor devices) that the mailbox device can interrupt - ti,mbox-num-fifos: Number of h/w fifo queues within the mailbox IP block @@ -72,6 +75,18 @@ data that represent the following: Cell #3 (usr_id) - mailbox user id for identifying the interrupt line associated with generating a tx/rx fifo interrupt. +Mailbox Users: +============== +A device needing to communicate with a target processor device should specify +them using the common mailbox binding properties, "mboxes" and the optional +"mbox-names" (please see Documentation/devicetree/bindings/mailbox/mailbox.txt +for details). Each value of the mboxes property should contain a phandle to the +mailbox controller device node and an args specifier that will be the phandle to +the intended sub-mailbox child node to be used for communication. The equivalent +"mbox-names" property value can be used to give a name to the communication channel +to be used by the client user. + + Example: -------- @@ -81,6 +96,7 @@ mailbox: mailbox@4a0f4000 { reg = <0x4a0f4000 0x200>; interrupts = <GIC_SPI 26 IRQ_TYPE_LEVEL_HIGH>; ti,hwmods = "mailbox"; + #mbox-cells = <1>; ti,mbox-num-users = <3>; ti,mbox-num-fifos = <8>; mbox_ipu: mbox_ipu { @@ -93,12 +109,19 @@ mailbox: mailbox@4a0f4000 { }; }; +dsp { + ... + mboxes = <&mailbox &mbox_dsp>; + ... +}; + /* AM33xx */ mailbox: mailbox@480C8000 { compatible = "ti,omap4-mailbox"; reg = <0x480C8000 0x200>; interrupts = <77>; ti,hwmods = "mailbox"; + #mbox-cells = <1>; ti,mbox-num-users = <4>; ti,mbox-num-fifos = <8>; mbox_wkupm3: wkup_m3 { diff --git a/Documentation/devicetree/bindings/media/atmel-isi.txt b/Documentation/devicetree/bindings/media/atmel-isi.txt index 17e71b7b44c6..251f008f220c 100644 --- a/Documentation/devicetree/bindings/media/atmel-isi.txt +++ b/Documentation/devicetree/bindings/media/atmel-isi.txt @@ -38,7 +38,7 @@ Example: i2c1: i2c@f0018000 { ov2640: camera@0x30 { - compatible = "omnivision,ov2640"; + compatible = "ovti,ov2640"; reg = <0x30>; port { diff --git a/Documentation/devicetree/bindings/media/i2c/nokia,smia.txt b/Documentation/devicetree/bindings/media/i2c/nokia,smia.txt new file mode 100644 index 000000000000..855e1faf73e2 --- /dev/null +++ b/Documentation/devicetree/bindings/media/i2c/nokia,smia.txt @@ -0,0 +1,63 @@ +SMIA/SMIA++ sensor + +SMIA (Standard Mobile Imaging Architecture) is an image sensor standard +defined jointly by Nokia and ST. SMIA++, defined by Nokia, is an extension +of that. These definitions are valid for both types of sensors. + +More detailed documentation can be found in +Documentation/devicetree/bindings/media/video-interfaces.txt . + + +Mandatory properties +-------------------- + +- compatible: "nokia,smia" +- reg: I2C address (0x10, or an alternative address) +- vana-supply: Analogue voltage supply (VANA), typically 2,8 volts (sensor + dependent). +- clocks: External clock to the sensor +- clock-frequency: Frequency of the external clock to the sensor +- link-frequencies: List of allowed data link frequencies. An array of + 64-bit elements. + + +Optional properties +------------------- + +- nokia,nvm-size: The size of the NVM, in bytes. If the size is not given, + the NVM contents will not be read. +- reset-gpios: XSHUTDOWN GPIO + + +Endpoint node mandatory properties +---------------------------------- + +- clock-lanes: <0> +- data-lanes: <1..n> +- remote-endpoint: A phandle to the bus receiver's endpoint node. + + +Example +------- + +&i2c2 { + clock-frequency = <400000>; + + smiapp_1: camera@10 { + compatible = "nokia,smia"; + reg = <0x10>; + reset-gpios = <&gpio3 20 0>; + vana-supply = <&vaux3>; + clocks = <&omap3_isp 0>; + clock-frequency = <9600000>; + nokia,nvm-size = <512>; /* 8 * 64 */ + link-frequencies = /bits/ 64 <199200000 210000000 499200000>; + port { + smiapp_1_1: endpoint { + clock-lanes = <0>; + data-lanes = <1 2>; + remote-endpoint = <&csi2a_ep>; + }; + }; + }; +}; diff --git a/Documentation/devicetree/bindings/media/meson-ir.txt b/Documentation/devicetree/bindings/media/meson-ir.txt new file mode 100644 index 000000000000..407848e85f31 --- /dev/null +++ b/Documentation/devicetree/bindings/media/meson-ir.txt @@ -0,0 +1,14 @@ +* Amlogic Meson IR remote control receiver + +Required properties: + - compatible : should be "amlogic,meson6-ir" + - reg : physical base address and length of the device registers + - interrupts : a single specifier for the interrupt from the device + +Example: + + ir-receiver@c8100480 { + compatible= "amlogic,meson6-ir"; + reg = <0xc8100480 0x20>; + interrupts = <0 15 1>; + }; diff --git a/Documentation/devicetree/bindings/media/rcar_vin.txt b/Documentation/devicetree/bindings/media/rcar_vin.txt index ba61782c2af9..9dafe6b06cd2 100644 --- a/Documentation/devicetree/bindings/media/rcar_vin.txt +++ b/Documentation/devicetree/bindings/media/rcar_vin.txt @@ -6,6 +6,8 @@ family of devices. The current blocks are always slaves and suppot one input channel which can be either RGB, YUYV or BT656. - compatible: Must be one of the following + - "renesas,vin-r8a7794" for the R8A7794 device + - "renesas,vin-r8a7793" for the R8A7793 device - "renesas,vin-r8a7791" for the R8A7791 device - "renesas,vin-r8a7790" for the R8A7790 device - "renesas,vin-r8a7779" for the R8A7779 device diff --git a/Documentation/devicetree/bindings/media/s5p-mfc.txt b/Documentation/devicetree/bindings/media/s5p-mfc.txt index 3e3c5f349570..2d5787eac91a 100644 --- a/Documentation/devicetree/bindings/media/s5p-mfc.txt +++ b/Documentation/devicetree/bindings/media/s5p-mfc.txt @@ -28,7 +28,7 @@ Required properties: for DMA contiguous memory allocation and its size. Optional properties: - - samsung,power-domain : power-domain property defined with a phandle + - power-domains : power-domain property defined with a phandle to respective power domain. Example: @@ -38,7 +38,7 @@ mfc: codec@13400000 { compatible = "samsung,mfc-v5"; reg = <0x13400000 0x10000>; interrupts = <0 94 0>; - samsung,power-domain = <&pd_mfc>; + power-domains = <&pd_mfc>; clocks = <&clock 273>; clock-names = "mfc"; }; diff --git a/Documentation/devicetree/bindings/media/si4713.txt b/Documentation/devicetree/bindings/media/si4713.txt new file mode 100644 index 000000000000..5ee5552d3465 --- /dev/null +++ b/Documentation/devicetree/bindings/media/si4713.txt @@ -0,0 +1,30 @@ +* Silicon Labs FM Radio transmitter + +The Silicon Labs Si4713 is an FM radio transmitter with receive power scan +supporting 76-108 MHz. It includes an RDS encoder and has both, a stereo-analog +and a digital interface, which supports I2S, left-justified and a custom +DSP-mode format. It is programmable through an I2C interface. + +Required Properties: +- compatible: Should contain "silabs,si4713" +- reg: the I2C address of the device + +Optional Properties: +- interrupts-extended: Interrupt specifier for the chips interrupt +- reset-gpios: GPIO specifier for the chips reset line +- vdd-supply: phandle for Vdd regulator +- vio-supply: phandle for Vio regulator + +Example: + +&i2c2 { + fmtx: si4713@63 { + compatible = "silabs,si4713"; + reg = <0x63>; + + interrupts-extended = <&gpio2 21 IRQ_TYPE_EDGE_FALLING>; /* 53 */ + reset-gpios = <&gpio6 3 GPIO_ACTIVE_HIGH>; /* 163 */ + vio-supply = <&vio>; + vdd-supply = <&vaux1>; + }; +}; diff --git a/Documentation/devicetree/bindings/media/sunxi-ir.txt b/Documentation/devicetree/bindings/media/sunxi-ir.txt index 23dd5ad07b7c..1811a067c72c 100644 --- a/Documentation/devicetree/bindings/media/sunxi-ir.txt +++ b/Documentation/devicetree/bindings/media/sunxi-ir.txt @@ -1,7 +1,7 @@ Device-Tree bindings for SUNXI IR controller found in sunXi SoC family Required properties: -- compatible : should be "allwinner,sun4i-a10-ir"; +- compatible : "allwinner,sun4i-a10-ir" or "allwinner,sun5i-a13-ir" - clocks : list of clock specifiers, corresponding to entries in clock-names property; - clock-names : should contain "apb" and "ir" entries; @@ -10,6 +10,7 @@ Required properties: Optional properties: - linux,rc-map-name : Remote control map name. +- resets : phandle + reset specifier pair Example: @@ -17,6 +18,7 @@ ir0: ir@01c21800 { compatible = "allwinner,sun4i-a10-ir"; clocks = <&apb0_gates 6>, <&ir0_clk>; clock-names = "apb", "ir"; + resets = <&apb0_rst 1>; interrupts = <0 5 1>; reg = <0x01C21800 0x40>; linux,rc-map-name = "rc-rc6-mce"; diff --git a/Documentation/devicetree/bindings/media/ti-am437x-vpfe.txt b/Documentation/devicetree/bindings/media/ti-am437x-vpfe.txt new file mode 100644 index 000000000000..3932e766553a --- /dev/null +++ b/Documentation/devicetree/bindings/media/ti-am437x-vpfe.txt @@ -0,0 +1,61 @@ +Texas Instruments AM437x CAMERA (VPFE) +-------------------------------------- + +The Video Processing Front End (VPFE) is a key component for image capture +applications. The capture module provides the system interface and the +processing capability to connect RAW image-sensor modules and video decoders +to the AM437x device. + +Required properties: +- compatible: must be "ti,am437x-vpfe" +- reg: physical base address and length of the registers set for the device; +- interrupts: should contain IRQ line for the VPFE; +- ti,am437x-vpfe-interface: can be one of the following, + 0 - Raw Bayer Interface. + 1 - 8 Bit BT656 Interface. + 2 - 10 Bit BT656 Interface. + 3 - YCbCr 8 Bit Interface. + 4 - YCbCr 16 Bit Interface. + +VPFE supports a single port node with parallel bus. It should contain one +'port' child node with child 'endpoint' node. Please refer to the bindings +defined in Documentation/devicetree/bindings/media/video-interfaces.txt. + +Example: + vpfe: vpfe@f0034000 { + compatible = "ti,am437x-vpfe"; + reg = <0x48328000 0x2000>; + interrupts = <GIC_SPI 50 IRQ_TYPE_LEVEL_HIGH>; + + pinctrl-names = "default", "sleep"; + pinctrl-0 = <&vpfe_pins_default>; + pinctrl-1 = <&vpfe_pins_sleep>; + + port { + #address-cells = <1>; + #size-cells = <0>; + + vpfe0_ep: endpoint { + remote-endpoint = <&ov2659_1>; + ti,am437x-vpfe-interface = <0>; + bus-width = <8>; + hsync-active = <0>; + vsync-active = <0>; + }; + }; + }; + + i2c1: i2c@4802a000 { + + ov2659@30 { + compatible = "ti,ov2659"; + reg = <0x30>; + + port { + ov2659_1: endpoint { + remote-endpoint = <&vpfe0_ep>; + bus-width = <8>; + mclk-frequency = <12000000>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/media/video-interfaces.txt b/Documentation/devicetree/bindings/media/video-interfaces.txt index ce719f89dd1c..571b4c60665f 100644 --- a/Documentation/devicetree/bindings/media/video-interfaces.txt +++ b/Documentation/devicetree/bindings/media/video-interfaces.txt @@ -103,6 +103,9 @@ Optional endpoint properties array contains only one entry. - clock-noncontinuous: a boolean property to allow MIPI CSI-2 non-continuous clock mode. +- link-frequencies: Allowed data bus frequencies. For MIPI CSI-2, for + instance, this is the actual frequency of the bus, not bits per clock per + lane value. An array of 64-bit unsigned integers. Example @@ -159,7 +162,7 @@ pipelines can be active: ov772x -> ceu0 or imx074 -> csi2 -> ceu0. i2c0: i2c@0xfff20000 { ... ov772x_1: camera@0x21 { - compatible = "omnivision,ov772x"; + compatible = "ovti,ov772x"; reg = <0x21>; vddio-supply = <®ulator1>; vddcore-supply = <®ulator2>; diff --git a/Documentation/devicetree/bindings/memory-controllers/mvebu-sdram-controller.txt b/Documentation/devicetree/bindings/memory-controllers/mvebu-sdram-controller.txt new file mode 100644 index 000000000000..89657d1d4cd4 --- /dev/null +++ b/Documentation/devicetree/bindings/memory-controllers/mvebu-sdram-controller.txt @@ -0,0 +1,21 @@ +Device Tree bindings for MVEBU SDRAM controllers + +The Marvell EBU SoCs all have a SDRAM controller. The SDRAM controller +differs from one SoC variant to another, but they also share a number +of commonalities. + +For now, this Device Tree binding documentation only documents the +Armada XP SDRAM controller. + +Required properties: + + - compatible: for Armada XP, "marvell,armada-xp-sdram-controller" + - reg: a resource specifier for the register space, which should + include all SDRAM controller registers as per the datasheet. + +Example: + +sdramc@1400 { + compatible = "marvell,armada-xp-sdram-controller"; + reg = <0x1400 0x500>; +}; diff --git a/Documentation/devicetree/bindings/memory-controllers/nvidia,tegra-mc.txt b/Documentation/devicetree/bindings/memory-controllers/nvidia,tegra-mc.txt new file mode 100644 index 000000000000..f3db93c85eea --- /dev/null +++ b/Documentation/devicetree/bindings/memory-controllers/nvidia,tegra-mc.txt @@ -0,0 +1,36 @@ +NVIDIA Tegra Memory Controller device tree bindings +=================================================== + +Required properties: +- compatible: Should be "nvidia,tegra<chip>-mc" +- reg: Physical base address and length of the controller's registers. +- clocks: Must contain an entry for each entry in clock-names. + See ../clocks/clock-bindings.txt for details. +- clock-names: Must include the following entries: + - mc: the module's clock input +- interrupts: The interrupt outputs from the controller. +- #iommu-cells: Should be 1. The single cell of the IOMMU specifier defines + the SWGROUP of the master. + +This device implements an IOMMU that complies with the generic IOMMU binding. +See ../iommu/iommu.txt for details. + +Example: +-------- + + mc: memory-controller@0,70019000 { + compatible = "nvidia,tegra124-mc"; + reg = <0x0 0x70019000 0x0 0x1000>; + clocks = <&tegra_car TEGRA124_CLK_MC>; + clock-names = "mc"; + + interrupts = <GIC_SPI 77 IRQ_TYPE_LEVEL_HIGH>; + + #iommu-cells = <1>; + }; + + sdhci@0,700b0000 { + compatible = "nvidia,tegra124-sdhci"; + ... + iommus = <&mc TEGRA_SWGROUP_SDMMC1A>; + }; diff --git a/Documentation/devicetree/bindings/memory-controllers/renesas-memory-controllers.txt b/Documentation/devicetree/bindings/memory-controllers/renesas-memory-controllers.txt new file mode 100644 index 000000000000..c64b7925cd09 --- /dev/null +++ b/Documentation/devicetree/bindings/memory-controllers/renesas-memory-controllers.txt @@ -0,0 +1,44 @@ +DT bindings for Renesas R-Mobile and SH-Mobile memory controllers +================================================================= + +Renesas R-Mobile and SH-Mobile SoCs contain one or more memory controllers. +These memory controllers differ from one SoC variant to another, and are called +by different names ("DDR Bus Controller (DBSC)", "DDR3 Bus State Controller +(DBSC3)", "SDRAM Bus State Controller (SBSC)"). + +Currently memory controller device nodes are used only to reference PM +domains, and prevent these PM domains from being powered down, which would +crash the system. + +As there exist no actual drivers for these controllers yet, these bindings +should be considered EXPERIMENTAL for now. + +Required properties: + - compatible: Must be one of the following SoC-specific values: + - "renesas,dbsc-r8a73a4" (R-Mobile APE6) + - "renesas,dbsc3-r8a7740" (R-Mobile A1) + - "renesas,sbsc-sh73a0" (SH-Mobile AG5) + - reg: Must contain the base address and length of the memory controller's + registers. + +Optional properties: + - interrupts: Must contain a list of interrupt specifiers for memory + controller interrupts, if available. + - interrupts-names: Must contain a list of interrupt names corresponding to + the interrupts in the interrupts property, if available. + Valid interrupt names are: + - "sec" (secure interrupt) + - "temp" (normal (temperature) interrupt) + - power-domains: Must contain a reference to the PM domain that the memory + controller belongs to, if available. + +Example: + + sbsc1: memory-controller@fe400000 { + compatible = "renesas,sbsc-sh73a0"; + reg = <0xfe400000 0x400>; + interrupts = <0 35 IRQ_TYPE_LEVEL_HIGH>, + <0 36 IRQ_TYPE_LEVEL_HIGH>; + interrupt-names = "sec", "temp"; + power-domains = <&pd_a4bc0>; + }; diff --git a/Documentation/devicetree/bindings/mfd/atmel-hlcdc.txt b/Documentation/devicetree/bindings/mfd/atmel-hlcdc.txt new file mode 100644 index 000000000000..f64de95a8e8b --- /dev/null +++ b/Documentation/devicetree/bindings/mfd/atmel-hlcdc.txt @@ -0,0 +1,51 @@ +Device-Tree bindings for Atmel's HLCDC (High LCD Controller) MFD driver + +Required properties: + - compatible: value should be one of the following: + "atmel,sama5d3-hlcdc" + - reg: base address and size of the HLCDC device registers. + - clock-names: the name of the 3 clocks requested by the HLCDC device. + Should contain "periph_clk", "sys_clk" and "slow_clk". + - clocks: should contain the 3 clocks requested by the HLCDC device. + - interrupts: should contain the description of the HLCDC interrupt line + +The HLCDC IP exposes two subdevices: + - a PWM chip: see ../pwm/atmel-hlcdc-pwm.txt + - a Display Controller: see ../drm/atmel-hlcdc-dc.txt + +Example: + + hlcdc: hlcdc@f0030000 { + compatible = "atmel,sama5d3-hlcdc"; + reg = <0xf0030000 0x2000>; + clocks = <&lcdc_clk>, <&lcdck>, <&clk32k>; + clock-names = "periph_clk","sys_clk", "slow_clk"; + interrupts = <36 IRQ_TYPE_LEVEL_HIGH 0>; + status = "disabled"; + + hlcdc-display-controller { + compatible = "atmel,hlcdc-display-controller"; + pinctrl-names = "default"; + pinctrl-0 = <&pinctrl_lcd_base &pinctrl_lcd_rgb888>; + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + #address-cells = <1>; + #size-cells = <0>; + reg = <0>; + + hlcdc_panel_output: endpoint@0 { + reg = <0>; + remote-endpoint = <&panel_input>; + }; + }; + }; + + hlcdc_pwm: hlcdc-pwm { + compatible = "atmel,hlcdc-pwm"; + pinctrl-names = "default"; + pinctrl-0 = <&pinctrl_lcd_pwm>; + #pwm-cells = <3>; + }; + }; diff --git a/Documentation/devicetree/bindings/mfd/atmel-matrix.txt b/Documentation/devicetree/bindings/mfd/atmel-matrix.txt new file mode 100644 index 000000000000..e3ef50ca02a5 --- /dev/null +++ b/Documentation/devicetree/bindings/mfd/atmel-matrix.txt @@ -0,0 +1,24 @@ +* Device tree bindings for Atmel Bus Matrix + +The Bus Matrix registers are used to configure Atmel SoCs internal bus +behavior (master/slave priorities, undefined burst length type, ...) + +Required properties: +- compatible: Should be one of the following + "atmel,at91sam9260-matrix", "syscon" + "atmel,at91sam9261-matrix", "syscon" + "atmel,at91sam9263-matrix", "syscon" + "atmel,at91sam9rl-matrix", "syscon" + "atmel,at91sam9g45-matrix", "syscon" + "atmel,at91sam9n12-matrix", "syscon" + "atmel,at91sam9x5-matrix", "syscon" + "atmel,sama5d3-matrix", "syscon" +- reg: Contains offset/length value of the Bus Matrix + memory region. + +Example: + +matrix: matrix@ffffec00 { + compatible = "atmel,sama5d3-matrix", "syscon"; + reg = <0xffffec00 0x200>; +}; diff --git a/Documentation/devicetree/bindings/mfd/atmel-smc.txt b/Documentation/devicetree/bindings/mfd/atmel-smc.txt new file mode 100644 index 000000000000..26eeed373934 --- /dev/null +++ b/Documentation/devicetree/bindings/mfd/atmel-smc.txt @@ -0,0 +1,19 @@ +* Device tree bindings for Atmel SMC (Static Memory Controller) + +The SMC registers are used to configure Atmel EBI (External Bus Interface) +to interface with standard memory devices (NAND, NOR, SRAM or specialized +devices like FPGAs). + +Required properties: +- compatible: Should be one of the following + "atmel,at91sam9260-smc", "syscon" + "atmel,sama5d3-smc", "syscon" +- reg: Contains offset/length value of the SMC memory + region. + +Example: + +smc: smc@ffffc000 { + compatible = "atmel,sama5d3-smc", "syscon"; + reg = <0xffffc000 0x1000>; +}; diff --git a/Documentation/devicetree/bindings/mfd/max77686.txt b/Documentation/devicetree/bindings/mfd/max77686.txt index 678f3cf0b8f0..e39f0bc1f55e 100644 --- a/Documentation/devicetree/bindings/mfd/max77686.txt +++ b/Documentation/devicetree/bindings/mfd/max77686.txt @@ -34,6 +34,18 @@ to get matched with their hardware counterparts as follow: -BUCKn : for BUCKs, where n can lie in range 1 to 9. example: BUCK1, BUCK5, BUCK9. + Regulators which can be turned off during system suspend: + -LDOn : 2, 6-8, 10-12, 14-16, + -BUCKn : 1-4. + Use standard regulator bindings for it ('regulator-off-in-suspend'). + + LDO20, LDO21, LDO22, BUCK8 and BUCK9 can be configured to GPIO enable + control. To turn this feature on this property must be added to the regulator + sub-node: + - maxim,ena-gpios : one GPIO specifier enable control (the gpio + flags are actually ignored and always + ACTIVE_HIGH is used) + Example: max77686@09 { @@ -59,4 +71,12 @@ Example: regulator-always-on; regulator-boot-on; }; + + buck9_reg { + regulator-compatible = "BUCK9"; + regulator-name = "CAM_ISP_CORE_1.2V"; + regulator-min-microvolt = <1000000>; + regulator-max-microvolt = <1200000>; + maxim,ena-gpios = <&gpm0 3 GPIO_ACTIVE_HIGH>; + }; } diff --git a/Documentation/devicetree/bindings/mfd/max77693.txt b/Documentation/devicetree/bindings/mfd/max77693.txt index 11921cc417bf..38e64405e98d 100644 --- a/Documentation/devicetree/bindings/mfd/max77693.txt +++ b/Documentation/devicetree/bindings/mfd/max77693.txt @@ -27,6 +27,55 @@ Optional properties: [*] refer Documentation/devicetree/bindings/regulator/regulator.txt +- haptic : The MAX77693 haptic device utilises a PWM controlled motor to provide + users with tactile feedback. PWM period and duty-cycle are varied in + order to provide the approprite level of feedback. + + Required properties: + - compatible : Must be "maxim,max77693-hpatic" + - haptic-supply : power supply for the haptic motor + [*] refer Documentation/devicetree/bindings/regulator/regulator.txt + - pwms : phandle to the physical PWM(Pulse Width Modulation) device. + PWM properties should be named "pwms". And number of cell is different + for each pwm device. + To get more informations, please refer to documentaion. + [*] refer Documentation/devicetree/bindings/pwm/pwm.txt + +- charger : Node configuring the charger driver. + If present, required properties: + - compatible : Must be "maxim,max77693-charger". + + Optional properties (if not set, defaults will be used): + - maxim,constant-microvolt : Battery constant voltage in uV. The charger + will operate in fast charge constant current mode till battery voltage + reaches this level. Then the charger will switch to fast charge constant + voltage mode. Also vsys (system voltage) will be set to this value when + DC power is supplied but charger is not enabled. + Valid values: 3650000 - 4400000, step by 25000 (rounded down) + Default: 4200000 + + - maxim,min-system-microvolt : Minimal system voltage in uV. + Valid values: 3000000 - 3700000, step by 100000 (rounded down) + Default: 3600000 + + - maxim,thermal-regulation-celsius : Temperature in Celsius for entering + high temperature charging mode. If die temperature exceeds this value + the charging current will be reduced by 105 mA/Celsius. + Valid values: 70, 85, 100, 115 + Default: 100 + + - maxim,battery-overcurrent-microamp : Overcurrent protection threshold + in uA (current from battery to system). + Valid values: 2000000 - 3500000, step by 250000 (rounded down) + Default: 3500000 + + - maxim,charge-input-threshold-microvolt : Threshold voltage in uV for + triggering input voltage regulation loop. If input voltage decreases + below this value, the input current will be reduced to reach the + threshold voltage. + Valid values: 4300000, 4700000, 4800000, 4900000 + Default: 4300000 + Example: max77693@66 { compatible = "maxim,max77693"; @@ -52,4 +101,21 @@ Example: regulator-boot-on; }; }; + + haptic { + compatible = "maxim,max77693-haptic"; + haptic-supply = <&haptic_supply>; + pwms = <&pwm 0 40000 0>; + pwm-names = "haptic"; + }; + + charger { + compatible = "maxim,max77693-charger"; + + maxim,constant-microvolt = <4200000>; + maxim,min-system-microvolt = <3600000>; + maxim,thermal-regulation-celsius = <75>; + maxim,battery-overcurrent-microamp = <3000000>; + maxim,charge-input-threshold-microvolt = <4300000>; + }; }; diff --git a/Documentation/devicetree/bindings/mfd/s2mps11.txt b/Documentation/devicetree/bindings/mfd/s2mps11.txt index 0e4026a6cbbf..57a045016fca 100644 --- a/Documentation/devicetree/bindings/mfd/s2mps11.txt +++ b/Documentation/devicetree/bindings/mfd/s2mps11.txt @@ -1,5 +1,5 @@ -* Samsung S2MPS11, S2MPS14 and S2MPU02 Voltage and Current Regulator +* Samsung S2MPS11, S2MPS13, S2MPS14 and S2MPU02 Voltage and Current Regulator The Samsung S2MPS11 is a multi-function device which includes voltage and current regulators, RTC, charger controller and other sub-blocks. It is @@ -7,8 +7,8 @@ interfaced to the host controller using an I2C interface. Each sub-block is addressed by the host system using different I2C slave addresses. Required properties: -- compatible: Should be "samsung,s2mps11-pmic" or "samsung,s2mps14-pmic" - or "samsung,s2mpu02-pmic". +- compatible: Should be "samsung,s2mps11-pmic" or "samsung,s2mps13-pmic" + or "samsung,s2mps14-pmic" or "samsung,s2mpu02-pmic". - reg: Specifies the I2C slave address of the pmic block. It should be 0x66. Optional properties: @@ -17,8 +17,8 @@ Optional properties: - interrupts: Interrupt specifiers for interrupt sources. Optional nodes: -- clocks: s2mps11 and s5m8767 provide three(AP/CP/BT) buffered 32.768 KHz - outputs, so to register these as clocks with common clock framework +- clocks: s2mps11, s2mps13 and s5m8767 provide three(AP/CP/BT) buffered 32.768 + KHz outputs, so to register these as clocks with common clock framework instantiate a sub-node named "clocks". It uses the common clock binding documented in : [Documentation/devicetree/bindings/clock/clock-bindings.txt] @@ -30,12 +30,12 @@ Optional nodes: the clock which they consume. Clock ID Devices ---------------------------------------------------------- - 32KhzAP 0 S2MPS11, S2MPS14, S5M8767 - 32KhzCP 1 S2MPS11, S5M8767 - 32KhzBT 2 S2MPS11, S2MPS14, S5M8767 + 32KhzAP 0 S2MPS11, S2MPS13, S2MPS14, S5M8767 + 32KhzCP 1 S2MPS11, S2MPS13, S5M8767 + 32KhzBT 2 S2MPS11, S2MPS13, S2MPS14, S5M8767 - - compatible: Should be one of: "samsung,s2mps11-clk", "samsung,s2mps14-clk", - "samsung,s5m8767-clk" + - compatible: Should be one of: "samsung,s2mps11-clk", "samsung,s2mps13-clk", + "samsung,s2mps14-clk", "samsung,s5m8767-clk" - regulators: The regulators of s2mps11 that have to be instantiated should be included in a sub-node named 'regulators'. Regulator nodes included in this @@ -81,12 +81,14 @@ as per the datasheet of s2mps11. - LDOn - valid values for n are: - S2MPS11: 1 to 38 + - S2MPS13: 1 to 40 - S2MPS14: 1 to 25 - S2MPU02: 1 to 28 - Example: LDO1, LDO2, LDO28 - BUCKn - valid values for n are: - S2MPS11: 1 to 10 + - S2MPS13: 1 to 10 - S2MPS14: 1 to 5 - S2MPU02: 1 to 7 - Example: BUCK1, BUCK2, BUCK9 diff --git a/Documentation/devicetree/bindings/mips/brcm/bcm3384-intc.txt b/Documentation/devicetree/bindings/mips/brcm/bcm3384-intc.txt new file mode 100644 index 000000000000..d4e0141d3620 --- /dev/null +++ b/Documentation/devicetree/bindings/mips/brcm/bcm3384-intc.txt @@ -0,0 +1,37 @@ +* Interrupt Controller + +Properties: +- compatible: "brcm,bcm3384-intc" + + Compatibility with BCM3384 and possibly other BCM33xx/BCM63xx SoCs. + +- reg: Address/length pairs for each mask/status register set. Length must + be 8. If multiple register sets are specified, the first set will + handle IRQ offsets 0..31, the second set 32..63, and so on. + +- interrupt-controller: This is an interrupt controller. + +- #interrupt-cells: Must be <1>. Just a simple IRQ offset; no level/edge + or polarity configuration is possible with this controller. + +- interrupt-parent: This controller is cascaded from a MIPS CPU HW IRQ, or + from another INTC. + +- interrupts: The IRQ on the parent controller. + +Example: + periph_intc: periph_intc@14e00038 { + compatible = "brcm,bcm3384-intc"; + + /* + * IRQs 0..31: mask reg 0x14e00038, status reg 0x14e0003c + * IRQs 32..63: mask reg 0x14e00340, status reg 0x14e00344 + */ + reg = <0x14e00038 0x8 0x14e00340 0x8>; + + interrupt-controller; + #interrupt-cells = <1>; + + interrupt-parent = <&cpu_intc>; + interrupts = <4>; + }; diff --git a/Documentation/devicetree/bindings/mips/brcm/bmips.txt b/Documentation/devicetree/bindings/mips/brcm/bmips.txt new file mode 100644 index 000000000000..8ef71b4085ca --- /dev/null +++ b/Documentation/devicetree/bindings/mips/brcm/bmips.txt @@ -0,0 +1,8 @@ +* Broadcom MIPS (BMIPS) CPUs + +Required properties: +- compatible: "brcm,bmips3300", "brcm,bmips4350", "brcm,bmips4380", + "brcm,bmips5000" + +- mips-hpt-frequency: This is common to all CPUs in the system so it lives + under the "cpus" node. diff --git a/Documentation/devicetree/bindings/mips/brcm/cm-dsl.txt b/Documentation/devicetree/bindings/mips/brcm/cm-dsl.txt new file mode 100644 index 000000000000..8a139cb3c0b5 --- /dev/null +++ b/Documentation/devicetree/bindings/mips/brcm/cm-dsl.txt @@ -0,0 +1,11 @@ +* Broadcom cable/DSL platforms + +SoCs: + +Required properties: +- compatible: "brcm,bcm3384", "brcm,bcm33843" + +Boards: + +Required properties: +- compatible: "brcm,bcm93384wvg" diff --git a/Documentation/devicetree/bindings/mips/brcm/usb.txt b/Documentation/devicetree/bindings/mips/brcm/usb.txt new file mode 100644 index 000000000000..452c45c7bf29 --- /dev/null +++ b/Documentation/devicetree/bindings/mips/brcm/usb.txt @@ -0,0 +1,11 @@ +* Broadcom USB controllers + +Required properties: +- compatible: "brcm,bcm3384-ohci", "brcm,bcm3384-ehci" + + These currently use the generic-ohci and generic-ehci drivers. On some + systems, special handling may be needed in the following cases: + + - Restoring state after systemwide power save modes + - Sharing PHYs with the USBD (UDC) hardware + - Figuring out which controllers are disabled on ASIC bondout variants diff --git a/Documentation/devicetree/bindings/mips/cpu_irq.txt b/Documentation/devicetree/bindings/mips/cpu_irq.txt index 13aa4b62c62a..fc149f326dae 100644 --- a/Documentation/devicetree/bindings/mips/cpu_irq.txt +++ b/Documentation/devicetree/bindings/mips/cpu_irq.txt @@ -1,6 +1,6 @@ MIPS CPU interrupt controller -On MIPS the mips_cpu_intc_init() helper can be used to initialize the 8 CPU +On MIPS the mips_cpu_irq_of_init() helper can be used to initialize the 8 CPU IRQs from a devicetree file and create a irq_domain for IRQ controller. With the irq_domain in place we can describe how the 8 IRQs are wired to the @@ -36,7 +36,7 @@ Example devicetree: Example platform irq.c: static struct of_device_id __initdata of_irq_ids[] = { - { .compatible = "mti,cpu-interrupt-controller", .data = mips_cpu_intc_init }, + { .compatible = "mti,cpu-interrupt-controller", .data = mips_cpu_irq_of_init }, { .compatible = "ralink,rt2880-intc", .data = intc_of_init }, {}, }; diff --git a/Documentation/devicetree/bindings/misc/fsl,qoriq-mc.txt b/Documentation/devicetree/bindings/misc/fsl,qoriq-mc.txt new file mode 100644 index 000000000000..c7a26ca8da12 --- /dev/null +++ b/Documentation/devicetree/bindings/misc/fsl,qoriq-mc.txt @@ -0,0 +1,40 @@ +* Freescale Management Complex + +The Freescale Management Complex (fsl-mc) is a hardware resource +manager that manages specialized hardware objects used in +network-oriented packet processing applications. After the fsl-mc +block is enabled, pools of hardware resources are available, such as +queues, buffer pools, I/O interfaces. These resources are building +blocks that can be used to create functional hardware objects/devices +such as network interfaces, crypto accelerator instances, L2 switches, +etc. + +Required properties: + + - compatible + Value type: <string> + Definition: Must be "fsl,qoriq-mc". A Freescale Management Complex + compatible with this binding must have Block Revision + Registers BRR1 and BRR2 at offset 0x0BF8 and 0x0BFC in + the MC control register region. + + - reg + Value type: <prop-encoded-array> + Definition: A standard property. Specifies one or two regions + defining the MC's registers: + + -the first region is the command portal for the + this machine and must always be present + + -the second region is the MC control registers. This + region may not be present in some scenarios, such + as in the device tree presented to a virtual machine. + +Example: + + fsl_mc: fsl-mc@80c000000 { + compatible = "fsl,qoriq-mc"; + reg = <0x00000008 0x0c000000 0 0x40>, /* MC portal base */ + <0x00000000 0x08340000 0 0x40000>; /* MC control reg */ + }; + diff --git a/Documentation/devicetree/bindings/misc/nvidia,tegra20-apbmisc.txt b/Documentation/devicetree/bindings/misc/nvidia,tegra20-apbmisc.txt index b97b8bef1fe5..47b205cc9cc7 100644 --- a/Documentation/devicetree/bindings/misc/nvidia,tegra20-apbmisc.txt +++ b/Documentation/devicetree/bindings/misc/nvidia,tegra20-apbmisc.txt @@ -1,11 +1,10 @@ NVIDIA Tegra20/Tegra30/Tegr114/Tegra124 apbmisc block Required properties: -- compatible : should be: - "nvidia,tegra20-apbmisc" - "nvidia,tegra30-apbmisc" - "nvidia,tegra114-apbmisc" - "nvidia,tegra124-apbmisc" +- compatible : For Tegra20, must be "nvidia,tegra20-apbmisc". For Tegra30, + must be "nvidia,tegra30-apbmisc". Otherwise, must contain + "nvidia,<chip>-apbmisc", plus one of the above, where <chip> is tegra114, + tegra124, tegra132. - reg: Should contain 2 entries: the first entry gives the physical address and length of the registers which contain revision and debug features. The second entry gives the physical address and length of the diff --git a/Documentation/devicetree/bindings/mmc/exynos-dw-mshc.txt b/Documentation/devicetree/bindings/mmc/exynos-dw-mshc.txt index 6cd3525d0e09..ee4fc0576c7d 100644 --- a/Documentation/devicetree/bindings/mmc/exynos-dw-mshc.txt +++ b/Documentation/devicetree/bindings/mmc/exynos-dw-mshc.txt @@ -18,6 +18,10 @@ Required Properties: specific extensions. - "samsung,exynos5420-dw-mshc": for controllers with Samsung Exynos5420 specific extensions. + - "samsung,exynos7-dw-mshc": for controllers with Samsung Exynos7 + specific extensions. + - "samsung,exynos7-dw-mshc-smu": for controllers with Samsung Exynos7 + specific extensions having an SMU. * samsung,dw-mshc-ciu-div: Specifies the divider value for the card interface unit (ciu) clock. This property is applicable only for Exynos5 SoC's and diff --git a/Documentation/devicetree/bindings/mmc/img-dw-mshc.txt b/Documentation/devicetree/bindings/mmc/img-dw-mshc.txt new file mode 100644 index 000000000000..85de99fcaa2f --- /dev/null +++ b/Documentation/devicetree/bindings/mmc/img-dw-mshc.txt @@ -0,0 +1,29 @@ +* Imagination specific extensions to the Synopsys Designware Mobile Storage + Host Controller + +The Synopsys designware mobile storage host controller is used to interface +a SoC with storage medium such as eMMC or SD/MMC cards. This file documents +differences between the core Synopsys dw mshc controller properties described +by synopsys-dw-mshc.txt and the properties used by the Imagination specific +extensions to the Synopsys Designware Mobile Storage Host Controller. + +Required Properties: + +* compatible: should be + - "img,pistachio-dw-mshc": for Pistachio SoCs + +Example: + + mmc@18142000 { + compatible = "img,pistachio-dw-mshc"; + reg = <0x18142000 0x400>; + interrupts = <GIC_SHARED 39 IRQ_TYPE_LEVEL_HIGH>; + + clocks = <&system_clk>, <&sdhost_clk>; + clock-names = "biu", "ciu"; + + fifo-depth = <0x20>; + bus-width = <4>; + num-slots = <1>; + disable-wp; + }; diff --git a/Documentation/devicetree/bindings/mmc/mmc-pwrseq-emmc.txt b/Documentation/devicetree/bindings/mmc/mmc-pwrseq-emmc.txt new file mode 100644 index 000000000000..0cb827bf9435 --- /dev/null +++ b/Documentation/devicetree/bindings/mmc/mmc-pwrseq-emmc.txt @@ -0,0 +1,25 @@ +* The simple eMMC hardware reset provider + +The purpose of this driver is to perform standard eMMC hw reset +procedure, as descibed by Jedec 4.4 specification. This procedure is +performed just after MMC core enabled power to the given mmc host (to +fix possible issues if bootloader has left eMMC card in initialized or +unknown state), and before performing complete system reboot (also in +case of emergency reboot call). The latter is needed on boards, which +doesn't have hardware reset logic connected to emmc card and (limited or +broken) ROM bootloaders are unable to read second stage from the emmc +card if the card is left in unknown or already initialized state. + +Required properties: +- compatible : contains "mmc-pwrseq-emmc". +- reset-gpios : contains a GPIO specifier. The reset GPIO is asserted + and then deasserted to perform eMMC card reset. To perform + reset procedure as described in Jedec 4.4 specification, the + gpio line should be defined as GPIO_ACTIVE_LOW. + +Example: + + sdhci0_pwrseq { + compatible = "mmc-pwrseq-emmc"; + reset-gpios = <&gpio1 12 GPIO_ACTIVE_LOW>; + } diff --git a/Documentation/devicetree/bindings/mmc/mmc-pwrseq-simple.txt b/Documentation/devicetree/bindings/mmc/mmc-pwrseq-simple.txt new file mode 100644 index 000000000000..a462c50f19a8 --- /dev/null +++ b/Documentation/devicetree/bindings/mmc/mmc-pwrseq-simple.txt @@ -0,0 +1,25 @@ +* The simple MMC power sequence provider + +The purpose of the simple MMC power sequence provider is to supports a set of +common properties between various SOC designs. It thus enables us to use the +same provider for several SOC designs. + +Required properties: +- compatible : contains "mmc-pwrseq-simple". + +Optional properties: +- reset-gpios : contains a list of GPIO specifiers. The reset GPIOs are asserted + at initialization and prior we start the power up procedure of the card. + They will be de-asserted right after the power has been provided to the + card. +- clocks : Must contain an entry for the entry in clock-names. + See ../clocks/clock-bindings.txt for details. +- clock-names : Must include the following entry: + "ext_clock" (External clock provided to the card). + +Example: + + sdhci0_pwrseq { + compatible = "mmc-pwrseq-simple"; + reset-gpios = <&gpio1 12 0>; + } diff --git a/Documentation/devicetree/bindings/mmc/mmc.txt b/Documentation/devicetree/bindings/mmc/mmc.txt index b52628b18a53..438899e8829b 100644 --- a/Documentation/devicetree/bindings/mmc/mmc.txt +++ b/Documentation/devicetree/bindings/mmc/mmc.txt @@ -64,7 +64,43 @@ Optional SDIO properties: - keep-power-in-suspend: Preserves card power during a suspend/resume cycle - enable-sdio-wakeup: Enables wake up of host system on SDIO IRQ assertion -Example: + +MMC power sequences: +-------------------- + +System on chip designs may specify a specific MMC power sequence. To +successfully detect an (e)MMC/SD/SDIO card, that power sequence must be +maintained while initializing the card. + +Optional property: +- mmc-pwrseq: phandle to the MMC power sequence node. See "mmc-pwrseq-*" + for documentation of MMC power sequence bindings. + + +Use of Function subnodes +------------------------ + +On embedded systems the cards connected to a host may need additional +properties. These can be specified in subnodes to the host controller node. +The subnodes are identified by the standard 'reg' property. +Which information exactly can be specified depends on the bindings for the +SDIO function driver for the subnode, as specified by the compatible string. + +Required host node properties when using function subnodes: +- #address-cells: should be one. The cell is the slot id. +- #size-cells: should be zero. + +Required function subnode properties: +- compatible: name of SDIO function following generic names recommended practice +- reg: Must contain the SDIO function number of the function this subnode + describes. A value of 0 denotes the memory SD function, values from + 1 to 7 denote the SDIO functions. + + +Examples +-------- + +Basic example: sdhci@ab000000 { compatible = "sdhci"; @@ -77,4 +113,28 @@ sdhci@ab000000 { max-frequency = <50000000>; keep-power-in-suspend; enable-sdio-wakeup; + mmc-pwrseq = <&sdhci0_pwrseq> } + +Example with sdio function subnode: + +mmc3: mmc@01c12000 { + #address-cells = <1>; + #size-cells = <0>; + + pinctrl-names = "default"; + pinctrl-0 = <&mmc3_pins_a>; + vmmc-supply = <®_vmmc3>; + bus-width = <4>; + non-removable; + mmc-pwrseq = <&sdhci0_pwrseq> + status = "okay"; + + brcmf: bcrmf@1 { + reg = <1>; + compatible = "brcm,bcm43xx-fmac"; + interrupt-parent = <&pio>; + interrupts = <10 8>; /* PH10 / EINT10 */ + interrupt-names = "host-wake"; + }; +}; diff --git a/Documentation/devicetree/bindings/mmc/nvidia,tegra20-sdhci.txt b/Documentation/devicetree/bindings/mmc/nvidia,tegra20-sdhci.txt index f357c16ea815..15b8368ee1f2 100644 --- a/Documentation/devicetree/bindings/mmc/nvidia,tegra20-sdhci.txt +++ b/Documentation/devicetree/bindings/mmc/nvidia,tegra20-sdhci.txt @@ -7,7 +7,11 @@ This file documents differences between the core properties described by mmc.txt and the properties used by the sdhci-tegra driver. Required properties: -- compatible : Should be "nvidia,<chip>-sdhci" +- compatible : For Tegra20, must contain "nvidia,tegra20-sdhci". + For Tegra30, must contain "nvidia,tegra30-sdhci". For Tegra114, + must contain "nvidia,tegra114-sdhci". For Tegra124, must contain + "nvidia,tegra124-sdhci". Otherwise, must contain "nvidia,<chip>-sdhci", + plus one of the above, where <chip> is tegra132 or tegra210. - clocks : Must contain one entry, for the module clock. See ../clocks/clock-bindings.txt for details. - resets : Must contain an entry for each entry in reset-names. diff --git a/Documentation/devicetree/bindings/mmc/sdhci-fujitsu.txt b/Documentation/devicetree/bindings/mmc/sdhci-fujitsu.txt new file mode 100644 index 000000000000..de2c53cff4f1 --- /dev/null +++ b/Documentation/devicetree/bindings/mmc/sdhci-fujitsu.txt @@ -0,0 +1,30 @@ +* Fujitsu SDHCI controller + +This file documents differences between the core properties in mmc.txt +and the properties used by the sdhci_f_sdh30 driver. + +Required properties: +- compatible: "fujitsu,mb86s70-sdhci-3.0" +- clocks: Must contain an entry for each entry in clock-names. It is a + list of phandles and clock-specifier pairs. + See ../clocks/clock-bindings.txt for details. +- clock-names: Should contain the following two entries: + "iface" - clock used for sdhci interface + "core" - core clock for sdhci controller + +Optional properties: +- vqmmc-supply: phandle to the regulator device tree node, mentioned + as the VCCQ/VDD_IO supply in the eMMC/SD specs. + +Example: + + sdhci1: mmc@36600000 { + compatible = "fujitsu,mb86s70-sdhci-3.0"; + reg = <0 0x36600000 0x1000>; + interrupts = <0 172 0x4>, + <0 173 0x4>; + bus-width = <4>; + vqmmc-supply = <&vccq_sdhci1>; + clocks = <&clock 2 2 0>, <&clock 2 3 0>; + clock-names = "iface", "core"; + }; diff --git a/Documentation/devicetree/bindings/mmc/sdhci-pxa.txt b/Documentation/devicetree/bindings/mmc/sdhci-pxa.txt index 86223c3eda90..3d1b449d6097 100644 --- a/Documentation/devicetree/bindings/mmc/sdhci-pxa.txt +++ b/Documentation/devicetree/bindings/mmc/sdhci-pxa.txt @@ -9,9 +9,17 @@ Required properties: - reg: * for "mrvl,pxav2-mmc" and "mrvl,pxav3-mmc", one register area for the SDHCI registers. - * for "marvell,armada-380-sdhci", two register areas. The first one - for the SDHCI registers themselves, and the second one for the - AXI/Mbus bridge registers of the SDHCI unit. + + * for "marvell,armada-380-sdhci", three register areas. The first + one for the SDHCI registers themselves, the second one for the + AXI/Mbus bridge registers of the SDHCI unit, the third one for the + SDIO3 Configuration register +- reg names: should be "sdhci", "mbus", "conf-sdio3". only mandatory + for "marvell,armada-380-sdhci" +- clocks: Array of clocks required for SDHCI; requires at least one for + I/O clock. +- clock-names: Array of names corresponding to clocks property; shall be + "io" for I/O clock and "core" for optional core clock. Optional properties: - mrvl,clk-delay-cycles: Specify a number of cycles to delay for tuning. @@ -23,14 +31,20 @@ sdhci@d4280800 { reg = <0xd4280800 0x800>; bus-width = <8>; interrupts = <27>; + clocks = <&chip CLKID_SDIO1XIN>, <&chip CLKID_SDIO1>; + clock-names = "io", "core"; non-removable; mrvl,clk-delay-cycles = <31>; }; sdhci@d8000 { compatible = "marvell,armada-380-sdhci"; - reg = <0xd8000 0x1000>, <0xdc000 0x100>; + reg-names = "sdhci", "mbus", "conf-sdio3"; + reg = <0xd8000 0x1000>, + <0xdc000 0x100>; + <0x18454 0x4>; interrupts = <0 25 0x4>; clocks = <&gateclk 17>; + clock-names = "io"; mrvl,clk-delay-cycles = <0x1F>; }; diff --git a/Documentation/devicetree/bindings/mtd/atmel-nand.txt b/Documentation/devicetree/bindings/mtd/atmel-nand.txt index 6edc3b616e98..1fe6dde98499 100644 --- a/Documentation/devicetree/bindings/mtd/atmel-nand.txt +++ b/Documentation/devicetree/bindings/mtd/atmel-nand.txt @@ -5,7 +5,9 @@ Required properties: - reg : should specify localbus address and size used for the chip, and hardware ECC controller if available. If the hardware ECC is PMECC, it should contain address and size for - PMECC, PMECC Error Location controller and ROM which has lookup tables. + PMECC and PMECC Error Location controller. + The PMECC lookup table address and size in ROM is optional. If not + specified, driver will build it in runtime. - atmel,nand-addr-offset : offset for the address latch. - atmel,nand-cmd-offset : offset for the command latch. - #address-cells, #size-cells : Must be present if the device has sub-nodes @@ -27,7 +29,7 @@ Optional properties: are: 512, 1024. - atmel,pmecc-lookup-table-offset : includes two offsets of lookup table in ROM for different sector size. First one is for sector size 512, the next is for - sector size 1024. + sector size 1024. If not specified, driver will build the table in runtime. - nand-bus-width : 8 or 16 bus width if not present 8 - nand-on-flash-bbt: boolean to enable on flash bbt option if not present false - Nand Flash Controller(NFC) is a slave driver under Atmel nand flash diff --git a/Documentation/devicetree/bindings/mtd/diskonchip.txt b/Documentation/devicetree/bindings/mtd/diskonchip.txt new file mode 100644 index 000000000000..3e13bfdbea5b --- /dev/null +++ b/Documentation/devicetree/bindings/mtd/diskonchip.txt @@ -0,0 +1,15 @@ +M-Systems and Sandisk DiskOnChip devices + +M-System DiskOnChip G3 +====================== +The Sandisk (formerly M-Systems) docg3 is a nand device of 64M to 256MB. + +Required properties: + - compatible: should be "m-systems,diskonchip-g3" + - reg: register base and size + +Example: + docg3: flash@0 { + compatible = "m-systems,diskonchip-g3"; + reg = <0x0 0x2000>; + }; diff --git a/Documentation/devicetree/bindings/mtd/fsmc-nand.txt b/Documentation/devicetree/bindings/mtd/fsmc-nand.txt index ec42935f3908..5235cbc551b0 100644 --- a/Documentation/devicetree/bindings/mtd/fsmc-nand.txt +++ b/Documentation/devicetree/bindings/mtd/fsmc-nand.txt @@ -9,7 +9,7 @@ Required properties: Optional properties: - bank-width : Width (in bytes) of the device. If not present, the width defaults to 1 byte -- nand-skip-bbtscan: Indicates the the BBT scanning should be skipped +- nand-skip-bbtscan: Indicates the BBT scanning should be skipped - timings: array of 6 bytes for NAND timings. The meanings of these bytes are: byte 0 TCLR : CLE to RE delay in number of AHB clock cycles, only 4 bits diff --git a/Documentation/devicetree/bindings/mtd/gpio-control-nand.txt b/Documentation/devicetree/bindings/mtd/gpio-control-nand.txt index 36ef07d3c90f..af8915b41ccf 100644 --- a/Documentation/devicetree/bindings/mtd/gpio-control-nand.txt +++ b/Documentation/devicetree/bindings/mtd/gpio-control-nand.txt @@ -11,8 +11,8 @@ Required properties: are made in native endianness. - #address-cells, #size-cells : Must be present if the device has sub-nodes representing partitions. -- gpios : specifies the gpio pins to control the NAND device. nwp is an - optional gpio and may be set to 0 if not present. +- gpios : Specifies the GPIO pins to control the NAND device. The order of + GPIO references is: RDY, nCE, ALE, CLE, and an optional nWP. Optional properties: - bank-width : Width (in bytes) of the device. If not present, the width @@ -35,11 +35,11 @@ gpio-nand@1,0 { reg = <1 0x0000 0x2>; #address-cells = <1>; #size-cells = <1>; - gpios = <&banka 1 0 /* rdy */ - &banka 2 0 /* nce */ - &banka 3 0 /* ale */ - &banka 4 0 /* cle */ - 0 /* nwp */>; + gpios = <&banka 1 0>, /* RDY */ + <&banka 2 0>, /* nCE */ + <&banka 3 0>, /* ALE */ + <&banka 4 0>, /* CLE */ + <0>; /* nWP */ partition@0 { ... diff --git a/Documentation/devicetree/bindings/mtd/sunxi-nand.txt b/Documentation/devicetree/bindings/mtd/sunxi-nand.txt new file mode 100644 index 000000000000..0273adb8638c --- /dev/null +++ b/Documentation/devicetree/bindings/mtd/sunxi-nand.txt @@ -0,0 +1,45 @@ +Allwinner NAND Flash Controller (NFC) + +Required properties: +- compatible : "allwinner,sun4i-a10-nand". +- reg : shall contain registers location and length for data and reg. +- interrupts : shall define the nand controller interrupt. +- #address-cells: shall be set to 1. Encode the nand CS. +- #size-cells : shall be set to 0. +- clocks : shall reference nand controller clocks. +- clock-names : nand controller internal clock names. Shall contain : + * "ahb" : AHB gating clock + * "mod" : nand controller clock + +Optional children nodes: +Children nodes represent the available nand chips. + +Optional properties: +- allwinner,rb : shall contain the native Ready/Busy ids. + or +- rb-gpios : shall contain the gpios used as R/B pins. +- nand-ecc-mode : one of the supported ECC modes ("hw", "hw_syndrome", "soft", + "soft_bch" or "none") + +see Documentation/devicetree/mtd/nand.txt for generic bindings. + + +Examples: +nfc: nand@01c03000 { + compatible = "allwinner,sun4i-a10-nand"; + reg = <0x01c03000 0x1000>; + interrupts = <0 37 1>; + clocks = <&ahb_gates 13>, <&nand_clk>; + clock-names = "ahb", "mod"; + #address-cells = <1>; + #size-cells = <0>; + pinctrl-names = "default"; + pinctrl-0 = <&nand_pins_a &nand_cs0_pins_a &nand_rb0_pins_a>; + status = "okay"; + + nand@0 { + reg = <0>; + allwinner,rb = <0>; + nand-ecc-mode = "soft_bch"; + }; +}; diff --git a/Documentation/devicetree/bindings/net/amd-xgbe-phy.txt b/Documentation/devicetree/bindings/net/amd-xgbe-phy.txt index 42409bfe04c4..33df3932168e 100644 --- a/Documentation/devicetree/bindings/net/amd-xgbe-phy.txt +++ b/Documentation/devicetree/bindings/net/amd-xgbe-phy.txt @@ -7,17 +7,38 @@ Required properties: - SerDes Rx/Tx registers - SerDes integration registers (1/2) - SerDes integration registers (2/2) +- interrupt-parent: Should be the phandle for the interrupt controller + that services interrupts for this device +- interrupts: Should contain the amd-xgbe-phy interrupt. Optional properties: - amd,speed-set: Speed capabilities of the device 0 - 1GbE and 10GbE (default) 1 - 2.5GbE and 10GbE +The following optional properties are represented by an array with each +value corresponding to a particular speed. The first array value represents +the setting for the 1GbE speed, the second value for the 2.5GbE speed and +the third value for the 10GbE speed. All three values are required if the +property is used. +- amd,serdes-blwc: Baseline wandering correction enablement + 0 - Off + 1 - On +- amd,serdes-cdr-rate: CDR rate speed selection +- amd,serdes-pq-skew: PQ (data sampling) skew +- amd,serdes-tx-amp: TX amplitude boost + Example: xgbe_phy@e1240800 { compatible = "amd,xgbe-phy-seattle-v1a", "ethernet-phy-ieee802.3-c45"; reg = <0 0xe1240800 0 0x00400>, <0 0xe1250000 0 0x00060>, <0 0xe1250080 0 0x00004>; + interrupt-parent = <&gic>; + interrupts = <0 323 4>; amd,speed-set = <0>; + amd,serdes-blwc = <1>, <1>, <0>; + amd,serdes-cdr-rate = <2>, <2>, <7>; + amd,serdes-pq-skew = <10>, <10>, <30>; + amd,serdes-tx-amp = <15>, <15>, <10>; }; diff --git a/Documentation/devicetree/bindings/net/amd-xgbe.txt b/Documentation/devicetree/bindings/net/amd-xgbe.txt index 41354f730beb..26efd526d16c 100644 --- a/Documentation/devicetree/bindings/net/amd-xgbe.txt +++ b/Documentation/devicetree/bindings/net/amd-xgbe.txt @@ -7,7 +7,10 @@ Required properties: - PCS registers - interrupt-parent: Should be the phandle for the interrupt controller that services interrupts for this device -- interrupts: Should contain the amd-xgbe interrupt +- interrupts: Should contain the amd-xgbe interrupt(s). The first interrupt + listed is required and is the general device interrupt. If the optional + amd,per-channel-interrupt property is specified, then one additional + interrupt for each DMA channel supported by the device should be specified - clocks: - DMA clock for the amd-xgbe device (used for calculating the correct Rx interrupt watchdog timer value on a DMA channel @@ -23,6 +26,9 @@ Optional properties: - mac-address: mac address to be assigned to the device. Can be overridden by UEFI. - dma-coherent: Present if dma operations are coherent +- amd,per-channel-interrupt: Indicates that Rx and Tx complete will generate + a unique interrupt for each DMA channel - this requires an additional + interrupt be configured for each DMA channel Example: xgbe@e0700000 { @@ -30,7 +36,9 @@ Example: reg = <0 0xe0700000 0 0x80000>, <0 0xe0780000 0 0x80000>; interrupt-parent = <&gic>; - interrupts = <0 325 4>; + interrupts = <0 325 4>, + <0 326 1>, <0 327 1>, <0 328 1>, <0 329 1>; + amd,per-channel-interrupt; clocks = <&xgbe_dma_clk>, <&xgbe_ptp_clk>; clock-names = "dma_clk", "ptp_clk"; phy-handle = <&phy>; diff --git a/Documentation/devicetree/bindings/net/broadcom-systemport.txt b/Documentation/devicetree/bindings/net/broadcom-systemport.txt index aa7ad622259d..877da34145b0 100644 --- a/Documentation/devicetree/bindings/net/broadcom-systemport.txt +++ b/Documentation/devicetree/bindings/net/broadcom-systemport.txt @@ -3,7 +3,7 @@ Required properties: - compatible: should be one of "brcm,systemport-v1.00" or "brcm,systemport" - reg: address and length of the register set for the device. -- interrupts: interrupts for the device, first cell must be for the the rx +- interrupts: interrupts for the device, first cell must be for the rx interrupts, and the second cell should be for the transmit queues. An optional third interrupt cell for Wake-on-LAN can be specified - local-mac-address: Ethernet MAC address (48 bits) of this adapter diff --git a/Documentation/devicetree/bindings/net/can/c_can.txt b/Documentation/devicetree/bindings/net/can/c_can.txt index 8f1ae81228e3..5a1d8b0c39e9 100644 --- a/Documentation/devicetree/bindings/net/can/c_can.txt +++ b/Documentation/devicetree/bindings/net/can/c_can.txt @@ -4,6 +4,8 @@ Bosch C_CAN/D_CAN controller Device Tree Bindings Required properties: - compatible : Should be "bosch,c_can" for C_CAN controllers and "bosch,d_can" for D_CAN controllers. + Can be "ti,dra7-d_can", "ti,am3352-d_can" or + "ti,am4372-d_can". - reg : physical base address and size of the C_CAN/D_CAN registers map - interrupts : property with a value describing the interrupt @@ -12,6 +14,9 @@ Required properties: Optional properties: - ti,hwmods : Must be "d_can<n>" or "c_can<n>", n being the instance number +- syscon-raminit : Handle to system control region that contains the + RAMINIT register, register offset to the RAMINIT + register and the CAN instance number (0 offset). Note: "ti,hwmods" field is used to fetch the base address and irq resources from TI, omap hwmod data base during device registration. diff --git a/Documentation/devicetree/bindings/net/davicom-dm9000.txt b/Documentation/devicetree/bindings/net/davicom-dm9000.txt index 28767ed7c1bd..5224bf05f6f8 100644 --- a/Documentation/devicetree/bindings/net/davicom-dm9000.txt +++ b/Documentation/devicetree/bindings/net/davicom-dm9000.txt @@ -11,6 +11,8 @@ Required properties: Optional properties: - davicom,no-eeprom : Configuration EEPROM is not available - davicom,ext-phy : Use external PHY +- reset-gpios : phandle of gpio that will be used to reset chip during probe +- vcc-supply : phandle of regulator that will be used to enable power to chip Example: @@ -21,4 +23,6 @@ Example: interrupts = <7 4>; local-mac-address = [00 00 de ad be ef]; davicom,no-eeprom; + reset-gpios = <&gpf 12 GPIO_ACTIVE_LOW>; + vcc-supply = <ð0_power>; }; diff --git a/Documentation/devicetree/bindings/net/davinci_emac.txt b/Documentation/devicetree/bindings/net/davinci_emac.txt index 032808843f90..24c5cdaba8d2 100644 --- a/Documentation/devicetree/bindings/net/davinci_emac.txt +++ b/Documentation/devicetree/bindings/net/davinci_emac.txt @@ -4,7 +4,8 @@ This file provides information, what the device node for the davinci_emac interface contains. Required properties: -- compatible: "ti,davinci-dm6467-emac" or "ti,am3517-emac" +- compatible: "ti,davinci-dm6467-emac", "ti,am3517-emac" or + "ti,dm816-emac" - reg: Offset and length of the register set for the device - ti,davinci-ctrl-reg-offset: offset to control register - ti,davinci-ctrl-mod-reg-offset: offset to control module register diff --git a/Documentation/devicetree/bindings/net/dsa/dsa.txt b/Documentation/devicetree/bindings/net/dsa/dsa.txt index a62c889aafca..e124847443f8 100644 --- a/Documentation/devicetree/bindings/net/dsa/dsa.txt +++ b/Documentation/devicetree/bindings/net/dsa/dsa.txt @@ -10,7 +10,7 @@ Required properties: - dsa,ethernet : Should be a phandle to a valid Ethernet device node - dsa,mii-bus : Should be a phandle to a valid MDIO bus device node -Optionnal properties: +Optional properties: - interrupts : property with a value describing the switch interrupt number (not supported by the driver) @@ -23,6 +23,13 @@ Each of these switch child nodes should have the following required properties: - #address-cells : Must be 1 - #size-cells : Must be 0 +A switch child node has the following optional property: + +- eeprom-length : Set to the length of an EEPROM connected to the + switch. Must be set if the switch can not detect + the presence and/or size of a connected EEPROM, + otherwise optional. + A switch may have multiple "port" children nodes Each port children node must have the following mandatory properties: diff --git a/Documentation/devicetree/bindings/net/fsl-fec.txt b/Documentation/devicetree/bindings/net/fsl-fec.txt index 0c8775c45798..a9eb611bee68 100644 --- a/Documentation/devicetree/bindings/net/fsl-fec.txt +++ b/Documentation/devicetree/bindings/net/fsl-fec.txt @@ -22,6 +22,8 @@ Optional properties: - fsl,num-rx-queues : The property is valid for enet-avb IP, which supports hw multi queues. Should specify the rx queue number, otherwise set rx queue number to 1. +- fsl,magic-packet : If present, indicates that the hardware supports waking + up via magic packet. Optional subnodes: - mdio : specifies the mdio bus in the FEC, used as a container for phy nodes diff --git a/Documentation/devicetree/bindings/net/fsl-tsec-phy.txt b/Documentation/devicetree/bindings/net/fsl-tsec-phy.txt index be6ea8960f20..1e97532a0b79 100644 --- a/Documentation/devicetree/bindings/net/fsl-tsec-phy.txt +++ b/Documentation/devicetree/bindings/net/fsl-tsec-phy.txt @@ -8,7 +8,16 @@ of how to define a PHY. Required properties: - reg : Offset and length of the register set for the device - compatible : Should define the compatible device type for the - mdio. Currently, this is most likely to be "fsl,gianfar-mdio" + mdio. Currently supported strings/devices are: + - "fsl,gianfar-tbi" + - "fsl,gianfar-mdio" + - "fsl,etsec2-tbi" + - "fsl,etsec2-mdio" + - "fsl,ucc-mdio" + - "fsl,fman-mdio" + When device_type is "mdio", the following strings are also considered: + - "gianfar" + - "ucc_geth_phy" Example: diff --git a/Documentation/devicetree/bindings/net/hisilicon-hip04-net.txt b/Documentation/devicetree/bindings/net/hisilicon-hip04-net.txt new file mode 100644 index 000000000000..988fc694b663 --- /dev/null +++ b/Documentation/devicetree/bindings/net/hisilicon-hip04-net.txt @@ -0,0 +1,88 @@ +Hisilicon hip04 Ethernet Controller + +* Ethernet controller node + +Required properties: +- compatible: should be "hisilicon,hip04-mac". +- reg: address and length of the register set for the device. +- interrupts: interrupt for the device. +- port-handle: <phandle port channel> + phandle, specifies a reference to the syscon ppe node + port, port number connected to the controller + channel, recv channel start from channel * number (RX_DESC_NUM) +- phy-mode: see ethernet.txt [1]. + +Optional properties: +- phy-handle: see ethernet.txt [1]. + +[1] Documentation/devicetree/bindings/net/ethernet.txt + + +* Ethernet ppe node: +Control rx & tx fifos of all ethernet controllers. +Have 2048 recv channels shared by all ethernet controllers, only if no overlap. +Each controller's recv channel start from channel * number (RX_DESC_NUM). + +Required properties: +- compatible: "hisilicon,hip04-ppe", "syscon". +- reg: address and length of the register set for the device. + + +* MDIO bus node: + +Required properties: + +- compatible: should be "hisilicon,hip04-mdio". +- Inherits from MDIO bus node binding [2] +[2] Documentation/devicetree/bindings/net/phy.txt + +Example: + mdio { + compatible = "hisilicon,hip04-mdio"; + reg = <0x28f1000 0x1000>; + #address-cells = <1>; + #size-cells = <0>; + + phy0: ethernet-phy@0 { + compatible = "ethernet-phy-ieee802.3-c22"; + reg = <0>; + marvell,reg-init = <18 0x14 0 0x8001>; + }; + + phy1: ethernet-phy@1 { + compatible = "ethernet-phy-ieee802.3-c22"; + reg = <1>; + marvell,reg-init = <18 0x14 0 0x8001>; + }; + }; + + ppe: ppe@28c0000 { + compatible = "hisilicon,hip04-ppe", "syscon"; + reg = <0x28c0000 0x10000>; + }; + + fe: ethernet@28b0000 { + compatible = "hisilicon,hip04-mac"; + reg = <0x28b0000 0x10000>; + interrupts = <0 413 4>; + phy-mode = "mii"; + port-handle = <&ppe 31 0>; + }; + + ge0: ethernet@2800000 { + compatible = "hisilicon,hip04-mac"; + reg = <0x2800000 0x10000>; + interrupts = <0 402 4>; + phy-mode = "sgmii"; + port-handle = <&ppe 0 1>; + phy-handle = <&phy0>; + }; + + ge8: ethernet@2880000 { + compatible = "hisilicon,hip04-mac"; + reg = <0x2880000 0x10000>; + interrupts = <0 410 4>; + phy-mode = "sgmii"; + port-handle = <&ppe 8 2>; + phy-handle = <&phy1>; + }; diff --git a/Documentation/devicetree/bindings/net/keystone-netcp.txt b/Documentation/devicetree/bindings/net/keystone-netcp.txt new file mode 100644 index 000000000000..f9c07710478d --- /dev/null +++ b/Documentation/devicetree/bindings/net/keystone-netcp.txt @@ -0,0 +1,197 @@ +This document describes the device tree bindings associated with the +keystone network coprocessor(NetCP) driver support. + +The network coprocessor (NetCP) is a hardware accelerator that processes +Ethernet packets. NetCP has a gigabit Ethernet (GbE) subsytem with a ethernet +switch sub-module to send and receive packets. NetCP also includes a packet +accelerator (PA) module to perform packet classification operations such as +header matching, and packet modification operations such as checksum +generation. NetCP can also optionally include a Security Accelerator (SA) +capable of performing IPSec operations on ingress/egress packets. + +Keystone II SoC's also have a 10 Gigabit Ethernet Subsystem (XGbE) which +includes a 3-port Ethernet switch sub-module capable of 10Gb/s and 1Gb/s rates +per Ethernet port. + +Keystone NetCP driver has a plug-in module architecture where each of the NetCP +sub-modules exist as a loadable kernel module which plug in to the netcp core. +These sub-modules are represented as "netcp-devices" in the dts bindings. It is +mandatory to have the ethernet switch sub-module for the ethernet interface to +be operational. Any other sub-module like the PA is optional. + +NetCP Ethernet SubSystem Layout: + +----------------------------- + NetCP subsystem(10G or 1G) +----------------------------- + | + |-> NetCP Devices -> | + | |-> GBE/XGBE Switch + | | + | |-> Packet Accelerator + | | + | |-> Security Accelerator + | + | + | + |-> NetCP Interfaces -> | + |-> Ethernet Port 0 + | + |-> Ethernet Port 1 + | + |-> Ethernet Port 2 + | + |-> Ethernet Port 3 + + +NetCP subsystem properties: +Required properties: +- compatible: Should be "ti,netcp-1.0" +- clocks: phandle to the reference clocks for the subsystem. +- dma-id: Navigator packet dma instance id. + +Optional properties: +- reg: register location and the size for the following register + regions in the specified order. + - Efuse MAC address register +- dma-coherent: Present if dma operations are coherent +- big-endian: Keystone devices can be operated in a mode where the DSP is in + the big endian mode. In such cases enable this option. This + option should also be enabled if the ARM is operated in + big endian mode with the DSP in little endian. + +NetCP device properties: Device specification for NetCP sub-modules. +1Gb/10Gb (gbe/xgbe) ethernet switch sub-module specifications. +Required properties: +- label: Must be "netcp-gbe" for 1Gb & "netcp-xgbe" for 10Gb. +- reg: register location and the size for the following register + regions in the specified order. + - subsystem registers + - serdes registers +- tx-channel: the navigator packet dma channel name for tx. +- tx-queue: the navigator queue number associated with the tx dma channel. +- interfaces: specification for each of the switch port to be registered as a + network interface in the stack. +-- slave-port: Switch port number, 0 based numbering. +-- link-interface: type of link interface, supported options are + - mac<->mac auto negotiate mode: 0 + - mac<->phy mode: 1 + - mac<->mac forced mode: 2 + - mac<->fiber mode: 3 + - mac<->phy mode with no mdio: 4 + - 10Gb mac<->phy mode : 10 + - 10Gb mac<->mac forced mode : 11 +----phy-handle: phandle to PHY device + +Optional properties: +- enable-ale: NetCP driver keeps the address learning feature in the ethernet + switch module disabled. This attribute is to enable the address + learning. +- secondary-slave-ports: specification for each of the switch port not be + registered as a network interface. NetCP driver + will only initialize these ports and attach PHY + driver to them if needed. + +NetCP interface properties: Interface specification for NetCP sub-modules. +Required properties: +- rx-channel: the navigator packet dma channel name for rx. +- rx-queue: the navigator queue number associated with rx dma channel. +- rx-pool: specifies the number of descriptors to be used & the region-id + for creating the rx descriptor pool. +- tx-pool: specifies the number of descriptors to be used & the region-id + for creating the tx descriptor pool. +- rx-queue-depth: number of descriptors in each of the free descriptor + queue (FDQ) for the pktdma Rx flow. There can be at + present a maximum of 4 queues per Rx flow. +- rx-buffer-size: the buffer size for each of the Rx flow FDQ. +- tx-completion-queue: the navigator queue number where the descriptors are + recycled after Tx DMA completion. + +Optional properties: +- efuse-mac: If this is 1, then the MAC address for the interface is + obtained from the device efuse mac address register +- local-mac-address: the driver is designed to use the of_get_mac_address api + only if efuse-mac is 0. When efuse-mac is 0, the MAC + address is obtained from local-mac-address. If this + attribute is not present, then the driver will use a + random MAC address. +- "netcp-device label": phandle to the device specification for each of NetCP + sub-module attached to this interface. + +Example binding: + +netcp: netcp@2090000 { + reg = <0x2620110 0x8>; + reg-names = "efuse"; + compatible = "ti,netcp-1.0"; + #address-cells = <1>; + #size-cells = <1>; + ranges; + + clocks = <&papllclk>, <&clkcpgmac>, <&chipclk12>; + dma-coherent; + /* big-endian; */ + dma-id = <0>; + + netcp-devices { + #address-cells = <1>; + #size-cells = <1>; + ranges; + gbe@0x2090000 { + label = "netcp-gbe"; + reg = <0x2090000 0xf00>; + /* enable-ale; */ + tx-queue = <648>; + tx-channel = <8>; + + interfaces { + gbe0: interface-0 { + slave-port = <0>; + link-interface = <4>; + }; + gbe1: interface-1 { + slave-port = <1>; + link-interface = <4>; + }; + }; + + secondary-slave-ports { + port-2 { + slave-port = <2>; + link-interface = <2>; + }; + port-3 { + slave-port = <3>; + link-interface = <2>; + }; + }; + }; + }; + + netcp-interfaces { + interface-0 { + rx-channel = <22>; + rx-pool = <1024 12>; + tx-pool = <1024 12>; + rx-queue-depth = <128 128 0 0>; + rx-buffer-size = <1518 4096 0 0>; + rx-queue = <8704>; + tx-completion-queue = <8706>; + efuse-mac = <1>; + netcp-gbe = <&gbe0>; + + }; + interface-1 { + rx-channel = <23>; + rx-pool = <1024 12>; + tx-pool = <1024 12>; + rx-queue-depth = <128 128 0 0>; + rx-buffer-size = <1518 4096 0 0>; + rx-queue = <8705>; + tx-completion-queue = <8707>; + efuse-mac = <0>; + local-mac-address = [02 18 31 7e 3e 6f]; + netcp-gbe = <&gbe1>; + }; + }; +}; diff --git a/Documentation/devicetree/bindings/net/micrel.txt b/Documentation/devicetree/bindings/net/micrel.txt index e1d99b95c4ec..87496a8c64ab 100644 --- a/Documentation/devicetree/bindings/net/micrel.txt +++ b/Documentation/devicetree/bindings/net/micrel.txt @@ -6,19 +6,32 @@ Optional properties: - micrel,led-mode : LED mode value to set for PHYs with configurable LEDs. - Configure the LED mode with single value. The list of PHYs and - the bits that are currently supported: + Configure the LED mode with single value. The list of PHYs and the + bits that are currently supported: - KSZ8001: register 0x1e, bits 15..14 - KSZ8041: register 0x1e, bits 15..14 - KSZ8021: register 0x1f, bits 5..4 - KSZ8031: register 0x1f, bits 5..4 - KSZ8051: register 0x1f, bits 5..4 + KSZ8001: register 0x1e, bits 15..14 + KSZ8041: register 0x1e, bits 15..14 + KSZ8021: register 0x1f, bits 5..4 + KSZ8031: register 0x1f, bits 5..4 + KSZ8051: register 0x1f, bits 5..4 + KSZ8081: register 0x1f, bits 5..4 + KSZ8091: register 0x1f, bits 5..4 - See the respective PHY datasheet for the mode values. + See the respective PHY datasheet for the mode values. + + - micrel,rmii-reference-clock-select-25-mhz: RMII Reference Clock Select + bit selects 25 MHz mode + + Setting the RMII Reference Clock Select bit enables 25 MHz rather + than 50 MHz clock mode. + + Note that this option in only needed for certain PHY revisions with a + non-standard, inverted function of this configuration bit. + Specifically, a clock reference ("rmii-ref" below) is always needed to + actually select a mode. - clocks, clock-names: contains clocks according to the common clock bindings. - supported clocks: - - KSZ8021, KSZ8031: "rmii-ref": The RMII refence input clock. Used - to determine the XI input clock. + supported clocks: + - KSZ8021, KSZ8031, KSZ8081, KSZ8091: "rmii-ref": The RMII reference + input clock. Used to determine the XI input clock. diff --git a/Documentation/devicetree/bindings/net/nfc/st21nfca.txt b/Documentation/devicetree/bindings/net/nfc/st21nfca.txt index e4faa2e8dfeb..7bb2e213d6f9 100644 --- a/Documentation/devicetree/bindings/net/nfc/st21nfca.txt +++ b/Documentation/devicetree/bindings/net/nfc/st21nfca.txt @@ -1,7 +1,7 @@ * STMicroelectronics SAS. ST21NFCA NFC Controller Required properties: -- compatible: Should be "st,st21nfca_i2c". +- compatible: Should be "st,st21nfca-i2c". - clock-frequency: I²C work frequency. - reg: address on the bus - interrupt-parent: phandle for the interrupt gpio controller @@ -11,6 +11,10 @@ Required properties: Optional SoC Specific Properties: - pinctrl-names: Contains only one value - "default". - pintctrl-0: Specifies the pin control groups used for this controller. +- ese-present: Specifies that an ese is physically connected to the nfc +controller. +- uicc-present: Specifies that the uicc swp signal can be physically +connected to the nfc controller. Example (for ARM-based BeagleBoard xM with ST21NFCA on I2C2): @@ -20,7 +24,7 @@ Example (for ARM-based BeagleBoard xM with ST21NFCA on I2C2): st21nfca: st21nfca@1 { - compatible = "st,st21nfca_i2c"; + compatible = "st,st21nfca-i2c"; reg = <0x01>; clock-frequency = <400000>; @@ -29,5 +33,8 @@ Example (for ARM-based BeagleBoard xM with ST21NFCA on I2C2): interrupts = <2 IRQ_TYPE_LEVEL_LOW>; enable-gpios = <&gpio5 29 GPIO_ACTIVE_HIGH>; + + ese-present; + uicc-present; }; }; diff --git a/Documentation/devicetree/bindings/net/nfc/st21nfcb.txt b/Documentation/devicetree/bindings/net/nfc/st21nfcb.txt index 9005608cbbd1..bb237072dbe9 100644 --- a/Documentation/devicetree/bindings/net/nfc/st21nfcb.txt +++ b/Documentation/devicetree/bindings/net/nfc/st21nfcb.txt @@ -1,7 +1,7 @@ * STMicroelectronics SAS. ST21NFCB NFC Controller Required properties: -- compatible: Should be "st,st21nfcb_i2c". +- compatible: Should be "st,st21nfcb-i2c". - clock-frequency: I²C work frequency. - reg: address on the bus - interrupt-parent: phandle for the interrupt gpio controller @@ -20,7 +20,7 @@ Example (for ARM-based BeagleBoard xM with ST21NFCB on I2C2): st21nfcb: st21nfcb@8 { - compatible = "st,st21nfcb_i2c"; + compatible = "st,st21nfcb-i2c"; reg = <0x08>; clock-frequency = <400000>; diff --git a/Documentation/devicetree/bindings/net/phy.txt b/Documentation/devicetree/bindings/net/phy.txt index 5b8c58903077..40831fbaff72 100644 --- a/Documentation/devicetree/bindings/net/phy.txt +++ b/Documentation/devicetree/bindings/net/phy.txt @@ -19,7 +19,6 @@ Optional Properties: specifications. If neither of these are specified, the default is to assume clause 22. The compatible list may also contain other elements. -- max-speed: Maximum PHY supported speed (10, 100, 1000...) If the phy's identifier is known then the list may contain an entry of the form: "ethernet-phy-idAAAA.BBBB" where @@ -29,6 +28,8 @@ Optional Properties: 4 hex digits. This is the chip vendor OUI bits 19:24, followed by 10 bits of a vendor specific ID. +- max-speed: Maximum PHY supported speed (10, 100, 1000...) + Example: ethernet-phy@0 { diff --git a/Documentation/devicetree/bindings/net/rockchip-dwmac.txt b/Documentation/devicetree/bindings/net/rockchip-dwmac.txt new file mode 100644 index 000000000000..21fd199e89b5 --- /dev/null +++ b/Documentation/devicetree/bindings/net/rockchip-dwmac.txt @@ -0,0 +1,68 @@ +Rockchip SoC RK3288 10/100/1000 Ethernet driver(GMAC) + +The device node has following properties. + +Required properties: + - compatible: Can be "rockchip,rk3288-gmac". + - reg: addresses and length of the register sets for the device. + - interrupts: Should contain the GMAC interrupts. + - interrupt-names: Should contain the interrupt names "macirq". + - rockchip,grf: phandle to the syscon grf used to control speed and mode. + - clocks: <&cru SCLK_MAC>: clock selector for main clock, from PLL or PHY. + <&cru SCLK_MAC_PLL>: PLL clock for SCLK_MAC + <&cru SCLK_MAC_RX>: clock gate for RX + <&cru SCLK_MAC_TX>: clock gate for TX + <&cru SCLK_MACREF>: clock gate for RMII referce clock + <&cru SCLK_MACREF_OUT> clock gate for RMII reference clock output + <&cru ACLK_GMAC>: AXI clock gate for GMAC + <&cru PCLK_GMAC>: APB clock gate for GMAC + - clock-names: One name for each entry in the clocks property. + - phy-mode: See ethernet.txt file in the same directory. + - pinctrl-names: Names corresponding to the numbered pinctrl states. + - pinctrl-0: pin-control mode. can be <&rgmii_pins> or <&rmii_pins>. + - clock_in_out: For RGMII, it must be "input", means main clock(125MHz) + is not sourced from SoC's PLL, but input from PHY; For RMII, "input" means + PHY provides the reference clock(50MHz), "output" means GMAC provides the + reference clock. + - snps,reset-gpio gpio number for phy reset. + - snps,reset-active-low boolean flag to indicate if phy reset is active low. + - assigned-clocks: main clock, should be <&cru SCLK_MAC>; + - assigned-clock-parents = parent of main clock. + can be <&ext_gmac> or <&cru SCLK_MAC_PLL>. + +Optional properties: + - tx_delay: Delay value for TXD timing. Range value is 0~0x7F, 0x30 as default. + - rx_delay: Delay value for RXD timing. Range value is 0~0x7F, 0x10 as default. + - phy-supply: phandle to a regulator if the PHY needs one + +Example: + +gmac: ethernet@ff290000 { + compatible = "rockchip,rk3288-gmac"; + reg = <0xff290000 0x10000>; + interrupts = <GIC_SPI 27 IRQ_TYPE_LEVEL_HIGH>; + interrupt-names = "macirq"; + rockchip,grf = <&grf>; + clocks = <&cru SCLK_MAC>, + <&cru SCLK_MAC_RX>, <&cru SCLK_MAC_TX>, + <&cru SCLK_MACREF>, <&cru SCLK_MACREF_OUT>, + <&cru ACLK_GMAC>, <&cru PCLK_GMAC>; + clock-names = "stmmaceth", + "mac_clk_rx", "mac_clk_tx", + "clk_mac_ref", "clk_mac_refout", + "aclk_mac", "pclk_mac"; + phy-mode = "rgmii"; + pinctrl-names = "default"; + pinctrl-0 = <&rgmii_pins /*&rmii_pins*/>; + + clock_in_out = "input"; + snps,reset-gpio = <&gpio4 7 0>; + snps,reset-active-low; + + assigned-clocks = <&cru SCLK_MAC>; + assigned-clock-parents = <&ext_gmac>; + tx_delay = <0x30>; + rx_delay = <0x10>; + + status = "ok"; +}; diff --git a/Documentation/devicetree/bindings/net/sh_eth.txt b/Documentation/devicetree/bindings/net/sh_eth.txt index 34d4db1a4e25..2f6ec85fda8e 100644 --- a/Documentation/devicetree/bindings/net/sh_eth.txt +++ b/Documentation/devicetree/bindings/net/sh_eth.txt @@ -9,6 +9,7 @@ Required properties: "renesas,ether-r8a7779" if the device is a part of R8A7779 SoC. "renesas,ether-r8a7790" if the device is a part of R8A7790 SoC. "renesas,ether-r8a7791" if the device is a part of R8A7791 SoC. + "renesas,ether-r8a7793" if the device is a part of R8A7793 SoC. "renesas,ether-r8a7794" if the device is a part of R8A7794 SoC. "renesas,ether-r7s72100" if the device is a part of R7S72100 SoC. - reg: offset and length of (1) the E-DMAC/feLic register block (required), diff --git a/Documentation/devicetree/bindings/net/sti-dwmac.txt b/Documentation/devicetree/bindings/net/sti-dwmac.txt index 6762a6b5da7e..d05c1e1fd9b6 100644 --- a/Documentation/devicetree/bindings/net/sti-dwmac.txt +++ b/Documentation/devicetree/bindings/net/sti-dwmac.txt @@ -9,14 +9,10 @@ The device node has following properties. Required properties: - compatible : Can be "st,stih415-dwmac", "st,stih416-dwmac", "st,stih407-dwmac", "st,stid127-dwmac". - - reg : Offset of the glue configuration register map in system - configuration regmap pointed by st,syscon property and size. - - st,syscon : Should be phandle to system configuration node which - encompases this glue registers. + - st,syscon : Should be phandle/offset pair. The phandle to the syscon node which + encompases the glue register, and the offset of the control register. - st,gmac_en: this is to enable the gmac into a dedicated sysctl control register available on STiH407 SoC. - - sti-ethconf: this is the gmac glue logic register to enable the GMAC, - select among the different modes and program the clk retiming. - pinctrl-0: pin-control for all the MII mode supported. Optional properties: @@ -40,10 +36,10 @@ ethernet0: dwmac@9630000 { device_type = "network"; status = "disabled"; compatible = "st,stih407-dwmac", "snps,dwmac", "snps,dwmac-3.710"; - reg = <0x9630000 0x8000>, <0x80 0x4>; - reg-names = "stmmaceth", "sti-ethconf"; + reg = <0x9630000 0x8000>; + reg-names = "stmmaceth"; - st,syscon = <&syscfg_sbc_reg>; + st,syscon = <&syscfg_sbc_reg 0x80>; st,gmac_en; resets = <&softreset STIH407_ETH1_SOFTRESET>; reset-names = "stmmaceth"; diff --git a/Documentation/devicetree/bindings/net/stmmac.txt b/Documentation/devicetree/bindings/net/stmmac.txt index c41afd963edf..8ca65cec52ae 100644 --- a/Documentation/devicetree/bindings/net/stmmac.txt +++ b/Documentation/devicetree/bindings/net/stmmac.txt @@ -43,6 +43,7 @@ Optional properties: available this clock is used for programming the Timestamp Addend Register. If not passed then the system clock will be used and this is fine on some platforms. +- snps,burst_len: The AXI burst lenth value of the AXI BUS MODE register. Examples: diff --git a/Documentation/devicetree/bindings/net/wireless/qcom,ath10k.txt b/Documentation/devicetree/bindings/net/wireless/qcom,ath10k.txt new file mode 100644 index 000000000000..edefc26c6204 --- /dev/null +++ b/Documentation/devicetree/bindings/net/wireless/qcom,ath10k.txt @@ -0,0 +1,30 @@ +* Qualcomm Atheros ath10k wireless devices + +For ath10k devices the calibration data can be provided through Device +Tree. The node is a child node of the PCI controller. + +Required properties: +-compatible : Should be "qcom,ath10k" + +Optional properties: +- qcom,ath10k-calibration-data : calibration data as an array, the + length can vary between hw versions + + +Example: + +pci { + pcie@0 { + reg = <0 0 0 0 0>; + #interrupt-cells = <1>; + #size-cells = <2>; + #address-cells = <3>; + device_type = "pci"; + + ath10k@0,0 { + reg = <0 0 0 0 0>; + device_type = "pci"; + qcom,ath10k-calibration-data = [ 01 02 03 ... ]; + }; + }; +}; diff --git a/Documentation/devicetree/bindings/nios2/nios2.txt b/Documentation/devicetree/bindings/nios2/nios2.txt new file mode 100644 index 000000000000..d6d0a94cb3bb --- /dev/null +++ b/Documentation/devicetree/bindings/nios2/nios2.txt @@ -0,0 +1,62 @@ +* Nios II Processor Binding + +This binding specifies what properties available in the device tree +representation of a Nios II Processor Core. + +Users can use sopc2dts tool for generating device tree sources (dts) from a +Qsys system. See more detail in: http://www.alterawiki.com/wiki/Sopc2dts + +Required properties: + +- compatible: Compatible property value should be "altr,nios2-1.0". +- reg: Contains CPU index. +- interrupt-controller: Specifies that the node is an interrupt controller +- #interrupt-cells: Specifies the number of cells needed to encode an + interrupt source, should be 1. +- clock-frequency: Contains the clock frequency for CPU, in Hz. +- dcache-line-size: Contains data cache line size. +- icache-line-size: Contains instruction line size. +- dcache-size: Contains data cache size. +- icache-size: Contains instruction cache size. +- altr,pid-num-bits: Specifies the number of bits to use to represent the process + identifier (PID). +- altr,tlb-num-ways: Specifies the number of set-associativity ways in the TLB. +- altr,tlb-num-entries: Specifies the number of entries in the TLB. +- altr,tlb-ptr-sz: Specifies size of TLB pointer. +- altr,has-mul: Specifies CPU hardware multipy support, should be 1. +- altr,has-mmu: Specifies CPU support MMU support, should be 1. +- altr,has-initda: Specifies CPU support initda instruction, should be 1. +- altr,reset-addr: Specifies CPU reset address +- altr,fast-tlb-miss-addr: Specifies CPU fast TLB miss exception address +- altr,exception-addr: Specifies CPU exception address + +Optional properties: +- altr,has-div: Specifies CPU hardware divide support +- altr,implementation: Nios II core implementation, this should be "fast"; + +Example: + +cpu@0x0 { + device_type = "cpu"; + compatible = "altr,nios2-1.0"; + reg = <0>; + interrupt-controller; + #interrupt-cells = <1>; + clock-frequency = <125000000>; + dcache-line-size = <32>; + icache-line-size = <32>; + dcache-size = <32768>; + icache-size = <32768>; + altr,implementation = "fast"; + altr,pid-num-bits = <8>; + altr,tlb-num-ways = <16>; + altr,tlb-num-entries = <128>; + altr,tlb-ptr-sz = <7>; + altr,has-div = <1>; + altr,has-mul = <1>; + altr,reset-addr = <0xc2800000>; + altr,fast-tlb-miss-addr = <0xc7fff400>; + altr,exception-addr = <0xd0000020>; + altr,has-initda = <1>; + altr,has-mmu = <1>; +}; diff --git a/Documentation/devicetree/bindings/nios2/timer.txt b/Documentation/devicetree/bindings/nios2/timer.txt new file mode 100644 index 000000000000..904a5846d7ac --- /dev/null +++ b/Documentation/devicetree/bindings/nios2/timer.txt @@ -0,0 +1,19 @@ +Altera Timer + +Required properties: + +- compatible : should be "altr,timer-1.0" +- reg : Specifies base physical address and size of the registers. +- interrupt-parent: phandle of the interrupt controller +- interrupts : Should contain the timer interrupt number +- clock-frequency : The frequency of the clock that drives the counter, in Hz. + +Example: + +timer { + compatible = "altr,timer-1.0"; + reg = <0x00400000 0x00000020>; + interrupt-parent = <&cpu>; + interrupts = <11>; + clock-frequency = <125000000>; +}; diff --git a/Documentation/devicetree/bindings/panel/auo,b116xw03.txt b/Documentation/devicetree/bindings/panel/auo,b116xw03.txt new file mode 100644 index 000000000000..690d0a568ef3 --- /dev/null +++ b/Documentation/devicetree/bindings/panel/auo,b116xw03.txt @@ -0,0 +1,7 @@ +AU Optronics Corporation 11.6" HD (1366x768) color TFT-LCD panel + +Required properties: +- compatible: should be "auo,b116xw03" + +This binding is compatible with the simple-panel binding, which is specified +in simple-panel.txt in this directory. diff --git a/Documentation/devicetree/bindings/panel/avic,tm070ddh03.txt b/Documentation/devicetree/bindings/panel/avic,tm070ddh03.txt new file mode 100644 index 000000000000..b6f2f3e8f44e --- /dev/null +++ b/Documentation/devicetree/bindings/panel/avic,tm070ddh03.txt @@ -0,0 +1,7 @@ +Shanghai AVIC Optoelectronics 7" 1024x600 color TFT-LCD panel + +Required properties: +- compatible: should be "avic,tm070ddh03" + +This binding is compatible with the simple-panel binding, which is specified +in simple-panel.txt in this directory. diff --git a/Documentation/devicetree/bindings/panel/giantplus,gpg482739qs5.txt b/Documentation/devicetree/bindings/panel/giantplus,gpg482739qs5.txt new file mode 100644 index 000000000000..24b0b624434b --- /dev/null +++ b/Documentation/devicetree/bindings/panel/giantplus,gpg482739qs5.txt @@ -0,0 +1,7 @@ +GiantPlus GPG48273QS5 4.3" (480x272) WQVGA TFT LCD panel + +Required properties: +- compatible: should be "giantplus,gpg48273qs5" + +This binding is compatible with the simple-panel binding, which is specified +in simple-panel.txt in this directory. diff --git a/Documentation/devicetree/bindings/panel/hannstar,hsd070pww1.txt b/Documentation/devicetree/bindings/panel/hannstar,hsd070pww1.txt new file mode 100644 index 000000000000..7da1d5c038ff --- /dev/null +++ b/Documentation/devicetree/bindings/panel/hannstar,hsd070pww1.txt @@ -0,0 +1,7 @@ +HannStar Display Corp. HSD070PWW1 7.0" WXGA TFT LCD panel + +Required properties: +- compatible: should be "hannstar,hsd070pww1" + +This binding is compatible with the simple-panel binding, which is specified +in simple-panel.txt in this directory. diff --git a/Documentation/devicetree/bindings/panel/hit,tx23d38vm0caa.txt b/Documentation/devicetree/bindings/panel/hit,tx23d38vm0caa.txt new file mode 100644 index 000000000000..04caaae19af6 --- /dev/null +++ b/Documentation/devicetree/bindings/panel/hit,tx23d38vm0caa.txt @@ -0,0 +1,7 @@ +Hitachi Ltd. Corporation 9" WVGA (800x480) TFT LCD panel + +Required properties: +- compatible: should be "hit,tx23d38vm0caa" + +This binding is compatible with the simple-panel binding, which is specified +in simple-panel.txt in this directory. diff --git a/Documentation/devicetree/bindings/panel/innolux,g121i1-l01.txt b/Documentation/devicetree/bindings/panel/innolux,g121i1-l01.txt new file mode 100644 index 000000000000..2743b07cd2f2 --- /dev/null +++ b/Documentation/devicetree/bindings/panel/innolux,g121i1-l01.txt @@ -0,0 +1,7 @@ +Innolux Corporation 12.1" WXGA (1280x800) TFT LCD panel + +Required properties: +- compatible: should be "innolux,g121i1-l01" + +This binding is compatible with the simple-panel binding, which is specified +in simple-panel.txt in this directory. diff --git a/Documentation/devicetree/bindings/panel/sharp,lq101r1sx01.txt b/Documentation/devicetree/bindings/panel/sharp,lq101r1sx01.txt new file mode 100644 index 000000000000..f522bb8e47e1 --- /dev/null +++ b/Documentation/devicetree/bindings/panel/sharp,lq101r1sx01.txt @@ -0,0 +1,49 @@ +Sharp Microelectronics 10.1" WQXGA TFT LCD panel + +This panel requires a dual-channel DSI host to operate. It supports two modes: +- left-right: each channel drives the left or right half of the screen +- even-odd: each channel drives the even or odd lines of the screen + +Each of the DSI channels controls a separate DSI peripheral. The peripheral +driven by the first link (DSI-LINK1), left or even, is considered the primary +peripheral and controls the device. The 'link2' property contains a phandle +to the peripheral driven by the second link (DSI-LINK2, right or odd). + +Note that in video mode the DSI-LINK1 interface always provides the left/even +pixels and DSI-LINK2 always provides the right/odd pixels. In command mode it +is possible to program either link to drive the left/even or right/odd pixels +but for the sake of consistency this binding assumes that the same assignment +is chosen as for video mode. + +Required properties: +- compatible: should be "sharp,lq101r1sx01" +- reg: DSI virtual channel of the peripheral + +Required properties (for DSI-LINK1 only): +- link2: phandle to the DSI peripheral on the secondary link. Note that the + presence of this property marks the containing node as DSI-LINK1. +- power-supply: phandle of the regulator that provides the supply voltage + +Optional properties (for DSI-LINK1 only): +- backlight: phandle of the backlight device attached to the panel + +Example: + + dsi@54300000 { + panel: panel@0 { + compatible = "sharp,lq101r1sx01"; + reg = <0>; + + link2 = <&secondary>; + + power-supply = <...>; + backlight = <...>; + }; + }; + + dsi@54400000 { + secondary: panel@0 { + compatible = "sharp,lq101r1sx01"; + reg = <0>; + }; + }; diff --git a/Documentation/devicetree/bindings/pci/layerscape-pci.txt b/Documentation/devicetree/bindings/pci/layerscape-pci.txt new file mode 100644 index 000000000000..6286f049bf18 --- /dev/null +++ b/Documentation/devicetree/bindings/pci/layerscape-pci.txt @@ -0,0 +1,42 @@ +Freescale Layerscape PCIe controller + +This PCIe host controller is based on the Synopsis Designware PCIe IP +and thus inherits all the common properties defined in designware-pcie.txt. + +Required properties: +- compatible: should contain the platform identifier such as "fsl,ls1021a-pcie" +- reg: base addresses and lengths of the PCIe controller +- interrupts: A list of interrupt outputs of the controller. Must contain an + entry for each entry in the interrupt-names property. +- interrupt-names: Must include the following entries: + "intr": The interrupt that is asserted for controller interrupts +- fsl,pcie-scfg: Must include two entries. + The first entry must be a link to the SCFG device node + The second entry must be '0' or '1' based on physical PCIe controller index. + This is used to get SCFG PEXN registers + +Example: + + pcie@3400000 { + compatible = "fsl,ls1021a-pcie", "snps,dw-pcie"; + reg = <0x00 0x03400000 0x0 0x00010000 /* controller registers */ + 0x40 0x00000000 0x0 0x00002000>; /* configuration space */ + reg-names = "regs", "config"; + interrupts = <GIC_SPI 177 IRQ_TYPE_LEVEL_HIGH>; /* controller interrupt */ + interrupt-names = "intr"; + fsl,pcie-scfg = <&scfg 0>; + #address-cells = <3>; + #size-cells = <2>; + device_type = "pci"; + num-lanes = <4>; + bus-range = <0x0 0xff>; + ranges = <0x81000000 0x0 0x00000000 0x40 0x00010000 0x0 0x00010000 /* downstream I/O */ + 0xc2000000 0x0 0x20000000 0x40 0x20000000 0x0 0x20000000 /* prefetchable memory */ + 0x82000000 0x0 0x40000000 0x40 0x40000000 0x0 0x40000000>; /* non-prefetchable memory */ + #interrupt-cells = <1>; + interrupt-map-mask = <0 0 0 7>; + interrupt-map = <0000 0 0 1 &gic GIC_SPI 91 IRQ_TYPE_LEVEL_HIGH>, + <0000 0 0 2 &gic GIC_SPI 188 IRQ_TYPE_LEVEL_HIGH>, + <0000 0 0 3 &gic GIC_SPI 190 IRQ_TYPE_LEVEL_HIGH>, + <0000 0 0 4 &gic GIC_SPI 192 IRQ_TYPE_LEVEL_HIGH>; + }; diff --git a/Documentation/devicetree/bindings/pci/nvidia,tegra20-pcie.txt b/Documentation/devicetree/bindings/pci/nvidia,tegra20-pcie.txt index d763e047c6ae..75321ae23c08 100644 --- a/Documentation/devicetree/bindings/pci/nvidia,tegra20-pcie.txt +++ b/Documentation/devicetree/bindings/pci/nvidia,tegra20-pcie.txt @@ -1,10 +1,10 @@ NVIDIA Tegra PCIe controller Required properties: -- compatible: Must be one of: - - "nvidia,tegra20-pcie" - - "nvidia,tegra30-pcie" - - "nvidia,tegra124-pcie" +- compatible: For Tegra20, must contain "nvidia,tegra20-pcie". For Tegra30, + "nvidia,tegra30-pcie". For Tegra124, must contain "nvidia,tegra124-pcie". + Otherwise, must contain "nvidia,<chip>-pcie", plus one of the above, where + <chip> is tegra132 or tegra210. - device_type: Must be "pci" - reg: A list of physical base address and length for each set of controller registers. Must contain an entry for each entry in the reg-names property. diff --git a/Documentation/devicetree/bindings/pci/versatile.txt b/Documentation/devicetree/bindings/pci/versatile.txt new file mode 100644 index 000000000000..ebd1e7d0403e --- /dev/null +++ b/Documentation/devicetree/bindings/pci/versatile.txt @@ -0,0 +1,59 @@ +* ARM Versatile Platform Baseboard PCI interface + +PCI host controller found on the ARM Versatile PB board's FPGA. + +Required properties: +- compatible: should contain "arm,versatile-pci" to identify the Versatile PCI + controller. +- reg: base addresses and lengths of the pci controller. There must be 3 + entries: + - Versatile-specific registers + - Self Config space + - Config space +- #address-cells: set to <3> +- #size-cells: set to <2> +- device_type: set to "pci" +- bus-range: set to <0 0xff> +- ranges: ranges for the PCI memory and I/O regions +- #interrupt-cells: set to <1> +- interrupt-map-mask and interrupt-map: standard PCI properties to define + the mapping of the PCI interface to interrupt numbers. + +Example: + +pci-controller@10001000 { + compatible = "arm,versatile-pci"; + device_type = "pci"; + reg = <0x10001000 0x1000 + 0x41000000 0x10000 + 0x42000000 0x100000>; + bus-range = <0 0xff>; + #address-cells = <3>; + #size-cells = <2>; + #interrupt-cells = <1>; + + ranges = <0x01000000 0 0x00000000 0x43000000 0 0x00010000 /* downstream I/O */ + 0x02000000 0 0x50000000 0x50000000 0 0x10000000 /* non-prefetchable memory */ + 0x42000000 0 0x60000000 0x60000000 0 0x10000000>; /* prefetchable memory */ + + interrupt-map-mask = <0x1800 0 0 7>; + interrupt-map = <0x1800 0 0 1 &sic 28 + 0x1800 0 0 2 &sic 29 + 0x1800 0 0 3 &sic 30 + 0x1800 0 0 4 &sic 27 + + 0x1000 0 0 1 &sic 27 + 0x1000 0 0 2 &sic 28 + 0x1000 0 0 3 &sic 29 + 0x1000 0 0 4 &sic 30 + + 0x0800 0 0 1 &sic 30 + 0x0800 0 0 2 &sic 27 + 0x0800 0 0 3 &sic 28 + 0x0800 0 0 4 &sic 29 + + 0x0000 0 0 1 &sic 29 + 0x0000 0 0 2 &sic 30 + 0x0000 0 0 3 &sic 27 + 0x0000 0 0 4 &sic 28>; +}; diff --git a/Documentation/devicetree/bindings/phy/berlin-sata-phy.txt b/Documentation/devicetree/bindings/phy/berlin-sata-phy.txt index 88f8c23384c0..c0155f842f62 100644 --- a/Documentation/devicetree/bindings/phy/berlin-sata-phy.txt +++ b/Documentation/devicetree/bindings/phy/berlin-sata-phy.txt @@ -2,7 +2,9 @@ Berlin SATA PHY --------------- Required properties: -- compatible: should be "marvell,berlin2q-sata-phy" +- compatible: should be one of + "marvell,berlin2-sata-phy" + "marvell,berlin2q-sata-phy" - address-cells: should be 1 - size-cells: should be 0 - phy-cells: from the generic PHY bindings, must be 1 diff --git a/Documentation/devicetree/bindings/phy/berlin-usb-phy.txt b/Documentation/devicetree/bindings/phy/berlin-usb-phy.txt new file mode 100644 index 000000000000..be33780f668e --- /dev/null +++ b/Documentation/devicetree/bindings/phy/berlin-usb-phy.txt @@ -0,0 +1,16 @@ +* Marvell Berlin USB PHY + +Required properties: +- compatible: "marvell,berlin2-usb-phy" or "marvell,berlin2cd-usb-phy" +- reg: base address and length of the registers +- #phys-cells: should be 0 +- resets: reference to the reset controller + +Example: + + usb-phy@f774000 { + compatible = "marvell,berlin2-usb-phy"; + reg = <0xf774000 0x128>; + #phy-cells = <0>; + resets = <&chip 0x104 14>; + }; diff --git a/Documentation/devicetree/bindings/phy/phy-miphy28lp.txt b/Documentation/devicetree/bindings/phy/phy-miphy28lp.txt new file mode 100644 index 000000000000..89caa885d08c --- /dev/null +++ b/Documentation/devicetree/bindings/phy/phy-miphy28lp.txt @@ -0,0 +1,117 @@ +STMicroelectronics STi MIPHY28LP PHY binding +============================================ + +This binding describes a miphy device that is used to control PHY hardware +for SATA, PCIe or USB3. + +Required properties (controller (parent) node): +- compatible : Should be "st,miphy28lp-phy". +- st,syscfg : Should be a phandle of the system configuration register group + which contain the SATA, PCIe or USB3 mode setting bits. + +Required nodes : A sub-node is required for each channel the controller + provides. Address range information including the usual + 'reg' and 'reg-names' properties are used inside these + nodes to describe the controller's topology. These nodes + are translated by the driver's .xlate() function. + +Required properties (port (child) node): +- #phy-cells : Should be 1 (See second example) + Cell after port phandle is device type from: + - PHY_TYPE_SATA + - PHY_TYPE_PCI + - PHY_TYPE_USB3 +- reg : Address and length of the register set for the device. +- reg-names : The names of the register addresses corresponding to the registers + filled in "reg". It can also contain the offset of the system configuration + registers used as glue-logic to setup the device for SATA/PCIe or USB3 + devices. +- st,syscfg : Offset of the parent configuration register. +- resets : phandle to the parent reset controller. +- reset-names : Associated name must be "miphy-sw-rst". + +Optional properties (port (child) node): +- st,osc-rdy : to check the MIPHY0_OSC_RDY status in the glue-logic. This + is not available in all the MiPHY. For example, for STiH407, only the + MiPHY0 has this bit. +- st,osc-force-ext : to select the external oscillator. This can change from + different MiPHY inside the same SoC. +- st,sata_gen : to select which SATA_SPDMODE has to be set in the SATA system config + register. +- st,px_rx_pol_inv : to invert polarity of RXn/RXp (respectively negative line and positive + line). +- st,scc-on : enable ssc to reduce effects of EMI (only for sata or PCIe). +- st,tx-impedance-comp : to compensate tx impedance avoiding out of range values. + +example: + + miphy28lp_phy: miphy28lp@9b22000 { + compatible = "st,miphy28lp-phy"; + st,syscfg = <&syscfg_core>; + #address-cells = <1>; + #size-cells = <1>; + ranges; + + phy_port0: port@9b22000 { + reg = <0x9b22000 0xff>, + <0x9b09000 0xff>, + <0x9b04000 0xff>; + reg-names = "sata-up", + "pcie-up", + "pipew"; + + st,syscfg = <0x114 0x818 0xe0 0xec>; + #phy-cells = <1>; + st,osc-rdy; + reset-names = "miphy-sw-rst"; + resets = <&softreset STIH407_MIPHY0_SOFTRESET>; + }; + + phy_port1: port@9b2a000 { + reg = <0x9b2a000 0xff>, + <0x9b19000 0xff>, + <0x9b14000 0xff>; + reg-names = "sata-up", + "pcie-up", + "pipew"; + + st,syscfg = <0x118 0x81c 0xe4 0xf0>; + + #phy-cells = <1>; + st,osc-force-ext; + reset-names = "miphy-sw-rst"; + resets = <&softreset STIH407_MIPHY1_SOFTRESET>; + }; + + phy_port2: port@8f95000 { + reg = <0x8f95000 0xff>, + <0x8f90000 0xff>; + reg-names = "pipew", + "usb3-up"; + + st,syscfg = <0x11c 0x820>; + + #phy-cells = <1>; + reset-names = "miphy-sw-rst"; + resets = <&softreset STIH407_MIPHY2_SOFTRESET>; + }; + }; + + +Specifying phy control of devices +================================= + +Device nodes should specify the configuration required in their "phys" +property, containing a phandle to the miphy device node and an index +specifying which configuration to use, as described in phy-bindings.txt. + +example: + sata0: sata@9b20000 { + ... + phys = <&phy_port0 PHY_TYPE_SATA>; + ... + }; + +Macro definitions for the supported miphy configuration can be found in: + +include/dt-bindings/phy/phy.h diff --git a/Documentation/devicetree/bindings/phy/phy-miphy365x.txt b/Documentation/devicetree/bindings/phy/phy-miphy365x.txt index 42c880886cf7..9802d5d911aa 100644 --- a/Documentation/devicetree/bindings/phy/phy-miphy365x.txt +++ b/Documentation/devicetree/bindings/phy/phy-miphy365x.txt @@ -6,8 +6,10 @@ for SATA and PCIe. Required properties (controller (parent) node): - compatible : Should be "st,miphy365x-phy" -- st,syscfg : Should be a phandle of the system configuration register group - which contain the SATA, PCIe mode setting bits +- st,syscfg : Phandle / integer array property. Phandle of sysconfig group + containing the miphy registers and integer array should contain + an entry for each port sub-node, specifying the control + register offset inside the sysconfig group. Required nodes : A sub-node is required for each channel the controller provides. Address range information including the usual @@ -26,7 +28,6 @@ Required properties (port (child) node): registers filled in "reg": - sata: For SATA devices - pcie: For PCIe devices - - syscfg: To specify the syscfg based config register Optional properties (port (child) node): - st,sata-gen : Generation of locally attached SATA IP. Expected values @@ -39,20 +40,20 @@ Example: miphy365x_phy: miphy365x@fe382000 { compatible = "st,miphy365x-phy"; - st,syscfg = <&syscfg_rear>; + st,syscfg = <&syscfg_rear 0x824 0x828>; #address-cells = <1>; #size-cells = <1>; ranges; phy_port0: port@fe382000 { - reg = <0xfe382000 0x100>, <0xfe394000 0x100>, <0x824 0x4>; - reg-names = "sata", "pcie", "syscfg"; + reg = <0xfe382000 0x100>, <0xfe394000 0x100>; + reg-names = "sata", "pcie"; #phy-cells = <1>; st,sata-gen = <3>; }; phy_port1: port@fe38a000 { - reg = <0xfe38a000 0x100>, <0xfe804000 0x100>, <0x828 0x4>;; + reg = <0xfe38a000 0x100>, <0xfe804000 0x100>;; reg-names = "sata", "pcie", "syscfg"; #phy-cells = <1>; st,pcie-tx-pol-inv; diff --git a/Documentation/devicetree/bindings/phy/phy-mvebu.txt b/Documentation/devicetree/bindings/phy/phy-mvebu.txt new file mode 100644 index 000000000000..f95b6260a3b3 --- /dev/null +++ b/Documentation/devicetree/bindings/phy/phy-mvebu.txt @@ -0,0 +1,43 @@ +* Marvell MVEBU SATA PHY + +Power control for the SATA phy found on Marvell MVEBU SoCs. + +This document extends the binding described in phy-bindings.txt + +Required properties : + + - reg : Offset and length of the register set for the SATA device + - compatible : Should be "marvell,mvebu-sata-phy" + - clocks : phandle of clock and specifier that supplies the device + - clock-names : Should be "sata" + +Example: + sata-phy@84000 { + compatible = "marvell,mvebu-sata-phy"; + reg = <0x84000 0x0334>; + clocks = <&gate_clk 15>; + clock-names = "sata"; + #phy-cells = <0>; + status = "ok"; + }; + +Armada 375 USB cluster +---------------------- + +Armada 375 comes with an USB2 host and device controller and an USB3 +controller. The USB cluster control register allows to manage common +features of both USB controllers. + +Required properties: + +- compatible: "marvell,armada-375-usb-cluster" +- reg: Should contain usb cluster register location and length. +- #phy-cells : from the generic phy bindings, must be 1. Possible +values are 1 (USB2), 2 (USB3). + +Example: + usbcluster: usb-cluster@18400 { + compatible = "marvell,armada-375-usb-cluster"; + reg = <0x18400 0x4>; + #phy-cells = <1> + }; diff --git a/Documentation/devicetree/bindings/phy/phy-stih407-usb.txt b/Documentation/devicetree/bindings/phy/phy-stih407-usb.txt index 1ef8228db73b..de6a706abcdb 100644 --- a/Documentation/devicetree/bindings/phy/phy-stih407-usb.txt +++ b/Documentation/devicetree/bindings/phy/phy-stih407-usb.txt @@ -5,10 +5,7 @@ host controllers (when controlling usb2/1.1 devices) available on STiH407 SoC fa Required properties: - compatible : should be "st,stih407-usb2-phy" -- reg : contain the offset and length of the system configuration registers - used as glue logic to control & parameter phy -- reg-names : the names of the system configuration registers in "reg", should be "param" and "reg" -- st,syscfg : sysconfig register to manage phy parameter at driver level +- st,syscfg : phandle of sysconfig bank plus integer array containing phyparam and phyctrl register offsets - resets : list of phandle and reset specifier pairs. There should be two entries, one for the whole phy and one for the port - reset-names : list of reset signal names. Should be "global" and "port" @@ -19,11 +16,8 @@ Example: usb2_picophy0: usbpicophy@f8 { compatible = "st,stih407-usb2-phy"; - reg = <0xf8 0x04>, /* syscfg 5062 */ - <0xf4 0x04>; /* syscfg 5061 */ - reg-names = "param", "ctrl"; #phy-cells = <0>; - st,syscfg = <&syscfg_core>; + st,syscfg = <&syscfg_core 0x100 0xf4>; resets = <&softreset STIH407_PICOPHY_SOFTRESET>, <&picophyreset STIH407_PICOPHY0_RESET>; reset-names = "global", "port"; diff --git a/Documentation/devicetree/bindings/phy/rockchip-usb-phy.txt b/Documentation/devicetree/bindings/phy/rockchip-usb-phy.txt new file mode 100644 index 000000000000..826454ac43bb --- /dev/null +++ b/Documentation/devicetree/bindings/phy/rockchip-usb-phy.txt @@ -0,0 +1,37 @@ +ROCKCHIP USB2 PHY + +Required properties: + - compatible: rockchip,rk3288-usb-phy + - rockchip,grf : phandle to the syscon managing the "general + register files" + - #address-cells: should be 1 + - #size-cells: should be 0 + +Sub-nodes: +Each PHY should be represented as a sub-node. + +Sub-nodes +required properties: +- #phy-cells: should be 0 +- reg: PHY configure reg address offset in GRF + "0x320" - for PHY attach to OTG controller + "0x334" - for PHY attach to HOST0 controller + "0x348" - for PHY attach to HOST1 controller + +Optional Properties: +- clocks : phandle + clock specifier for the phy clocks +- clock-names: string, clock name, must be "phyclk" + +Example: + +usbphy: phy { + compatible = "rockchip,rk3288-usb-phy"; + rockchip,grf = <&grf>; + #address-cells = <1>; + #size-cells = <0>; + + usbphy0: usb-phy0 { + #phy-cells = <0>; + reg = <0x320>; + }; +}; diff --git a/Documentation/devicetree/bindings/phy/samsung-phy.txt b/Documentation/devicetree/bindings/phy/samsung-phy.txt index 15e0f2c7130f..91e38cfe1f8f 100644 --- a/Documentation/devicetree/bindings/phy/samsung-phy.txt +++ b/Documentation/devicetree/bindings/phy/samsung-phy.txt @@ -3,8 +3,8 @@ Samsung S5P/EXYNOS SoC series MIPI CSIS/DSIM DPHY Required properties: - compatible : should be "samsung,s5pv210-mipi-video-phy"; -- reg : offset and length of the MIPI DPHY register set; - #phy-cells : from the generic phy bindings, must be 1; +- syscon - phandle to the PMU system controller; For "samsung,s5pv210-mipi-video-phy" compatible PHYs the second cell in the PHY specifier identifies the PHY and its meaning is as follows: @@ -128,6 +128,7 @@ Required properties: - compatible : Should be set to one of the following supported values: - "samsung,exynos5250-usbdrd-phy" - for exynos5250 SoC, - "samsung,exynos5420-usbdrd-phy" - for exynos5420 SoC. + - "samsung,exynos7-usbdrd-phy" - for exynos7 SoC. - reg : Register offset and length of USB DRD PHY register set; - clocks: Clock IDs array as required by the controller - clock-names: names of clocks correseponding to IDs in the clock property; @@ -138,6 +139,11 @@ Required properties: PHY operations, associated by phy name. It is used to determine bit values for clock settings register. For Exynos5420 this is given as 'sclk_usbphy30' in CMU. + - optional clocks: Exynos7 SoC has now following additional + gate clocks available: + - phy_pipe: for PIPE3 phy + - phy_utmi: for UTMI+ phy + - itp: for ITP generation - samsung,pmu-syscon: phandle for PMU system controller interface, used to control pmu registers for power isolation. - #phy-cells : from the generic PHY bindings, must be 1; diff --git a/Documentation/devicetree/bindings/pinctrl/allwinner,sunxi-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/allwinner,sunxi-pinctrl.txt index 93ce12eb422a..fdd8046e650a 100644 --- a/Documentation/devicetree/bindings/pinctrl/allwinner,sunxi-pinctrl.txt +++ b/Documentation/devicetree/bindings/pinctrl/allwinner,sunxi-pinctrl.txt @@ -11,6 +11,7 @@ Required properties: "allwinner,sun5i-a10s-pinctrl" "allwinner,sun5i-a13-pinctrl" "allwinner,sun6i-a31-pinctrl" + "allwinner,sun6i-a31s-pinctrl" "allwinner,sun6i-a31-r-pinctrl" "allwinner,sun7i-a20-pinctrl" "allwinner,sun8i-a23-pinctrl" diff --git a/Documentation/devicetree/bindings/pinctrl/img,tz1090-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/img,tz1090-pinctrl.txt index 49d0e6050940..509faa87ad0e 100644 --- a/Documentation/devicetree/bindings/pinctrl/img,tz1090-pinctrl.txt +++ b/Documentation/devicetree/bindings/pinctrl/img,tz1090-pinctrl.txt @@ -67,7 +67,7 @@ Valid values for pin and group names are: They also all support the some form of muxing. Any pins which are contained in one of the mux groups (see below) can be muxed only to the functions supported by the mux group. All other pins can be muxed to the "perip" - function which which enables them with their intended peripheral. + function which enables them with their intended peripheral. Different pins in the same mux group cannot be muxed to different functions, however it is possible to mux only a subset of the pins in a mux group to a diff --git a/Documentation/devicetree/bindings/pinctrl/meson,pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/meson,pinctrl.txt new file mode 100644 index 000000000000..17e7240c6998 --- /dev/null +++ b/Documentation/devicetree/bindings/pinctrl/meson,pinctrl.txt @@ -0,0 +1,96 @@ +== Amlogic Meson pinmux controller == + +Required properties for the root node: + - compatible: "amlogic,meson8-pinctrl" + - reg: address and size of registers controlling irq functionality + +=== GPIO sub-nodes === + +The 2 power domains of the controller (regular and always-on) are +represented as sub-nodes and each of them acts as a GPIO controller. + +Required properties for sub-nodes are: + - reg: should contain address and size for mux, pull-enable, pull and + gpio register sets + - reg-names: an array of strings describing the "reg" entries. Must + contain "mux", "pull" and "gpio". "pull-enable" is optional and + when it is missing the "pull" registers are used instead + - gpio-controller: identifies the node as a gpio controller + - #gpio-cells: must be 2 + +Valid sub-node names are: + - "banks" for the regular domain + - "ao-bank" for the always-on domain + +=== Other sub-nodes === + +Child nodes without the "gpio-controller" represent some desired +configuration for a pin or a group. Those nodes can be pinmux nodes or +configuration nodes. + +Required properties for pinmux nodes are: + - groups: a list of pinmux groups. The list of all available groups + depends on the SoC and can be found in driver sources. + - function: the name of a function to activate for the specified set + of groups. The list of all available functions depends on the SoC + and can be found in driver sources. + +Required properties for configuration nodes: + - pins: a list of pin names + +Configuration nodes support the generic properties "bias-disable", +"bias-pull-up" and "bias-pull-down", described in file +pinctrl-bindings.txt + +=== Example === + + pinctrl: pinctrl@c1109880 { + compatible = "amlogic,meson8-pinctrl"; + reg = <0xc1109880 0x10>; + #address-cells = <1>; + #size-cells = <1>; + ranges; + + gpio: banks@c11080b0 { + reg = <0xc11080b0 0x28>, + <0xc11080e8 0x18>, + <0xc1108120 0x18>, + <0xc1108030 0x30>; + reg-names = "mux", "pull", "pull-enable", "gpio"; + gpio-controller; + #gpio-cells = <2>; + }; + + gpio_ao: ao-bank@c1108030 { + reg = <0xc8100014 0x4>, + <0xc810002c 0x4>, + <0xc8100024 0x8>; + reg-names = "mux", "pull", "gpio"; + gpio-controller; + #gpio-cells = <2>; + }; + + nand { + mux { + groups = "nand_io", "nand_io_ce0", "nand_io_ce1", + "nand_io_rb0", "nand_ale", "nand_cle", + "nand_wen_clk", "nand_ren_clk", "nand_dqs", + "nand_ce2", "nand_ce3"; + function = "nand"; + }; + }; + + uart_ao_a { + mux { + groups = "uart_tx_ao_a", "uart_rx_ao_a", + "uart_cts_ao_a", "uart_rts_ao_a"; + function = "uart_ao"; + }; + + conf { + pins = "GPIOAO_0", "GPIOAO_1", + "GPIOAO_2", "GPIOAO_3"; + bias-disable; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/pinctrl/nvidia,tegra124-pinmux.txt b/Documentation/devicetree/bindings/pinctrl/nvidia,tegra124-pinmux.txt index 189814e7cdc7..ecb5c0d25218 100644 --- a/Documentation/devicetree/bindings/pinctrl/nvidia,tegra124-pinmux.txt +++ b/Documentation/devicetree/bindings/pinctrl/nvidia,tegra124-pinmux.txt @@ -6,7 +6,8 @@ nvidia,tegra30-pinmux.txt. In fact, this document assumes that binding as a baseline, and only documents the differences between the two bindings. Required properties: -- compatible: "nvidia,tegra124-pinmux" +- compatible: For Tegra124, must contain "nvidia,tegra124-pinmux". For + Tegra132, must contain '"nvidia,tegra132-pinmux", "nvidia-tegra124-pinmux"'. - reg: Should contain a list of base address and size pairs for: -- first entry - the drive strength and pad control registers. -- second entry - the pinmux registers diff --git a/Documentation/devicetree/bindings/pinctrl/nvidia,tegra124-xusb-padctl.txt b/Documentation/devicetree/bindings/pinctrl/nvidia,tegra124-xusb-padctl.txt index 2f9c0bd66457..30676ded85bb 100644 --- a/Documentation/devicetree/bindings/pinctrl/nvidia,tegra124-xusb-padctl.txt +++ b/Documentation/devicetree/bindings/pinctrl/nvidia,tegra124-xusb-padctl.txt @@ -13,7 +13,9 @@ how to describe and reference PHYs in device trees. Required properties: -------------------- -- compatible: should be "nvidia,tegra124-xusb-padctl" +- compatible: For Tegra124, must contain "nvidia,tegra124-xusb-padctl". + Otherwise, must contain '"nvidia,<chip>-xusb-padctl", + "nvidia-tegra124-xusb-padctl"', where <chip> is tegra132 or tegra210. - reg: Physical base address and length of the controller's registers. - resets: Must contain an entry for each entry in reset-names. See ../reset/reset.txt for details. diff --git a/Documentation/devicetree/bindings/pinctrl/pinctrl-bindings.txt b/Documentation/devicetree/bindings/pinctrl/pinctrl-bindings.txt index 98eb94d91a1c..47d84b6ee91b 100644 --- a/Documentation/devicetree/bindings/pinctrl/pinctrl-bindings.txt +++ b/Documentation/devicetree/bindings/pinctrl/pinctrl-bindings.txt @@ -216,4 +216,4 @@ arguments are described below. or 0 to disable debouncing More in-depth documentation on these parameters can be found in -<include/linux/pinctrl/pinconfig-generic.h> +<include/linux/pinctrl/pinconf-generic.h> diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,msm8916-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/qcom,msm8916-pinctrl.txt new file mode 100644 index 000000000000..498caff6029e --- /dev/null +++ b/Documentation/devicetree/bindings/pinctrl/qcom,msm8916-pinctrl.txt @@ -0,0 +1,186 @@ +Qualcomm MSM8916 TLMM block + +This binding describes the Top Level Mode Multiplexer block found in the +MSM8916 platform. + +- compatible: + Usage: required + Value type: <string> + Definition: must be "qcom,msm8916-pinctrl" + +- reg: + Usage: required + Value type: <prop-encoded-array> + Definition: the base address and size of the TLMM register space. + +- interrupts: + Usage: required + Value type: <prop-encoded-array> + Definition: should specify the TLMM summary IRQ. + +- interrupt-controller: + Usage: required + Value type: <none> + Definition: identifies this node as an interrupt controller + +- #interrupt-cells: + Usage: required + Value type: <u32> + Definition: must be 2. Specifying the pin number and flags, as defined + in <dt-bindings/interrupt-controller/irq.h> + +- gpio-controller: + Usage: required + Value type: <none> + Definition: identifies this node as a gpio controller + +- #gpio-cells: + Usage: required + Value type: <u32> + Definition: must be 2. Specifying the pin number and flags, as defined + in <dt-bindings/gpio/gpio.h> + +Please refer to ../gpio/gpio.txt and ../interrupt-controller/interrupts.txt for +a general description of GPIO and interrupt bindings. + +Please refer to pinctrl-bindings.txt in this directory for details of the +common pinctrl bindings used by client devices, including the meaning of the +phrase "pin configuration node". + +The pin configuration nodes act as a container for an arbitrary number of +subnodes. Each of these subnodes represents some desired configuration for a +pin, a group, or a list of pins or groups. This configuration can include the +mux function to select on those pin(s)/group(s), and various pin configuration +parameters, such as pull-up, drive strength, etc. + + +PIN CONFIGURATION NODES: + +The name of each subnode is not important; all subnodes should be enumerated +and processed purely based on their content. + +Each subnode only affects those parameters that are explicitly listed. In +other words, a subnode that lists a mux function but no pin configuration +parameters implies no information about any pin configuration parameters. +Similarly, a pin subnode that describes a pullup parameter implies no +information about e.g. the mux function. + + +The following generic properties as defined in pinctrl-bindings.txt are valid +to specify in a pin configuration subnode: + +- pins: + Usage: required + Value type: <string-array> + Definition: List of gpio pins affected by the properties specified in + this subnode. Valid pins are: + gpio0-gpio121, + sdc1_clk, + sdc1_cmd, + sdc1_data + sdc2_clk, + sdc2_cmd, + sdc2_data, + qdsd_cmd, + qdsd_data0, + qdsd_data1, + qdsd_data2, + qdsd_data3 + +- function: + Usage: required + Value type: <string> + Definition: Specify the alternative function to be configured for the + specified pins. Functions are only valid for gpio pins. + Valid values are: + adsp_ext, alsp_int, atest_bbrx0, atest_bbrx1, atest_char, atest_char0, + atest_char1, atest_char2, atest_char3, atest_combodac, atest_gpsadc0, + atest_gpsadc1, atest_tsens, atest_wlan0, atest_wlan1, backlight_en, + bimc_dte0,bimc_dte1, blsp_i2c1, blsp_i2c2, blsp_i2c3, blsp_i2c4, + blsp_i2c5, blsp_i2c6, blsp_spi1, blsp_spi1_cs1, blsp_spi1_cs2, + blsp_spi1_cs3, blsp_spi2, blsp_spi2_cs1, blsp_spi2_cs2, blsp_spi2_cs3, + blsp_spi3, blsp_spi3_cs1, blsp_spi3_cs2, blsp_spi3_cs3, blsp_spi4, + blsp_spi5, blsp_spi6, blsp_uart1, blsp_uart2, blsp_uim1, blsp_uim2, + cam1_rst, cam1_standby, cam_mclk0, cam_mclk1, cci_async, cci_i2c, + cci_timer0, cci_timer1, cci_timer2, cdc_pdm0, codec_mad, dbg_out, + display_5v, dmic0_clk, dmic0_data, dsi_rst, ebi0_wrcdc, euro_us, + ext_lpass, flash_strobe, gcc_gp1_clk_a, gcc_gp1_clk_b, gcc_gp2_clk_a, + gcc_gp2_clk_b, gcc_gp3_clk_a, gcc_gp3_clk_b, gpio, gsm0_tx0, gsm0_tx1, + gsm1_tx0, gsm1_tx1, gyro_accl, kpsns0, kpsns1, kpsns2, ldo_en, + ldo_update, mag_int, mdp_vsync, modem_tsync, m_voc, nav_pps, nav_tsync, + pa_indicator, pbs0, pbs1, pbs2, pri_mi2s, pri_mi2s_ws, prng_rosc, + pwr_crypto_enabled_a, pwr_crypto_enabled_b, pwr_modem_enabled_a, + pwr_modem_enabled_b, pwr_nav_enabled_a, pwr_nav_enabled_b, + qdss_ctitrig_in_a0, qdss_ctitrig_in_a1, qdss_ctitrig_in_b0, + qdss_ctitrig_in_b1, qdss_ctitrig_out_a0, qdss_ctitrig_out_a1, + qdss_ctitrig_out_b0, qdss_ctitrig_out_b1, qdss_traceclk_a, + qdss_traceclk_b, qdss_tracectl_a, qdss_tracectl_b, qdss_tracedata_a, + qdss_tracedata_b, reset_n, sd_card, sd_write, sec_mi2s, smb_int, + ssbi_wtr0, ssbi_wtr1, uim1, uim2, uim3, uim_batt, wcss_bt, wcss_fm, + wcss_wlan, webcam1_rst + +- bias-disable: + Usage: optional + Value type: <none> + Definition: The specified pins should be configued as no pull. + +- bias-pull-down: + Usage: optional + Value type: <none> + Definition: The specified pins should be configued as pull down. + +- bias-pull-up: + Usage: optional + Value type: <none> + Definition: The specified pins should be configued as pull up. + +- output-high: + Usage: optional + Value type: <none> + Definition: The specified pins are configured in output mode, driven + high. + Not valid for sdc pins. + +- output-low: + Usage: optional + Value type: <none> + Definition: The specified pins are configured in output mode, driven + low. + Not valid for sdc pins. + +- drive-strength: + Usage: optional + Value type: <u32> + Definition: Selects the drive strength for the specified pins, in mA. + Valid values are: 2, 4, 6, 8, 10, 12, 14 and 16 + +Example: + + tlmm: pinctrl@1000000 { + compatible = "qcom,msm8916-pinctrl"; + reg = <0x1000000 0x300000>; + interrupts = <0 208 0>; + gpio-controller; + #gpio-cells = <2>; + interrupt-controller; + #interrupt-cells = <2>; + + uart2: uart2-default { + mux { + pins = "gpio4", "gpio5"; + function = "blsp_uart2"; + }; + + tx { + pins = "gpio4"; + drive-strength = <4>; + bias-disable; + }; + + rx { + pins = "gpio5"; + drive-strength = <2>; + bias-pull-up; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,pmic-gpio.txt b/Documentation/devicetree/bindings/pinctrl/qcom,pmic-gpio.txt new file mode 100644 index 000000000000..7ed08048516a --- /dev/null +++ b/Documentation/devicetree/bindings/pinctrl/qcom,pmic-gpio.txt @@ -0,0 +1,215 @@ +Qualcomm PMIC GPIO block + +This binding describes the GPIO block(s) found in the 8xxx series of +PMIC's from Qualcomm. + +- compatible: + Usage: required + Value type: <string> + Definition: must be one of: + "qcom,pm8018-gpio" + "qcom,pm8038-gpio" + "qcom,pm8058-gpio" + "qcom,pm8917-gpio" + "qcom,pm8921-gpio" + "qcom,pm8941-gpio" + "qcom,pma8084-gpio" + +- reg: + Usage: required + Value type: <prop-encoded-array> + Definition: Register base of the GPIO block and length. + +- interrupts: + Usage: required + Value type: <prop-encoded-array> + Definition: Must contain an array of encoded interrupt specifiers for + each available GPIO + +- gpio-controller: + Usage: required + Value type: <none> + Definition: Mark the device node as a GPIO controller + +- #gpio-cells: + Usage: required + Value type: <u32> + Definition: Must be 2; + the first cell will be used to define gpio number and the + second denotes the flags for this gpio + +Please refer to ../gpio/gpio.txt and ../interrupt-controller/interrupts.txt for +a general description of GPIO and interrupt bindings. + +Please refer to pinctrl-bindings.txt in this directory for details of the +common pinctrl bindings used by client devices, including the meaning of the +phrase "pin configuration node". + +The pin configuration nodes act as a container for an arbitrary number of +subnodes. Each of these subnodes represents some desired configuration for a +pin or a list of pins. This configuration can include the +mux function to select on those pin(s), and various pin configuration +parameters, as listed below. + + +SUBNODES: + +The name of each subnode is not important; all subnodes should be enumerated +and processed purely based on their content. + +Each subnode only affects those parameters that are explicitly listed. In +other words, a subnode that lists a mux function but no pin configuration +parameters implies no information about any pin configuration parameters. +Similarly, a pin subnode that describes a pullup parameter implies no +information about e.g. the mux function. + +The following generic properties as defined in pinctrl-bindings.txt are valid +to specify in a pin configuration subnode: + +- pins: + Usage: required + Value type: <string-array> + Definition: List of gpio pins affected by the properties specified in + this subnode. Valid pins are: + gpio1-gpio6 for pm8018 + gpio1-gpio12 for pm8038 + gpio1-gpio40 for pm8058 + gpio1-gpio38 for pm8917 + gpio1-gpio44 for pm8921 + gpio1-gpio36 for pm8941 + gpio1-gpio22 for pma8084 + +- function: + Usage: required + Value type: <string> + Definition: Specify the alternative function to be configured for the + specified pins. Valid values are: + "normal", + "paired", + "func1", + "func2", + "dtest1", + "dtest2", + "dtest3", + "dtest4" + +- bias-disable: + Usage: optional + Value type: <none> + Definition: The specified pins should be configured as no pull. + +- bias-pull-down: + Usage: optional + Value type: <none> + Definition: The specified pins should be configured as pull down. + +- bias-pull-up: + Usage: optional + Value type: <empty> + Definition: The specified pins should be configured as pull up. + +- qcom,pull-up-strength: + Usage: optional + Value type: <u32> + Definition: Specifies the strength to use for pull up, if selected. + Valid values are; as defined in + <dt-bindings/pinctrl/qcom,pmic-gpio.h>: + 1: 30uA (PMIC_GPIO_PULL_UP_30) + 2: 1.5uA (PMIC_GPIO_PULL_UP_1P5) + 3: 31.5uA (PMIC_GPIO_PULL_UP_31P5) + 4: 1.5uA + 30uA boost (PMIC_GPIO_PULL_UP_1P5_30) + If this property is ommited 30uA strength will be used if + pull up is selected + +- bias-high-impedance: + Usage: optional + Value type: <none> + Definition: The specified pins will put in high-Z mode and disabled. + +- input-enable: + Usage: optional + Value type: <none> + Definition: The specified pins are put in input mode. + +- output-high: + Usage: optional + Value type: <none> + Definition: The specified pins are configured in output mode, driven + high. + +- output-low: + Usage: optional + Value type: <none> + Definition: The specified pins are configured in output mode, driven + low. + +- power-source: + Usage: optional + Value type: <u32> + Definition: Selects the power source for the specified pins. Valid + power sources are defined per chip in + <dt-bindings/pinctrl/qcom,pmic-gpio.h> + +- qcom,drive-strength: + Usage: optional + Value type: <u32> + Definition: Selects the drive strength for the specified pins. Value + drive strengths are: + 0: no (PMIC_GPIO_STRENGTH_NO) + 1: high (PMIC_GPIO_STRENGTH_HIGH) 0.9mA @ 1.8V - 1.9mA @ 2.6V + 2: medium (PMIC_GPIO_STRENGTH_MED) 0.6mA @ 1.8V - 1.25mA @ 2.6V + 3: low (PMIC_GPIO_STRENGTH_LOW) 0.15mA @ 1.8V - 0.3mA @ 2.6V + as defined in <dt-bindings/pinctrl/qcom,pmic-gpio.h> + +- drive-push-pull: + Usage: optional + Value type: <none> + Definition: The specified pins are configured in push-pull mode. + +- drive-open-drain: + Usage: optional + Value type: <none> + Definition: The specified pins are configured in open-drain mode. + +- drive-open-source: + Usage: optional + Value type: <none> + Definition: The specified pins are configured in open-source mode. + +Example: + + pm8921_gpio: gpio@150 { + compatible = "qcom,pm8921-gpio"; + reg = <0x150 0x160>; + interrupts = <192 1>, <193 1>, <194 1>, + <195 1>, <196 1>, <197 1>, + <198 1>, <199 1>, <200 1>, + <201 1>, <202 1>, <203 1>, + <204 1>, <205 1>, <206 1>, + <207 1>, <208 1>, <209 1>, + <210 1>, <211 1>, <212 1>, + <213 1>, <214 1>, <215 1>, + <216 1>, <217 1>, <218 1>, + <219 1>, <220 1>, <221 1>, + <222 1>, <223 1>, <224 1>, + <225 1>, <226 1>, <227 1>, + <228 1>, <229 1>, <230 1>, + <231 1>, <232 1>, <233 1>, + <234 1>, <235 1>; + + gpio-controller; + #gpio-cells = <2>; + + pm8921_gpio_keys: gpio-keys { + volume-keys { + pins = "gpio20", "gpio21"; + function = "normal"; + + input-enable; + bias-pull-up; + drive-push-pull; + qcom,drive-strength = <PMIC_GPIO_STRENGTH_NO>; + power-source = <PM8921_GPIO_S4>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,pmic-mpp.txt b/Documentation/devicetree/bindings/pinctrl/qcom,pmic-mpp.txt new file mode 100644 index 000000000000..854774b194ed --- /dev/null +++ b/Documentation/devicetree/bindings/pinctrl/qcom,pmic-mpp.txt @@ -0,0 +1,162 @@ +Qualcomm PMIC Multi-Purpose Pin (MPP) block + +This binding describes the MPP block(s) found in the 8xxx series +of PMIC's from Qualcomm. + +- compatible: + Usage: required + Value type: <string> + Definition: Should contain one of: + "qcom,pm8841-mpp", + "qcom,pm8941-mpp", + "qcom,pma8084-mpp", + +- reg: + Usage: required + Value type: <prop-encoded-array> + Definition: Register base of the MPP block and length. + +- interrupts: + Usage: required + Value type: <prop-encoded-array> + Definition: Must contain an array of encoded interrupt specifiers for + each available MPP + +- gpio-controller: + Usage: required + Value type: <none> + Definition: Mark the device node as a GPIO controller + +- #gpio-cells: + Usage: required + Value type: <u32> + Definition: Must be 2; + the first cell will be used to define MPP number and the + second denotes the flags for this MPP + +Please refer to ../gpio/gpio.txt and ../interrupt-controller/interrupts.txt for +a general description of GPIO and interrupt bindings. + +Please refer to pinctrl-bindings.txt in this directory for details of the +common pinctrl bindings used by client devices, including the meaning of the +phrase "pin configuration node". + +The pin configuration nodes act as a container for an arbitrary number of +subnodes. Each of these subnodes represents some desired configuration for a +pin or a list of pins. This configuration can include the +mux function to select on those pin(s), and various pin configuration +parameters, as listed below. + +SUBNODES: + +The name of each subnode is not important; all subnodes should be enumerated +and processed purely based on their content. + +Each subnode only affects those parameters that are explicitly listed. In +other words, a subnode that lists a mux function but no pin configuration +parameters implies no information about any pin configuration parameters. +Similarly, a pin subnode that describes a pullup parameter implies no +information about e.g. the mux function. + +The following generic properties as defined in pinctrl-bindings.txt are valid +to specify in a pin configuration subnode: + +- pins: + Usage: required + Value type: <string-array> + Definition: List of MPP pins affected by the properties specified in + this subnode. Valid pins are: + mpp1-mpp4 for pm8841 + mpp1-mpp8 for pm8941 + mpp1-mpp4 for pma8084 + +- function: + Usage: required + Value type: <string> + Definition: Specify the alternative function to be configured for the + specified pins. Valid values are: + "normal", + "paired", + "dtest1", + "dtest2", + "dtest3", + "dtest4" + +- bias-disable: + Usage: optional + Value type: <none> + Definition: The specified pins should be configured as no pull. + +- bias-pull-up: + Usage: optional + Value type: <u32> + Definition: The specified pins should be configured as pull up. + Valid values are 600, 10000 and 30000 in bidirectional mode + only, i.e. when operating in qcom,analog-mode and input and + outputs are enabled. The hardware ignores the configuration + when operating in other modes. + +- bias-high-impedance: + Usage: optional + Value type: <none> + Definition: The specified pins will put in high-Z mode and disabled. + +- input-enable: + Usage: optional + Value type: <none> + Definition: The specified pins are put in input mode, i.e. their input + buffer is enabled + +- output-high: + Usage: optional + Value type: <none> + Definition: The specified pins are configured in output mode, driven + high. + +- output-low: + Usage: optional + Value type: <none> + Definition: The specified pins are configured in output mode, driven + low. + +- power-source: + Usage: optional + Value type: <u32> + Definition: Selects the power source for the specified pins. Valid power + sources are defined in <dt-bindings/pinctrl/qcom,pmic-mpp.h> + +- qcom,analog-mode: + Usage: optional + Value type: <none> + Definition: Selects Analog mode of operation: combined with input-enable + and/or output-high, output-low MPP could operate as + Bidirectional Logic, Analog Input, Analog Output. + +- qcom,amux-route: + Usage: optional + Value type: <u32> + Definition: Selects the source for analog input. Valid values are + defined in <dt-bindings/pinctrl/qcom,pmic-mpp.h> + PMIC_MPP_AMUX_ROUTE_CH5, PMIC_MPP_AMUX_ROUTE_CH6... + +Example: + + mpps@a000 { + compatible = "qcom,pm8841-mpp"; + reg = <0xa000>; + gpio-controller; + #gpio-cells = <2>; + interrupts = <4 0xa0 0 0>, <4 0xa1 0 0>, <4 0xa2 0 0>, <4 0xa3 0 0>; + + pinctrl-names = "default"; + pinctrl-0 = <&pm8841_default>; + + pm8841_default: default { + gpio { + pins = "mpp1", "mpp2", "mpp3", "mpp4"; + function = "normal"; + input-enable; + power-source = <PM8841_MPP_S3>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/pinctrl/renesas,pfc-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/renesas,pfc-pinctrl.txt index daef6fad6a5f..bfe72ec055e3 100644 --- a/Documentation/devicetree/bindings/pinctrl/renesas,pfc-pinctrl.txt +++ b/Documentation/devicetree/bindings/pinctrl/renesas,pfc-pinctrl.txt @@ -1,7 +1,7 @@ * Renesas Pin Function Controller (GPIO and Pin Mux/Config) -The Pin Function Controller (PFC) is a Pin Mux/Config controller. On SH7372, -SH73A0, R8A73A4 and R8A7740 it also acts as a GPIO controller. +The Pin Function Controller (PFC) is a Pin Mux/Config controller. On SH73A0, +R8A73A4 and R8A7740 it also acts as a GPIO controller. Pin Control @@ -10,13 +10,13 @@ Pin Control Required Properties: - compatible: should be one of the following. + - "renesas,pfc-emev2": for EMEV2 (EMMA Mobile EV2) compatible pin-controller. - "renesas,pfc-r8a73a4": for R8A73A4 (R-Mobile APE6) compatible pin-controller. - "renesas,pfc-r8a7740": for R8A7740 (R-Mobile A1) compatible pin-controller. - "renesas,pfc-r8a7778": for R8A7778 (R-Mobile M1) compatible pin-controller. - "renesas,pfc-r8a7779": for R8A7779 (R-Car H1) compatible pin-controller. - "renesas,pfc-r8a7790": for R8A7790 (R-Car H2) compatible pin-controller. - "renesas,pfc-r8a7791": for R8A7791 (R-Car M2) compatible pin-controller. - - "renesas,pfc-sh7372": for SH7372 (SH-Mobile AP4) compatible pin-controller. - "renesas,pfc-sh73a0": for SH73A0 (SH-Mobile AG5) compatible pin-controller. - reg: Base address and length of each memory resource used by the pin @@ -75,8 +75,7 @@ bias-disable, bias-pull-up and bias-pull-down. GPIO ---- -On SH7372, SH73A0, R8A73A4 and R8A7740 the PFC node is also a GPIO controller -node. +On SH73A0, R8A73A4 and R8A7740 the PFC node is also a GPIO controller node. Required Properties: diff --git a/Documentation/devicetree/bindings/pinctrl/samsung-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/samsung-pinctrl.txt index e82aaf492517..9d2a995293e6 100644 --- a/Documentation/devicetree/bindings/pinctrl/samsung-pinctrl.txt +++ b/Documentation/devicetree/bindings/pinctrl/samsung-pinctrl.txt @@ -18,6 +18,7 @@ Required Properties: - "samsung,exynos5250-pinctrl": for Exynos5250 compatible pin-controller. - "samsung,exynos5260-pinctrl": for Exynos5260 compatible pin-controller. - "samsung,exynos5420-pinctrl": for Exynos5420 compatible pin-controller. + - "samsung,exynos7-pinctrl": for Exynos7 compatible pin-controller. - reg: Base address of the pin controller hardware module and length of the address space it occupies. @@ -136,6 +137,8 @@ B. External Wakeup Interrupts: For supporting external wakeup interrupts, a found on Samsung S3C64xx SoCs, - samsung,exynos4210-wakeup-eint: represents wakeup interrupt controller found on Samsung Exynos4210 and S5PC110/S5PV210 SoCs. + - samsung,exynos7-wakeup-eint: represents wakeup interrupt controller + found on Samsung Exynos7 SoC. - interrupt-parent: phandle of the interrupt parent to which the external wakeup interrupts are forwarded to. - interrupts: interrupt used by multiplexed wakeup interrupts. @@ -168,6 +171,18 @@ Aliases: All the pin controller nodes should be represented in the aliases node using the following format 'pinctrl{n}' where n is a unique number for the alias. +Aliases for controllers compatible with "samsung,exynos7-pinctrl": +- pinctrl0: pin controller of ALIVE block, +- pinctrl1: pin controller of BUS0 block, +- pinctrl2: pin controller of NFC block, +- pinctrl3: pin controller of TOUCH block, +- pinctrl4: pin controller of FF block, +- pinctrl5: pin controller of ESE block, +- pinctrl6: pin controller of FSYS0 block, +- pinctrl7: pin controller of FSYS1 block, +- pinctrl8: pin controller of BUS1 block, +- pinctrl9: pin controller of AUDIO block, + Example: A pin-controller node with pin banks: pinctrl_0: pinctrl@11400000 { diff --git a/Documentation/devicetree/bindings/pinctrl/ste,abx500.txt b/Documentation/devicetree/bindings/pinctrl/ste,abx500.txt index e3865e136067..87697420439e 100644 --- a/Documentation/devicetree/bindings/pinctrl/ste,abx500.txt +++ b/Documentation/devicetree/bindings/pinctrl/ste,abx500.txt @@ -8,42 +8,8 @@ Please refer to pinctrl-bindings.txt in this directory for details of the common pinctrl bindings used by client devices, including the meaning of the phrase "pin configuration node". -ST Ericsson's pin configuration nodes act as a container for an arbitrary number of -subnodes. Each of these subnodes represents some desired configuration for a -pin, a group, or a list of pins or groups. This configuration can include the -mux function to select on those pin(s)/group(s), and various pin configuration -parameters, such as input, output, pull up, pull down... - -The name of each subnode is not important; all subnodes should be enumerated -and processed purely based on their content. - -Required subnode-properties: -- ste,pins : An array of strings. Each string contains the name of a pin or - group. - -Optional subnode-properties: -- ste,function: A string containing the name of the function to mux to the - pin or group. - -- generic pin configuration option to use. Example : - - default_cfg { - ste,pins = "GPIO1"; - bias-disable; - }; - -- ste,config: Handle of pin configuration node containing the generic - pinconfig options to use, as described in pinctrl-bindings.txt in - this directory. Example : - - pcfg_bias_disable: pcfg_bias_disable { - bias-disable; - }; - - default_cfg { - ste,pins = "GPIO1"; - ste.config = <&pcfg_bias_disable>; - }; +ST Ericsson's pin configuration nodes use the generic pin multiplexing +and pin configuration bindings, see pinctrl-bindings.txt Example board file extract: @@ -54,11 +20,11 @@ Example board file extract: sysclkreq2 { sysclkreq2_default_mode: sysclkreq2_default { default_mux { - ste,function = "sysclkreq"; - ste,pins = "sysclkreq2_d_1"; + function = "sysclkreq"; + groups = "sysclkreq2_d_1"; }; default_cfg { - ste,pins = "GPIO1"; + pins = "GPIO1"; bias-disable; }; }; @@ -66,11 +32,11 @@ Example board file extract: sysclkreq3 { sysclkreq3_default_mode: sysclkreq3_default { default_mux { - ste,function = "sysclkreq"; - ste,pins = "sysclkreq3_d_1"; + function = "sysclkreq"; + groups = "sysclkreq3_d_1"; }; default_cfg { - ste,pins = "GPIO2"; + pins = "GPIO2"; output-low; }; }; @@ -78,11 +44,11 @@ Example board file extract: gpio3 { gpio3_default_mode: gpio3_default { default_mux { - ste,function = "gpio"; - ste,pins = "gpio3_a_1"; + function = "gpio"; + groups = "gpio3_a_1"; }; default_cfg { - ste,pins = "GPIO3"; + pins = "GPIO3"; output-low; }; }; @@ -90,11 +56,11 @@ Example board file extract: sysclkreq6 { sysclkreq6_default_mode: sysclkreq6_default { default_mux { - ste,function = "sysclkreq"; - ste,pins = "sysclkreq6_d_1"; + function = "sysclkreq"; + groups = "sysclkreq6_d_1"; }; default_cfg { - ste,pins = "GPIO4"; + pins = "GPIO4"; bias-disable; }; }; @@ -102,11 +68,11 @@ Example board file extract: pwmout1 { pwmout1_default_mode: pwmout1_default { default_mux { - ste,function = "pwmout"; - ste,pins = "pwmout1_d_1"; + function = "pwmout"; + groups = "pwmout1_d_1"; }; default_cfg { - ste,pins = "GPIO14"; + pins = "GPIO14"; output-low; }; }; @@ -114,11 +80,11 @@ Example board file extract: pwmout2 { pwmout2_default_mode: pwmout2_default { pwmout2_default_mux { - ste,function = "pwmout"; - ste,pins = "pwmout2_d_1"; + function = "pwmout"; + groups = "pwmout2_d_1"; }; pwmout2_default_cfg { - ste,pins = "GPIO15"; + pins = "GPIO15"; output-low; }; }; @@ -126,11 +92,11 @@ Example board file extract: pwmout3 { pwmout3_default_mode: pwmout3_default { pwmout3_default_mux { - ste,function = "pwmout"; - ste,pins = "pwmout3_d_1"; + function = "pwmout"; + groups = "pwmout3_d_1"; }; pwmout3_default_cfg { - ste,pins = "GPIO16"; + pins = "GPIO16"; output-low; }; }; @@ -139,15 +105,15 @@ Example board file extract: adi1_default_mode: adi1_default { adi1_default_mux { - ste,function = "adi1"; - ste,pins = "adi1_d_1"; + function = "adi1"; + groups = "adi1_d_1"; }; adi1_default_cfg1 { - ste,pins = "GPIO17","GPIO19","GPIO20"; + pins = "GPIO17","GPIO19","GPIO20"; bias-disable; }; adi1_default_cfg2 { - ste,pins = "GPIO18"; + pins = "GPIO18"; output-low; }; }; @@ -155,15 +121,15 @@ Example board file extract: dmic12 { dmic12_default_mode: dmic12_default { dmic12_default_mux { - ste,function = "dmic"; - ste,pins = "dmic12_d_1"; + function = "dmic"; + groups = "dmic12_d_1"; }; dmic12_default_cfg1 { - ste,pins = "GPIO27"; + pins = "GPIO27"; output-low; }; dmic12_default_cfg2 { - ste,pins = "GPIO28"; + pins = "GPIO28"; bias-disable; }; }; @@ -171,15 +137,15 @@ Example board file extract: dmic34 { dmic34_default_mode: dmic34_default { dmic34_default_mux { - ste,function = "dmic"; - ste,pins = "dmic34_d_1"; + function = "dmic"; + groups = "dmic34_d_1"; }; dmic34_default_cfg1 { - ste,pins = "GPIO29"; + pins = "GPIO29"; output-low; }; dmic34_default_cfg2 { - ste,pins = "GPIO30"; + pins = "GPIO30"; bias-disable;{ }; @@ -188,15 +154,15 @@ Example board file extract: dmic56 { dmic56_default_mode: dmic56_default { dmic56_default_mux { - ste,function = "dmic"; - ste,pins = "dmic56_d_1"; + function = "dmic"; + groups = "dmic56_d_1"; }; dmic56_default_cfg1 { - ste,pins = "GPIO31"; + pins = "GPIO31"; output-low; }; dmic56_default_cfg2 { - ste,pins = "GPIO32"; + pins = "GPIO32"; bias-disable; }; }; @@ -204,11 +170,11 @@ Example board file extract: sysclkreq5 { sysclkreq5_default_mode: sysclkreq5_default { sysclkreq5_default_mux { - ste,function = "sysclkreq"; - ste,pins = "sysclkreq5_d_1"; + function = "sysclkreq"; + groups = "sysclkreq5_d_1"; }; sysclkreq5_default_cfg { - ste,pins = "GPIO42"; + pins = "GPIO42"; output-low; }; }; @@ -216,11 +182,11 @@ Example board file extract: batremn { batremn_default_mode: batremn_default { batremn_default_mux { - ste,function = "batremn"; - ste,pins = "batremn_d_1"; + function = "batremn"; + groups = "batremn_d_1"; }; batremn_default_cfg { - ste,pins = "GPIO43"; + pins = "GPIO43"; bias-disable; }; }; @@ -228,11 +194,11 @@ Example board file extract: service { service_default_mode: service_default { service_default_mux { - ste,function = "service"; - ste,pins = "service_d_1"; + function = "service"; + groups = "service_d_1"; }; service_default_cfg { - ste,pins = "GPIO44"; + pins = "GPIO44"; bias-disable; }; }; @@ -240,13 +206,13 @@ Example board file extract: pwrctrl0 { pwrctrl0_default_mux: pwrctrl0_mux { pwrctrl0_default_mux { - ste,function = "pwrctrl"; - ste,pins = "pwrctrl0_d_1"; + function = "pwrctrl"; + groups = "pwrctrl0_d_1"; }; }; pwrctrl0_default_mode: pwrctrl0_default { pwrctrl0_default_cfg { - ste,pins = "GPIO45"; + pins = "GPIO45"; bias-disable; }; }; @@ -254,13 +220,13 @@ Example board file extract: pwrctrl1 { pwrctrl1_default_mux: pwrctrl1_mux { pwrctrl1_default_mux { - ste,function = "pwrctrl"; - ste,pins = "pwrctrl1_d_1"; + function = "pwrctrl"; + groups = "pwrctrl1_d_1"; }; }; pwrctrl1_default_mode: pwrctrl1_default { pwrctrl1_default_cfg { - ste,pins = "GPIO46"; + pins = "GPIO46"; bias-disable; }; }; @@ -268,11 +234,11 @@ Example board file extract: pwmextvibra1 { pwmextvibra1_default_mode: pwmextvibra1_default { pwmextvibra1_default_mux { - ste,function = "pwmextvibra"; - ste,pins = "pwmextvibra1_d_1"; + function = "pwmextvibra"; + groups = "pwmextvibra1_d_1"; }; pwmextvibra1_default_cfg { - ste,pins = "GPIO47"; + pins = "GPIO47"; bias-disable; }; }; @@ -280,11 +246,11 @@ Example board file extract: pwmextvibra2 { pwmextvibra2_default_mode: pwmextvibra2_default { pwmextvibra2_default_mux { - ste,function = "pwmextvibra"; - ste,pins = "pwmextvibra2_d_1"; + function = "pwmextvibra"; + groups = "pwmextvibra2_d_1"; }; pwmextvibra1_default_cfg { - ste,pins = "GPIO48"; + pins = "GPIO48"; bias-disable; }; }; @@ -292,11 +258,11 @@ Example board file extract: gpio51 { gpio51_default_mode: gpio51_default { gpio51_default_mux { - ste,function = "gpio"; - ste,pins = "gpio51_a_1"; + function = "gpio"; + groups = "gpio51_a_1"; }; gpio51_default_cfg { - ste,pins = "GPIO51"; + pins = "GPIO51"; output-low; }; }; @@ -304,11 +270,11 @@ Example board file extract: gpio52 { gpio52_default_mode: gpio52_default { gpio52_default_mux { - ste,function = "gpio"; - ste,pins = "gpio52_a_1"; + function = "gpio"; + groups = "gpio52_a_1"; }; gpio52_default_cfg { - ste,pins = "GPIO52"; + pins = "GPIO52"; bias-pull-down; }; }; @@ -316,11 +282,11 @@ Example board file extract: gpio53 { gpio53_default_mode: gpio53_default { gpio53_default_mux { - ste,function = "gpio"; - ste,pins = "gpio53_a_1"; + function = "gpio"; + groups = "gpio53_a_1"; }; gpio53_default_cfg { - ste,pins = "GPIO53"; + pins = "GPIO53"; bias-pull-down; }; }; @@ -328,11 +294,11 @@ Example board file extract: gpio54 { gpio54_default_mode: gpio54_default { gpio54_default_mux { - ste,function = "gpio"; - ste,pins = "gpio54_a_1"; + function = "gpio"; + groups = "gpio54_a_1"; }; gpio54_default_cfg { - ste,pins = "GPIO54"; + pins = "GPIO54"; output-low; }; }; @@ -340,11 +306,11 @@ Example board file extract: pdmclkdat { pdmclkdat_default_mode: pdmclkdat_default { pdmclkdat_default_mux { - ste,function = "pdm"; - ste,pins = "pdmclkdat_d_1"; + function = "pdm"; + groups = "pdmclkdat_d_1"; }; pdmclkdat_default_cfg { - ste,pins = "GPIO55", "GPIO56"; + pins = "GPIO55", "GPIO56"; bias-disable; }; }; diff --git a/Documentation/devicetree/bindings/pinctrl/ste,nomadik.txt b/Documentation/devicetree/bindings/pinctrl/ste,nomadik.txt index 6b33b9f18e88..f63fcb3ed352 100644 --- a/Documentation/devicetree/bindings/pinctrl/ste,nomadik.txt +++ b/Documentation/devicetree/bindings/pinctrl/ste,nomadik.txt @@ -16,17 +16,22 @@ mux function to select on those pin(s)/group(s), and various pin configuration parameters, such as input, output, pull up, pull down... The name of each subnode is not important; all subnodes should be enumerated -and processed purely based on their content. +and processed purely based on their content. The subnodes use the generic +pin multiplexing node layout from the standard pin control bindings +(see pinctrl-bindings.txt): -Required subnode-properties: -- ste,pins : An array of strings. Each string contains the name of a pin or - group. - -Optional subnode-properties: -- ste,function: A string containing the name of the function to mux to the +Required pin multiplexing subnode properties: +- function: A string containing the name of the function to mux to the pin or group. +- groups : An array of strings. Each string contains the name of a pin + group that will be combined with the function to form a multiplexing + set-up. -- ste,config: Handle of pin configuration node (e.g. ste,config = <&slpm_in_wkup_pdis>) +Required pin configuration subnode properties: +- pins: A string array describing the pins affected by the configuration + in the node. +- ste,config: Handle of pin configuration node + (e.g. ste,config = <&slpm_in_wkup_pdis>) - ste,input : <0/1/2> 0: input with no pull @@ -97,32 +102,32 @@ Example board file extract: uart0 { uart0_default_mux: uart0_mux { u0_default_mux { - ste,function = "u0"; - ste,pins = "u0_a_1"; + function = "u0"; + pins = "u0_a_1"; }; }; uart0_default_mode: uart0_default { uart0_default_cfg1 { - ste,pins = "GPIO0", "GPIO2"; + pins = "GPIO0", "GPIO2"; ste,input = <1>; }; uart0_default_cfg2 { - ste,pins = "GPIO1", "GPIO3"; + pins = "GPIO1", "GPIO3"; ste,output = <1>; }; }; uart0_sleep_mode: uart0_sleep { uart0_sleep_cfg1 { - ste,pins = "GPIO0", "GPIO2"; + pins = "GPIO0", "GPIO2"; ste,config = <&slpm_in_wkup_pdis>; }; uart0_sleep_cfg2 { - ste,pins = "GPIO1"; + pins = "GPIO1"; ste,config = <&slpm_out_hi_wkup_pdis>; }; uart0_sleep_cfg3 { - ste,pins = "GPIO3"; + pins = "GPIO3"; ste,config = <&slpm_out_wkup_pdis>; }; }; diff --git a/Documentation/devicetree/bindings/pinctrl/xlnx,zynq-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/xlnx,zynq-pinctrl.txt new file mode 100644 index 000000000000..b7b55a964f65 --- /dev/null +++ b/Documentation/devicetree/bindings/pinctrl/xlnx,zynq-pinctrl.txt @@ -0,0 +1,104 @@ + Binding for Xilinx Zynq Pinctrl + +Required properties: +- compatible: "xlnx,zynq-pinctrl" +- syscon: phandle to SLCR +- reg: Offset and length of pinctrl space in SLCR + +Please refer to pinctrl-bindings.txt in this directory for details of the +common pinctrl bindings used by client devices, including the meaning of the +phrase "pin configuration node". + +Zynq's pin configuration nodes act as a container for an arbitrary number of +subnodes. Each of these subnodes represents some desired configuration for a +pin, a group, or a list of pins or groups. This configuration can include the +mux function to select on those pin(s)/group(s), and various pin configuration +parameters, such as pull-up, slew rate, etc. + +Each configuration node can consist of multiple nodes describing the pinmux and +pinconf options. Those nodes can be pinmux nodes or pinconf nodes. + +The name of each subnode is not important; all subnodes should be enumerated +and processed purely based on their content. + +Required properties for pinmux nodes are: + - groups: A list of pinmux groups. + - function: The name of a pinmux function to activate for the specified set + of groups. + +Required properties for configuration nodes: +One of: + - pins: a list of pin names + - groups: A list of pinmux groups. + +The following generic properties as defined in pinctrl-bindings.txt are valid +to specify in a pinmux subnode: + groups, function + +The following generic properties as defined in pinctrl-bindings.txt are valid +to specify in a pinconf subnode: + groups, pins, bias-disable, bias-high-impedance, bias-pull-up, slew-rate, + low-power-disable, low-power-enable + + Valid arguments for 'slew-rate' are '0' and '1' to select between slow and fast + respectively. + + Valid values for groups are: + ethernet0_0_grp, ethernet1_0_grp, mdio0_0_grp, mdio1_0_grp, + qspi0_0_grp, qspi1_0_grp, qspi_fbclk, qspi_cs1_grp, spi0_0_grp, + spi0_1_grp - spi0_2_grp, spi1_0_grp - spi1_3_grp, sdio0_0_grp - sdio0_2_grp, + sdio1_0_grp - sdio1_3_grp, sdio0_emio_wp, sdio0_emio_cd, sdio1_emio_wp, + sdio1_emio_cd, smc0_nor, smc0_nor_cs1_grp, smc0_nor_addr25_grp, smc0_nand, + can0_0_grp - can0_10_grp, can1_0_grp - can1_11_grp, uart0_0_grp - uart0_10_grp, + uart1_0_grp - uart1_11_grp, i2c0_0_grp - i2c0_10_grp, i2c1_0_grp - i2c1_10_grp, + ttc0_0_grp - ttc0_2_grp, ttc1_0_grp - ttc1_2_grp, swdt0_0_grp - swdt0_4_grp, + gpio0_0_grp - gpio0_53_grp, usb0_0_grp, usb1_0_grp + + Valid values for pins are: + MIO0 - MIO53 + + Valid values for function are: + ethernet0, ethernet1, mdio0, mdio1, qspi0, qspi1, qspi_fbclk, qspi_cs1, + spi0, spi1, sdio0, sdio0_pc, sdio0_cd, sdio0_wp, + sdio1, sdio1_pc, sdio1_cd, sdio1_wp, + smc0_nor, smc0_nor_cs1, smc0_nor_addr25, smc0_nand, can0, can1, uart0, uart1, + i2c0, i2c1, ttc0, ttc1, swdt0, gpio0, usb0, usb1 + +The following driver-specific properties as defined here are valid to specify in +a pin configuration subnode: + - io-standard: Configure the pin to use the selected IO standard according to + this mapping: + 1: LVCMOS18 + 2: LVCMOS25 + 3: LVCMOS33 + 4: HSTL + +Example: + pinctrl0: pinctrl@700 { + compatible = "xlnx,pinctrl-zynq"; + reg = <0x700 0x200>; + syscon = <&slcr>; + + pinctrl_uart1_default: uart1-default { + mux { + groups = "uart1_10_grp"; + function = "uart1"; + }; + + conf { + groups = "uart1_10_grp"; + slew-rate = <0>; + io-standard = <1>; + }; + + conf-rx { + pins = "MIO49"; + bias-high-impedance; + }; + + conf-tx { + pins = "MIO48"; + bias-disable; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/power/ltc2941.txt b/Documentation/devicetree/bindings/power/ltc2941.txt new file mode 100644 index 000000000000..ea42ae12d924 --- /dev/null +++ b/Documentation/devicetree/bindings/power/ltc2941.txt @@ -0,0 +1,27 @@ +binding for LTC2941 and LTC2943 battery gauges + +Both the LTC2941 and LTC2943 measure battery capacity. +The LTC2943 is compatible with the LTC2941, it adds voltage and +temperature monitoring, and uses a slightly different conversion +formula for the charge counter. + +Required properties: +- compatible: Should contain "ltc2941" or "ltc2943" which also indicates the + type of I2C chip attached. +- reg: The 7-bit I2C address. +- lltc,resistor-sense: The sense resistor value in milli-ohms. Can be a 32-bit + negative value when the battery has been connected to the wrong end of the + resistor. +- lltc,prescaler-exponent: The prescaler exponent as explained in the datasheet. + This determines the range and accuracy of the gauge. The value is programmed + into the chip only if it differs from the current setting. The setting is + lost when the battery is disconnected. + +Example from the Topic Miami Florida board: + + fuelgauge: ltc2943@64 { + compatible = "ltc2943"; + reg = <0x64>; + lltc,resistor-sense = <15>; + lltc,prescaler-exponent = <5>; /* 2^(2*5) = 1024 */ + }; diff --git a/Documentation/devicetree/bindings/power/power-controller.txt b/Documentation/devicetree/bindings/power/power-controller.txt new file mode 100644 index 000000000000..4f7a3bc9c407 --- /dev/null +++ b/Documentation/devicetree/bindings/power/power-controller.txt @@ -0,0 +1,18 @@ +* Generic system power control capability + +Power-management integrated circuits or miscellaneous hardware components are +sometimes able to control the system power. The device driver associated with these +components might need to define this capability, which tells the kernel that +it can be used to switch off the system. The corresponding device must have the +standard property "system-power-controller" in its device node. This property +marks the device as able to control the system power. In order to test if this +property is found programmatically, use the helper function +"of_device_is_system_power_controller" from of.h . + +Example: + +act8846: act8846@5 { + compatible = "active-semi,act8846"; + status = "okay"; + system-power-controller; +} diff --git a/Documentation/devicetree/bindings/power/renesas,sysc-rmobile.txt b/Documentation/devicetree/bindings/power/renesas,sysc-rmobile.txt new file mode 100644 index 000000000000..cc3b1f0a9b1a --- /dev/null +++ b/Documentation/devicetree/bindings/power/renesas,sysc-rmobile.txt @@ -0,0 +1,99 @@ +DT bindings for the Renesas R-Mobile System Controller + +== System Controller Node == + +The R-Mobile System Controller provides the following functions: + - Boot mode management, + - Reset generation, + - Power management. + +Required properties: +- compatible: Should be "renesas,sysc-<soctype>", "renesas,sysc-rmobile" as + fallback. + Examples with soctypes are: + - "renesas,sysc-r8a7740" (R-Mobile A1) + - "renesas,sysc-sh73a0" (SH-Mobile AG5) +- reg: Two address start and address range blocks for the device: + - The first block refers to the normally accessible registers, + - the second block refers to the registers protected by the HPB + semaphore. + +Optional nodes: +- pm-domains: This node contains a hierarchy of PM domain nodes, which should + match the Power Area Hierarchy in the Power Domain Specifications section of + the device's datasheet. + + +== PM Domain Nodes == + +Each of the PM domain nodes represents a PM domain, as documented by the +generic PM domain bindings in +Documentation/devicetree/bindings/power/power_domain.txt. + +The nodes should be named by the real power area names, and thus their names +should be unique. + +Required properties: + - #power-domain-cells: Must be 0. + +Optional properties: +- reg: If the PM domain is not always-on, this property must contain the bit + index number for the corresponding power area in the various Power + Control and Status Registers. The parent's node must contain the + following two properties: + - #address-cells: Must be 1, + - #size-cells: Must be 0. + If the PM domain is always-on, this property must be omitted. + + +Example: + +This shows a subset of the r8a7740 PM domain hierarchy, containing the +C5 "always-on" domain, 2 of its subdomains (A4S and A4SU), and the A3SP domain, +which is a subdomain of A4S. + + sysc: system-controller@e6180000 { + compatible = "renesas,sysc-r8a7740", "renesas,sysc-rmobile"; + reg = <0xe6180000 0x8000>, <0xe6188000 0x8000>; + + pm-domains { + pd_c5: c5 { + #address-cells = <1>; + #size-cells = <0>; + #power-domain-cells = <0>; + + pd_a4s: a4s@10 { + reg = <10>; + #address-cells = <1>; + #size-cells = <0>; + #power-domain-cells = <0>; + + pd_a3sp: a3sp@11 { + reg = <11>; + #power-domain-cells = <0>; + }; + }; + + pd_a4su: a4su@20 { + reg = <20>; + #power-domain-cells = <0>; + }; + }; + }; + }; + + +== PM Domain Consumers == + +Hardware blocks belonging to a PM domain should contain a "power-domains" +property that is a phandle pointing to the corresponding PM domain node. + +Example: + + tpu: pwm@e6600000 { + compatible = "renesas,tpu-r8a7740", "renesas,tpu"; + reg = <0xe6600000 0x100>; + clocks = <&mstp3_clks R8A7740_CLK_TPU0>; + power-domains = <&pd_a3sp>; + #pwm-cells = <3>; + }; diff --git a/Documentation/devicetree/bindings/power/reset/ltc2952-poweroff.txt b/Documentation/devicetree/bindings/power/reset/ltc2952-poweroff.txt index 0c94c637f63b..cd2d7f58a9d7 100644 --- a/Documentation/devicetree/bindings/power/reset/ltc2952-poweroff.txt +++ b/Documentation/devicetree/bindings/power/reset/ltc2952-poweroff.txt @@ -1,20 +1,23 @@ Binding for the LTC2952 PowerPath controller This chip is used to externally trigger a system shut down. Once the trigger has -been sent, the chips' watchdog has to be reset to gracefully shut down. -If the Linux systems decides to shut down it powers off the platform via the -kill signal. +been sent, the chip's watchdog has to be reset to gracefully shut down. +A full powerdown can be triggered via the kill signal. Required properties: - compatible: Must contain: "lltc,ltc2952" -- trigger-gpios: phandle + gpio-specifier for the GPIO connected to the - chip's trigger line - watchdog-gpios: phandle + gpio-specifier for the GPIO connected to the chip's watchdog line - kill-gpios: phandle + gpio-specifier for the GPIO connected to the chip's kill line +Optional properties: +- trigger-gpios: phandle + gpio-specifier for the GPIO connected to the + chip's trigger line. If this property is not set, the + trigger function is ignored and the chip is kept alive + until an explicit kill signal is received + Example: ltc2952 { diff --git a/Documentation/devicetree/bindings/power/rockchip-io-domain.txt b/Documentation/devicetree/bindings/power/rockchip-io-domain.txt index 6fbf6e7ecde6..8b70db103ca7 100644 --- a/Documentation/devicetree/bindings/power/rockchip-io-domain.txt +++ b/Documentation/devicetree/bindings/power/rockchip-io-domain.txt @@ -37,7 +37,7 @@ Required properties: You specify supplies using the standard regulator bindings by including -a phandle the the relevant regulator. All specified supplies must be able +a phandle the relevant regulator. All specified supplies must be able to report their voltage. The IO Voltage Domain for any non-specified supplies will be not be touched. diff --git a/Documentation/devicetree/bindings/power_supply/gpio-charger.txt b/Documentation/devicetree/bindings/power_supply/gpio-charger.txt new file mode 100644 index 000000000000..adbb5dc5b6e9 --- /dev/null +++ b/Documentation/devicetree/bindings/power_supply/gpio-charger.txt @@ -0,0 +1,27 @@ +gpio-charger + +Required properties : + - compatible : "gpio-charger" + - gpios : GPIO indicating the charger presence. + See GPIO binding in bindings/gpio/gpio.txt . + - charger-type : power supply type, one of + unknown + battery + ups + mains + usb-sdp (USB standard downstream port) + usb-dcp (USB dedicated charging port) + usb-cdp (USB charging downstream port) + usb-aca (USB accessory charger adapter) + +Example: + + usb_charger: charger { + compatible = "gpio-charger"; + charger-type = "usb-sdp"; + gpios = <&gpf0 2 0 0 0>; + } + + battery { + power-supplies = <&usb_charger>; + }; diff --git a/Documentation/devicetree/bindings/power_supply/imx-snvs-poweroff.txt b/Documentation/devicetree/bindings/power_supply/imx-snvs-poweroff.txt new file mode 100644 index 000000000000..dc7c9bad63ea --- /dev/null +++ b/Documentation/devicetree/bindings/power_supply/imx-snvs-poweroff.txt @@ -0,0 +1,23 @@ +i.mx6 Poweroff Driver + +SNVS_LPCR in SNVS module can power off the whole system by pull +PMIC_ON_REQ low if PMIC_ON_REQ is connected with external PMIC. +If you don't want to use PMIC_ON_REQ as power on/off control, +please set status='disabled' to disable this driver. + +Required Properties: +-compatible: "fsl,sec-v4.0-poweroff" +-reg: Specifies the physical address of the SNVS_LPCR register + +Example: + snvs@020cc000 { + compatible = "fsl,sec-v4.0-mon", "simple-bus"; + #address-cells = <1>; + #size-cells = <1>; + ranges = <0 0x020cc000 0x4000>; + ..... + snvs_poweroff: snvs-poweroff@38 { + compatible = "fsl,sec-v4.0-poweroff"; + reg = <0x38 0x4>; + }; + } diff --git a/Documentation/devicetree/bindings/powerpc/fsl/fman.txt b/Documentation/devicetree/bindings/powerpc/fsl/fman.txt new file mode 100644 index 000000000000..edda55f74004 --- /dev/null +++ b/Documentation/devicetree/bindings/powerpc/fsl/fman.txt @@ -0,0 +1,604 @@ +============================================================================= +Freescale Frame Manager Device Bindings + +CONTENTS + - FMan Node + - FMan Port Node + - FMan MURAM Node + - FMan dTSEC/XGEC/mEMAC Node + - FMan IEEE 1588 Node + - FMan MDIO Node + - Example + +============================================================================= +FMan Node + +DESCRIPTION + +Due to the fact that the FMan is an aggregation of sub-engines (ports, MACs, +etc.) the FMan node will have child nodes for each of them. + +PROPERTIES + +- compatible + Usage: required + Value type: <stringlist> + Definition: Must include "fsl,fman" + FMan version can be determined via FM_IP_REV_1 register in the + FMan block. The offset is 0xc4 from the beginning of the + Frame Processing Manager memory map (0xc3000 from the + beginning of the FMan node). + +- cell-index + Usage: required + Value type: <u32> + Definition: Specifies the index of the FMan unit. + + The cell-index value may be used by the SoC, to identify the + FMan unit in the SoC memory map. In the table bellow, + there's a description of the cell-index use in each SoC: + + - P1023: + register[bit] FMan unit cell-index + ============================================================ + DEVDISR[1] 1 0 + + - P2041, P3041, P4080 P5020, P5040: + register[bit] FMan unit cell-index + ============================================================ + DCFG_DEVDISR2[6] 1 0 + DCFG_DEVDISR2[14] 2 1 + (Second FM available only in P4080 and P5040) + + - B4860, T1040, T2080, T4240: + register[bit] FMan unit cell-index + ============================================================ + DCFG_CCSR_DEVDISR2[24] 1 0 + DCFG_CCSR_DEVDISR2[25] 2 1 + (Second FM available only in T4240) + + DEVDISR, DCFG_DEVDISR2 and DCFG_CCSR_DEVDISR2 are located in + the specific SoC "Device Configuration/Pin Control" Memory + Map. + +- reg + Usage: required + Value type: <prop-encoded-array> + Definition: A standard property. Specifies the offset of the + following configuration registers: + - BMI configuration registers. + - QMI configuration registers. + - DMA configuration registers. + - FPM configuration registers. + - FMan controller configuration registers. + +- ranges + Usage: required + Value type: <prop-encoded-array> + Definition: A standard property. + +- clocks + Usage: required + Value type: <prop-encoded-array> + Definition: phandle for the fman input clock. + +- clock-names + usage: required + Value type: <stringlist> + Definition: "fmanclk" for the fman input clock. + +- interrupts + Usage: required + Value type: <prop-encoded-array> + Definition: A pair of IRQs are specified in this property. + The first element is associated with the event interrupts and + the second element is associated with the error interrupts. + +- fsl,qman-channel-range + Usage: required + Value type: <prop-encoded-array> + Definition: Specifies the range of the available dedicated + channels in the FMan. The first cell specifies the beginning + of the range and the second cell specifies the number of + channels. + Further information available at: + "Work Queue (WQ) Channel Assignments in the QMan" section + in DPAA Reference Manual. + +- fsl,qman +- fsl,bman + Usage: required + Definition: See soc/fsl/qman.txt and soc/fsl/bman.txt + +============================================================================= +FMan MURAM Node + +DESCRIPTION + +FMan Internal memory - shared between all the FMan modules. +It contains data structures that are common and written to or read by +the modules. +FMan internal memory is split into the following parts: + Packet buffering (Tx/Rx FIFOs) + Frames internal context + +PROPERTIES + +- compatible + Usage: required + Value type: <stringlist> + Definition: Must include "fsl,fman-muram" + +- ranges + Usage: required + Value type: <prop-encoded-array> + Definition: A standard property. + Specifies the multi-user memory offset and the size within + the FMan. + +EXAMPLE + +muram@0 { + compatible = "fsl,fman-muram"; + ranges = <0 0x000000 0x28000>; +}; + +============================================================================= +FMan Port Node + +DESCRIPTION + +The Frame Manager (FMan) supports several types of hardware ports: + Ethernet receiver (RX) + Ethernet transmitter (TX) + Offline/Host command (O/H) + +PROPERTIES + +- compatible + Usage: required + Value type: <stringlist> + Definition: A standard property. + Must include one of the following: + - "fsl,fman-v2-port-oh" for FManV2 OH ports + - "fsl,fman-v2-port-rx" for FManV2 RX ports + - "fsl,fman-v2-port-tx" for FManV2 TX ports + - "fsl,fman-v3-port-oh" for FManV3 OH ports + - "fsl,fman-v3-port-rx" for FManV3 RX ports + - "fsl,fman-v3-port-tx" for FManV3 TX ports + +- cell-index + Usage: required + Value type: <u32> + Definition: Specifies the hardware port id. + Each hardware port on the FMan has its own hardware PortID. + Super set of all hardware Port IDs available at FMan Reference + Manual under "FMan Hardware Ports in Freescale Devices" table. + + Each hardware port is assigned a 4KB, port-specific page in + the FMan hardware port memory region (which is part of the + FMan memory map). The first 4 KB in the FMan hardware ports + memory region is used for what are called common registers. + The subsequent 63 4KB pages are allocated to the hardware + ports. + The page of a specific port is determined by the cell-index. + +- reg + Usage: required + Value type: <prop-encoded-array> + Definition: There is one reg region describing the port + configuration registers. + +EXAMPLE + +port@a8000 { + cell-index = <0x28>; + compatible = "fsl,fman-v2-port-tx"; + reg = <0xa8000 0x1000>; +}; + +port@88000 { + cell-index = <0x8>; + compatible = "fsl,fman-v2-port-rx"; + reg = <0x88000 0x1000>; +}; + +port@81000 { + cell-index = <0x1>; + compatible = "fsl,fman-v2-port-oh"; + reg = <0x81000 0x1000>; +}; + +============================================================================= +FMan dTSEC/XGEC/mEMAC Node + +DESCRIPTION + +mEMAC/dTSEC/XGEC are the Ethernet network interfaces + +PROPERTIES + +- compatible + Usage: required + Value type: <stringlist> + Definition: A standard property. + Must include one of the following: + - "fsl,fman-dtsec" for dTSEC MAC + - "fsl,fman-xgec" for XGEC MAC + - "fsl,fman-memac for mEMAC MAC + +- cell-index + Usage: required + Value type: <u32> + Definition: Specifies the MAC id. + + The cell-index value may be used by the FMan or the SoC, to + identify the MAC unit in the FMan (or SoC) memory map. + In the tables bellow there's a description of the cell-index + use, there are two tables, one describes the use of cell-index + by the FMan, the second describes the use by the SoC: + + 1. FMan Registers + + FManV2: + register[bit] MAC cell-index + ============================================================ + FM_EPI[16] XGEC 8 + FM_EPI[16+n] dTSECn n-1 + FM_NPI[11+n] dTSECn n-1 + n = 1,..,5 + + FManV3: + register[bit] MAC cell-index + ============================================================ + FM_EPI[16+n] mEMACn n-1 + FM_EPI[25] mEMAC10 9 + + FM_NPI[11+n] mEMACn n-1 + FM_NPI[10] mEMAC10 9 + FM_NPI[11] mEMAC9 8 + n = 1,..8 + + FM_EPI and FM_NPI are located in the FMan memory map. + + 2. SoC registers: + + - P2041, P3041, P4080 P5020, P5040: + register[bit] FMan MAC cell + Unit index + ============================================================ + DCFG_DEVDISR2[7] 1 XGEC 8 + DCFG_DEVDISR2[7+n] 1 dTSECn n-1 + DCFG_DEVDISR2[15] 2 XGEC 8 + DCFG_DEVDISR2[15+n] 2 dTSECn n-1 + n = 1,..5 + + - T1040, T2080, T4240, B4860: + register[bit] FMan MAC cell + Unit index + ============================================================ + DCFG_CCSR_DEVDISR2[n-1] 1 mEMACn n-1 + DCFG_CCSR_DEVDISR2[11+n] 2 mEMACn n-1 + n = 1,..6,9,10 + + EVDISR, DCFG_DEVDISR2 and DCFG_CCSR_DEVDISR2 are located in + the specific SoC "Device Configuration/Pin Control" Memory + Map. + +- reg + Usage: required + Value type: <prop-encoded-array> + Definition: A standard property. + +- fsl,fman-ports + Usage: required + Value type: <prop-encoded-array> + Definition: An array of two phandles - the first references is + the FMan RX port and the second is the TX port used by this + MAC. + +- ptp-timer + Usage required + Value type: <phandle> + Definition: A phandle for 1EEE1588 timer. + +EXAMPLE + +fman1_tx28: port@a8000 { + cell-index = <0x28>; + compatible = "fsl,fman-v2-port-tx"; + reg = <0xa8000 0x1000>; +}; + +fman1_rx8: port@88000 { + cell-index = <0x8>; + compatible = "fsl,fman-v2-port-rx"; + reg = <0x88000 0x1000>; +}; + +ptp-timer: ptp_timer@fe000 { + compatible = "fsl,fman-ptp-timer"; + reg = <0xfe000 0x1000>; +}; + +ethernet@e0000 { + compatible = "fsl,fman-dtsec"; + cell-index = <0>; + reg = <0xe0000 0x1000>; + fsl,fman-ports = <&fman1_rx8 &fman1_tx28>; + ptp-timer = <&ptp-timer>; +}; + +============================================================================ +FMan IEEE 1588 Node + +DESCRIPTION + +The FMan interface to support IEEE 1588 + + +PROPERTIES + +- compatible + Usage: required + Value type: <stringlist> + Definition: A standard property. + Must include "fsl,fman-ptp-timer". + +- reg + Usage: required + Value type: <prop-encoded-array> + Definition: A standard property. + +EXAMPLE + +ptp-timer@fe000 { + compatible = "fsl,fman-ptp-timer"; + reg = <0xfe000 0x1000>; +}; + +============================================================================= +FMan MDIO Node + +DESCRIPTION + +The MDIO is a bus to which the PHY devices are connected. + +PROPERTIES + +- compatible + Usage: required + Value type: <stringlist> + Definition: A standard property. + Must include "fsl,fman-mdio" for 1 Gb/s MDIO from FMan v2. + Must include "fsl,fman-xmdio" for 10 Gb/s MDIO from FMan v2. + Must include "fsl,fman-memac-mdio" for 1/10 Gb/s MDIO from + FMan v3. + +- reg + Usage: required + Value type: <prop-encoded-array> + Definition: A standard property. + +- bus-frequency + Usage: optional + Value type: <u32> + Definition: Specifies the external MDIO bus clock speed to + be used, if different from the standard 2.5 MHz. + This may be due to the standard speed being unsupported (e.g. + due to a hardware problem), or to advertise that all relevant + components in the system support a faster speed. + +- interrupts + Usage: required for external MDIO + Value type: <prop-encoded-array> + Definition: Event interrupt of external MDIO controller. + +- fsl,fman-internal-mdio + Usage: required for internal MDIO + Value type: boolean + Definition: Fman has internal MDIO for internal PCS(Physical + Coding Sublayer) PHYs and external MDIO for external PHYs. + The settings and programming routines for internal/external + MDIO are different. Must be included for internal MDIO. + +EXAMPLE + +Example for FMan v2 external MDIO: + +mdio@f1000 { + compatible = "fsl,fman-xmdio"; + reg = <0xf1000 0x1000>; + interrupts = <101 2 0 0>; +}; + +Example for FMan v3 internal MDIO: + +mdio@f1000 { + compatible = "fsl,fman-memac-mdio"; + reg = <0xf1000 0x1000>; + fsl,fman-internal-mdio; +}; + +============================================================================= +Example + +fman@400000 { + #address-cells = <1>; + #size-cells = <1>; + cell-index = <1>; + compatible = "fsl,fman" + ranges = <0 0x400000 0x100000>; + reg = <0x400000 0x100000>; + clocks = <&fman_clk>; + clock-names = "fmanclk"; + interrupts = < + 96 2 0 0 + 16 2 1 1>; + fsl,qman-channel-range = <0x40 0xc>; + + muram@0 { + compatible = "fsl,fman-muram"; + reg = <0x0 0x28000>; + }; + + port@81000 { + cell-index = <1>; + compatible = "fsl,fman-v2-port-oh"; + reg = <0x81000 0x1000>; + }; + + port@82000 { + cell-index = <2>; + compatible = "fsl,fman-v2-port-oh"; + reg = <0x82000 0x1000>; + }; + + port@83000 { + cell-index = <3>; + compatible = "fsl,fman-v2-port-oh"; + reg = <0x83000 0x1000>; + }; + + port@84000 { + cell-index = <4>; + compatible = "fsl,fman-v2-port-oh"; + reg = <0x84000 0x1000>; + }; + + port@85000 { + cell-index = <5>; + compatible = "fsl,fman-v2-port-oh"; + reg = <0x85000 0x1000>; + }; + + port@86000 { + cell-index = <6>; + compatible = "fsl,fman-v2-port-oh"; + reg = <0x86000 0x1000>; + }; + + fman1_rx_0x8: port@88000 { + cell-index = <0x8>; + compatible = "fsl,fman-v2-port-rx"; + reg = <0x88000 0x1000>; + }; + + fman1_rx_0x9: port@89000 { + cell-index = <0x9>; + compatible = "fsl,fman-v2-port-rx"; + reg = <0x89000 0x1000>; + }; + + fman1_rx_0xa: port@8a000 { + cell-index = <0xa>; + compatible = "fsl,fman-v2-port-rx"; + reg = <0x8a000 0x1000>; + }; + + fman1_rx_0xb: port@8b000 { + cell-index = <0xb>; + compatible = "fsl,fman-v2-port-rx"; + reg = <0x8b000 0x1000>; + }; + + fman1_rx_0xc: port@8c000 { + cell-index = <0xc>; + compatible = "fsl,fman-v2-port-rx"; + reg = <0x8c000 0x1000>; + }; + + fman1_rx_0x10: port@90000 { + cell-index = <0x10>; + compatible = "fsl,fman-v2-port-rx"; + reg = <0x90000 0x1000>; + }; + + fman1_tx_0x28: port@a8000 { + cell-index = <0x28>; + compatible = "fsl,fman-v2-port-tx"; + reg = <0xa8000 0x1000>; + }; + + fman1_tx_0x29: port@a9000 { + cell-index = <0x29>; + compatible = "fsl,fman-v2-port-tx"; + reg = <0xa9000 0x1000>; + }; + + fman1_tx_0x2a: port@aa000 { + cell-index = <0x2a>; + compatible = "fsl,fman-v2-port-tx"; + reg = <0xaa000 0x1000>; + }; + + fman1_tx_0x2b: port@ab000 { + cell-index = <0x2b>; + compatible = "fsl,fman-v2-port-tx"; + reg = <0xab000 0x1000>; + }; + + fman1_tx_0x2c: port@ac0000 { + cell-index = <0x2c>; + compatible = "fsl,fman-v2-port-tx"; + reg = <0xac000 0x1000>; + }; + + fman1_tx_0x30: port@b0000 { + cell-index = <0x30>; + compatible = "fsl,fman-v2-port-tx"; + reg = <0xb0000 0x1000>; + }; + + ethernet@e0000 { + compatible = "fsl,fman-dtsec"; + cell-index = <0>; + reg = <0xe0000 0x1000>; + fsl,fman-ports = <&fman1_rx_0x8 &fman1_tx_0x28>; + }; + + ethernet@e2000 { + compatible = "fsl,fman-dtsec"; + cell-index = <1>; + reg = <0xe2000 0x1000>; + fsl,fman-ports = <&fman1_rx_0x9 &fman1_tx_0x29>; + }; + + ethernet@e4000 { + compatible = "fsl,fman-dtsec"; + cell-index = <2>; + reg = <0xe4000 0x1000>; + fsl,fman-ports = <&fman1_rx_0xa &fman1_tx_0x2a>; + }; + + ethernet@e6000 { + compatible = "fsl,fman-dtsec"; + cell-index = <3>; + reg = <0xe6000 0x1000>; + fsl,fman-ports = <&fman1_rx_0xb &fman1_tx_0x2b>; + }; + + ethernet@e8000 { + compatible = "fsl,fman-dtsec"; + cell-index = <4>; + reg = <0xf0000 0x1000>; + fsl,fman-ports = <&fman1_rx_0xc &fman1_tx_0x2c>; + + ethernet@f0000 { + cell-index = <8>; + compatible = "fsl,fman-xgec"; + reg = <0xf0000 0x1000>; + fsl,fman-ports = <&fman1_rx_0x10 &fman1_tx_0x30>; + }; + + ptp-timer@fe000 { + compatible = "fsl,fman-ptp-timer"; + reg = <0xfe000 0x1000>; + }; + + mdio@f1000 { + compatible = "fsl,fman-xmdio"; + reg = <0xf1000 0x1000>; + interrupts = <101 2 0 0>; + }; +}; diff --git a/Documentation/devicetree/bindings/powerpc/fsl/lbc.txt b/Documentation/devicetree/bindings/powerpc/fsl/lbc.txt index 3300fec501c5..1c80fcedebb5 100644 --- a/Documentation/devicetree/bindings/powerpc/fsl/lbc.txt +++ b/Documentation/devicetree/bindings/powerpc/fsl/lbc.txt @@ -16,20 +16,28 @@ Example: "fsl,pq2-localbus"; #address-cells = <2>; #size-cells = <1>; - reg = <f0010100 40>; + reg = <0xf0010100 0x40>; - ranges = <0 0 fe000000 02000000 - 1 0 f4500000 00008000>; + ranges = <0x0 0x0 0xfe000000 0x02000000 + 0x1 0x0 0xf4500000 0x00008000 + 0x2 0x0 0xfd810000 0x00010000>; flash@0,0 { compatible = "jedec-flash"; - reg = <0 0 2000000>; + reg = <0x0 0x0 0x2000000>; bank-width = <4>; device-width = <1>; }; board-control@1,0 { - reg = <1 0 20>; + reg = <0x1 0x0 0x20>; compatible = "fsl,mpc8272ads-bcsr"; }; + + simple-periph@2,0 { + compatible = "fsl,elbc-gpcm-uio"; + reg = <0x2 0x0 0x10000>; + elbc-gpcm-br = <0xfd810800>; + elbc-gpcm-or = <0xffff09f7>; + }; }; diff --git a/Documentation/devicetree/bindings/pwm/atmel-hlcdc-pwm.txt b/Documentation/devicetree/bindings/pwm/atmel-hlcdc-pwm.txt new file mode 100644 index 000000000000..cfda0d57d302 --- /dev/null +++ b/Documentation/devicetree/bindings/pwm/atmel-hlcdc-pwm.txt @@ -0,0 +1,29 @@ +Device-Tree bindings for Atmel's HLCDC (High-end LCD Controller) PWM driver + +The Atmel HLCDC PWM is subdevice of the HLCDC MFD device. +See ../mfd/atmel-hlcdc.txt for more details. + +Required properties: + - compatible: value should be one of the following: + "atmel,hlcdc-pwm" + - pinctr-names: the pin control state names. Should contain "default". + - pinctrl-0: should contain the pinctrl states described by pinctrl + default. + - #pwm-cells: should be set to 3. This PWM chip use the default 3 cells + bindings defined in pwm.txt in this directory. + +Example: + + hlcdc: hlcdc@f0030000 { + compatible = "atmel,sama5d3-hlcdc"; + reg = <0xf0030000 0x2000>; + clocks = <&lcdc_clk>, <&lcdck>, <&clk32k>; + clock-names = "periph_clk","sys_clk", "slow_clk"; + + hlcdc_pwm: hlcdc-pwm { + compatible = "atmel,hlcdc-pwm"; + pinctrl-names = "default"; + pinctrl-0 = <&pinctrl_lcd_pwm>; + #pwm-cells = <3>; + }; + }; diff --git a/Documentation/devicetree/bindings/pwm/nvidia,tegra20-pwm.txt b/Documentation/devicetree/bindings/pwm/nvidia,tegra20-pwm.txt index c7ea9d4a988b..c52f03b5032f 100644 --- a/Documentation/devicetree/bindings/pwm/nvidia,tegra20-pwm.txt +++ b/Documentation/devicetree/bindings/pwm/nvidia,tegra20-pwm.txt @@ -1,9 +1,10 @@ Tegra SoC PWFM controller Required properties: -- compatible: should be one of: - - "nvidia,tegra20-pwm" - - "nvidia,tegra30-pwm" +- compatible: For Tegra20, must contain "nvidia,tegra20-pwm". For Tegra30, + must contain "nvidia,tegra30-pwm". Otherwise, must contain + "nvidia,<chip>-pwm", plus one of the above, where <chip> is tegra114, + tegra124, tegra132, or tegra210. - reg: physical base address and length of the controller's registers - #pwm-cells: should be 2. See pwm.txt in this directory for a description of the cells format. diff --git a/Documentation/devicetree/bindings/pwm/pwm-bcm2835.txt b/Documentation/devicetree/bindings/pwm/pwm-bcm2835.txt new file mode 100644 index 000000000000..fb6fb31bc4c4 --- /dev/null +++ b/Documentation/devicetree/bindings/pwm/pwm-bcm2835.txt @@ -0,0 +1,30 @@ +BCM2835 PWM controller (Raspberry Pi controller) + +Required properties: +- compatible: should be "brcm,bcm2835-pwm" +- reg: physical base address and length of the controller's registers +- clock: This clock defines the base clock frequency of the PWM hardware + system, the period and the duty_cycle of the PWM signal is a multiple of + the base period. +- #pwm-cells: Should be 2. See pwm.txt in this directory for a description of + the cells format. + +Examples: + +pwm@2020c000 { + compatible = "brcm,bcm2835-pwm"; + reg = <0x2020c000 0x28>; + clocks = <&clk_pwm>; + #pwm-cells = <2>; +}; + +clocks { + .... + clk_pwm: pwm { + compatible = "fixed-clock"; + reg = <3>; + #clock-cells = <0>; + clock-frequency = <9200000>; + }; + .... +}; diff --git a/Documentation/devicetree/bindings/regulator/act8865-regulator.txt b/Documentation/devicetree/bindings/regulator/act8865-regulator.txt index 865614b34d6f..dad6358074ac 100644 --- a/Documentation/devicetree/bindings/regulator/act8865-regulator.txt +++ b/Documentation/devicetree/bindings/regulator/act8865-regulator.txt @@ -5,6 +5,10 @@ Required properties: - compatible: "active-semi,act8846" or "active-semi,act8865" - reg: I2C slave address +Optional properties: +- system-power-controller: Telling whether or not this pmic is controlling + the system power. See Documentation/devicetree/bindings/power/power-controller.txt . + Any standard regulator properties can be used to configure the single regulator. The valid names for regulators are: diff --git a/Documentation/devicetree/bindings/regulator/da9211.txt b/Documentation/devicetree/bindings/regulator/da9211.txt index 240019a82f9a..eb618907c7de 100644 --- a/Documentation/devicetree/bindings/regulator/da9211.txt +++ b/Documentation/devicetree/bindings/regulator/da9211.txt @@ -11,6 +11,7 @@ Required properties: BUCKA and BUCKB. Optional properties: +- enable-gpios: platform gpio for control of BUCKA/BUCKB. - Any optional property defined in regulator.txt Example 1) DA9211 @@ -27,6 +28,7 @@ Example 1) DA9211 regulator-max-microvolt = <1570000>; regulator-min-microamp = <2000000>; regulator-max-microamp = <5000000>; + enable-gpios = <&gpio 27 0>; }; BUCKB { regulator-name = "VBUCKB"; @@ -34,11 +36,12 @@ Example 1) DA9211 regulator-max-microvolt = <1570000>; regulator-min-microamp = <2000000>; regulator-max-microamp = <5000000>; + enable-gpios = <&gpio 17 0>; }; }; }; -Example 2) DA92113 +Example 2) DA9213 pmic: da9213@68 { compatible = "dlg,da9213"; reg = <0x68>; @@ -51,6 +54,7 @@ Example 2) DA92113 regulator-max-microvolt = <1570000>; regulator-min-microamp = <3000000>; regulator-max-microamp = <6000000>; + enable-gpios = <&gpio 27 0>; }; BUCKB { regulator-name = "VBUCKB"; @@ -58,6 +62,7 @@ Example 2) DA92113 regulator-max-microvolt = <1570000>; regulator-min-microamp = <3000000>; regulator-max-microamp = <6000000>; + enable-gpios = <&gpio 17 0>; }; }; }; diff --git a/Documentation/devicetree/bindings/regulator/isl9305.txt b/Documentation/devicetree/bindings/regulator/isl9305.txt index a626fc1bbf0d..d6e7c9ec9413 100644 --- a/Documentation/devicetree/bindings/regulator/isl9305.txt +++ b/Documentation/devicetree/bindings/regulator/isl9305.txt @@ -2,7 +2,7 @@ Intersil ISL9305/ISL9305H voltage regulator Required properties: -- compatible: "isl,isl9305" or "isl,isl9305h" +- compatible: "isil,isl9305" or "isil,isl9305h" - reg: I2C slave address, usually 0x68. - regulators: A node that houses a sub-node for each regulator within the device. Each sub-node is identified using the node's name, with valid @@ -19,7 +19,7 @@ Optional properties: Example pmic: isl9305@68 { - compatible = "isl,isl9305"; + compatible = "isil,isl9305"; reg = <0x68>; VINDCD1-supply = <&system_power>; diff --git a/Documentation/devicetree/bindings/regulator/max77802.txt b/Documentation/devicetree/bindings/regulator/max77802.txt index 5aeaffc0f1f0..79e5476444f7 100644 --- a/Documentation/devicetree/bindings/regulator/max77802.txt +++ b/Documentation/devicetree/bindings/regulator/max77802.txt @@ -25,6 +25,29 @@ with their hardware counterparts as follow. The valid names are: example: LDO1, LDO2, LDO35. -BUCKn : for BUCKs, where n can lie in range 1 to 10. example: BUCK1, BUCK5, BUCK10. + +The max77802 regulator supports two different operating modes: Normal and Low +Power Mode. Some regulators support the modes to be changed at startup or by +the consumers during normal operation while others only support to change the +mode during system suspend. The standard regulator suspend states binding can +be used to configure the regulator operating mode. + +The regulators that support the standard "regulator-initial-mode" property, +changing their mode during normal operation are: LDOs 1, 3, 20 and 21. + +The possible values for "regulator-initial-mode" and "regulator-mode" are: + 1: Normal regulator voltage output mode. + 3: Low Power which reduces the quiescent current down to only 1uA + +The list of valid modes are defined in the dt-bindings/clock/maxim,max77802.h +header and can be included by device tree source files. + +The standard "regulator-mode" property can only be used for regulators that +support changing their mode to Low Power Mode during suspend. These regulators +are: BUCKs 2-4 and LDOs 1-35. Also, it only takes effect if the regulator has +been enabled for the given suspend state using "regulator-on-in-suspend" and +has not been disabled for that state using "regulator-off-in-suspend". + Example: max77802@09 { @@ -36,11 +59,23 @@ Example: #size-cells = <0>; regulators { + ldo1_reg: LDO1 { + regulator-name = "vdd_1v0"; + regulator-min-microvolt = <1000000>; + regulator-max-microvolt = <1000000>; + regulator-always-on; + regulator-initial-mode = <MAX77802_OPMODE_LP>; + }; + ldo11_reg: LDO11 { regulator-name = "vdd_ldo11"; regulator-min-microvolt = <1900000>; regulator-max-microvolt = <1900000>; regulator-always-on; + regulator-state-mem { + regulator-on-in-suspend; + regulator-mode = <MAX77802_OPMODE_LP>; + }; }; buck1_reg: BUCK1 { diff --git a/Documentation/devicetree/bindings/regulator/mt6397-regulator.txt b/Documentation/devicetree/bindings/regulator/mt6397-regulator.txt new file mode 100644 index 000000000000..a42b1d6e9863 --- /dev/null +++ b/Documentation/devicetree/bindings/regulator/mt6397-regulator.txt @@ -0,0 +1,217 @@ +Mediatek MT6397 Regulator Driver + +Required properties: +- compatible: "mediatek,mt6397-regulator" +- mt6397regulator: List of regulators provided by this controller. It is named + according to its regulator type, buck_<name> and ldo_<name>. + The definition for each of these nodes is defined using the standard binding + for regulators at Documentation/devicetree/bindings/regulator/regulator.txt. + +The valid names for regulators are:: +BUCK: + buck_vpca15, buck_vpca7, buck_vsramca15, buck_vsramca7, buck_vcore, buck_vgpu, + buck_vdrm, buck_vio18 +LDO: + ldo_vtcxo, ldo_va28, ldo_vcama, ldo_vio28, ldo_vusb, ldo_vmc, ldo_vmch, + ldo_vemc3v3, ldo_vgp1, ldo_vgp2, ldo_vgp3, ldo_vgp4, ldo_vgp5, ldo_vgp6, + ldo_vibr + +Example: + pmic { + compatible = "mediatek,mt6397"; + + mt6397regulator: mt6397regulator { + compatible = "mediatek,mt6397-regulator"; + + mt6397_vpca15_reg: buck_vpca15 { + regulator-compatible = "buck_vpca15"; + regulator-name = "vpca15"; + regulator-min-microvolt = < 850000>; + regulator-max-microvolt = <1350000>; + regulator-ramp-delay = <12500>; + regulator-enable-ramp-delay = <200>; + }; + + mt6397_vpca7_reg: buck_vpca7 { + regulator-compatible = "buck_vpca7"; + regulator-name = "vpca7"; + regulator-min-microvolt = < 850000>; + regulator-max-microvolt = <1350000>; + regulator-ramp-delay = <12500>; + regulator-enable-ramp-delay = <115>; + }; + + mt6397_vsramca15_reg: buck_vsramca15 { + regulator-compatible = "buck_vsramca15"; + regulator-name = "vsramca15"; + regulator-min-microvolt = < 850000>; + regulator-max-microvolt = <1350000>; + regulator-ramp-delay = <12500>; + regulator-enable-ramp-delay = <115>; + + }; + + mt6397_vsramca7_reg: buck_vsramca7 { + regulator-compatible = "buck_vsramca7"; + regulator-name = "vsramca7"; + regulator-min-microvolt = < 850000>; + regulator-max-microvolt = <1350000>; + regulator-ramp-delay = <12500>; + regulator-enable-ramp-delay = <115>; + + }; + + mt6397_vcore_reg: buck_vcore { + regulator-compatible = "buck_vcore"; + regulator-name = "vcore"; + regulator-min-microvolt = < 850000>; + regulator-max-microvolt = <1350000>; + regulator-ramp-delay = <12500>; + regulator-enable-ramp-delay = <115>; + }; + + mt6397_vgpu_reg: buck_vgpu { + regulator-compatible = "buck_vgpu"; + regulator-name = "vgpu"; + regulator-min-microvolt = < 700000>; + regulator-max-microvolt = <1350000>; + regulator-ramp-delay = <12500>; + regulator-enable-ramp-delay = <115>; + }; + + mt6397_vdrm_reg: buck_vdrm { + regulator-compatible = "buck_vdrm"; + regulator-name = "vdrm"; + regulator-min-microvolt = < 800000>; + regulator-max-microvolt = <1400000>; + regulator-ramp-delay = <12500>; + regulator-enable-ramp-delay = <500>; + }; + + mt6397_vio18_reg: buck_vio18 { + regulator-compatible = "buck_vio18"; + regulator-name = "vio18"; + regulator-min-microvolt = <1500000>; + regulator-max-microvolt = <2120000>; + regulator-ramp-delay = <12500>; + regulator-enable-ramp-delay = <500>; + }; + + mt6397_vtcxo_reg: ldo_vtcxo { + regulator-compatible = "ldo_vtcxo"; + regulator-name = "vtcxo"; + regulator-min-microvolt = <2800000>; + regulator-max-microvolt = <2800000>; + regulator-enable-ramp-delay = <90>; + }; + + mt6397_va28_reg: ldo_va28 { + regulator-compatible = "ldo_va28"; + regulator-name = "va28"; + /* fixed output 2.8 V */ + regulator-enable-ramp-delay = <218>; + }; + + mt6397_vcama_reg: ldo_vcama { + regulator-compatible = "ldo_vcama"; + regulator-name = "vcama"; + regulator-min-microvolt = <1500000>; + regulator-max-microvolt = <2800000>; + regulator-enable-ramp-delay = <218>; + }; + + mt6397_vio28_reg: ldo_vio28 { + regulator-compatible = "ldo_vio28"; + regulator-name = "vio28"; + /* fixed output 2.8 V */ + regulator-enable-ramp-delay = <240>; + }; + + mt6397_usb_reg: ldo_vusb { + regulator-compatible = "ldo_vusb"; + regulator-name = "vusb"; + /* fixed output 3.3 V */ + regulator-enable-ramp-delay = <218>; + }; + + mt6397_vmc_reg: ldo_vmc { + regulator-compatible = "ldo_vmc"; + regulator-name = "vmc"; + regulator-min-microvolt = <1800000>; + regulator-max-microvolt = <3300000>; + regulator-enable-ramp-delay = <218>; + }; + + mt6397_vmch_reg: ldo_vmch { + regulator-compatible = "ldo_vmch"; + regulator-name = "vmch"; + regulator-min-microvolt = <3000000>; + regulator-max-microvolt = <3300000>; + regulator-enable-ramp-delay = <218>; + }; + + mt6397_vemc_3v3_reg: ldo_vemc3v3 { + regulator-compatible = "ldo_vemc3v3"; + regulator-name = "vemc_3v3"; + regulator-min-microvolt = <3000000>; + regulator-max-microvolt = <3300000>; + regulator-enable-ramp-delay = <218>; + }; + + mt6397_vgp1_reg: ldo_vgp1 { + regulator-compatible = "ldo_vgp1"; + regulator-name = "vcamd"; + regulator-min-microvolt = <1220000>; + regulator-max-microvolt = <3300000>; + regulator-enable-ramp-delay = <240>; + }; + + mt6397_vgp2_reg: ldo_vgp2 { + egulator-compatible = "ldo_vgp2"; + regulator-name = "vcamio"; + regulator-min-microvolt = <1000000>; + regulator-max-microvolt = <3300000>; + regulator-enable-ramp-delay = <218>; + }; + + mt6397_vgp3_reg: ldo_vgp3 { + regulator-compatible = "ldo_vgp3"; + regulator-name = "vcamaf"; + regulator-min-microvolt = <1200000>; + regulator-max-microvolt = <3300000>; + regulator-enable-ramp-delay = <218>; + }; + + mt6397_vgp4_reg: ldo_vgp4 { + regulator-compatible = "ldo_vgp4"; + regulator-name = "vgp4"; + regulator-min-microvolt = <1200000>; + regulator-max-microvolt = <3300000>; + regulator-enable-ramp-delay = <218>; + }; + + mt6397_vgp5_reg: ldo_vgp5 { + regulator-compatible = "ldo_vgp5"; + regulator-name = "vgp5"; + regulator-min-microvolt = <1200000>; + regulator-max-microvolt = <3000000>; + regulator-enable-ramp-delay = <218>; + }; + + mt6397_vgp6_reg: ldo_vgp6 { + regulator-compatible = "ldo_vgp6"; + regulator-name = "vgp6"; + regulator-min-microvolt = <1200000>; + regulator-max-microvolt = <3300000>; + regulator-enable-ramp-delay = <218>; + }; + + mt6397_vibr_reg: ldo_vibr { + regulator-compatible = "ldo_vibr"; + regulator-name = "vibr"; + regulator-min-microvolt = <1200000>; + regulator-max-microvolt = <3300000>; + regulator-enable-ramp-delay = <218>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/regulator/pfuze100.txt b/Documentation/devicetree/bindings/regulator/pfuze100.txt index 34ef5d16d0f1..9b40db88f637 100644 --- a/Documentation/devicetree/bindings/regulator/pfuze100.txt +++ b/Documentation/devicetree/bindings/regulator/pfuze100.txt @@ -1,7 +1,7 @@ PFUZE100 family of regulators Required properties: -- compatible: "fsl,pfuze100" or "fsl,pfuze200" +- compatible: "fsl,pfuze100", "fsl,pfuze200", "fsl,pfuze3000" - reg: I2C slave address Required child node: @@ -14,6 +14,8 @@ Required child node: sw1ab,sw1c,sw2,sw3a,sw3b,sw4,swbst,vsnvs,vrefddr,vgen1~vgen6 --PFUZE200 sw1ab,sw2,sw3a,sw3b,swbst,vsnvs,vrefddr,vgen1~vgen6 + --PFUZE3000 + sw1a,sw1b,sw2,sw3,swbst,vsnvs,vrefddr,vldo1,vldo2,vccsd,v33,vldo3,vldo4 Each regulator is defined using the standard binding for regulators. @@ -205,3 +207,93 @@ Example 2: PFUZE200 }; }; }; + +Example 3: PFUZE3000 + + pmic: pfuze3000@08 { + compatible = "fsl,pfuze3000"; + reg = <0x08>; + + regulators { + sw1a_reg: sw1a { + regulator-min-microvolt = <700000>; + regulator-max-microvolt = <1475000>; + regulator-boot-on; + regulator-always-on; + regulator-ramp-delay = <6250>; + }; + /* use sw1c_reg to align with pfuze100/pfuze200 */ + sw1c_reg: sw1b { + regulator-min-microvolt = <700000>; + regulator-max-microvolt = <1475000>; + regulator-boot-on; + regulator-always-on; + regulator-ramp-delay = <6250>; + }; + + sw2_reg: sw2 { + regulator-min-microvolt = <2500000>; + regulator-max-microvolt = <3300000>; + regulator-boot-on; + regulator-always-on; + }; + + sw3a_reg: sw3 { + regulator-min-microvolt = <900000>; + regulator-max-microvolt = <1650000>; + regulator-boot-on; + regulator-always-on; + }; + + swbst_reg: swbst { + regulator-min-microvolt = <5000000>; + regulator-max-microvolt = <5150000>; + }; + + snvs_reg: vsnvs { + regulator-min-microvolt = <1000000>; + regulator-max-microvolt = <3000000>; + regulator-boot-on; + regulator-always-on; + }; + + vref_reg: vrefddr { + regulator-boot-on; + regulator-always-on; + }; + + vgen1_reg: vldo1 { + regulator-min-microvolt = <1800000>; + regulator-max-microvolt = <3300000>; + regulator-always-on; + }; + + vgen2_reg: vldo2 { + regulator-min-microvolt = <800000>; + regulator-max-microvolt = <1550000>; + }; + + vgen3_reg: vccsd { + regulator-min-microvolt = <2850000>; + regulator-max-microvolt = <3300000>; + regulator-always-on; + }; + + vgen4_reg: v33 { + regulator-min-microvolt = <2850000>; + regulator-max-microvolt = <3300000>; + }; + + vgen5_reg: vldo3 { + regulator-min-microvolt = <1800000>; + regulator-max-microvolt = <3300000>; + regulator-always-on; + }; + + vgen6_reg: vldo4 { + regulator-min-microvolt = <1800000>; + regulator-max-microvolt = <3300000>; + regulator-always-on; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/regulator/regulator.txt b/Documentation/devicetree/bindings/regulator/regulator.txt index 86074334e342..abb26b58c83e 100644 --- a/Documentation/devicetree/bindings/regulator/regulator.txt +++ b/Documentation/devicetree/bindings/regulator/regulator.txt @@ -19,6 +19,24 @@ Optional properties: design requires. This property describes the total system ramp time required due to the combination of internal ramping of the regulator itself, and board design issues such as trace capacitance and load on the supply. +- regulator-state-mem sub-root node for Suspend-to-RAM mode + : suspend to memory, the device goes to sleep, but all data stored in memory, + only some external interrupt can wake the device. +- regulator-state-disk sub-root node for Suspend-to-DISK mode + : suspend to disk, this state operates similarly to Suspend-to-RAM, + but includes a final step of writing memory contents to disk. +- regulator-state-[mem/disk] node has following common properties: + - regulator-on-in-suspend: regulator should be on in suspend state. + - regulator-off-in-suspend: regulator should be off in suspend state. + - regulator-suspend-microvolt: regulator should be set to this voltage + in suspend. + - regulator-mode: operating mode in the given suspend state. + The set of possible operating modes depends on the capabilities of + every hardware so the valid modes are documented on each regulator + device tree binding document. +- regulator-initial-mode: initial operating mode. The set of possible operating + modes depends on the capabilities of every hardware so each device binding + documentation explains which values the regulator supports. Deprecated properties: - regulator-compatible: If a regulator chip contains multiple @@ -34,6 +52,10 @@ Example: regulator-max-microvolt = <2500000>; regulator-always-on; vin-supply = <&vin>; + + regulator-state-mem { + regulator-on-in-suspend; + }; }; Regulator Consumers: diff --git a/Documentation/devicetree/bindings/regulator/sky81452-regulator.txt b/Documentation/devicetree/bindings/regulator/sky81452-regulator.txt index 882455e9b36d..f9acbc1f3c6b 100644 --- a/Documentation/devicetree/bindings/regulator/sky81452-regulator.txt +++ b/Documentation/devicetree/bindings/regulator/sky81452-regulator.txt @@ -1,6 +1,7 @@ SKY81452 voltage regulator Required properties: +- regulator node named lout. - any required generic properties defined in regulator.txt Optional properties: @@ -9,8 +10,9 @@ Optional properties: Example: regulator { - /* generic regulator properties */ - regulator-name = "touch_en"; - regulator-min-microvolt = <4500000>; - regulator-max-microvolt = <8000000>; + lout { + regulator-name = "sky81452-lout"; + regulator-min-microvolt = <4500000>; + regulator-max-microvolt = <8000000>; + }; }; diff --git a/Documentation/devicetree/bindings/reset/st,sti-picophyreset.txt b/Documentation/devicetree/bindings/reset/st,sti-picophyreset.txt new file mode 100644 index 000000000000..54ae9f747e45 --- /dev/null +++ b/Documentation/devicetree/bindings/reset/st,sti-picophyreset.txt @@ -0,0 +1,42 @@ +STMicroelectronics STi family Sysconfig Picophy SoftReset Controller +============================================================================= + +This binding describes a reset controller device that is used to enable and +disable on-chip PicoPHY USB2 phy(s) using "softreset" control bits found in +the STi family SoC system configuration registers. + +The actual action taken when softreset is asserted is hardware dependent. +However, when asserted it may not be possible to access the hardware's +registers and after an assert/deassert sequence the hardware's previous state +may no longer be valid. + +Please refer to Documentation/devicetree/bindings/reset/reset.txt +for common reset controller binding usage. + +Required properties: +- compatible: Should be "st,stih407-picophyreset" +- #reset-cells: 1, see below + +Example: + + picophyreset: picophyreset-controller { + compatible = "st,stih407-picophyreset"; + #reset-cells = <1>; + }; + +Specifying picophyreset control of devices +======================================= + +Device nodes should specify the reset channel required in their "resets" +property, containing a phandle to the picophyreset device node and an +index specifying which channel to use, as described in +Documentation/devicetree/bindings/reset/reset.txt. + +Example: + + usb2_picophy0: usbpicophy@0 { + resets = <&picophyreset STIH407_PICOPHY0_RESET>; + }; + +Macro definitions for the supported reset channels can be found in: +include/dt-bindings/reset-controller/stih407-resets.h diff --git a/Documentation/devicetree/bindings/rtc/armada-380-rtc.txt b/Documentation/devicetree/bindings/rtc/armada-380-rtc.txt new file mode 100644 index 000000000000..2eb9d4ee7dc0 --- /dev/null +++ b/Documentation/devicetree/bindings/rtc/armada-380-rtc.txt @@ -0,0 +1,22 @@ +* Real Time Clock of the Armada 38x SoCs + +RTC controller for the Armada 38x SoCs + +Required properties: +- compatible : Should be "marvell,armada-380-rtc" +- reg: a list of base address and size pairs, one for each entry in + reg-names +- reg names: should contain: + * "rtc" for the RTC registers + * "rtc-soc" for the SoC related registers and among them the one + related to the interrupt. +- interrupts: IRQ line for the RTC. + +Example: + +rtc@a3800 { + compatible = "marvell,armada-380-rtc"; + reg = <0xa3800 0x20>, <0x184a0 0x0c>; + reg-names = "rtc", "rtc-soc"; + interrupts = <GIC_SPI 21 IRQ_TYPE_LEVEL_HIGH>; +}; diff --git a/Documentation/devicetree/bindings/rtc/atmel,at91sam9-rtc.txt b/Documentation/devicetree/bindings/rtc/atmel,at91sam9-rtc.txt new file mode 100644 index 000000000000..6ae79d1843f3 --- /dev/null +++ b/Documentation/devicetree/bindings/rtc/atmel,at91sam9-rtc.txt @@ -0,0 +1,23 @@ +Atmel AT91SAM9260 Real Time Timer + +Required properties: +- compatible: should be: "atmel,at91sam9260-rtt" +- reg: should encode the memory region of the RTT controller +- interrupts: rtt alarm/event interrupt +- clocks: should contain the 32 KHz slow clk that will drive the RTT block. +- atmel,rtt-rtc-time-reg: should encode the GPBR register used to store + the time base when the RTT is used as an RTC. + The first cell should point to the GPBR node and the second one + encode the offset within the GPBR block (or in other words, the + GPBR register used to store the time base). + + +Example: + +rtt@fffffd20 { + compatible = "atmel,at91sam9260-rtt"; + reg = <0xfffffd20 0x10>; + interrupts = <1 4 7>; + clocks = <&clk32k>; + atmel,rtt-rtc-time-reg = <&gpbr 0x0>; +}; diff --git a/Documentation/devicetree/bindings/rtc/isil,isl12057.txt b/Documentation/devicetree/bindings/rtc/isil,isl12057.txt new file mode 100644 index 000000000000..501c39ceae79 --- /dev/null +++ b/Documentation/devicetree/bindings/rtc/isil,isl12057.txt @@ -0,0 +1,78 @@ +Intersil ISL12057 I2C RTC/Alarm chip + +ISL12057 is a trivial I2C device (it has simple device tree bindings, +consisting of a compatible field, an address and possibly an interrupt +line). + +Nonetheless, it also supports an option boolean property +("isil,irq2-can-wakeup-machine") to handle the specific use-case found +on at least three in-tree users of the chip (NETGEAR ReadyNAS 102, 104 +and 2120 ARM-based NAS); On those devices, the IRQ#2 pin of the chip +(associated with the alarm supported by the driver) is not connected +to the SoC but to a PMIC. It allows the device to be powered up when +RTC alarm rings. In order to mark the device has a wakeup source and +get access to the 'wakealarm' sysfs entry, this specific property can +be set when the IRQ#2 pin of the chip is not connected to the SoC but +can wake up the device. + +Required properties supported by the device: + + - "compatible": must be "isil,isl12057" + - "reg": I2C bus address of the device + +Optional properties: + + - "isil,irq2-can-wakeup-machine": mark the chip as a wakeup source, + independently of the availability of an IRQ line connected to the + SoC. + + - "interrupt-parent", "interrupts": for passing the interrupt line + of the SoC connected to IRQ#2 of the RTC chip. + + +Example isl12057 node without IRQ#2 pin connected (no alarm support): + + isl12057: isl12057@68 { + compatible = "isil,isl12057"; + reg = <0x68>; + }; + + +Example isl12057 node with IRQ#2 pin connected to main SoC via MPP6 (note +that the pinctrl-related properties below are given for completeness and +may not be required or may be different depending on your system or +SoC, and the main function of the MPP used as IRQ line, i.e. +"interrupt-parent" and "interrupts" are usually sufficient): + + pinctrl { + ... + + rtc_alarm_pin: rtc_alarm_pin { + marvell,pins = "mpp6"; + marvell,function = "gpio"; + }; + + ... + + }; + + ... + + isl12057: isl12057@68 { + compatible = "isil,isl12057"; + reg = <0x68>; + pinctrl-0 = <&rtc_alarm_pin>; + pinctrl-names = "default"; + interrupt-parent = <&gpio0>; + interrupts = <6 IRQ_TYPE_EDGE_FALLING>; + }; + + +Example isl12057 node without IRQ#2 pin connected to the SoC but to a +PMIC, allowing the device to be started based on configured alarm: + + isl12057: isl12057@68 { + compatible = "isil,isl12057"; + reg = <0x68>; + isil,irq2-can-wakeup-machine; + }; diff --git a/Documentation/devicetree/bindings/rtc/nvidia,tegra20-rtc.txt b/Documentation/devicetree/bindings/rtc/nvidia,tegra20-rtc.txt index 652d1ff2e8be..b7d98ed3e098 100644 --- a/Documentation/devicetree/bindings/rtc/nvidia,tegra20-rtc.txt +++ b/Documentation/devicetree/bindings/rtc/nvidia,tegra20-rtc.txt @@ -6,7 +6,9 @@ state. Required properties: -- compatible : should be "nvidia,tegra20-rtc". +- compatible : For Tegra20, must contain "nvidia,tegra20-rtc". Otherwise, + must contain '"nvidia,<chip>-rtc", "nvidia,tegra20-rtc"', where <chip> + can be tegra30, tegra114, tegra124, or tegra132. - reg : Specifies base physical address and size of the registers. - interrupts : A single interrupt specifier. - clocks : Must contain one entry, for the module clock. diff --git a/Documentation/devicetree/bindings/rtc/nxp,rtc-2123.txt b/Documentation/devicetree/bindings/rtc/nxp,rtc-2123.txt new file mode 100644 index 000000000000..5cbc0b145a61 --- /dev/null +++ b/Documentation/devicetree/bindings/rtc/nxp,rtc-2123.txt @@ -0,0 +1,16 @@ +NXP PCF2123 SPI Real Time Clock + +Required properties: +- compatible: should be: "nxp,rtc-pcf2123" +- reg: should be the SPI slave chipselect address + +Optional properties: +- spi-cs-high: PCF2123 needs chipselect high + +Example: + +rtc: nxp,rtc-pcf2123@3 { + compatible = "nxp,rtc-pcf2123" + reg = <3> + spi-cs-high; +}; diff --git a/Documentation/devicetree/bindings/rtc/rtc-omap.txt b/Documentation/devicetree/bindings/rtc/rtc-omap.txt index 5a0f02d34d95..4ba4dbd34289 100644 --- a/Documentation/devicetree/bindings/rtc/rtc-omap.txt +++ b/Documentation/devicetree/bindings/rtc/rtc-omap.txt @@ -5,11 +5,17 @@ Required properties: - "ti,da830-rtc" - for RTC IP used similar to that on DA8xx SoC family. - "ti,am3352-rtc" - for RTC IP used similar to that on AM335x SoC family. This RTC IP has special WAKE-EN Register to enable - Wakeup generation for event Alarm. + Wakeup generation for event Alarm. It can also be + used to control an external PMIC via the + pmic_power_en pin. - reg: Address range of rtc register set - interrupts: rtc timer, alarm interrupts in order - interrupt-parent: phandle for the interrupt controller +Optional properties: +- system-power-controller: whether the rtc is controlling the system power + through pmic_power_en + Example: rtc@1c23000 { @@ -18,4 +24,5 @@ rtc@1c23000 { interrupts = <19 19>; interrupt-parent = <&intc>; + system-power-controller; }; diff --git a/Documentation/devicetree/bindings/rtc/rtc-opal.txt b/Documentation/devicetree/bindings/rtc/rtc-opal.txt new file mode 100644 index 000000000000..af87e5ecac54 --- /dev/null +++ b/Documentation/devicetree/bindings/rtc/rtc-opal.txt @@ -0,0 +1,16 @@ +IBM OPAL real-time clock +------------------------ + +Required properties: +- comapatible: Should be "ibm,opal-rtc" + +Optional properties: +- has-tpo: Decides if the wakeup is supported or not. + +Example: + rtc { + compatible = "ibm,opal-rtc"; + has-tpo; + phandle = <0x10000029>; + linux,phandle = <0x10000029>; + }; diff --git a/Documentation/devicetree/bindings/security/tpm/st33zp24-i2c.txt b/Documentation/devicetree/bindings/security/tpm/st33zp24-i2c.txt new file mode 100644 index 000000000000..3ad115efed1e --- /dev/null +++ b/Documentation/devicetree/bindings/security/tpm/st33zp24-i2c.txt @@ -0,0 +1,36 @@ +* STMicroelectronics SAS. ST33ZP24 TPM SoC + +Required properties: +- compatible: Should be "st,st33zp24-i2c". +- clock-frequency: I²C work frequency. +- reg: address on the bus + +Optional ST33ZP24 Properties: +- interrupt-parent: phandle for the interrupt gpio controller +- interrupts: GPIO interrupt to which the chip is connected +- lpcpd-gpios: Output GPIO pin used for ST33ZP24 power management D1/D2 state. +If set, power must be present when the platform is going into sleep/hibernate mode. + +Optional SoC Specific Properties: +- pinctrl-names: Contains only one value - "default". +- pintctrl-0: Specifies the pin control groups used for this controller. + +Example (for ARM-based BeagleBoard xM with ST33ZP24 on I2C2): + +&i2c2 { + + status = "okay"; + + st33zp24: st33zp24@13 { + + compatible = "st,st33zp24-i2c"; + + reg = <0x13>; + clock-frequency = <400000>; + + interrupt-parent = <&gpio5>; + interrupts = <7 IRQ_TYPE_LEVEL_HIGH>; + + lpcpd-gpios = <&gpio5 15 GPIO_ACTIVE_HIGH>; + }; +}; diff --git a/Documentation/devicetree/bindings/serial/bcm63xx-uart.txt b/Documentation/devicetree/bindings/serial/bcm63xx-uart.txt new file mode 100644 index 000000000000..5c52e5eef16d --- /dev/null +++ b/Documentation/devicetree/bindings/serial/bcm63xx-uart.txt @@ -0,0 +1,30 @@ +* BCM63xx UART + +Required properties: + +- compatible: "brcm,bcm6345-uart" + +- reg: The base address of the UART register bank. + +- interrupts: A single interrupt specifier. + +- clocks: Clock driving the hardware; used to figure out the baud rate + divisor. + +Example: + + uart0: serial@14e00520 { + compatible = "brcm,bcm6345-uart"; + reg = <0x14e00520 0x18>; + interrupt-parent = <&periph_intc>; + interrupts = <2>; + clocks = <&periph_clk>; + }; + + clocks { + periph_clk: periph_clk@0 { + compatible = "fixed-clock"; + #clock-cells = <0>; + clock-frequency = <54000000>; + }; + }; diff --git a/Documentation/devicetree/bindings/serial/digicolor-usart.txt b/Documentation/devicetree/bindings/serial/digicolor-usart.txt new file mode 100644 index 000000000000..2d3ede66889d --- /dev/null +++ b/Documentation/devicetree/bindings/serial/digicolor-usart.txt @@ -0,0 +1,27 @@ +Binding for Conexant Digicolor USART + +Note: this binding is only applicable for using the USART peripheral as +UART. USART also support synchronous serial protocols like SPI and I2S. Use +the binding that matches the wiring of your system. + +Required properties: +- compatible : should be "cnxt,cx92755-usart". +- reg: Should contain USART controller registers location and length. +- interrupts: Should contain a single USART controller interrupt. +- clocks: Must contain phandles to the USART clock + See ../clocks/clock-bindings.txt for details. + +Note: Each UART port should have an alias correctly numbered +in "aliases" node. + +Example: + aliases { + serial0 = &uart0; + }; + + uart0: uart@f0000740 { + compatible = "cnxt,cx92755-usart"; + reg = <0xf0000740 0x20>; + clocks = <&main_clk>; + interrupts = <44>; + }; diff --git a/Documentation/devicetree/bindings/serial/fsl-mxs-auart.txt b/Documentation/devicetree/bindings/serial/fsl-mxs-auart.txt index 59a40f18d551..7c408c87e613 100644 --- a/Documentation/devicetree/bindings/serial/fsl-mxs-auart.txt +++ b/Documentation/devicetree/bindings/serial/fsl-mxs-auart.txt @@ -11,8 +11,13 @@ Required properties: - dma-names: "rx" for RX channel, "tx" for TX channel. Optional properties: -- fsl,uart-has-rtscts : Indicate the UART has RTS and CTS lines, +- fsl,uart-has-rtscts : Indicate the UART has RTS and CTS lines + for hardware flow control, it also means you enable the DMA support for this UART. +- {rts,cts,dtr,dsr,rng,dcd}-gpios: specify a GPIO for RTS/CTS/DTR/DSR/RI/DCD + line respectively. It will use specified PIO instead of the peripheral + function pin for the USART feature. + If unsure, don't specify this property. Example: auart0: serial@8006a000 { @@ -21,6 +26,9 @@ auart0: serial@8006a000 { interrupts = <112>; dmas = <&dma_apbx 8>, <&dma_apbx 9>; dma-names = "rx", "tx"; + cts-gpios = <&gpio1 15 GPIO_ACTIVE_LOW>; + dsr-gpios = <&gpio1 16 GPIO_ACTIVE_LOW>; + dcd-gpios = <&gpio1 17 GPIO_ACTIVE_LOW>; }; Note: Each auart port should have an alias correctly numbered in "aliases" diff --git a/Documentation/devicetree/bindings/serial/mtk-uart.txt b/Documentation/devicetree/bindings/serial/mtk-uart.txt index 48358a33ea7d..44152261e5c5 100644 --- a/Documentation/devicetree/bindings/serial/mtk-uart.txt +++ b/Documentation/devicetree/bindings/serial/mtk-uart.txt @@ -2,9 +2,13 @@ Required properties: - compatible should contain: + * "mediatek,mt8135-uart" for MT8135 compatible UARTS + * "mediatek,mt8127-uart" for MT8127 compatible UARTS + * "mediatek,mt8173-uart" for MT8173 compatible UARTS * "mediatek,mt6589-uart" for MT6589 compatible UARTS * "mediatek,mt6582-uart" for MT6582 compatible UARTS - * "mediatek,mt6577-uart" for all compatible UARTS (MT6589, MT6582, MT6577) + * "mediatek,mt6577-uart" for all compatible UARTS (MT8173, MT6589, MT6582, + MT6577) - reg: The base address of the UART register bank. diff --git a/Documentation/devicetree/bindings/serial/of-serial.txt b/Documentation/devicetree/bindings/serial/of-serial.txt index 8c4fd0332028..91d5ab0e60fc 100644 --- a/Documentation/devicetree/bindings/serial/of-serial.txt +++ b/Documentation/devicetree/bindings/serial/of-serial.txt @@ -8,13 +8,18 @@ Required properties: - "ns16550" - "ns16750" - "ns16850" - - "nvidia,tegra20-uart" + - For Tegra20, must contain "nvidia,tegra20-uart" + - For other Tegra, must contain '"nvidia,<chip>-uart", + "nvidia,tegra20-uart"' where <chip> is tegra30, tegra114, tegra124, + tegra132, or tegra210. - "nxp,lpc3220-uart" + - "ralink,rt2880-uart" - "ibm,qpace-nwp-serial" - "altr,16550-FIFO32" - "altr,16550-FIFO64" - "altr,16550-FIFO128" - "fsl,16550-FIFO64" + - "fsl,ns16550" - "serial" if the port type is unknown. - reg : offset and length of the register set for the device. - interrupts : should contain uart interrupt. @@ -39,6 +44,17 @@ Optional properties: driver is allowed to detect support for the capability even without this property. +Note: +* fsl,ns16550: + ------------ + Freescale DUART is very similar to the PC16552D (and to a + pair of NS16550A), albeit with some nonstandard behavior such as + erratum A-004737 (relating to incorrect BRK handling). + + Represents a single port that is compatible with the DUART found + on many Freescale chips (examples include mpc8349, mpc8548, + mpc8641d, p4080 and ls2085a). + Example: uart@80230000 { diff --git a/Documentation/devicetree/bindings/serial/pl011.txt b/Documentation/devicetree/bindings/serial/pl011.txt index 5d2e840ae65c..ba3ecb8cb5a1 100644 --- a/Documentation/devicetree/bindings/serial/pl011.txt +++ b/Documentation/devicetree/bindings/serial/pl011.txt @@ -6,12 +6,46 @@ Required properties: - interrupts: exactly one interrupt specifier Optional properties: -- pinctrl: When present, must have one state named "sleep" - and one state named "default" -- clocks: When present, must refer to exactly one clock named +- pinctrl: + When present, must have one state named "default", + and may contain a second name named "sleep". The former + state sets up pins for ordinary operation whereas + the latter state will put the associated pins to sleep + when the UART is unused +- clocks: + When present, the first clock listed must correspond to + the clock named UARTCLK on the IP block, i.e. the clock + to the external serial line, whereas the second clock + must correspond to the PCLK clocking the internal logic + of the block. Just listing one clock (the first one) is + deprecated. +- clocks-names: + When present, the first clock listed must be named + "uartclk" and the second clock listed must be named "apb_pclk" -- dmas: When present, may have one or two dma channels. +- dmas: + When present, may have one or two dma channels. The first one must be named "rx", the second one must be named "tx". +- auto-poll: + Enables polling when using RX DMA. +- poll-rate-ms: + Rate at which poll occurs when auto-poll is set, + default 100ms. +- poll-timeout-ms: + Poll timeout when auto-poll is set, default + 3000ms. See also bindings/arm/primecell.txt + +Example: + +uart@80120000 { + compatible = "arm,pl011", "arm,primecell"; + reg = <0x80120000 0x1000>; + interrupts = <0 11 IRQ_TYPE_LEVEL_HIGH>; + dmas = <&dma 13 0 0x2>, <&dma 13 0 0x0>; + dma-names = "rx", "tx"; + clocks = <&foo_clk>, <&bar_clk>; + clock-names = "uartclk", "apb_pclk"; +}; diff --git a/Documentation/devicetree/bindings/serial/qcom,msm-uartdm.txt b/Documentation/devicetree/bindings/serial/qcom,msm-uartdm.txt index ffa5b784c66e..a2114c217376 100644 --- a/Documentation/devicetree/bindings/serial/qcom,msm-uartdm.txt +++ b/Documentation/devicetree/bindings/serial/qcom,msm-uartdm.txt @@ -27,27 +27,52 @@ Optional properties: - dmas: Should contain dma specifiers for transmit and receive channels - dma-names: Should contain "tx" for transmit and "rx" for receive channels +Note: Aliases may be defined to ensure the correct ordering of the UARTs. +The alias serialN will result in the UART being assigned port N. If any +serialN alias exists, then an alias must exist for each enabled UART. The +serialN aliases should be in a .dts file instead of in a .dtsi file. + Examples: -A uartdm v1.4 device with dma capabilities. - -serial@f991e000 { - compatible = "qcom,msm-uartdm-v1.4", "qcom,msm-uartdm"; - reg = <0xf991e000 0x1000>; - interrupts = <0 108 0x0>; - clocks = <&blsp1_uart2_apps_cxc>, <&blsp1_ahb_cxc>; - clock-names = "core", "iface"; - dmas = <&dma0 0>, <&dma0 1>; - dma-names = "tx", "rx"; -}; - -A uartdm v1.3 device without dma capabilities and part of a GSBI complex. - -serial@19c40000 { - compatible = "qcom,msm-uartdm-v1.3", "qcom,msm-uartdm"; - reg = <0x19c40000 0x1000>, - <0x19c00000 0x1000>; - interrupts = <0 195 0x0>; - clocks = <&gsbi5_uart_cxc>, <&gsbi5_ahb_cxc>; - clock-names = "core", "iface"; -}; +- A uartdm v1.4 device with dma capabilities. + + serial@f991e000 { + compatible = "qcom,msm-uartdm-v1.4", "qcom,msm-uartdm"; + reg = <0xf991e000 0x1000>; + interrupts = <0 108 0x0>; + clocks = <&blsp1_uart2_apps_cxc>, <&blsp1_ahb_cxc>; + clock-names = "core", "iface"; + dmas = <&dma0 0>, <&dma0 1>; + dma-names = "tx", "rx"; + }; + +- A uartdm v1.3 device without dma capabilities and part of a GSBI complex. + + serial@19c40000 { + compatible = "qcom,msm-uartdm-v1.3", "qcom,msm-uartdm"; + reg = <0x19c40000 0x1000>, + <0x19c00000 0x1000>; + interrupts = <0 195 0x0>; + clocks = <&gsbi5_uart_cxc>, <&gsbi5_ahb_cxc>; + clock-names = "core", "iface"; + }; + +- serialN alias. + + aliases { + serial0 = &uarta; + serial1 = &uartc; + serial2 = &uartb; + }; + + uarta: serial@12490000 { + status = "ok"; + }; + + uartb: serial@16340000 { + status = "ok"; + }; + + uartc: serial@1a240000 { + status = "ok"; + }; diff --git a/Documentation/devicetree/bindings/serial/renesas,sci-serial.txt b/Documentation/devicetree/bindings/serial/renesas,sci-serial.txt index b3556609a06f..ae73bb0e9ad9 100644 --- a/Documentation/devicetree/bindings/serial/renesas,sci-serial.txt +++ b/Documentation/devicetree/bindings/serial/renesas,sci-serial.txt @@ -4,8 +4,7 @@ Required properties: - compatible: Must contain one of the following: - - "renesas,scifa-sh73a0" for SH73A0 (SH-Mobile AG5) SCIFA compatible UART. - - "renesas,scifb-sh73a0" for SH73A0 (SH-Mobile AG5) SCIFB compatible UART. + - "renesas,scif-r7s72100" for R7S72100 (RZ/A1H) SCIF compatible UART. - "renesas,scifa-r8a73a4" for R8A73A4 (R-Mobile APE6) SCIFA compatible UART. - "renesas,scifb-r8a73a4" for R8A73A4 (R-Mobile APE6) SCIFB compatible UART. - "renesas,scifa-r8a7740" for R8A7740 (R-Mobile A1) SCIFA compatible UART. @@ -20,6 +19,12 @@ Required properties: - "renesas,scifa-r8a7791" for R8A7791 (R-Car M2) SCIFA compatible UART. - "renesas,scifb-r8a7791" for R8A7791 (R-Car M2) SCIFB compatible UART. - "renesas,hscif-r8a7791" for R8A7791 (R-Car M2) HSCIF compatible UART. + - "renesas,scif-r8a7794" for R8A7794 (R-Car E2) SCIF compatible UART. + - "renesas,scifa-r8a7794" for R8A7794 (R-Car E2) SCIFA compatible UART. + - "renesas,scifb-r8a7794" for R8A7794 (R-Car E2) SCIFB compatible UART. + - "renesas,hscif-r8a7794" for R8A7794 (R-Car E2) HSCIF compatible UART. + - "renesas,scifa-sh73a0" for SH73A0 (SH-Mobile AG5) SCIFA compatible UART. + - "renesas,scifb-sh73a0" for SH73A0 (SH-Mobile AG5) SCIFB compatible UART. - "renesas,scif" for generic SCIF compatible UART. - "renesas,scifa" for generic SCIFA compatible UART. - "renesas,scifb" for generic SCIFB compatible UART. diff --git a/Documentation/devicetree/bindings/serial/sirf-uart.txt b/Documentation/devicetree/bindings/serial/sirf-uart.txt index a2dfc6522a91..f0c39261c5d4 100644 --- a/Documentation/devicetree/bindings/serial/sirf-uart.txt +++ b/Documentation/devicetree/bindings/serial/sirf-uart.txt @@ -1,7 +1,9 @@ * CSR SiRFprimaII/atlasVI Universal Synchronous Asynchronous Receiver/Transmitter * Required properties: -- compatible : Should be "sirf,prima2-uart" or "sirf, prima2-usp-uart" +- compatible : Should be "sirf,prima2-uart", "sirf, prima2-usp-uart", + "sirf,atlas7-uart" or "sirf,atlas7-bt-uart" which means + uart located in BT module and used for BT. - reg : Offset and length of the register set for the device - interrupts : Should contain uart interrupt - fifosize : Should define hardware rx/tx fifo size @@ -31,3 +33,15 @@ usp@b0090000 { rts-gpios = <&gpio 15 0>; cts-gpios = <&gpio 46 0>; }; + +for uart use in BT module, +uart6: uart@11000000 { + cell-index = <6>; + compatible = "sirf,atlas7-bt-uart", "sirf,atlas7-uart"; + reg = <0x11000000 0x1000>; + interrupts = <0 100 0>; + clocks = <&clks 138>, <&clks 140>, <&clks 141>; + clock-names = "uart", "general", "noc"; + fifosize = <128>; + status = "disabled"; +} diff --git a/Documentation/devicetree/bindings/serial/sprd-uart.txt b/Documentation/devicetree/bindings/serial/sprd-uart.txt new file mode 100644 index 000000000000..2aff0f22c9fa --- /dev/null +++ b/Documentation/devicetree/bindings/serial/sprd-uart.txt @@ -0,0 +1,7 @@ +* Spreadtrum serial UART + +Required properties: +- compatible: must be "sprd,sc9836-uart" +- reg: offset and length of the register set for the device +- interrupts: exactly one interrupt specifier +- clocks: phandles to input clocks. diff --git a/Documentation/devicetree/bindings/serio/allwinner,sun4i-ps2.txt b/Documentation/devicetree/bindings/serio/allwinner,sun4i-ps2.txt new file mode 100644 index 000000000000..362a76925bcd --- /dev/null +++ b/Documentation/devicetree/bindings/serio/allwinner,sun4i-ps2.txt @@ -0,0 +1,23 @@ +* Device tree bindings for Allwinner A10, A20 PS2 host controller + +A20 PS2 is dual role controller (PS2 host and PS2 device). These bindings are +for PS2 A10/A20 host controller. IBM compliant IBM PS2 and AT-compatible keyboard +and mouse can be connected. + +Required properties: + + - reg : Offset and length of the register set for the device. + - compatible : Should be as of the following: + - "allwinner,sun4i-a10-ps2" + - interrupts : The interrupt line connected to the PS2. + - clocks : The gate clk connected to the PS2. + + +Example: + ps20: ps2@0x01c2a000 { + compatible = "allwinner,sun4i-a10-ps2"; + reg = <0x01c2a000 0x400>; + interrupts = <0 62 4>; + clocks = <&apb1_gates 6>; + status = "disabled"; + }; diff --git a/Documentation/devicetree/bindings/soc/fsl/bman-portals.txt b/Documentation/devicetree/bindings/soc/fsl/bman-portals.txt new file mode 100644 index 000000000000..2a00e14e11e0 --- /dev/null +++ b/Documentation/devicetree/bindings/soc/fsl/bman-portals.txt @@ -0,0 +1,56 @@ +QorIQ DPAA Buffer Manager Portals Device Tree Binding + +Copyright (C) 2008 - 2014 Freescale Semiconductor Inc. + +CONTENTS + + - BMan Portal + - Example + +BMan Portal Node + +Portals are memory mapped interfaces to BMan that allow low-latency, lock-less +interaction by software running on processor cores, accelerators and network +interfaces with the BMan + +PROPERTIES + +- compatible + Usage: Required + Value type: <stringlist> + Definition: Must include "fsl,bman-portal-<hardware revision>" + May include "fsl,<SoC>-bman-portal" or "fsl,bman-portal" + +- reg + Usage: Required + Value type: <prop-encoded-array> + Definition: Two regions. The first is the cache-enabled region of + the portal. The second is the cache-inhibited region of + the portal + +- interrupts + Usage: Required + Value type: <prop-encoded-array> + Definition: Standard property + +EXAMPLE + +The example below shows a (P4080) BMan portals container/bus node with two portals + + bman-portals@ff4000000 { + #address-cells = <1>; + #size-cells = <1>; + compatible = "simple-bus"; + ranges = <0 0xf 0xf4000000 0x200000>; + + bman-portal@0 { + compatible = "fsl,bman-portal-1.0.0", "fsl,bman-portal"; + reg = <0x0 0x4000>, <0x100000 0x1000>; + interrupts = <105 2 0 0>; + }; + bman-portal@4000 { + compatible = "fsl,bman-portal-1.0.0", "fsl,bman-portal"; + reg = <0x4000 0x4000>, <0x101000 0x1000>; + interrupts = <107 2 0 0>; + }; + }; diff --git a/Documentation/devicetree/bindings/soc/fsl/bman.txt b/Documentation/devicetree/bindings/soc/fsl/bman.txt new file mode 100644 index 000000000000..47ac834414d8 --- /dev/null +++ b/Documentation/devicetree/bindings/soc/fsl/bman.txt @@ -0,0 +1,135 @@ +QorIQ DPAA Buffer Manager Device Tree Bindings + +Copyright (C) 2008 - 2014 Freescale Semiconductor Inc. + +CONTENTS + + - BMan Node + - BMan Private Memory Node + - Example + +BMan Node + +The Buffer Manager is part of the Data-Path Acceleration Architecture (DPAA). +BMan supports hardware allocation and deallocation of buffers belonging to pools +originally created by software with configurable depletion thresholds. This +binding covers the CCSR space programming model + +PROPERTIES + +- compatible + Usage: Required + Value type: <stringlist> + Definition: Must include "fsl,bman" + May include "fsl,<SoC>-bman" + +- reg + Usage: Required + Value type: <prop-encoded-array> + Definition: Registers region within the CCSR address space + +The BMan revision information is located in the BMAN_IP_REV_1/2 registers which +are located at offsets 0xbf8 and 0xbfc + +- interrupts + Usage: Required + Value type: <prop-encoded-array> + Definition: Standard property. The error interrupt + +- fsl,bman-portals + Usage: Required + Value type: <phandle> + Definition: Phandle to this BMan instance's portals + +- fsl,liodn + Usage: See pamu.txt + Value type: <prop-encoded-array> + Definition: PAMU property used for static LIODN assignment + +- fsl,iommu-parent + Usage: See pamu.txt + Value type: <phandle> + Definition: PAMU property used for dynamic LIODN assignment + + For additional details about the PAMU/LIODN binding(s) see pamu.txt + +Devices connected to a BMan instance via Direct Connect Portals (DCP) must link +to the respective BMan instance + +- fsl,bman + Usage: Required + Value type: <prop-encoded-array> + Description: List of phandle and DCP index pairs, to the BMan instance + to which this device is connected via the DCP + +BMan Private Memory Node + +BMan requires a contiguous range of physical memory used for the backing store +for BMan Free Buffer Proxy Records (FBPR). This memory is reserved/allocated as a +node under the /reserved-memory node + +The BMan FBPR memory node must be named "bman-fbpr" + +PROPERTIES + +- compatible + Usage: required + Value type: <stringlist> + Definition: Must inclide "fsl,bman-fbpr" + +The following constraints are relevant to the FBPR private memory: + - The size must be 2^(size + 1), with size = 11..33. That is 4 KiB to + 16 GiB + - The alignment must be a muliptle of the memory size + +The size of the FBPR must be chosen by observing the hardware features configured +via the Reset Configuration Word (RCW) and that are relevant to a specific board +(e.g. number of MAC(s) pinned-out, number of offline/host command FMan ports, +etc.). The size configured in the DT must reflect the hardware capabilities and +not the specific needs of an application + +For additional details about reserved memory regions see reserved-memory.txt + +EXAMPLE + +The example below shows a BMan FBPR dynamic allocation memory node + + reserved-memory { + #address-cells = <2>; + #size-cells = <2>; + ranges; + + bman_fbpr: bman-fbpr { + compatible = "fsl,bman-fbpr"; + alloc-ranges = <0 0 0x10 0>; + size = <0 0x1000000>; + alignment = <0 0x1000000>; + }; + }; + +The example below shows a (P4080) BMan CCSR-space node + + bportals: bman-portals@ff4000000 { + ... + }; + + crypto@300000 { + ... + fsl,bman = <&bman, 2>; + ... + }; + + bman: bman@31a000 { + compatible = "fsl,bman"; + reg = <0x31a000 0x1000>; + interrupts = <16 2 1 2>; + fsl,liodn = <0x17>; + fsl,bman-portals = <&bportals>; + memory-region = <&bman_fbpr>; + }; + + fman@400000 { + ... + fsl,bman = <&bman, 0>; + ... + }; diff --git a/Documentation/devicetree/bindings/soc/fsl/qman-portals.txt b/Documentation/devicetree/bindings/soc/fsl/qman-portals.txt new file mode 100644 index 000000000000..48c4dae5d6f9 --- /dev/null +++ b/Documentation/devicetree/bindings/soc/fsl/qman-portals.txt @@ -0,0 +1,154 @@ +QorIQ DPAA Queue Manager Portals Device Tree Binding + +Copyright (C) 2008 - 2014 Freescale Semiconductor Inc. + +CONTENTS + + - QMan Portal + - QMan Pool Channel + - Example + +QMan Portal Node + +Portals are memory mapped interfaces to QMan that allow low-latency, lock-less +interaction by software running on processor cores, accelerators and network +interfaces with the QMan + +PROPERTIES + +- compatible + Usage: Required + Value type: <stringlist> + Definition: Must include "fsl,qman-portal-<hardware revision>" + May include "fsl,<SoC>-qman-portal" or "fsl,qman-portal" + +- reg + Usage: Required + Value type: <prop-encoded-array> + Definition: Two regions. The first is the cache-enabled region of + the portal. The second is the cache-inhibited region of + the portal + +- interrupts + Usage: Required + Value type: <prop-encoded-array> + Definition: Standard property + +- fsl,liodn + Usage: See pamu.txt + Value type: <prop-encoded-array> + Definition: Two LIODN(s). DQRR LIODN (DLIODN) and Frame LIODN + (FLIODN) + +- fsl,iommu-parent + Usage: See pamu.txt + Value type: <phandle> + Definition: PAMU property used for dynamic LIODN assignment + + For additional details about the PAMU/LIODN binding(s) see pamu.txt + +- fsl,qman-channel-id + Usage: Required + Value type: <u32> + Definition: The hardware index of the channel. This can also be + determined by dividing any of the channel's 8 work queue + IDs by 8 + +In addition to these properties the qman-portals should have sub-nodes to +represent the HW devices/portals that are connected to the software portal +described here + +The currently supported sub-nodes are: + * fman0 + * fman1 + * pme + * crypto + +These subnodes should have the following properties: + +- fsl,liodn + Usage: See pamu.txt + Value type: <prop-encoded-array> + Definition: PAMU property used for static LIODN assignment + +- fsl,iommu-parent + Usage: See pamu.txt + Value type: <phandle> + Definition: PAMU property used for dynamic LIODN assignment + +- dev-handle + Usage: Required + Value type: <phandle> + Definition: The phandle to the particular hardware device that this + portal is connected to. + +DPAA QMan Pool Channel Nodes + +Pool Channels are defined with the following properties. + +PROPERTIES + +- compatible + Usage: Required + Value type: <stringlist> + Definition: Must include "fsl,qman-pool-channel" + May include "fsl,<SoC>-qman-pool-channel" + +- fsl,qman-channel-id + Usage: Required + Value type: <u32> + Definition: The hardware index of the channel. This can also be + determined by dividing any of the channel's 8 work queue + IDs by 8 + +EXAMPLE + +The example below shows a (P4080) QMan portals container/bus node with two portals + + qman-portals@ff4200000 { + #address-cells = <1>; + #size-cells = <1>; + compatible = "simple-bus"; + ranges = <0 0xf 0xf4200000 0x200000>; + + qman-portal@0 { + compatible = "fsl,qman-portal-1.2.0", "fsl,qman-portal"; + reg = <0 0x4000>, <0x100000 0x1000>; + interrupts = <104 2 0 0>; + fsl,liodn = <1 2>; + fsl,qman-channel-id = <0>; + + fman0 { + fsl,liodn = <0x21>; + dev-handle = <&fman0>; + }; + fman1 { + fsl,liodn = <0xa1>; + dev-handle = <&fman1>; + }; + crypto { + fsl,liodn = <0x41 0x66>; + dev-handle = <&crypto>; + }; + }; + qman-portal@4000 { + compatible = "fsl,qman-portal-1.2.0", "fsl,qman-portal"; + reg = <0x4000 0x4000>, <0x101000 0x1000>; + interrupts = <106 2 0 0>; + fsl,liodn = <3 4>; + fsl,qman-channel-id = <1>; + + fman0 { + fsl,liodn = <0x22>; + dev-handle = <&fman0>; + }; + fman1 { + fsl,liodn = <0xa2>; + dev-handle = <&fman1>; + }; + crypto { + fsl,liodn = <0x42 0x67>; + dev-handle = <&crypto>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/soc/fsl/qman.txt b/Documentation/devicetree/bindings/soc/fsl/qman.txt new file mode 100644 index 000000000000..556ebb8be75d --- /dev/null +++ b/Documentation/devicetree/bindings/soc/fsl/qman.txt @@ -0,0 +1,175 @@ +QorIQ DPAA Queue Manager Device Tree Binding + +Copyright (C) 2008 - 2014 Freescale Semiconductor Inc. + +CONTENTS + + - QMan Node + - QMan Private Memory Nodes + - Example + +QMan Node + +The Queue Manager is part of the Data-Path Acceleration Architecture (DPAA). QMan +supports queuing and QoS scheduling of frames to CPUs, network interfaces and +DPAA logic modules, maintains packet ordering within flows. Besides providing +flow-level queuing, is also responsible for congestion management functions such +as RED/WRED, congestion notifications and tail discards. This binding covers the +CCSR space programming model + +PROPERTIES + +- compatible + Usage: Required + Value type: <stringlist> + Definition: Must include "fsl,qman" + May include "fsl,<SoC>-qman" + +- reg + Usage: Required + Value type: <prop-encoded-array> + Definition: Registers region within the CCSR address space + +The QMan revision information is located in the QMAN_IP_REV_1/2 registers which +are located at offsets 0xbf8 and 0xbfc + +- interrupts + Usage: Required + Value type: <prop-encoded-array> + Definition: Standard property. The error interrupt + +- fsl,qman-portals + Usage: Required + Value type: <phandle> + Definition: Phandle to this QMan instance's portals + +- fsl,liodn + Usage: See pamu.txt + Value type: <prop-encoded-array> + Definition: PAMU property used for static LIODN assignment + +- fsl,iommu-parent + Usage: See pamu.txt + Value type: <phandle> + Definition: PAMU property used for dynamic LIODN assignment + + For additional details about the PAMU/LIODN binding(s) see pamu.txt + +- clocks + Usage: See clock-bindings.txt and qoriq-clock.txt + Value type: <prop-encoded-array> + Definition: Reference input clock. Its frequency is half of the + platform clock + +Devices connected to a QMan instance via Direct Connect Portals (DCP) must link +to the respective QMan instance + +- fsl,qman + Usage: Required + Value type: <prop-encoded-array> + Description: List of phandle and DCP index pairs, to the QMan instance + to which this device is connected via the DCP + +QMan Private Memory Nodes + +QMan requires two contiguous range of physical memory used for the backing store +for QMan Frame Queue Descriptor (FQD) and Packed Frame Descriptor Record (PFDR). +This memory is reserved/allocated as a nodes under the /reserved-memory node + +The QMan FQD memory node must be named "qman-fqd" + +PROPERTIES + +- compatible + Usage: required + Value type: <stringlist> + Definition: Must inclide "fsl,qman-fqd" + +The QMan PFDR memory node must be named "qman-pfdr" + +PROPERTIES + +- compatible + Usage: required + Value type: <stringlist> + Definition: Must inclide "fsl,qman-pfdr" + +The following constraints are relevant to the FQD and PFDR private memory: + - The size must be 2^(size + 1), with size = 11..29. That is 4 KiB to + 1 GiB + - The alignment must be a muliptle of the memory size + +The size of the FQD and PFDP must be chosen by observing the hardware features +configured via the Reset Configuration Word (RCW) and that are relevant to a +specific board (e.g. number of MAC(s) pinned-out, number of offline/host command +FMan ports, etc.). The size configured in the DT must reflect the hardware +capabilities and not the specific needs of an application + +For additional details about reserved memory regions see reserved-memory.txt + +EXAMPLE + +The example below shows a QMan FQD and a PFDR dynamic allocation memory nodes + + reserved-memory { + #address-cells = <2>; + #size-cells = <2>; + ranges; + + qman_fqd: qman-fqd { + compatible = "fsl,qman-fqd"; + alloc-ranges = <0 0 0x10 0>; + size = <0 0x400000>; + alignment = <0 0x400000>; + }; + qman_pfdr: qman-pfdr { + compatible = "fsl,qman-pfdr"; + alloc-ranges = <0 0 0x10 0>; + size = <0 0x2000000>; + alignment = <0 0x2000000>; + }; + }; + +The example below shows a (P4080) QMan CCSR-space node + + qportals: qman-portals@ff4200000 { + ... + }; + + clockgen: global-utilities@e1000 { + ... + sysclk: sysclk { + ... + }; + ... + platform_pll: platform-pll@c00 { + #clock-cells = <1>; + reg = <0xc00 0x4>; + compatible = "fsl,qoriq-platform-pll-1.0"; + clocks = <&sysclk>; + clock-output-names = "platform-pll", "platform-pll-div2"; + }; + ... + }; + + crypto@300000 { + ... + fsl,qman = <&qman, 2>; + ... + }; + + qman: qman@318000 { + compatible = "fsl,qman"; + reg = <0x318000 0x1000>; + interrupts = <16 2 1 3> + fsl,liodn = <0x16>; + fsl,qman-portals = <&qportals>; + memory-region = <&qman_fqd &qman_pfdr>; + clocks = <&platform_pll 1>; + }; + + fman@400000 { + ... + fsl,qman = <&qman, 0>; + ... + }; diff --git a/Documentation/devicetree/bindings/sound/arndale.txt b/Documentation/devicetree/bindings/sound/arndale.txt new file mode 100644 index 000000000000..0e76946385ae --- /dev/null +++ b/Documentation/devicetree/bindings/sound/arndale.txt @@ -0,0 +1,24 @@ +Audio Binding for Arndale boards + +Required properties: +- compatible : Can be the following, + "samsung,arndale-rt5631" + +- samsung,audio-cpu: The phandle of the Samsung I2S controller +- samsung,audio-codec: The phandle of the audio codec + +Optional: +- samsung,model: The name of the sound-card + +Arndale Boards has many audio daughter cards, one of them is +rt5631/alc5631. Below example shows audio bindings for rt5631/ +alc5631 based codec. + +Example: + +sound { + compatible = "samsung,arndale-rt5631"; + + samsung,audio-cpu = <&i2s0> + samsung,audio-codec = <&rt5631>; +}; diff --git a/Documentation/devicetree/bindings/sound/atmel_ac97c.txt b/Documentation/devicetree/bindings/sound/atmel_ac97c.txt new file mode 100644 index 000000000000..b151bd902ce3 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/atmel_ac97c.txt @@ -0,0 +1,20 @@ +* Atmel AC97 controller + +Required properties: + - compatible: "atmel,at91sam9263-ac97c" + - reg: Address and length of the register set for the device + - interrupts: Should contain AC97 interrupt + - ac97-gpios: Please refer to soc-ac97link.txt, only ac97-reset is used +Optional properties: + - pinctrl-names, pinctrl-0: Please refer to pinctrl-bindings.txt + +Example: +sound@fffa0000 { + compatible = "atmel,at91sam9263-ac97c"; + pinctrl-names = "default"; + pinctrl-0 = <&pinctrl_ac97>; + reg = <0xfffa0000 0x4000>; + interrupts = <18 IRQ_TYPE_LEVEL_HIGH 5>; + + ac97-gpios = <&pioB 0 0 &pioB 2 0 &pioC 29 GPIO_ACTIVE_LOW>; +}; diff --git a/Documentation/devicetree/bindings/sound/cdns,xtfpga-i2s.txt b/Documentation/devicetree/bindings/sound/cdns,xtfpga-i2s.txt new file mode 100644 index 000000000000..befd125d18bb --- /dev/null +++ b/Documentation/devicetree/bindings/sound/cdns,xtfpga-i2s.txt @@ -0,0 +1,18 @@ +Bindings for I2S controller built into xtfpga Xtensa bitstreams. + +Required properties: +- compatible: shall be "cdns,xtfpga-i2s". +- reg: memory region (address and length) with device registers. +- interrupts: interrupt for the device. +- clocks: phandle to the clk used as master clock. I2S bus clock + is derived from it. + +Examples: + + i2s0: xtfpga-i2s@0d080000 { + #sound-dai-cells = <0>; + compatible = "cdns,xtfpga-i2s"; + reg = <0x0d080000 0x40>; + interrupts = <2 1>; + clocks = <&cdce706 4>; + }; diff --git a/Documentation/devicetree/bindings/sound/davinci-mcasp-audio.txt b/Documentation/devicetree/bindings/sound/davinci-mcasp-audio.txt index 60ca07996458..46bc9829c71a 100644 --- a/Documentation/devicetree/bindings/sound/davinci-mcasp-audio.txt +++ b/Documentation/devicetree/bindings/sound/davinci-mcasp-audio.txt @@ -32,7 +32,7 @@ Optional properties: - rx-num-evt : FIFO levels. - sram-size-playback : size of sram to be allocated during playback - sram-size-capture : size of sram to be allocated during capture -- interrupts : Interrupt numbers for McASP, currently not used by the driver +- interrupts : Interrupt numbers for McASP - interrupt-names : Known interrupt names are "tx" and "rx" - pinctrl-0: Should specify pin control group used for this controller. - pinctrl-names: Should contain only one value - "default", for more details diff --git a/Documentation/devicetree/bindings/sound/designware-i2s.txt b/Documentation/devicetree/bindings/sound/designware-i2s.txt new file mode 100644 index 000000000000..7bb54247f8e8 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/designware-i2s.txt @@ -0,0 +1,31 @@ +DesignWare I2S controller + +Required properties: + - compatible : Must be "snps,designware-i2s" + - reg : Must contain the I2S core's registers location and length + - clocks : Pairs of phandle and specifier referencing the controller's + clocks. The controller expects one clock: the clock used as the sampling + rate reference clock sample. + - clock-names : "i2sclk" for the sample rate reference clock. + - dmas: Pairs of phandle and specifier for the DMA channels that are used by + the core. The core expects one or two dma channels: one for transmit and + one for receive. + - dma-names : "tx" for the transmit channel, "rx" for the receive channel. + +For more details on the 'dma', 'dma-names', 'clock' and 'clock-names' +properties please check: + * resource-names.txt + * clock/clock-bindings.txt + * dma/dma.txt + +Example: + + soc_i2s: i2s@7ff90000 { + compatible = "snps,designware-i2s"; + reg = <0x0 0x7ff90000 0x0 0x1000>; + clocks = <&scpi_i2sclk 0>; + clock-names = "i2sclk"; + #sound-dai-cells = <0>; + dmas = <&dma0 5>; + dma-names = "tx"; + }; diff --git a/Documentation/devicetree/bindings/sound/eukrea-tlv320.txt b/Documentation/devicetree/bindings/sound/eukrea-tlv320.txt index 0d7985c864af..6dfa88c4dc1e 100644 --- a/Documentation/devicetree/bindings/sound/eukrea-tlv320.txt +++ b/Documentation/devicetree/bindings/sound/eukrea-tlv320.txt @@ -1,11 +1,16 @@ Audio complex for Eukrea boards with tlv320aic23 codec. Required properties: -- compatible : "eukrea,asoc-tlv320" -- eukrea,model : The user-visible name of this sound complex. -- ssi-controller : The phandle of the SSI controller. -- fsl,mux-int-port : The internal port of the i.MX audio muxer (AUDMUX). -- fsl,mux-ext-port : The external port of the i.MX audio muxer. + + - compatible : "eukrea,asoc-tlv320" + + - eukrea,model : The user-visible name of this sound complex. + + - ssi-controller : The phandle of the SSI controller. + + - fsl,mux-int-port : The internal port of the i.MX audio muxer (AUDMUX). + + - fsl,mux-ext-port : The external port of the i.MX audio muxer. Note: The AUDMUX port numbering should start at 1, which is consistent with hardware manual. diff --git a/Documentation/devicetree/bindings/sound/fsl,esai.txt b/Documentation/devicetree/bindings/sound/fsl,esai.txt index 52f5b6bf3e8e..d3b6b5f48010 100644 --- a/Documentation/devicetree/bindings/sound/fsl,esai.txt +++ b/Documentation/devicetree/bindings/sound/fsl,esai.txt @@ -7,37 +7,39 @@ other DSPs. It has up to six transmitters and four receivers. Required properties: - - compatible : Compatible list, must contain "fsl,imx35-esai" or - "fsl,vf610-esai" + - compatible : Compatible list, must contain "fsl,imx35-esai" or + "fsl,vf610-esai" - - reg : Offset and length of the register set for the device. + - reg : Offset and length of the register set for the device. - - interrupts : Contains the spdif interrupt. + - interrupts : Contains the spdif interrupt. - - dmas : Generic dma devicetree binding as described in - Documentation/devicetree/bindings/dma/dma.txt. + - dmas : Generic dma devicetree binding as described in + Documentation/devicetree/bindings/dma/dma.txt. - - dma-names : Two dmas have to be defined, "tx" and "rx". + - dma-names : Two dmas have to be defined, "tx" and "rx". - - clocks: Contains an entry for each entry in clock-names. + - clocks : Contains an entry for each entry in clock-names. - - clock-names : Includes the following entries: - "core" The core clock used to access registers - "extal" The esai baud clock for esai controller used to derive - HCK, SCK and FS. - "fsys" The system clock derived from ahb clock used to derive - HCK, SCK and FS. + - clock-names : Includes the following entries: + "core" The core clock used to access registers + "extal" The esai baud clock for esai controller used to + derive HCK, SCK and FS. + "fsys" The system clock derived from ahb clock used to + derive HCK, SCK and FS. - - fsl,fifo-depth: The number of elements in the transmit and receive FIFOs. - This number is the maximum allowed value for TFCR[TFWM] or RFCR[RFWM]. + - fsl,fifo-depth : The number of elements in the transmit and receive + FIFOs. This number is the maximum allowed value for + TFCR[TFWM] or RFCR[RFWM]. - fsl,esai-synchronous: This is a boolean property. If present, indicating - that ESAI would work in the synchronous mode, which means all the settings - for Receiving would be duplicated from Transmition related registers. + that ESAI would work in the synchronous mode, which + means all the settings for Receiving would be + duplicated from Transmition related registers. - - big-endian : If this property is absent, the native endian mode will - be in use as default, or the big endian mode will be in use for all the - device registers. + - big-endian : If this property is absent, the native endian mode + will be in use as default, or the big endian mode + will be in use for all the device registers. Example: diff --git a/Documentation/devicetree/bindings/sound/fsl,spdif.txt b/Documentation/devicetree/bindings/sound/fsl,spdif.txt index 3e9e82c8eab3..b5ee32ee3706 100644 --- a/Documentation/devicetree/bindings/sound/fsl,spdif.txt +++ b/Documentation/devicetree/bindings/sound/fsl,spdif.txt @@ -6,32 +6,31 @@ a fibre cable. Required properties: - - compatible : Compatible list, must contain "fsl,imx35-spdif". + - compatible : Compatible list, must contain "fsl,imx35-spdif". - - reg : Offset and length of the register set for the device. + - reg : Offset and length of the register set for the device. - - interrupts : Contains the spdif interrupt. + - interrupts : Contains the spdif interrupt. - - dmas : Generic dma devicetree binding as described in - Documentation/devicetree/bindings/dma/dma.txt. + - dmas : Generic dma devicetree binding as described in + Documentation/devicetree/bindings/dma/dma.txt. - - dma-names : Two dmas have to be defined, "tx" and "rx". + - dma-names : Two dmas have to be defined, "tx" and "rx". - - clocks : Contains an entry for each entry in clock-names. + - clocks : Contains an entry for each entry in clock-names. - - clock-names : Includes the following entries: - "core" The core clock of spdif controller - "rxtx<0-7>" Clock source list for tx and rx clock. - This clock list should be identical to - the source list connecting to the spdif - clock mux in "SPDIF Transceiver Clock - Diagram" of SoC reference manual. It - can also be referred to TxClk_Source - bit of register SPDIF_STC. + - clock-names : Includes the following entries: + "core" The core clock of spdif controller. + "rxtx<0-7>" Clock source list for tx and rx clock. + This clock list should be identical to the source + list connecting to the spdif clock mux in "SPDIF + Transceiver Clock Diagram" of SoC reference manual. + It can also be referred to TxClk_Source bit of + register SPDIF_STC. - - big-endian : If this property is absent, the native endian mode will - be in use as default, or the big endian mode will be in use for all the - device registers. + - big-endian : If this property is absent, the native endian mode + will be in use as default, or the big endian mode + will be in use for all the device registers. Example: diff --git a/Documentation/devicetree/bindings/sound/fsl-sai.txt b/Documentation/devicetree/bindings/sound/fsl-sai.txt index 4956b14d4b06..044e5d76e2dd 100644 --- a/Documentation/devicetree/bindings/sound/fsl-sai.txt +++ b/Documentation/devicetree/bindings/sound/fsl-sai.txt @@ -5,32 +5,48 @@ which provides a synchronous audio interface that supports fullduplex serial interfaces with frame synchronization such as I2S, AC97, TDM, and codec/DSP interfaces. - Required properties: -- compatible: Compatible list, contains "fsl,vf610-sai" or "fsl,imx6sx-sai". -- reg: Offset and length of the register set for the device. -- clocks: Must contain an entry for each entry in clock-names. -- clock-names : Must include the "bus" for register access and "mclk1" "mclk2" - "mclk3" for bit clock and frame clock providing. -- dmas : Generic dma devicetree binding as described in - Documentation/devicetree/bindings/dma/dma.txt. -- dma-names : Two dmas have to be defined, "tx" and "rx". -- pinctrl-names: Must contain a "default" entry. -- pinctrl-NNN: One property must exist for each entry in pinctrl-names. - See ../pinctrl/pinctrl-bindings.txt for details of the property values. -- big-endian: Boolean property, required if all the FTM_PWM registers - are big-endian rather than little-endian. -- lsb-first: Configures whether the LSB or the MSB is transmitted first for - the fifo data. If this property is absent, the MSB is transmitted first as - default, or the LSB is transmitted first. -- fsl,sai-synchronous-rx: This is a boolean property. If present, indicating - that SAI will work in the synchronous mode (sync Tx with Rx) which means - both the transimitter and receiver will send and receive data by following - receiver's bit clocks and frame sync clocks. -- fsl,sai-asynchronous: This is a boolean property. If present, indicating - that SAI will work in the asynchronous mode, which means both transimitter - and receiver will send and receive data by following their own bit clocks - and frame sync clocks separately. + + - compatible : Compatible list, contains "fsl,vf610-sai" or + "fsl,imx6sx-sai". + + - reg : Offset and length of the register set for the device. + + - clocks : Must contain an entry for each entry in clock-names. + + - clock-names : Must include the "bus" for register access and + "mclk1", "mclk2", "mclk3" for bit clock and frame + clock providing. + - dmas : Generic dma devicetree binding as described in + Documentation/devicetree/bindings/dma/dma.txt. + + - dma-names : Two dmas have to be defined, "tx" and "rx". + + - pinctrl-names : Must contain a "default" entry. + + - pinctrl-NNN : One property must exist for each entry in + pinctrl-names. See ../pinctrl/pinctrl-bindings.txt + for details of the property values. + + - big-endian : Boolean property, required if all the FTM_PWM + registers are big-endian rather than little-endian. + + - lsb-first : Configures whether the LSB or the MSB is transmitted + first for the fifo data. If this property is absent, + the MSB is transmitted first as default, or the LSB + is transmitted first. + + - fsl,sai-synchronous-rx: This is a boolean property. If present, indicating + that SAI will work in the synchronous mode (sync Tx + with Rx) which means both the transimitter and the + receiver will send and receive data by following + receiver's bit clocks and frame sync clocks. + + - fsl,sai-asynchronous: This is a boolean property. If present, indicating + that SAI will work in the asynchronous mode, which + means both transimitter and receiver will send and + receive data by following their own bit clocks and + frame sync clocks separately. Note: - If both fsl,sai-asynchronous and fsl,sai-synchronous-rx are absent, the diff --git a/Documentation/devicetree/bindings/sound/imx-audio-sgtl5000.txt b/Documentation/devicetree/bindings/sound/imx-audio-sgtl5000.txt index e4acdd891e49..2f89db88fd57 100644 --- a/Documentation/devicetree/bindings/sound/imx-audio-sgtl5000.txt +++ b/Documentation/devicetree/bindings/sound/imx-audio-sgtl5000.txt @@ -1,33 +1,40 @@ Freescale i.MX audio complex with SGTL5000 codec Required properties: -- compatible : "fsl,imx-audio-sgtl5000" -- model : The user-visible name of this sound complex -- ssi-controller : The phandle of the i.MX SSI controller -- audio-codec : The phandle of the SGTL5000 audio codec -- audio-routing : A list of the connections between audio components. - Each entry is a pair of strings, the first being the connection's sink, - the second being the connection's source. Valid names could be power - supplies, SGTL5000 pins, and the jacks on the board: - - Power supplies: - * Mic Bias - - SGTL5000 pins: - * MIC_IN - * LINE_IN - * HP_OUT - * LINE_OUT - - Board connectors: - * Mic Jack - * Line In Jack - * Headphone Jack - * Line Out Jack - * Ext Spk - -- mux-int-port : The internal port of the i.MX audio muxer (AUDMUX) -- mux-ext-port : The external port of the i.MX audio muxer + + - compatible : "fsl,imx-audio-sgtl5000" + + - model : The user-visible name of this sound complex + + - ssi-controller : The phandle of the i.MX SSI controller + + - audio-codec : The phandle of the SGTL5000 audio codec + + - audio-routing : A list of the connections between audio components. + Each entry is a pair of strings, the first being the + connection's sink, the second being the connection's + source. Valid names could be power supplies, SGTL5000 + pins, and the jacks on the board: + + Power supplies: + * Mic Bias + + SGTL5000 pins: + * MIC_IN + * LINE_IN + * HP_OUT + * LINE_OUT + + Board connectors: + * Mic Jack + * Line In Jack + * Headphone Jack + * Line Out Jack + * Ext Spk + + - mux-int-port : The internal port of the i.MX audio muxer (AUDMUX) + + - mux-ext-port : The external port of the i.MX audio muxer Note: The AUDMUX port numbering should start at 1, which is consistent with hardware manual. diff --git a/Documentation/devicetree/bindings/sound/imx-audio-spdif.txt b/Documentation/devicetree/bindings/sound/imx-audio-spdif.txt index 7d13479f9c3c..da84a442ccea 100644 --- a/Documentation/devicetree/bindings/sound/imx-audio-spdif.txt +++ b/Documentation/devicetree/bindings/sound/imx-audio-spdif.txt @@ -2,23 +2,25 @@ Freescale i.MX audio complex with S/PDIF transceiver Required properties: - - compatible : "fsl,imx-audio-spdif" + - compatible : "fsl,imx-audio-spdif" - - model : The user-visible name of this sound complex + - model : The user-visible name of this sound complex - - spdif-controller : The phandle of the i.MX S/PDIF controller + - spdif-controller : The phandle of the i.MX S/PDIF controller Optional properties: - - spdif-out : This is a boolean property. If present, the transmitting - function of S/PDIF will be enabled, indicating there's a physical - S/PDIF out connector/jack on the board or it's connecting to some - other IP block, such as an HDMI encoder/display-controller. + - spdif-out : This is a boolean property. If present, the + transmitting function of S/PDIF will be enabled, + indicating there's a physical S/PDIF out connector + or jack on the board or it's connecting to some + other IP block, such as an HDMI encoder or + display-controller. - - spdif-in : This is a boolean property. If present, the receiving - function of S/PDIF will be enabled, indicating there's a physical - S/PDIF in connector/jack on the board. + - spdif-in : This is a boolean property. If present, the receiving + function of S/PDIF will be enabled, indicating there + is a physical S/PDIF in connector/jack on the board. * Note: At least one of these two properties should be set in the DT binding. diff --git a/Documentation/devicetree/bindings/sound/imx-audio-wm8962.txt b/Documentation/devicetree/bindings/sound/imx-audio-wm8962.txt index f49450a87890..acea71bee34f 100644 --- a/Documentation/devicetree/bindings/sound/imx-audio-wm8962.txt +++ b/Documentation/devicetree/bindings/sound/imx-audio-wm8962.txt @@ -1,25 +1,32 @@ Freescale i.MX audio complex with WM8962 codec Required properties: -- compatible : "fsl,imx-audio-wm8962" -- model : The user-visible name of this sound complex -- ssi-controller : The phandle of the i.MX SSI controller -- audio-codec : The phandle of the WM8962 audio codec -- audio-routing : A list of the connections between audio components. - Each entry is a pair of strings, the first being the connection's sink, - the second being the connection's source. Valid names could be power - supplies, WM8962 pins, and the jacks on the board: - - Power supplies: - * Mic Bias - - Board connectors: - * Mic Jack - * Headphone Jack - * Ext Spk - -- mux-int-port : The internal port of the i.MX audio muxer (AUDMUX) -- mux-ext-port : The external port of the i.MX audio muxer + + - compatible : "fsl,imx-audio-wm8962" + + - model : The user-visible name of this sound complex + + - ssi-controller : The phandle of the i.MX SSI controller + + - audio-codec : The phandle of the WM8962 audio codec + + - audio-routing : A list of the connections between audio components. + Each entry is a pair of strings, the first being the + connection's sink, the second being the connection's + source. Valid names could be power supplies, WM8962 + pins, and the jacks on the board: + + Power supplies: + * Mic Bias + + Board connectors: + * Mic Jack + * Headphone Jack + * Ext Spk + + - mux-int-port : The internal port of the i.MX audio muxer (AUDMUX) + + - mux-ext-port : The external port of the i.MX audio muxer Note: The AUDMUX port numbering should start at 1, which is consistent with hardware manual. diff --git a/Documentation/devicetree/bindings/sound/imx-audmux.txt b/Documentation/devicetree/bindings/sound/imx-audmux.txt index f88a00e54c63..b30a737e209e 100644 --- a/Documentation/devicetree/bindings/sound/imx-audmux.txt +++ b/Documentation/devicetree/bindings/sound/imx-audmux.txt @@ -1,18 +1,24 @@ Freescale Digital Audio Mux (AUDMUX) device Required properties: -- compatible : "fsl,imx21-audmux" for AUDMUX version firstly used on i.MX21, - or "fsl,imx31-audmux" for the version firstly used on i.MX31. -- reg : Should contain AUDMUX registers location and length + + - compatible : "fsl,imx21-audmux" for AUDMUX version firstly used + on i.MX21, or "fsl,imx31-audmux" for the version + firstly used on i.MX31. + + - reg : Should contain AUDMUX registers location and length. An initial configuration can be setup using child nodes. Required properties of optional child nodes: -- fsl,audmux-port : Integer of the audmux port that is configured by this - child node. -- fsl,port-config : List of configuration options for the specific port. For - imx31-audmux and above, it is a list of tuples <ptcr pdcr>. For - imx21-audmux it is a list of pcr values. + + - fsl,audmux-port : Integer of the audmux port that is configured by this + child node. + + - fsl,port-config : List of configuration options for the specific port. + For imx31-audmux and above, it is a list of tuples + <ptcr pdcr>. For imx21-audmux it is a list of pcr + values. Example: diff --git a/Documentation/devicetree/bindings/sound/ingenic,jz4740-i2s.txt b/Documentation/devicetree/bindings/sound/ingenic,jz4740-i2s.txt new file mode 100644 index 000000000000..b41433386e2f --- /dev/null +++ b/Documentation/devicetree/bindings/sound/ingenic,jz4740-i2s.txt @@ -0,0 +1,23 @@ +Ingenic JZ4740 I2S controller + +Required properties: +- compatible : "ingenic,jz4740-i2s" +- reg : I2S registers location and length +- clocks : AIC and I2S PLL clock specifiers. +- clock-names: "aic" and "i2s" +- dmas: DMA controller phandle and DMA request line for I2S Tx and Rx channels +- dma-names: Must be "tx" and "rx" + +Example: + +i2s: i2s@10020000 { + compatible = "ingenic,jz4740-i2s"; + reg = <0x10020000 0x94>; + + clocks = <&cgu JZ4740_CLK_AIC>, <&cgu JZ4740_CLK_I2SPLL>; + clock-names = "aic", "i2s"; + + dmas = <&dma 2>, <&dma 3>; + dma-names = "tx", "rx"; + +}; diff --git a/Documentation/devicetree/bindings/sound/max98090.txt b/Documentation/devicetree/bindings/sound/max98090.txt index c454e67f54bb..aa802a274520 100644 --- a/Documentation/devicetree/bindings/sound/max98090.txt +++ b/Documentation/devicetree/bindings/sound/max98090.txt @@ -16,6 +16,8 @@ Optional properties: - clock-names: Should be "mclk" +- maxim,dmic-freq: Frequency at which to clock DMIC + Pins on the device (for linking into audio routes): * MIC1 diff --git a/Documentation/devicetree/bindings/sound/max98357a.txt b/Documentation/devicetree/bindings/sound/max98357a.txt new file mode 100644 index 000000000000..a7a149a236e5 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/max98357a.txt @@ -0,0 +1,14 @@ +Maxim MAX98357A audio DAC + +This node models the Maxim MAX98357A DAC. + +Required properties: +- compatible : "maxim,max98357a" +- sdmode-gpios : GPIO specifier for the GPIO -> DAC SDMODE pin + +Example: + +max98357a { + compatible = "maxim,max98357a"; + sdmode-gpios = <&qcom_pinmux 25 0>; +}; diff --git a/Documentation/devicetree/bindings/sound/nvidia,tegra-audio-rt5677.txt b/Documentation/devicetree/bindings/sound/nvidia,tegra-audio-rt5677.txt new file mode 100644 index 000000000000..a4589cda214e --- /dev/null +++ b/Documentation/devicetree/bindings/sound/nvidia,tegra-audio-rt5677.txt @@ -0,0 +1,67 @@ +NVIDIA Tegra audio complex, with RT5677 CODEC + +Required properties: +- compatible : "nvidia,tegra-audio-rt5677" +- clocks : Must contain an entry for each entry in clock-names. + See ../clocks/clock-bindings.txt for details. +- clock-names : Must include the following entries: + - pll_a + - pll_a_out0 + - mclk (The Tegra cdev1/extern1 clock, which feeds the CODEC's mclk) +- nvidia,model : The user-visible name of this sound complex. +- nvidia,audio-routing : A list of the connections between audio components. + Each entry is a pair of strings, the first being the connection's sink, + the second being the connection's source. Valid names for sources and + sinks are the RT5677's pins (as documented in its binding), and the jacks + on the board: + + * Headphone + * Speaker + * Headset Mic + * Internal Mic 1 + * Internal Mic 2 + +- nvidia,i2s-controller : The phandle of the Tegra I2S controller that's + connected to the CODEC. +- nvidia,audio-codec : The phandle of the RT5677 audio codec. This binding + assumes that AIF1 on the CODEC is connected to Tegra. + +Optional properties: +- nvidia,hp-det-gpios : The GPIO that detects headphones are plugged in +- nvidia,hp-en-gpios : The GPIO that enables headphone amplifier +- nvidia,mic-present-gpios: The GPIO that mic jack is plugged in +- nvidia,dmic-clk-en-gpios : The GPIO that gates DMIC clock signal + +Example: + +sound { + compatible = "nvidia,tegra-audio-rt5677-ryu", + "nvidia,tegra-audio-rt5677"; + nvidia,model = "NVIDIA Tegra Ryu"; + + nvidia,audio-routing = + "Headphone", "LOUT2", + "Headphone", "LOUT1", + "Headset Mic", "MICBIAS1", + "IN1P", "Headset Mic", + "IN1N", "Headset Mic", + "DMIC L1", "Internal Mic 1", + "DMIC R1", "Internal Mic 1", + "DMIC L2", "Internal Mic 2", + "DMIC R2", "Internal Mic 2", + "Speaker", "PDM1L", + "Speaker", "PDM1R"; + + nvidia,i2s-controller = <&tegra_i2s1>; + nvidia,audio-codec = <&rt5677>; + + nvidia,hp-det-gpios = <&gpio TEGRA_GPIO(R, 7) GPIO_ACTIVE_HIGH>; + nvidia,mic-present-gpios = <&gpio TEGRA_GPIO(O, 5) GPIO_ACTIVE_LOW>; + nvidia,hp-en-gpios = <&rt5677 1 GPIO_ACTIVE_HIGH>; + nvidia,dmic-clk-en-gpios = <&rt5677 2 GPIO_ACTIVE_HIGH>; + + clocks = <&tegra_car TEGRA124_CLK_PLL_A>, + <&tegra_car TEGRA124_CLK_PLL_A_OUT0>, + <&tegra_car TEGRA124_CLK_EXTERN1>; + clock-names = "pll_a", "pll_a_out0", "mclk"; +}; diff --git a/Documentation/devicetree/bindings/sound/nvidia,tegra30-ahub.txt b/Documentation/devicetree/bindings/sound/nvidia,tegra30-ahub.txt index 946e2ac46091..0e9a1895d7fb 100644 --- a/Documentation/devicetree/bindings/sound/nvidia,tegra30-ahub.txt +++ b/Documentation/devicetree/bindings/sound/nvidia,tegra30-ahub.txt @@ -1,7 +1,10 @@ NVIDIA Tegra30 AHUB (Audio Hub) Required properties: -- compatible : "nvidia,tegra30-ahub", "nvidia,tegra114-ahub", etc. +- compatible : For Tegra30, must contain "nvidia,tegra30-ahub". For Tegra114, + must contain "nvidia,tegra114-ahub". For Tegra124, must contain + "nvidia,tegra124-ahub". Otherwise, must contain "nvidia,<chip>-ahub", + plus at least one of the above, where <chip> is tegra132. - reg : Should contain the register physical address and length for each of the AHUB's register blocks. - Tegra30 requires 2 entries, for the APBIF and AHUB/AUDIO register blocks. diff --git a/Documentation/devicetree/bindings/sound/nvidia,tegra30-hda.txt b/Documentation/devicetree/bindings/sound/nvidia,tegra30-hda.txt index b4730c2822bc..13e2ef496724 100644 --- a/Documentation/devicetree/bindings/sound/nvidia,tegra30-hda.txt +++ b/Documentation/devicetree/bindings/sound/nvidia,tegra30-hda.txt @@ -1,7 +1,9 @@ NVIDIA Tegra30 HDA controller Required properties: -- compatible : "nvidia,tegra30-hda" +- compatible : For Tegra30, must contain "nvidia,tegra30-hda". Otherwise, + must contain '"nvidia,<chip>-hda", "nvidia,tegra30-hda"', where <chip> is + tegra114, tegra124, or tegra132. - reg : Should contain the HDA registers location and length. - interrupts : The interrupt from the HDA controller. - clocks : Must contain an entry for each required entry in clock-names. diff --git a/Documentation/devicetree/bindings/sound/nvidia,tegra30-i2s.txt b/Documentation/devicetree/bindings/sound/nvidia,tegra30-i2s.txt index 0c113ffe3814..38caa936f6f8 100644 --- a/Documentation/devicetree/bindings/sound/nvidia,tegra30-i2s.txt +++ b/Documentation/devicetree/bindings/sound/nvidia,tegra30-i2s.txt @@ -1,7 +1,10 @@ NVIDIA Tegra30 I2S controller Required properties: -- compatible : "nvidia,tegra30-i2s" +- compatible : For Tegra30, must contain "nvidia,tegra30-i2s". For Tegra124, + must contain "nvidia,tegra124-i2s". Otherwise, must contain + "nvidia,<chip>-i2s" plus at least one of the above, where <chip> is + tegra114 or tegra132. - reg : Should contain I2S registers location and length - clocks : Must contain one entry, for the module clock. See ../clocks/clock-bindings.txt for details. diff --git a/Documentation/devicetree/bindings/sound/pcm512x.txt b/Documentation/devicetree/bindings/sound/pcm512x.txt index faff75e64573..3aae3b41bd8e 100644 --- a/Documentation/devicetree/bindings/sound/pcm512x.txt +++ b/Documentation/devicetree/bindings/sound/pcm512x.txt @@ -5,7 +5,8 @@ on the board). Required properties: - - compatible : One of "ti,pcm5121" or "ti,pcm5122" + - compatible : One of "ti,pcm5121", "ti,pcm5122", "ti,pcm5141" or + "ti,pcm5142" - reg : the I2C address of the device for I2C, the chip select number for SPI. @@ -16,9 +17,16 @@ Required properties: Optional properties: - clocks : A clock specifier for the clock connected as SCLK. If this - is absent the device will be configured to clock from BCLK. + is absent the device will be configured to clock from BCLK. If pll-in + and pll-out are specified in addition to a clock, the device is + configured to accept clock input on a specified gpio pin. -Example: + - pll-in, pll-out : gpio pins used to connect the pll using <1> + through <6>. The device will be configured for clock input on the + given pll-in pin and PLL output on the given pll-out pin. An + external connection from the pll-out pin to the SCLK pin is assumed. + +Examples: pcm5122: pcm5122@4c { compatible = "ti,pcm5122"; @@ -28,3 +36,17 @@ Example: DVDD-supply = <®_1v8>; CPVDD-supply = <®_3v3>; }; + + + pcm5142: pcm5142@4c { + compatible = "ti,pcm5142"; + reg = <0x4c>; + + AVDD-supply = <®_3v3_analog>; + DVDD-supply = <®_1v8>; + CPVDD-supply = <®_3v3>; + + clocks = <&sck>; + pll-in = <3>; + pll-out = <6>; + }; diff --git a/Documentation/devicetree/bindings/sound/renesas,fsi.txt b/Documentation/devicetree/bindings/sound/renesas,fsi.txt index c5be003f413e..0d0ab51105b0 100644 --- a/Documentation/devicetree/bindings/sound/renesas,fsi.txt +++ b/Documentation/devicetree/bindings/sound/renesas,fsi.txt @@ -1,11 +1,16 @@ Renesas FSI Required properties: -- compatible : "renesas,sh_fsi2" or "renesas,sh_fsi" +- compatible : "renesas,fsi2-<soctype>", + "renesas,sh_fsi2" or "renesas,sh_fsi" as + fallback. + Examples with soctypes are: + - "renesas,fsi2-r8a7740" (R-Mobile A1) + - "renesas,fsi2-sh73a0" (SH-Mobile AG5) - reg : Should contain the register physical address and length - interrupts : Should contain FSI interrupt -- fsia,spdif-connection : FSI is connected by S/PDFI +- fsia,spdif-connection : FSI is connected by S/PDIF - fsia,stream-mode-support : FSI supports 16bit stream mode. - fsia,use-internal-clock : FSI uses internal clock when master mode. diff --git a/Documentation/devicetree/bindings/sound/renesas,rsnd.txt b/Documentation/devicetree/bindings/sound/renesas,rsnd.txt index aa697abf337e..2dd690bc19cc 100644 --- a/Documentation/devicetree/bindings/sound/renesas,rsnd.txt +++ b/Documentation/devicetree/bindings/sound/renesas,rsnd.txt @@ -1,8 +1,12 @@ Renesas R-Car sound Required properties: -- compatible : "renesas,rcar_sound-gen1" if generation1 +- compatible : "renesas,rcar_sound-<soctype>", fallbacks + "renesas,rcar_sound-gen1" if generation1, and "renesas,rcar_sound-gen2" if generation2 + Examples with soctypes are: + - "renesas,rcar_sound-r8a7790" (R-Car H2) + - "renesas,rcar_sound-r8a7791" (R-Car M2-W) - reg : Should contain the register physical address. required register is SRU/ADG/SSI if generation1 @@ -35,9 +39,9 @@ DAI subnode properties: Example: -rcar_sound: rcar_sound@0xffd90000 { +rcar_sound: rcar_sound@ec500000 { #sound-dai-cells = <1>; - compatible = "renesas,rcar_sound-gen2"; + compatible = "renesas,rcar_sound-r8a7791", "renesas,rcar_sound-gen2"; reg = <0 0xec500000 0 0x1000>, /* SCU */ <0 0xec5a0000 0 0x100>, /* ADG */ <0 0xec540000 0 0x1000>, /* SSIU */ diff --git a/Documentation/devicetree/bindings/sound/rt5631.txt b/Documentation/devicetree/bindings/sound/rt5631.txt new file mode 100644 index 000000000000..92b986ca337b --- /dev/null +++ b/Documentation/devicetree/bindings/sound/rt5631.txt @@ -0,0 +1,48 @@ +ALC5631/RT5631 audio CODEC + +This device supports I2C only. + +Required properties: + + - compatible : "realtek,alc5631" or "realtek,rt5631" + + - reg : the I2C address of the device. + +Pins on the device (for linking into audio routes): + + * SPK_OUT_R_P + * SPK_OUT_R_N + * SPK_OUT_L_P + * SPK_OUT_L_N + * HP_OUT_L + * HP_OUT_R + * AUX_OUT2_LP + * AUX_OUT2_RN + * AUX_OUT1_LP + * AUX_OUT1_RN + * AUX_IN_L_JD + * AUX_IN_R_JD + * MONO_IN_P + * MONO_IN_N + * MIC1_P + * MIC1_N + * MIC2_P + * MIC2_N + * MONO_OUT_P + * MONO_OUT_N + * MICBIAS1 + * MICBIAS2 + +Example: + +alc5631: alc5631@1a { + compatible = "realtek,alc5631"; + reg = <0x1a>; +}; + +or + +rt5631: rt5631@1a { + compatible = "realtek,rt5631"; + reg = <0x1a>; +}; diff --git a/Documentation/devicetree/bindings/sound/rt5677.txt b/Documentation/devicetree/bindings/sound/rt5677.txt index 0701b834fc73..740ff771aa8b 100644 --- a/Documentation/devicetree/bindings/sound/rt5677.txt +++ b/Documentation/devicetree/bindings/sound/rt5677.txt @@ -27,6 +27,21 @@ Optional properties: Boolean. Indicate MIC1/2 input and LOUT1/2/3 outputs are differential, rather than single-ended. +- realtek,gpio-config + Array of six 8bit elements that configures GPIO. + 0 - floating (reset value) + 1 - pull down + 2 - pull up + +- realtek,jd1-gpio + Configures GPIO Mic Jack detection 1. + Select 0 ~ 3 as OFF, GPIO1, GPIO2 and GPIO3 respectively. + +- realtek,jd2-gpio +- realtek,jd3-gpio + Configures GPIO Mic Jack detection 2 and 3. + Select 0 ~ 3 as OFF, GPIO4, GPIO5 and GPIO6 respectively. + Pins on the device (for linking into audio routes): * IN1P @@ -56,4 +71,6 @@ rt5677 { realtek,pow-ldo2-gpio = <&gpio TEGRA_GPIO(V, 3) GPIO_ACTIVE_HIGH>; realtek,in1-differential = "true"; + realtek,gpio-config = /bits/ 8 <0 0 0 0 0 2>; /* pull up GPIO6 */ + realtek,jd2-gpio = <3>; /* Enables Jack detection for GPIO6 */ }; diff --git a/Documentation/devicetree/bindings/sound/samsung-i2s.txt b/Documentation/devicetree/bindings/sound/samsung-i2s.txt index 7386d444ada1..09e0e18591ae 100644 --- a/Documentation/devicetree/bindings/sound/samsung-i2s.txt +++ b/Documentation/devicetree/bindings/sound/samsung-i2s.txt @@ -6,10 +6,17 @@ Required SoC Specific Properties: - samsung,s3c6410-i2s: for 8/16/24bit stereo I2S. - samsung,s5pv210-i2s: for 8/16/24bit multichannel(5.1) I2S with secondary fifo, s/w reset control and internal mux for root clk src. - - samsung,exynos5420-i2s: for 8/16/24bit multichannel(7.1) I2S with - secondary fifo, s/w reset control, internal mux for root clk src and - TDM support. TDM (Time division multiplexing) is to allow transfer of - multiple channel audio data on single data line. + - samsung,exynos5420-i2s: for 8/16/24bit multichannel(5.1) I2S for + playback, sterio channel capture, secondary fifo using internal + or external dma, s/w reset control, internal mux for root clk src + and 7.1 channel TDM support for playback. TDM (Time division multiplexing) + is to allow transfer of multiple channel audio data on single data line. + - samsung,exynos7-i2s: with all the available features of exynos5 i2s, + exynos7 I2S has 7.1 channel TDM support for capture, secondary fifo + with only external dma and more no.of root clk sampling frequencies. + - samsung,exynos7-i2s1: I2S1 on previous samsung platforms supports + stereo channels. exynos7 i2s1 upgraded to 5.1 multichannel with + slightly modified bit offsets. - reg: physical base address of the controller and length of memory mapped region. @@ -26,6 +33,25 @@ Required SoC Specific Properties: "iis" is the i2s bus clock and i2s_opclk0, i2s_opclk1 are sources of the root clk. i2s0 has internal mux to select the source of root clk and i2s1 and i2s2 doesn't have any such mux. +- #clock-cells: should be 1, this property must be present if the I2S device + is a clock provider in terms of the common clock bindings, described in + ../clock/clock-bindings.txt. +- clock-output-names: from the common clock bindings, names of the CDCLK + I2S output clocks, suggested values are "i2s_cdclk0", "i2s_cdclk1", + "i2s_cdclk3" for the I2S0, I2S1, I2S2 devices recpectively. + +There are following clocks available at the I2S device nodes: + CLK_I2S_CDCLK - the CDCLK (CODECLKO) gate clock, + CLK_I2S_RCLK_PSR - the RCLK prescaler divider clock (corresponding to the + IISPSR register), + CLK_I2S_RCLK_SRC - the RCLKSRC mux clock (corresponding to RCLKSRC bit in + IISMOD register). + +Refer to the SoC datasheet for availability of the above clocks. +The CLK_I2S_RCLK_PSR and CLK_I2S_RCLK_SRC clocks are usually only available +in the IIS Multi Audio Interface (I2S0). +Note: Old DTs may not have the #clock-cells, clock-output-names properties +and then not use the I2S node as a clock supplier. Optional SoC Specific Properties: @@ -34,6 +60,7 @@ Optional SoC Specific Properties: - pinctrl-0: Should specify pin control groups used for this controller. - pinctrl-names: Should contain only one value - "default". + Example: i2s0: i2s@03830000 { @@ -47,6 +74,8 @@ i2s0: i2s@03830000 { <&clock_audss EXYNOS_I2S_BUS>, <&clock_audss EXYNOS_SCLK_I2S>; clock-names = "iis", "i2s_opclk0", "i2s_opclk1"; + #clock-cells; + clock-output-names = "i2s_cdclk0"; samsung,idma-addr = <0x03000000>; pinctrl-names = "default"; pinctrl-0 = <&i2s0_bus>; diff --git a/Documentation/devicetree/bindings/sound/sgtl5000.txt b/Documentation/devicetree/bindings/sound/sgtl5000.txt index d556dcb8816b..0e5e4eb3ef1b 100644 --- a/Documentation/devicetree/bindings/sound/sgtl5000.txt +++ b/Documentation/devicetree/bindings/sound/sgtl5000.txt @@ -7,6 +7,17 @@ Required properties: - clocks : the clock provider of SYS_MCLK +- micbias-resistor-k-ohms : the bias resistor to be used in kOmhs + The resistor can take values of 2k, 4k or 8k. + If set to 0 it will be off. + If this node is not mentioned or if the value is unknown, then + micbias resistor is set to 4K. + +- micbias-voltage-m-volts : the bias voltage to be used in mVolts + The voltage can take values from 1.25V to 3V by 250mV steps + If this node is not mentionned or the value is unknown, then + the value is set to 1.25V. + - VDDA-supply : the regulator provider of VDDA - VDDIO-supply: the regulator provider of VDDIO @@ -21,6 +32,8 @@ codec: sgtl5000@0a { compatible = "fsl,sgtl5000"; reg = <0x0a>; clocks = <&clks 150>; + micbias-resistor-k-ohms = <2>; + micbias-voltage-m-volts = <2250>; VDDA-supply = <®_3p3v>; VDDIO-supply = <®_3p3v>; }; diff --git a/Documentation/devicetree/bindings/sound/simple-card.txt b/Documentation/devicetree/bindings/sound/simple-card.txt index c3cba600bf11..73bf314f7240 100644 --- a/Documentation/devicetree/bindings/sound/simple-card.txt +++ b/Documentation/devicetree/bindings/sound/simple-card.txt @@ -75,6 +75,11 @@ Optional CPU/CODEC subnodes properties: it can be specified via "clocks" if system has clock node (= common clock), or "system-clock-frequency" (if system doens't support common clock) + If a clock is specified, it is + enabled with clk_prepare_enable() + in dai startup() and disabled with + clk_disable_unprepare() in dai + shutdown(). Example 1 - single DAI link: diff --git a/Documentation/devicetree/bindings/sound/st,sta32x.txt b/Documentation/devicetree/bindings/sound/st,sta32x.txt new file mode 100644 index 000000000000..255de3ae5b2f --- /dev/null +++ b/Documentation/devicetree/bindings/sound/st,sta32x.txt @@ -0,0 +1,92 @@ +STA32X audio CODEC + +The driver for this device only supports I2C. + +Required properties: + + - compatible: "st,sta32x" + - reg: the I2C address of the device for I2C + - reset-gpios: a GPIO spec for the reset pin. If specified, it will be + deasserted before communication to the codec starts. + + - power-down-gpios: a GPIO spec for the power down pin. If specified, + it will be deasserted before communication to the codec + starts. + + - Vdda-supply: regulator spec, providing 3.3V + - Vdd3-supply: regulator spec, providing 3.3V + - Vcc-supply: regulator spec, providing 5V - 26V + +Optional properties: + + - st,output-conf: number, Selects the output configuration: + 0: 2-channel (full-bridge) power, 2-channel data-out + 1: 2 (half-bridge). 1 (full-bridge) on-board power + 2: 2 Channel (Full-Bridge) Power, 1 Channel FFX + 3: 1 Channel Mono-Parallel + If parameter is missing, mode 0 will be enabled. + This property has to be specified as '/bits/ 8' value. + + - st,ch1-output-mapping: Channel 1 output mapping + - st,ch2-output-mapping: Channel 2 output mapping + - st,ch3-output-mapping: Channel 3 output mapping + 0: Channel 1 + 1: Channel 2 + 2: Channel 3 + If parameter is missing, channel 1 is chosen. + This properties have to be specified as '/bits/ 8' values. + + - st,thermal-warning-recover: + If present, thermal warning recovery is enabled. + + - st,thermal-warning-adjustment: + If present, thermal warning adjustment is enabled. + + - st,fault-detect-recovery: + If present, then fault recovery will be enabled. + + - st,drop-compensation-ns: number + Only required for "st,ffx-power-output-mode" == + "variable-drop-compensation". + Specifies the drop compensation in nanoseconds. + The value must be in the range of 0..300, and only + multiples of 20 are allowed. Default is 140ns. + + - st,max-power-use-mpcc: + If present, then MPCC bits are used for MPC coefficients, + otherwise standard MPC coefficients are used. + + - st,max-power-corr: + If present, power bridge correction for THD reduction near maximum + power output is enabled. + + - st,am-reduction-mode: + If present, FFX mode runs in AM reduction mode, otherwise normal + FFX mode is used. + + - st,odd-pwm-speed-mode: + If present, PWM speed mode run on odd speed mode (341.3 kHz) on all + channels. If not present, normal PWM spped mode (384 kHz) will be used. + + - st,invalid-input-detect-mute: + If present, automatic invalid input detect mute is enabled. + +Example: + +codec: sta32x@38 { + compatible = "st,sta32x"; + reg = <0x1c>; + reset-gpios = <&gpio1 19 0>; + power-down-gpios = <&gpio1 16 0>; + st,output-conf = /bits/ 8 <0x3>; // set output to 2-channel + // (full-bridge) power, + // 2-channel data-out + st,ch1-output-mapping = /bits/ 8 <0>; // set channel 1 output ch 1 + st,ch2-output-mapping = /bits/ 8 <0>; // set channel 2 output ch 1 + st,ch3-output-mapping = /bits/ 8 <0>; // set channel 3 output ch 1 + st,max-power-correction; // enables power bridge + // correction for THD reduction + // near maximum power output + st,invalid-input-detect-mute; // mute if no valid digital + // audio signal is provided. +}; diff --git a/Documentation/devicetree/bindings/sound/tlv320aic3x.txt b/Documentation/devicetree/bindings/sound/tlv320aic3x.txt index 5e6040c2c2e9..47a213c411ce 100644 --- a/Documentation/devicetree/bindings/sound/tlv320aic3x.txt +++ b/Documentation/devicetree/bindings/sound/tlv320aic3x.txt @@ -9,6 +9,7 @@ Required properties: "ti,tlv320aic33" - TLV320AIC33 "ti,tlv320aic3007" - TLV320AIC3007 "ti,tlv320aic3106" - TLV320AIC3106 + "ti,tlv320aic3104" - TLV320AIC3104 - reg - <int> - I2C slave address @@ -18,6 +19,7 @@ Optional properties: - gpio-reset - gpio pin number used for codec reset - ai3x-gpio-func - <array of 2 int> - AIC3X_GPIO1 & AIC3X_GPIO2 Functionality + - Not supported on tlv320aic3104 - ai3x-micbias-vg - MicBias Voltage required. 1 - MICBIAS output is powered to 2.0V, 2 - MICBIAS output is powered to 2.5V, @@ -36,7 +38,13 @@ CODEC output pins: * HPLCOM * HPRCOM -CODEC input pins: +CODEC input pins for TLV320AIC3104: + * MIC2L + * MIC2R + * LINE1L + * LINE1R + +CODEC input pins for other compatible codecs: * MIC3L * MIC3R * LINE1L diff --git a/Documentation/devicetree/bindings/sound/ts3a227e.txt b/Documentation/devicetree/bindings/sound/ts3a227e.txt new file mode 100644 index 000000000000..a836881d9608 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/ts3a227e.txt @@ -0,0 +1,31 @@ +Texas Instruments TS3A227E +Autonomous Audio Accessory Detection and Configuration Switch + +The TS3A227E detect headsets of 3-ring and 4-ring standards and +switches automatically to route the microphone correctly. It also +handles key press detection in accordance with the Android audio +headset specification v1.0. + +Required properties: + + - compatible: Should contain "ti,ts3a227e". + - reg: The i2c address. Should contain <0x3b>. + - interrupt-parent: The parent interrupt controller + - interrupts: Interrupt number for /INT pin from the 227e + +Optional properies: + - ti,micbias: Intended MICBIAS voltage (datasheet section 9.6.7). + Select 0/1/2/3/4/5/6/7 to specify MACBIAS voltage + 2.1V/2.2V/2.3V/2.4V/2.5V/2.6V/2.7V/2.8V + Default value is "1" (2.2V). + +Examples: + + i2c { + ts3a227e@3b { + compatible = "ti,ts3a227e"; + reg = <0x3b>; + interrupt-parent = <&gpio>; + interrupts = <3 IRQ_TYPE_LEVEL_LOW>; + }; + }; diff --git a/Documentation/devicetree/bindings/sound/wm8904.txt b/Documentation/devicetree/bindings/sound/wm8904.txt index e99f4097c83c..66bf261423b9 100644 --- a/Documentation/devicetree/bindings/sound/wm8904.txt +++ b/Documentation/devicetree/bindings/sound/wm8904.txt @@ -3,7 +3,7 @@ WM8904 audio CODEC This device supports I2C only. Required properties: - - compatible: "wlf,wm8904" + - compatible: "wlf,wm8904" or "wlf,wm8912" - reg: the I2C address of the device. - clock-names: "mclk" - clocks: reference to diff --git a/Documentation/devicetree/bindings/sound/wm8960.txt b/Documentation/devicetree/bindings/sound/wm8960.txt new file mode 100644 index 000000000000..2deb8a3da9c5 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/wm8960.txt @@ -0,0 +1,31 @@ +WM8960 audio CODEC + +This device supports I2C only. + +Required properties: + + - compatible : "wlf,wm8960" + + - reg : the I2C address of the device. + +Optional properties: + - wlf,shared-lrclk: This is a boolean property. If present, the LRCM bit of + R24 (Additional control 2) gets set, indicating that ADCLRC and DACLRC pins + will be disabled only when ADC (Left and Right) and DAC (Left and Right) + are disabled. + When wm8960 works on synchronize mode and DACLRC pin is used to supply + frame clock, it will no frame clock for captrue unless enable DAC to enable + DACLRC pin. If shared-lrclk is present, no need to enable DAC for captrue. + + - wlf,capless: This is a boolean property. If present, OUT3 pin will be + enabled and disabled together with HP_L and HP_R pins in response to jack + detect events. + +Example: + +codec: wm8960@1a { + compatible = "wlf,wm8960"; + reg = <0x1a>; + + wlf,shared-lrclk; +}; diff --git a/Documentation/devicetree/bindings/spi/nvidia,tegra114-spi.txt b/Documentation/devicetree/bindings/spi/nvidia,tegra114-spi.txt index 7ea701e07dc2..b785976fe98a 100644 --- a/Documentation/devicetree/bindings/spi/nvidia,tegra114-spi.txt +++ b/Documentation/devicetree/bindings/spi/nvidia,tegra114-spi.txt @@ -1,7 +1,9 @@ NVIDIA Tegra114 SPI controller. Required properties: -- compatible : should be "nvidia,tegra114-spi". +- compatible : For Tegra114, must contain "nvidia,tegra114-spi". + Otherwise, must contain '"nvidia,<chip>-spi", "nvidia,tegra114-spi"' where + <chip> is tegra124, tegra132, or tegra210. - reg: Should contain SPI registers location and length. - interrupts: Should contain SPI interrupts. - clock-names : Must include the following entries: diff --git a/Documentation/devicetree/bindings/spi/sh-msiof.txt b/Documentation/devicetree/bindings/spi/sh-msiof.txt index d11c3721e7cd..4c388bb2f0a2 100644 --- a/Documentation/devicetree/bindings/spi/sh-msiof.txt +++ b/Documentation/devicetree/bindings/spi/sh-msiof.txt @@ -30,6 +30,22 @@ Optional properties: specifiers, one for transmission, and one for reception. - dma-names : Must contain a list of two DMA names, "tx" and "rx". +- renesas,dtdl : delay sync signal (setup) in transmit mode. + Must contain one of the following values: + 0 (no bit delay) + 50 (0.5-clock-cycle delay) + 100 (1-clock-cycle delay) + 150 (1.5-clock-cycle delay) + 200 (2-clock-cycle delay) + +- renesas,syncdl : delay sync signal (hold) in transmit mode. + Must contain one of the following values: + 0 (no bit delay) + 50 (0.5-clock-cycle delay) + 100 (1-clock-cycle delay) + 150 (1.5-clock-cycle delay) + 200 (2-clock-cycle delay) + 300 (3-clock-cycle delay) Optional properties, deprecated for soctype-specific bindings: - renesas,tx-fifo-size : Overrides the default tx fifo size given in words diff --git a/Documentation/devicetree/bindings/spi/spi-gpio.txt b/Documentation/devicetree/bindings/spi/spi-gpio.txt index 8a824be15754..a95603bcf6ff 100644 --- a/Documentation/devicetree/bindings/spi/spi-gpio.txt +++ b/Documentation/devicetree/bindings/spi/spi-gpio.txt @@ -8,8 +8,10 @@ Required properties: - gpio-sck: GPIO spec for the SCK line to use - gpio-miso: GPIO spec for the MISO line to use - gpio-mosi: GPIO spec for the MOSI line to use - - cs-gpios: GPIOs to use for chipselect lines - - num-chipselects: number of chipselect lines + - cs-gpios: GPIOs to use for chipselect lines. + Not needed if num-chipselects = <0>. + - num-chipselects: Number of chipselect lines. Should be <0> if a single device + with no chip select is connected. Example: diff --git a/Documentation/devicetree/bindings/spi/spi-img-spfi.txt b/Documentation/devicetree/bindings/spi/spi-img-spfi.txt new file mode 100644 index 000000000000..c7dd50fb8eb2 --- /dev/null +++ b/Documentation/devicetree/bindings/spi/spi-img-spfi.txt @@ -0,0 +1,37 @@ +IMG Synchronous Peripheral Flash Interface (SPFI) controller + +Required properties: +- compatible: Must be "img,spfi". +- reg: Must contain the base address and length of the SPFI registers. +- interrupts: Must contain the SPFI interrupt. +- clocks: Must contain an entry for each entry in clock-names. + See ../clock/clock-bindings.txt for details. +- clock-names: Must include the following entries: + - spfi: SPI operating clock + - sys: SPI system interface clock +- dmas: Must contain an entry for each entry in dma-names. + See ../dma/dma.txt for details. +- dma-names: Must include the following entries: + - rx + - tx +- #address-cells: Must be 1. +- #size-cells: Must be 0. + +Optional properties: +- img,supports-quad-mode: Should be set if the interface supports quad mode + SPI transfers. + +Example: + +spi@18100f00 { + compatible = "img,spfi"; + reg = <0x18100f00 0x100>; + interrupts = <GIC_SHARED 22 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&spi_clk>, <&system_clk>; + clock-names = "spfi", "sys"; + dmas = <&mdc 9 0xffffffff 0>, <&mdc 10 0xffffffff 0>; + dma-names = "rx", "tx"; + + #address-cells = <1>; + #size-cells = <0>; +}; diff --git a/Documentation/devicetree/bindings/spi/spi-meson.txt b/Documentation/devicetree/bindings/spi/spi-meson.txt new file mode 100644 index 000000000000..bb52a86f3365 --- /dev/null +++ b/Documentation/devicetree/bindings/spi/spi-meson.txt @@ -0,0 +1,22 @@ +Amlogic Meson SPI controllers + +* SPIFC (SPI Flash Controller) + +The Meson SPIFC is a controller optimized for communication with SPI +NOR memories, without DMA support and a 64-byte unified transmit / +receive buffer. + +Required properties: + - compatible: should be "amlogic,meson6-spifc" + - reg: physical base address and length of the controller registers + - clocks: phandle of the input clock for the baud rate generator + - #address-cells: should be 1 + - #size-cells: should be 0 + + spi@c1108c80 { + compatible = "amlogic,meson6-spifc"; + reg = <0xc1108c80 0x80>; + clocks = <&clk81>; + #address-cells = <1>; + #size-cells = <0>; + }; diff --git a/Documentation/devicetree/bindings/spi/spi-samsung.txt b/Documentation/devicetree/bindings/spi/spi-samsung.txt index 1e8a8578148f..6dbdeb3c361a 100644 --- a/Documentation/devicetree/bindings/spi/spi-samsung.txt +++ b/Documentation/devicetree/bindings/spi/spi-samsung.txt @@ -9,7 +9,7 @@ Required SoC Specific Properties: - samsung,s3c2443-spi: for s3c2443, s3c2416 and s3c2450 platforms - samsung,s3c6410-spi: for s3c6410 platforms - samsung,s5pv210-spi: for s5pv210 and s5pc110 platforms - - samsung,exynos4210-spi: for exynos4 and exynos5 platforms + - samsung,exynos7-spi: for exynos7 platforms - reg: physical base address of the controller and length of memory mapped region. diff --git a/Documentation/devicetree/bindings/spi/spi-sirf.txt b/Documentation/devicetree/bindings/spi/spi-sirf.txt new file mode 100644 index 000000000000..4c7adb8f777c --- /dev/null +++ b/Documentation/devicetree/bindings/spi/spi-sirf.txt @@ -0,0 +1,41 @@ +* CSR SiRFprimaII Serial Peripheral Interface + +Required properties: +- compatible : Should be "sirf,prima2-spi" +- reg : Offset and length of the register set for the device +- interrupts : Should contain SPI interrupt +- resets: phandle to the reset controller asserting this device in + reset + See ../reset/reset.txt for details. +- dmas : Must contain an entry for each entry in clock-names. + See ../dma/dma.txt for details. +- dma-names : Must include the following entries: + - rx + - tx +- clocks : Must contain an entry for each entry in clock-names. + See ../clocks/clock-bindings.txt for details. + +- #address-cells: Number of cells required to define a chip select + address on the SPI bus. Should be set to 1. +- #size-cells: Should be zero. + +Optional properties: +- spi-max-frequency: Specifies maximum SPI clock frequency, + Units - Hz. Definition as per + Documentation/devicetree/bindings/spi/spi-bus.txt +- cs-gpios: should specify GPIOs used for chipselects. + +Example: + +spi0: spi@b00d0000 { + compatible = "sirf,prima2-spi"; + reg = <0xb00d0000 0x10000>; + interrupts = <15>; + dmas = <&dmac1 9>, + <&dmac1 4>; + dma-names = "rx", "tx"; + #address-cells = <1>; + #size-cells = <0>; + clocks = <&clks 19>; + resets = <&rstc 26>; +}; diff --git a/Documentation/devicetree/bindings/spi/spi-st-ssc.txt b/Documentation/devicetree/bindings/spi/spi-st-ssc.txt new file mode 100644 index 000000000000..fe54959ec957 --- /dev/null +++ b/Documentation/devicetree/bindings/spi/spi-st-ssc.txt @@ -0,0 +1,40 @@ +STMicroelectronics SSC (SPI) Controller +--------------------------------------- + +Required properties: +- compatible : "st,comms-ssc4-spi" +- reg : Offset and length of the device's register set +- interrupts : The interrupt specifier +- clock-names : Must contain "ssc" +- clocks : Must contain an entry for each name in clock-names + See ../clk/* +- pinctrl-names : Uses "default", can use "sleep" if provided + See ../pinctrl/pinctrl-binding.txt + +Optional properties: +- cs-gpios : List of GPIO chip selects + See ../spi/spi-bus.txt + +Child nodes represent devices on the SPI bus + See ../spi/spi-bus.txt + +Example: + spi@9840000 { + compatible = "st,comms-ssc4-spi"; + reg = <0x9840000 0x110>; + interrupts = <GIC_SPI 112 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&clk_s_c0_flexgen CLK_EXT2F_A9>; + clock-names = "ssc"; + pinctrl-0 = <&pinctrl_spi0_default>; + pinctrl-names = "default"; + cs-gpios = <&pio17 5 0>; + #address-cells = <1>; + #size-cells = <0>; + + st95hf@0{ + compatible = "st,st95hf"; + reg = <0>; + spi-max-frequency = <1000000>; + interrupts = <2 IRQ_TYPE_EDGE_FALLING>; + }; + }; diff --git a/Documentation/devicetree/bindings/staging/iio/adc/mxs-lradc.txt b/Documentation/devicetree/bindings/staging/iio/adc/mxs-lradc.txt index ee05dc390694..307537787574 100644 --- a/Documentation/devicetree/bindings/staging/iio/adc/mxs-lradc.txt +++ b/Documentation/devicetree/bindings/staging/iio/adc/mxs-lradc.txt @@ -12,9 +12,9 @@ Optional properties: property is not present, then the touchscreen is disabled. 5 wires is valid for i.MX28 SoC only. - fsl,ave-ctrl: number of samples per direction to calculate an average value. - Allowed value is 1 ... 31, default is 4 + Allowed value is 1 ... 32, default is 4 - fsl,ave-delay: delay between consecutive samples. Allowed value is - 1 ... 2047. It is used if 'fsl,ave-ctrl' > 1, counts at + 2 ... 2048. It is used if 'fsl,ave-ctrl' > 1, counts at 2 kHz and its default is 2 (= 1 ms) - fsl,settling: delay between plate switch to next sample. Allowed value is 1 ... 2047. It counts at 2 kHz and its default is diff --git a/Documentation/devicetree/bindings/submitting-patches.txt b/Documentation/devicetree/bindings/submitting-patches.txt index b7ba01ad1426..56742bc70218 100644 --- a/Documentation/devicetree/bindings/submitting-patches.txt +++ b/Documentation/devicetree/bindings/submitting-patches.txt @@ -15,6 +15,29 @@ I. For patch submitters 3) The Documentation/ portion of the patch should come in the series before the code implementing the binding. + 4) Any compatible strings used in a chip or board DTS file must be + previously documented in the corresponding DT binding text file + in Documentation/devicetree/bindings. This rule applies even if + the Linux device driver does not yet match on the compatible + string. [ checkpatch will emit warnings if this step is not + followed as of commit bff5da4335256513497cc8c79f9a9d1665e09864 + ("checkpatch: add DT compatible string documentation checks"). ] + + 5) The wildcard "<chip>" may be used in compatible strings, as in + the following example: + + - compatible: Must contain '"nvidia,<chip>-pcie", + "nvidia,tegra20-pcie"' where <chip> is tegra30, tegra132, ... + + As in the above example, the known values of "<chip>" should be + documented if it is used. + + 6) If a documented compatible string is not yet matched by the + driver, the documentation should also include a compatible + string that is matched by the driver (as in the "nvidia,tegra20-pcie" + example above). + + II. For kernel maintainers 1) If you aren't comfortable reviewing a given binding, reply to it and ask diff --git a/Documentation/devicetree/bindings/thermal/armada-thermal.txt b/Documentation/devicetree/bindings/thermal/armada-thermal.txt index 4cf024929a3f..4698e0edc205 100644 --- a/Documentation/devicetree/bindings/thermal/armada-thermal.txt +++ b/Documentation/devicetree/bindings/thermal/armada-thermal.txt @@ -5,17 +5,9 @@ Required properties: - compatible: Should be set to one of the following: marvell,armada370-thermal marvell,armada375-thermal - marvell,armada375-z1-thermal marvell,armada380-thermal marvell,armadaxp-thermal - Note: As the name suggests, "marvell,armada375-z1-thermal" - applies for the SoC Z1 stepping only. On such stepping - some quirks need to be done and the register offset differs - from the one in the A0 stepping. - The operating system may auto-detect the SoC stepping and - update the compatible and register offsets at runtime. - - reg: Device's register space. Two entries are expected, see the examples below. The first one is required for the sensor register; diff --git a/Documentation/devicetree/bindings/thermal/rockchip-thermal.txt b/Documentation/devicetree/bindings/thermal/rockchip-thermal.txt new file mode 100644 index 000000000000..ef802de4957a --- /dev/null +++ b/Documentation/devicetree/bindings/thermal/rockchip-thermal.txt @@ -0,0 +1,68 @@ +* Temperature Sensor ADC (TSADC) on rockchip SoCs + +Required properties: +- compatible : "rockchip,rk3288-tsadc" +- reg : physical base address of the controller and length of memory mapped + region. +- interrupts : The interrupt number to the cpu. The interrupt specifier format + depends on the interrupt controller. +- clocks : Must contain an entry for each entry in clock-names. +- clock-names : Shall be "tsadc" for the converter-clock, and "apb_pclk" for + the peripheral clock. +- resets : Must contain an entry for each entry in reset-names. + See ../reset/reset.txt for details. +- reset-names : Must include the name "tsadc-apb". +- #thermal-sensor-cells : Should be 1. See ./thermal.txt for a description. +- rockchip,hw-tshut-temp : The hardware-controlled shutdown temperature value. +- rockchip,hw-tshut-mode : The hardware-controlled shutdown mode 0:CRU 1:GPIO. +- rockchip,hw-tshut-polarity : The hardware-controlled active polarity 0:LOW + 1:HIGH. + +Exiample: +tsadc: tsadc@ff280000 { + compatible = "rockchip,rk3288-tsadc"; + reg = <0xff280000 0x100>; + interrupts = <GIC_SPI 37 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&cru SCLK_TSADC>, <&cru PCLK_TSADC>; + clock-names = "tsadc", "apb_pclk"; + resets = <&cru SRST_TSADC>; + reset-names = "tsadc-apb"; + pinctrl-names = "default"; + pinctrl-0 = <&otp_out>; + #thermal-sensor-cells = <1>; + rockchip,hw-tshut-temp = <95000>; + rockchip,hw-tshut-mode = <0>; + rockchip,hw-tshut-polarity = <0>; +}; + +Example: referring to thermal sensors: +thermal-zones { + cpu_thermal: cpu_thermal { + polling-delay-passive = <1000>; /* milliseconds */ + polling-delay = <5000>; /* milliseconds */ + + /* sensor ID */ + thermal-sensors = <&tsadc 1>; + + trips { + cpu_alert0: cpu_alert { + temperature = <70000>; /* millicelsius */ + hysteresis = <2000>; /* millicelsius */ + type = "passive"; + }; + cpu_crit: cpu_crit { + temperature = <90000>; /* millicelsius */ + hysteresis = <2000>; /* millicelsius */ + type = "critical"; + }; + }; + + cooling-maps { + map0 { + trip = <&cpu_alert0>; + cooling-device = + <&cpu0 THERMAL_NO_LIMIT THERMAL_NO_LIMIT>; + }; + }; + }; +}; diff --git a/Documentation/devicetree/bindings/thermal/tegra-soctherm.txt b/Documentation/devicetree/bindings/thermal/tegra-soctherm.txt new file mode 100644 index 000000000000..6b68cd150405 --- /dev/null +++ b/Documentation/devicetree/bindings/thermal/tegra-soctherm.txt @@ -0,0 +1,55 @@ +Tegra124 SOCTHERM thermal management system + +The SOCTHERM IP block contains thermal sensors, support for polled +or interrupt-based thermal monitoring, CPU and GPU throttling based +on temperature trip points, and handling external overcurrent +notifications. It is also used to manage emergency shutdown in an +overheating situation. + +Required properties : +- compatible : For Tegra124, must contain "nvidia,tegra124-soctherm". + For Tegra132, must contain "nvidia,tegra132-soctherm". + For Tegra210, must contain "nvidia,tegra210-soctherm". +- reg : Should contain 1 entry: + - SOCTHERM register set +- interrupts : Defines the interrupt used by SOCTHERM +- clocks : Must contain an entry for each entry in clock-names. + See ../clocks/clock-bindings.txt for details. +- clock-names : Must include the following entries: + - tsensor + - soctherm +- resets : Must contain an entry for each entry in reset-names. + See ../reset/reset.txt for details. +- reset-names : Must include the following entries: + - soctherm +- #thermal-sensor-cells : Should be 1. See ./thermal.txt for a description + of this property. See <dt-bindings/thermal/tegra124-soctherm.h> for a + list of valid values when referring to thermal sensors. + + +Example : + + soctherm@0,700e2000 { + compatible = "nvidia,tegra124-soctherm"; + reg = <0x0 0x700e2000 0x0 0x1000>; + interrupts = <GIC_SPI 48 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&tegra_car TEGRA124_CLK_TSENSOR>, + <&tegra_car TEGRA124_CLK_SOC_THERM>; + clock-names = "tsensor", "soctherm"; + resets = <&tegra_car 78>; + reset-names = "soctherm"; + + #thermal-sensor-cells = <1>; + }; + +Example: referring to thermal sensors : + + thermal-zones { + cpu { + polling-delay-passive = <1000>; + polling-delay = <1000>; + + thermal-sensors = + <&soctherm TEGRA124_SOCTHERM_SENSOR_CPU>; + }; + }; diff --git a/Documentation/devicetree/bindings/timer/digicolor-timer.txt b/Documentation/devicetree/bindings/timer/digicolor-timer.txt new file mode 100644 index 000000000000..d1b659bbc29f --- /dev/null +++ b/Documentation/devicetree/bindings/timer/digicolor-timer.txt @@ -0,0 +1,18 @@ +Conexant Digicolor SoCs Timer Controller + +Required properties: + +- compatible : should be "cnxt,cx92755-timer" +- reg : Specifies base physical address and size of the "Agent Communication" + timer registers +- interrupts : Contains 8 interrupts, one for each timer +- clocks: phandle to the main clock + +Example: + + timer@f0000fc0 { + compatible = "cnxt,cx92755-timer"; + reg = <0xf0000fc0 0x40>; + interrupts = <19>, <31>, <34>, <35>, <52>, <53>, <54>, <55>; + clocks = <&main_clk>; + }; diff --git a/Documentation/devicetree/bindings/timer/marvell,armada-370-xp-timer.txt b/Documentation/devicetree/bindings/timer/marvell,armada-370-xp-timer.txt index f455182b1086..e9c78ce880e6 100644 --- a/Documentation/devicetree/bindings/timer/marvell,armada-370-xp-timer.txt +++ b/Documentation/devicetree/bindings/timer/marvell,armada-370-xp-timer.txt @@ -2,8 +2,10 @@ Marvell Armada 370 and Armada XP Timers --------------------------------------- Required properties: -- compatible: Should be either "marvell,armada-370-timer" or - "marvell,armada-xp-timer" as appropriate. +- compatible: Should be one of the following + "marvell,armada-370-timer", + "marvell,armada-375-timer", + "marvell,armada-xp-timer". - interrupts: Should contain the list of Global Timer interrupts and then local timer interrupts - reg: Should contain location and length for timers register. First @@ -13,7 +15,8 @@ Required properties: Clocks required for compatible = "marvell,armada-370-timer": - clocks : Must contain a single entry describing the clock input -Clocks required for compatible = "marvell,armada-xp-timer": +Clocks required for compatibles = "marvell,armada-xp-timer", + "marvell,armada-375-timer": - clocks : Must contain an entry for each entry in clock-names. - clock-names : Must include the following entries: "nbclk" (L2/coherency fabric clock), diff --git a/Documentation/devicetree/bindings/timer/nvidia,tegra30-timer.txt b/Documentation/devicetree/bindings/timer/nvidia,tegra30-timer.txt index b5082a1cf461..1761f53ee36f 100644 --- a/Documentation/devicetree/bindings/timer/nvidia,tegra30-timer.txt +++ b/Documentation/devicetree/bindings/timer/nvidia,tegra30-timer.txt @@ -6,7 +6,9 @@ trigger a legacy watchdog reset. Required properties: -- compatible : should be "nvidia,tegra30-timer", "nvidia,tegra20-timer". +- compatible : For Tegra30, must contain "nvidia,tegra30-timer". Otherwise, + must contain '"nvidia,<chip>-timer", "nvidia,tegra30-timer"' where + <chip> is tegra124 or tegra132. - reg : Specifies base physical address and size of the registers. - interrupts : A list of 6 interrupts; one per each of timer channels 1 through 5, and one for the shared interrupt for the remaining channels. diff --git a/Documentation/devicetree/bindings/timer/renesas,mtu2.txt b/Documentation/devicetree/bindings/timer/renesas,mtu2.txt index d9a8d5af1a21..ba0a34d97eb8 100644 --- a/Documentation/devicetree/bindings/timer/renesas,mtu2.txt +++ b/Documentation/devicetree/bindings/timer/renesas,mtu2.txt @@ -1,4 +1,4 @@ -* Renesas R-Car Multi-Function Timer Pulse Unit 2 (MTU2) +* Renesas Multi-Function Timer Pulse Unit 2 (MTU2) The MTU2 is a multi-purpose, multi-channel timer/counter with configurable clock inputs and programmable compare match. diff --git a/Documentation/devicetree/bindings/timer/renesas,tmu.txt b/Documentation/devicetree/bindings/timer/renesas,tmu.txt index 7db89fb25444..cd5f20bf2582 100644 --- a/Documentation/devicetree/bindings/timer/renesas,tmu.txt +++ b/Documentation/devicetree/bindings/timer/renesas,tmu.txt @@ -1,4 +1,4 @@ -* Renesas R-Car Timer Unit (TMU) +* Renesas R-Mobile/R-Car Timer Unit (TMU) The TMU is a 32-bit timer/counter with configurable clock inputs and programmable compare match. @@ -9,6 +9,8 @@ are independent. The TMU hardware supports up to three channels. Required Properties: - compatible: must contain one or more of the following: + - "renesas,tmu-r8a7740" for the r8a7740 TMU + - "renesas,tmu-r8a7778" for the r8a7778 TMU - "renesas,tmu-r8a7779" for the r8a7779 TMU - "renesas,tmu" for any TMU. This is a fallback for the above renesas,tmu-* entries diff --git a/Documentation/devicetree/bindings/timer/rockchip,rk3288-timer.txt b/Documentation/devicetree/bindings/timer/rockchip,rk3288-timer.txt new file mode 100644 index 000000000000..87f0b0042bae --- /dev/null +++ b/Documentation/devicetree/bindings/timer/rockchip,rk3288-timer.txt @@ -0,0 +1,18 @@ +Rockchip rk3288 timer + +Required properties: +- compatible: shall be "rockchip,rk3288-timer" +- reg: base address of the timer register starting with TIMERS CONTROL register +- interrupts: should contain the interrupts for Timer0 +- clocks : must contain an entry for each entry in clock-names +- clock-names : must include the following entries: + "timer", "pclk" + +Example: + timer: timer@ff810000 { + compatible = "rockchip,rk3288-timer"; + reg = <0xff810000 0x20>; + interrupts = <GIC_SPI 72 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&xin24m>, <&cru PCLK_TIMER>; + clock-names = "timer", "pclk"; + }; diff --git a/Documentation/devicetree/bindings/unittest.txt b/Documentation/devicetree/bindings/unittest.txt new file mode 100644 index 000000000000..8933211f32f9 --- /dev/null +++ b/Documentation/devicetree/bindings/unittest.txt @@ -0,0 +1,71 @@ +1) OF selftest platform device + +** selftest + +Required properties: +- compatible: must be "selftest" + +All other properties are optional. + +Example: + selftest { + compatible = "selftest"; + status = "okay"; + }; + +2) OF selftest i2c adapter platform device + +** platform device unittest adapter + +Required properties: +- compatible: must be selftest-i2c-bus + +Children nodes contain selftest i2c devices. + +Example: + selftest-i2c-bus { + compatible = "selftest-i2c-bus"; + status = "okay"; + }; + +3) OF selftest i2c device + +** I2C selftest device + +Required properties: +- compatible: must be selftest-i2c-dev + +All other properties are optional + +Example: + selftest-i2c-dev { + compatible = "selftest-i2c-dev"; + status = "okay"; + }; + +4) OF selftest i2c mux device + +** I2C selftest mux + +Required properties: +- compatible: must be selftest-i2c-mux + +Children nodes contain selftest i2c bus nodes per channel. + +Example: + selftest-i2c-mux { + compatible = "selftest-i2c-mux"; + status = "okay"; + #address-cells = <1>; + #size-cells = <0>; + channel-0 { + reg = <0>; + #address-cells = <1>; + #size-cells = <0>; + i2c-dev { + reg = <8>; + compatible = "selftest-i2c-dev"; + status = "okay"; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/usb/atmel-usb.txt b/Documentation/devicetree/bindings/usb/atmel-usb.txt index bc2222ca3f2a..e180d56c75db 100644 --- a/Documentation/devicetree/bindings/usb/atmel-usb.txt +++ b/Documentation/devicetree/bindings/usb/atmel-usb.txt @@ -33,9 +33,17 @@ usb1: ehci@00800000 { AT91 USB device controller Required properties: - - compatible: Should be "atmel,at91rm9200-udc" + - compatible: Should be one of the following + "atmel,at91rm9200-udc" + "atmel,at91sam9260-udc" + "atmel,at91sam9261-udc" + "atmel,at91sam9263-udc" - reg: Address and length of the register set for the device - interrupts: Should contain macb interrupt + - clocks: Should reference the peripheral and the AHB clocks + - clock-names: Should contains two strings + "pclk" for the peripheral clock + "hclk" for the AHB clock Optional properties: - atmel,vbus-gpio: If present, specifies a gpio that needs to be @@ -51,7 +59,10 @@ usb1: gadget@fffa4000 { Atmel High-Speed USB device controller Required properties: - - compatible: Should be "atmel,at91sam9rl-udc" + - compatible: Should be one of the following + "at91sam9rl-udc" + "at91sam9g45-udc" + "sama5d3-udc" - reg: Address and length of the register set for the device - interrupts: Should contain usba interrupt - ep childnode: To specify the number of endpoints and their properties. diff --git a/Documentation/devicetree/bindings/usb/ci-hdrc-usb2.txt b/Documentation/devicetree/bindings/usb/ci-hdrc-usb2.txt new file mode 100644 index 000000000000..27f8b1e5ee46 --- /dev/null +++ b/Documentation/devicetree/bindings/usb/ci-hdrc-usb2.txt @@ -0,0 +1,24 @@ +* USB2 ChipIdea USB controller for ci13xxx + +Required properties: +- compatible: should be "chipidea,usb2" +- reg: base address and length of the registers +- interrupts: interrupt for the USB controller + +Optional properties: +- clocks: reference to the USB clock +- phys: reference to the USB PHY +- phy-names: should be "usb-phy" +- vbus-supply: reference to the VBUS regulator + +Example: + + usb@f7ed0000 { + compatible = "chipidea,usb2"; + reg = <0xf7ed0000 0x10000>; + interrupts = <GIC_SPI 11 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&chip CLKID_USB0>; + phys = <&usb_phy0>; + phy-names = "usb-phy"; + vbus-supply = <®_usb0_vbus>; + }; diff --git a/Documentation/devicetree/bindings/usb/dwc2.txt b/Documentation/devicetree/bindings/usb/dwc2.txt index 482f815363ef..fd132cbee70e 100644 --- a/Documentation/devicetree/bindings/usb/dwc2.txt +++ b/Documentation/devicetree/bindings/usb/dwc2.txt @@ -20,6 +20,10 @@ Optional properties: Refer to phy/phy-bindings.txt for generic phy consumer properties - dr_mode: shall be one of "host", "peripheral" and "otg" Refer to usb/generic.txt +- g-use-dma: enable dma usage in gadget driver. +- g-rx-fifo-size: size of rx fifo size in gadget mode. +- g-np-tx-fifo-size: size of non-periodic tx fifo size in gadget mode. +- g-tx-fifo-size: size of periodic tx fifo per endpoint (except ep0) in gadget mode. Example: diff --git a/Documentation/devicetree/bindings/usb/dwc3.txt b/Documentation/devicetree/bindings/usb/dwc3.txt index 471366d6a129..cd7f0454e13a 100644 --- a/Documentation/devicetree/bindings/usb/dwc3.txt +++ b/Documentation/devicetree/bindings/usb/dwc3.txt @@ -14,6 +14,29 @@ Optional properties: - phys: from the *Generic PHY* bindings - phy-names: from the *Generic PHY* bindings - tx-fifo-resize: determines if the FIFO *has* to be reallocated. + - snps,disable_scramble_quirk: true when SW should disable data scrambling. + Only really useful for FPGA builds. + - snps,has-lpm-erratum: true when DWC3 was configured with LPM Erratum enabled + - snps,lpm-nyet-threshold: LPM NYET threshold + - snps,u2exit_lfps_quirk: set if we want to enable u2exit lfps quirk + - snps,u2ss_inp3_quirk: set if we enable P3 OK for U2/SS Inactive quirk + - snps,req_p1p2p3_quirk: when set, the core will always request for + P1/P2/P3 transition sequence. + - snps,del_p1p2p3_quirk: when set core will delay P1/P2/P3 until a certain + amount of 8B10B errors occur. + - snps,del_phy_power_chg_quirk: when set core will delay PHY power change + from P0 to P1/P2/P3. + - snps,lfps_filter_quirk: when set core will filter LFPS reception. + - snps,rx_detect_poll_quirk: when set core will disable a 400us delay to start + Polling LFPS after RX.Detect. + - snps,tx_de_emphasis_quirk: when set core will set Tx de-emphasis value. + - snps,tx_de_emphasis: the value driven to the PHY is controlled by the + LTSSM during USB3 Compliance mode. + - snps,dis_u3_susphy_quirk: when set core will disable USB3 suspend phy. + - snps,dis_u2_susphy_quirk: when set core will disable USB2 suspend phy. + - snps,is-utmi-l1-suspend: true when DWC3 asserts output signal + utmi_l1_suspend_n, false when asserts utmi_sleep_n + - snps,hird-threshold: HIRD threshold This is usually a subnode to DWC3 glue to which it is connected. diff --git a/Documentation/devicetree/bindings/usb/exynos-usb.txt b/Documentation/devicetree/bindings/usb/exynos-usb.txt index a3b5990d0f2c..9b4dbe3b2acc 100644 --- a/Documentation/devicetree/bindings/usb/exynos-usb.txt +++ b/Documentation/devicetree/bindings/usb/exynos-usb.txt @@ -82,8 +82,10 @@ Example: DWC3 Required properties: - - compatible: should be "samsung,exynos5250-dwusb3" for USB 3.0 DWC3 - controller. + - compatible: should be one of the following - + "samsung,exynos5250-dwusb3": for USB 3.0 DWC3 controller on + Exynos5250/5420. + "samsung,exynos7-dwusb3": for USB 3.0 DWC3 controller on Exynos7. - #address-cells, #size-cells : should be '1' if the device has sub-nodes with 'reg' property. - ranges: allows valid 1:1 translation between child's address space and diff --git a/Documentation/devicetree/bindings/usb/nvidia,tegra20-ehci.txt b/Documentation/devicetree/bindings/usb/nvidia,tegra20-ehci.txt index 3dc9140e3dfb..f60785f73d3d 100644 --- a/Documentation/devicetree/bindings/usb/nvidia,tegra20-ehci.txt +++ b/Documentation/devicetree/bindings/usb/nvidia,tegra20-ehci.txt @@ -6,7 +6,10 @@ Practice : Universal Serial Bus" with the following modifications and additions : Required properties : - - compatible : Should be "nvidia,tegra20-ehci". + - compatible : For Tegra20, must contain "nvidia,tegra20-ehci". + For Tegra30, must contain "nvidia,tegra30-ehci". Otherwise, must contain + "nvidia,<chip>-ehci" plus at least one of the above, where <chip> is + tegra114, tegra124, tegra132, or tegra210. - nvidia,phy : phandle of the PHY that the controller is connected to. - clocks : Must contain one entry, for the module clock. See ../clocks/clock-bindings.txt for details. diff --git a/Documentation/devicetree/bindings/usb/nvidia,tegra20-usb-phy.txt b/Documentation/devicetree/bindings/usb/nvidia,tegra20-usb-phy.txt index c9205fbf26e2..a9aa79fb90ed 100644 --- a/Documentation/devicetree/bindings/usb/nvidia,tegra20-usb-phy.txt +++ b/Documentation/devicetree/bindings/usb/nvidia,tegra20-usb-phy.txt @@ -3,7 +3,10 @@ Tegra SOC USB PHY The device node for Tegra SOC USB PHY: Required properties : - - compatible : Should be "nvidia,tegra<chip>-usb-phy". + - compatible : For Tegra20, must contain "nvidia,tegra20-usb-phy". + For Tegra30, must contain "nvidia,tegra30-usb-phy". Otherwise, must contain + "nvidia,<chip>-usb-phy" plus at least one of the above, where <chip> is + tegra114, tegra124, tegra132, or tegra210. - reg : Defines the following set of registers, in the order listed: - The PHY's own register set. Always present. diff --git a/Documentation/devicetree/bindings/usb/pxa-usb.txt b/Documentation/devicetree/bindings/usb/pxa-usb.txt index 79729a948d5a..9c331799b87c 100644 --- a/Documentation/devicetree/bindings/usb/pxa-usb.txt +++ b/Documentation/devicetree/bindings/usb/pxa-usb.txt @@ -29,3 +29,25 @@ Example: marvell,port-mode = <2>; /* PMM_GLOBAL_MODE */ }; +UDC + +Required properties: + - compatible: Should be "marvell,pxa270-udc" for USB controllers + used in device mode. + - reg: usb device MMIO address space + - interrupts: single interrupt generated by the UDC IP + - clocks: input clock of the UDC IP (see clock-bindings.txt) + +Optional properties: + - gpios: + - gpio activated to control the USB D+ pullup (see gpio.txt) + +Example: + + pxa27x_udc: udc@40600000 { + compatible = "marvell,pxa270-udc"; + reg = <0x40600000 0x10000>; + interrupts = <11>; + clocks = <&pxa2xx_clks 11>; + gpios = <&gpio 22 GPIO_ACTIVE_LOW>; + }; diff --git a/Documentation/devicetree/bindings/usb/renesas_usbhs.txt b/Documentation/devicetree/bindings/usb/renesas_usbhs.txt index b08c903f8668..61b045b6d50e 100644 --- a/Documentation/devicetree/bindings/usb/renesas_usbhs.txt +++ b/Documentation/devicetree/bindings/usb/renesas_usbhs.txt @@ -14,6 +14,8 @@ Optional properties: function should be enabled - phys: phandle + phy specifier pair - phy-names: must be "usb" + - dmas: Must contain a list of references to DMA specifiers. + - dma-names : Must contain a list of DMA names, "tx" or "rx". Example: usbhs: usb@e6590000 { diff --git a/Documentation/devicetree/bindings/usb/usb-ehci.txt b/Documentation/devicetree/bindings/usb/usb-ehci.txt index 43c1a4e06767..0b04fdff9d5a 100644 --- a/Documentation/devicetree/bindings/usb/usb-ehci.txt +++ b/Documentation/devicetree/bindings/usb/usb-ehci.txt @@ -12,6 +12,7 @@ Optional properties: - big-endian-regs : boolean, set this for hcds with big-endian registers - big-endian-desc : boolean, set this for hcds with big-endian descriptors - big-endian : boolean, for hcds with big-endian-regs + big-endian-desc + - needs-reset-on-resume : boolean, set this to force EHCI reset after resume - clocks : a list of phandle + clock specifier pairs - phys : phandle + phy specifier pair - phy-names : "usb" diff --git a/Documentation/devicetree/bindings/usb/usb-nop-xceiv.txt b/Documentation/devicetree/bindings/usb/usb-nop-xceiv.txt index 1bd37faba05b..5be01c859b7a 100644 --- a/Documentation/devicetree/bindings/usb/usb-nop-xceiv.txt +++ b/Documentation/devicetree/bindings/usb/usb-nop-xceiv.txt @@ -13,10 +13,15 @@ Optional properties: - clock-frequency: the clock frequency (in Hz) that the PHY clock must be configured to. -- vcc-supply: phandle to the regulator that provides RESET to the PHY. +- vcc-supply: phandle to the regulator that provides power to the PHY. - reset-gpios: Should specify the GPIO for reset. +- vbus-detect-gpio: should specify the GPIO detecting a VBus insertion + (see Documentation/devicetree/bindings/gpio/gpio.txt) +- vbus-regulator : should specifiy the regulator supplying current drawn from + the VBus line (see Documentation/devicetree/bindings/regulator/regulator.txt). + Example: hsusb1_phy { @@ -26,8 +31,11 @@ Example: clock-names = "main_clk"; vcc-supply = <&hsusb1_vcc_regulator>; reset-gpios = <&gpio1 7 GPIO_ACTIVE_LOW>; + vbus-detect-gpio = <&gpio2 13 GPIO_ACTIVE_HIGH>; + vbus-regulator = <&vbus_regulator>; }; hsusb1_phy is a NOP USB PHY device that gets its clock from an oscillator and expects that clock to be configured to 19.2MHz by the NOP PHY driver. hsusb1_vcc_regulator provides power to the PHY and GPIO 7 controls RESET. +GPIO 13 detects VBus insertion, and accordingly notifies the vbus-regulator. diff --git a/Documentation/devicetree/bindings/usb/usb-ohci.txt b/Documentation/devicetree/bindings/usb/usb-ohci.txt index b968a1aea995..19233b7365e1 100644 --- a/Documentation/devicetree/bindings/usb/usb-ohci.txt +++ b/Documentation/devicetree/bindings/usb/usb-ohci.txt @@ -9,6 +9,8 @@ Optional properties: - big-endian-regs : boolean, set this for hcds with big-endian registers - big-endian-desc : boolean, set this for hcds with big-endian descriptors - big-endian : boolean, for hcds with big-endian-regs + big-endian-desc +- no-big-frame-no : boolean, set if frame_no lives in bits [15:0] of HCCA +- num-ports : u32, to override the detected port count - clocks : a list of phandle + clock specifier pairs - phys : phandle + phy specifier pair - phy-names : "usb" diff --git a/Documentation/devicetree/bindings/vendor-prefixes.txt b/Documentation/devicetree/bindings/vendor-prefixes.txt index a344ec2713a5..389ca1347a77 100644 --- a/Documentation/devicetree/bindings/vendor-prefixes.txt +++ b/Documentation/devicetree/bindings/vendor-prefixes.txt @@ -4,13 +4,15 @@ This isn't an exhaustive list, but you should add new prefixes to it before using them to avoid name-space collisions. abilis Abilis Systems +abcn Abracon Corporation active-semi Active-Semi International Inc ad Avionic Design GmbH adapteva Adapteva, Inc. +adh AD Holdings Plc. adi Analog Devices, Inc. aeroflexgaisler Aeroflex Gaisler AB -ak Asahi Kasei Corp. allwinner Allwinner Technology Co., Ltd. +alphascale AlphaScale Integrated Circuits Systems, Inc. altr Altera Corp. amcc Applied Micro Circuits Corporation (APM, formally AMCC) amd Advanced Micro Devices (AMD), Inc. @@ -20,9 +22,11 @@ amstaos AMS-Taos Inc. apm Applied Micro Circuits Corporation (APM) arm ARM Ltd. armadeus ARMadeus Systems SARL +asahi-kasei Asahi Kasei Corp. atmel Atmel Corporation auo AU Optronics Corporation avago Avago Technologies +avic Shanghai AVIC Optoelectronics Co., Ltd. bosch Bosch Sensortec GmbH brcm Broadcom Corporation buffalo Buffalo, Inc. @@ -31,42 +35,55 @@ capella Capella Microsystems, Inc cavium Cavium, Inc. cdns Cadence Design Systems Inc. chipidea Chipidea, Inc +chipspark ChipSPARK chrp Common Hardware Reference Platform chunghwa Chunghwa Picture Tubes Ltd. cirrus Cirrus Logic, Inc. +cloudengines Cloud Engines, Inc. cnm Chips&Media, Inc. +cnxt Conexant Systems, Inc. cortina Cortina Systems, Inc. +cosmic Cosmic Circuits crystalfontz Crystalfontz America, Inc. dallas Maxim Integrated Products (formerly Dallas Semiconductor) davicom DAVICOM Semiconductor, Inc. denx Denx Software Engineering digi Digi International Inc. +digilent Diglent, Inc. dlg Dialog Semiconductor dlink D-Link Corporation dmo Data Modul AG ebv EBV Elektronik edt Emerging Display Technologies +elan Elan Microelectronic Corp. emmicro EM Microelectronic energymicro Silicon Laboratories (formerly Energy Micro AS) epcos EPCOS AG epfl Ecole Polytechnique Fédérale de Lausanne epson Seiko Epson Corp. est ESTeem Wireless Modems +ettus NI Ettus Research eukrea Eukréa Electromatique everest Everest Semiconductor Co. Ltd. +everspin Everspin Technologies, Inc. excito Excito fcs Fairchild Semiconductor +firefly Firefly fsl Freescale Semiconductor GEFanuc GE Fanuc Intelligent Platforms Embedded Systems, Inc. gef GE Fanuc Intelligent Platforms Embedded Systems, Inc. geniatech Geniatech, Inc. +giantplus Giantplus Technology Co., Ltd. globalscale Globalscale Technologies, Inc. gmt Global Mixed-mode Technology, Inc. google Google, Inc. gumstix Gumstix, Inc. gw Gateworks Corporation +hannstar HannStar Display Corporation haoyu Haoyu Microelectronic Co. Ltd. +himax Himax Technologies, Inc. hisilicon Hisilicon Limited. +hit Hitachi Ltd. honeywell Honeywell hp Hewlett Packard i2se I2SE GmbH @@ -78,7 +95,7 @@ innolux Innolux Corporation intel Intel Corporation intercontrol Inter Control Group isee ISEE 2007 S.L. -isl Intersil +isil Intersil karo Ka-Ro electronics GmbH keymile Keymile GmbH lacie LaCie @@ -91,6 +108,7 @@ lltc Linear Technology Corporation marvell Marvell Technology Group Ltd. maxim Maxim Integrated Products mediatek MediaTek Inc. +merrii Merrii Technology Co., Ltd. micrel Micrel Inc. microchip Microchip Technology Inc. micron Micron Technology Inc. @@ -98,6 +116,7 @@ mitsubishi Mitsubishi Electric Corporation mosaixtech Mosaix Technologies, Inc. moxa Moxa mpl MPL AG +mti Imagination Technologies Ltd. (formerly MIPS Technologies Inc.) mundoreader Mundo Reader S.L. murata Murata Manufacturing Co., Ltd. mxicy Macronix International Co., Ltd. @@ -111,7 +130,10 @@ nvidia NVIDIA nxp NXP Semiconductors onnn ON Semiconductor Corp. opencores OpenCores.org +ovti OmniVision Technologies panasonic Panasonic Corporation +parade Parade Technologies Inc. +pericom Pericom Technology Inc. phytec PHYTEC Messtechnik GmbH picochip Picochip Ltd plathome Plat'Home Co., Ltd. @@ -119,6 +141,7 @@ pixcir PIXCIR MICROELECTRONICS Co., Ltd powervr PowerVR (deprecated, use img) qca Qualcomm Atheros, Inc. qcom Qualcomm Technologies, Inc +qemu QEMU, a generic and open source machine emulator and virtualizer qnap QNAP Systems, Inc. radxa Radxa raidsonic RaidSonic Technology GmbH @@ -133,8 +156,10 @@ sandisk Sandisk Corporation sbs Smart Battery System schindler Schindler seagate Seagate Technology PLC +semtech Semtech Corporation sil Silicon Image silabs Silicon Laboratories +siliconmitus Silicon Mitus, Inc. simtek sii Seiko Instruments, Inc. silergy Silergy Corp. @@ -145,20 +170,24 @@ snps Synopsys, Inc. solidrun SolidRun sony Sony Corporation spansion Spansion Inc. +sprd Spreadtrum Communications Inc. st STMicroelectronics ste ST-Ericsson stericsson ST-Ericsson synology Synology, Inc. +tbs TBS Technologies thine THine Electronics, Inc. ti Texas Instruments tlm Trusted Logic Mobility toradex Toradex AG toshiba Toshiba Corporation toumaz Toumaz +truly Truly Semiconductors Limited usi Universal Scientific Industrial Co., Ltd. v3 V3 Semiconductor variscite Variscite Ltd. via VIA Technologies, Inc. +virtio Virtual I/O Device Specification, developed by the OASIS consortium voipac Voipac Technologies s.r.o. winbond Winbond Electronics corp. wlf Wolfson Microelectronics diff --git a/Documentation/devicetree/bindings/video/adi,adv7511.txt b/Documentation/devicetree/bindings/video/adi,adv7511.txt new file mode 100644 index 000000000000..96c25ee01501 --- /dev/null +++ b/Documentation/devicetree/bindings/video/adi,adv7511.txt @@ -0,0 +1,88 @@ +Analog Device ADV7511(W)/13 HDMI Encoders +----------------------------------------- + +The ADV7511, ADV7511W and ADV7513 are HDMI audio and video transmitters +compatible with HDMI 1.4 and DVI 1.0. They support color space conversion, +S/PDIF, CEC and HDCP. + +Required properties: + +- compatible: Should be one of "adi,adv7511", "adi,adv7511w" or "adi,adv7513" +- reg: I2C slave address + +The ADV7511 supports a large number of input data formats that differ by their +color depth, color format, clock mode, bit justification and random +arrangement of components on the data bus. The combination of the following +properties describe the input and map directly to the video input tables of the +ADV7511 datasheet that document all the supported combinations. + +- adi,input-depth: Number of bits per color component at the input (8, 10 or + 12). +- adi,input-colorspace: The input color space, one of "rgb", "yuv422" or + "yuv444". +- adi,input-clock: The input clock type, one of "1x" (one clock cycle per + pixel), "2x" (two clock cycles per pixel), "ddr" (one clock cycle per pixel, + data driven on both edges). + +The following input format properties are required except in "rgb 1x" and +"yuv444 1x" modes, in which case they must not be specified. + +- adi,input-style: The input components arrangement variant (1, 2 or 3), as + listed in the input format tables in the datasheet. +- adi,input-justification: The input bit justification ("left", "evenly", + "right"). + +Optional properties: + +- interrupts: Specifier for the ADV7511 interrupt +- pd-gpios: Specifier for the GPIO connected to the power down signal + +- adi,clock-delay: Video data clock delay relative to the pixel clock, in ps + (-1200 ps .. 1600 ps). Defaults to no delay. +- adi,embedded-sync: The input uses synchronization signals embedded in the + data stream (similar to BT.656). Defaults to separate H/V synchronization + signals. + +Required nodes: + +The ADV7511 has two video ports. Their connections are modelled using the OF +graph bindings specified in Documentation/devicetree/bindings/graph.txt. + +- Video port 0 for the RGB or YUV input +- Video port 1 for the HDMI output + + +Example +------- + + adv7511w: hdmi@39 { + compatible = "adi,adv7511w"; + reg = <39>; + interrupt-parent = <&gpio3>; + interrupts = <29 IRQ_TYPE_EDGE_FALLING>; + + adi,input-depth = <8>; + adi,input-colorspace = "rgb"; + adi,input-clock = "1x"; + adi,input-style = <1>; + adi,input-justification = "evenly"; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + reg = <0>; + adv7511w_in: endpoint { + remote-endpoint = <&dpi_out>; + }; + }; + + port@1 { + reg = <1>; + adv7511_out: endpoint { + remote-endpoint = <&hdmi_connector_in>; + }; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/video/backlight/lp855x.txt b/Documentation/devicetree/bindings/video/backlight/lp855x.txt index 96e83a56048e..0a3ecbc3a1b9 100644 --- a/Documentation/devicetree/bindings/video/backlight/lp855x.txt +++ b/Documentation/devicetree/bindings/video/backlight/lp855x.txt @@ -12,6 +12,7 @@ Optional properties: - pwm-period: PWM period value. Set only PWM input mode used (u32) - rom-addr: Register address of ROM area to be updated (u8) - rom-val: Register value to be updated (u8) + - power-supply: Regulator which controls the 3V rail Example: @@ -56,6 +57,7 @@ Example: backlight@2c { compatible = "ti,lp8557"; reg = <0x2c>; + power-supply = <&backlight_vdd>; dev-ctrl = /bits/ 8 <0x41>; init-brt = /bits/ 8 <0x0a>; diff --git a/Documentation/devicetree/bindings/video/bridge/ps8622.txt b/Documentation/devicetree/bindings/video/bridge/ps8622.txt new file mode 100644 index 000000000000..c989c3807f2b --- /dev/null +++ b/Documentation/devicetree/bindings/video/bridge/ps8622.txt @@ -0,0 +1,31 @@ +ps8622-bridge bindings + +Required properties: + - compatible: "parade,ps8622" or "parade,ps8625" + - reg: first i2c address of the bridge + - sleep-gpios: OF device-tree gpio specification for PD_ pin. + - reset-gpios: OF device-tree gpio specification for RST_ pin. + +Optional properties: + - lane-count: number of DP lanes to use + - use-external-pwm: backlight will be controlled by an external PWM + - video interfaces: Device node can contain video interface port + nodes for panel according to [1]. + +[1]: Documentation/devicetree/bindings/media/video-interfaces.txt + +Example: + lvds-bridge@48 { + compatible = "parade,ps8622"; + reg = <0x48>; + sleep-gpios = <&gpc3 6 1 0 0>; + reset-gpios = <&gpc3 1 1 0 0>; + lane-count = <1>; + ports { + port@0 { + bridge_out: endpoint { + remote-endpoint = <&panel_in>; + }; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/drm/bridge/ptn3460.txt b/Documentation/devicetree/bindings/video/bridge/ptn3460.txt index 52b93b2c6748..361971ba104d 100644 --- a/Documentation/devicetree/bindings/drm/bridge/ptn3460.txt +++ b/Documentation/devicetree/bindings/video/bridge/ptn3460.txt @@ -3,8 +3,8 @@ ptn3460 bridge bindings Required properties: - compatible: "nxp,ptn3460" - reg: i2c address of the bridge - - powerdown-gpio: OF device-tree gpio specification - - reset-gpio: OF device-tree gpio specification + - powerdown-gpio: OF device-tree gpio specification for PD_N pin. + - reset-gpio: OF device-tree gpio specification for RST_N pin. - edid-emulation: The EDID emulation entry to use +-------+------------+------------------+ | Value | Resolution | Description | @@ -17,6 +17,11 @@ Required properties: | 6 | 1600x900 | ChiMei M215HGE | +-------+------------+------------------+ + - video interfaces: Device node can contain video interface port + nodes for panel according to [1]. + +[1]: Documentation/devicetree/bindings/media/video-interfaces.txt + Example: lvds-bridge@20 { compatible = "nxp,ptn3460"; @@ -24,4 +29,11 @@ Example: powerdown-gpio = <&gpy2 5 1 0 0>; reset-gpio = <&gpx1 5 1 0 0>; edid-emulation = <5>; + ports { + port@0 { + bridge_out: endpoint { + remote-endpoint = <&panel_in>; + }; + }; + }; }; diff --git a/Documentation/devicetree/bindings/video/dw_hdmi-rockchip.txt b/Documentation/devicetree/bindings/video/dw_hdmi-rockchip.txt new file mode 100644 index 000000000000..668091f27674 --- /dev/null +++ b/Documentation/devicetree/bindings/video/dw_hdmi-rockchip.txt @@ -0,0 +1,46 @@ +Rockchip specific extensions to the Synopsys Designware HDMI +================================ + +Required properties: +- compatible: "rockchip,rk3288-dw-hdmi"; +- reg: Physical base address and length of the controller's registers. +- clocks: phandle to hdmi iahb and isfr clocks. +- clock-names: should be "iahb" "isfr" +- rockchip,grf: this soc should set GRF regs to mux vopl/vopb. +- interrupts: HDMI interrupt number +- ports: contain a port node with endpoint definitions as defined in + Documentation/devicetree/bindings/media/video-interfaces.txt. For + vopb,set the reg = <0> and set the reg = <1> for vopl. +- reg-io-width: the width of the reg:1,4, the value should be 4 on + rk3288 platform + +Optional properties +- ddc-i2c-bus: phandle of an I2C controller used for DDC EDID probing +- clocks, clock-names: phandle to the HDMI CEC clock, name should be "cec" + +Example: +hdmi: hdmi@ff980000 { + compatible = "rockchip,rk3288-dw-hdmi"; + reg = <0xff980000 0x20000>; + reg-io-width = <4>; + ddc-i2c-bus = <&i2c5>; + rockchip,grf = <&grf>; + interrupts = <GIC_SPI 103 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&cru PCLK_HDMI_CTRL>, <&cru SCLK_HDMI_HDCP>; + clock-names = "iahb", "isfr"; + status = "disabled"; + ports { + hdmi_in: port { + #address-cells = <1>; + #size-cells = <0>; + hdmi_in_vopb: endpoint@0 { + reg = <0>; + remote-endpoint = <&vopb_out_hdmi>; + }; + hdmi_in_vopl: endpoint@1 { + reg = <1>; + remote-endpoint = <&vopl_out_hdmi>; + }; + }; + }; +}; diff --git a/Documentation/devicetree/bindings/video/exynos7-decon.txt b/Documentation/devicetree/bindings/video/exynos7-decon.txt new file mode 100644 index 000000000000..f5f9c8d4a55a --- /dev/null +++ b/Documentation/devicetree/bindings/video/exynos7-decon.txt @@ -0,0 +1,68 @@ +Device-Tree bindings for Samsung Exynos7 SoC display controller (DECON) + +DECON (Display and Enhancement Controller) is the Display Controller for the +Exynos7 series of SoCs which transfers the image data from a video memory +buffer to an external LCD interface. + +Required properties: +- compatible: value should be "samsung,exynos7-decon"; + +- reg: physical base address and length of the DECON registers set. + +- interrupt-parent: should be the phandle of the decon controller's + parent interrupt controller. + +- interrupts: should contain a list of all DECON IP block interrupts in the + order: FIFO Level, VSYNC, LCD_SYSTEM. The interrupt specifier + format depends on the interrupt controller used. + +- interrupt-names: should contain the interrupt names: "fifo", "vsync", + "lcd_sys", in the same order as they were listed in the interrupts + property. + +- pinctrl-0: pin control group to be used for this controller. + +- pinctrl-names: must contain a "default" entry. + +- clocks: must include clock specifiers corresponding to entries in the + clock-names property. + +- clock-names: list of clock names sorted in the same order as the clocks + property. Must contain "pclk_decon0", "aclk_decon0", + "decon0_eclk", "decon0_vclk". +- i80-if-timings: timing configuration for lcd i80 interface support. + +Optional Properties: +- samsung,power-domain: a phandle to DECON power domain node. +- display-timings: timing settings for DECON, as described in document [1]. + Can be used in case timings cannot be provided otherwise + or to override timings provided by the panel. + +[1]: Documentation/devicetree/bindings/video/display-timing.txt + +Example: + +SoC specific DT entry: + + decon@13930000 { + compatible = "samsung,exynos7-decon"; + interrupt-parent = <&combiner>; + reg = <0x13930000 0x1000>; + interrupt-names = "lcd_sys", "vsync", "fifo"; + interrupts = <0 188 0>, <0 189 0>, <0 190 0>; + clocks = <&clock_disp PCLK_DECON_INT>, + <&clock_disp ACLK_DECON_INT>, + <&clock_disp SCLK_DECON_INT_ECLK>, + <&clock_disp SCLK_DECON_INT_EXTCLKPLL>; + clock-names = "pclk_decon0", "aclk_decon0", "decon0_eclk", + "decon0_vclk"; + status = "disabled"; + }; + +Board specific DT entry: + + decon@13930000 { + pinctrl-0 = <&lcd_clk &pwm1_out>; + pinctrl-names = "default"; + status = "okay"; + }; diff --git a/Documentation/devicetree/bindings/video/exynos_dp.txt b/Documentation/devicetree/bindings/video/exynos_dp.txt index 53dbccfa80ca..7a3a9cdb86ab 100644 --- a/Documentation/devicetree/bindings/video/exynos_dp.txt +++ b/Documentation/devicetree/bindings/video/exynos_dp.txt @@ -66,6 +66,10 @@ Optional properties for dp-controller: Hotplug detect GPIO. Indicates which GPIO should be used for hotplug detection + -video interfaces: Device node can contain video interface port + nodes according to [1]. + +[1]: Documentation/devicetree/bindings/media/video-interfaces.txt Example: @@ -105,4 +109,12 @@ Board Specific portion: vsync-len = <6>; }; }; + + ports { + port@0 { + dp_out: endpoint { + remote-endpoint = <&bridge_in>; + }; + }; + }; }; diff --git a/Documentation/devicetree/bindings/video/exynos_dsim.txt b/Documentation/devicetree/bindings/video/exynos_dsim.txt index e74243b4b317..802aa7ef64e5 100644 --- a/Documentation/devicetree/bindings/video/exynos_dsim.txt +++ b/Documentation/devicetree/bindings/video/exynos_dsim.txt @@ -4,6 +4,7 @@ Required properties: - compatible: value should be one of the following "samsung,exynos3250-mipi-dsi" /* for Exynos3250/3472 SoCs */ "samsung,exynos4210-mipi-dsi" /* for Exynos4 SoCs */ + "samsung,exynos4415-mipi-dsi" /* for Exynos4415 SoC */ "samsung,exynos5410-mipi-dsi" /* for Exynos5410/5420/5440 SoCs */ - reg: physical base address and length of the registers set for the device - interrupts: should contain DSI interrupt @@ -20,7 +21,7 @@ Required properties: according to DSI host bindings (see MIPI DSI bindings [1]) Optional properties: - - samsung,power-domain: a phandle to DSIM power domain node + - power-domains: a phandle to DSIM power domain node Child nodes: Should contain DSI peripheral nodes (see MIPI DSI bindings [1]). @@ -52,7 +53,7 @@ Example: phy-names = "dsim"; vddcore-supply = <&vusb_reg>; vddio-supply = <&vmipi_reg>; - samsung,power-domain = <&pd_lcd0>; + power-domains = <&pd_lcd0>; #address-cells = <1>; #size-cells = <0>; samsung,pll-clock-frequency = <24000000>; diff --git a/Documentation/devicetree/bindings/video/exynos_mixer.txt b/Documentation/devicetree/bindings/video/exynos_mixer.txt index 08b394b1edbf..3e38128f866b 100644 --- a/Documentation/devicetree/bindings/video/exynos_mixer.txt +++ b/Documentation/devicetree/bindings/video/exynos_mixer.txt @@ -15,6 +15,7 @@ Required properties: a) mixer: Gate of Mixer IP bus clock. b) sclk_hdmi: HDMI Special clock, one of the two possible inputs of mixer mux. + c) hdmi: Gate of HDMI IP bus clock, needed together with sclk_hdmi. Example: diff --git a/Documentation/devicetree/bindings/video/renesas,du.txt b/Documentation/devicetree/bindings/video/renesas,du.txt index 5102830f2760..c902323928f7 100644 --- a/Documentation/devicetree/bindings/video/renesas,du.txt +++ b/Documentation/devicetree/bindings/video/renesas,du.txt @@ -26,6 +26,10 @@ Required Properties: per LVDS encoder. The functional clocks must be named "du.x" with "x" being the channel numerical index. The LVDS clocks must be named "lvds.x" with "x" being the LVDS encoder numerical index. + - In addition to the functional and encoder clocks, all DU versions also + support externally supplied pixel clocks. Those clocks are optional. + When supplied they must be named "dclkin.x" with "x" being the input + clock numerical index. Required nodes: diff --git a/Documentation/devicetree/bindings/video/rockchip-drm.txt b/Documentation/devicetree/bindings/video/rockchip-drm.txt new file mode 100644 index 000000000000..7fff582495a2 --- /dev/null +++ b/Documentation/devicetree/bindings/video/rockchip-drm.txt @@ -0,0 +1,19 @@ +Rockchip DRM master device +================================ + +The Rockchip DRM master device is a virtual device needed to list all +vop devices or other display interface nodes that comprise the +graphics subsystem. + +Required properties: +- compatible: Should be "rockchip,display-subsystem" +- ports: Should contain a list of phandles pointing to display interface port + of vop devices. vop definitions as defined in + Documentation/devicetree/bindings/video/rockchip-vop.txt + +example: + +display-subsystem { + compatible = "rockchip,display-subsystem"; + ports = <&vopl_out>, <&vopb_out>; +}; diff --git a/Documentation/devicetree/bindings/video/rockchip-vop.txt b/Documentation/devicetree/bindings/video/rockchip-vop.txt new file mode 100644 index 000000000000..d15351f2313d --- /dev/null +++ b/Documentation/devicetree/bindings/video/rockchip-vop.txt @@ -0,0 +1,58 @@ +device-tree bindings for rockchip soc display controller (vop) + +VOP (Visual Output Processor) is the Display Controller for the Rockchip +series of SoCs which transfers the image data from a video memory +buffer to an external LCD interface. + +Required properties: +- compatible: value should be one of the following + "rockchip,rk3288-vop"; + +- interrupts: should contain a list of all VOP IP block interrupts in the + order: VSYNC, LCD_SYSTEM. The interrupt specifier + format depends on the interrupt controller used. + +- clocks: must include clock specifiers corresponding to entries in the + clock-names property. + +- clock-names: Must contain + aclk_vop: for ddr buffer transfer. + hclk_vop: for ahb bus to R/W the phy regs. + dclk_vop: pixel clock. + +- resets: Must contain an entry for each entry in reset-names. + See ../reset/reset.txt for details. +- reset-names: Must include the following entries: + - axi + - ahb + - dclk + +- iommus: required a iommu node + +- port: A port node with endpoint definitions as defined in + Documentation/devicetree/bindings/media/video-interfaces.txt. + +Example: +SoC specific DT entry: + vopb: vopb@ff930000 { + compatible = "rockchip,rk3288-vop"; + reg = <0xff930000 0x19c>; + interrupts = <GIC_SPI 15 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&cru ACLK_VOP0>, <&cru DCLK_VOP0>, <&cru HCLK_VOP0>; + clock-names = "aclk_vop", "dclk_vop", "hclk_vop"; + resets = <&cru SRST_LCDC1_AXI>, <&cru SRST_LCDC1_AHB>, <&cru SRST_LCDC1_DCLK>; + reset-names = "axi", "ahb", "dclk"; + iommus = <&vopb_mmu>; + vopb_out: port { + #address-cells = <1>; + #size-cells = <0>; + vopb_out_edp: endpoint@0 { + reg = <0>; + remote-endpoint=<&edp_in_vopb>; + }; + vopb_out_hdmi: endpoint@1 { + reg = <1>; + remote-endpoint=<&hdmi_in_vopb>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/video/samsung-fimd.txt b/Documentation/devicetree/bindings/video/samsung-fimd.txt index 4e6c77c85546..a8bbbde03e79 100644 --- a/Documentation/devicetree/bindings/video/samsung-fimd.txt +++ b/Documentation/devicetree/bindings/video/samsung-fimd.txt @@ -11,6 +11,7 @@ Required properties: "samsung,s5pv210-fimd"; /* for S5PV210 SoC */ "samsung,exynos3250-fimd"; /* for Exynos3250/3472 SoCs */ "samsung,exynos4210-fimd"; /* for Exynos4 SoCs */ + "samsung,exynos4415-fimd"; /* for Exynos4415 SoC */ "samsung,exynos5250-fimd"; /* for Exynos5 SoCs */ - reg: physical base address and length of the FIMD registers set. @@ -37,7 +38,7 @@ Required properties: property. Must contain "sclk_fimd" and "fimd". Optional Properties: -- samsung,power-domain: a phandle to FIMD power domain node. +- power-domains: a phandle to FIMD power domain node. - samsung,invert-vden: video enable signal is inverted - samsung,invert-vclk: video clock signal is inverted - display-timings: timing settings for FIMD, as described in document [1]. @@ -96,7 +97,7 @@ SoC specific DT entry: interrupts = <11 0>, <11 1>, <11 2>; clocks = <&clock 140>, <&clock 283>; clock-names = "sclk_fimd", "fimd"; - samsung,power-domain = <&pd_lcd0>; + power-domains = <&pd_lcd0>; status = "disabled"; }; diff --git a/Documentation/devicetree/bindings/video/simple-framebuffer-sunxi.txt b/Documentation/devicetree/bindings/video/simple-framebuffer-sunxi.txt new file mode 100644 index 000000000000..c46ba641a1df --- /dev/null +++ b/Documentation/devicetree/bindings/video/simple-framebuffer-sunxi.txt @@ -0,0 +1,33 @@ +Sunxi specific Simple Framebuffer bindings + +This binding documents sunxi specific extensions to the simple-framebuffer +bindings. The sunxi simplefb u-boot code relies on the devicetree containing +pre-populated simplefb nodes. + +These extensions are intended so that u-boot can select the right node based +on which pipeline is being used. As such they are solely intended for +firmware / bootloader use, and the OS should ignore them. + +Required properties: +- compatible: "allwinner,simple-framebuffer" +- allwinner,pipeline, one of: + "de_be0-lcd0" + "de_be1-lcd1" + "de_be0-lcd0-hdmi" + "de_be1-lcd1-hdmi" + +Example: + +chosen { + #address-cells = <1>; + #size-cells = <1>; + ranges; + + framebuffer@0 { + compatible = "allwinner,simple-framebuffer", "simple-framebuffer"; + allwinner,pipeline = "de_be0-lcd0-hdmi"; + clocks = <&pll5 1>, <&ahb_gates 36>, <&ahb_gates 43>, + <&ahb_gates 44>; + status = "disabled"; + }; +}; diff --git a/Documentation/devicetree/bindings/video/simple-framebuffer.txt b/Documentation/devicetree/bindings/video/simple-framebuffer.txt index 70c26f3a5b9a..4474ef6e0b95 100644 --- a/Documentation/devicetree/bindings/video/simple-framebuffer.txt +++ b/Documentation/devicetree/bindings/video/simple-framebuffer.txt @@ -1,8 +1,40 @@ Simple Framebuffer -A simple frame-buffer describes a raw memory region that may be rendered to, -with the assumption that the display hardware has already been set up to scan -out from that buffer. +A simple frame-buffer describes a frame-buffer setup by firmware or +the bootloader, with the assumption that the display hardware has already +been set up to scan out from the memory pointed to by the reg property. + +Since simplefb nodes represent runtime information they must be sub-nodes of +the chosen node (*). Simplefb nodes must be named "framebuffer@<address>". + +If the devicetree contains nodes for the display hardware used by a simplefb, +then the simplefb node must contain a property called "display", which +contains a phandle pointing to the primary display hw node, so that the OS +knows which simplefb to disable when handing over control to a driver for the +real hardware. The bindings for the hw nodes must specify which node is +considered the primary node. + +It is advised to add display# aliases to help the OS determine how to number +things. If display# aliases are used, then if the simplefb node contains a +"display" property then the /aliases/display# path must point to the display +hw node the "display" property points to, otherwise it must point directly +to the simplefb node. + +If a simplefb node represents the preferred console for user interaction, +then the chosen node's stdout-path property should point to it, or to the +primary display hw node, as with display# aliases. If display aliases are +used then it should be set to the alias instead. + +It is advised that devicetree files contain pre-filled, disabled framebuffer +nodes, so that the firmware only needs to update the mode information and +enable them. This way if e.g. later on support for more display clocks get +added, the simplefb nodes will already contain this info and the firmware +does not need to be updated. + +If pre-filled framebuffer nodes are used, the firmware may need extra +information to find the right node. In that case an extra platform specific +compatible and platform specific properties should be used and documented, +see e.g. simple-framebuffer-sunxi.txt . Required properties: - compatible: "simple-framebuffer" @@ -14,13 +46,41 @@ Required properties: - r5g6b5 (16-bit pixels, d[15:11]=r, d[10:5]=g, d[4:0]=b). - a8b8g8r8 (32-bit pixels, d[31:24]=a, d[23:16]=b, d[15:8]=g, d[7:0]=r). +Optional properties: +- clocks : List of clocks used by the framebuffer. Clocks listed here + are expected to already be configured correctly. The OS must + ensure these clocks are not modified or disabled while the + simple framebuffer remains active. +- display : phandle pointing to the primary display hardware node + Example: - framebuffer { +aliases { + display0 = &lcdc0; +} + +chosen { + framebuffer0: framebuffer@1d385000 { compatible = "simple-framebuffer"; reg = <0x1d385000 (1600 * 1200 * 2)>; width = <1600>; height = <1200>; stride = <(1600 * 2)>; format = "r5g6b5"; + clocks = <&ahb_gates 36>, <&ahb_gates 43>, <&ahb_gates 44>; + display = <&lcdc0>; + }; + stdout-path = "display0"; +}; + +soc@01c00000 { + lcdc0: lcdc@1c0c000 { + compatible = "allwinner,sun4i-a10-lcdc"; + ... }; +}; + + +*) Older devicetree files may have a compatible = "simple-framebuffer" node +in a different place, operating systems must first enumerate any compatible +nodes found under chosen and then check for other compatible nodes. diff --git a/Documentation/devicetree/bindings/video/ti,dra7-dss.txt b/Documentation/devicetree/bindings/video/ti,dra7-dss.txt new file mode 100644 index 000000000000..f33a05137b0e --- /dev/null +++ b/Documentation/devicetree/bindings/video/ti,dra7-dss.txt @@ -0,0 +1,69 @@ +Texas Instruments DRA7x Display Subsystem +========================================= + +See Documentation/devicetree/bindings/video/ti,omap-dss.txt for generic +description about OMAP Display Subsystem bindings. + +DSS Core +-------- + +Required properties: +- compatible: "ti,dra7-dss" +- reg: address and length of the register spaces for 'dss' +- ti,hwmods: "dss_core" +- clocks: handle to fclk +- clock-names: "fck" +- syscon: phandle to control module core syscon node + +Optional properties: + +Some DRA7xx SoCs have one dedicated video PLL, some have two. These properties +can be used to describe the video PLLs: + +- reg: address and length of the register spaces for 'pll1_clkctrl', + 'pll1', 'pll2_clkctrl', 'pll2' +- clocks: handle to video1 pll clock and video2 pll clock +- clock-names: "video1_clk" and "video2_clk" + +Required nodes: +- DISPC + +Optional nodes: +- DSS Submodules: HDMI +- Video port for DPI output + +DPI Endpoint required properties: +- data-lines: number of lines used + + +DISPC +----- + +Required properties: +- compatible: "ti,dra7-dispc" +- reg: address and length of the register space +- ti,hwmods: "dss_dispc" +- interrupts: the DISPC interrupt +- clocks: handle to fclk +- clock-names: "fck" + +HDMI +---- + +Required properties: +- compatible: "ti,dra7-hdmi" +- reg: addresses and lengths of the register spaces for 'wp', 'pll', 'phy', + 'core' +- reg-names: "wp", "pll", "phy", "core" +- interrupts: the HDMI interrupt line +- ti,hwmods: "dss_hdmi" +- vdda-supply: vdda power supply +- clocks: handles to fclk and pll clock +- clock-names: "fck", "sys_clk" + +Optional nodes: +- Video port for HDMI output + +HDMI Endpoint optional properties: +- lanes: list of 8 pin numbers for the HDMI lanes: CLK+, CLK-, D0+, D0-, + D1+, D1-, D2+, D2-. (default: 0,1,2,3,4,5,6,7) diff --git a/Documentation/devicetree/bindings/video/ti,opa362.txt b/Documentation/devicetree/bindings/video/ti,opa362.txt new file mode 100644 index 000000000000..f96083c0bd17 --- /dev/null +++ b/Documentation/devicetree/bindings/video/ti,opa362.txt @@ -0,0 +1,38 @@ +OPA362 analog video amplifier + +Required properties: +- compatible: "ti,opa362" +- enable-gpios: enable/disable output gpio + +Required node: +- Video port 0 for opa362 input +- Video port 1 for opa362 output + +Example: + +tv_amp: opa362 { + compatible = "ti,opa362"; + enable-gpios = <&gpio1 23 0>; /* GPIO to enable video out amplifier */ + + ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + reg = <0>; + opa_in: endpoint@0 { + remote-endpoint = <&venc_out>; + }; + }; + + port@1 { + reg = <1>; + opa_out: endpoint@0 { + remote-endpoint = <&tv_connector_in>; + }; + }; + }; +}; + + + diff --git a/Documentation/devicetree/bindings/w1/omap-hdq.txt b/Documentation/devicetree/bindings/w1/omap-hdq.txt new file mode 100644 index 000000000000..fef794741bd1 --- /dev/null +++ b/Documentation/devicetree/bindings/w1/omap-hdq.txt @@ -0,0 +1,17 @@ +* OMAP HDQ One wire bus master controller + +Required properties: +- compatible : should be "ti,omap3-1w" +- reg : Address and length of the register set for the device +- interrupts : interrupt line. +- ti,hwmods : "hdq1w" + +Example: + +- From omap3.dtsi + hdqw1w: 1w@480b2000 { + compatible = "ti,omap3-1w"; + reg = <0x480b2000 0x1000>; + interrupts = <58>; + ti,hwmods = "hdq1w"; + }; diff --git a/Documentation/devicetree/bindings/watchdog/marvel.txt b/Documentation/devicetree/bindings/watchdog/marvel.txt index 97223fddb7bd..858ed9221ac4 100644 --- a/Documentation/devicetree/bindings/watchdog/marvel.txt +++ b/Documentation/devicetree/bindings/watchdog/marvel.txt @@ -17,6 +17,18 @@ For "marvell,armada-375-wdt" and "marvell,armada-380-wdt": - reg : A third entry is mandatory and should contain the shared mask/unmask RSTOUT address. +Clocks required for compatibles = "marvell,orion-wdt", + "marvell,armada-370-wdt": +- clocks : Must contain a single entry describing the clock input + +Clocks required for compatibles = "marvell,armada-xp-wdt" + "marvell,armada-375-wdt" + "marvell,armada-380-wdt": +- clocks : Must contain an entry for each entry in clock-names. +- clock-names : Must include the following entries: + "nbclk" (L2/coherency fabric clock), + "fixed" (Reference 25 MHz fixed-clock). + Optional properties: - interrupts : Contains the IRQ for watchdog expiration @@ -30,4 +42,5 @@ Example: interrupts = <3>; timeout-sec = <10>; status = "okay"; + clocks = <&gate_clk 7>; }; diff --git a/Documentation/devicetree/of_selftest.txt b/Documentation/devicetree/of_selftest.txt index 1e3d5c92b5e3..57a808b588bf 100644 --- a/Documentation/devicetree/of_selftest.txt +++ b/Documentation/devicetree/of_selftest.txt @@ -63,7 +63,6 @@ struct device_node { struct device_node *parent; struct device_node *child; struct device_node *sibling; - struct device_node *allnext; /* next in list of all nodes */ ... }; @@ -99,12 +98,6 @@ child11 -> sibling12 -> sibling13 -> sibling14 -> null Figure 1: Generic structure of un-flattened device tree -*allnext: it is used to link all the nodes of DT into a list. So, for the - above tree the list would be as follows: - -root->child1->child11->sibling12->sibling13->child131->sibling14->sibling2-> -child21->sibling22->sibling23->sibling3->child31->sibling32->sibling4->null - Before executing OF selftest, it is required to attach the test data to machine's device tree (if present). So, when selftest_data_add() is called, at first it reads the flattened device tree data linked into the kernel image @@ -131,11 +124,6 @@ root ('/') test-child01 null null null -allnext list: - -root->testcase-data->test-child0->test-child01->test-sibling1->test-sibling2 -->test-sibling3->null - Figure 2: Example test data tree to be attached to live tree. According to the scenario above, the live tree is already present so it isn't @@ -204,8 +192,6 @@ detached and then moving up the parent nodes are removed, and eventually the whole tree). selftest_data_remove() calls detach_node_and_children() that uses of_detach_node() to detach the nodes from the live device tree. -To detach a node, of_detach_node() first updates all_next linked list, by -attaching the previous node's allnext to current node's allnext pointer. And -then, it either updates the child pointer of given node's parent to its -sibling or attaches the previous sibling to the given node's sibling, as -appropriate. That is it :) +To detach a node, of_detach_node() either updates the child pointer of given +node's parent to its sibling or attaches the previous sibling to the given +node's sibling, as appropriate. That is it :) diff --git a/Documentation/devicetree/overlay-notes.txt b/Documentation/devicetree/overlay-notes.txt new file mode 100644 index 000000000000..d418a6ce9812 --- /dev/null +++ b/Documentation/devicetree/overlay-notes.txt @@ -0,0 +1,133 @@ +Device Tree Overlay Notes +------------------------- + +This document describes the implementation of the in-kernel +device tree overlay functionality residing in drivers/of/overlay.c and is a +companion document to Documentation/devicetree/dt-object-internal.txt[1] & +Documentation/devicetree/dynamic-resolution-notes.txt[2] + +How overlays work +----------------- + +A Device Tree's overlay purpose is to modify the kernel's live tree, and +have the modification affecting the state of the kernel in a way that +is reflecting the changes. +Since the kernel mainly deals with devices, any new device node that result +in an active device should have it created while if the device node is either +disabled or removed all together, the affected device should be deregistered. + +Lets take an example where we have a foo board with the following base tree +which is taken from [1]. + +---- foo.dts ----------------------------------------------------------------- + /* FOO platform */ + / { + compatible = "corp,foo"; + + /* shared resources */ + res: res { + }; + + /* On chip peripherals */ + ocp: ocp { + /* peripherals that are always instantiated */ + peripheral1 { ... }; + } + }; +---- foo.dts ----------------------------------------------------------------- + +The overlay bar.dts, when loaded (and resolved as described in [2]) should + +---- bar.dts ----------------------------------------------------------------- +/plugin/; /* allow undefined label references and record them */ +/ { + .... /* various properties for loader use; i.e. part id etc. */ + fragment@0 { + target = <&ocp>; + __overlay__ { + /* bar peripheral */ + bar { + compatible = "corp,bar"; + ... /* various properties and child nodes */ + } + }; + }; +}; +---- bar.dts ----------------------------------------------------------------- + +result in foo+bar.dts + +---- foo+bar.dts ------------------------------------------------------------- + /* FOO platform + bar peripheral */ + / { + compatible = "corp,foo"; + + /* shared resources */ + res: res { + }; + + /* On chip peripherals */ + ocp: ocp { + /* peripherals that are always instantiated */ + peripheral1 { ... }; + + /* bar peripheral */ + bar { + compatible = "corp,bar"; + ... /* various properties and child nodes */ + } + } + }; +---- foo+bar.dts ------------------------------------------------------------- + +As a result of the overlay, a new device node (bar) has been created +so a bar platform device will be registered and if a matching device driver +is loaded the device will be created as expected. + +Overlay in-kernel API +-------------------------------- + +The API is quite easy to use. + +1. Call of_overlay_create() to create and apply an overlay. The return value +is a cookie identifying this overlay. + +2. Call of_overlay_destroy() to remove and cleanup the overlay previously +created via the call to of_overlay_create(). Removal of an overlay that +is stacked by another will not be permitted. + +Finally, if you need to remove all overlays in one-go, just call +of_overlay_destroy_all() which will remove every single one in the correct +order. + +Overlay DTS Format +------------------ + +The DTS of an overlay should have the following format: + +{ + /* ignored properties by the overlay */ + + fragment@0 { /* first child node */ + + target=<phandle>; /* phandle target of the overlay */ + or + target-path="/path"; /* target path of the overlay */ + + __overlay__ { + property-a; /* add property-a to the target */ + node-a { /* add to an existing, or create a node-a */ + ... + }; + }; + } + fragment@1 { /* second child node */ + ... + }; + /* more fragments follow */ +} + +Using the non-phandle based target method allows one to use a base DT which does +not contain a __symbols__ node, i.e. it was not compiled with the -@ option. +The __symbols__ node is only required for the target=<phandle> method, since it +contains the information required to map from a phandle to a tree location. diff --git a/Documentation/devicetree/todo.txt b/Documentation/devicetree/todo.txt index c3cf0659bd19..b5139d1de811 100644 --- a/Documentation/devicetree/todo.txt +++ b/Documentation/devicetree/todo.txt @@ -2,7 +2,6 @@ Todo list for devicetree: === General structure === - Switch from custom lists to (h)list_head for nodes and properties structure -- Remove of_allnodes list and iterate using list of child nodes alone === CONFIG_OF_DYNAMIC === - Switch to RCU for tree updates and get rid of global spinlock diff --git a/Documentation/dmaengine/00-INDEX b/Documentation/dmaengine/00-INDEX new file mode 100644 index 000000000000..07de6573d22b --- /dev/null +++ b/Documentation/dmaengine/00-INDEX @@ -0,0 +1,8 @@ +00-INDEX + - this file. +client.txt + -the DMA Engine API Guide. +dmatest.txt + - how to compile, configure and use the dmatest system. +provider.txt + - the DMA controller API.
\ No newline at end of file diff --git a/Documentation/dmaengine.txt b/Documentation/dmaengine/client.txt index 11fb87ff6cd0..11fb87ff6cd0 100644 --- a/Documentation/dmaengine.txt +++ b/Documentation/dmaengine/client.txt diff --git a/Documentation/dmatest.txt b/Documentation/dmaengine/dmatest.txt index dd77a81bdb80..dd77a81bdb80 100644 --- a/Documentation/dmatest.txt +++ b/Documentation/dmaengine/dmatest.txt diff --git a/Documentation/dmaengine/provider.txt b/Documentation/dmaengine/provider.txt new file mode 100644 index 000000000000..766658ccf235 --- /dev/null +++ b/Documentation/dmaengine/provider.txt @@ -0,0 +1,366 @@ +DMAengine controller documentation +================================== + +Hardware Introduction ++++++++++++++++++++++ + +Most of the Slave DMA controllers have the same general principles of +operations. + +They have a given number of channels to use for the DMA transfers, and +a given number of requests lines. + +Requests and channels are pretty much orthogonal. Channels can be used +to serve several to any requests. To simplify, channels are the +entities that will be doing the copy, and requests what endpoints are +involved. + +The request lines actually correspond to physical lines going from the +DMA-eligible devices to the controller itself. Whenever the device +will want to start a transfer, it will assert a DMA request (DRQ) by +asserting that request line. + +A very simple DMA controller would only take into account a single +parameter: the transfer size. At each clock cycle, it would transfer a +byte of data from one buffer to another, until the transfer size has +been reached. + +That wouldn't work well in the real world, since slave devices might +require a specific number of bits to be transferred in a single +cycle. For example, we may want to transfer as much data as the +physical bus allows to maximize performances when doing a simple +memory copy operation, but our audio device could have a narrower FIFO +that requires data to be written exactly 16 or 24 bits at a time. This +is why most if not all of the DMA controllers can adjust this, using a +parameter called the transfer width. + +Moreover, some DMA controllers, whenever the RAM is used as a source +or destination, can group the reads or writes in memory into a buffer, +so instead of having a lot of small memory accesses, which is not +really efficient, you'll get several bigger transfers. This is done +using a parameter called the burst size, that defines how many single +reads/writes it's allowed to do without the controller splitting the +transfer into smaller sub-transfers. + +Our theoretical DMA controller would then only be able to do transfers +that involve a single contiguous block of data. However, some of the +transfers we usually have are not, and want to copy data from +non-contiguous buffers to a contiguous buffer, which is called +scatter-gather. + +DMAEngine, at least for mem2dev transfers, require support for +scatter-gather. So we're left with two cases here: either we have a +quite simple DMA controller that doesn't support it, and we'll have to +implement it in software, or we have a more advanced DMA controller, +that implements in hardware scatter-gather. + +The latter are usually programmed using a collection of chunks to +transfer, and whenever the transfer is started, the controller will go +over that collection, doing whatever we programmed there. + +This collection is usually either a table or a linked list. You will +then push either the address of the table and its number of elements, +or the first item of the list to one channel of the DMA controller, +and whenever a DRQ will be asserted, it will go through the collection +to know where to fetch the data from. + +Either way, the format of this collection is completely dependent on +your hardware. Each DMA controller will require a different structure, +but all of them will require, for every chunk, at least the source and +destination addresses, whether it should increment these addresses or +not and the three parameters we saw earlier: the burst size, the +transfer width and the transfer size. + +The one last thing is that usually, slave devices won't issue DRQ by +default, and you have to enable this in your slave device driver first +whenever you're willing to use DMA. + +These were just the general memory-to-memory (also called mem2mem) or +memory-to-device (mem2dev) kind of transfers. Most devices often +support other kind of transfers or memory operations that dmaengine +support and will be detailed later in this document. + +DMA Support in Linux +++++++++++++++++++++ + +Historically, DMA controller drivers have been implemented using the +async TX API, to offload operations such as memory copy, XOR, +cryptography, etc., basically any memory to memory operation. + +Over time, the need for memory to device transfers arose, and +dmaengine was extended. Nowadays, the async TX API is written as a +layer on top of dmaengine, and acts as a client. Still, dmaengine +accommodates that API in some cases, and made some design choices to +ensure that it stayed compatible. + +For more information on the Async TX API, please look the relevant +documentation file in Documentation/crypto/async-tx-api.txt. + +DMAEngine Registration +++++++++++++++++++++++ + +struct dma_device Initialization +-------------------------------- + +Just like any other kernel framework, the whole DMAEngine registration +relies on the driver filling a structure and registering against the +framework. In our case, that structure is dma_device. + +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 + INIT_LIST_HEAD macro for example + + * dev: should hold the pointer to the struct device associated + to your current driver instance. + +Supported transaction types +--------------------------- + +The next thing you need is to set which transaction types your device +(and driver) supports. + +Our dma_device structure has a field called cap_mask that holds the +various types of transaction supported, and you need to modify this +mask using the dma_cap_set function, with various flags depending on +transaction types you support as an argument. + +All those capabilities are defined in the dma_transaction_type enum, +in include/linux/dmaengine.h + +Currently, the types available are: + * DMA_MEMCPY + - The device is able to do memory to memory copies + + * DMA_XOR + - The device is able to perform XOR operations on memory areas + - Used to accelerate XOR intensive tasks, such as RAID5 + + * DMA_XOR_VAL + - The device is able to perform parity check using the XOR + algorithm against a memory buffer. + + * DMA_PQ + - The device is able to perform RAID6 P+Q computations, P being a + simple XOR, and Q being a Reed-Solomon algorithm. + + * DMA_PQ_VAL + - The device is able to perform parity check using RAID6 P+Q + algorithm against a memory buffer. + + * DMA_INTERRUPT + - The device is able to trigger a dummy transfer that will + generate periodic interrupts + - Used by the client drivers to register a callback that will be + called on a regular basis through the DMA controller interrupt + + * DMA_SG + - The device supports memory to memory scatter-gather + transfers. + - Even though a plain memcpy can look like a particular case of a + scatter-gather transfer, with a single chunk to transfer, it's a + distinct transaction type in the mem2mem transfers case + + * DMA_PRIVATE + - The devices only supports slave transfers, and as such isn't + available for async transfers. + + * DMA_ASYNC_TX + - Must not be set by the device, and will be set by the framework + if needed + - /* TODO: What is it about? */ + + * DMA_SLAVE + - The device can handle device to memory transfers, including + scatter-gather transfers. + - While in the mem2mem case we were having two distinct types to + deal with a single chunk to copy or a collection of them, here, + we just have a single transaction type that is supposed to + handle both. + - If you want to transfer a single contiguous memory buffer, + simply build a scatter list with only one item. + + * DMA_CYCLIC + - The device can handle cyclic transfers. + - A cyclic transfer is a transfer where the chunk collection will + loop over itself, with the last item pointing to the first. + - It's usually used for audio transfers, where you want to operate + on a single ring buffer that you will fill with your audio data. + + * DMA_INTERLEAVE + - The device supports interleaved transfer. + - These transfers can transfer data from a non-contiguous buffer + to a non-contiguous buffer, opposed to DMA_SLAVE that can + transfer data from a non-contiguous data set to a continuous + destination buffer. + - It's usually used for 2d content transfers, in which case you + want to transfer a portion of uncompressed data directly to the + display to print it + +These various types will also affect how the source and destination +addresses change over time. + +Addresses pointing to RAM are typically incremented (or decremented) +after each transfer. In case of a ring buffer, they may loop +(DMA_CYCLIC). Addresses pointing to a device's register (e.g. a FIFO) +are typically fixed. + +Device operations +----------------- + +Our dma_device structure also requires a few function pointers in +order to implement the actual logic, now that we described what +operations we were able to perform. + +The functions that we have to fill in there, and hence have to +implement, obviously depend on the transaction types you reported as +supported. + + * device_alloc_chan_resources + * device_free_chan_resources + - These functions will be called whenever a driver will call + dma_request_channel or dma_release_channel for the first/last + time on the channel associated to that driver. + - They are in charge of allocating/freeing all the needed + resources in order for that channel to be useful for your + driver. + - These functions can sleep. + + * device_prep_dma_* + - These functions are matching the capabilities you registered + previously. + - These functions all take the buffer or the scatterlist relevant + for the transfer being prepared, and should create a hardware + descriptor or a list of hardware descriptors from it + - These functions can be called from an interrupt context + - Any allocation you might do should be using the GFP_NOWAIT + flag, in order not to potentially sleep, but without depleting + the emergency pool either. + - Drivers should try to pre-allocate any memory they might need + during the transfer setup at probe time to avoid putting to + much pressure on the nowait allocator. + + - It should return a unique instance of the + dma_async_tx_descriptor structure, that further represents this + particular transfer. + + - This structure can be initialized using the function + dma_async_tx_descriptor_init. + - You'll also need to set two fields in this structure: + + flags: + TODO: Can it be modified by the driver itself, or + should it be always the flags passed in the arguments + + + tx_submit: A pointer to a function you have to implement, + that is supposed to push the current + transaction descriptor to a pending queue, waiting + for issue_pending to be called. + + * device_issue_pending + - Takes the first transaction descriptor in the pending queue, + and starts the transfer. Whenever that transfer is done, it + should move to the next transaction in the list. + - This function can be called in an interrupt context + + * device_tx_status + - Should report the bytes left to go over on the given channel + - Should only care about the transaction descriptor passed as + argument, not the currently active one on a given channel + - The tx_state argument might be NULL + - Should use dma_set_residue to report it + - In the case of a cyclic transfer, it should only take into + account the current period. + - This function can be called in an interrupt context. + + * device_control + - Used by client drivers to control and configure the channel it + has a handle on. + - Called with a command and an argument + + The command is one of the values listed by the enum + dma_ctrl_cmd. The valid commands are: + + DMA_PAUSE + + Pauses a transfer on the channel + + This command should operate synchronously on the channel, + pausing right away the work of the given channel + + DMA_RESUME + + Restarts a transfer on the channel + + This command should operate synchronously on the channel, + resuming right away the work of the given channel + + DMA_TERMINATE_ALL + + Aborts all the pending and ongoing transfers on the + channel + + This command should operate synchronously on the channel, + terminating right away all the channels + + DMA_SLAVE_CONFIG + + Reconfigures the channel with passed configuration + + This command should NOT perform synchronously, or on any + currently queued transfers, but only on subsequent ones + + In this case, the function will receive a + dma_slave_config structure pointer as an argument, that + will detail which configuration to use. + + Even though that structure contains a direction field, + this field is deprecated in favor of the direction + argument given to the prep_* functions + + FSLDMA_EXTERNAL_START + + TODO: Why does that even exist? + + The argument is an opaque unsigned long. This actually is a + pointer to a struct dma_slave_config that should be used only + in the DMA_SLAVE_CONFIG. + + * device_slave_caps + - Called through the framework by client drivers in order to have + an idea of what are the properties of the channel allocated to + them. + - Such properties are the buswidth, available directions, etc. + - Required for every generic layer doing DMA transfers, such as + ASoC. + +Misc notes (stuff that should be documented, but don't really know +where to put them) +------------------------------------------------------------------ + * dma_run_dependencies + - Should be called at the end of an async TX transfer, and can be + ignored in the slave transfers case. + - Makes sure that dependent operations are run before marking it + as complete. + + * dma_cookie_t + - it's a DMA transaction ID that will increment over time. + - Not really relevant any more since the introduction of virt-dma + that abstracts it away. + + * DMA_CTRL_ACK + - Undocumented feature + - No one really has an idea of what it's about, besides being + related to reusing the DMA transaction descriptors or having + additional transactions added to it in the async-tx API + - Useless in the case of the slave API + +General Design Notes +-------------------- + +Most of the DMAEngine drivers you'll see are based on a similar design +that handles the end of transfer interrupts in the handler, but defer +most work to a tasklet, including the start of a new transfer whenever +the previous transfer ended. + +This is a rather inefficient design though, because the inter-transfer +latency will be not only the interrupt latency, but also the +scheduling latency of the tasklet, which will leave the channel idle +in between, which will slow down the global transfer rate. + +You should avoid this kind of practice, and instead of electing a new +transfer in your tasklet, move that part to the interrupt handler in +order to have a shorter idle window (that we can't really avoid +anyway). + +Glossary +-------- + +Burst: A number of consecutive read or write operations + that can be queued to buffers before being flushed to + memory. +Chunk: A contiguous collection of bursts +Transfer: A collection of chunks (be it contiguous or not) diff --git a/Documentation/driver-model/bus.txt b/Documentation/driver-model/bus.txt index 6754b2df8aa1..b577a45b93ea 100644 --- a/Documentation/driver-model/bus.txt +++ b/Documentation/driver-model/bus.txt @@ -45,7 +45,7 @@ them are inherently bus-specific. Drivers typically declare an array of device IDs of devices they support that reside in a bus-specific driver structure. -The purpose of the match callback is provide the bus an opportunity to +The purpose of the match callback is to give the bus an opportunity to determine if a particular driver supports a particular device by comparing the device IDs the driver supports with the device ID of a particular device, without sacrificing bus-specific functionality or diff --git a/Documentation/driver-model/devres.txt b/Documentation/driver-model/devres.txt index b5ab416cd53a..6d1e8eeb5990 100644 --- a/Documentation/driver-model/devres.txt +++ b/Documentation/driver-model/devres.txt @@ -258,6 +258,8 @@ IIO devm_iio_device_free() devm_iio_device_register() devm_iio_device_unregister() + devm_iio_kfifo_allocate() + devm_iio_kfifo_free() devm_iio_trigger_alloc() devm_iio_trigger_free() diff --git a/Documentation/email-clients.txt b/Documentation/email-clients.txt index 9af538be3751..eede6088f978 100644 --- a/Documentation/email-clients.txt +++ b/Documentation/email-clients.txt @@ -77,6 +77,17 @@ should appear, and then pressing CTRL-R let you specify the patch file to insert into the message. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Claws Mail (GUI) + +Works. Some people use this successfully for patches. + +To insert a patch use Message->Insert File (CTRL+i) or an external editor. + +If the inserted patch has to be edited in the Claws composition window +"Auto wrapping" in Configuration->Preferences->Compose->Wrapping should be +disabled. + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Evolution (GUI) Some people use this successfully for patches. diff --git a/Documentation/filesystems/00-INDEX b/Documentation/filesystems/00-INDEX index ac28149aede4..9922939e7d99 100644 --- a/Documentation/filesystems/00-INDEX +++ b/Documentation/filesystems/00-INDEX @@ -34,6 +34,9 @@ configfs/ - directory containing configfs documentation and example code. cramfs.txt - info on the cram filesystem for small storage (ROMs etc). +dax.txt + - info on avoiding the page cache for files stored on CPU-addressable + storage devices. debugfs.txt - info on the debugfs filesystem. devpts.txt @@ -154,5 +157,3 @@ xfs-self-describing-metadata.txt - info on XFS Self Describing Metadata. xfs.txt - info and mount options for the XFS filesystem. -xip.txt - - info on execute-in-place for file mappings. diff --git a/Documentation/filesystems/Locking b/Documentation/filesystems/Locking index b30753cbf431..2ca3d17eee56 100644 --- a/Documentation/filesystems/Locking +++ b/Documentation/filesystems/Locking @@ -199,8 +199,6 @@ prototypes: int (*releasepage) (struct page *, int); void (*freepage)(struct page *); int (*direct_IO)(int, struct kiocb *, struct iov_iter *iter, loff_t offset); - int (*get_xip_mem)(struct address_space *, pgoff_t, int, void **, - unsigned long *); int (*migratepage)(struct address_space *, struct page *, struct page *); int (*launder_page)(struct page *); int (*is_partially_uptodate)(struct page *, unsigned long, unsigned long); @@ -225,7 +223,6 @@ invalidatepage: yes releasepage: yes freepage: yes direct_IO: -get_xip_mem: maybe migratepage: yes (both) launder_page: yes is_partially_uptodate: yes diff --git a/Documentation/filesystems/dax.txt b/Documentation/filesystems/dax.txt new file mode 100644 index 000000000000..baf41118660d --- /dev/null +++ b/Documentation/filesystems/dax.txt @@ -0,0 +1,94 @@ +Direct Access for files +----------------------- + +Motivation +---------- + +The page cache is usually used to buffer reads and writes to files. +It is also used to provide the pages which are mapped into userspace +by a call to mmap. + +For block devices that are memory-like, the page cache pages would be +unnecessary copies of the original storage. The DAX code removes the +extra copy by performing reads and writes directly to the storage device. +For file mappings, the storage device is mapped directly into userspace. + + +Usage +----- + +If you have a block device which supports DAX, you can make a filesystem +on it as usual. When mounting it, use the -o dax option manually +or add 'dax' to the options in /etc/fstab. + + +Implementation Tips for Block Driver Writers +-------------------------------------------- + +To support DAX in your block driver, implement the 'direct_access' +block device operation. It is used to translate the sector number +(expressed in units of 512-byte sectors) to a page frame number (pfn) +that identifies the physical page for the memory. It also returns a +kernel virtual address that can be used to access the memory. + +The direct_access method takes a 'size' parameter that indicates the +number of bytes being requested. The function should return the number +of bytes that can be contiguously accessed at that offset. It may also +return a negative errno if an error occurs. + +In order to support this method, the storage must be byte-accessible by +the CPU at all times. If your device uses paging techniques to expose +a large amount of memory through a smaller window, then you cannot +implement direct_access. Equally, if your device can occasionally +stall the CPU for an extended period, you should also not attempt to +implement direct_access. + +These block devices may be used for inspiration: +- axonram: Axon DDR2 device driver +- brd: RAM backed block device driver +- dcssblk: s390 dcss block device driver + + +Implementation Tips for Filesystem Writers +------------------------------------------ + +Filesystem support consists of +- adding support to mark inodes as being DAX by setting the S_DAX flag in + i_flags +- implementing the direct_IO address space operation, and calling + dax_do_io() instead of blockdev_direct_IO() if S_DAX is set +- implementing an mmap file operation for DAX files which sets the + VM_MIXEDMAP flag on the VMA, and setting the vm_ops to include handlers + for fault and page_mkwrite (which should probably call dax_fault() and + dax_mkwrite(), passing the appropriate get_block() callback) +- calling dax_truncate_page() instead of block_truncate_page() for DAX files +- calling dax_zero_page_range() instead of zero_user() for DAX files +- ensuring that there is sufficient locking between reads, writes, + truncates and page faults + +The get_block() callback passed to the DAX functions may return +uninitialised extents. If it does, it must ensure that simultaneous +calls to get_block() (for example by a page-fault racing with a read() +or a write()) work correctly. + +These filesystems may be used for inspiration: +- ext2: the second extended filesystem, see Documentation/filesystems/ext2.txt +- ext4: the fourth extended filesystem, see Documentation/filesystems/ext4.txt + + +Shortcomings +------------ + +Even if the kernel or its modules are stored on a filesystem that supports +DAX on a block device that supports DAX, they will still be copied into RAM. + +The DAX code does not work correctly on architectures which have virtually +mapped caches such as ARM, MIPS and SPARC. + +Calling get_user_pages() on a range of user memory that has been mmaped +from a DAX file will fail as there are no 'struct page' to describe +those pages. This problem is being worked on. That means that O_DIRECT +reads/writes to those memory ranges from a non-DAX file will fail (note +that O_DIRECT reads/writes _of a DAX file_ do work, it is the memory +that is being accessed that is key here). Other things that will not +work include RDMA, sendfile() and splice(). diff --git a/Documentation/filesystems/debugfs.txt b/Documentation/filesystems/debugfs.txt index 3a863f692728..88ab81c79109 100644 --- a/Documentation/filesystems/debugfs.txt +++ b/Documentation/filesystems/debugfs.txt @@ -140,7 +140,7 @@ file. struct dentry *parent, struct debugfs_regset32 *regset); - int debugfs_print_regs32(struct seq_file *s, struct debugfs_reg32 *regs, + void debugfs_print_regs32(struct seq_file *s, struct debugfs_reg32 *regs, int nregs, void __iomem *base, char *prefix); The "base" argument may be 0, but you may want to build the reg32 array diff --git a/Documentation/filesystems/ext2.txt b/Documentation/filesystems/ext2.txt index 67639f905f10..b9714569e472 100644 --- a/Documentation/filesystems/ext2.txt +++ b/Documentation/filesystems/ext2.txt @@ -20,6 +20,9 @@ minixdf Makes `df' act like Minix. check=none, nocheck (*) Don't do extra checking of bitmaps on mount (check=normal and check=strict options removed) +dax Use direct access (no page cache). See + Documentation/filesystems/dax.txt. + debug Extra debugging information is sent to the kernel syslog. Useful for developers. @@ -56,8 +59,6 @@ noacl Don't support POSIX ACLs. nobh Do not attach buffer_heads to file pagecache. -xip Use execute in place (no caching) if possible - grpquota,noquota,quota,usrquota Quota options are silently ignored by ext2. diff --git a/Documentation/filesystems/ext4.txt b/Documentation/filesystems/ext4.txt index 919a3293aaa4..6c0108eb0137 100644 --- a/Documentation/filesystems/ext4.txt +++ b/Documentation/filesystems/ext4.txt @@ -386,6 +386,10 @@ max_dir_size_kb=n This limits the size of directories so that any i_version Enable 64-bit inode version support. This option is off by default. +dax Use direct access (no page cache). See + Documentation/filesystems/dax.txt. Note that + this option is incompatible with data=journal. + Data Mode ========= There are 3 different data modes: diff --git a/Documentation/filesystems/f2fs.txt b/Documentation/filesystems/f2fs.txt index 2cca5a25ef89..dac11d7fef27 100644 --- a/Documentation/filesystems/f2fs.txt +++ b/Documentation/filesystems/f2fs.txt @@ -106,6 +106,8 @@ background_gc=%s Turn on/off cleaning operations, namely garbage Default value for this option is on. So garbage collection is on by default. disable_roll_forward Disable the roll-forward recovery routine +norecovery Disable the roll-forward recovery routine, mounted read- + only (i.e., -o ro,disable_roll_forward) discard Issue discard/TRIM commands when a segment is cleaned. no_heap Disable heap-style segment allocation which finds free segments for data from the beginning of main area, while @@ -122,6 +124,10 @@ disable_ext_identify Disable the extension list configured by mkfs, so f2fs inline_xattr Enable the inline xattrs feature. inline_data Enable the inline data feature: New created small(<~3.4k) files can be written into inode block. +inline_dentry Enable the inline dir feature: data in new created + directory entries can be written into inode block. The + space of inode block which is used to store inline + dentries is limited to ~3.4k. flush_merge Merge concurrent cache_flush commands as much as possible to eliminate redundant command issues. If the underlying device handles the cache_flush command relatively slowly, @@ -131,6 +137,9 @@ nobarrier This option can be used if underlying storage guarantees If this option is set, no cache_flush commands are issued but f2fs still guarantees the write ordering of all the data writes. +fastboot This option is used when a system wants to reduce mount + time as much as possible, even though normal performance + can be sacrificed. ================================================================================ DEBUGFS ENTRIES @@ -190,6 +199,10 @@ Files in /sys/fs/f2fs/<devname> checkpoint is triggered, and issued during the checkpoint. By default, it is disabled with 0. + trim_sections This parameter controls the number of sections + to be trimmed out in batch mode when FITRIM + conducts. 32 sections is set by default. + ipu_policy This parameter controls the policy of in-place updates in f2fs. There are five policies: 0x01: F2FS_IPU_FORCE, 0x02: F2FS_IPU_SSR, diff --git a/Documentation/filesystems/fiemap.txt b/Documentation/filesystems/fiemap.txt index 1b805a0efbb0..f6d9c99103a4 100644 --- a/Documentation/filesystems/fiemap.txt +++ b/Documentation/filesystems/fiemap.txt @@ -196,7 +196,8 @@ struct fiemap_extent_info { }; It is intended that the file system should not need to access any of this -structure directly. +structure directly. Filesystem handlers should be tolerant to signals and return +EINTR once fatal signal received. Flag checking should be done at the beginning of the ->fiemap callback via the diff --git a/Documentation/filesystems/inotify.txt b/Documentation/filesystems/inotify.txt index cfd02712b83e..51f61db787fb 100644 --- a/Documentation/filesystems/inotify.txt +++ b/Documentation/filesystems/inotify.txt @@ -4,201 +4,10 @@ Document started 15 Mar 2005 by Robert Love <rml@novell.com> +Document updated 4 Jan 2015 by Zhang Zhen <zhenzhang.zhang@huawei.com> + --Deleted obsoleted interface, just refer to manpages for user interface. - -(i) User Interface - -Inotify is controlled by a set of three system calls and normal file I/O on a -returned file descriptor. - -First step in using inotify is to initialise an inotify instance: - - int fd = inotify_init (); - -Each instance is associated with a unique, ordered queue. - -Change events are managed by "watches". A watch is an (object,mask) pair where -the object is a file or directory and the mask is a bit mask of one or more -inotify events that the application wishes to receive. See <linux/inotify.h> -for valid events. A watch is referenced by a watch descriptor, or wd. - -Watches are added via a path to the file. - -Watches on a directory will return events on any files inside of the directory. - -Adding a watch is simple: - - int wd = inotify_add_watch (fd, path, mask); - -Where "fd" is the return value from inotify_init(), path is the path to the -object to watch, and mask is the watch mask (see <linux/inotify.h>). - -You can update an existing watch in the same manner, by passing in a new mask. - -An existing watch is removed via - - int ret = inotify_rm_watch (fd, wd); - -Events are provided in the form of an inotify_event structure that is read(2) -from a given inotify instance. The filename is of dynamic length and follows -the struct. It is of size len. The filename is padded with null bytes to -ensure proper alignment. This padding is reflected in len. - -You can slurp multiple events by passing a large buffer, for example - - size_t len = read (fd, buf, BUF_LEN); - -Where "buf" is a pointer to an array of "inotify_event" structures at least -BUF_LEN bytes in size. The above example will return as many events as are -available and fit in BUF_LEN. - -Each inotify instance fd is also select()- and poll()-able. - -You can find the size of the current event queue via the standard FIONREAD -ioctl on the fd returned by inotify_init(). - -All watches are destroyed and cleaned up on close. - - -(ii) - -Prototypes: - - int inotify_init (void); - int inotify_add_watch (int fd, const char *path, __u32 mask); - int inotify_rm_watch (int fd, __u32 mask); - - -(iii) Kernel Interface - -Inotify's kernel API consists a set of functions for managing watches and an -event callback. - -To use the kernel API, you must first initialize an inotify instance with a set -of inotify_operations. You are given an opaque inotify_handle, which you use -for any further calls to inotify. - - struct inotify_handle *ih = inotify_init(my_event_handler); - -You must provide a function for processing events and a function for destroying -the inotify watch. - - void handle_event(struct inotify_watch *watch, u32 wd, u32 mask, - u32 cookie, const char *name, struct inode *inode) - - watch - the pointer to the inotify_watch that triggered this call - wd - the watch descriptor - mask - describes the event that occurred - cookie - an identifier for synchronizing events - name - the dentry name for affected files in a directory-based event - inode - the affected inode in a directory-based event - - void destroy_watch(struct inotify_watch *watch) - -You may add watches by providing a pre-allocated and initialized inotify_watch -structure and specifying the inode to watch along with an inotify event mask. -You must pin the inode during the call. You will likely wish to embed the -inotify_watch structure in a structure of your own which contains other -information about the watch. Once you add an inotify watch, it is immediately -subject to removal depending on filesystem events. You must grab a reference if -you depend on the watch hanging around after the call. - - inotify_init_watch(&my_watch->iwatch); - inotify_get_watch(&my_watch->iwatch); // optional - s32 wd = inotify_add_watch(ih, &my_watch->iwatch, inode, mask); - inotify_put_watch(&my_watch->iwatch); // optional - -You may use the watch descriptor (wd) or the address of the inotify_watch for -other inotify operations. You must not directly read or manipulate data in the -inotify_watch. Additionally, you must not call inotify_add_watch() more than -once for a given inotify_watch structure, unless you have first called either -inotify_rm_watch() or inotify_rm_wd(). - -To determine if you have already registered a watch for a given inode, you may -call inotify_find_watch(), which gives you both the wd and the watch pointer for -the inotify_watch, or an error if the watch does not exist. - - wd = inotify_find_watch(ih, inode, &watchp); - -You may use container_of() on the watch pointer to access your own data -associated with a given watch. When an existing watch is found, -inotify_find_watch() bumps the refcount before releasing its locks. You must -put that reference with: - - put_inotify_watch(watchp); - -Call inotify_find_update_watch() to update the event mask for an existing watch. -inotify_find_update_watch() returns the wd of the updated watch, or an error if -the watch does not exist. - - wd = inotify_find_update_watch(ih, inode, mask); - -An existing watch may be removed by calling either inotify_rm_watch() or -inotify_rm_wd(). - - int ret = inotify_rm_watch(ih, &my_watch->iwatch); - int ret = inotify_rm_wd(ih, wd); - -A watch may be removed while executing your event handler with the following: - - inotify_remove_watch_locked(ih, iwatch); - -Call inotify_destroy() to remove all watches from your inotify instance and -release it. If there are no outstanding references, inotify_destroy() will call -your destroy_watch op for each watch. - - inotify_destroy(ih); - -When inotify removes a watch, it sends an IN_IGNORED event to your callback. -You may use this event as an indication to free the watch memory. Note that -inotify may remove a watch due to filesystem events, as well as by your request. -If you use IN_ONESHOT, inotify will remove the watch after the first event, at -which point you may call the final inotify_put_watch. - -(iv) Kernel Interface Prototypes - - struct inotify_handle *inotify_init(struct inotify_operations *ops); - - inotify_init_watch(struct inotify_watch *watch); - - s32 inotify_add_watch(struct inotify_handle *ih, - struct inotify_watch *watch, - struct inode *inode, u32 mask); - - s32 inotify_find_watch(struct inotify_handle *ih, struct inode *inode, - struct inotify_watch **watchp); - - s32 inotify_find_update_watch(struct inotify_handle *ih, - struct inode *inode, u32 mask); - - int inotify_rm_wd(struct inotify_handle *ih, u32 wd); - - int inotify_rm_watch(struct inotify_handle *ih, - struct inotify_watch *watch); - - void inotify_remove_watch_locked(struct inotify_handle *ih, - struct inotify_watch *watch); - - void inotify_destroy(struct inotify_handle *ih); - - void get_inotify_watch(struct inotify_watch *watch); - void put_inotify_watch(struct inotify_watch *watch); - - -(v) Internal Kernel Implementation - -Each inotify instance is represented by an inotify_handle structure. -Inotify's userspace consumers also have an inotify_device which is -associated with the inotify_handle, and on which events are queued. - -Each watch is associated with an inotify_watch structure. Watches are chained -off of each associated inotify_handle and each associated inode. - -See fs/notify/inotify/inotify_fsnotify.c and fs/notify/inotify/inotify_user.c -for the locking and lifetime rules. - - -(vi) Rationale +(i) Rationale Q: What is the design decision behind not tying the watch to the open fd of the watched object? diff --git a/Documentation/filesystems/nfs/Exporting b/Documentation/filesystems/nfs/Exporting index c8f036a9b13f..520a4becb75c 100644 --- a/Documentation/filesystems/nfs/Exporting +++ b/Documentation/filesystems/nfs/Exporting @@ -72,24 +72,11 @@ c/ Helper routines to allocate anonymous dentries, and to help attach DCACHE_DISCONNECTED) dentry is allocated and attached. In the case of a directory, care is taken that only one dentry can ever be attached. - d_splice_alias(inode, dentry) or d_materialise_unique(dentry, inode) - will introduce a new dentry into the tree; either the passed-in - dentry or a preexisting alias for the given inode (such as an - anonymous one created by d_obtain_alias), if appropriate. The two - functions differ in their handling of directories with preexisting - aliases: - d_splice_alias will use any existing IS_ROOT dentry, but it will - return -EIO rather than try to move a dentry with a different - parent. This is appropriate for local filesystems, which - should never see such an alias unless the filesystem is - corrupted somehow (for example, if two on-disk directory - entries refer to the same directory.) - d_materialise_unique will attempt to move any dentry. This is - appropriate for distributed filesystems, where finding a - directory other than where we last cached it may be a normal - consequence of concurrent operations on other hosts. - Both functions return NULL when the passed-in dentry is used, - following the calling convention of ->lookup. + d_splice_alias(inode, dentry) will introduce a new dentry into the tree; + either the passed-in dentry or a preexisting alias for the given inode + (such as an anonymous one created by d_obtain_alias), if appropriate. + It returns NULL when the passed-in dentry is used, following the calling + convention of ->lookup. Filesystem Issues diff --git a/Documentation/filesystems/nfs/nfs41-server.txt b/Documentation/filesystems/nfs/nfs41-server.txt index c49cd7e796e7..682a59fabe3f 100644 --- a/Documentation/filesystems/nfs/nfs41-server.txt +++ b/Documentation/filesystems/nfs/nfs41-server.txt @@ -24,11 +24,6 @@ focuses on the mandatory-to-implement NFSv4.1 Sessions, providing "exactly once" semantics and better control and throttling of the resources allocated for each client. -Other NFSv4.1 features, Parallel NFS operations in particular, -are still under development out of tree. -See http://wiki.linux-nfs.org/wiki/index.php/PNFS_prototype_design -for more information. - The table below, taken from the NFSv4.1 document, lists the operations that are mandatory to implement (REQ), optional (OPT), and NFSv4.0 operations that are required not to implement (MNI) @@ -43,9 +38,7 @@ The OPTIONAL features identified and their abbreviations are as follows: The following abbreviations indicate the linux server implementation status. I Implemented NFSv4.1 operations. NS Not Supported. - NS* unimplemented optional feature. - P pNFS features implemented out of tree. - PNS pNFS features that are not supported yet (out of tree). + NS* Unimplemented optional feature. Operations @@ -70,13 +63,13 @@ I | DESTROY_SESSION | REQ | | Section 18.37 | I | EXCHANGE_ID | REQ | | Section 18.35 | I | FREE_STATEID | REQ | | Section 18.38 | | GETATTR | REQ | | Section 18.7 | -P | GETDEVICEINFO | OPT | pNFS (REQ) | Section 18.40 | -P | GETDEVICELIST | OPT | pNFS (OPT) | Section 18.41 | +I | GETDEVICEINFO | OPT | pNFS (REQ) | Section 18.40 | +NS*| GETDEVICELIST | OPT | pNFS (OPT) | Section 18.41 | | GETFH | REQ | | Section 18.8 | NS*| GET_DIR_DELEGATION | OPT | DDELG (REQ) | Section 18.39 | -P | LAYOUTCOMMIT | OPT | pNFS (REQ) | Section 18.42 | -P | LAYOUTGET | OPT | pNFS (REQ) | Section 18.43 | -P | LAYOUTRETURN | OPT | pNFS (REQ) | Section 18.44 | +I | LAYOUTCOMMIT | OPT | pNFS (REQ) | Section 18.42 | +I | LAYOUTGET | OPT | pNFS (REQ) | Section 18.43 | +I | LAYOUTRETURN | OPT | pNFS (REQ) | Section 18.44 | | LINK | OPT | | Section 18.9 | | LOCK | REQ | | Section 18.10 | | LOCKT | REQ | | Section 18.11 | @@ -122,9 +115,9 @@ Callback Operations | | MNI | or OPT) | | +-------------------------+-----------+-------------+---------------+ | CB_GETATTR | OPT | FDELG (REQ) | Section 20.1 | -P | CB_LAYOUTRECALL | OPT | pNFS (REQ) | Section 20.3 | +I | CB_LAYOUTRECALL | OPT | pNFS (REQ) | Section 20.3 | NS*| CB_NOTIFY | OPT | DDELG (REQ) | Section 20.4 | -P | CB_NOTIFY_DEVICEID | OPT | pNFS (OPT) | Section 20.12 | +NS*| CB_NOTIFY_DEVICEID | OPT | pNFS (OPT) | Section 20.12 | NS*| CB_NOTIFY_LOCK | OPT | | Section 20.11 | NS*| CB_PUSH_DELEG | OPT | FDELG (OPT) | Section 20.5 | | CB_RECALL | OPT | FDELG, | Section 20.2 | diff --git a/Documentation/filesystems/nfs/pnfs-block-server.txt b/Documentation/filesystems/nfs/pnfs-block-server.txt new file mode 100644 index 000000000000..2143673cf154 --- /dev/null +++ b/Documentation/filesystems/nfs/pnfs-block-server.txt @@ -0,0 +1,37 @@ +pNFS block layout server user guide + +The Linux NFS server now supports the pNFS block layout extension. In this +case the NFS server acts as Metadata Server (MDS) for pNFS, which in addition +to handling all the metadata access to the NFS export also hands out layouts +to the clients to directly access the underlying block devices that are +shared with the client. + +To use pNFS block layouts with with the Linux NFS server the exported file +system needs to support the pNFS block layouts (currently just XFS), and the +file system must sit on shared storage (typically iSCSI) that is accessible +to the clients in addition to the MDS. As of now the file system needs to +sit directly on the exported volume, striping or concatenation of +volumes on the MDS and clients is not supported yet. + +On the server, pNFS block volume support is automatically if the file system +support it. On the client make sure the kernel has the CONFIG_PNFS_BLOCK +option enabled, the blkmapd daemon from nfs-utils is running, and the +file system is mounted using the NFSv4.1 protocol version (mount -o vers=4.1). + +If the nfsd server needs to fence a non-responding client it calls +/sbin/nfsd-recall-failed with the first argument set to the IP address of +the client, and the second argument set to the device node without the /dev +prefix for the file system to be fenced. Below is an example file that shows +how to translate the device into a serial number from SCSI EVPD 0x80: + +cat > /sbin/nfsd-recall-failed << EOF +#!/bin/sh + +CLIENT="$1" +DEV="/dev/$2" +EVPD=`sg_inq --page=0x80 ${DEV} | \ + grep "Unit serial number:" | \ + awk -F ': ' '{print $2}'` + +echo "fencing client ${CLIENT} serial ${EVPD}" >> /var/log/pnfsd-fence.log +EOF diff --git a/Documentation/filesystems/nfs/pnfs.txt b/Documentation/filesystems/nfs/pnfs.txt index adc81a35fe2d..44a9f2493a88 100644 --- a/Documentation/filesystems/nfs/pnfs.txt +++ b/Documentation/filesystems/nfs/pnfs.txt @@ -57,15 +57,16 @@ bit is set, preventing any new lsegs from being added. layout drivers -------------- -PNFS utilizes what is called layout drivers. The STD defines 3 basic -layout types: "files" "objects" and "blocks". For each of these types -there is a layout-driver with a common function-vectors table which -are called by the nfs-client pnfs-core to implement the different layout -types. +PNFS utilizes what is called layout drivers. The STD defines 4 basic +layout types: "files", "objects", "blocks", and "flexfiles". For each +of these types there is a layout-driver with a common function-vectors +table which are called by the nfs-client pnfs-core to implement the +different layout types. -Files-layout-driver code is in: fs/nfs/nfs4filelayout.c && nfs4filelayoutdev.c +Files-layout-driver code is in: fs/nfs/filelayout/.. directory Objects-layout-deriver code is in: fs/nfs/objlayout/.. directory Blocks-layout-deriver code is in: fs/nfs/blocklayout/.. directory +Flexfiles-layout-driver code is in: fs/nfs/flexfilelayout/.. directory objects-layout setup -------------------- diff --git a/Documentation/filesystems/ocfs2.txt b/Documentation/filesystems/ocfs2.txt index 7618a287aa41..28f8c08201e2 100644 --- a/Documentation/filesystems/ocfs2.txt +++ b/Documentation/filesystems/ocfs2.txt @@ -100,3 +100,7 @@ coherency=full (*) Disallow concurrent O_DIRECT writes, cluster inode coherency=buffered Allow concurrent O_DIRECT writes without EX lock among nodes, which gains high performance at risk of getting stale data on other nodes. +journal_async_commit Commit block can be written to disk without waiting + for descriptor blocks. If enabled older kernels cannot + mount the device. This will enable 'journal_checksum' + internally. diff --git a/Documentation/filesystems/porting b/Documentation/filesystems/porting index 0f3a1390bf00..fa2db081505e 100644 --- a/Documentation/filesystems/porting +++ b/Documentation/filesystems/porting @@ -463,3 +463,11 @@ in your dentry operations instead. of the in-tree instances did). inode_hash_lock is still held, of course, so they are still serialized wrt removal from inode hash, as well as wrt set() callback of iget5_locked(). +-- +[mandatory] + d_materialise_unique() is gone; d_splice_alias() does everything you + need now. Remember that they have opposite orders of arguments ;-/ +-- +[mandatory] + f_dentry is gone; use f_path.dentry, or, better yet, see if you can avoid + it entirely. diff --git a/Documentation/filesystems/proc.txt b/Documentation/filesystems/proc.txt index eb8a10e22f7c..a07ba61662ed 100644 --- a/Documentation/filesystems/proc.txt +++ b/Documentation/filesystems/proc.txt @@ -28,7 +28,7 @@ Table of Contents 1.6 Parallel port info in /proc/parport 1.7 TTY info in /proc/tty 1.8 Miscellaneous kernel statistics in /proc/stat - 1.9 Ext4 file system parameters + 1.9 Ext4 file system parameters 2 Modifying System Parameters @@ -42,6 +42,7 @@ Table of Contents 3.6 /proc/<pid>/comm & /proc/<pid>/task/<tid>/comm 3.7 /proc/<pid>/task/<tid>/children - Information about task children 3.8 /proc/<pid>/fdinfo/<fd> - Information about opened file + 3.9 /proc/<pid>/map_files - Information about memory mapped files 4 Configuring procfs 4.1 Mount options @@ -144,6 +145,8 @@ Table 1-1: Process specific entries in /proc stack Report full stack trace, enable via CONFIG_STACKTRACE smaps a extension based on maps, showing the memory consumption of each mapping and flags associated with it + numa_maps an extension based on maps, showing the memory locality and + binding policy as well as mem usage (in pages) of each mapping. .............................................................................. For example, to get the status information of a process, all you have to do is @@ -488,12 +491,47 @@ To clear the bits for the file mapped pages associated with the process To clear the soft-dirty bit > echo 4 > /proc/PID/clear_refs +To reset the peak resident set size ("high water mark") to the process's +current value: + > echo 5 > /proc/PID/clear_refs + Any other value written to /proc/PID/clear_refs will have no effect. The /proc/pid/pagemap gives the PFN, which can be used to find the pageflags using /proc/kpageflags and number of times a page is mapped using /proc/kpagecount. For detailed explanation, see Documentation/vm/pagemap.txt. +The /proc/pid/numa_maps is an extension based on maps, showing the memory +locality and binding policy, as well as the memory usage (in pages) of +each mapping. The output follows a general format where mapping details get +summarized separated by blank spaces, one mapping per each file line: + +address policy mapping details + +00400000 default file=/usr/local/bin/app mapped=1 active=0 N3=1 kernelpagesize_kB=4 +00600000 default file=/usr/local/bin/app anon=1 dirty=1 N3=1 kernelpagesize_kB=4 +3206000000 default file=/lib64/ld-2.12.so mapped=26 mapmax=6 N0=24 N3=2 kernelpagesize_kB=4 +320621f000 default file=/lib64/ld-2.12.so anon=1 dirty=1 N3=1 kernelpagesize_kB=4 +3206220000 default file=/lib64/ld-2.12.so anon=1 dirty=1 N3=1 kernelpagesize_kB=4 +3206221000 default anon=1 dirty=1 N3=1 kernelpagesize_kB=4 +3206800000 default file=/lib64/libc-2.12.so mapped=59 mapmax=21 active=55 N0=41 N3=18 kernelpagesize_kB=4 +320698b000 default file=/lib64/libc-2.12.so +3206b8a000 default file=/lib64/libc-2.12.so anon=2 dirty=2 N3=2 kernelpagesize_kB=4 +3206b8e000 default file=/lib64/libc-2.12.so anon=1 dirty=1 N3=1 kernelpagesize_kB=4 +3206b8f000 default anon=3 dirty=3 active=1 N3=3 kernelpagesize_kB=4 +7f4dc10a2000 default anon=3 dirty=3 N3=3 kernelpagesize_kB=4 +7f4dc10b4000 default anon=2 dirty=2 active=1 N3=2 kernelpagesize_kB=4 +7f4dc1200000 default file=/anon_hugepage\040(deleted) huge anon=1 dirty=1 N3=1 kernelpagesize_kB=2048 +7fff335f0000 default stack anon=3 dirty=3 N3=3 kernelpagesize_kB=4 +7fff3369d000 default mapped=1 mapmax=35 active=0 N3=1 kernelpagesize_kB=4 + +Where: +"address" is the starting address for the mapping; +"policy" reports the NUMA memory policy set for the mapping (see vm/numa_memory_policy.txt); +"mapping details" summarizes mapping data such as mapping type, page usage counters, +node locality page counters (N0 == node0, N1 == node1, ...) and the kernel page +size, in KB, that is backing the mapping up. + 1.2 Kernel data --------------- @@ -1272,7 +1310,7 @@ softirq. 1.9 Ext4 file system parameters ------------------------------- +------------------------------- Information about mounted ext4 file systems can be found in /proc/fs/ext4. Each mounted filesystem will have a directory in @@ -1763,6 +1801,28 @@ pair provide additional information particular to the objects they represent. with TIMER_ABSTIME option which will be shown in 'settime flags', but 'it_value' still exhibits timer's remaining time. +3.9 /proc/<pid>/map_files - Information about memory mapped files +--------------------------------------------------------------------- +This directory contains symbolic links which represent memory mapped files +the process is maintaining. Example output: + + | lr-------- 1 root root 64 Jan 27 11:24 333c600000-333c620000 -> /usr/lib64/ld-2.18.so + | lr-------- 1 root root 64 Jan 27 11:24 333c81f000-333c820000 -> /usr/lib64/ld-2.18.so + | lr-------- 1 root root 64 Jan 27 11:24 333c820000-333c821000 -> /usr/lib64/ld-2.18.so + | ... + | lr-------- 1 root root 64 Jan 27 11:24 35d0421000-35d0422000 -> /usr/lib64/libselinux.so.1 + | lr-------- 1 root root 64 Jan 27 11:24 400000-41a000 -> /usr/bin/ls + +The name of a link represents the virtual memory bounds of a mapping, i.e. +vm_area_struct::vm_start-vm_area_struct::vm_end. + +The main purpose of the map_files is to retrieve a set of memory mapped +files in a fast way instead of parsing /proc/<pid>/maps or +/proc/<pid>/smaps, both of which contain many more records. At the same +time one can open(2) mappings from the listings of two processes and +comparing their inode numbers to figure out which anonymous memory areas +are actually shared. + ------------------------------------------------------------------------------ Configuring procfs ------------------------------------------------------------------------------ diff --git a/Documentation/filesystems/seq_file.txt b/Documentation/filesystems/seq_file.txt index 8ea3e90ace07..9de4303201e1 100644 --- a/Documentation/filesystems/seq_file.txt +++ b/Documentation/filesystems/seq_file.txt @@ -180,34 +180,38 @@ output must be passed to the seq_file code. Some utility functions have been defined which make this task easy. Most code will simply use seq_printf(), which works pretty much like -printk(), but which requires the seq_file pointer as an argument. It is -common to ignore the return value from seq_printf(), but a function -producing complicated output may want to check that value and quit if -something non-zero is returned; an error return means that the seq_file -buffer has been filled and further output will be discarded. +printk(), but which requires the seq_file pointer as an argument. For straight character output, the following functions may be used: - int seq_putc(struct seq_file *m, char c); - int seq_puts(struct seq_file *m, const char *s); - int seq_escape(struct seq_file *m, const char *s, const char *esc); + seq_putc(struct seq_file *m, char c); + seq_puts(struct seq_file *m, const char *s); + seq_escape(struct seq_file *m, const char *s, const char *esc); The first two output a single character and a string, just like one would expect. seq_escape() is like seq_puts(), except that any character in s which is in the string esc will be represented in octal form in the output. -There is also a pair of functions for printing filenames: +There are also a pair of functions for printing filenames: - int seq_path(struct seq_file *m, struct path *path, char *esc); - int seq_path_root(struct seq_file *m, struct path *path, - struct path *root, char *esc) + int seq_path(struct seq_file *m, const struct path *path, + const char *esc); + int seq_path_root(struct seq_file *m, const struct path *path, + const struct path *root, const char *esc) Here, path indicates the file of interest, and esc is a set of characters which should be escaped in the output. A call to seq_path() will output the path relative to the current process's filesystem root. If a different -root is desired, it can be used with seq_path_root(). Note that, if it -turns out that path cannot be reached from root, the value of root will be -changed in seq_file_root() to a root which *does* work. +root is desired, it can be used with seq_path_root(). If it turns out that +path cannot be reached from root, seq_path_root() returns SEQ_SKIP. + +A function producing complicated output may want to check + bool seq_has_overflowed(struct seq_file *m); +and avoid further seq_<output> calls if true is returned. + +A true return from seq_has_overflowed means that the seq_file buffer will +be discarded and the seq_show function will attempt to allocate a larger +buffer and retry printing. Making it all work diff --git a/Documentation/filesystems/squashfs.txt b/Documentation/filesystems/squashfs.txt index 403c090aca39..e5274f84dc56 100644 --- a/Documentation/filesystems/squashfs.txt +++ b/Documentation/filesystems/squashfs.txt @@ -2,10 +2,10 @@ SQUASHFS 4.0 FILESYSTEM ======================= Squashfs is a compressed read-only filesystem for Linux. -It uses zlib/lzo/xz compression to compress files, inodes and directories. -Inodes in the system are very small and all blocks are packed to minimise -data overhead. Block sizes greater than 4K are supported up to a maximum -of 1Mbytes (default block size 128K). +It uses zlib, lz4, lzo, or xz compression to compress files, inodes and +directories. Inodes in the system are very small and all blocks are packed to +minimise data overhead. Block sizes greater than 4K are supported up to a +maximum of 1Mbytes (default block size 128K). Squashfs is intended for general read-only filesystem use, for archival use (i.e. in cases where a .tar.gz file may be used), and in constrained diff --git a/Documentation/filesystems/vfs.txt b/Documentation/filesystems/vfs.txt index 20bf204426ca..966b22829f3b 100644 --- a/Documentation/filesystems/vfs.txt +++ b/Documentation/filesystems/vfs.txt @@ -591,8 +591,6 @@ struct address_space_operations { int (*releasepage) (struct page *, int); void (*freepage)(struct page *); ssize_t (*direct_IO)(int, struct kiocb *, struct iov_iter *iter, loff_t offset); - struct page* (*get_xip_page)(struct address_space *, sector_t, - int); /* migrate the contents of a page to the specified target */ int (*migratepage) (struct page *, struct page *); int (*launder_page) (struct page *); @@ -748,11 +746,6 @@ struct address_space_operations { and transfer data directly between the storage and the application's address space. - get_xip_page: called by the VM to translate a block number to a page. - The page is valid until the corresponding filesystem is unmounted. - Filesystems that want to use execute-in-place (XIP) need to implement - it. An example implementation can be found in fs/ext2/xip.c. - migrate_page: This is used to compact the physical memory usage. If the VM wants to relocate a page (maybe off a memory card that is signalling imminent failure) it will pass a new page @@ -835,7 +828,7 @@ struct file_operations { ssize_t (*splice_read)(struct file *, struct pipe_inode_info *, size_t, unsigned int); int (*setlease)(struct file *, long arg, struct file_lock **, void **); long (*fallocate)(struct file *, int mode, loff_t offset, loff_t len); - int (*show_fdinfo)(struct seq_file *m, struct file *f); + void (*show_fdinfo)(struct seq_file *m, struct file *f); }; Again, all methods are called without any locks being held, unless diff --git a/Documentation/filesystems/xfs.txt b/Documentation/filesystems/xfs.txt index 5be51fd888bd..0bfafe108357 100644 --- a/Documentation/filesystems/xfs.txt +++ b/Documentation/filesystems/xfs.txt @@ -287,9 +287,9 @@ The following sysctls are available for the XFS filesystem: XFS_ERRLEVEL_LOW: 1 XFS_ERRLEVEL_HIGH: 5 - fs.xfs.panic_mask (Min: 0 Default: 0 Max: 127) + fs.xfs.panic_mask (Min: 0 Default: 0 Max: 255) Causes certain error conditions to call BUG(). Value is a bitmask; - AND together the tags which represent errors which should cause panics: + OR together the tags which represent errors which should cause panics: XFS_NO_PTAG 0 XFS_PTAG_IFLUSH 0x00000001 @@ -299,6 +299,7 @@ The following sysctls are available for the XFS filesystem: XFS_PTAG_SHUTDOWN_CORRUPT 0x00000010 XFS_PTAG_SHUTDOWN_IOERROR 0x00000020 XFS_PTAG_SHUTDOWN_LOGERROR 0x00000040 + XFS_PTAG_FSBLOCK_ZERO 0x00000080 This option is intended for debugging only. @@ -348,16 +349,13 @@ The following sysctls are available for the XFS filesystem: Deprecated Sysctls ================== - fs.xfs.xfsbufd_centisecs (Min: 50 Default: 100 Max: 3000) - Dirty metadata is now tracked by the log subsystem and - flushing is driven by log space and idling demands. The - xfsbufd no longer exists, so this syctl does nothing. +None at present. - Due for removal in 3.14. - fs.xfs.age_buffer_centisecs (Min: 100 Default: 1500 Max: 720000) - Dirty metadata is now tracked by the log subsystem and - flushing is driven by log space and idling demands. The - xfsbufd no longer exists, so this syctl does nothing. +Removed Sysctls +=============== - Due for removal in 3.14. + Name Removed + ---- ------- + fs.xfs.xfsbufd_centisec v3.20 + fs.xfs.age_buffer_centisecs v3.20 diff --git a/Documentation/filesystems/xip.txt b/Documentation/filesystems/xip.txt deleted file mode 100644 index 0466ee569278..000000000000 --- a/Documentation/filesystems/xip.txt +++ /dev/null @@ -1,68 +0,0 @@ -Execute-in-place for file mappings ----------------------------------- - -Motivation ----------- -File mappings are performed by mapping page cache pages to userspace. In -addition, read&write type file operations also transfer data from/to the page -cache. - -For memory backed storage devices that use the block device interface, the page -cache pages are in fact copies of the original storage. Various approaches -exist to work around the need for an extra copy. The ramdisk driver for example -does read the data into the page cache, keeps a reference, and discards the -original data behind later on. - -Execute-in-place solves this issue the other way around: instead of keeping -data in the page cache, the need to have a page cache copy is eliminated -completely. With execute-in-place, read&write type operations are performed -directly from/to the memory backed storage device. For file mappings, the -storage device itself is mapped directly into userspace. - -This implementation was initially written for shared memory segments between -different virtual machines on s390 hardware to allow multiple machines to -share the same binaries and libraries. - -Implementation --------------- -Execute-in-place is implemented in three steps: block device operation, -address space operation, and file operations. - -A block device operation named direct_access is used to retrieve a -reference (pointer) to a block on-disk. The reference is supposed to be -cpu-addressable, physical address and remain valid until the release operation -is performed. A struct block_device reference is used to address the device, -and a sector_t argument is used to identify the individual block. As an -alternative, memory technology devices can be used for this. - -The block device operation is optional, these block devices support it as of -today: -- dcssblk: s390 dcss block device driver - -An address space operation named get_xip_mem is used to retrieve references -to a page frame number and a kernel address. To obtain these values a reference -to an address_space is provided. This function assigns values to the kmem and -pfn parameters. The third argument indicates whether the function should allocate -blocks if needed. - -This address space operation is mutually exclusive with readpage&writepage that -do page cache read/write operations. -The following filesystems support it as of today: -- ext2: the second extended filesystem, see Documentation/filesystems/ext2.txt - -A set of file operations that do utilize get_xip_page can be found in -mm/filemap_xip.c . The following file operation implementations are provided: -- aio_read/aio_write -- readv/writev -- sendfile - -The generic file operations do_sync_read/do_sync_write can be used to implement -classic synchronous IO calls. - -Shortcomings ------------- -This implementation is limited to storage devices that are cpu addressable at -all times (no highmem or such). It works well on rom/ram, but enhancements are -needed to make it work with flash in read+write mode. -Putting the Linux kernel and/or its modules on a xip filesystem does not mean -they are not copied. diff --git a/Documentation/futex-requeue-pi.txt b/Documentation/futex-requeue-pi.txt index 31b16610c416..77b36f59d16b 100644 --- a/Documentation/futex-requeue-pi.txt +++ b/Documentation/futex-requeue-pi.txt @@ -98,7 +98,7 @@ rt_mutex_start_proxy_lock() and rt_mutex_finish_proxy_lock(), which allow the requeue code to acquire an uncontended rt_mutex on behalf of the waiter and to enqueue the waiter on a contended rt_mutex. Two new system calls provide the kernel<->user interface to -requeue_pi: FUTEX_WAIT_REQUEUE_PI and FUTEX_REQUEUE_CMP_PI. +requeue_pi: FUTEX_WAIT_REQUEUE_PI and FUTEX_CMP_REQUEUE_PI. FUTEX_WAIT_REQUEUE_PI is called by the waiter (pthread_cond_wait() and pthread_cond_timedwait()) to block on the initial futex and wait @@ -107,7 +107,7 @@ result of a high-speed collision between futex_wait() and futex_lock_pi(), with some extra logic to check for the additional wake-up scenarios. -FUTEX_REQUEUE_CMP_PI is called by the waker +FUTEX_CMP_REQUEUE_PI is called by the waker (pthread_cond_broadcast() and pthread_cond_signal()) to requeue and possibly wake the waiting tasks. Internally, this system call is still handled by futex_requeue (by passing requeue_pi=1). Before @@ -120,12 +120,12 @@ task as a waiter on the underlying rt_mutex. It is possible that the lock can be acquired at this stage as well, if so, the next waiter is woken to finish the acquisition of the lock. -FUTEX_REQUEUE_PI accepts nr_wake and nr_requeue as arguments, but +FUTEX_CMP_REQUEUE_PI accepts nr_wake and nr_requeue as arguments, but their sum is all that really matters. futex_requeue() will wake or requeue up to nr_wake + nr_requeue tasks. It will wake only as many tasks as it can acquire the lock for, which in the majority of cases should be 0 as good programming practice dictates that the caller of either pthread_cond_broadcast() or pthread_cond_signal() acquire the -mutex prior to making the call. FUTEX_REQUEUE_PI requires that +mutex prior to making the call. FUTEX_CMP_REQUEUE_PI requires that nr_wake=1. nr_requeue should be INT_MAX for broadcast and 0 for signal. diff --git a/Documentation/gdb-kernel-debugging.txt b/Documentation/gdb-kernel-debugging.txt new file mode 100644 index 000000000000..7050ce8794b9 --- /dev/null +++ b/Documentation/gdb-kernel-debugging.txt @@ -0,0 +1,160 @@ +Debugging kernel and modules via gdb +==================================== + +The kernel debugger kgdb, hypervisors like QEMU or JTAG-based hardware +interfaces allow to debug the Linux kernel and its modules during runtime +using gdb. Gdb comes with a powerful scripting interface for python. The +kernel provides a collection of helper scripts that can simplify typical +kernel debugging steps. This is a short tutorial about how to enable and use +them. It focuses on QEMU/KVM virtual machines as target, but the examples can +be transferred to the other gdb stubs as well. + + +Requirements +------------ + + o gdb 7.2+ (recommended: 7.4+) with python support enabled (typically true + for distributions) + + +Setup +----- + + o Create a virtual Linux machine for QEMU/KVM (see www.linux-kvm.org and + www.qemu.org for more details). For cross-development, + http://landley.net/aboriginal/bin keeps a pool of machine images and + toolchains that can be helpful to start from. + + o Build the kernel with CONFIG_GDB_SCRIPTS enabled, but leave + CONFIG_DEBUG_INFO_REDUCED off. If your architecture supports + CONFIG_FRAME_POINTER, keep it enabled. + + o Install that kernel on the guest. + + Alternatively, QEMU allows to boot the kernel directly using -kernel, + -append, -initrd command line switches. This is generally only useful if + you do not depend on modules. See QEMU documentation for more details on + this mode. + + o Enable the gdb stub of QEMU/KVM, either + - at VM startup time by appending "-s" to the QEMU command line + or + - during runtime by issuing "gdbserver" from the QEMU monitor + console + + o cd /path/to/linux-build + + o Start gdb: gdb vmlinux + + Note: Some distros may restrict auto-loading of gdb scripts to known safe + directories. In case gdb reports to refuse loading vmlinux-gdb.py, add + + add-auto-load-safe-path /path/to/linux-build + + to ~/.gdbinit. See gdb help for more details. + + o Attach to the booted guest: + (gdb) target remote :1234 + + +Examples of using the Linux-provided gdb helpers +------------------------------------------------ + + o Load module (and main kernel) symbols: + (gdb) lx-symbols + loading vmlinux + scanning for modules in /home/user/linux/build + loading @0xffffffffa0020000: /home/user/linux/build/net/netfilter/xt_tcpudp.ko + loading @0xffffffffa0016000: /home/user/linux/build/net/netfilter/xt_pkttype.ko + loading @0xffffffffa0002000: /home/user/linux/build/net/netfilter/xt_limit.ko + loading @0xffffffffa00ca000: /home/user/linux/build/net/packet/af_packet.ko + loading @0xffffffffa003c000: /home/user/linux/build/fs/fuse/fuse.ko + ... + loading @0xffffffffa0000000: /home/user/linux/build/drivers/ata/ata_generic.ko + + o Set a breakpoint on some not yet loaded module function, e.g.: + (gdb) b btrfs_init_sysfs + Function "btrfs_init_sysfs" not defined. + Make breakpoint pending on future shared library load? (y or [n]) y + Breakpoint 1 (btrfs_init_sysfs) pending. + + o Continue the target + (gdb) c + + o Load the module on the target and watch the symbols being loaded as well as + the breakpoint hit: + loading @0xffffffffa0034000: /home/user/linux/build/lib/libcrc32c.ko + loading @0xffffffffa0050000: /home/user/linux/build/lib/lzo/lzo_compress.ko + loading @0xffffffffa006e000: /home/user/linux/build/lib/zlib_deflate/zlib_deflate.ko + loading @0xffffffffa01b1000: /home/user/linux/build/fs/btrfs/btrfs.ko + + Breakpoint 1, btrfs_init_sysfs () at /home/user/linux/fs/btrfs/sysfs.c:36 + 36 btrfs_kset = kset_create_and_add("btrfs", NULL, fs_kobj); + + o Dump the log buffer of the target kernel: + (gdb) lx-dmesg + [ 0.000000] Initializing cgroup subsys cpuset + [ 0.000000] Initializing cgroup subsys cpu + [ 0.000000] Linux version 3.8.0-rc4-dbg+ (... + [ 0.000000] Command line: root=/dev/sda2 resume=/dev/sda1 vga=0x314 + [ 0.000000] e820: BIOS-provided physical RAM map: + [ 0.000000] BIOS-e820: [mem 0x0000000000000000-0x000000000009fbff] usable + [ 0.000000] BIOS-e820: [mem 0x000000000009fc00-0x000000000009ffff] reserved + .... + + o Examine fields of the current task struct: + (gdb) p $lx_current().pid + $1 = 4998 + (gdb) p $lx_current().comm + $2 = "modprobe\000\000\000\000\000\000\000" + + o Make use of the per-cpu function for the current or a specified CPU: + (gdb) p $lx_per_cpu("runqueues").nr_running + $3 = 1 + (gdb) p $lx_per_cpu("runqueues", 2).nr_running + $4 = 0 + + o Dig into hrtimers using the container_of helper: + (gdb) set $next = $lx_per_cpu("hrtimer_bases").clock_base[0].active.next + (gdb) p *$container_of($next, "struct hrtimer", "node") + $5 = { + node = { + node = { + __rb_parent_color = 18446612133355256072, + rb_right = 0x0 <irq_stack_union>, + rb_left = 0x0 <irq_stack_union> + }, + expires = { + tv64 = 1835268000000 + } + }, + _softexpires = { + tv64 = 1835268000000 + }, + function = 0xffffffff81078232 <tick_sched_timer>, + base = 0xffff88003fd0d6f0, + state = 1, + start_pid = 0, + start_site = 0xffffffff81055c1f <hrtimer_start_range_ns+20>, + start_comm = "swapper/2\000\000\000\000\000\000" + } + + +List of commands and functions +------------------------------ + +The number of commands and convenience functions may evolve over the time, +this is just a snapshot of the initial version: + + (gdb) apropos lx + function lx_current -- Return current task + function lx_module -- Find module by name and return the module variable + function lx_per_cpu -- Return per-cpu variable + function lx_task_by_pid -- Find Linux task by PID and return the task_struct variable + function lx_thread_info -- Calculate Linux thread_info from task variable + lx-dmesg -- Print Linux kernel log buffer + lx-lsmod -- List currently loaded modules + lx-symbols -- (Re-)load symbols of Linux kernel and currently loaded modules + +Detailed help can be obtained via "help <command-name>" for commands and "help +function <function-name>" for convenience functions. diff --git a/Documentation/gpio/board.txt b/Documentation/gpio/board.txt index 4452786225b8..8b35f51fe7b6 100644 --- a/Documentation/gpio/board.txt +++ b/Documentation/gpio/board.txt @@ -31,7 +31,7 @@ through gpiod_get(). For example: <&gpio 16 GPIO_ACTIVE_HIGH>, /* green */ <&gpio 17 GPIO_ACTIVE_HIGH>; /* blue */ - power-gpio = <&gpio 1 GPIO_ACTIVE_LOW>; + power-gpios = <&gpio 1 GPIO_ACTIVE_LOW>; }; This property will make GPIOs 15, 16 and 17 available to the driver under the diff --git a/Documentation/gpio/consumer.txt b/Documentation/gpio/consumer.txt index 6ce544191ca6..d85fbae451ea 100644 --- a/Documentation/gpio/consumer.txt +++ b/Documentation/gpio/consumer.txt @@ -199,6 +199,33 @@ The active-low state of a GPIO can also be queried using the following call: Note that these functions should only be used with great moderation ; a driver should not have to care about the physical line level. + +Set multiple GPIO outputs with a single function call +----------------------------------------------------- +The following functions set the output values of an array of GPIOs: + + void gpiod_set_array(unsigned int array_size, + struct gpio_desc **desc_array, + int *value_array) + void gpiod_set_raw_array(unsigned int array_size, + struct gpio_desc **desc_array, + int *value_array) + void gpiod_set_array_cansleep(unsigned int array_size, + struct gpio_desc **desc_array, + int *value_array) + void gpiod_set_raw_array_cansleep(unsigned int array_size, + struct gpio_desc **desc_array, + int *value_array) + +The array can be an arbitrary set of GPIOs. The functions will try to set +GPIOs belonging to the same bank or chip simultaneously if supported by the +corresponding chip driver. In that case a significantly improved performance +can be expected. If simultaneous setting is not possible the GPIOs will be set +sequentially. +Note that for optimal performance GPIOs belonging to the same chip should be +contiguous within the array of descriptors. + + GPIOs mapped to IRQs -------------------- GPIO lines can quite often be used as IRQs. You can get the IRQ number @@ -219,6 +246,24 @@ part of the IRQ interface, e.g. IRQF_TRIGGER_FALLING, as are system wakeup capabilities. +GPIOs and ACPI +============== + +On ACPI systems, GPIOs are described by GpioIo()/GpioInt() resources listed by +the _CRS configuration objects of devices. Those resources do not provide +connection IDs (names) for GPIOs, so it is necessary to use an additional +mechanism for this purpose. + +Systems compliant with ACPI 5.1 or newer may provide a _DSD configuration object +which, among other things, may be used to provide connection IDs for specific +GPIOs described by the GpioIo()/GpioInt() resources in _CRS. If that is the +case, it will be handled by the GPIO subsystem automatically. However, if the +_DSD is not present, the mappings between GpioIo()/GpioInt() resources and GPIO +connection IDs need to be provided by device drivers. + +For details refer to Documentation/acpi/gpio-properties.txt + + Interacting With the Legacy GPIO Subsystem ========================================== Many kernel subsystems still handle GPIOs using the legacy integer-based diff --git a/Documentation/gpio/driver.txt b/Documentation/gpio/driver.txt index 31e0b5db55d8..90d0f6aba7a6 100644 --- a/Documentation/gpio/driver.txt +++ b/Documentation/gpio/driver.txt @@ -158,12 +158,12 @@ Locking IRQ usage Input GPIOs can be used as IRQ signals. When this happens, a driver is requested to mark the GPIO as being used as an IRQ: - int gpio_lock_as_irq(struct gpio_chip *chip, unsigned int offset) + int gpiochip_lock_as_irq(struct gpio_chip *chip, unsigned int offset) This will prevent the use of non-irq related GPIO APIs until the GPIO IRQ lock is released: - void gpio_unlock_as_irq(struct gpio_chip *chip, unsigned int offset) + void gpiochip_unlock_as_irq(struct gpio_chip *chip, unsigned int offset) When implementing an irqchip inside a GPIO driver, these two functions should typically be called in the .startup() and .shutdown() callbacks from the diff --git a/Documentation/hwmon/ina2xx b/Documentation/hwmon/ina2xx index 4223c2d3b508..cfd31d94c872 100644 --- a/Documentation/hwmon/ina2xx +++ b/Documentation/hwmon/ina2xx @@ -26,6 +26,12 @@ Supported chips: Datasheet: Publicly available at the Texas Instruments website http://www.ti.com/ + * Texas Instruments INA231 + Prefix: 'ina231' + Addresses: I2C 0x40 - 0x4f + Datasheet: Publicly available at the Texas Instruments website + http://www.ti.com/ + Author: Lothar Felten <l-felten@ti.com> Description @@ -41,9 +47,18 @@ interface. The INA220 monitors both shunt drop and supply voltage. The INA226 is a current shunt and power monitor with an I2C interface. The INA226 monitors both a shunt voltage drop and bus supply voltage. -The INA230 is a high or low side current shunt and power monitor with an I2C -interface. The INA230 monitors both a shunt voltage drop and bus supply voltage. +INA230 and INA231 are high or low side current shunt and power monitors +with an I2C interface. The chips monitor both a shunt voltage drop and +bus supply voltage. -The shunt value in micro-ohms can be set via platform data or device tree. -Please refer to the Documentation/devicetree/bindings/i2c/ina2xx.txt for bindings +The shunt value in micro-ohms can be set via platform data or device tree at +compile-time or via the shunt_resistor attribute in sysfs at run-time. Please +refer to the Documentation/devicetree/bindings/i2c/ina2xx.txt for bindings if the device tree is used. + +Additionally ina226 supports update_interval attribute as described in +Documentation/hwmon/sysfs-interface. Internally the interval is the sum of +bus and shunt voltage conversion times multiplied by the averaging rate. We +don't touch the conversion times and only modify the number of averages. The +lower limit of the update_interval is 2 ms, the upper limit is 2253 ms. +The actual programmed interval may vary from the desired value. diff --git a/Documentation/hwmon/lm75 b/Documentation/hwmon/lm75 index c6a5ff1b4641..67691a0aa41d 100644 --- a/Documentation/hwmon/lm75 +++ b/Documentation/hwmon/lm75 @@ -53,6 +53,11 @@ Supported chips: http://www.ti.com/product/tmp75 http://www.ti.com/product/tmp175 http://www.ti.com/product/tmp275 + * NXP LM75B + Prefix: 'lm75b' + Addresses scanned: none + Datasheet: Publicly available at the NXP website + http://www.nxp.com/documents/data_sheet/LM75B.pdf Author: Frodo Looijaard <frodol@dds.nl> diff --git a/Documentation/hwmon/lm95234 b/Documentation/hwmon/lm95234 index a0e95ddfd372..32b777ef224c 100644 --- a/Documentation/hwmon/lm95234 +++ b/Documentation/hwmon/lm95234 @@ -2,6 +2,10 @@ Kernel driver lm95234 ===================== Supported chips: + * National Semiconductor / Texas Instruments LM95233 + Addresses scanned: I2C 0x18, 0x2a, 0x2b + Datasheet: Publicly available at the Texas Instruments website + http://www.ti.com/product/lm95233 * National Semiconductor / Texas Instruments LM95234 Addresses scanned: I2C 0x18, 0x4d, 0x4e Datasheet: Publicly available at the Texas Instruments website @@ -13,11 +17,12 @@ Author: Guenter Roeck <linux@roeck-us.net> Description ----------- -LM95234 is an 11-bit digital temperature sensor with a 2-wire System Management -Bus (SMBus) interface and TrueTherm technology that can very accurately monitor -the temperature of four remote diodes as well as its own temperature. -The four remote diodes can be external devices such as microprocessors, -graphics processors or diode-connected 2N3904s. The LM95234's TruTherm +LM95233 and LM95234 are 11-bit digital temperature sensors with a 2-wire +System Management Bus (SMBus) interface and TrueTherm technology +that can very accurately monitor the temperature of two (LM95233) +or four (LM95234) remote diodes as well as its own temperature. +The remote diodes can be external devices such as microprocessors, +graphics processors or diode-connected 2N3904s. The chip's TruTherm beta compensation technology allows sensing of 90 nm or 65 nm process thermal diodes accurately. diff --git a/Documentation/hwmon/lm95245 b/Documentation/hwmon/lm95245 index 77eaf2812d25..d755901f58c4 100644 --- a/Documentation/hwmon/lm95245 +++ b/Documentation/hwmon/lm95245 @@ -2,10 +2,14 @@ Kernel driver lm95245 ================== Supported chips: - * National Semiconductor LM95245 + * TI LM95235 + Addresses scanned: I2C 0x18, 0x29, 0x4c + Datasheet: Publicly available at the TI website + http://www.ti.com/lit/ds/symlink/lm95235.pdf + * TI / National Semiconductor LM95245 Addresses scanned: I2C 0x18, 0x19, 0x29, 0x4c, 0x4d - Datasheet: Publicly available at the National Semiconductor website - http://www.national.com/mpf/LM/LM95245.html + Datasheet: Publicly available at the TI website + http://www.ti.com/lit/ds/symlink/lm95245.pdf Author: Alexander Stein <alexander.stein@systec-electronic.com> @@ -13,10 +17,10 @@ Author: Alexander Stein <alexander.stein@systec-electronic.com> Description ----------- -The LM95245 is an 11-bit digital temperature sensor with a 2-wire System +LM95235 and LM95245 are 11-bit digital temperature sensors with a 2-wire System Management Bus (SMBus) interface and TruTherm technology that can monitor the temperature of a remote diode as well as its own temperature. -The LM95245 can be used to very accurately monitor the temperature of +The chips can be used to very accurately monitor the temperature of external devices such as microprocessors. All temperature values are given in millidegrees Celsius. Local temperature diff --git a/Documentation/hwmon/nct6775 b/Documentation/hwmon/nct6775 index 4e9ef60e8c6c..f0dd3d2fec96 100644 --- a/Documentation/hwmon/nct6775 +++ b/Documentation/hwmon/nct6775 @@ -8,11 +8,15 @@ Kernel driver NCT6775 ===================== Supported chips: + * Nuvoton NCT6102D/NCT6104D/NCT6106D + Prefix: 'nct6106' + Addresses scanned: ISA address retrieved from Super I/O registers + Datasheet: Available from the Nuvoton web site * Nuvoton NCT5572D/NCT6771F/NCT6772F/NCT6775F/W83677HG-I Prefix: 'nct6775' Addresses scanned: ISA address retrieved from Super I/O registers Datasheet: Available from Nuvoton upon request - * Nuvoton NCT5577D/NCT6776D/NCT6776F + * Nuvoton NCT5573D/NCT5577D/NCT6776D/NCT6776F Prefix: 'nct6776' Addresses scanned: ISA address retrieved from Super I/O registers Datasheet: Available from Nuvoton upon request @@ -20,6 +24,14 @@ Supported chips: Prefix: 'nct6779' Addresses scanned: ISA address retrieved from Super I/O registers Datasheet: Available from Nuvoton upon request + * Nuvoton NCT6791D + Prefix: 'nct6791' + Addresses scanned: ISA address retrieved from Super I/O registers + Datasheet: Available from Nuvoton upon request + * Nuvoton NCT6792D + Prefix: 'nct6792' + Addresses scanned: ISA address retrieved from Super I/O registers + Datasheet: Available from Nuvoton upon request Authors: Guenter Roeck <linux@roeck-us.net> diff --git a/Documentation/hwmon/nct7802 b/Documentation/hwmon/nct7802 new file mode 100644 index 000000000000..2e00f5e344bc --- /dev/null +++ b/Documentation/hwmon/nct7802 @@ -0,0 +1,32 @@ +Kernel driver nct7802 +===================== + +Supported chips: + * Nuvoton NCT7802Y + Prefix: 'nct7802' + Addresses scanned: I2C 0x28..0x2f + Datasheet: Available from Nuvoton web site + +Authors: + Guenter Roeck <linux@roeck-us.net> + +Description +----------- + +This driver implements support for the Nuvoton NCT7802Y hardware monitoring +chip. NCT7802Y supports 6 temperature sensors, 5 voltage sensors, and 3 fan +speed sensors. + +The chip also supports intelligent fan speed control. This functionality is +not currently supported by the driver. + +Tested Boards and BIOS Versions +------------------------------- + +The driver has been reported to work with the following boards and +BIOS versions. + +Board BIOS version +--------------------------------------------------------------- +Kontron COMe-bSC2 CHR2E934.001.GGO +Kontron COMe-bIP2 CCR2E212 diff --git a/Documentation/hwmon/tmp401 b/Documentation/hwmon/tmp401 index f91e3fa7e5ec..8eb88e974055 100644 --- a/Documentation/hwmon/tmp401 +++ b/Documentation/hwmon/tmp401 @@ -18,6 +18,10 @@ Supported chips: Prefix: 'tmp432' Addresses scanned: I2C 0x4c, 0x4d Datasheet: http://focus.ti.com/docs/prod/folders/print/tmp432.html + * Texas Instruments TMP435 + Prefix: 'tmp435' + Addresses scanned: I2C 0x37, 0x48 - 0x4f + Datasheet: http://focus.ti.com/docs/prod/folders/print/tmp435.html Authors: Hans de Goede <hdegoede@redhat.com> @@ -27,8 +31,8 @@ Description ----------- This driver implements support for Texas Instruments TMP401, TMP411, -TMP431, and TMP432 chips. These chips implement one or two remote and -one local temperature sensors. Temperature is measured in degrees +TMP431, TMP432 and TMP435 chips. These chips implement one or two remote +and one local temperature sensors. Temperature is measured in degrees Celsius. Resolution of the remote sensor is 0.0625 degree. Local sensor resolution can be set to 0.5, 0.25, 0.125 or 0.0625 degree (not supported by the driver so far, so using the default resolution of 0.5 diff --git a/Documentation/i2c/busses/i2c-i801 b/Documentation/i2c/busses/i2c-i801 index 793c83dac738..82f48f774afb 100644 --- a/Documentation/i2c/busses/i2c-i801 +++ b/Documentation/i2c/busses/i2c-i801 @@ -29,6 +29,7 @@ Supported adapters: * Intel Wildcat Point-LP (PCH) * Intel BayTrail (SOC) * Intel Sunrise Point-H (PCH) + * Intel Sunrise Point-LP (PCH) Datasheets: Publicly available at the Intel website On Intel Patsburg and later chipsets, both the normal host SMBus controller diff --git a/Documentation/i2c/upgrading-clients b/Documentation/i2c/upgrading-clients index 8e5fbd88c7d1..ccba3ffd6e80 100644 --- a/Documentation/i2c/upgrading-clients +++ b/Documentation/i2c/upgrading-clients @@ -79,11 +79,10 @@ static struct i2c_driver example_driver = { .driver = { .owner = THIS_MODULE, .name = "example", + .pm = &example_pm_ops, }, .attach_adapter = example_attach_adapter, .detach_client = example_detach, - .suspend = example_suspend, - .resume = example_resume, }; @@ -272,10 +271,9 @@ static struct i2c_driver example_driver = { .driver = { .owner = THIS_MODULE, .name = "example", + .pm = &example_pm_ops, }, .id_table = example_idtable, .probe = example_probe, .remove = example_remove, - .suspend = example_suspend, - .resume = example_resume, }; diff --git a/Documentation/i2c/writing-clients b/Documentation/i2c/writing-clients index 6b344b516bff..a755b141fa4a 100644 --- a/Documentation/i2c/writing-clients +++ b/Documentation/i2c/writing-clients @@ -36,6 +36,7 @@ MODULE_DEVICE_TABLE(i2c, foo_idtable); static struct i2c_driver foo_driver = { .driver = { .name = "foo", + .pm = &foo_pm_ops, /* optional */ }, .id_table = foo_idtable, @@ -47,8 +48,6 @@ static struct i2c_driver foo_driver = { .address_list = normal_i2c, .shutdown = foo_shutdown, /* optional */ - .suspend = foo_suspend, /* optional */ - .resume = foo_resume, /* optional */ .command = foo_command, /* optional, deprecated */ } @@ -279,8 +278,9 @@ Power Management If your I2C device needs special handling when entering a system low power state -- like putting a transceiver into a low power mode, or -activating a system wakeup mechanism -- do that in the suspend() method. -The resume() method should reverse what the suspend() method does. +activating a system wakeup mechanism -- do that by implementing the +appropriate callbacks for the dev_pm_ops of the driver (like suspend +and resume). These are standard driver model calls, and they work just like they would for any other driver stack. The calls can sleep, and can use diff --git a/Documentation/ia64/kvm.txt b/Documentation/ia64/kvm.txt deleted file mode 100644 index ffb5c80bec3e..000000000000 --- a/Documentation/ia64/kvm.txt +++ /dev/null @@ -1,83 +0,0 @@ -Currently, kvm module is in EXPERIMENTAL stage on IA64. This means that -interfaces are not stable enough to use. So, please don't run critical -applications in virtual machine. -We will try our best to improve it in future versions! - - Guide: How to boot up guests on kvm/ia64 - -This guide is to describe how to enable kvm support for IA-64 systems. - -1. Get the kvm source from git.kernel.org. - Userspace source: - git clone git://git.kernel.org/pub/scm/virt/kvm/kvm-userspace.git - Kernel Source: - git clone git://git.kernel.org/pub/scm/linux/kernel/git/xiantao/kvm-ia64.git - -2. Compile the source code. - 2.1 Compile userspace code: - (1)cd ./kvm-userspace - (2)./configure - (3)cd kernel - (4)make sync LINUX= $kernel_dir (kernel_dir is the directory of kernel source.) - (5)cd .. - (6)make qemu - (7)cd qemu; make install - - 2.2 Compile kernel source code: - (1) cd ./$kernel_dir - (2) Make menuconfig - (3) Enter into virtualization option, and choose kvm. - (4) make - (5) Once (4) done, make modules_install - (6) Make initrd, and use new kernel to reboot up host machine. - (7) Once (6) done, cd $kernel_dir/arch/ia64/kvm - (8) insmod kvm.ko; insmod kvm-intel.ko - -Note: For step 2, please make sure that host page size == TARGET_PAGE_SIZE of qemu, otherwise, may fail. - -3. Get Guest Firmware named as Flash.fd, and put it under right place: - (1) If you have the guest firmware (binary) released by Intel Corp for Xen, use it directly. - - (2) If you have no firmware at hand, Please download its source from - hg clone http://xenbits.xensource.com/ext/efi-vfirmware.hg - you can get the firmware's binary in the directory of efi-vfirmware.hg/binaries. - - (3) Rename the firmware you owned to Flash.fd, and copy it to /usr/local/share/qemu - -4. Boot up Linux or Windows guests: - 4.1 Create or install a image for guest boot. If you have xen experience, it should be easy. - - 4.2 Boot up guests use the following command. - /usr/local/bin/qemu-system-ia64 -smp xx -m 512 -hda $your_image - (xx is the number of virtual processors for the guest, now the maximum value is 4) - -5. Known possible issue on some platforms with old Firmware. - -In the event of strange host crash issues, try to solve it through either of the following ways: - -(1): Upgrade your Firmware to the latest one. - -(2): Applying the below patch to kernel source. -diff --git a/arch/ia64/kernel/pal.S b/arch/ia64/kernel/pal.S -index 0b53344..f02b0f7 100644 ---- a/arch/ia64/kernel/pal.S -+++ b/arch/ia64/kernel/pal.S -@@ -84,7 +84,8 @@ GLOBAL_ENTRY(ia64_pal_call_static) - mov ar.pfs = loc1 - mov rp = loc0 - ;; -- srlz.d // serialize restoration of psr.l -+ srlz.i // serialize restoration of psr.l -+ ;; - br.ret.sptk.many b0 - END(ia64_pal_call_static) - -6. Bug report: - If you found any issues when use kvm/ia64, Please post the bug info to kvm-ia64-devel mailing list. - https://lists.sourceforge.net/lists/listinfo/kvm-ia64-devel/ - -Thanks for your interest! Let's work together, and make kvm/ia64 stronger and stronger! - - - Xiantao Zhang <xiantao.zhang@intel.com> - 2008.3.10 diff --git a/Documentation/input/xpad.txt b/Documentation/input/xpad.txt index 7cc9a436e6a1..d1b23f295db4 100644 --- a/Documentation/input/xpad.txt +++ b/Documentation/input/xpad.txt @@ -1,18 +1,22 @@ -xpad - Linux USB driver for X-Box gamepads +xpad - Linux USB driver for Xbox compatible controllers -This is the very first release of a driver for X-Box gamepads. -Basically, this was hacked away in just a few hours, so don't expect -miracles. +This driver exposes all first-party and third-party Xbox compatible +controllers. It has a long history and has enjoyed considerable usage +as Window's xinput library caused most PC games to focus on Xbox +controller compatibility. -In particular, there is currently NO support for the rumble pack. -You won't find many ff-aware linux applications anyway. +Due to backwards compatibility all buttons are reported as digital. +This only effects Original Xbox controllers. All later controller models +have only digital face buttons. + +Rumble is supported on some models of Xbox 360 controllers but not of +Original Xbox controllers nor on Xbox One controllers. As of writing +the Xbox One's rumble protocol has not been reverse engineered but in +the future could be supported. 0. Notes -------- - -Driver updated for kernel 2.6.17.11. (Based on a patch for 2.6.11.4.) - The number of buttons/axes reported varies based on 3 things: - if you are using a known controller - if you are using a known dance pad @@ -20,12 +24,16 @@ The number of buttons/axes reported varies based on 3 things: module configuration for "Map D-PAD to buttons rather than axes for unknown pads" (module option dpad_to_buttons) -If you set dpad_to_buttons to 0 and you are using an unknown device (one -not listed below), the driver will map the directional pad to axes (X/Y), -if you said N it will map the d-pad to buttons, which is needed for dance -style games to function correctly. The default is Y. +If you set dpad_to_buttons to N and you are using an unknown device +the driver will map the directional pad to axes (X/Y). +If you said Y it will map the d-pad to buttons, which is needed for dance +style games to function correctly. The default is Y. + +dpad_to_buttons has no effect for known pads. A erroneous commit message +claimed dpad_to_buttons could be used to force behavior on known devices. +This is not true. Both dpad_to_buttons and triggers_to_buttons only affect +unknown controllers. -dpad_to_buttons has no effect for known pads. 0.1 Normal Controllers ---------------------- @@ -80,17 +88,29 @@ to the list of supported devices, ensuring that it will work out of the box in the future. -1. USB adapter +1. USB adapters -------------- +All generations of Xbox controllers speak USB over the wire. +- Original Xbox controllers use a proprietary connector and require adapters. +- Wireless Xbox 360 controllers require a 'Xbox 360 Wireless Gaming Receiver + for Windows' +- Wired Xbox 360 controllers use standard USB connectors. +- Xbox One controllers can be wireless but speak Wi-Fi Direct and are not + yet supported. +- Xbox One controllers can be wired and use standard Micro-USB connectors. + -Before you can actually use the driver, you need to get yourself an -adapter cable to connect the X-Box controller to your Linux-Box. You -can buy these online fairly cheap, or build your own. + +1.1 Original Xbox USB adapters +-------------- +Using this driver with an Original Xbox controller requires an +adapter cable to break out the proprietary connector's pins to USB. +You can buy these online fairly cheap, or build your own. Such a cable is pretty easy to build. The Controller itself is a USB compound device (a hub with three ports for two expansion slots and the controller device) with the only difference in a nonstandard connector -(5 pins vs. 4 on standard USB connector). +(5 pins vs. 4 on standard USB 1.0 connectors). You just need to solder a USB connector onto the cable and keep the yellow wire unconnected. The other pins have the same order on both @@ -102,26 +122,41 @@ original one. You can buy an extension cable and cut that instead. That way, you can still use the controller with your X-Box, if you have one ;) + 2. Driver Installation ---------------------- -Once you have the adapter cable and the controller is connected, you need -to load your USB subsystem and should cat /proc/bus/usb/devices. -There should be an entry like the one at the end [4]. +Once you have the adapter cable, if needed, and the controller connected +the xpad module should be auto loaded. To confirm you can cat +/proc/bus/usb/devices. There should be an entry like the one at the end [4]. + + -Currently (as of version 0.0.6), the following devices are included: - original Microsoft XBOX controller (US), vendor=0x045e, product=0x0202 - smaller Microsoft XBOX controller (US), vendor=0x045e, product=0x0289 +3. Supported Controllers +------------------------ +For a full list of supported controllers and associated vendor and product +IDs see the xpad_device[] array[6]. + +As of the historic version 0.0.6 (2006-10-10) the following devices +were supported: + original Microsoft XBOX controller (US), vendor=0x045e, product=0x0202 + smaller Microsoft XBOX controller (US), vendor=0x045e, product=0x0289 original Microsoft XBOX controller (Japan), vendor=0x045e, product=0x0285 - InterAct PowerPad Pro (Germany), vendor=0x05fd, product=0x107a - RedOctane Xbox Dance Pad (US), vendor=0x0c12, product=0x8809 + InterAct PowerPad Pro (Germany), vendor=0x05fd, product=0x107a + RedOctane Xbox Dance Pad (US), vendor=0x0c12, product=0x8809 + +Unrecognized models of Xbox controllers should function as Generic +Xbox controllers. Unrecognized Dance Pad controllers require setting +the module option 'dpad_to_buttons'. + +If you have an unrecognized controller please see 0.3 - Unknown Controllers -The driver should work with xbox pads not listed above as well, however -you will need to do something extra for dance pads to work. -If you have a controller not listed above, see 0.3 - Unknown Controllers +4. Manual Testing +----------------- +To test this driver's functionality you may use 'jstest'. -If you compiled and installed the driver, test the functionality: +For example: > modprobe xpad > modprobe joydev > jstest /dev/js0 @@ -134,7 +169,8 @@ show 20 inputs (6 axes, 14 buttons). It works? Voila, you're done ;) -3. Thanks + +5. Thanks --------- I have to thank ITO Takayuki for the detailed info on his site @@ -145,14 +181,14 @@ His useful info and both the usb-skeleton as well as the iforce input driver the basic functionality. -4. References -------------- -1. http://euc.jp/periphs/xbox-controller.ja.html (ITO Takayuki) -2. http://xpad.xbox-scene.com/ -3. http://www.markosweb.com/www/xboxhackz.com/ +6. References +------------- -4. /proc/bus/usb/devices - dump from InterAct PowerPad Pro (Germany): +[1]: http://euc.jp/periphs/xbox-controller.ja.html (ITO Takayuki) +[2]: http://xpad.xbox-scene.com/ +[3]: http://www.markosweb.com/www/xboxhackz.com/ +[4]: /proc/bus/usb/devices - dump from InterAct PowerPad Pro (Germany): T: Bus=01 Lev=03 Prnt=04 Port=00 Cnt=01 Dev#= 5 Spd=12 MxCh= 0 D: Ver= 1.10 Cls=00(>ifc ) Sub=00 Prot=00 MxPS=32 #Cfgs= 1 @@ -162,7 +198,7 @@ I: If#= 0 Alt= 0 #EPs= 2 Cls=58(unk. ) Sub=42 Prot=00 Driver=(none) E: Ad=81(I) Atr=03(Int.) MxPS= 32 Ivl= 10ms E: Ad=02(O) Atr=03(Int.) MxPS= 32 Ivl= 10ms -5. /proc/bus/usb/devices - dump from Redoctane Xbox Dance Pad (US): +[5]: /proc/bus/usb/devices - dump from Redoctane Xbox Dance Pad (US): T: Bus=01 Lev=02 Prnt=09 Port=00 Cnt=01 Dev#= 10 Spd=12 MxCh= 0 D: Ver= 1.10 Cls=00(>ifc ) Sub=00 Prot=00 MxPS= 8 #Cfgs= 1 @@ -173,7 +209,12 @@ I: If#= 0 Alt= 0 #EPs= 2 Cls=58(unk. ) Sub=42 Prot=00 Driver=xpad E: Ad=82(I) Atr=03(Int.) MxPS= 32 Ivl=4ms E: Ad=02(O) Atr=03(Int.) MxPS= 32 Ivl=4ms --- +[6]: http://lxr.free-electrons.com/ident?i=xpad_device + + + +7. Historic Edits +----------------- Marko Friedemann <mfr@bmx-chemnitz.de> 2002-07-16 - original doc @@ -181,3 +222,5 @@ Marko Friedemann <mfr@bmx-chemnitz.de> Dominic Cerquetti <binary1230@yahoo.com> 2005-03-19 - added stuff for dance pads, new d-pad->axes mappings + +Later changes may be viewed with 'git log Documentation/input/xpad.txt' diff --git a/Documentation/kasan.txt b/Documentation/kasan.txt new file mode 100644 index 000000000000..092fc10961fe --- /dev/null +++ b/Documentation/kasan.txt @@ -0,0 +1,170 @@ +Kernel address sanitizer +================ + +0. Overview +=========== + +Kernel Address sanitizer (KASan) is a dynamic memory error detector. It provides +a fast and comprehensive solution for finding use-after-free and out-of-bounds +bugs. + +KASan uses compile-time instrumentation for checking every memory access, +therefore you will need a certain version of GCC > 4.9.2 + +Currently KASan is supported only for x86_64 architecture and requires that the +kernel be built with the SLUB allocator. + +1. Usage +========= + +To enable KASAN configure kernel with: + + CONFIG_KASAN = y + +and choose between CONFIG_KASAN_OUTLINE and CONFIG_KASAN_INLINE. Outline/inline +is compiler instrumentation types. The former produces smaller binary the +latter is 1.1 - 2 times faster. Inline instrumentation requires GCC 5.0 or +latter. + +Currently KASAN works only with the SLUB memory allocator. +For better bug detection and nicer report, enable CONFIG_STACKTRACE and put +at least 'slub_debug=U' in the boot cmdline. + +To disable instrumentation for specific files or directories, add a line +similar to the following to the respective kernel Makefile: + + For a single file (e.g. main.o): + KASAN_SANITIZE_main.o := n + + For all files in one directory: + KASAN_SANITIZE := n + +1.1 Error reports +========== + +A typical out of bounds access report looks like this: + +================================================================== +BUG: AddressSanitizer: out of bounds access in kmalloc_oob_right+0x65/0x75 [test_kasan] at addr ffff8800693bc5d3 +Write of size 1 by task modprobe/1689 +============================================================================= +BUG kmalloc-128 (Not tainted): kasan error +----------------------------------------------------------------------------- + +Disabling lock debugging due to kernel taint +INFO: Allocated in kmalloc_oob_right+0x3d/0x75 [test_kasan] age=0 cpu=0 pid=1689 + __slab_alloc+0x4b4/0x4f0 + kmem_cache_alloc_trace+0x10b/0x190 + kmalloc_oob_right+0x3d/0x75 [test_kasan] + init_module+0x9/0x47 [test_kasan] + do_one_initcall+0x99/0x200 + load_module+0x2cb3/0x3b20 + SyS_finit_module+0x76/0x80 + system_call_fastpath+0x12/0x17 +INFO: Slab 0xffffea0001a4ef00 objects=17 used=7 fp=0xffff8800693bd728 flags=0x100000000004080 +INFO: Object 0xffff8800693bc558 @offset=1368 fp=0xffff8800693bc720 + +Bytes b4 ffff8800693bc548: 00 00 00 00 00 00 00 00 5a 5a 5a 5a 5a 5a 5a 5a ........ZZZZZZZZ +Object ffff8800693bc558: 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b kkkkkkkkkkkkkkkk +Object ffff8800693bc568: 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b kkkkkkkkkkkkkkkk +Object ffff8800693bc578: 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b kkkkkkkkkkkkkkkk +Object ffff8800693bc588: 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b kkkkkkkkkkkkkkkk +Object ffff8800693bc598: 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b kkkkkkkkkkkkkkkk +Object ffff8800693bc5a8: 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b kkkkkkkkkkkkkkkk +Object ffff8800693bc5b8: 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b kkkkkkkkkkkkkkkk +Object ffff8800693bc5c8: 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b a5 kkkkkkkkkkkkkkk. +Redzone ffff8800693bc5d8: cc cc cc cc cc cc cc cc ........ +Padding ffff8800693bc718: 5a 5a 5a 5a 5a 5a 5a 5a ZZZZZZZZ +CPU: 0 PID: 1689 Comm: modprobe Tainted: G B 3.18.0-rc1-mm1+ #98 +Hardware name: QEMU Standard PC (i440FX + PIIX, 1996), BIOS rel-1.7.5-0-ge51488c-20140602_164612-nilsson.home.kraxel.org 04/01/2014 + ffff8800693bc000 0000000000000000 ffff8800693bc558 ffff88006923bb78 + ffffffff81cc68ae 00000000000000f3 ffff88006d407600 ffff88006923bba8 + ffffffff811fd848 ffff88006d407600 ffffea0001a4ef00 ffff8800693bc558 +Call Trace: + [<ffffffff81cc68ae>] dump_stack+0x46/0x58 + [<ffffffff811fd848>] print_trailer+0xf8/0x160 + [<ffffffffa00026a7>] ? kmem_cache_oob+0xc3/0xc3 [test_kasan] + [<ffffffff811ff0f5>] object_err+0x35/0x40 + [<ffffffffa0002065>] ? kmalloc_oob_right+0x65/0x75 [test_kasan] + [<ffffffff8120b9fa>] kasan_report_error+0x38a/0x3f0 + [<ffffffff8120a79f>] ? kasan_poison_shadow+0x2f/0x40 + [<ffffffff8120b344>] ? kasan_unpoison_shadow+0x14/0x40 + [<ffffffff8120a79f>] ? kasan_poison_shadow+0x2f/0x40 + [<ffffffffa00026a7>] ? kmem_cache_oob+0xc3/0xc3 [test_kasan] + [<ffffffff8120a995>] __asan_store1+0x75/0xb0 + [<ffffffffa0002601>] ? kmem_cache_oob+0x1d/0xc3 [test_kasan] + [<ffffffffa0002065>] ? kmalloc_oob_right+0x65/0x75 [test_kasan] + [<ffffffffa0002065>] kmalloc_oob_right+0x65/0x75 [test_kasan] + [<ffffffffa00026b0>] init_module+0x9/0x47 [test_kasan] + [<ffffffff810002d9>] do_one_initcall+0x99/0x200 + [<ffffffff811e4e5c>] ? __vunmap+0xec/0x160 + [<ffffffff81114f63>] load_module+0x2cb3/0x3b20 + [<ffffffff8110fd70>] ? m_show+0x240/0x240 + [<ffffffff81115f06>] SyS_finit_module+0x76/0x80 + [<ffffffff81cd3129>] system_call_fastpath+0x12/0x17 +Memory state around the buggy address: + ffff8800693bc300: fc fc fc fc fc fc fc fc fc fc fc fc fc fc fc fc + ffff8800693bc380: fc fc 00 00 00 00 00 00 00 00 00 00 00 00 00 fc + ffff8800693bc400: fc fc fc fc fc fc fc fc fc fc fc fc fc fc fc fc + ffff8800693bc480: fc fc fc fc fc fc fc fc fc fc fc fc fc fc fc fc + ffff8800693bc500: fc fc fc fc fc fc fc fc fc fc fc 00 00 00 00 00 +>ffff8800693bc580: 00 00 00 00 00 00 00 00 00 00 03 fc fc fc fc fc + ^ + ffff8800693bc600: fc fc fc fc fc fc fc fc fc fc fc fc fc fc fc fc + ffff8800693bc680: fc fc fc fc fc fc fc fc fc fc fc fc fc fc fc fc + ffff8800693bc700: fc fc fc fc fb fb fb fb fb fb fb fb fb fb fb fb + ffff8800693bc780: fb fb fb fb fb fb fb fb fb fb fb fb fb fb fb fb + ffff8800693bc800: fb fb fb fb fb fb fb fb fb fb fb fb fb fb fb fb +================================================================== + +First sections describe slub object where bad access happened. +See 'SLUB Debug output' section in Documentation/vm/slub.txt for details. + +In the last section the report shows memory state around the accessed address. +Reading this part requires some more understanding of how KASAN works. + +Each 8 bytes of memory are encoded in one shadow byte as accessible, +partially accessible, freed or they can be part of a redzone. +We use the following encoding for each shadow byte: 0 means that all 8 bytes +of the corresponding memory region are accessible; number N (1 <= N <= 7) means +that the first N bytes are accessible, and other (8 - N) bytes are not; +any negative value indicates that the entire 8-byte word is inaccessible. +We use different negative values to distinguish between different kinds of +inaccessible memory like redzones or freed memory (see mm/kasan/kasan.h). + +In the report above the arrows point to the shadow byte 03, which means that +the accessed address is partially accessible. + + +2. Implementation details +======================== + +From a high level, our approach to memory error detection is similar to that +of kmemcheck: use shadow memory to record whether each byte of memory is safe +to access, and use compile-time instrumentation to check shadow memory on each +memory access. + +AddressSanitizer dedicates 1/8 of kernel memory to its shadow memory +(e.g. 16TB to cover 128TB on x86_64) and uses direct mapping with a scale and +offset to translate a memory address to its corresponding shadow address. + +Here is the function witch translate an address to its corresponding shadow +address: + +static inline void *kasan_mem_to_shadow(const void *addr) +{ + return ((unsigned long)addr >> KASAN_SHADOW_SCALE_SHIFT) + + KASAN_SHADOW_OFFSET; +} + +where KASAN_SHADOW_SCALE_SHIFT = 3. + +Compile-time instrumentation used for checking memory accesses. Compiler inserts +function calls (__asan_load*(addr), __asan_store*(addr)) before each memory +access of size 1, 2, 4, 8 or 16. These functions check whether memory access is +valid or not by checking corresponding shadow memory. + +GCC 5.0 has possibility to perform inline instrumentation. Instead of making +function calls GCC directly inserts the code to check the shadow memory. +This option significantly enlarges kernel but it gives x1.1-x2 performance +boost over outline instrumented kernel. diff --git a/Documentation/kdump/kdump.txt b/Documentation/kdump/kdump.txt index 6c0b9f27e465..bc4bd5a44b88 100644 --- a/Documentation/kdump/kdump.txt +++ b/Documentation/kdump/kdump.txt @@ -471,6 +471,13 @@ format. Crash is available on Dave Anderson's site at the following URL: http://people.redhat.com/~anderson/ +Trigger Kdump on WARN() +======================= + +The kernel parameter, panic_on_warn, calls panic() in all WARN() paths. This +will cause a kdump to occur at the panic() call. In cases where a user wants +to specify this during runtime, /proc/sys/kernel/panic_on_warn can be set to 1 +to achieve the same behaviour. Contact ======= diff --git a/Documentation/kernel-parameters.txt b/Documentation/kernel-parameters.txt index 479f33204a37..bfcb1a62a7b4 100644 --- a/Documentation/kernel-parameters.txt +++ b/Documentation/kernel-parameters.txt @@ -829,6 +829,15 @@ bytes respectively. Such letter suffixes can also be entirely omitted. CONFIG_DEBUG_PAGEALLOC, hence this option will not help tracking down these problems. + debug_pagealloc= + [KNL] When CONFIG_DEBUG_PAGEALLOC is set, this + parameter enables the feature at boot time. In + default, it is disabled. We can avoid allocating huge + chunk of memory for debug pagealloc if we don't enable + it at boot time and the system will work mostly same + with the kernel built without CONFIG_DEBUG_PAGEALLOC. + on: enable the feature + debugpat [X86] Enable PAT debugging decnet.addr= [HW,NET] @@ -961,6 +970,18 @@ bytes respectively. Such letter suffixes can also be entirely omitted. smh Use ARM semihosting calls for early console. + s3c2410,<addr> + s3c2412,<addr> + s3c2440,<addr> + s3c6400,<addr> + s5pv210,<addr> + exynos4210,<addr> + Use early console provided by serial driver available + on Samsung SoCs, requires selecting proper type and + a correct base address of the selected UART port. The + serial port must already be setup and configured. + Options are not yet supported. + earlyprintk= [X86,SH,BLACKFIN,ARM,M68k] earlyprintk=vga earlyprintk=efi @@ -1228,9 +1249,7 @@ bytes respectively. Such letter suffixes can also be entirely omitted. multiple times interleaved with hugepages= to reserve huge pages of different sizes. Valid pages sizes on x86-64 are 2M (when the CPU supports "pse") and 1G - (when the CPU supports the "pdpe1gb" cpuinfo flag) - Note that 1GB pages can only be allocated at boot time - using hugepages= and not freed afterwards. + (when the CPU supports the "pdpe1gb" cpuinfo flag). hvc_iucv= [S390] Number of z/VM IUCV hypervisor console (HVC) terminal devices. Valid values: 0..8 @@ -1270,6 +1289,7 @@ bytes respectively. Such letter suffixes can also be entirely omitted. i8042.notimeout [HW] Ignore timeout condition signalled by controller i8042.reset [HW] Reset the controller during init and cleanup i8042.unlock [HW] Unlock (ignore) the keylock + i8042.kbdreset [HW] Reset device connected to KBD port i810= [HW,DRM] @@ -1369,6 +1389,10 @@ bytes respectively. Such letter suffixes can also be entirely omitted. Formats: { "ima" | "ima-ng" } Default: "ima-ng" + ima_template_fmt= + [IMA] Define a custom template format. + Format: { "field1|...|fieldN" } + ima.ahash_minsize= [IMA] Minimum file size for asynchronous hash usage Format: <min_file_size> Set the minimal file size for using asynchronous hash. @@ -1446,6 +1470,21 @@ bytes respectively. Such letter suffixes can also be entirely omitted. disable Do not enable intel_pstate as the default scaling driver for the supported processors + force + Enable intel_pstate on systems that prohibit it by default + in favor of acpi-cpufreq. Forcing the intel_pstate driver + instead of acpi-cpufreq may disable platform features, such + as thermal controls and power capping, that rely on ACPI + P-States information being indicated to OSPM and therefore + should be used with caution. This option does not work with + processors that aren't supported by the intel_pstate driver + or on platforms that use pcc-cpufreq instead of acpi-cpufreq. + no_hwp + Do not enable hardware P state control (HWP) + if available. + hwp_only + Only load intel_pstate on systems which support + hardware P state control (HWP) if available. intremap= [X86-64, Intel-IOMMU] on enable Interrupt Remapping (default) @@ -1470,6 +1509,8 @@ bytes respectively. Such letter suffixes can also be entirely omitted. forcesac soft pt [x86, IA-64] + nobypass [PPC/POWERNV] + Disable IOMMU bypass, using IOMMU for PCI devices. io7= [HW] IO7 for Marvel based alpha systems @@ -2503,12 +2544,21 @@ bytes respectively. Such letter suffixes can also be entirely omitted. OSS [HW,OSS] See Documentation/sound/oss/oss-parameters.txt + page_owner= [KNL] Boot-time page_owner enabling option. + Storage of the information about who allocated + each page is disabled in default. With this switch, + we can turn it on. + on: enable the feature + panic= [KNL] Kernel behaviour on panic: delay <timeout> timeout > 0: seconds before rebooting timeout = 0: wait forever timeout < 0: reboot immediately Format: <timeout> + panic_on_warn panic() instead of WARN(). Useful to cause kdump + on a WARN(). + crash_kexec_post_notifiers Run kdump after running panic-notifiers and dumping kmsg. This only for the users who doubt kdump always @@ -2940,6 +2990,13 @@ bytes respectively. Such letter suffixes can also be entirely omitted. quiescent states. Units are jiffies, minimum value is one, and maximum value is HZ. + rcutree.kthread_prio= [KNL,BOOT] + Set the SCHED_FIFO priority of the RCU + per-CPU kthreads (rcuc/N). This value is also + used for the priority of the RCU boost threads + (rcub/N). Valid values are 1-99 and the default + is 1 (the least-favored priority). + rcutree.rcu_nocb_leader_stride= [KNL] Set the number of NOCB kthread groups, which defaults to the square root of the number of @@ -3089,6 +3146,15 @@ bytes respectively. Such letter suffixes can also be entirely omitted. messages. Disable with a value less than or equal to zero. + rcupdate.rcu_self_test= [KNL] + Run the RCU early boot self tests + + rcupdate.rcu_self_test_bh= [KNL] + Run the RCU bh early boot self tests + + rcupdate.rcu_self_test_sched= [KNL] + Run the RCU sched early boot self tests + rdinit= [KNL] Format: <full_path> Run specified binary instead of /init from the ramdisk, @@ -3158,6 +3224,18 @@ bytes respectively. Such letter suffixes can also be entirely omitted. retain_initrd [RAM] Keep initrd memory after extraction + rfkill.default_state= + 0 "airplane mode". All wifi, bluetooth, wimax, gps, fm, + etc. communication is blocked by default. + 1 Unblocked. + + rfkill.master_switch_mode= + 0 The "airplane mode" button does nothing. + 1 The "airplane mode" button toggles between everything + blocked and the previous configuration. + 2 The "airplane mode" button toggles between everything + blocked and everything unblocked. + rhash_entries= [KNL,NET] Set number of hash buckets for route cache @@ -3412,6 +3490,13 @@ bytes respectively. Such letter suffixes can also be entirely omitted. neutralize any effect of /proc/sys/kernel/sysrq. Useful for debugging. + tcpmhash_entries= [KNL,NET] + Set the number of tcp_metrics_hash slots. + Default value is 8192 or 16384 depending on total + ram pages. This is used to specify the TCP metrics + cache size. See Documentation/networking/ip-sysctl.txt + "tcp_no_metrics_save" section for more details. + tdfx= [HW,DRM] test_suspend= [SUSPEND][,N] @@ -3501,7 +3586,7 @@ bytes respectively. Such letter suffixes can also be entirely omitted. are saved. trace_buf_size=nn[KMG] - [FTRACE] will set tracing buffer size. + [FTRACE] will set tracing buffer size on each cpu. trace_event=[event-list] [FTRACE] Set and start specified trace events in order @@ -3524,6 +3609,24 @@ bytes respectively. Such letter suffixes can also be entirely omitted. See also Documentation/trace/ftrace.txt "trace options" section. + tp_printk[FTRACE] + Have the tracepoints sent to printk as well as the + tracing ring buffer. This is useful for early boot up + where the system hangs or reboots and does not give the + option for reading the tracing buffer or performing a + ftrace_dump_on_oops. + + To turn off having tracepoints sent to printk, + echo 0 > /proc/sys/kernel/tracepoint_printk + Note, echoing 1 into this file without the + tracepoint_printk kernel cmdline option has no effect. + + ** CAUTION ** + + Having tracepoints sent to printk() and activating high + frequency tracepoints such as irq or sched, can cause + the system to live lock. + traceoff_on_warning [FTRACE] enable this option to disable tracing when a warning is hit. This turns off "tracing_on". Tracing can diff --git a/Documentation/kobject.txt b/Documentation/kobject.txt index f87241dfed87..1be59a3a521c 100644 --- a/Documentation/kobject.txt +++ b/Documentation/kobject.txt @@ -173,7 +173,7 @@ This should be done only after any attributes or children of the kobject have been initialized properly, as userspace will instantly start to look for them when this call happens. -When the kobject is removed from the kernel (details on how to do that is +When the kobject is removed from the kernel (details on how to do that are below), the uevent for KOBJ_REMOVE will be automatically created by the kobject core, so the caller does not have to worry about doing that by hand. diff --git a/Documentation/kprobes.txt b/Documentation/kprobes.txt index 4227ec2e3ab2..1488b6525eb6 100644 --- a/Documentation/kprobes.txt +++ b/Documentation/kprobes.txt @@ -702,7 +702,8 @@ a virtual address that is no longer valid (module init sections, module virtual addresses that correspond to modules that've been unloaded), such probes are marked with [GONE]. If the probe is temporarily disabled, such probes are marked with [DISABLED]. If the probe is optimized, it is -marked with [OPTIMIZED]. +marked with [OPTIMIZED]. If the probe is ftrace-based, it is marked with +[FTRACE]. /sys/kernel/debug/kprobes/enabled: Turn kprobes ON/OFF forcibly. diff --git a/Documentation/kselftest.txt b/Documentation/kselftest.txt new file mode 100644 index 000000000000..a87d840bacfe --- /dev/null +++ b/Documentation/kselftest.txt @@ -0,0 +1,69 @@ +Linux Kernel Selftests + +The kernel contains a set of "self tests" under the tools/testing/selftests/ +directory. These are intended to be small unit tests to exercise individual +code paths in the kernel. + +On some systems, hot-plug tests could hang forever waiting for cpu and +memory to be ready to be offlined. A special hot-plug target is created +to run full range of hot-plug tests. In default mode, hot-plug tests run +in safe mode with a limited scope. In limited mode, cpu-hotplug test is +run on a single cpu as opposed to all hotplug capable cpus, and memory +hotplug test is run on 2% of hotplug capable memory instead of 10%. + +Running the selftests (hotplug tests are run in limited mode) +============================================================= + +To build the tests: + $ make -C tools/testing/selftests + + +To run the tests: + $ make -C tools/testing/selftests run_tests + +To build and run the tests with a single command, use: + $ make kselftest + +- note that some tests will require root privileges. + + +Running a subset of selftests +======================================== +You can use the "TARGETS" variable on the make command line to specify +single test to run, or a list of tests to run. + +To run only tests targeted for a single subsystem: + $ make -C tools/testing/selftests TARGETS=ptrace run_tests + +You can specify multiple tests to build and run: + $ make TARGETS="size timers" kselftest + +See the top-level tools/testing/selftests/Makefile for the list of all +possible targets. + + +Running the full range hotplug selftests +======================================== + +To build the hotplug tests: + $ make -C tools/testing/selftests hotplug + +To run the hotplug tests: + $ make -C tools/testing/selftests run_hotplug + +- note that some tests will require root privileges. + + +Contributing new tests +====================== + +In general, the rules for for selftests are + + * Do as much as you can if you're not root; + + * Don't take too long; + + * Don't break the build on any architecture, and + + * Don't cause the top-level "make run_tests" to fail if your feature is + unconfigured. diff --git a/Documentation/local_ops.txt b/Documentation/local_ops.txt index 300da4bdfdbd..407576a23317 100644 --- a/Documentation/local_ops.txt +++ b/Documentation/local_ops.txt @@ -8,6 +8,11 @@ to implement them for any given architecture and shows how they can be used properly. It also stresses on the precautions that must be taken when reading those local variables across CPUs when the order of memory writes matters. +Note that local_t based operations are not recommended for general kernel use. +Please use the this_cpu operations instead unless there is really a special purpose. +Most uses of local_t in the kernel have been replaced by this_cpu operations. +this_cpu operations combine the relocation with the local_t like semantics in +a single instruction and yield more compact and faster executing code. * Purpose of local atomic operations @@ -87,10 +92,10 @@ the per cpu variable. For instance : local_inc(&get_cpu_var(counters)); put_cpu_var(counters); -If you are already in a preemption-safe context, you can directly use -__get_cpu_var() instead. +If you are already in a preemption-safe context, you can use +this_cpu_ptr() instead. - local_inc(&__get_cpu_var(counters)); + local_inc(this_cpu_ptr(&counters)); @@ -134,7 +139,7 @@ static void test_each(void *info) { /* Increment the counter from a non preemptible context */ printk("Increment on cpu %d\n", smp_processor_id()); - local_inc(&__get_cpu_var(counters)); + local_inc(this_cpu_ptr(&counters)); /* This is what incrementing the variable would look like within a * preemptible context (it disables preemption) : diff --git a/Documentation/locking/00-INDEX b/Documentation/locking/00-INDEX new file mode 100644 index 000000000000..c256c9bee2a4 --- /dev/null +++ b/Documentation/locking/00-INDEX @@ -0,0 +1,16 @@ +00-INDEX + - this file. +lockdep-design.txt + - documentation on the runtime locking correctness validator. +lockstat.txt + - info on collecting statistics on locks (and contention). +mutex-design.txt + - info on the generic mutex subsystem. +rt-mutex-design.txt + - description of the RealTime mutex implementation design. +rt-mutex.txt + - desc. of RT-mutex subsystem with PI (Priority Inheritance) support. +spinlocks.txt + - info on using spinlocks to provide exclusive access in kernel. +ww-mutex-design.txt + - Intro to Mutex wait/would deadlock handling.s diff --git a/Documentation/locking/lglock.txt b/Documentation/locking/lglock.txt new file mode 100644 index 000000000000..a6971e34fabe --- /dev/null +++ b/Documentation/locking/lglock.txt @@ -0,0 +1,166 @@ +lglock - local/global locks for mostly local access patterns +------------------------------------------------------------ + +Origin: Nick Piggin's VFS scalability series introduced during + 2.6.35++ [1] [2] +Location: kernel/locking/lglock.c + include/linux/lglock.h +Users: currently only the VFS and stop_machine related code + +Design Goal: +------------ + +Improve scalability of globally used large data sets that are +distributed over all CPUs as per_cpu elements. + +To manage global data structures that are partitioned over all CPUs +as per_cpu elements but can be mostly handled by CPU local actions +lglock will be used where the majority of accesses are cpu local +reading and occasional cpu local writing with very infrequent +global write access. + + +* deal with things locally whenever possible + - very fast access to the local per_cpu data + - reasonably fast access to specific per_cpu data on a different + CPU +* while making global action possible when needed + - by expensive access to all CPUs locks - effectively + resulting in a globally visible critical section. + +Design: +------- + +Basically it is an array of per_cpu spinlocks with the +lg_local_lock/unlock accessing the local CPUs lock object and the +lg_local_lock_cpu/unlock_cpu accessing a remote CPUs lock object +the lg_local_lock has to disable preemption as migration protection so +that the reference to the local CPUs lock does not go out of scope. +Due to the lg_local_lock/unlock only touching cpu-local resources it +is fast. Taking the local lock on a different CPU will be more +expensive but still relatively cheap. + +One can relax the migration constraints by acquiring the current +CPUs lock with lg_local_lock_cpu, remember the cpu, and release that +lock at the end of the critical section even if migrated. This should +give most of the performance benefits without inhibiting migration +though needs careful considerations for nesting of lglocks and +consideration of deadlocks with lg_global_lock. + +The lg_global_lock/unlock locks all underlying spinlocks of all +possible CPUs (including those off-line). The preemption disable/enable +are needed in the non-RT kernels to prevent deadlocks like: + + on cpu 1 + + task A task B + lg_global_lock + got cpu 0 lock + <<<< preempt <<<< + lg_local_lock_cpu for cpu 0 + spin on cpu 0 lock + +On -RT this deadlock scenario is resolved by the arch_spin_locks in the +lglocks being replaced by rt_mutexes which resolve the above deadlock +by boosting the lock-holder. + + +Implementation: +--------------- + +The initial lglock implementation from Nick Piggin used some complex +macros to generate the lglock/brlock in lglock.h - they were later +turned into a set of functions by Andi Kleen [7]. The change to functions +was motivated by the presence of multiple lock users and also by them +being easier to maintain than the generating macros. This change to +functions is also the basis to eliminated the restriction of not +being initializeable in kernel modules (the remaining problem is that +locks are not explicitly initialized - see lockdep-design.txt) + +Declaration and initialization: +------------------------------- + + #include <linux/lglock.h> + + DEFINE_LGLOCK(name) + or: + DEFINE_STATIC_LGLOCK(name); + + lg_lock_init(&name, "lockdep_name_string"); + + on UP this is mapped to DEFINE_SPINLOCK(name) in both cases, note + also that as of 3.18-rc6 all declaration in use are of the _STATIC_ + variant (and it seems that the non-static was never in use). + lg_lock_init is initializing the lockdep map only. + +Usage: +------ + +From the locking semantics it is a spinlock. It could be called a +locality aware spinlock. lg_local_* behaves like a per_cpu +spinlock and lg_global_* like a global spinlock. +No surprises in the API. + + lg_local_lock(*lglock); + access to protected per_cpu object on this CPU + lg_local_unlock(*lglock); + + lg_local_lock_cpu(*lglock, cpu); + access to protected per_cpu object on other CPU cpu + lg_local_unlock_cpu(*lglock, cpu); + + lg_global_lock(*lglock); + access all protected per_cpu objects on all CPUs + lg_global_unlock(*lglock); + + There are no _trylock variants of the lglocks. + +Note that the lg_global_lock/unlock has to iterate over all possible +CPUs rather than the actually present CPUs or a CPU could go off-line +with a held lock [4] and that makes it very expensive. A discussion on +these issues can be found at [5] + +Constraints: +------------ + + * currently the declaration of lglocks in kernel modules is not + possible, though this should be doable with little change. + * lglocks are not recursive. + * suitable for code that can do most operations on the CPU local + data and will very rarely need the global lock + * lg_global_lock/unlock is *very* expensive and does not scale + * on UP systems all lg_* primitives are simply spinlocks + * in PREEMPT_RT the spinlock becomes an rt-mutex and can sleep but + does not change the tasks state while sleeping [6]. + * in PREEMPT_RT the preempt_disable/enable in lg_local_lock/unlock + is downgraded to a migrate_disable/enable, the other + preempt_disable/enable are downgraded to barriers [6]. + The deadlock noted for non-RT above is resolved due to rt_mutexes + boosting the lock-holder in this case which arch_spin_locks do + not do. + +lglocks were designed for very specific problems in the VFS and probably +only are the right answer in these corner cases. Any new user that looks +at lglocks probably wants to look at the seqlock and RCU alternatives as +her first choice. There are also efforts to resolve the RCU issues that +currently prevent using RCU in place of view remaining lglocks. + +Note on brlock history: +----------------------- + +The 'Big Reader' read-write spinlocks were originally introduced by +Ingo Molnar in 2000 (2.4/2.5 kernel series) and removed in 2003. They +later were introduced by the VFS scalability patch set in 2.6 series +again as the "big reader lock" brlock [2] variant of lglock which has +been replaced by seqlock primitives or by RCU based primitives in the +3.13 kernel series as was suggested in [3] in 2003. The brlock was +entirely removed in the 3.13 kernel series. + +Link: 1 http://lkml.org/lkml/2010/8/2/81 +Link: 2 http://lwn.net/Articles/401738/ +Link: 3 http://lkml.org/lkml/2003/3/9/205 +Link: 4 https://lkml.org/lkml/2011/8/24/185 +Link: 5 http://lkml.org/lkml/2011/12/18/189 +Link: 6 https://www.kernel.org/pub/linux/kernel/projects/rt/ + patch series - lglocks-rt.patch.patch +Link: 7 http://lkml.org/lkml/2012/3/5/26 diff --git a/Documentation/locking/lockdep-design.txt b/Documentation/locking/lockdep-design.txt index 5dbc99c04f6e..5001280e9d82 100644 --- a/Documentation/locking/lockdep-design.txt +++ b/Documentation/locking/lockdep-design.txt @@ -34,7 +34,7 @@ The validator tracks lock-class usage history into 4n + 1 separate state bits: - 'ever held with STATE enabled' - 'ever held as readlock with STATE enabled' -Where STATE can be either one of (kernel/lockdep_states.h) +Where STATE can be either one of (kernel/locking/lockdep_states.h) - hardirq - softirq - reclaim_fs diff --git a/Documentation/locking/lockstat.txt b/Documentation/locking/lockstat.txt index 7428773a1e69..568bbbacee91 100644 --- a/Documentation/locking/lockstat.txt +++ b/Documentation/locking/lockstat.txt @@ -121,6 +121,11 @@ show the header with column descriptions. Lines 05-18 and 20-31 show the actual statistics. These statistics come in two parts; the actual stats separated by a short separator (line 08, 13) from the contention points. +Lines 09-12 show the first 4 recorded contention points (the code +which tries to get the lock) and lines 14-17 show the first 4 recorded +contended points (the lock holder). It is possible that the max +con-bounces point is missing in the statistics. + The first lock (05-18) is a read/write lock, and shows two lines above the short separator. The contention points don't match the column descriptors, they have two: contentions and [<IP>] symbol. The second set of contention diff --git a/Documentation/mailbox.txt b/Documentation/mailbox.txt index 60f43ff629aa..1092ad9578da 100644 --- a/Documentation/mailbox.txt +++ b/Documentation/mailbox.txt @@ -53,7 +53,7 @@ static void message_from_remote(struct mbox_client *cl, void *mssg) { struct demo_client *dc = container_of(mbox_client, struct demo_client, cl); - if (dc->aysnc) { + if (dc->async) { if (is_an_ack(mssg)) { /* An ACK to our last sample sent */ return; /* Or do something else here */ diff --git a/Documentation/memory-barriers.txt b/Documentation/memory-barriers.txt index 22a969cdd476..ca2387ef27ab 100644 --- a/Documentation/memory-barriers.txt +++ b/Documentation/memory-barriers.txt @@ -121,22 +121,22 @@ For example, consider the following sequence of events: The set of accesses as seen by the memory system in the middle can be arranged in 24 different combinations: - STORE A=3, STORE B=4, x=LOAD A->3, y=LOAD B->4 - STORE A=3, STORE B=4, y=LOAD B->4, x=LOAD A->3 - STORE A=3, x=LOAD A->3, STORE B=4, y=LOAD B->4 - STORE A=3, x=LOAD A->3, y=LOAD B->2, STORE B=4 - STORE A=3, y=LOAD B->2, STORE B=4, x=LOAD A->3 - STORE A=3, y=LOAD B->2, x=LOAD A->3, STORE B=4 - STORE B=4, STORE A=3, x=LOAD A->3, y=LOAD B->4 + STORE A=3, STORE B=4, y=LOAD A->3, x=LOAD B->4 + STORE A=3, STORE B=4, x=LOAD B->4, y=LOAD A->3 + STORE A=3, y=LOAD A->3, STORE B=4, x=LOAD B->4 + STORE A=3, y=LOAD A->3, x=LOAD B->2, STORE B=4 + STORE A=3, x=LOAD B->2, STORE B=4, y=LOAD A->3 + STORE A=3, x=LOAD B->2, y=LOAD A->3, STORE B=4 + STORE B=4, STORE A=3, y=LOAD A->3, x=LOAD B->4 STORE B=4, ... ... and can thus result in four different combinations of values: - x == 1, y == 2 - x == 1, y == 4 - x == 3, y == 2 - x == 3, y == 4 + x == 2, y == 1 + x == 2, y == 3 + x == 4, y == 1 + x == 4, y == 3 Furthermore, the stores committed by a CPU to the memory system may not be @@ -269,6 +269,50 @@ And there are a number of things that _must_ or _must_not_ be assumed: STORE *(A + 4) = Y; STORE *A = X; STORE {*A, *(A + 4) } = {X, Y}; +And there are anti-guarantees: + + (*) These guarantees do not apply to bitfields, because compilers often + generate code to modify these using non-atomic read-modify-write + sequences. Do not attempt to use bitfields to synchronize parallel + algorithms. + + (*) Even in cases where bitfields are protected by locks, all fields + in a given bitfield must be protected by one lock. If two fields + in a given bitfield are protected by different locks, the compiler's + non-atomic read-modify-write sequences can cause an update to one + field to corrupt the value of an adjacent field. + + (*) These guarantees apply only to properly aligned and sized scalar + variables. "Properly sized" currently means variables that are + the same size as "char", "short", "int" and "long". "Properly + aligned" means the natural alignment, thus no constraints for + "char", two-byte alignment for "short", four-byte alignment for + "int", and either four-byte or eight-byte alignment for "long", + on 32-bit and 64-bit systems, respectively. Note that these + guarantees were introduced into the C11 standard, so beware when + using older pre-C11 compilers (for example, gcc 4.6). The portion + of the standard containing this guarantee is Section 3.14, which + defines "memory location" as follows: + + memory location + either an object of scalar type, or a maximal sequence + of adjacent bit-fields all having nonzero width + + NOTE 1: Two threads of execution can update and access + separate memory locations without interfering with + each other. + + NOTE 2: A bit-field and an adjacent non-bit-field member + are in separate memory locations. The same applies + to two bit-fields, if one is declared inside a nested + structure declaration and the other is not, or if the two + are separated by a zero-length bit-field declaration, + or if they are separated by a non-bit-field member + declaration. It is not safe to concurrently update two + bit-fields in the same structure if all members declared + between them are also bit-fields, no matter what the + sizes of those intervening bit-fields happen to be. + ========================= WHAT ARE MEMORY BARRIERS? @@ -694,6 +738,24 @@ Please note once again that the stores to 'b' differ. If they were identical, as noted earlier, the compiler could pull this store outside of the 'if' statement. +You must also be careful not to rely too much on boolean short-circuit +evaluation. Consider this example: + + q = ACCESS_ONCE(a); + if (a || 1 > 0) + ACCESS_ONCE(b) = 1; + +Because the second condition is always true, the compiler can transform +this example as following, defeating control dependency: + + q = ACCESS_ONCE(a); + ACCESS_ONCE(b) = 1; + +This example underscores the need to ensure that the compiler cannot +out-guess your code. More generally, although ACCESS_ONCE() does force +the compiler to actually emit code for a given load, it does not force +the compiler to use the results. + Finally, control dependencies do -not- provide transitivity. This is demonstrated by two related examples, with the initial values of x and y both being zero: @@ -732,7 +794,7 @@ In summary: However, they do -not- guarantee any other sort of ordering: Not prior loads against later loads, nor prior stores against later anything. If you need these other forms of ordering, - use smb_rmb(), smp_wmb(), or, in the case of prior stores and + use smp_rmb(), smp_wmb(), or, in the case of prior stores and later loads, smp_mb(). (*) If both legs of the "if" statement begin with identical stores @@ -1615,6 +1677,48 @@ There are some more advanced barrier functions: operations" subsection for information on where to use these. + (*) dma_wmb(); + (*) dma_rmb(); + + These are for use with consistent memory to guarantee the ordering + of writes or reads of shared memory accessible to both the CPU and a + DMA capable device. + + For example, consider a device driver that shares memory with a device + and uses a descriptor status value to indicate if the descriptor belongs + to the device or the CPU, and a doorbell to notify it when new + descriptors are available: + + if (desc->status != DEVICE_OWN) { + /* do not read data until we own descriptor */ + dma_rmb(); + + /* read/modify data */ + read_data = desc->data; + desc->data = write_data; + + /* flush modifications before status update */ + dma_wmb(); + + /* assign ownership */ + desc->status = DEVICE_OWN; + + /* force memory to sync before notifying device via MMIO */ + wmb(); + + /* notify device of new descriptors */ + writel(DESC_NOTIFY, doorbell); + } + + The dma_rmb() allows us guarantee the device has released ownership + before we read the data from the descriptor, and he dma_wmb() allows + us to guarantee the data is written to the descriptor before the device + can see it now has ownership. The wmb() is needed to guarantee that the + cache coherent memory writes have completed before attempting a write to + the cache incoherent MMIO region. + + See Documentation/DMA-API.txt for more information on consistent memory. + MMIO WRITE BARRIER ------------------ @@ -2465,10 +2569,15 @@ functions: Please refer to the PCI specification for more information on interactions between PCI transactions. - (*) readX_relaxed() + (*) readX_relaxed(), writeX_relaxed() - These are similar to readX(), but are not guaranteed to be ordered in any - way. Be aware that there is no I/O read barrier available. + These are similar to readX() and writeX(), but provide weaker memory + ordering guarantees. Specifically, they do not guarantee ordering with + respect to normal memory accesses (e.g. DMA buffers) nor do they guarantee + ordering with respect to LOCK or UNLOCK operations. If the latter is + required, an mmiowb() barrier can be used. Note that relaxed accesses to + the same peripheral are guaranteed to be ordered with respect to each + other. (*) ioreadX(), iowriteX() diff --git a/Documentation/mic/mpssd/Makefile b/Documentation/mic/mpssd/Makefile index 0f3156888048..f47fe6ba7300 100644 --- a/Documentation/mic/mpssd/Makefile +++ b/Documentation/mic/mpssd/Makefile @@ -1,5 +1,5 @@ # List of programs to build -hostprogs-y := mpssd +hostprogs-$(CONFIG_X86_64) := mpssd mpssd-objs := mpssd.o sysfs.o diff --git a/Documentation/misc-devices/mei/mei-client-bus.txt b/Documentation/misc-devices/mei/mei-client-bus.txt index f83910a8ce76..743be4ec8989 100644 --- a/Documentation/misc-devices/mei/mei-client-bus.txt +++ b/Documentation/misc-devices/mei/mei-client-bus.txt @@ -1,9 +1,10 @@ Intel(R) Management Engine (ME) Client bus API -=============================================== +============================================== Rationale ========= + MEI misc character device is useful for dedicated applications to send and receive data to the many FW appliance found in Intel's ME from the user space. However for some of the ME functionalities it make sense to leverage existing software @@ -17,7 +18,8 @@ the existing code. MEI CL bus API -=========== +============== + A driver implementation for an MEI Client is very similar to existing bus based device drivers. The driver registers itself as an MEI CL bus driver through the mei_cl_driver structure: @@ -55,6 +57,7 @@ received buffers. Example ======= + As a theoretical example let's pretend the ME comes with a "contact" NFC IP. The driver init and exit routines for this device would look like: @@ -69,11 +72,11 @@ static struct mei_cl_device_id contact_mei_cl_tbl[] = { MODULE_DEVICE_TABLE(mei_cl, contact_mei_cl_tbl); static struct mei_cl_driver contact_driver = { - .id_table = contact_mei_tbl, - .name = CONTACT_DRIVER_NAME, + .id_table = contact_mei_tbl, + .name = CONTACT_DRIVER_NAME, - .probe = contact_probe, - .remove = contact_remove, + .probe = contact_probe, + .remove = contact_remove, }; static int contact_init(void) @@ -109,7 +112,7 @@ int contact_probe(struct mei_cl_device *dev, struct mei_cl_device_id *id) mei_cl_register_event_cb(dev, contact_event_cb, contact); return 0; - } +} In the probe routine the driver first enable the MEI device and then registers an ME bus event handler which is as close as it can get to registering a diff --git a/Documentation/misc-devices/mei/mei.txt b/Documentation/misc-devices/mei/mei.txt index 15bba1aeba9a..8d47501bba0a 100644 --- a/Documentation/misc-devices/mei/mei.txt +++ b/Documentation/misc-devices/mei/mei.txt @@ -1,8 +1,8 @@ Intel(R) Management Engine Interface (Intel(R) MEI) -======================= +=================================================== Introduction -======================= +============ The Intel Management Engine (Intel ME) is an isolated and protected computing resource (Co-processor) residing inside certain Intel chipsets. The Intel ME @@ -19,7 +19,7 @@ each client has its own protocol. The protocol is message-based with a header and payload up to 512 bytes. Prominent usage of the Intel ME Interface is to communicate with Intel(R) -Active Management Technology (Intel AMT)implemented in firmware running on +Active Management Technology (Intel AMT) implemented in firmware running on the Intel ME. Intel AMT provides the ability to manage a host remotely out-of-band (OOB) @@ -44,8 +44,9 @@ HTTP/S that are received from a remote management console application. For more information about Intel AMT: http://software.intel.com/sites/manageability/AMT_Implementation_and_Reference_Guide + Intel MEI Driver -======================= +================ The driver exposes a misc device called /dev/mei. @@ -91,8 +92,10 @@ A code snippet for an application communicating with Intel AMTHI client: [...] close(fd); -IOCTL: -====== + +IOCTL +===== + The Intel MEI Driver supports the following IOCTL command: IOCTL_MEI_CONNECT_CLIENT Connect to firmware Feature (client). @@ -122,58 +125,61 @@ The Intel MEI Driver supports the following IOCTL command: data that can be sent or received. (e.g. if MTU=2K, can send requests up to bytes 2k and received responses up to 2k bytes). -Intel ME Applications: -============== - -1) Intel Local Management Service (Intel LMS) - - Applications running locally on the platform communicate with Intel AMT Release - 2.0 and later releases in the same way that network applications do via SOAP - over HTTP (deprecated starting with Release 6.0) or with WS-Management over - SOAP over HTTP. This means that some Intel AMT features can be accessed from a - local application using the same network interface as a remote application - communicating with Intel AMT over the network. - - When a local application sends a message addressed to the local Intel AMT host - name, the Intel LMS, which listens for traffic directed to the host name, - intercepts the message and routes it to the Intel MEI. - For more information: - http://software.intel.com/sites/manageability/AMT_Implementation_and_Reference_Guide - Under "About Intel AMT" => "Local Access" - - For downloading Intel LMS: - http://software.intel.com/en-us/articles/download-the-latest-intel-amt-open-source-drivers/ - - The Intel LMS opens a connection using the Intel MEI driver to the Intel LMS - firmware feature using a defined UUID and then communicates with the feature - using a protocol called Intel AMT Port Forwarding Protocol(Intel APF protocol). - The protocol is used to maintain multiple sessions with Intel AMT from a - single application. - - See the protocol specification in the Intel AMT Software Development Kit(SDK) - http://software.intel.com/sites/manageability/AMT_Implementation_and_Reference_Guide - Under "SDK Resources" => "Intel(R) vPro(TM) Gateway(MPS)" - => "Information for Intel(R) vPro(TM) Gateway Developers" - => "Description of the Intel AMT Port Forwarding (APF)Protocol" - - 2) Intel AMT Remote configuration using a Local Agent - A Local Agent enables IT personnel to configure Intel AMT out-of-the-box - without requiring installing additional data to enable setup. The remote - configuration process may involve an ISV-developed remote configuration - agent that runs on the host. - For more information: - http://software.intel.com/sites/manageability/AMT_Implementation_and_Reference_Guide - Under "Setup and Configuration of Intel AMT" => - "SDK Tools Supporting Setup and Configuration" => - "Using the Local Agent Sample" - - An open source Intel AMT configuration utility, implementing a local agent - that accesses the Intel MEI driver, can be found here: - http://software.intel.com/en-us/articles/download-the-latest-intel-amt-open-source-drivers/ - - -Intel AMT OS Health Watchdog: -============================= + +Intel ME Applications +===================== + + 1) Intel Local Management Service (Intel LMS) + + Applications running locally on the platform communicate with Intel AMT Release + 2.0 and later releases in the same way that network applications do via SOAP + over HTTP (deprecated starting with Release 6.0) or with WS-Management over + SOAP over HTTP. This means that some Intel AMT features can be accessed from a + local application using the same network interface as a remote application + communicating with Intel AMT over the network. + + When a local application sends a message addressed to the local Intel AMT host + name, the Intel LMS, which listens for traffic directed to the host name, + intercepts the message and routes it to the Intel MEI. + For more information: + http://software.intel.com/sites/manageability/AMT_Implementation_and_Reference_Guide + Under "About Intel AMT" => "Local Access" + + For downloading Intel LMS: + http://software.intel.com/en-us/articles/download-the-latest-intel-amt-open-source-drivers/ + + The Intel LMS opens a connection using the Intel MEI driver to the Intel LMS + firmware feature using a defined UUID and then communicates with the feature + using a protocol called Intel AMT Port Forwarding Protocol (Intel APF protocol). + The protocol is used to maintain multiple sessions with Intel AMT from a + single application. + + See the protocol specification in the Intel AMT Software Development Kit (SDK) + http://software.intel.com/sites/manageability/AMT_Implementation_and_Reference_Guide + Under "SDK Resources" => "Intel(R) vPro(TM) Gateway (MPS)" + => "Information for Intel(R) vPro(TM) Gateway Developers" + => "Description of the Intel AMT Port Forwarding (APF) Protocol" + + 2) Intel AMT Remote configuration using a Local Agent + + A Local Agent enables IT personnel to configure Intel AMT out-of-the-box + without requiring installing additional data to enable setup. The remote + configuration process may involve an ISV-developed remote configuration + agent that runs on the host. + For more information: + http://software.intel.com/sites/manageability/AMT_Implementation_and_Reference_Guide + Under "Setup and Configuration of Intel AMT" => + "SDK Tools Supporting Setup and Configuration" => + "Using the Local Agent Sample" + + An open source Intel AMT configuration utility, implementing a local agent + that accesses the Intel MEI driver, can be found here: + http://software.intel.com/en-us/articles/download-the-latest-intel-amt-open-source-drivers/ + + +Intel AMT OS Health Watchdog +============================ + The Intel AMT Watchdog is an OS Health (Hang/Crash) watchdog. Whenever the OS hangs or crashes, Intel AMT will send an event to any subscriber to this event. This mechanism means that @@ -192,8 +198,10 @@ watchdog is 120 seconds. If the Intel AMT Watchdog feature does not exist (i.e. the connection failed), the Intel MEI driver will disable the sending of heartbeats. -Supported Chipsets: + +Supported Chipsets ================== + 7 Series Chipset Family 6 Series Chipset Family 5 Series Chipset Family diff --git a/Documentation/networking/00-INDEX b/Documentation/networking/00-INDEX index 557b6ef70c26..df27a1a50776 100644 --- a/Documentation/networking/00-INDEX +++ b/Documentation/networking/00-INDEX @@ -1,7 +1,5 @@ 00-INDEX - this file -3c505.txt - - information on the 3Com EtherLink Plus (3c505) driver. 3c509.txt - information on the 3Com Etherlink III Series Ethernet cards. 6pack.txt @@ -24,6 +22,8 @@ README.sb1000 - info on General Instrument/NextLevel SURFboard1000 cable modem. alias.txt - info on using alias network devices. +altera_tse.txt + - Altera Triple-Speed Ethernet controller. arcnet-hardware.txt - tons of info on ARCnet, hubs, jumper settings for ARCnet cards, etc. arcnet.txt @@ -42,6 +42,8 @@ bridge.txt - where to get user space programs for ethernet bridging with Linux. can.txt - documentation on CAN protocol family. +cdc_mbim.txt + - 3G/LTE USB modem (Mobile Broadband Interface Model) cops.txt - info on the COPS LocalTalk Linux driver cs89x0.txt @@ -54,6 +56,8 @@ cxgb.txt - Release Notes for the Chelsio N210 Linux device driver. dccp.txt - the Datagram Congestion Control Protocol (DCCP) (RFC 4340..42). +dctcp.txt + - DataCenter TCP congestion control de4x5.txt - the Digital EtherWORKS DE4?? and DE5?? PCI Ethernet driver decnet.txt diff --git a/Documentation/networking/bonding.txt b/Documentation/networking/bonding.txt index eeb5b2e97bed..83bf4986baea 100644 --- a/Documentation/networking/bonding.txt +++ b/Documentation/networking/bonding.txt @@ -2230,11 +2230,8 @@ balance-rr: This mode is the only mode that will permit a single It is possible to adjust TCP/IP's congestion limits by altering the net.ipv4.tcp_reordering sysctl parameter. The - usual default value is 3, and the maximum useful value is 127. - For a four interface balance-rr bond, expect that a single - TCP/IP stream will utilize no more than approximately 2.3 - interface's worth of throughput, even after adjusting - tcp_reordering. + usual default value is 3. But keep in mind TCP stack is able + to automatically increase this when it detects reorders. Note that the fraction of packets that will be delivered out of order is highly variable, and is unlikely to be zero. The level diff --git a/Documentation/networking/can.txt b/Documentation/networking/can.txt index 2236d6dcb7da..0a2859a8ee7e 100644 --- a/Documentation/networking/can.txt +++ b/Documentation/networking/can.txt @@ -234,7 +234,7 @@ solution for a couple of reasons: mechanisms. Inside this filter definition the (interested) type of errors may be selected. The reception of error messages is disabled by default. The format of the CAN error message frame is briefly - described in the Linux header file "include/linux/can/error.h". + described in the Linux header file "include/uapi/linux/can/error.h". 4. How to use SocketCAN ------------------------ diff --git a/Documentation/networking/fib_trie.txt b/Documentation/networking/fib_trie.txt index 0723db7f8495..fe719388518b 100644 --- a/Documentation/networking/fib_trie.txt +++ b/Documentation/networking/fib_trie.txt @@ -73,8 +73,8 @@ trie_leaf_remove() trie_rebalance() The key function for the dynamic trie after any change in the trie - it is run to optimize and reorganize. Tt will walk the trie upwards - towards the root from a given tnode, doing a resize() at each step + it is run to optimize and reorganize. It will walk the trie upwards + towards the root from a given tnode, doing a resize() at each step to implement level compression. resize() diff --git a/Documentation/networking/filter.txt b/Documentation/networking/filter.txt index 58d08f8d8d80..9930ecfbb465 100644 --- a/Documentation/networking/filter.txt +++ b/Documentation/networking/filter.txt @@ -279,8 +279,8 @@ Possible BPF extensions are shown in the following table: hatype skb->dev->type rxhash skb->hash cpu raw_smp_processor_id() - vlan_tci vlan_tx_tag_get(skb) - vlan_pr vlan_tx_tag_present(skb) + vlan_tci skb_vlan_tag_get(skb) + vlan_pr skb_vlan_tag_present(skb) rand prandom_u32() These extensions can also be prefixed with '#'. diff --git a/Documentation/networking/ip-sysctl.txt b/Documentation/networking/ip-sysctl.txt index a476b08a43e0..1b8c964b0d17 100644 --- a/Documentation/networking/ip-sysctl.txt +++ b/Documentation/networking/ip-sysctl.txt @@ -66,6 +66,8 @@ fwmark_reflect - BOOLEAN route/max_size - INTEGER Maximum number of routes allowed in the kernel. Increase this when using large numbers of interfaces and/or routes. + From linux kernel 3.6 onwards, this is deprecated for ipv4 + as route cache is no longer used. neigh/default/gc_thresh1 - INTEGER Minimum number of entries to keep. Garbage collector will not @@ -288,6 +290,28 @@ tcp_frto - INTEGER By default it's enabled with a non-zero value. 0 disables F-RTO. +tcp_invalid_ratelimit - INTEGER + Limit the maximal rate for sending duplicate acknowledgments + in response to incoming TCP packets that are for an existing + connection but that are invalid due to any of these reasons: + + (a) out-of-window sequence number, + (b) out-of-window acknowledgment number, or + (c) PAWS (Protection Against Wrapped Sequence numbers) check failure + + This can help mitigate simple "ack loop" DoS attacks, wherein + a buggy or malicious middlebox or man-in-the-middle can + rewrite TCP header fields in manner that causes each endpoint + to think that the other is sending invalid TCP segments, thus + causing each side to send an unterminating stream of duplicate + acknowledgments for invalid segments. + + Using 0 disables rate-limiting of dupacks in response to + invalid segments; otherwise this value specifies the minimal + space between sending such dupacks, in milliseconds. + + Default: 500 (milliseconds). + tcp_keepalive_time - INTEGER How often TCP sends out keepalive messages when keepalive is enabled. Default: 2hours. @@ -383,9 +407,17 @@ tcp_orphan_retries - INTEGER may consume significant resources. Cf. tcp_max_orphans. tcp_reordering - INTEGER - Maximal reordering of packets in a TCP stream. + Initial reordering level of packets in a TCP stream. + TCP stack can then dynamically adjust flow reordering level + between this initial value and tcp_max_reordering Default: 3 +tcp_max_reordering - INTEGER + Maximal reordering level of packets in a TCP stream. + 300 is a fairly conservative value, but you might increase it + if paths are using per packet load balancing (like bonding rr mode) + Default: 300 + tcp_retrans_collapse - BOOLEAN Bug-to-bug compatibility with some broken printers. On retransmit try to send bigger packets to work around bugs in @@ -1277,6 +1309,13 @@ accept_ra_rtr_pref - BOOLEAN Functional default: enabled if accept_ra is enabled. disabled if accept_ra is disabled. +accept_ra_mtu - BOOLEAN + Apply the MTU value specified in RA option 5 (RFC4861). If + disabled, the MTU specified in the RA will be ignored. + + Functional default: enabled if accept_ra is enabled. + disabled if accept_ra is disabled. + accept_redirects - BOOLEAN Accept Redirects. @@ -1466,6 +1505,19 @@ suppress_frag_ndisc - INTEGER 1 - (default) discard fragmented neighbor discovery packets 0 - allow fragmented neighbor discovery packets +optimistic_dad - BOOLEAN + Whether to perform Optimistic Duplicate Address Detection (RFC 4429). + 0: disabled (default) + 1: enabled + +use_optimistic - BOOLEAN + If enabled, do not classify optimistic addresses as deprecated during + source address selection. Preferred addresses will still be chosen + before optimistic addresses, subject to other ranking in the source + address selection algorithm. + 0: disabled (default) + 1: enabled + icmp/*: ratelimit - INTEGER Limit the maximal rates for sending ICMPv6 packets. diff --git a/Documentation/networking/ipvlan.txt b/Documentation/networking/ipvlan.txt new file mode 100644 index 000000000000..cf996394e466 --- /dev/null +++ b/Documentation/networking/ipvlan.txt @@ -0,0 +1,107 @@ + + IPVLAN Driver HOWTO + +Initial Release: + Mahesh Bandewar <maheshb AT google.com> + +1. Introduction: + This is conceptually very similar to the macvlan driver with one major +exception of using L3 for mux-ing /demux-ing among slaves. This property makes +the master device share the L2 with it's slave devices. I have developed this +driver in conjuntion with network namespaces and not sure if there is use case +outside of it. + + +2. Building and Installation: + In order to build the driver, please select the config item CONFIG_IPVLAN. +The driver can be built into the kernel (CONFIG_IPVLAN=y) or as a module +(CONFIG_IPVLAN=m). + + +3. Configuration: + There are no module parameters for this driver and it can be configured +using IProute2/ip utility. + + ip link add link <master-dev> <slave-dev> type ipvlan mode { l2 | L3 } + + e.g. ip link add link ipvl0 eth0 type ipvlan mode l2 + + +4. Operating modes: + IPvlan has two modes of operation - L2 and L3. For a given master device, +you can select one of these two modes and all slaves on that master will +operate in the same (selected) mode. The RX mode is almost identical except +that in L3 mode the slaves wont receive any multicast / broadcast traffic. +L3 mode is more restrictive since routing is controlled from the other (mostly) +default namespace. + +4.1 L2 mode: + In this mode TX processing happens on the stack instance attached to the +slave device and packets are switched and queued to the master device to send +out. In this mode the slaves will RX/TX multicast and broadcast (if applicable) +as well. + +4.2 L3 mode: + In this mode TX processing upto L3 happens on the stack instance attached +to the slave device and packets are switched to the stack instance of the +master device for the L2 processing and routing from that instance will be +used before packets are queued on the outbound device. In this mode the slaves +will not receive nor can send multicast / broadcast traffic. + + +5. What to choose (macvlan vs. ipvlan)? + These two devices are very similar in many regards and the specific use +case could very well define which device to choose. if one of the following +situations defines your use case then you can choose to use ipvlan - + (a) The Linux host that is connected to the external switch / router has +policy configured that allows only one mac per port. + (b) No of virtual devices created on a master exceed the mac capacity and +puts the NIC in promiscous mode and degraded performance is a concern. + (c) If the slave device is to be put into the hostile / untrusted network +namespace where L2 on the slave could be changed / misused. + + +6. Example configuration: + + +=============================================================+ + | Host: host1 | + | | + | +----------------------+ +----------------------+ | + | | NS:ns0 | | NS:ns1 | | + | | | | | | + | | | | | | + | | ipvl0 | | ipvl1 | | + | +----------#-----------+ +-----------#----------+ | + | # # | + | ################################ | + | # eth0 | + +==============================#==============================+ + + + (a) Create two network namespaces - ns0, ns1 + ip netns add ns0 + ip netns add ns1 + + (b) Create two ipvlan slaves on eth0 (master device) + ip link add link eth0 ipvl0 type ipvlan mode l2 + ip link add link eth0 ipvl1 type ipvlan mode l2 + + (c) Assign slaves to the respective network namespaces + ip link set dev ipvl0 netns ns0 + ip link set dev ipvl1 netns ns1 + + (d) Now switch to the namespace (ns0 or ns1) to configure the slave devices + - For ns0 + (1) ip netns exec ns0 bash + (2) ip link set dev ipvl0 up + (3) ip link set dev lo up + (4) ip -4 addr add 127.0.0.1 dev lo + (5) ip -4 addr add $IPADDR dev ipvl0 + (6) ip -4 route add default via $ROUTER dev ipvl0 + - For ns1 + (1) ip netns exec ns1 bash + (2) ip link set dev ipvl1 up + (3) ip link set dev lo up + (4) ip -4 addr add 127.0.0.1 dev lo + (5) ip -4 addr add $IPADDR dev ipvl1 + (6) ip -4 route add default via $ROUTER dev ipvl1 diff --git a/Documentation/networking/ixgbe.txt b/Documentation/networking/ixgbe.txt index 96cccebb839b..0ace6e776ac8 100644 --- a/Documentation/networking/ixgbe.txt +++ b/Documentation/networking/ixgbe.txt @@ -138,7 +138,7 @@ Other ethtool Commands: To enable Flow Director ethtool -K ethX ntuple on To add a filter - Use -U switch. e.g., ethtool -U ethX flow-type tcp4 src-ip 0x178000a + Use -U switch. e.g., ethtool -U ethX flow-type tcp4 src-ip 10.0.128.23 action 1 To see the list of filters currently present: ethtool -u ethX diff --git a/Documentation/networking/netlink_mmap.txt b/Documentation/networking/netlink_mmap.txt index c6af4bac5aa8..54f10478e8e3 100644 --- a/Documentation/networking/netlink_mmap.txt +++ b/Documentation/networking/netlink_mmap.txt @@ -199,16 +199,9 @@ frame header. TX limitations -------------- -Kernel processing usually involves validation of the message received by -user-space, then processing its contents. The kernel must assure that -userspace is not able to modify the message contents after they have been -validated. In order to do so, the message is copied from the ring frame -to an allocated buffer if either of these conditions is false: - -- only a single mapping of the ring exists -- the file descriptor is not shared between processes - -This means that for threaded programs, the kernel will fall back to copying. +As of Jan 2015 the message is always copied from the ring frame to an +allocated buffer due to unresolved security concerns. +See commit 4682a0358639b29cf ("netlink: Always copy on mmap TX."). Example ------- diff --git a/Documentation/networking/nf_conntrack-sysctl.txt b/Documentation/networking/nf_conntrack-sysctl.txt index 70da5086153d..f55599c62c9d 100644 --- a/Documentation/networking/nf_conntrack-sysctl.txt +++ b/Documentation/networking/nf_conntrack-sysctl.txt @@ -11,7 +11,8 @@ nf_conntrack_buckets - INTEGER (read-only) Size of hash table. If not specified as parameter during module loading, the default size is calculated by dividing total memory by 16384 to determine the number of buckets but the hash table will - never have fewer than 32 or more than 16384 buckets. + never have fewer than 32 and limited to 16384 buckets. For systems + with more than 4GB of memory it will be 65536 buckets. nf_conntrack_checksum - BOOLEAN 0 - disabled diff --git a/Documentation/networking/openvswitch.txt b/Documentation/networking/openvswitch.txt index 37c20ee2455e..b3b9ac61d29d 100644 --- a/Documentation/networking/openvswitch.txt +++ b/Documentation/networking/openvswitch.txt @@ -131,6 +131,19 @@ performs best-effort detection of overlapping wildcarded flows and may reject some but not all of them. However, this behavior may change in future versions. +Unique flow identifiers +----------------------- + +An alternative to using the original match portion of a key as the handle for +flow identification is a unique flow identifier, or "UFID". UFIDs are optional +for both the kernel and user space program. + +User space programs that support UFID are expected to provide it during flow +setup in addition to the flow, then refer to the flow using the UFID for all +future operations. The kernel is not required to index flows by the original +flow key if a UFID is specified. + + Basic rule for evolving flow keys --------------------------------- diff --git a/Documentation/networking/stmmac.txt b/Documentation/networking/stmmac.txt index 2090895b08d4..e655e2453c98 100644 --- a/Documentation/networking/stmmac.txt +++ b/Documentation/networking/stmmac.txt @@ -1,12 +1,12 @@ STMicroelectronics 10/100/1000 Synopsys Ethernet driver -Copyright (C) 2007-2013 STMicroelectronics Ltd +Copyright (C) 2007-2014 STMicroelectronics Ltd Author: Giuseppe Cavallaro <peppe.cavallaro@st.com> This is the driver for the MAC 10/100/1000 on-chip Ethernet controllers (Synopsys IP blocks). -Currently this network device driver is for all STM embedded MAC/GMAC +Currently this network device driver is for all STi embedded MAC/GMAC (i.e. 7xxx/5xxx SoCs), SPEAr (arm), Loongson1B (mips) and XLINX XC2V3000 FF1152AMT0221 D1215994A VIRTEX FPGA board. @@ -22,6 +22,9 @@ The kernel configuration option is STMMAC_ETH: Device Drivers ---> Network device support ---> Ethernet (1000 Mbit) ---> STMicroelectronics 10/100/1000 Ethernet driver (STMMAC_ETH) +CONFIG_STMMAC_PLATFORM: is to enable the platform driver. +CONFIG_STMMAC_PCI: is to enable the pci driver. + 2) Driver parameters list: debug: message level (0: no output, 16: all); phyaddr: to manually provide the physical address to the PHY device; @@ -45,10 +48,11 @@ Driver parameters can be also passed in command line by using: The xmit method is invoked when the kernel needs to transmit a packet; it sets the descriptors in the ring and informs the DMA engine that there is a packet ready to be transmitted. -Once the controller has finished transmitting the packet, an interrupt is -triggered; So the driver will be able to release the socket buffers. By default, the driver sets the NETIF_F_SG bit in the features field of the -net_device structure enabling the scatter/gather feature. +net_device structure enabling the scatter-gather feature. This is true on +chips and configurations where the checksum can be done in hardware. +Once the controller has finished transmitting the packet, napi will be +scheduled to release the transmit resources. 4.2) Receive process When one or more packets are received, an interrupt happens. The interrupts @@ -58,20 +62,12 @@ This is based on NAPI so the interrupt handler signals only if there is work to be done, and it exits. Then the poll method will be scheduled at some future point. The incoming packets are stored, by the DMA, in a list of pre-allocated socket -buffers in order to avoid the memcpy (Zero-copy). +buffers in order to avoid the memcpy (zero-copy). 4.3) Interrupt Mitigation The driver is able to mitigate the number of its DMA interrupts using NAPI for the reception on chips older than the 3.50. New chips have an HW RX-Watchdog used for this mitigation. - -On Tx-side, the mitigation schema is based on a SW timer that calls the -tx function (stmmac_tx) to reclaim the resource after transmitting the -frames. -Also there is another parameter (like a threshold) used to program -the descriptors avoiding to set the interrupt on completion bit in -when the frame is sent (xmit). - Mitigation parameters can be tuned by ethtool. 4.4) WOL @@ -79,7 +75,7 @@ Wake up on Lan feature through Magic and Unicast frames are supported for the GMAC core. 4.5) DMA descriptors -Driver handles both normal and enhanced descriptors. The latter has been only +Driver handles both normal and alternate descriptors. The latter has been only tested on DWC Ether MAC 10/100/1000 Universal version 3.41a and later. STMMAC supports DMA descriptor to operate both in dual buffer (RING) @@ -91,9 +87,20 @@ In CHAINED mode each descriptor will have pointer to next descriptor in the list, hence creating the explicit chaining in the descriptor itself, whereas such explicit chaining is not possible in RING mode. +4.5.1) Extended descriptors + The extended descriptors give us information about the Ethernet payload + when it is carrying PTP packets or TCP/UDP/ICMP over IP. + These are not available on GMAC Synopsys chips older than the 3.50. + At probe time the driver will decide if these can be actually used. + This support also is mandatory for PTPv2 because the extra descriptors + are used for saving the hardware timestamps and Extended Status. + 4.6) Ethtool support -Ethtool is supported. Driver statistics and internal errors can be taken using: -ethtool -S ethX command. It is possible to dump registers etc. +Ethtool is supported. + +For example, driver statistics (including RMON), internal errors can be taken +using: + # ethtool -S ethX command 4.7) Jumbo and Segmentation Offloading Jumbo frames are supported and tested for the GMAC. @@ -101,12 +108,11 @@ The GSO has been also added but it's performed in software. LRO is not supported. 4.8) Physical -The driver is compatible with PAL to work with PHY and GPHY devices. +The driver is compatible with Physical Abstraction Layer to be connected with +PHY and GPHY devices. 4.9) Platform information -Several driver's information can be passed through the platform -These are included in the include/linux/stmmac.h header file -and detailed below as well: +Several information can be passed through the platform and device-tree. struct plat_stmmacenet_data { char *phy_bus_name; @@ -125,15 +131,18 @@ struct plat_stmmacenet_data { int force_sf_dma_mode; int force_thresh_dma_mode; int riwt_off; + int max_speed; + int maxmtu; void (*fix_mac_speed)(void *priv, unsigned int speed); void (*bus_setup)(void __iomem *ioaddr); void *(*setup)(struct platform_device *pdev); + void (*free)(struct platform_device *pdev, void *priv); int (*init)(struct platform_device *pdev, void *priv); void (*exit)(struct platform_device *pdev, void *priv); void *custom_cfg; void *custom_data; void *bsp_priv; - }; +}; Where: o phy_bus_name: phy bus name to attach to the stmmac. @@ -258,32 +267,43 @@ and the second one, with a real PHY device attached to the bus, by using the stmmac_mdio_bus_data structure (to provide the id, the reset procedure etc). -4.10) List of source files: - o Kconfig - o Makefile - o stmmac_main.c: main network device driver; - o stmmac_mdio.c: mdio functions; - o stmmac_pci: PCI driver; - o stmmac_platform.c: platform driver - o stmmac_ethtool.c: ethtool support; - o stmmac_timer.[ch]: timer code used for mitigating the driver dma interrupts - (only tested on ST40 platforms based); +Note that, starting from new chips, where it is available the HW capability +register, many configurations are discovered at run-time for example to +understand if EEE, HW csum, PTP, enhanced descriptor etc are actually +available. As strategy adopted in this driver, the information from the HW +capability register can replace what has been passed from the platform. + +4.10) Device-tree support. + +Please see the following document: + Documentation/devicetree/bindings/net/stmmac.txt + +and the stmmac_of_data structure inside the include/linux/stmmac.h header file. + +4.11) This is a summary of the content of some relevant files: + o stmmac_main.c: to implement the main network device driver; + o stmmac_mdio.c: to provide mdio functions; + o stmmac_pci: this the PCI driver; + o stmmac_platform.c: this the platform driver (OF supported) + o stmmac_ethtool.c: to implement the ethtool support; o stmmac.h: private driver structure; o common.h: common definitions and VFTs; o descs.h: descriptor structure definitions; - o dwmac1000_core.c: GMAC core functions; - o dwmac1000_dma.c: dma functions for the GMAC chip; - o dwmac1000.h: specific header file for the GMAC; - o dwmac100_core: MAC 100 core and dma code; - o dwmac100_dma.c: dma functions for the MAC chip; + o dwmac1000_core.c: dwmac GiGa core functions; + o dwmac1000_dma.c: dma functions for the GMAC chip; + o dwmac1000.h: specific header file for the dwmac GiGa; + o dwmac100_core: dwmac 100 core code; + o dwmac100_dma.c: dma functions for the dwmac 100 chip; o dwmac1000.h: specific header file for the MAC; - o dwmac_lib.c: generic DMA functions shared among chips; + o dwmac_lib.c: generic DMA functions; o enh_desc.c: functions for handling enhanced descriptors; o norm_desc.c: functions for handling normal descriptors; o chain_mode.c/ring_mode.c:: functions to manage RING/CHAINED modes; o mmc_core.c/mmc.h: Management MAC Counters; - o stmmac_hwtstamp.c: HW timestamp support for PTP - o stmmac_ptp.c: PTP 1588 clock + o stmmac_hwtstamp.c: HW timestamp support for PTP; + o stmmac_ptp.c: PTP 1588 clock; + o dwmac-<XXX>.c: these are for the platform glue-logic file; e.g. dwmac-sti.c + for STMicroelectronics SoCs. 5) Debug Information @@ -298,23 +318,14 @@ to get statistics: e.g. using: ethtool -S ethX (that shows the Management counters (MMC) if supported) or sees the MAC/DMA registers: e.g. using: ethtool -d ethX -Compiling the Kernel with CONFIG_DEBUG_FS and enabling the -STMMAC_DEBUG_FS option the driver will export the following +Compiling the Kernel with CONFIG_DEBUG_FS the driver will export the following debugfs entries: /sys/kernel/debug/stmmaceth/descriptors_status To show the DMA TX/RX descriptor rings -Developer can also use the "debug" module parameter to get -further debug information. - -In the end, there are other macros (that cannot be enabled -via menuconfig) to turn-on the RX/TX DMA debugging, -specific MAC core debug printk etc. Others to enable the -debug in the TX and RX processes. -All these are only useful during the developing stage -and should never enabled inside the code for general usage. -In fact, these can generate an huge amount of debug messages. +Developer can also use the "debug" module parameter to get further debug +information (please see: NETIF Msg Level). 6) Energy Efficient Ethernet @@ -337,15 +348,7 @@ To enter in Tx LPI mode the driver needs to have a software timer that enable and disable the LPI mode when there is nothing to be transmitted. -7) Extended descriptors -The extended descriptors give us information about the receive Ethernet payload -when it is carrying PTP packets or TCP/UDP/ICMP over IP. -These are not available on GMAC Synopsys chips older than the 3.50. -At probe time the driver will decide if these can be actually used. -This support also is mandatory for PTPv2 because the extra descriptors 6 and 7 -are used for saving the hardware timestamps. - -8) Precision Time Protocol (PTP) +7) Precision Time Protocol (PTP) The driver supports the IEEE 1588-2002, Precision Time Protocol (PTP), which enables precise synchronization of clocks in measurement and control systems implemented with technologies such as network @@ -355,7 +358,7 @@ In addition to the basic timestamp features mentioned in IEEE 1588-2002 Timestamps, new GMAC cores support the advanced timestamp features. IEEE 1588-2008 that can be enabled when configure the Kernel. -9) SGMII/RGMII supports +8) SGMII/RGMII supports New GMAC devices provide own way to manage RGMII/SGMII. This information is available at run-time by looking at the HW capability register. This means that the stmmac can manage @@ -364,8 +367,3 @@ In fact, the HW provides a subset of extended registers to restart the ANE, verify Full/Half duplex mode and Speed. Also thanks to these registers it is possible to look at the Auto-negotiated Link Parter Ability. - -10) TODO: - o XGMAC is not supported. - o Complete the TBI & RTBI support. - o extend VLAN support for 3.70a SYNP GMAC. diff --git a/Documentation/networking/switchdev.txt b/Documentation/networking/switchdev.txt new file mode 100644 index 000000000000..f981a9295a39 --- /dev/null +++ b/Documentation/networking/switchdev.txt @@ -0,0 +1,59 @@ +Switch (and switch-ish) device drivers HOWTO +=========================== + +Please note that the word "switch" is here used in very generic meaning. +This include devices supporting L2/L3 but also various flow offloading chips, +including switches embedded into SR-IOV NICs. + +Lets describe a topology a bit. Imagine the following example: + + +----------------------------+ +---------------+ + | SOME switch chip | | CPU | + +----------------------------+ +---------------+ + port1 port2 port3 port4 MNGMNT | PCI-E | + | | | | | +---------------+ + PHY PHY | | | | NIC0 NIC1 + | | | | | | + | | +- PCI-E -+ | | + | +------- MII -------+ | + +------------- MII ------------+ + +In this example, there are two independent lines between the switch silicon +and CPU. NIC0 and NIC1 drivers are not aware of a switch presence. They are +separate from the switch driver. SOME switch chip is by managed by a driver +via PCI-E device MNGMNT. Note that MNGMNT device, NIC0 and NIC1 may be +connected to some other type of bus. + +Now, for the previous example show the representation in kernel: + + +----------------------------+ +---------------+ + | SOME switch chip | | CPU | + +----------------------------+ +---------------+ + sw0p0 sw0p1 sw0p2 sw0p3 MNGMNT | PCI-E | + | | | | | +---------------+ + PHY PHY | | | | eth0 eth1 + | | | | | | + | | +- PCI-E -+ | | + | +------- MII -------+ | + +------------- MII ------------+ + +Lets call the example switch driver for SOME switch chip "SOMEswitch". This +driver takes care of PCI-E device MNGMNT. There is a netdevice instance sw0pX +created for each port of a switch. These netdevices are instances +of "SOMEswitch" driver. sw0pX netdevices serve as a "representation" +of the switch chip. eth0 and eth1 are instances of some other existing driver. + +The only difference of the switch-port netdevice from the ordinary netdevice +is that is implements couple more NDOs: + + ndo_switch_parent_id_get - This returns the same ID for two port netdevices + of the same physical switch chip. This is + mandatory to be implemented by all switch drivers + and serves the caller for recognition of a port + netdevice. + ndo_switch_parent_* - Functions that serve for a manipulation of the switch + chip itself (it can be though of as a "parent" of the + port, therefore the name). They are not port-specific. + Caller might use arbitrary port netdevice of the same + switch and it will make no difference. + ndo_switch_port_* - Functions that serve for a port-specific manipulation. diff --git a/Documentation/networking/timestamping.txt b/Documentation/networking/timestamping.txt index 1d6d02d6ba52..5f0922613f1a 100644 --- a/Documentation/networking/timestamping.txt +++ b/Documentation/networking/timestamping.txt @@ -122,7 +122,7 @@ SOF_TIMESTAMPING_RAW_HARDWARE: 1.3.3 Timestamp Options -The interface supports one option +The interface supports the options SOF_TIMESTAMPING_OPT_ID: @@ -130,19 +130,57 @@ SOF_TIMESTAMPING_OPT_ID: have multiple concurrent timestamping requests outstanding. Packets can be reordered in the transmit path, for instance in the packet scheduler. In that case timestamps will be queued onto the error - queue out of order from the original send() calls. This option - embeds a counter that is incremented at send() time, to order - timestamps within a flow. + queue out of order from the original send() calls. It is not always + possible to uniquely match timestamps to the original send() calls + based on timestamp order or payload inspection alone, then. + + This option associates each packet at send() with a unique + identifier and returns that along with the timestamp. The identifier + is derived from a per-socket u32 counter (that wraps). For datagram + sockets, the counter increments with each sent packet. For stream + sockets, it increments with every byte. + + The counter starts at zero. It is initialized the first time that + the socket option is enabled. It is reset each time the option is + enabled after having been disabled. Resetting the counter does not + change the identifiers of existing packets in the system. This option is implemented only for transmit timestamps. There, the timestamp is always looped along with a struct sock_extended_err. The option modifies field ee_data to pass an id that is unique among all possibly concurrently outstanding timestamp requests for - that socket. In practice, it is a monotonically increasing u32 - (that wraps). + that socket. + + +SOF_TIMESTAMPING_OPT_CMSG: + + Support recv() cmsg for all timestamped packets. Control messages + are already supported unconditionally on all packets with receive + timestamps and on IPv6 packets with transmit timestamp. This option + extends them to IPv4 packets with transmit timestamp. One use case + is to correlate packets with their egress device, by enabling socket + option IP_PKTINFO simultaneously. + + +SOF_TIMESTAMPING_OPT_TSONLY: + + Applies to transmit timestamps only. Makes the kernel return the + timestamp as a cmsg alongside an empty packet, as opposed to + alongside the original packet. This reduces the amount of memory + charged to the socket's receive budget (SO_RCVBUF) and delivers + the timestamp even if sysctl net.core.tstamp_allow_data is 0. + This option disables SOF_TIMESTAMPING_OPT_CMSG. + + +New applications are encouraged to pass SOF_TIMESTAMPING_OPT_ID to +disambiguate timestamps and SOF_TIMESTAMPING_OPT_TSONLY to operate +regardless of the setting of sysctl net.core.tstamp_allow_data. - In datagram sockets, the counter increments on each send call. In - stream sockets, it increments with every byte. +An exception is when a process needs additional cmsg data, for +instance SOL_IP/IP_PKTINFO to detect the egress network interface. +Then pass option SOF_TIMESTAMPING_OPT_CMSG. This option depends on +having access to the contents of the original packet, so cannot be +combined with SOF_TIMESTAMPING_OPT_TSONLY. 1.4 Bytestream Timestamps diff --git a/Documentation/networking/timestamping/txtimestamp.c b/Documentation/networking/timestamping/txtimestamp.c index b32fc2a07734..8217510d3842 100644 --- a/Documentation/networking/timestamping/txtimestamp.c +++ b/Documentation/networking/timestamping/txtimestamp.c @@ -30,6 +30,8 @@ * 51 Franklin St - Fifth Floor, Boston, MA 02110-1301 USA. */ +#define _GNU_SOURCE + #include <arpa/inet.h> #include <asm/types.h> #include <error.h> @@ -46,6 +48,7 @@ #include <netpacket/packet.h> #include <poll.h> #include <stdarg.h> +#include <stdbool.h> #include <stdint.h> #include <stdio.h> #include <stdlib.h> @@ -65,6 +68,9 @@ static int cfg_num_pkts = 4; static int do_ipv4 = 1; static int do_ipv6 = 1; static int cfg_payload_len = 10; +static bool cfg_show_payload; +static bool cfg_do_pktinfo; +static bool cfg_loop_nodata; static uint16_t dest_port = 9000; static struct sockaddr_in daddr; @@ -131,6 +137,33 @@ static void print_timestamp(struct scm_timestamping *tss, int tstype, __print_timestamp(tsname, &tss->ts[0], tskey, payload_len); } +/* TODO: convert to check_and_print payload once API is stable */ +static void print_payload(char *data, int len) +{ + int i; + + if (!len) + return; + + if (len > 70) + len = 70; + + fprintf(stderr, "payload: "); + for (i = 0; i < len; i++) + fprintf(stderr, "%02hhx ", data[i]); + fprintf(stderr, "\n"); +} + +static void print_pktinfo(int family, int ifindex, void *saddr, void *daddr) +{ + char sa[INET6_ADDRSTRLEN], da[INET6_ADDRSTRLEN]; + + fprintf(stderr, " pktinfo: ifindex=%u src=%s dst=%s\n", + ifindex, + saddr ? inet_ntop(family, saddr, sa, sizeof(sa)) : "unknown", + daddr ? inet_ntop(family, daddr, da, sizeof(da)) : "unknown"); +} + static void __poll(int fd) { struct pollfd pollfd; @@ -148,6 +181,7 @@ static void __recv_errmsg_cmsg(struct msghdr *msg, int payload_len) struct sock_extended_err *serr = NULL; struct scm_timestamping *tss = NULL; struct cmsghdr *cm; + int batch = 0; for (cm = CMSG_FIRSTHDR(msg); cm && cm->cmsg_len; @@ -156,10 +190,9 @@ static void __recv_errmsg_cmsg(struct msghdr *msg, int payload_len) cm->cmsg_type == SCM_TIMESTAMPING) { tss = (void *) CMSG_DATA(cm); } else if ((cm->cmsg_level == SOL_IP && - cm->cmsg_type == IP_RECVERR) || - (cm->cmsg_level == SOL_IPV6 && - cm->cmsg_type == IPV6_RECVERR)) { - + cm->cmsg_type == IP_RECVERR) || + (cm->cmsg_level == SOL_IPV6 && + cm->cmsg_type == IPV6_RECVERR)) { serr = (void *) CMSG_DATA(cm); if (serr->ee_errno != ENOMSG || serr->ee_origin != SO_EE_ORIGIN_TIMESTAMPING) { @@ -168,13 +201,31 @@ static void __recv_errmsg_cmsg(struct msghdr *msg, int payload_len) serr->ee_origin); serr = NULL; } + } else if (cm->cmsg_level == SOL_IP && + cm->cmsg_type == IP_PKTINFO) { + struct in_pktinfo *info = (void *) CMSG_DATA(cm); + print_pktinfo(AF_INET, info->ipi_ifindex, + &info->ipi_spec_dst, &info->ipi_addr); + } else if (cm->cmsg_level == SOL_IPV6 && + cm->cmsg_type == IPV6_PKTINFO) { + struct in6_pktinfo *info6 = (void *) CMSG_DATA(cm); + print_pktinfo(AF_INET6, info6->ipi6_ifindex, + NULL, &info6->ipi6_addr); } else fprintf(stderr, "unknown cmsg %d,%d\n", cm->cmsg_level, cm->cmsg_type); + + if (serr && tss) { + print_timestamp(tss, serr->ee_info, serr->ee_data, + payload_len); + serr = NULL; + tss = NULL; + batch++; + } } - if (serr && tss) - print_timestamp(tss, serr->ee_info, serr->ee_data, payload_len); + if (batch > 1) + fprintf(stderr, "batched %d timestamps\n", batch); } static int recv_errmsg(int fd) @@ -206,7 +257,11 @@ static int recv_errmsg(int fd) if (ret == -1 && errno != EAGAIN) error(1, errno, "recvmsg"); - __recv_errmsg_cmsg(&msg, ret); + if (ret >= 0) { + __recv_errmsg_cmsg(&msg, ret); + if (cfg_show_payload) + print_payload(data, cfg_payload_len); + } free(data); return ret == -1; @@ -215,9 +270,9 @@ static int recv_errmsg(int fd) static void do_test(int family, unsigned int opt) { char *buf; - int fd, i, val, total_len; + int fd, i, val = 1, total_len; - if (family == IPPROTO_IPV6 && cfg_proto != SOCK_STREAM) { + if (family == AF_INET6 && cfg_proto != SOCK_STREAM) { /* due to lack of checksum generation code */ fprintf(stderr, "test: skipping datagram over IPv6\n"); return; @@ -239,7 +294,6 @@ static void do_test(int family, unsigned int opt) error(1, errno, "socket"); if (cfg_proto == SOCK_STREAM) { - val = 1; if (setsockopt(fd, IPPROTO_TCP, TCP_NODELAY, (char*) &val, sizeof(val))) error(1, 0, "setsockopt no nagle"); @@ -253,8 +307,24 @@ static void do_test(int family, unsigned int opt) } } + if (cfg_do_pktinfo) { + if (family == AF_INET6) { + if (setsockopt(fd, SOL_IPV6, IPV6_RECVPKTINFO, + &val, sizeof(val))) + error(1, errno, "setsockopt pktinfo ipv6"); + } else { + if (setsockopt(fd, SOL_IP, IP_PKTINFO, + &val, sizeof(val))) + error(1, errno, "setsockopt pktinfo ipv4"); + } + } + opt |= SOF_TIMESTAMPING_SOFTWARE | + SOF_TIMESTAMPING_OPT_CMSG | SOF_TIMESTAMPING_OPT_ID; + if (cfg_loop_nodata) + opt |= SOF_TIMESTAMPING_OPT_TSONLY; + if (setsockopt(fd, SOL_SOCKET, SO_TIMESTAMPING, (char *) &opt, sizeof(opt))) error(1, 0, "setsockopt timestamping"); @@ -262,8 +332,6 @@ static void do_test(int family, unsigned int opt) for (i = 0; i < cfg_num_pkts; i++) { memset(&ts_prev, 0, sizeof(ts_prev)); memset(buf, 'a' + i, total_len); - buf[total_len - 2] = '\n'; - buf[total_len - 1] = '\0'; if (cfg_proto == SOCK_RAW) { struct udphdr *udph; @@ -324,11 +392,14 @@ static void __attribute__((noreturn)) usage(const char *filepath) " -4: only IPv4\n" " -6: only IPv6\n" " -h: show this message\n" + " -I: request PKTINFO\n" " -l N: send N bytes at a time\n" + " -n: set no-payload option\n" " -r: use raw\n" " -R: use raw (IP_HDRINCL)\n" " -p N: connect to port N\n" - " -u: use udp\n", + " -u: use udp\n" + " -x: show payload (up to 70 bytes)\n", filepath); exit(1); } @@ -338,7 +409,7 @@ static void parse_opt(int argc, char **argv) int proto_count = 0; char c; - while ((c = getopt(argc, argv, "46hl:p:rRu")) != -1) { + while ((c = getopt(argc, argv, "46hIl:np:rRux")) != -1) { switch (c) { case '4': do_ipv6 = 0; @@ -346,6 +417,12 @@ static void parse_opt(int argc, char **argv) case '6': do_ipv4 = 0; break; + case 'I': + cfg_do_pktinfo = true; + break; + case 'n': + cfg_loop_nodata = true; + break; case 'r': proto_count++; cfg_proto = SOCK_RAW; @@ -367,6 +444,9 @@ static void parse_opt(int argc, char **argv) case 'p': dest_port = strtoul(optarg, NULL, 10); break; + case 'x': + cfg_show_payload = true; + break; case 'h': default: usage(argv[0]); diff --git a/Documentation/nios2/README b/Documentation/nios2/README new file mode 100644 index 000000000000..054a67d55563 --- /dev/null +++ b/Documentation/nios2/README @@ -0,0 +1,23 @@ +Linux on the Nios II architecture +================================= + +This is a port of Linux to Nios II (nios2) processor. + +In order to compile for Nios II, you need a version of GCC with support for the generic +system call ABI. Please see this link for more information on how compiling and booting +software for the Nios II platform: +http://www.rocketboards.org/foswiki/Documentation/NiosIILinuxUserManual + +For reference, please see the following link: +http://www.altera.com/literature/lit-nio2.jsp + +What is Nios II? +================ +Nios II is a 32-bit embedded-processor architecture designed specifically for the +Altera family of FPGAs. In order to support Linux, Nios II needs to be configured +with MMU and hardware multiplier enabled. + +Nios II ABI +=========== +Please refer to chapter "Application Binary Interface" in Nios II Processor Reference +Handbook. diff --git a/Documentation/nommu-mmap.txt b/Documentation/nommu-mmap.txt index 8e1ddec2c78a..ae57b9ea0d41 100644 --- a/Documentation/nommu-mmap.txt +++ b/Documentation/nommu-mmap.txt @@ -43,12 +43,12 @@ and it's also much more restricted in the latter case: even if this was created by another process. - If possible, the file mapping will be directly on the backing device - if the backing device has the BDI_CAP_MAP_DIRECT capability and + if the backing device has the NOMMU_MAP_DIRECT capability and appropriate mapping protection capabilities. Ramfs, romfs, cramfs and mtd might all permit this. - If the backing device device can't or won't permit direct sharing, - but does have the BDI_CAP_MAP_COPY capability, then a copy of the + but does have the NOMMU_MAP_COPY capability, then a copy of the appropriate bit of the file will be read into a contiguous bit of memory and any extraneous space beyond the EOF will be cleared @@ -220,7 +220,7 @@ directly (can't be copied). The file->f_op->mmap() operation will be called to actually inaugurate the mapping. It can be rejected at that point. Returning the ENOSYS error will -cause the mapping to be copied instead if BDI_CAP_MAP_COPY is specified. +cause the mapping to be copied instead if NOMMU_MAP_COPY is specified. The vm_ops->close() routine will be invoked when the last mapping on a chardev is removed. An existing mapping will be shared, partially or not, if possible @@ -232,7 +232,7 @@ want to handle it, despite the fact it's got an operation. For instance, it might try directing the call to a secondary driver which turns out not to implement it. Such is the case for the framebuffer driver which attempts to direct the call to the device-specific driver. Under such circumstances, the -mapping request will be rejected if BDI_CAP_MAP_COPY is not specified, and a +mapping request will be rejected if NOMMU_MAP_COPY is not specified, and a copy mapped otherwise. IMPORTANT NOTE: diff --git a/Documentation/oops-tracing.txt b/Documentation/oops-tracing.txt index beefb9f82902..f3ac05cc23e4 100644 --- a/Documentation/oops-tracing.txt +++ b/Documentation/oops-tracing.txt @@ -270,6 +270,8 @@ characters, each representing a particular tainted value. 15: 'L' if a soft lockup has previously occurred on the system. + 16: 'K' if the kernel has been live patched. + The primary reason for the 'Tainted: ' string is to tell kernel debuggers if this is a clean kernel or if anything unusual has occurred. Tainting is permanent: even if an offending module is diff --git a/Documentation/phy.txt b/Documentation/phy.txt index c6594af94d25..371361c69a4b 100644 --- a/Documentation/phy.txt +++ b/Documentation/phy.txt @@ -54,18 +54,14 @@ The PHY driver should create the PHY in order for other peripheral controllers to make use of it. The PHY framework provides 2 APIs to create the PHY. struct phy *phy_create(struct device *dev, struct device_node *node, - const struct phy_ops *ops, - struct phy_init_data *init_data); + const struct phy_ops *ops); struct phy *devm_phy_create(struct device *dev, struct device_node *node, - const struct phy_ops *ops, - struct phy_init_data *init_data); + const struct phy_ops *ops); The PHY drivers can use one of the above 2 APIs to create the PHY by passing -the device pointer, phy ops and init_data. +the device pointer and phy ops. phy_ops is a set of function pointers for performing PHY operations such as -init, exit, power_on and power_off. *init_data* is mandatory to get a reference -to the PHY in the case of non-dt boot. See section *Board File Initialization* -on how init_data should be used. +init, exit, power_on and power_off. Inorder to dereference the private data (in phy_ops), the phy provider driver can use phy_set_drvdata() after creating the PHY and use phy_get_drvdata() in @@ -137,42 +133,18 @@ There are exported APIs like phy_pm_runtime_get, phy_pm_runtime_get_sync, phy_pm_runtime_put, phy_pm_runtime_put_sync, phy_pm_runtime_allow and phy_pm_runtime_forbid for performing PM operations. -8. Board File Initialization - -Certain board file initialization is necessary in order to get a reference -to the PHY in the case of non-dt boot. -Say we have a single device that implements 3 PHYs that of USB, SATA and PCIe, -then in the board file the following initialization should be done. - -struct phy_consumer consumers[] = { - PHY_CONSUMER("dwc3.0", "usb"), - PHY_CONSUMER("pcie.0", "pcie"), - PHY_CONSUMER("sata.0", "sata"), -}; -PHY_CONSUMER takes 2 parameters, first is the device name of the controller -(PHY consumer) and second is the port name. - -struct phy_init_data init_data = { - .consumers = consumers, - .num_consumers = ARRAY_SIZE(consumers), -}; - -static const struct platform_device pipe3_phy_dev = { - .name = "pipe3-phy", - .id = -1, - .dev = { - .platform_data = { - .init_data = &init_data, - }, - }, -}; - -then, while doing phy_create, the PHY driver should pass this init_data - phy_create(dev, ops, pdata->init_data); - -and the controller driver (phy consumer) should pass the port name along with -the device to get a reference to the PHY - phy_get(dev, "pcie"); +8. PHY Mappings + +In order to get reference to a PHY without help from DeviceTree, the framework +offers lookups which can be compared to clkdev that allow clk structures to be +bound to devices. A lookup can be made be made during runtime when a handle to +the struct phy already exists. + +The framework offers the following API for registering and unregistering the +lookups. + +int phy_create_lookup(struct phy *phy, const char *con_id, const char *dev_id); +void phy_remove_lookup(struct phy *phy, const char *con_id, const char *dev_id); 9. DeviceTree Binding diff --git a/Documentation/power/runtime_pm.txt b/Documentation/power/runtime_pm.txt index f32ce5419573..44fe1d28a163 100644 --- a/Documentation/power/runtime_pm.txt +++ b/Documentation/power/runtime_pm.txt @@ -229,13 +229,13 @@ defined in include/linux/pm.h: - if set, the value of child_count is ignored (but still updated) unsigned int disable_depth; - - used for disabling the helper funcions (they work normally if this is + - used for disabling the helper functions (they work normally if this is equal to zero); the initial value of it is 1 (i.e. runtime PM is initially disabled for all devices) int runtime_error; - if set, there was a fatal error (one of the callbacks returned error code - as described in Section 2), so the helper funtions will not work until + as described in Section 2), so the helper functions will not work until this flag is cleared; this is the error code returned by the failing callback @@ -468,6 +468,10 @@ drivers/base/power/runtime.c and include/linux/pm_runtime.h: - set the power.irq_safe flag for the device, causing the runtime-PM callbacks to be invoked with interrupts off + bool pm_runtime_is_irq_safe(struct device *dev); + - return true if power.irq_safe flag was set for the device, causing + the runtime-PM callbacks to be invoked with interrupts off + void pm_runtime_mark_last_busy(struct device *dev); - set the power.last_busy field to the current time @@ -524,7 +528,7 @@ pm_runtime_put_sync_autosuspend() 5. Runtime PM Initialization, Device Probing and Removal Initially, the runtime PM is disabled for all devices, which means that the -majority of the runtime PM helper funtions described in Section 4 will return +majority of the runtime PM helper functions described in Section 4 will return -EAGAIN until pm_runtime_enable() is called for the device. In addition to that, the initial runtime PM status of all devices is diff --git a/Documentation/power/s2ram.txt b/Documentation/power/s2ram.txt index 1bdfa0443773..4685aee197fd 100644 --- a/Documentation/power/s2ram.txt +++ b/Documentation/power/s2ram.txt @@ -69,6 +69,10 @@ Reason for this is that the RTC is the only reliably available piece of hardware during resume operations where a value can be set that will survive a reboot. +pm_trace is not compatible with asynchronous suspend, so it turns +asynchronous suspend off (which may work around timing or +ordering-sensitive bugs). + Consequence is that after a resume (even if it is successful) your system clock will have a value corresponding to the magic number instead of the correct date/time! It is therefore advisable to use a program like ntp-date diff --git a/Documentation/power/suspend-and-interrupts.txt b/Documentation/power/suspend-and-interrupts.txt index 69663640dea5..2f9c5a5fcb25 100644 --- a/Documentation/power/suspend-and-interrupts.txt +++ b/Documentation/power/suspend-and-interrupts.txt @@ -77,7 +77,7 @@ Calling enable_irq_wake() causes suspend_device_irqs() to treat the given IRQ in a special way. Namely, the IRQ remains enabled, by on the first interrupt it will be disabled, marked as pending and "suspended" so that it will be re-enabled by resume_device_irqs() during the subsequent system resume. Also -the PM core is notified about the event which casues the system suspend in +the PM core is notified about the event which causes the system suspend in progress to be aborted (that doesn't have to happen immediately, but at one of the points where the suspend thread looks for pending wakeup events). diff --git a/Documentation/power/userland-swsusp.txt b/Documentation/power/userland-swsusp.txt index 0e870825c1b9..bbfcd1bbedc5 100644 --- a/Documentation/power/userland-swsusp.txt +++ b/Documentation/power/userland-swsusp.txt @@ -99,7 +99,7 @@ SNAPSHOT_S2RAM - suspend to RAM; using this call causes the kernel to The device's read() operation can be used to transfer the snapshot image from the kernel. It has the following limitations: - you cannot read() more than one virtual memory page at a time -- read()s across page boundaries are impossible (ie. if ypu read() 1/2 of +- read()s across page boundaries are impossible (ie. if you read() 1/2 of a page in the previous call, you will only be able to read() _at_ _most_ 1/2 of the page in the next call) diff --git a/Documentation/ramoops.txt b/Documentation/ramoops.txt index 69b3cac4749d..5d8675615e59 100644 --- a/Documentation/ramoops.txt +++ b/Documentation/ramoops.txt @@ -14,11 +14,19 @@ survive after a restart. 1. Ramoops concepts -Ramoops uses a predefined memory area to store the dump. The start and size of -the memory area are set using two variables: +Ramoops uses a predefined memory area to store the dump. The start and size +and type of the memory area are set using three variables: * "mem_address" for the start * "mem_size" for the size. The memory size will be rounded down to a power of two. + * "mem_type" to specifiy if the memory type (default is pgprot_writecombine). + +Typically the default value of mem_type=0 should be used as that sets the pstore +mapping to pgprot_writecombine. Setting mem_type=1 attempts to use +pgprot_noncached, which only works on some platforms. This is because pstore +depends on atomic operations. At least on ARM, pgprot_noncached causes the +memory to be mapped strongly ordered, and atomic operations on strongly ordered +memory are implementation defined, and won't work on many ARMs such as omaps. The memory area is divided into "record_size" chunks (also rounded down to power of two) and each oops/panic writes a "record_size" chunk of @@ -55,6 +63,7 @@ Setting the ramoops parameters can be done in 2 different manners: static struct ramoops_platform_data ramoops_data = { .mem_size = <...>, .mem_address = <...>, + .mem_type = <...>, .record_size = <...>, .dump_oops = <...>, .ecc = <...>, diff --git a/Documentation/rfkill.txt b/Documentation/rfkill.txt index 427e89712f4a..2ee6ef9a6554 100644 --- a/Documentation/rfkill.txt +++ b/Documentation/rfkill.txt @@ -25,6 +25,9 @@ whether they can be changed or not: - soft block: writable radio block (need not be readable) that is set by the system software. +The rfkill subsystem has two parameters, rfkill.default_state and +rfkill.master_switch_mode, which are documented in kernel-parameters.txt. + 2. Implementation details diff --git a/Documentation/s390/Debugging390.txt b/Documentation/s390/Debugging390.txt index 462321c1aeea..3df8babcdc41 100644 --- a/Documentation/s390/Debugging390.txt +++ b/Documentation/s390/Debugging390.txt @@ -1,14 +1,14 @@ - - Debugging on Linux for s/390 & z/Architecture - by - Denis Joseph Barrow (djbarrow@de.ibm.com,barrow_dj@yahoo.com) - Copyright (C) 2000-2001 IBM Deutschland Entwicklung GmbH, IBM Corporation - Best viewed with fixed width fonts + + Debugging on Linux for s/390 & z/Architecture + by + Denis Joseph Barrow (djbarrow@de.ibm.com,barrow_dj@yahoo.com) + Copyright (C) 2000-2001 IBM Deutschland Entwicklung GmbH, IBM Corporation + Best viewed with fixed width fonts Overview of Document: ===================== -This document is intended to give a good overview of how to debug -Linux for s/390 & z/Architecture. It isn't intended as a complete reference & not a +This document is intended to give a good overview of how to debug Linux for +s/390 and z/Architecture. It is not intended as a complete reference and not a tutorial on the fundamentals of C & assembly. It doesn't go into 390 IO in any detail. It is intended to complement the documents in the reference section below & any other worthwhile references you get. @@ -26,11 +26,6 @@ The Linux for s/390 & z/Architecture Kernel Task Structure Register Usage & Stackframes on Linux for s/390 & z/Architecture A sample program with comments Compiling programs for debugging on Linux for s/390 & z/Architecture -Figuring out gcc compile errors -Debugging Tools -objdump -strace -Performance Debugging Debugging under VM s/390 & z/Architecture IO Overview Debugging IO on s/390 & z/Architecture under VM @@ -40,7 +35,6 @@ Examining core dumps ldd Debugging modules The proc file system -Starting points for debugging scripting languages etc. SysRq References Special Thanks @@ -49,18 +43,20 @@ Register Set ============ The current architectures have the following registers. -16 General propose registers, 32 bit on s/390 64 bit on z/Architecture, r0-r15 or gpr0-gpr15 used for arithmetic & addressing. - -16 Control registers, 32 bit on s/390 64 bit on z/Architecture, ( cr0-cr15 kernel usage only ) used for memory management, -interrupt control,debugging control etc. - -16 Access registers ( ar0-ar15 ) 32 bit on s/390 & z/Architecture -not used by normal programs but potentially could -be used as temporary storage. Their main purpose is their 1 to 1 -association with general purpose registers and are used in -the kernel for copying data between kernel & user address spaces. -Access register 0 ( & access register 1 on z/Architecture ( needs 64 bit -pointer ) ) is currently used by the pthread library as a pointer to +16 General propose registers, 32 bit on s/390 and 64 bit on z/Architecture, +r0-r15 (or gpr0-gpr15), used for arithmetic and addressing. + +16 Control registers, 32 bit on s/390 and 64 bit on z/Architecture, cr0-cr15, +kernel usage only, used for memory management, interrupt control, debugging +control etc. + +16 Access registers (ar0-ar15), 32 bit on both s/390 and z/Architecture, +normally not used by normal programs but potentially could be used as +temporary storage. These registers have a 1:1 association with general +purpose registers and are designed to be used in the so-called access +register mode to select different address spaces. +Access register 0 (and access register 1 on z/Architecture, which needs a +64 bit pointer) is currently used by the pthread library as a pointer to the current running threads private area. 16 64 bit floating point registers (fp0-fp15 ) IEEE & HFP floating @@ -95,18 +91,19 @@ s/390 z/Architecture 6 6 Input/Output interrupt Mask -7 7 External interrupt Mask used primarily for interprocessor signalling & - clock interrupts. +7 7 External interrupt Mask used primarily for interprocessor + signalling and clock interrupts. -8-11 8-11 PSW Key used for complex memory protection mechanism not used under linux +8-11 8-11 PSW Key used for complex memory protection mechanism + (not used under linux) 12 12 1 on s/390 0 on z/Architecture 13 13 Machine Check Mask 1=enable machine check interrupts -14 14 Wait State set this to 1 to stop the processor except for interrupts & give - time to other LPARS used in CPU idle in the kernel to increase overall - usage of processor resources. +14 14 Wait State. Set this to 1 to stop the processor except for + interrupts and give time to other LPARS. Used in CPU idle in + the kernel to increase overall usage of processor resources. 15 15 Problem state ( if set to 1 certain instructions are disabled ) all linux user programs run with this bit 1 @@ -114,28 +111,25 @@ s/390 z/Architecture 16-17 16-17 Address Space Control - 00 Primary Space Mode when DAT on - The linux kernel currently runs in this mode, CR1 is affiliated with - this mode & points to the primary segment table origin etc. - - 01 Access register mode this mode is used in functions to - copy data between kernel & user space. - - 10 Secondary space mode not used in linux however CR7 the - register affiliated with this mode is & this & normally - CR13=CR7 to allow us to copy data between kernel & user space. - We do this as follows: - We set ar2 to 0 to designate its - affiliated gpr ( gpr2 )to point to primary=kernel space. - We set ar4 to 1 to designate its - affiliated gpr ( gpr4 ) to point to secondary=home=user space - & then essentially do a memcopy(gpr2,gpr4,size) to - copy data between the address spaces, the reason we use home space for the - kernel & don't keep secondary space free is that code will not run in - secondary space. - - 11 Home Space Mode all user programs run in this mode. - it is affiliated with CR13. + 00 Primary Space Mode: + The register CR1 contains the primary address-space control ele- + ment (PASCE), which points to the primary space region/segment + table origin. + + 01 Access register mode + + 10 Secondary Space Mode: + The register CR7 contains the secondary address-space control + element (SASCE), which points to the secondary space region or + segment table origin. + + 11 Home Space Mode: + The register CR13 contains the home space address-space control + element (HASCE), which points to the home space region/segment + table origin. + + See "Address Spaces on Linux for s/390 & z/Architecture" below + for more information about address space usage in Linux. 18-19 18-19 Condition codes (CC) @@ -173,21 +167,23 @@ s/390 z/Architecture when loading the address with LPSWE otherwise a specification exception occurs, LPSW is fully backward compatible. - - + + Prefix Page(s) --------------- +-------------- This per cpu memory area is too intimately tied to the processor not to mention. -It exists between the real addresses 0-4096 on s/390 & 0-8192 z/Architecture & is exchanged -with a 1 page on s/390 or 2 pages on z/Architecture in absolute storage by the set -prefix instruction in linux'es startup. -This page is mapped to a different prefix for each processor in an SMP configuration -( assuming the os designer is sane of course :-) ). -Bytes 0-512 ( 200 hex ) on s/390 & 0-512,4096-4544,4604-5119 currently on z/Architecture -are used by the processor itself for holding such information as exception indications & -entry points for exceptions. -Bytes after 0xc00 hex are used by linux for per processor globals on s/390 & z/Architecture -( there is a gap on z/Architecture too currently between 0xc00 & 1000 which linux uses ). +It exists between the real addresses 0-4096 on s/390 and between 0-8192 on +z/Architecture and is exchanged with one page on s/390 or two pages on +z/Architecture in absolute storage by the set prefix instruction during Linux +startup. +This page is mapped to a different prefix for each processor in an SMP +configuration (assuming the OS designer is sane of course). +Bytes 0-512 (200 hex) on s/390 and 0-512, 4096-4544, 4604-5119 currently on +z/Architecture are used by the processor itself for holding such information +as exception indications and entry points for exceptions. +Bytes after 0xc00 hex are used by linux for per processor globals on s/390 and +z/Architecture (there is a gap on z/Architecture currently between 0xc00 and +0x1000, too, which is used by Linux). The closest thing to this on traditional architectures is the interrupt vector table. This is a good thing & does simplify some of the kernel coding however it means that we now cannot catch stray NULL pointers in the @@ -200,26 +196,26 @@ Address Spaces on Intel Linux The traditional Intel Linux is approximately mapped as follows forgive the ascii art. -0xFFFFFFFF 4GB Himem ***************** - * * - * Kernel Space * - * * - ***************** **************** -User Space Himem (typically 0xC0000000 3GB )* User Stack * * * - ***************** * * - * Shared Libs * * Next Process * - ***************** * to * - * * <== * Run * <== - * User Program * * * - * Data BSS * * * - * Text * * * - * Sections * * * -0x00000000 ***************** **************** - -Now it is easy to see that on Intel it is quite easy to recognise a kernel address -as being one greater than user space himem ( in this case 0xC0000000). -& addresses of less than this are the ones in the current running program on this -processor ( if an smp box ). +0xFFFFFFFF 4GB Himem ***************** + * * + * Kernel Space * + * * + ***************** **************** +User Space Himem * User Stack * * * +(typically 0xC0000000 3GB ) ***************** * * + * Shared Libs * * Next Process * + ***************** * to * + * * <== * Run * <== + * User Program * * * + * Data BSS * * * + * Text * * * + * Sections * * * +0x00000000 ***************** **************** + +Now it is easy to see that on Intel it is quite easy to recognise a kernel +address as being one greater than user space himem (in this case 0xC0000000), +and addresses of less than this are the ones in the current running program on +this processor (if an smp box). If using the virtual machine ( VM ) as a debugger it is quite difficult to know which user process is running as the address space you are looking at could be from any process in the run queue. @@ -249,14 +245,14 @@ currently 4TB of physical memory currently on z/Architecture. Address Spaces on Linux for s/390 & z/Architecture ================================================== -Our addressing scheme is as follows - +Our addressing scheme is basically as follows: + Primary Space Home Space Himem 0x7fffffff 2GB on s/390 ***************** **************** currently 0x3ffffffffff (2^42)-1 * User Stack * * * on z/Architecture. ***************** * * - * Shared Libs * * * - ***************** * * + * Shared Libs * * * + ***************** * * * * * Kernel * * User Program * * * * Data BSS * * * @@ -264,18 +260,55 @@ on z/Architecture. ***************** * * * Sections * * * 0x00000000 ***************** **************** -This also means that we need to look at the PSW problem state bit -or the addressing mode to decide whether we are looking at -user or kernel space. +This also means that we need to look at the PSW problem state bit and the +addressing mode to decide whether we are looking at user or kernel space. + +User space runs in primary address mode (or access register mode within +the vdso code). + +The kernel usually also runs in home space mode, however when accessing +user space the kernel switches to primary or secondary address mode if +the mvcos instruction is not available or if a compare-and-swap (futex) +instruction on a user space address is performed. + +When also looking at the ASCE control registers, this means: + +User space: +- runs in primary or access register mode +- cr1 contains the user asce +- cr7 contains the user asce +- cr13 contains the kernel asce + +Kernel space: +- runs in home space mode +- cr1 contains the user or kernel asce + -> the kernel asce is loaded when a uaccess requires primary or + secondary address mode +- cr7 contains the user or kernel asce, (changed with set_fs()) +- cr13 contains the kernel asce + +In case of uaccess the kernel changes to: +- primary space mode in case of a uaccess (copy_to_user) and uses + e.g. the mvcp instruction to access user space. However the kernel + will stay in home space mode if the mvcos instruction is available +- secondary space mode in case of futex atomic operations, so that the + instructions come from primary address space and data from secondary + space + +In case of KVM, the kernel runs in home space mode, but cr1 gets switched +to contain the gmap asce before the SIE instruction gets executed. When +the SIE instruction is finished, cr1 will be switched back to contain the +user asce. + Virtual Addresses on s/390 & z/Architecture =========================================== A virtual address on s/390 is made up of 3 parts -The SX ( segment index, roughly corresponding to the PGD & PMD in linux terminology ) -being bits 1-11. -The PX ( page index, corresponding to the page table entry (pte) in linux terminology ) -being bits 12-19. +The SX (segment index, roughly corresponding to the PGD & PMD in Linux +terminology) being bits 1-11. +The PX (page index, corresponding to the page table entry (pte) in Linux +terminology) being bits 12-19. The remaining bits BX (the byte index are the offset in the page ) i.e. bits 20 to 31. @@ -339,9 +372,9 @@ each processor as follows. * ( 8K ) * 16K aligned ************************ -What this means is that we don't need to dedicate any register or global variable -to point to the current running process & can retrieve it with the following -very simple construct for s/390 & one very similar for z/Architecture. +What this means is that we don't need to dedicate any register or global +variable to point to the current running process & can retrieve it with the +following very simple construct for s/390 & one very similar for z/Architecture. static inline struct task_struct * get_current(void) { @@ -374,8 +407,8 @@ Note: To follow stackframes requires a knowledge of C or Pascal & limited knowledge of one assembly language. It should be noted that there are some differences between the -s/390 & z/Architecture stack layouts as the z/Architecture stack layout didn't have -to maintain compatibility with older linkage formats. +s/390 and z/Architecture stack layouts as the z/Architecture stack layout +didn't have to maintain compatibility with older linkage formats. Glossary: --------- @@ -411,7 +444,7 @@ The code generated by the compiler to return to the caller. frameless-function A frameless function in Linux for s390 & z/Architecture is one which doesn't -need more than the register save area ( 96 bytes on s/390, 160 on z/Architecture ) +need more than the register save area (96 bytes on s/390, 160 on z/Architecture) given to it by the caller. A frameless function never: 1) Sets up a back chain. @@ -559,8 +592,8 @@ A sample program with comments. Comments on the function test ----------------------------- -1) It didn't need to set up a pointer to the constant pool gpr13 as it isn't used -( :-( ). +1) It didn't need to set up a pointer to the constant pool gpr13 as it is not +used ( :-( ). 2) This is a frameless function & no stack is bought. 3) The compiler was clever enough to recognise that it could return the value in r2 as well as use it for the passed in parameter ( :-) ). @@ -706,376 +739,7 @@ Debugging with optimisation has since much improved after fixing some bugs, please make sure you are using gdb-5.0 or later developed after Nov'2000. -Figuring out gcc compile errors -=============================== -If you are getting a lot of syntax errors compiling a program & the problem -isn't blatantly obvious from the source. -It often helps to just preprocess the file, this is done with the -E -option in gcc. -What this does is that it runs through the very first phase of compilation -( compilation in gcc is done in several stages & gcc calls many programs to -achieve its end result ) with the -E option gcc just calls the gcc preprocessor (cpp). -The c preprocessor does the following, it joins all the files #included together -recursively ( #include files can #include other files ) & also the c file you wish to compile. -It puts a fully qualified path of the #included files in a comment & it -does macro expansion. -This is useful for debugging because -1) You can double check whether the files you expect to be included are the ones -that are being included ( e.g. double check that you aren't going to the i386 asm directory ). -2) Check that macro definitions aren't clashing with typedefs, -3) Check that definitions aren't being used before they are being included. -4) Helps put the line emitting the error under the microscope if it contains macros. - -For convenience the Linux kernel's makefile will do preprocessing automatically for you -by suffixing the file you want built with .i ( instead of .o ) - -e.g. -from the linux directory type -make arch/s390/kernel/signal.i -this will build - -s390-gcc -D__KERNEL__ -I/home1/barrow/linux/include -Wall -Wstrict-prototypes -O2 -fomit-frame-pointer --fno-strict-aliasing -D__SMP__ -pipe -fno-strength-reduce -E arch/s390/kernel/signal.c -> arch/s390/kernel/signal.i - -Now look at signal.i you should see something like. - - -# 1 "/home1/barrow/linux/include/asm/types.h" 1 -typedef unsigned short umode_t; -typedef __signed__ char __s8; -typedef unsigned char __u8; -typedef __signed__ short __s16; -typedef unsigned short __u16; - -If instead you are getting errors further down e.g. -unknown instruction:2515 "move.l" or better still unknown instruction:2515 -"Fixme not implemented yet, call Martin" you are probably are attempting to compile some code -meant for another architecture or code that is simply not implemented, with a fixme statement -stuck into the inline assembly code so that the author of the file now knows he has work to do. -To look at the assembly emitted by gcc just before it is about to call gas ( the gnu assembler ) -use the -S option. -Again for your convenience the Linux kernel's Makefile will hold your hand & -do all this donkey work for you also by building the file with the .s suffix. -e.g. -from the Linux directory type -make arch/s390/kernel/signal.s - -s390-gcc -D__KERNEL__ -I/home1/barrow/linux/include -Wall -Wstrict-prototypes -O2 -fomit-frame-pointer --fno-strict-aliasing -D__SMP__ -pipe -fno-strength-reduce -S arch/s390/kernel/signal.c --o arch/s390/kernel/signal.s - - -This will output something like, ( please note the constant pool & the useful comments -in the prologue to give you a hand at interpreting it ). - -.LC54: - .string "misaligned (__u16 *) in __xchg\n" -.LC57: - .string "misaligned (__u32 *) in __xchg\n" -.L$PG1: # Pool sys_sigsuspend -.LC192: - .long -262401 -.LC193: - .long -1 -.LC194: - .long schedule-.L$PG1 -.LC195: - .long do_signal-.L$PG1 - .align 4 -.globl sys_sigsuspend - .type sys_sigsuspend,@function -sys_sigsuspend: -# leaf function 0 -# automatics 16 -# outgoing args 0 -# need frame pointer 0 -# call alloca 0 -# has varargs 0 -# incoming args (stack) 0 -# function length 168 - STM 8,15,32(15) - LR 0,15 - AHI 15,-112 - BASR 13,0 -.L$CO1: AHI 13,.L$PG1-.L$CO1 - ST 0,0(15) - LR 8,2 - N 5,.LC192-.L$PG1(13) - -Adding -g to the above output makes the output even more useful -e.g. typing -make CC:="s390-gcc -g" kernel/sched.s - -which compiles. -s390-gcc -g -D__KERNEL__ -I/home/barrow/linux-2.3/include -Wall -Wstrict-prototypes -O2 -fomit-frame-pointer -fno-strict-aliasing -pipe -fno-strength-reduce -S kernel/sched.c -o kernel/sched.s - -also outputs stabs ( debugger ) info, from this info you can find out the -offsets & sizes of various elements in structures. -e.g. the stab for the structure -struct rlimit { - unsigned long rlim_cur; - unsigned long rlim_max; -}; -is -.stabs "rlimit:T(151,2)=s8rlim_cur:(0,5),0,32;rlim_max:(0,5),32,32;;",128,0,0,0 -from this stab you can see that -rlimit_cur starts at bit offset 0 & is 32 bits in size -rlimit_max starts at bit offset 32 & is 32 bits in size. - - -Debugging Tools: -================ - -objdump -======= -This is a tool with many options the most useful being ( if compiled with -g). -objdump --source <victim program or object file> > <victims debug listing > - - -The whole kernel can be compiled like this ( Doing this will make a 17MB kernel -& a 200 MB listing ) however you have to strip it before building the image -using the strip command to make it a more reasonable size to boot it. - -A source/assembly mixed dump of the kernel can be done with the line -objdump --source vmlinux > vmlinux.lst -Also, if the file isn't compiled -g, this will output as much debugging information -as it can (e.g. function names). This is very slow as it spends lots -of time searching for debugging info. The following self explanatory line should be used -instead if the code isn't compiled -g, as it is much faster: -objdump --disassemble-all --syms vmlinux > vmlinux.lst - -As hard drive space is valuable most of us use the following approach. -1) Look at the emitted psw on the console to find the crash address in the kernel. -2) Look at the file System.map ( in the linux directory ) produced when building -the kernel to find the closest address less than the current PSW to find the -offending function. -3) use grep or similar to search the source tree looking for the source file - with this function if you don't know where it is. -4) rebuild this object file with -g on, as an example suppose the file was -( /arch/s390/kernel/signal.o ) -5) Assuming the file with the erroneous function is signal.c Move to the base of the -Linux source tree. -6) rm /arch/s390/kernel/signal.o -7) make /arch/s390/kernel/signal.o -8) watch the gcc command line emitted -9) type it in again or alternatively cut & paste it on the console adding the -g option. -10) objdump --source arch/s390/kernel/signal.o > signal.lst -This will output the source & the assembly intermixed, as the snippet below shows -This will unfortunately output addresses which aren't the same -as the kernel ones you should be able to get around the mental arithmetic -by playing with the --adjust-vma parameter to objdump. - - - - -static inline void spin_lock(spinlock_t *lp) -{ - a0: 18 34 lr %r3,%r4 - a2: a7 3a 03 bc ahi %r3,956 - __asm__ __volatile(" lhi 1,-1\n" - a6: a7 18 ff ff lhi %r1,-1 - aa: 1f 00 slr %r0,%r0 - ac: ba 01 30 00 cs %r0,%r1,0(%r3) - b0: a7 44 ff fd jm aa <sys_sigsuspend+0x2e> - saveset = current->blocked; - b4: d2 07 f0 68 mvc 104(8,%r15),972(%r4) - b8: 43 cc - return (set->sig[0] & mask) != 0; -} - -6) If debugging under VM go down to that section in the document for more info. - - -I now have a tool which takes the pain out of --adjust-vma -& you are able to do something like -make /arch/s390/kernel/traps.lst -& it automatically generates the correctly relocated entries for -the text segment in traps.lst. -This tool is now standard in linux distro's in scripts/makelst - -strace: -------- -Q. What is it ? -A. It is a tool for intercepting calls to the kernel & logging them -to a file & on the screen. - -Q. What use is it ? -A. You can use it to find out what files a particular program opens. - - - -Example 1 ---------- -If you wanted to know does ping work but didn't have the source -strace ping -c 1 127.0.0.1 -& then look at the man pages for each of the syscalls below, -( In fact this is sometimes easier than looking at some spaghetti -source which conditionally compiles for several architectures ). -Not everything that it throws out needs to make sense immediately. - -Just looking quickly you can see that it is making up a RAW socket -for the ICMP protocol. -Doing an alarm(10) for a 10 second timeout -& doing a gettimeofday call before & after each read to see -how long the replies took, & writing some text to stdout so the user -has an idea what is going on. - -socket(PF_INET, SOCK_RAW, IPPROTO_ICMP) = 3 -getuid() = 0 -setuid(0) = 0 -stat("/usr/share/locale/C/libc.cat", 0xbffff134) = -1 ENOENT (No such file or directory) -stat("/usr/share/locale/libc/C", 0xbffff134) = -1 ENOENT (No such file or directory) -stat("/usr/local/share/locale/C/libc.cat", 0xbffff134) = -1 ENOENT (No such file or directory) -getpid() = 353 -setsockopt(3, SOL_SOCKET, SO_BROADCAST, [1], 4) = 0 -setsockopt(3, SOL_SOCKET, SO_RCVBUF, [49152], 4) = 0 -fstat(1, {st_mode=S_IFCHR|0620, st_rdev=makedev(3, 1), ...}) = 0 -mmap(0, 4096, PROT_READ|PROT_WRITE, MAP_PRIVATE|MAP_ANONYMOUS, -1, 0) = 0x40008000 -ioctl(1, TCGETS, {B9600 opost isig icanon echo ...}) = 0 -write(1, "PING 127.0.0.1 (127.0.0.1): 56 d"..., 42PING 127.0.0.1 (127.0.0.1): 56 data bytes -) = 42 -sigaction(SIGINT, {0x8049ba0, [], SA_RESTART}, {SIG_DFL}) = 0 -sigaction(SIGALRM, {0x8049600, [], SA_RESTART}, {SIG_DFL}) = 0 -gettimeofday({948904719, 138951}, NULL) = 0 -sendto(3, "\10\0D\201a\1\0\0\17#\2178\307\36"..., 64, 0, {sin_family=AF_INET, -sin_port=htons(0), sin_addr=inet_addr("127.0.0.1")}, 16) = 64 -sigaction(SIGALRM, {0x8049600, [], SA_RESTART}, {0x8049600, [], SA_RESTART}) = 0 -sigaction(SIGALRM, {0x8049ba0, [], SA_RESTART}, {0x8049600, [], SA_RESTART}) = 0 -alarm(10) = 0 -recvfrom(3, "E\0\0T\0005\0\0@\1|r\177\0\0\1\177"..., 192, 0, -{sin_family=AF_INET, sin_port=htons(50882), sin_addr=inet_addr("127.0.0.1")}, [16]) = 84 -gettimeofday({948904719, 160224}, NULL) = 0 -recvfrom(3, "E\0\0T\0006\0\0\377\1\275p\177\0"..., 192, 0, -{sin_family=AF_INET, sin_port=htons(50882), sin_addr=inet_addr("127.0.0.1")}, [16]) = 84 -gettimeofday({948904719, 166952}, NULL) = 0 -write(1, "64 bytes from 127.0.0.1: icmp_se"..., -5764 bytes from 127.0.0.1: icmp_seq=0 ttl=255 time=28.0 ms - -Example 2 ---------- -strace passwd 2>&1 | grep open -produces the following output -open("/etc/ld.so.cache", O_RDONLY) = 3 -open("/opt/kde/lib/libc.so.5", O_RDONLY) = -1 ENOENT (No such file or directory) -open("/lib/libc.so.5", O_RDONLY) = 3 -open("/dev", O_RDONLY) = 3 -open("/var/run/utmp", O_RDONLY) = 3 -open("/etc/passwd", O_RDONLY) = 3 -open("/etc/shadow", O_RDONLY) = 3 -open("/etc/login.defs", O_RDONLY) = 4 -open("/dev/tty", O_RDONLY) = 4 - -The 2>&1 is done to redirect stderr to stdout & grep is then filtering this input -through the pipe for each line containing the string open. - - -Example 3 ---------- -Getting sophisticated -telnetd crashes & I don't know why - -Steps ------ -1) Replace the following line in /etc/inetd.conf -telnet stream tcp nowait root /usr/sbin/in.telnetd -h -with -telnet stream tcp nowait root /blah - -2) Create the file /blah with the following contents to start tracing telnetd -#!/bin/bash -/usr/bin/strace -o/t1 -f /usr/sbin/in.telnetd -h -3) chmod 700 /blah to make it executable only to root -4) -killall -HUP inetd -or ps aux | grep inetd -get inetd's process id -& kill -HUP inetd to restart it. - -Important options ------------------ --o is used to tell strace to output to a file in our case t1 in the root directory --f is to follow children i.e. -e.g in our case above telnetd will start the login process & subsequently a shell like bash. -You will be able to tell which is which from the process ID's listed on the left hand side -of the strace output. --p<pid> will tell strace to attach to a running process, yup this can be done provided - it isn't being traced or debugged already & you have enough privileges, -the reason 2 processes cannot trace or debug the same program is that strace -becomes the parent process of the one being debugged & processes ( unlike people ) -can have only one parent. - - -However the file /t1 will get big quite quickly -to test it telnet 127.0.0.1 - -now look at what files in.telnetd execve'd -413 execve("/usr/sbin/in.telnetd", ["/usr/sbin/in.telnetd", "-h"], [/* 17 vars */]) = 0 -414 execve("/bin/login", ["/bin/login", "-h", "localhost", "-p"], [/* 2 vars */]) = 0 - -Whey it worked!. - - -Other hints: ------------- -If the program is not very interactive ( i.e. not much keyboard input ) -& is crashing in one architecture but not in another you can do -an strace of both programs under as identical a scenario as you can -on both architectures outputting to a file then. -do a diff of the two traces using the diff program -i.e. -diff output1 output2 -& maybe you'll be able to see where the call paths differed, this -is possibly near the cause of the crash. - -More info ---------- -Look at man pages for strace & the various syscalls -e.g. man strace, man alarm, man socket. - -Performance Debugging -===================== -gcc is capable of compiling in profiling code just add the -p option -to the CFLAGS, this obviously affects program size & performance. -This can be used by the gprof gnu profiling tool or the -gcov the gnu code coverage tool ( code coverage is a means of testing -code quality by checking if all the code in an executable in exercised by -a tester ). - - -Using top to find out where processes are sleeping in the kernel ----------------------------------------------------------------- -To do this copy the System.map from the root directory where -the linux kernel was built to the /boot directory on your -linux machine. -Start top -Now type fU<return> -You should see a new field called WCHAN which -tells you where each process is sleeping here is a typical output. - - 6:59pm up 41 min, 1 user, load average: 0.00, 0.00, 0.00 -28 processes: 27 sleeping, 1 running, 0 zombie, 0 stopped -CPU states: 0.0% user, 0.1% system, 0.0% nice, 99.8% idle -Mem: 254900K av, 45976K used, 208924K free, 0K shrd, 28636K buff -Swap: 0K av, 0K used, 0K free 8620K cached - - PID USER PRI NI SIZE RSS SHARE WCHAN STAT LIB %CPU %MEM TIME COMMAND - 750 root 12 0 848 848 700 do_select S 0 0.1 0.3 0:00 in.telnetd - 767 root 16 0 1140 1140 964 R 0 0.1 0.4 0:00 top - 1 root 8 0 212 212 180 do_select S 0 0.0 0.0 0:00 init - 2 root 9 0 0 0 0 down_inte SW 0 0.0 0.0 0:00 kmcheck - -The time command ----------------- -Another related command is the time command which gives you an indication -of where a process is spending the majority of its time. -e.g. -time ping -c 5 nc -outputs -real 0m4.054s -user 0m0.010s -sys 0m0.010s Debugging under VM ================== @@ -1083,35 +747,34 @@ Debugging under VM Notes ----- Addresses & values in the VM debugger are always hex never decimal -Address ranges are of the format <HexValue1>-<HexValue2> or <HexValue1>.<HexValue2> -e.g. The address range 0x2000 to 0x3000 can be described as 2000-3000 or 2000.1000 +Address ranges are of the format <HexValue1>-<HexValue2> or +<HexValue1>.<HexValue2> +For example, the address range 0x2000 to 0x3000 can be described as 2000-3000 +or 2000.1000 The VM Debugger is case insensitive. -VM's strengths are usually other debuggers weaknesses you can get at any resource -no matter how sensitive e.g. memory management resources,change address translation -in the PSW. For kernel hacking you will reap dividends if you get good at it. - -The VM Debugger displays operators but not operands, probably because some -of it was written when memory was expensive & the programmer was probably proud that -it fitted into 2k of memory & the programmers & didn't want to shock hardcore VM'ers by -changing the interface :-), also the debugger displays useful information on the same line & -the author of the code probably felt that it was a good idea not to go over -the 80 columns on the screen. - -As some of you are probably in a panic now this isn't as unintuitive as it may seem -as the 390 instructions are easy to decode mentally & you can make a good guess at a lot -of them as all the operands are nibble ( half byte aligned ) & if you have an objdump listing -also it is quite easy to follow, if you don't have an objdump listing keep a copy of -the s/390 Reference Summary & look at between pages 2 & 7 or alternatively the -s/390 principles of operation. +VM's strengths are usually other debuggers weaknesses you can get at any +resource no matter how sensitive e.g. memory management resources, change +address translation in the PSW. For kernel hacking you will reap dividends if +you get good at it. + +The VM Debugger displays operators but not operands, and also the debugger +displays useful information on the same line as the author of the code probably +felt that it was a good idea not to go over the 80 columns on the screen. +This isn't as unintuitive as it may seem as the s/390 instructions are easy to +decode mentally and you can make a good guess at a lot of them as all the +operands are nibble (half byte aligned). +So if you have an objdump listing by hand, it is quite easy to follow, and if +you don't have an objdump listing keep a copy of the s/390 Reference Summary +or alternatively the s/390 principles of operation next to you. e.g. even I can guess that 0001AFF8' LR 180F CC 0 is a ( load register ) lr r0,r15 -Also it is very easy to tell the length of a 390 instruction from the 2 most significant -bits in the instruction ( not that this info is really useful except if you are trying to -make sense of a hexdump of code ). +Also it is very easy to tell the length of a 390 instruction from the 2 most +significant bits in the instruction (not that this info is really useful except +if you are trying to make sense of a hexdump of code). Here is a table Bits Instruction Length ------------------------------------------ @@ -1120,9 +783,6 @@ Bits Instruction Length 10 4 Bytes 11 6 Bytes - - - The debugger also displays other useful info on the same line such as the addresses being operated on destination addresses of branches & condition codes. e.g. @@ -1193,8 +853,8 @@ Displaying & modifying Registers -------------------------------- D G will display all the gprs Adding a extra G to all the commands is necessary to access the full 64 bit -content in VM on z/Architecture obviously this isn't required for access registers -as these are still 32 bit. +content in VM on z/Architecture. Obviously this isn't required for access +registers as these are still 32 bit. e.g. DGG instead of DG D X will display all the control registers D AR will display all the access registers @@ -1210,10 +870,11 @@ Displaying Memory ----------------- To display memory mapped using the current PSW's mapping try D <range> -To make VM display a message each time it hits a particular address & continue try +To make VM display a message each time it hits a particular address and +continue try D I<range> will disassemble/display a range of instructions. ST addr 32 bit word will store a 32 bit aligned address -D T<range> will display the EBCDIC in an address ( if you are that way inclined ) +D T<range> will display the EBCDIC in an address (if you are that way inclined) D R<range> will display real addresses ( without DAT ) but with prefixing. There are other complex options to display if you need to get at say home space but are in primary space the easiest thing to do is to temporarily @@ -1224,8 +885,8 @@ restore it. Hints ----- -If you want to issue a debugger command without halting your virtual machine with the -PA1 key try prefixing the command with #CP e.g. +If you want to issue a debugger command without halting your virtual machine +with the PA1 key try prefixing the command with #CP e.g. #cp tr i pswa 2000 also suffixing most debugger commands with RUN will cause them not to stop just display the mnemonic at the current instruction on the console. @@ -1243,9 +904,10 @@ This sends a message to your own console each time do_signal is entered. script with breakpoints on every kernel procedure, this isn't a good idea because there are thousands of these routines & VM can only set 255 breakpoints at a time so you nearly had to spend as long pruning the file down as you would -entering the msg's by hand ),however, the trick might be useful for a single object file. -On linux'es 3270 emulator x3270 there is a very useful option under the file ment -Save Screens In File this is very good of keeping a copy of traces. +entering the msgs by hand), however, the trick might be useful for a single +object file. In the 3270 terminal emulator x3270 there is a very useful option +in the file menu called "Save Screen In File" - this is very good for keeping a +copy of traces. From CMS help <command name> will give you online help on a particular command. e.g. @@ -1260,7 +922,8 @@ SET PF9 IMM B This does a single step in VM on pressing F8. SET PF10 ^ This sets up the ^ key. -which can be used for ^c (ctrl-c),^z (ctrl-z) which can't be typed directly into some 3270 consoles. +which can be used for ^c (ctrl-c),^z (ctrl-z) which can't be typed directly +into some 3270 consoles. SET PF11 ^- This types the starting keystrokes for a sysrq see SysRq below. SET PF12 RETRIEVE @@ -1354,8 +1017,8 @@ Tracing Program Exceptions -------------------------- If you get a crash which says something like illegal operation or specification exception followed by a register dump -You can restart linux & trace these using the tr prog <range or value> trace option. - +You can restart linux & trace these using the tr prog <range or value> trace +option. The most common ones you will normally be tracing for is @@ -1397,9 +1060,10 @@ TR GOTO INITIAL Tracing linux syscalls under VM ------------------------------- -Syscalls are implemented on Linux for S390 by the Supervisor call instruction (SVC) there 256 -possibilities of these as the instruction is made up of a 0xA opcode & the second byte being -the syscall number. They are traced using the simple command. +Syscalls are implemented on Linux for S390 by the Supervisor call instruction +(SVC). There 256 possibilities of these as the instruction is made up of a 0xA +opcode and the second byte being the syscall number. They are traced using the +simple command: TR SVC <Optional value or range> the syscalls are defined in linux/arch/s390/include/asm/unistd.h e.g. to trace all file opens just do @@ -1410,12 +1074,12 @@ SMP Specific commands --------------------- To find out how many cpus you have Q CPUS displays all the CPU's available to your virtual machine -To find the cpu that the current cpu VM debugger commands are being directed at do -Q CPU to change the current cpu VM debugger commands are being directed at do +To find the cpu that the current cpu VM debugger commands are being directed at +do Q CPU to change the current cpu VM debugger commands are being directed at do CPU <desired cpu no> -On a SMP guest issue a command to all CPUs try prefixing the command with cpu all. -To issue a command to a particular cpu try cpu <cpu number> e.g. +On a SMP guest issue a command to all CPUs try prefixing the command with cpu +all. To issue a command to a particular cpu try cpu <cpu number> e.g. CPU 01 TR I R 2000.3000 If you are running on a guest with several cpus & you have a IO related problem & cannot follow the flow of code but you know it isn't smp related. @@ -1441,10 +1105,10 @@ D TX0.100 Alternatively ============= -Under older VM debuggers ( I love EBDIC too ) you can use this little program I wrote which -will convert a command line of hex digits to ascii text which can be compiled under linux & -you can copy the hex digits from your x3270 terminal to your xterm if you are debugging -from a linuxbox. +Under older VM debuggers (I love EBDIC too) you can use following little +program which converts a command line of hex digits to ascii text. It can be +compiled under linux and you can copy the hex digits from your x3270 terminal +to your xterm if you are debugging from a linuxbox. This is quite useful when looking at a parameter passed in as a text string under VM ( unless you are good at decoding ASCII in your head ). @@ -1454,14 +1118,14 @@ TR SVC 5 We have stopped at a breakpoint 000151B0' SVC 0A05 -> 0001909A' CC 0 -D 20.8 to check the SVC old psw in the prefix area & see was it from userspace -( for the layout of the prefix area consult P18 of the s/390 390 Reference Summary -if you have it available ). +D 20.8 to check the SVC old psw in the prefix area and see was it from userspace +(for the layout of the prefix area consult the "Fixed Storage Locations" +chapter of the s/390 Reference Summary if you have it available). V00000020 070C2000 800151B2 The problem state bit wasn't set & it's also too early in the boot sequence for it to be a userspace SVC if it was we would have to temporarily switch the -psw to user space addressing so we could get at the first parameter of the open in -gpr2. +psw to user space addressing so we could get at the first parameter of the open +in gpr2. Next do a D G2 GPR 2 = 00014CB4 @@ -1548,9 +1212,9 @@ Here are the tricks I use 9 out of 10 times it works pretty well, When your backchain reaches a dead end -------------------------------------- -This can happen when an exception happens in the kernel & the kernel is entered twice -if you reach the NULL pointer at the end of the back chain you should be -able to sniff further back if you follow the following tricks. +This can happen when an exception happens in the kernel and the kernel is +entered twice. If you reach the NULL pointer at the end of the back chain you +should be able to sniff further back if you follow the following tricks. 1) A kernel address should be easy to recognise since it is in primary space & the problem state bit isn't set & also The Hi bit of the address is set. @@ -1600,8 +1264,8 @@ V000FFFD0 00010400 80010802 8001085A 000FFFA0 our 3rd return address is 8001085A -as the 04B52002 looks suspiciously like rubbish it is fair to assume that the kernel entry routines -for the sake of optimisation don't set up a backchain. +as the 04B52002 looks suspiciously like rubbish it is fair to assume that the +kernel entry routines for the sake of optimisation don't set up a backchain. now look at System.map to see if the addresses make any sense. @@ -1629,67 +1293,75 @@ Congrats you've done your first backchain. s/390 & z/Architecture IO Overview ================================== -I am not going to give a course in 390 IO architecture as this would take me quite a -while & I'm no expert. Instead I'll give a 390 IO architecture summary for Dummies if you have -the s/390 principles of operation available read this instead. If nothing else you may find a few -useful keywords in here & be able to use them on a web search engine like altavista to find -more useful information. +I am not going to give a course in 390 IO architecture as this would take me +quite a while and I'm no expert. Instead I'll give a 390 IO architecture +summary for Dummies. If you have the s/390 principles of operation available +read this instead. If nothing else you may find a few useful keywords in here +and be able to use them on a web search engine to find more useful information. Unlike other bus architectures modern 390 systems do their IO using mostly -fibre optics & devices such as tapes & disks can be shared between several mainframes, -also S390 can support up to 65536 devices while a high end PC based system might be choking -with around 64. Here is some of the common IO terminology +fibre optics and devices such as tapes and disks can be shared between several +mainframes. Also S390 can support up to 65536 devices while a high end PC based +system might be choking with around 64. -Subchannel: -This is the logical number most IO commands use to talk to an IO device there can be up to -0x10000 (65536) of these in a configuration typically there is a few hundred. Under VM -for simplicity they are allocated contiguously, however on the native hardware they are not -they typically stay consistent between boots provided no new hardware is inserted or removed. -Under Linux for 390 we use these as IRQ's & also when issuing an IO command (CLEAR SUBCHANNEL, -HALT SUBCHANNEL,MODIFY SUBCHANNEL,RESUME SUBCHANNEL,START SUBCHANNEL,STORE SUBCHANNEL & -TEST SUBCHANNEL ) we use this as the ID of the device we wish to talk to, the most -important of these instructions are START SUBCHANNEL ( to start IO ), TEST SUBCHANNEL ( to check -whether the IO completed successfully ), & HALT SUBCHANNEL ( to kill IO ), a subchannel -can have up to 8 channel paths to a device this offers redundancy if one is not available. +Here is some of the common IO terminology: +Subchannel: +This is the logical number most IO commands use to talk to an IO device. There +can be up to 0x10000 (65536) of these in a configuration, typically there are a +few hundred. Under VM for simplicity they are allocated contiguously, however +on the native hardware they are not. They typically stay consistent between +boots provided no new hardware is inserted or removed. +Under Linux for s390 we use these as IRQ's and also when issuing an IO command +(CLEAR SUBCHANNEL, HALT SUBCHANNEL, MODIFY SUBCHANNEL, RESUME SUBCHANNEL, +START SUBCHANNEL, STORE SUBCHANNEL and TEST SUBCHANNEL). We use this as the ID +of the device we wish to talk to. The most important of these instructions are +START SUBCHANNEL (to start IO), TEST SUBCHANNEL (to check whether the IO +completed successfully) and HALT SUBCHANNEL (to kill IO). A subchannel can have +up to 8 channel paths to a device, this offers redundancy if one is not +available. Device Number: -This number remains static & Is closely tied to the hardware, there are 65536 of these -also they are made up of a CHPID ( Channel Path ID, the most significant 8 bits ) -& another lsb 8 bits. These remain static even if more devices are inserted or removed -from the hardware, there is a 1 to 1 mapping between Subchannels & Device Numbers provided -devices aren't inserted or removed. +This number remains static and is closely tied to the hardware. There are 65536 +of these, made up of a CHPID (Channel Path ID, the most significant 8 bits) and +another lsb 8 bits. These remain static even if more devices are inserted or +removed from the hardware. There is a 1 to 1 mapping between subchannels and +device numbers, provided devices aren't inserted or removed. Channel Control Words: -CCWS are linked lists of instructions initially pointed to by an operation request block (ORB), -which is initially given to Start Subchannel (SSCH) command along with the subchannel number -for the IO subsystem to process while the CPU continues executing normal code. -These come in two flavours, Format 0 ( 24 bit for backward ) -compatibility & Format 1 ( 31 bit ). These are typically used to issue read & write -( & many other instructions ) they consist of a length field & an absolute address field. -For each IO typically get 1 or 2 interrupts one for channel end ( primary status ) when the -channel is idle & the second for device end ( secondary status ) sometimes you get both -concurrently, you check how the IO went on by issuing a TEST SUBCHANNEL at each interrupt, -from which you receive an Interruption response block (IRB). If you get channel & device end -status in the IRB without channel checks etc. your IO probably went okay. If you didn't you -probably need a doctor to examine the IRB & extended status word etc. +CCWs are linked lists of instructions initially pointed to by an operation +request block (ORB), which is initially given to Start Subchannel (SSCH) +command along with the subchannel number for the IO subsystem to process +while the CPU continues executing normal code. +CCWs come in two flavours, Format 0 (24 bit for backward compatibility) and +Format 1 (31 bit). These are typically used to issue read and write (and many +other) instructions. They consist of a length field and an absolute address +field. +Each IO typically gets 1 or 2 interrupts, one for channel end (primary status) +when the channel is idle, and the second for device end (secondary status). +Sometimes you get both concurrently. You check how the IO went on by issuing a +TEST SUBCHANNEL at each interrupt, from which you receive an Interruption +response block (IRB). If you get channel and device end status in the IRB +without channel checks etc. your IO probably went okay. If you didn't you +probably need to examine the IRB, extended status word etc. If an error occurs, more sophisticated control units have a facility known as -concurrent sense this means that if an error occurs Extended sense information will -be presented in the Extended status word in the IRB if not you have to issue a -subsequent SENSE CCW command after the test subchannel. +concurrent sense. This means that if an error occurs Extended sense information +will be presented in the Extended status word in the IRB. If not you have to +issue a subsequent SENSE CCW command after the test subchannel. -TPI( Test pending interrupt) can also be used for polled IO but in multitasking multiprocessor -systems it isn't recommended except for checking special cases ( i.e. non looping checks for -pending IO etc. ). +TPI (Test pending interrupt) can also be used for polled IO, but in +multitasking multiprocessor systems it isn't recommended except for +checking special cases (i.e. non looping checks for pending IO etc.). -Store Subchannel & Modify Subchannel can be used to examine & modify operating characteristics -of a subchannel ( e.g. channel paths ). +Store Subchannel and Modify Subchannel can be used to examine and modify +operating characteristics of a subchannel (e.g. channel paths). Other IO related Terms: Sysplex: S390's Clustering Technology -QDIO: S390's new high speed IO architecture to support devices such as gigabit ethernet, -this architecture is also designed to be forward compatible with up & coming 64 bit machines. +QDIO: S390's new high speed IO architecture to support devices such as gigabit +ethernet, this architecture is also designed to be forward compatible with +upcoming 64 bit machines. General Concepts @@ -1746,37 +1418,40 @@ sometimes called Bus-and Tag & sometimes Original Equipment Manufacturers Interface (OEMI). This byte wide Parallel channel path/bus has parity & data on the "Bus" cable -& control lines on the "Tag" cable. These can operate in byte multiplex mode for -sharing between several slow devices or burst mode & monopolize the channel for the -whole burst. Up to 256 devices can be addressed on one of these cables. These cables are -about one inch in diameter. The maximum unextended length supported by these cables is -125 Meters but this can be extended up to 2km with a fibre optic channel extended -such as a 3044. The maximum burst speed supported is 4.5 megabytes per second however -some really old processors support only transfer rates of 3.0, 2.0 & 1.0 MB/sec. +and control lines on the "Tag" cable. These can operate in byte multiplex mode +for sharing between several slow devices or burst mode and monopolize the +channel for the whole burst. Up to 256 devices can be addressed on one of these +cables. These cables are about one inch in diameter. The maximum unextended +length supported by these cables is 125 Meters but this can be extended up to +2km with a fibre optic channel extended such as a 3044. The maximum burst speed +supported is 4.5 megabytes per second. However, some really old processors +support only transfer rates of 3.0, 2.0 & 1.0 MB/sec. One of these paths can be daisy chained to up to 8 control units. ESCON if fibre optic it is also called FICON -Was introduced by IBM in 1990. Has 2 fibre optic cables & uses either leds or lasers -for communication at a signaling rate of up to 200 megabits/sec. As 10bits are transferred -for every 8 bits info this drops to 160 megabits/sec & to 18.6 Megabytes/sec once -control info & CRC are added. ESCON only operates in burst mode. +Was introduced by IBM in 1990. Has 2 fibre optic cables and uses either leds or +lasers for communication at a signaling rate of up to 200 megabits/sec. As +10bits are transferred for every 8 bits info this drops to 160 megabits/sec +and to 18.6 Megabytes/sec once control info and CRC are added. ESCON only +operates in burst mode. -ESCONs typical max cable length is 3km for the led version & 20km for the laser version -known as XDF ( extended distance facility ). This can be further extended by using an -ESCON director which triples the above mentioned ranges. Unlike Bus & Tag as ESCON is -serial it uses a packet switching architecture the standard Bus & Tag control protocol -is however present within the packets. Up to 256 devices can be attached to each control -unit that uses one of these interfaces. +ESCONs typical max cable length is 3km for the led version and 20km for the +laser version known as XDF (extended distance facility). This can be further +extended by using an ESCON director which triples the above mentioned ranges. +Unlike Bus & Tag as ESCON is serial it uses a packet switching architecture, +the standard Bus & Tag control protocol is however present within the packets. +Up to 256 devices can be attached to each control unit that uses one of these +interfaces. Common 390 Devices include: Network adapters typically OSA2,3172's,2116's & OSA-E gigabit ethernet adapters, -Consoles 3270 & 3215 ( a teletype emulated under linux for a line mode console ). +Consoles 3270 & 3215 (a teletype emulated under linux for a line mode console). DASD's direct access storage devices ( otherwise known as hard disks ). Tape Drives. CTC ( Channel to Channel Adapters ), ESCON or Parallel Cables used as a very high speed serial link -between 2 machines. We use 2 cables under linux to do a bi-directional serial link. +between 2 machines. Debugging IO on s/390 & z/Architecture under VM @@ -1815,9 +1490,9 @@ or the halt subchannels or TR HSCH 7C08-7C09 MSCH's ,STSCH's I think you can guess the rest -Ingo's favourite trick is tracing all the IO's & CCWS & spooling them into the reader of another -VM guest so he can ftp the logfile back to his own machine.I'll do a small bit of this & give you - a look at the output. +A good trick is tracing all the IO's and CCWS and spooling them into the reader +of another VM guest so he can ftp the logfile back to his own machine. I'll do +a small bit of this and give you a look at the output. 1) Spool stdout to VM reader SP PRT TO (another vm guest ) or * for the local vm guest @@ -1933,8 +1608,8 @@ undisplay : undo's display's info breakpoints: shows all current breakpoints -info stack: shows stack back trace ( if this doesn't work too well, I'll show you the -stacktrace by hand below ). +info stack: shows stack back trace (if this doesn't work too well, I'll show +you the stacktrace by hand below). info locals: displays local variables. @@ -1959,7 +1634,8 @@ next: like step except this will not step into subroutines stepi: steps a single machine code instruction. e.g. stepi 100 -nexti: steps a single machine code instruction but will not step into subroutines. +nexti: steps a single machine code instruction but will not step into +subroutines. finish: will run until exit of the current routine @@ -2061,7 +1737,8 @@ e.g. outputs: $1 = 11 -You might now be thinking that the line above didn't work, something extra had to be done. +You might now be thinking that the line above didn't work, something extra had +to be done. (gdb) call fflush(stdout) hello world$2 = 0 As an aside the debugger also calls malloc & free under the hood @@ -2144,26 +1821,17 @@ man gdb or info gdb. core dumps ---------- What a core dump ?, -A core dump is a file generated by the kernel ( if allowed ) which contains the registers, -& all active pages of the program which has crashed. -From this file gdb will allow you to look at the registers & stack trace & memory of the -program as if it just crashed on your system, it is usually called core & created in the -current working directory. -This is very useful in that a customer can mail a core dump to a technical support department -& the technical support department can reconstruct what happened. -Provided they have an identical copy of this program with debugging symbols compiled in & -the source base of this build is available. -In short it is far more useful than something like a crash log could ever hope to be. - -In theory all that is missing to restart a core dumped program is a kernel patch which -will do the following. -1) Make a new kernel task structure -2) Reload all the dumped pages back into the kernel's memory management structures. -3) Do the required clock fixups -4) Get all files & network connections for the process back into an identical state ( really difficult ). -5) A few more difficult things I haven't thought of. - - +A core dump is a file generated by the kernel (if allowed) which contains the +registers and all active pages of the program which has crashed. +From this file gdb will allow you to look at the registers, stack trace and +memory of the program as if it just crashed on your system. It is usually +called core and created in the current working directory. +This is very useful in that a customer can mail a core dump to a technical +support department and the technical support department can reconstruct what +happened. Provided they have an identical copy of this program with debugging +symbols compiled in and the source base of this build is available. +In short it is far more useful than something like a crash log could ever hope +to be. Why have I never seen one ?. Probably because you haven't used the command @@ -2208,7 +1876,7 @@ Breakpoint 2 at 0x4d87a4: file top.c, line 2609. #3 0x5167e6 in readline_internal_char () at readline.c:454 #4 0x5168ee in readline_internal_charloop () at readline.c:507 #5 0x51692c in readline_internal () at readline.c:521 -#6 0x5164fe in readline (prompt=0x7ffff810 "\177ÿøx\177ÿ÷Ø\177ÿøxÀ") +#6 0x5164fe in readline (prompt=0x7ffff810) at readline.c:349 #7 0x4d7a8a in command_line_input (prompt=0x564420 "(gdb) ", repeat=1, annotation_suffix=0x4d6b44 "prompt") at top.c:2091 @@ -2269,8 +1937,8 @@ cat /proc/sys/net/ipv4/ip_forward On my machine now outputs 1 IP forwarding is on. -There is a lot of useful info in here best found by going in & having a look around, -so I'll take you through some entries I consider important. +There is a lot of useful info in here best found by going in and having a look +around, so I'll take you through some entries I consider important. All the processes running on the machine have their own entry defined by /proc/<pid> @@ -2400,7 +2068,8 @@ if the device doesn't say up try /etc/rc.d/init.d/network start ( this starts the network stack & hopefully calls ifconfig tr0 up ). -ifconfig looks at the output of /proc/net/dev & presents it in a more presentable form +ifconfig looks at the output of /proc/net/dev and presents it in a more +presentable form. Now ping the device from a machine in the same subnet. if the RX packets count & TX packets counts don't increment you probably have problems. @@ -2426,34 +2095,6 @@ of the device. See the manpage chandev.8 &type cat /proc/chandev for more info. - -Starting points for debugging scripting languages etc. -====================================================== - -bash/sh - -bash -x <scriptname> -e.g. bash -x /usr/bin/bashbug -displays the following lines as it executes them. -+ MACHINE=i586 -+ OS=linux-gnu -+ CC=gcc -+ CFLAGS= -DPROGRAM='bash' -DHOSTTYPE='i586' -DOSTYPE='linux-gnu' -DMACHTYPE='i586-pc-linux-gnu' -DSHELL -DHAVE_CONFIG_H -I. -I. -I./lib -O2 -pipe -+ RELEASE=2.01 -+ PATCHLEVEL=1 -+ RELSTATUS=release -+ MACHTYPE=i586-pc-linux-gnu - -perl -d <scriptname> runs the perlscript in a fully interactive debugger -<like gdb>. -Type 'h' in the debugger for help. - -for debugging java type -jdb <filename> another fully interactive gdb style debugger. -& type ? in the debugger for help. - - - SysRq ===== This is now supported by linux for s/390 & z/Architecture. diff --git a/Documentation/scheduler/completion.txt b/Documentation/scheduler/completion.txt new file mode 100644 index 000000000000..f77651eca31e --- /dev/null +++ b/Documentation/scheduler/completion.txt @@ -0,0 +1,236 @@ +completions - wait for completion handling +========================================== + +This document was originally written based on 3.18.0 (linux-next) + +Introduction: +------------- + +If you have one or more threads of execution that must wait for some process +to have reached a point or a specific state, completions can provide a race +free solution to this problem. Semantically they are somewhat like a +pthread_barriers and have similar use-cases. + +Completions are a code synchronization mechanism that is preferable to any +misuse of locks. Any time you think of using yield() or some quirky +msleep(1); loop to allow something else to proceed, you probably want to +look into using one of the wait_for_completion*() calls instead. The +advantage of using completions is clear intent of the code but also more +efficient code as both threads can continue until the result is actually +needed. + +Completions are built on top of the generic event infrastructure in Linux, +with the event reduced to a simple flag appropriately called "done" in +struct completion, that tells the waiting threads of execution if they +can continue safely. + +As completions are scheduling related the code is found in +kernel/sched/completion.c - for details on completion design and +implementation see completions-design.txt + + +Usage: +------ + +There are three parts to the using completions, the initialization of the +struct completion, the waiting part through a call to one of the variants of +wait_for_completion() and the signaling side through a call to complete(), +or complete_all(). Further there are some helper functions for checking the +state of completions. + +To use completions one needs to include <linux/completion.h> and +create a variable of type struct completion. The structure used for +handling of completions is: + + struct completion { + unsigned int done; + wait_queue_head_t wait; + }; + +providing the wait queue to place tasks on for waiting and the flag for +indicating the state of affairs. + +Completions should be named to convey the intent of the waiter. A good +example is: + + wait_for_completion(&early_console_added); + + complete(&early_console_added); + +Good naming (as always) helps code readability. + + +Initializing completions: +------------------------- + +Initialization of dynamically allocated completions, often embedded in +other structures, is done with: + + void init_completion(&done); + +Initialization is accomplished by initializing the wait queue and setting +the default state to "not available", that is, "done" is set to 0. + +The re-initialization function, reinit_completion(), simply resets the +done element to "not available", thus again to 0, without touching the +wait queue. Calling init_completion() on the same completions object is +most likely a bug as it re-initializes the queue to an empty queue and +enqueued tasks could get "lost" - use reinit_completion() in that case. + +For static declaration and initialization, macros are available. These are: + + static DECLARE_COMPLETION(setup_done) + +used for static declarations in file scope. Within functions the static +initialization should always use: + + DECLARE_COMPLETION_ONSTACK(setup_done) + +suitable for automatic/local variables on the stack and will make lockdep +happy. Note also that one needs to making *sure* the completion passt to +work threads remains in-scope, and no references remain to on-stack data +when the initiating function returns. + + +Waiting for completions: +------------------------ + +For a thread of execution to wait for some concurrent work to finish, it +calls wait_for_completion() on the initialized completion structure. +A typical usage scenario is: + + structure completion setup_done; + init_completion(&setup_done); + initialze_work(...,&setup_done,...) + + /* run non-dependent code */ /* do setup */ + + wait_for_completion(&seupt_done); complete(setup_done) + +This is not implying any temporal order of wait_for_completion() and the +call to complete() - if the call to complete() happened before the call +to wait_for_completion() then the waiting side simply will continue +immediately as all dependencies are satisfied. + +Note that wait_for_completion() is calling spin_lock_irq/spin_unlock_irq +so it can only be called safely when you know that interrupts are enabled. +Calling it from hard-irq context will result in hard to detect spurious +enabling of interrupts. + +wait_for_completion(): + + void wait_for_completion(struct completion *done): + +The default behavior is to wait without a timeout and mark the task as +uninterruptible. wait_for_completion() and its variants are only safe +in soft-interrupt or process context but not in hard-irq context. +As all variants of wait_for_completion() can (obviously) block for a long +time, you probably don't want to call this with held locks - see also +try_wait_for_completion() below. + + +Variants available: +------------------- + +The below variants all return status and this status should be checked in +most(/all) cases - in cases where the status is deliberately not checked you +probably want to make a note explaining this (e.g. see +arch/arm/kernel/smp.c:__cpu_up()). + +A common problem that occurs is to have unclean assignment of return types, +so care should be taken with assigning return-values to variables of proper +type. Checking for the specific meaning of return values also has been found +to be quite inaccurate e.g. constructs like +if(!wait_for_completion_interruptible_timeout(...)) would execute the same +code path for successful completion and for the interrupted case - which is +probably not what you want. + + int wait_for_completion_interruptible(struct completion *done) + +marking the task TASK_INTERRUPTIBLE. If a signal was received while waiting. +It will return -ERESTARTSYS and 0 otherwise. + + unsigned long wait_for_completion_timeout(struct completion *done, + unsigned long timeout) + +The task is marked as TASK_UNINTERRUPTIBLE and will wait at most timeout +(in jiffies). If timeout occurs it return 0 else the remaining time in +jiffies (but at least 1). Timeouts are preferably passed by msecs_to_jiffies() +or usecs_to_jiffies(). If the returned timeout value is deliberately ignored +a comment should probably explain why (e.g. see drivers/mfd/wm8350-core.c +wm8350_read_auxadc()) + + long wait_for_completion_interruptible_timeout( + struct completion *done, unsigned long timeout) + +passing a timeout in jiffies and marking the task as TASK_INTERRUPTIBLE. If a +signal was received it will return -ERESTARTSYS, 0 if completion timed-out and +the remaining time in jiffies if completion occurred. + +Further variants include _killable which passes TASK_KILLABLE as the +designated tasks state and will return a -ERESTARTSYS if interrupted or +else 0 if completions was achieved as well as a _timeout variant. + + long wait_for_completion_killable(struct completion *done) + long wait_for_completion_killable_timeout(struct completion *done, + unsigned long timeout) + +The _io variants wait_for_completion_io behave the same as the non-_io +variants, except for accounting waiting time as waiting on IO, which has +an impact on how scheduling is calculated. + + void wait_for_completion_io(struct completion *done) + unsigned long wait_for_completion_io_timeout(struct completion *done + unsigned long timeout) + + +Signaling completions: +---------------------- + +A thread of execution that wants to signal that the conditions for +continuation have been achieved calls complete() to signal exactly one +of the waiters that it can continue. + + void complete(struct completion *done) + +or calls complete_all to signal all current and future waiters. + + void complete_all(struct completion *done) + +The signaling will work as expected even if completions are signaled before +a thread starts waiting. This is achieved by the waiter "consuming" +(decrementing) the done element of struct completion. Waiting threads +wakeup order is the same in which they were enqueued (FIFO order). + +If complete() is called multiple times then this will allow for that number +of waiters to continue - each call to complete() will simply increment the +done element. Calling complete_all() multiple times is a bug though. Both +complete() and complete_all() can be called in hard-irq context safely. + +There only can be one thread calling complete() or complete_all() on a +particular struct completions at any time - serialized through the wait +queue spinlock. Any such concurrent calls to complete() or complete_all() +probably are a design bug. + +Signaling completion from hard-irq context is fine as it will appropriately +lock with spin_lock_irqsave/spin_unlock_irqrestore. + + +try_wait_for_completion()/completion_done(): +-------------------------------------------- + +The try_wait_for_completion will not put the thread on the wait queue but +rather returns false if it would need to enqueue (block) the thread, else it +consumes any posted completions and returns true. + + bool try_wait_for_completion(struct completion *done) + +Finally to check state of a completions without changing it in any way is +provided by completion_done() returning false if there are any posted +completion that was not yet consumed by waiters implying that there are +waiters and true otherwise; + + bool completion_done(struct completion *done) + +Both try_wait_for_completion() and completion_done() are safe to be called in +hard-irq context. diff --git a/Documentation/scsi/libsas.txt b/Documentation/scsi/libsas.txt index 3cc9c7843e15..8cac6492aade 100644 --- a/Documentation/scsi/libsas.txt +++ b/Documentation/scsi/libsas.txt @@ -226,9 +226,6 @@ static int register_sas_ha(struct my_sas_ha *my_ha) my_ha->sas_ha.lldd_dev_found = my_dev_found; my_ha->sas_ha.lldd_dev_gone = my_dev_gone; - my_ha->sas_ha.lldd_max_execute_num = lldd_max_execute_num; (1) - - my_ha->sas_ha.lldd_queue_size = ha_can_queue; my_ha->sas_ha.lldd_execute_task = my_execute_task; my_ha->sas_ha.lldd_abort_task = my_abort_task; @@ -247,28 +244,6 @@ static int register_sas_ha(struct my_sas_ha *my_ha) return sas_register_ha(&my_ha->sas_ha); } -(1) This is normally a LLDD parameter, something of the -lines of a task collector. What it tells the SAS Layer is -whether the SAS layer should run in Direct Mode (default: -value 0 or 1) or Task Collector Mode (value greater than 1). - -In Direct Mode, the SAS Layer calls Execute Task as soon as -it has a command to send to the SDS, _and_ this is a single -command, i.e. not linked. - -Some hardware (e.g. aic94xx) has the capability to DMA more -than one task at a time (interrupt) from host memory. Task -Collector Mode is an optional feature for HAs which support -this in their hardware. (Again, it is completely optional -even if your hardware supports it.) - -In Task Collector Mode, the SAS Layer would do _natural_ -coalescing of tasks and at the appropriate moment it would -call your driver to DMA more than one task in a single HA -interrupt. DMBS may want to use this by insmod/modprobe -setting the lldd_max_execute_num to something greater than -1. - (2) SAS 1.1 does not define I_T Nexus Reset TMF. Events @@ -325,71 +300,22 @@ PHYE_SPINUP_HOLD -- SATA is present, COMWAKE not sent. The Execute Command SCSI RPC: - int (*lldd_execute_task)(struct sas_task *, int num, - unsigned long gfp_flags); + int (*lldd_execute_task)(struct sas_task *, gfp_t gfp_flags); -Used to queue a task to the SAS LLDD. @task is the tasks to -be executed. @num should be the number of tasks being -queued at this function call (they are linked listed via -task::list), @gfp_mask should be the gfp_mask defining the -context of the caller. +Used to queue a task to the SAS LLDD. @task is the task to be executed. +@gfp_mask is the gfp_mask defining the context of the caller. This function should implement the Execute Command SCSI RPC, -or if you're sending a SCSI Task as linked commands, you -should also use this function. -That is, when lldd_execute_task() is called, the command(s) +That is, when lldd_execute_task() is called, the command go out on the transport *immediately*. There is *no* queuing of any sort and at any level in a SAS LLDD. -The use of task::list is two-fold, one for linked commands, -the other discussed below. - -It is possible to queue up more than one task at a time, by -initializing the list element of struct sas_task, and -passing the number of tasks enlisted in this manner in num. - Returns: -SAS_QUEUE_FULL, -ENOMEM, nothing was queued; 0, the task(s) were queued. -If you want to pass num > 1, then either -A) you're the only caller of this function and keep track - of what you've queued to the LLDD, or -B) you know what you're doing and have a strategy of - retrying. - -As opposed to queuing one task at a time (function call), -batch queuing of tasks, by having num > 1, greatly -simplifies LLDD code, sequencer code, and _hardware design_, -and has some performance advantages in certain situations -(DBMS). - -The LLDD advertises if it can take more than one command at -a time at lldd_execute_task(), by setting the -lldd_max_execute_num parameter (controlled by "collector" -module parameter in aic94xx SAS LLDD). - -You should leave this to the default 1, unless you know what -you're doing. - -This is a function of the LLDD, to which the SAS layer can -cater to. - -int lldd_queue_size - The host adapter's queue size. This is the maximum -number of commands the lldd can have pending to domain -devices on behalf of all upper layers submitting through -lldd_execute_task(). - -You really want to set this to something (much) larger than -1. - -This _really_ has absolutely nothing to do with queuing. -There is no queuing in SAS LLDDs. - struct sas_task { dev -- the device this task is destined to - list -- must be initialized (INIT_LIST_HEAD) task_proto -- _one_ of enum sas_proto scatter -- pointer to scatter gather list array num_scatter -- number of elements in scatter diff --git a/Documentation/scsi/scsi_eh.txt b/Documentation/scsi/scsi_eh.txt index a0c85110a07e..8638f61c8c9d 100644 --- a/Documentation/scsi/scsi_eh.txt +++ b/Documentation/scsi/scsi_eh.txt @@ -172,7 +172,7 @@ ways. - eh_strategy_handler() callback This is one big callback which should perform whole error - handling. As such, it should do all choirs SCSI midlayer + handling. As such, it should do all chores the SCSI midlayer performs during recovery. This will be discussed in [2-2]. Once recovery is complete, SCSI EH resumes normal operation by @@ -428,7 +428,7 @@ scmd->allowed. scsi_unjam_host() and it is responsible for whole recovery process. On completion, the handler should have made lower layers forget about all failed scmds and either ready for new commands or offline. Also, -it should perform SCSI EH maintenance choirs to maintain integrity of +it should perform SCSI EH maintenance chores to maintain integrity of SCSI midlayer. IOW, of the steps described in [2-1-2], all steps except for #1 must be implemented by eh_strategy_handler(). diff --git a/Documentation/scsi/scsi_mid_low_api.txt b/Documentation/scsi/scsi_mid_low_api.txt index d6a9bdeee7f2..731bc4f4c5e6 100644 --- a/Documentation/scsi/scsi_mid_low_api.txt +++ b/Documentation/scsi/scsi_mid_low_api.txt @@ -149,7 +149,7 @@ scsi_add_host() ----> scsi_scan_host() -------+ | slave_alloc() - slave_configure() --> scsi_adjust_queue_depth() + slave_configure() --> scsi_change_queue_depth() | slave_alloc() slave_configure() @@ -159,7 +159,7 @@ scsi_scan_host() -------+ ------------------------------------------------------------ If the LLD wants to adjust the default queue settings, it can invoke -scsi_adjust_queue_depth() in its slave_configure() routine. +scsi_change_queue_depth() in its slave_configure() routine. *** For scsi devices that the mid level tries to scan but do not respond, a slave_alloc(), slave_destroy() pair is called. @@ -203,7 +203,7 @@ LLD mid level LLD scsi_add_device() ------+ | slave_alloc() - slave_configure() [--> scsi_adjust_queue_depth()] + slave_configure() [--> scsi_change_queue_depth()] ------------------------------------------------------------ In a similar fashion, an LLD may become aware that a SCSI device has been @@ -261,7 +261,7 @@ init_this_scsi_driver() ----+ | scsi_register() | slave_alloc() - slave_configure() --> scsi_adjust_queue_depth() + slave_configure() --> scsi_change_queue_depth() slave_alloc() *** slave_destroy() *** | @@ -271,9 +271,9 @@ init_this_scsi_driver() ----+ slave_destroy() *** ------------------------------------------------------------ -The mid level invokes scsi_adjust_queue_depth() with tagged queuing off and -"cmd_per_lun" for that host as the queue length. These settings can be -overridden by a slave_configure() supplied by the LLD. +The mid level invokes scsi_change_queue_depth() with "cmd_per_lun" for that +host as the queue length. These settings can be overridden by a +slave_configure() supplied by the LLD. *** For scsi devices that the mid level tries to scan but do not respond, a slave_alloc(), slave_destroy() pair is called. @@ -366,13 +366,11 @@ is initialized. The functions below are listed alphabetically and their names all start with "scsi_". Summary: - scsi_activate_tcq - turn on tag command queueing scsi_add_device - creates new scsi device (lu) instance scsi_add_host - perform sysfs registration and set up transport class - scsi_adjust_queue_depth - change the queue depth on a SCSI device + scsi_change_queue_depth - change the queue depth on a SCSI device scsi_bios_ptable - return copy of block device's partition table scsi_block_requests - prevent further commands being queued to given host - scsi_deactivate_tcq - turn off tag command queueing scsi_host_alloc - return a new scsi_host instance whose refcount==1 scsi_host_get - increments Scsi_Host instance's refcount scsi_host_put - decrements Scsi_Host instance's refcount (free if 0) @@ -390,24 +388,6 @@ Summary: Details: /** - * scsi_activate_tcq - turn on tag command queueing ("ordered" task attribute) - * @sdev: device to turn on TCQ for - * @depth: queue depth - * - * Returns nothing - * - * Might block: no - * - * Notes: Eventually, it is hoped depth would be the maximum depth - * the device could cope with and the real queue depth - * would be adjustable from 0 to depth. - * - * Defined (inline) in: include/scsi/scsi_tcq.h - **/ -void scsi_activate_tcq(struct scsi_device *sdev, int depth) - - -/** * scsi_add_device - creates new scsi device (lu) instance * @shost: pointer to scsi host instance * @channel: channel number (rarely other than 0) @@ -456,11 +436,8 @@ int scsi_add_host(struct Scsi_Host *shost, struct device * dev) /** - * scsi_adjust_queue_depth - allow LLD to change queue depth on a SCSI device + * scsi_change_queue_depth - allow LLD to change queue depth on a SCSI device * @sdev: pointer to SCSI device to change queue depth on - * @tagged: 0 - no tagged queuing - * MSG_SIMPLE_TAG - simple tagged queuing - * MSG_ORDERED_TAG - ordered tagged queuing * @tags Number of tags allowed if tagged queuing enabled, * or number of commands the LLD can queue up * in non-tagged mode (as per cmd_per_lun). @@ -471,15 +448,12 @@ int scsi_add_host(struct Scsi_Host *shost, struct device * dev) * * Notes: Can be invoked any time on a SCSI device controlled by this * LLD. [Specifically during and after slave_configure() and prior to - * slave_destroy().] Can safely be invoked from interrupt code. Actual - * queue depth change may be delayed until the next command is being - * processed. See also scsi_activate_tcq() and scsi_deactivate_tcq(). + * slave_destroy().] Can safely be invoked from interrupt code. * * Defined in: drivers/scsi/scsi.c [see source code for more notes] * **/ -void scsi_adjust_queue_depth(struct scsi_device * sdev, int tagged, - int tags) +int scsi_change_queue_depth(struct scsi_device *sdev, int tags) /** @@ -515,20 +489,6 @@ void scsi_block_requests(struct Scsi_Host * shost) /** - * scsi_deactivate_tcq - turn off tag command queueing - * @sdev: device to turn off TCQ for - * @depth: queue depth (stored in sdev) - * - * Returns nothing - * - * Might block: no - * - * Defined (inline) in: include/scsi/scsi_tcq.h - **/ -void scsi_deactivate_tcq(struct scsi_device *sdev, int depth) - - -/** * scsi_host_alloc - create a scsi host adapter instance and perform basic * initialization. * @sht: pointer to scsi host template @@ -1254,7 +1214,7 @@ of interest: for disk firmware uploads. cmd_per_lun - maximum number of commands that can be queued on devices controlled by the host. Overridden by LLD calls to - scsi_adjust_queue_depth(). + scsi_change_queue_depth(). unchecked_isa_dma - 1=>only use bottom 16 MB of ram (ISA DMA addressing restriction), 0=>can use full 32 bit (or better) DMA address space @@ -1294,7 +1254,7 @@ struct scsi_cmnd Instances of this structure convey SCSI commands to the LLD and responses back to the mid level. The SCSI mid level will ensure that no more SCSI commands become queued against the LLD than are indicated by -scsi_adjust_queue_depth() (or struct Scsi_Host::cmd_per_lun). There will +scsi_change_queue_depth() (or struct Scsi_Host::cmd_per_lun). There will be at least one instance of struct scsi_cmnd available for each SCSI device. Members of interest: cmnd - array containing SCSI command diff --git a/Documentation/scsi/st.txt b/Documentation/scsi/st.txt index f346abbdd6ff..0d5bdb153d3b 100644 --- a/Documentation/scsi/st.txt +++ b/Documentation/scsi/st.txt @@ -506,9 +506,11 @@ user does not request data that far.) DEBUGGING HINTS -To enable debugging messages, edit st.c and #define DEBUG 1. As seen -above, debugging can be switched off with an ioctl if debugging is -compiled into the driver. The debugging output is not voluminous. +Debugging code is now compiled in by default but debugging is turned off +with the kernel module parameter debug_flag defaulting to 0. Debugging +can still be switched on and off with an ioctl. To enable debug at +module load time add debug_flag=1 to the module load options, the +debugging output is not voluminous. If the tape seems to hang, I would be very interested to hear where the driver is waiting. With the command 'ps -l' you can see the state diff --git a/Documentation/scsi/wd719x.txt b/Documentation/scsi/wd719x.txt new file mode 100644 index 000000000000..0816b0220238 --- /dev/null +++ b/Documentation/scsi/wd719x.txt @@ -0,0 +1,21 @@ +Driver for Western Digital WD7193, WD7197 and WD7296 SCSI cards +--------------------------------------------------------------- + +The card requires firmware that can be cut out of the Windows NT driver that +can be downloaded from WD at: +http://support.wdc.com/product/download.asp?groupid=801&sid=27&lang=en + +There is no license anywhere in the file or on the page - so the firmware +probably cannot be added to linux-firmware. + +This script downloads and extracts the firmware, creating wd719x-risc.bin and +d719x-wcs.bin files. Put them in /lib/firmware/. + +#!/bin/sh +wget http://support.wdc.com/download/archive/pciscsi.exe +lha xi pciscsi.exe pci-scsi.exe +lha xi pci-scsi.exe nt/wd7296a.sys +rm pci-scsi.exe +dd if=wd7296a.sys of=wd719x-risc.bin bs=1 skip=5760 count=14336 +dd if=wd7296a.sys of=wd719x-wcs.bin bs=1 skip=20096 count=514 +rm wd7296a.sys diff --git a/Documentation/security/IMA-templates.txt b/Documentation/security/IMA-templates.txt index a4e102dddfea..839b5dad9226 100644 --- a/Documentation/security/IMA-templates.txt +++ b/Documentation/security/IMA-templates.txt @@ -27,25 +27,22 @@ Managing templates with these structures is very simple. To support a new data type, developers define the field identifier and implement two functions, init() and show(), respectively to generate and display measurement entries. Defining a new template descriptor requires -specifying the template format, a string of field identifiers separated -by the '|' character. While in the current implementation it is possible -to define new template descriptors only by adding their definition in the -template specific code (ima_template.c), in a future version it will be -possible to register a new template on a running kernel by supplying to IMA -the desired format string. In this version, IMA initializes at boot time -all defined template descriptors by translating the format into an array -of template fields structures taken from the set of the supported ones. +specifying the template format (a string of field identifiers separated +by the '|' character) through the 'ima_template_fmt' kernel command line +parameter. At boot time, IMA initializes the chosen template descriptor +by translating the format into an array of template fields structures taken +from the set of the supported ones. After the initialization step, IMA will call ima_alloc_init_template() (new function defined within the patches for the new template management mechanism) to generate a new measurement entry by using the template descriptor chosen through the kernel configuration or through the newly -introduced 'ima_template=' kernel command line parameter. It is during this -phase that the advantages of the new architecture are clearly shown: -the latter function will not contain specific code to handle a given template -but, instead, it simply calls the init() method of the template fields -associated to the chosen template descriptor and store the result (pointer -to allocated data and data length) in the measurement entry structure. +introduced 'ima_template' and 'ima_template_fmt' kernel command line parameters. +It is during this phase that the advantages of the new architecture are +clearly shown: the latter function will not contain specific code to handle +a given template but, instead, it simply calls the init() method of the template +fields associated to the chosen template descriptor and store the result +(pointer to allocated data and data length) in the measurement entry structure. The same mechanism is employed to display measurements entries. The functions ima[_ascii]_measurements_show() retrieve, for each entry, @@ -86,4 +83,6 @@ currently the following methods are supported: - select a template descriptor among those supported in the kernel configuration ('ima-ng' is the default choice); - specify a template descriptor name from the kernel command line through - the 'ima_template=' parameter. + the 'ima_template=' parameter; + - register a new template descriptor with custom format through the kernel + command line parameter 'ima_template_fmt='. diff --git a/Documentation/security/keys.txt b/Documentation/security/keys.txt index 821c936e1a63..c9e7f4f223a5 100644 --- a/Documentation/security/keys.txt +++ b/Documentation/security/keys.txt @@ -323,8 +323,6 @@ about the status of the key service: U Under construction by callback to userspace N Negative key - This file must be enabled at kernel configuration time as it allows anyone - to list the keys database. (*) /proc/key-users diff --git a/Documentation/serial/driver b/Documentation/serial/driver index ba64e4b892e9..c415b0ef4493 100644 --- a/Documentation/serial/driver +++ b/Documentation/serial/driver @@ -59,7 +59,9 @@ The core driver uses the info->tmpbuf_sem lock to prevent multi-threaded access to the info->tmpbuf bouncebuffer used for port writes. The port_sem semaphore is used to protect against ports being added/ -removed or reconfigured at inappropriate times. +removed or reconfigured at inappropriate times. Since v2.6.27, this +semaphore has been the 'mutex' member of the tty_port struct, and +commonly referred to as the port mutex (or port->mutex). uart_ops @@ -248,7 +250,7 @@ hardware. Other flags may be used (eg, xon/xoff characters) if your hardware supports hardware "soft" flow control. - Locking: none. + Locking: caller holds port->mutex Interrupts: caller dependent. This call must not sleep diff --git a/Documentation/sound/alsa/ControlNames.txt b/Documentation/sound/alsa/ControlNames.txt index fea65bb6269e..79a6127863ca 100644 --- a/Documentation/sound/alsa/ControlNames.txt +++ b/Documentation/sound/alsa/ControlNames.txt @@ -1,6 +1,6 @@ This document describes standard names of mixer controls. -Syntax: SOURCE [DIRECTION] FUNCTION +Syntax: [LOCATION] SOURCE [CHANNEL] [DIRECTION] FUNCTION DIRECTION: <nothing> (both directions) @@ -14,12 +14,29 @@ FUNCTION: Volume Route (route control, hardware specific) +CHANNEL: + <nothing> (channel independent, or applies to all channels) + Front + Surround (rear left/right in 4.0/5.1 surround) + CLFE + Center + LFE + Side (side left/right for 7.1 surround) + +LOCATION: (physical location of source) + Front + Rear + Dock (docking station) + Internal + SOURCE: Master Master Mono Hardware Master Speaker (internal speaker) + Bass Speaker (internal LFE speaker) Headphone + Line Out Beep (beep generator) Phone Phone Input @@ -27,14 +44,14 @@ SOURCE: Synth FM Mic - Line + Headset Mic (mic part of combined headset jack - 4-pin headphone + mic) + Headphone Mic (mic part of either/or - 3-pin headphone or mic) + Line (input only, use "Line Out" for output) CD Video Zoom Video Aux PCM - PCM Front - PCM Rear PCM Pan Loopback Analog Loopback (D/A -> A/D loopback) @@ -47,8 +64,13 @@ SOURCE: Music I2S IEC958 + HDMI + SPDIF (output only) + SPDIF In + Digital In + HDMI/DP (either HDMI or DisplayPort) -Exceptions: +Exceptions (deprecated): [Digital] Capture Source [Digital] Capture Switch (aka input gain switch) [Digital] Capture Volume (aka input gain volume) diff --git a/Documentation/sound/alsa/HD-Audio-Models.txt b/Documentation/sound/alsa/HD-Audio-Models.txt index a5e754714344..5a3163cac6c3 100644 --- a/Documentation/sound/alsa/HD-Audio-Models.txt +++ b/Documentation/sound/alsa/HD-Audio-Models.txt @@ -113,14 +113,10 @@ AD1984 AD1986A ======= - 6stack 6-jack, separate surrounds (default) 3stack 3-stack, shared surrounds laptop 2-channel only (FSC V2060, Samsung M50) - laptop-eapd 2-channel with EAPD (ASUS A6J) - laptop-automute 2-channel with EAPD and HP-automute (Lenovo N100) - ultra 2-channel with EAPD (Samsung Ultra tablet PC) - samsung 2-channel with EAPD (Samsung R65) - samsung-p50 2-channel with HP-automute (Samsung P50) + laptop-imic 2-channel with built-in mic + eapd Turn on EAPD constantly AD1988/AD1988B/AD1989A/AD1989B ============================== diff --git a/Documentation/sound/alsa/Procfile.txt b/Documentation/sound/alsa/Procfile.txt index 7fcd1ad96fcc..7f8a0d325905 100644 --- a/Documentation/sound/alsa/Procfile.txt +++ b/Documentation/sound/alsa/Procfile.txt @@ -101,10 +101,6 @@ card*/pcm*/xrun_debug bit 0 = Enable XRUN/jiffies debug messages bit 1 = Show stack trace at XRUN / jiffies check bit 2 = Enable additional jiffies check - bit 3 = Log hwptr update at each period interrupt - bit 4 = Log hwptr update at each snd_pcm_update_hw_ptr() - bit 5 = Show last 10 positions on error - bit 6 = Do above only once When the bit 0 is set, the driver will show the messages to kernel log when an xrun is detected. The debug message is @@ -121,15 +117,6 @@ card*/pcm*/xrun_debug buggy) hardware that doesn't give smooth pointer updates. This feature is enabled via the bit 2. - Bits 3 and 4 are for logging the hwptr records. Note that - these will give flood of kernel messages. - - When bit 5 is set, the driver logs the last 10 xrun errors and - the proc file shows each jiffies, position, period_size, - buffer_size, old_hw_ptr, and hw_ptr_base values. - - When bit 6 is set, the full xrun log is shown only once. - card*/pcm*/sub*/info The general information of this PCM sub-stream. @@ -146,6 +133,10 @@ card*/pcm*/sub*/sw_params card*/pcm*/sub*/prealloc The buffer pre-allocation information. +card*/pcm*/sub*/xrun_injection + Triggers an XRUN to the running stream when any value is + written to this proc file. Used for fault injection. + This entry is write-only. AC97 Codec Information ---------------------- diff --git a/Documentation/stable_kernel_rules.txt b/Documentation/stable_kernel_rules.txt index aee73e78c7d4..02f8331edb8b 100644 --- a/Documentation/stable_kernel_rules.txt +++ b/Documentation/stable_kernel_rules.txt @@ -32,18 +32,42 @@ Procedure for submitting patches to the -stable tree: - If the patch covers files in net/ or drivers/net please follow netdev stable submission guidelines as described in Documentation/networking/netdev-FAQ.txt - - Send the patch, after verifying that it follows the above rules, to - stable@vger.kernel.org. You must note the upstream commit ID in the - changelog of your submission, as well as the kernel version you wish - it to be applied to. - - To have the patch automatically included in the stable tree, add the tag + - Security patches should not be handled (solely) by the -stable review + process but should follow the procedures in Documentation/SecurityBugs. + +For all other submissions, choose one of the following procedures: + + --- Option 1 --- + + To have the patch automatically included in the stable tree, add the tag Cc: stable@vger.kernel.org in the sign-off area. Once the patch is merged it will be applied to the stable tree without anything else needing to be done by the author or subsystem maintainer. - - If the patch requires other patches as prerequisites which can be - cherry-picked, then this can be specified in the following format in - the sign-off area: + + --- Option 2 --- + + After the patch has been merged to Linus' tree, send an email to + stable@vger.kernel.org containing the subject of the patch, the commit ID, + why you think it should be applied, and what kernel version you wish it to + be applied to. + + --- Option 3 --- + + Send the patch, after verifying that it follows the above rules, to + stable@vger.kernel.org. You must note the upstream commit ID in the + changelog of your submission, as well as the kernel version you wish + it to be applied to. + +Option 1 is probably the easiest and most common. Options 2 and 3 are more +useful if the patch isn't deemed worthy at the time it is applied to a public +git tree (for instance, because it deserves more regression testing first). +Option 3 is especially useful if the patch needs some special handling to apply +to an older kernel (e.g., if API's have changed in the meantime). + +Additionally, some patches submitted via Option 1 may have additional patch +prerequisites which can be cherry-picked. This can be specified in the following +format in the sign-off area: Cc: <stable@vger.kernel.org> # 3.3.x: a1f84a3: sched: Check for idle Cc: <stable@vger.kernel.org> # 3.3.x: 1b9508f: sched: Rate-limit newidle @@ -57,13 +81,13 @@ Procedure for submitting patches to the -stable tree: git cherry-pick fd21073 git cherry-pick <this commit> +Following the submission: + - The sender will receive an ACK when the patch has been accepted into the queue, or a NAK if the patch is rejected. This response might take a few days, according to the developer's schedules. - If accepted, the patch will be added to the -stable queue, for review by other developers and by the relevant subsystem maintainer. - - Security patches should not be sent to this alias, but instead to the - documented security@kernel.org address. Review cycle: diff --git a/Documentation/sysctl/kernel.txt b/Documentation/sysctl/kernel.txt index 57baff5bdb80..83ab25660fc9 100644 --- a/Documentation/sysctl/kernel.txt +++ b/Documentation/sysctl/kernel.txt @@ -54,8 +54,9 @@ show up in /proc/sys/kernel: - overflowuid - panic - panic_on_oops -- panic_on_unrecovered_nmi - panic_on_stackoverflow +- panic_on_unrecovered_nmi +- panic_on_warn - pid_max - powersave-nap [ PPC only ] - printk @@ -115,10 +116,12 @@ set during run time. auto_msgmni: -Enables/Disables automatic recomputing of msgmni upon memory add/remove -or upon ipc namespace creation/removal (see the msgmni description -above). Echoing "1" into this file enables msgmni automatic recomputing. -Echoing "0" turns it off. auto_msgmni default value is 1. +This variable has no effect and may be removed in future kernel +releases. Reading it always returns 0. +Up to Linux 3.17, it enabled/disabled automatic recomputing of msgmni +upon memory add/remove or upon ipc namespace creation/removal. +Echoing "1" into this file enabled msgmni automatic recomputing. +Echoing "0" turned it off. auto_msgmni default value was 1. ============================================================== @@ -527,19 +530,6 @@ the recommended setting is 60. ============================================================== -panic_on_unrecovered_nmi: - -The default Linux behaviour on an NMI of either memory or unknown is -to continue operation. For many environments such as scientific -computing it is preferable that the box is taken out and the error -dealt with than an uncorrected parity/ECC error get propagated. - -A small number of systems do generate NMI's for bizarre random reasons -such as power management so the default is off. That sysctl works like -the existing panic controls already in that directory. - -============================================================== - panic_on_oops: Controls the kernel's behaviour when an oops or BUG is encountered. @@ -563,6 +553,30 @@ This file shows up if CONFIG_DEBUG_STACKOVERFLOW is enabled. ============================================================== +panic_on_unrecovered_nmi: + +The default Linux behaviour on an NMI of either memory or unknown is +to continue operation. For many environments such as scientific +computing it is preferable that the box is taken out and the error +dealt with than an uncorrected parity/ECC error get propagated. + +A small number of systems do generate NMI's for bizarre random reasons +such as power management so the default is off. That sysctl works like +the existing panic controls already in that directory. + +============================================================== + +panic_on_warn: + +Calls panic() in the WARN() path when set to 1. This is useful to avoid +a kernel rebuild when attempting to kdump at the location of a WARN(). + +0: only WARN(), default behaviour. + +1: call panic() after printing out WARN() location. + +============================================================== + perf_cpu_time_max_percent: Hints to the kernel how much CPU time it should be allowed to @@ -829,6 +843,7 @@ can be ORed together: 8192 - An unsigned module has been loaded in a kernel supporting module signature. 16384 - A soft lockup has previously occurred on the system. +32768 - The kernel has been live patched. ============================================================== diff --git a/Documentation/sysctl/net.txt b/Documentation/sysctl/net.txt index 04892b821157..6294b5186ae5 100644 --- a/Documentation/sysctl/net.txt +++ b/Documentation/sysctl/net.txt @@ -97,6 +97,14 @@ rmem_max The maximum receive socket buffer size in bytes. +tstamp_allow_data +----------------- +Allow processes to receive tx timestamps looped together with the original +packet contents. If disabled, transmit timestamp requests from unprivileged +processes are dropped unless socket option SOF_TIMESTAMPING_OPT_TSONLY is set. +Default: 1 (on) + + wmem_default ------------ @@ -120,10 +128,14 @@ seconds. warnings -------- -This controls console messages from the networking stack that can occur because -of problems on the network like duplicate address or bad checksums. Normally, -this should be enabled, but if the problem persists the messages can be -disabled. +This sysctl is now unused. + +This was used to control console messages from the networking stack that +occur because of problems on the network like duplicate address or bad +checksums. + +These messages are now emitted at KERN_DEBUG and can generally be enabled +and controlled by the dynamic_debug facility. netdev_budget ------------- @@ -138,6 +150,28 @@ netdev_max_backlog Maximum number of packets, queued on the INPUT side, when the interface receives packets faster than kernel can process them. +netdev_rss_key +-------------- + +RSS (Receive Side Scaling) enabled drivers use a 40 bytes host key that is +randomly generated. +Some user space might need to gather its content even if drivers do not +provide ethtool -x support yet. + +myhost:~# cat /proc/sys/net/core/netdev_rss_key +84:50:f4:00:a8:15:d1:a7:e9:7f:1d:60:35:c7:47:25:42:97:74:ca:56:bb:b6:a1:d8: ... (52 bytes total) + +File contains nul bytes if no driver ever called netdev_rss_key_fill() function. +Note: +/proc/sys/net/core/netdev_rss_key contains 52 bytes of key, +but most drivers only use 40 bytes of it. + +myhost:~# ethtool -x eth0 +RX flow hash indirection table for eth0 with 8 RX ring(s): + 0: 0 1 2 3 4 5 6 7 +RSS hash key: +84:50:f4:00:a8:15:d1:a7:e9:7f:1d:60:35:c7:47:25:42:97:74:ca:56:bb:b6:a1:d8:43:e3:c9:0c:fd:17:55:c2:3a:4d:69:ed:f1:42:89 + netdev_tstamp_prequeue ---------------------- diff --git a/Documentation/sysctl/vm.txt b/Documentation/sysctl/vm.txt index 4415aa915681..902b4574acfb 100644 --- a/Documentation/sysctl/vm.txt +++ b/Documentation/sysctl/vm.txt @@ -555,12 +555,12 @@ this is causing problems for your system/application. oom_dump_tasks -Enables a system-wide task dump (excluding kernel threads) to be -produced when the kernel performs an OOM-killing and includes such -information as pid, uid, tgid, vm size, rss, nr_ptes, swapents, -oom_score_adj score, and name. This is helpful to determine why the -OOM killer was invoked, to identify the rogue task that caused it, -and to determine why the OOM killer chose the task it did to kill. +Enables a system-wide task dump (excluding kernel threads) to be produced +when the kernel performs an OOM-killing and includes such information as +pid, uid, tgid, vm size, rss, nr_ptes, nr_pmds, swapents, oom_score_adj +score, and name. This is helpful to determine why the OOM killer was +invoked, to identify the rogue task that caused it, and to determine why +the OOM killer chose the task it did to kill. If this is set to zero, this information is suppressed. On very large systems with thousands of tasks it may not be feasible to dump @@ -728,7 +728,7 @@ The default value is 60. - user_reserve_kbytes -When overcommit_memory is set to 2, "never overommit" mode, reserve +When overcommit_memory is set to 2, "never overcommit" mode, reserve min(3% of current process size, user_reserve_kbytes) of free memory. This is intended to prevent a user from starting a single memory hogging process, such that they cannot recover (kill the hog). diff --git a/Documentation/target/tcm_mod_builder.py b/Documentation/target/tcm_mod_builder.py index 230ce71f4d75..2b47704f75cb 100755 --- a/Documentation/target/tcm_mod_builder.py +++ b/Documentation/target/tcm_mod_builder.py @@ -389,9 +389,6 @@ def tcm_mod_build_configfs(proto_ident, fabric_mod_dir_var, fabric_mod_name): buf += " .release_cmd = " + fabric_mod_name + "_release_cmd,\n" buf += " .shutdown_session = " + fabric_mod_name + "_shutdown_session,\n" buf += " .close_session = " + fabric_mod_name + "_close_session,\n" - buf += " .stop_session = " + fabric_mod_name + "_stop_session,\n" - buf += " .fall_back_to_erl0 = " + fabric_mod_name + "_reset_nexus,\n" - buf += " .sess_logged_in = " + fabric_mod_name + "_sess_logged_in,\n" buf += " .sess_get_index = " + fabric_mod_name + "_sess_get_index,\n" buf += " .sess_get_initiator_sid = NULL,\n" buf += " .write_pending = " + fabric_mod_name + "_write_pending,\n" @@ -402,7 +399,7 @@ def tcm_mod_build_configfs(proto_ident, fabric_mod_dir_var, fabric_mod_name): buf += " .queue_data_in = " + fabric_mod_name + "_queue_data_in,\n" buf += " .queue_status = " + fabric_mod_name + "_queue_status,\n" buf += " .queue_tm_rsp = " + fabric_mod_name + "_queue_tm_rsp,\n" - buf += " .is_state_remove = " + fabric_mod_name + "_is_state_remove,\n" + buf += " .aborted_task = " + fabric_mod_name + "_aborted_task,\n" buf += " /*\n" buf += " * Setup function pointers for generic logic in target_core_fabric_configfs.c\n" buf += " */\n" @@ -428,7 +425,7 @@ def tcm_mod_build_configfs(proto_ident, fabric_mod_dir_var, fabric_mod_name): buf += " /*\n" buf += " * Register the top level struct config_item_type with TCM core\n" buf += " */\n" - buf += " fabric = target_fabric_configfs_init(THIS_MODULE, \"" + fabric_mod_name[4:] + "\");\n" + buf += " fabric = target_fabric_configfs_init(THIS_MODULE, \"" + fabric_mod_name + "\");\n" buf += " if (IS_ERR(fabric)) {\n" buf += " printk(KERN_ERR \"target_fabric_configfs_init() failed\\n\");\n" buf += " return PTR_ERR(fabric);\n" @@ -595,7 +592,7 @@ def tcm_mod_dump_fabric_ops(proto_ident, fabric_mod_dir_var, fabric_mod_name): if re.search('get_fabric_name', fo): buf += "char *" + fabric_mod_name + "_get_fabric_name(void)\n" buf += "{\n" - buf += " return \"" + fabric_mod_name[4:] + "\";\n" + buf += " return \"" + fabric_mod_name + "\";\n" buf += "}\n\n" bufi += "char *" + fabric_mod_name + "_get_fabric_name(void);\n" continue @@ -820,27 +817,6 @@ def tcm_mod_dump_fabric_ops(proto_ident, fabric_mod_dir_var, fabric_mod_name): buf += "}\n\n" bufi += "void " + fabric_mod_name + "_close_session(struct se_session *);\n" - if re.search('stop_session\)\(', fo): - buf += "void " + fabric_mod_name + "_stop_session(struct se_session *se_sess, int sess_sleep , int conn_sleep)\n" - buf += "{\n" - buf += " return;\n" - buf += "}\n\n" - bufi += "void " + fabric_mod_name + "_stop_session(struct se_session *, int, int);\n" - - if re.search('fall_back_to_erl0\)\(', fo): - buf += "void " + fabric_mod_name + "_reset_nexus(struct se_session *se_sess)\n" - buf += "{\n" - buf += " return;\n" - buf += "}\n\n" - bufi += "void " + fabric_mod_name + "_reset_nexus(struct se_session *);\n" - - if re.search('sess_logged_in\)\(', fo): - buf += "int " + fabric_mod_name + "_sess_logged_in(struct se_session *se_sess)\n" - buf += "{\n" - buf += " return 0;\n" - buf += "}\n\n" - bufi += "int " + fabric_mod_name + "_sess_logged_in(struct se_session *);\n" - if re.search('sess_get_index\)\(', fo): buf += "u32 " + fabric_mod_name + "_sess_get_index(struct se_session *se_sess)\n" buf += "{\n" @@ -898,19 +874,18 @@ def tcm_mod_dump_fabric_ops(proto_ident, fabric_mod_dir_var, fabric_mod_name): bufi += "int " + fabric_mod_name + "_queue_status(struct se_cmd *);\n" if re.search('queue_tm_rsp\)\(', fo): - buf += "int " + fabric_mod_name + "_queue_tm_rsp(struct se_cmd *se_cmd)\n" + buf += "void " + fabric_mod_name + "_queue_tm_rsp(struct se_cmd *se_cmd)\n" buf += "{\n" - buf += " return 0;\n" + buf += " return;\n" buf += "}\n\n" - bufi += "int " + fabric_mod_name + "_queue_tm_rsp(struct se_cmd *);\n" + bufi += "void " + fabric_mod_name + "_queue_tm_rsp(struct se_cmd *);\n" - if re.search('is_state_remove\)\(', fo): - buf += "int " + fabric_mod_name + "_is_state_remove(struct se_cmd *se_cmd)\n" + if re.search('aborted_task\)\(', fo): + buf += "void " + fabric_mod_name + "_aborted_task(struct se_cmd *se_cmd)\n" buf += "{\n" - buf += " return 0;\n" + buf += " return;\n" buf += "}\n\n" - bufi += "int " + fabric_mod_name + "_is_state_remove(struct se_cmd *);\n" - + bufi += "void " + fabric_mod_name + "_aborted_task(struct se_cmd *);\n" ret = p.write(buf) if ret: @@ -1018,11 +993,11 @@ def main(modname, proto_ident): tcm_mod_build_kbuild(fabric_mod_dir, fabric_mod_name) tcm_mod_build_kconfig(fabric_mod_dir, fabric_mod_name) - input = raw_input("Would you like to add " + fabric_mod_name + "to drivers/target/Makefile..? [yes,no]: ") + input = raw_input("Would you like to add " + fabric_mod_name + " to drivers/target/Makefile..? [yes,no]: ") if input == "yes" or input == "y": tcm_mod_add_kbuild(tcm_dir, fabric_mod_name) - input = raw_input("Would you like to add " + fabric_mod_name + "to drivers/target/Kconfig..? [yes,no]: ") + input = raw_input("Would you like to add " + fabric_mod_name + " to drivers/target/Kconfig..? [yes,no]: ") if input == "yes" or input == "y": tcm_mod_add_kconfig(tcm_dir, fabric_mod_name) diff --git a/Documentation/thermal/cpu-cooling-api.txt b/Documentation/thermal/cpu-cooling-api.txt index fca24c931ec8..753e47cc2e20 100644 --- a/Documentation/thermal/cpu-cooling-api.txt +++ b/Documentation/thermal/cpu-cooling-api.txt @@ -3,7 +3,7 @@ CPU cooling APIs How To Written by Amit Daniel Kachhap <amit.kachhap@linaro.org> -Updated: 12 May 2012 +Updated: 6 Jan 2015 Copyright (c) 2012 Samsung Electronics Co., Ltd(http://www.samsung.com) @@ -25,7 +25,18 @@ the user. The registration APIs returns the cooling device pointer. clip_cpus: cpumask of cpus where the frequency constraints will happen. -1.1.2 void cpufreq_cooling_unregister(struct thermal_cooling_device *cdev) +1.1.2 struct thermal_cooling_device *of_cpufreq_cooling_register( + struct device_node *np, const struct cpumask *clip_cpus) + + This interface function registers the cpufreq cooling device with + the name "thermal-cpufreq-%x" linking it with a device tree node, in + order to bind it via the thermal DT code. This api can support multiple + instances of cpufreq cooling devices. + + np: pointer to the cooling device device tree node + clip_cpus: cpumask of cpus where the frequency constraints will happen. + +1.1.3 void cpufreq_cooling_unregister(struct thermal_cooling_device *cdev) This interface function unregisters the "thermal-cpufreq-%x" cooling device. diff --git a/Documentation/trace/coresight.txt b/Documentation/trace/coresight.txt new file mode 100644 index 000000000000..02361552a3ea --- /dev/null +++ b/Documentation/trace/coresight.txt @@ -0,0 +1,299 @@ + Coresight - HW Assisted Tracing on ARM + ====================================== + + Author: Mathieu Poirier <mathieu.poirier@linaro.org> + Date: September 11th, 2014 + +Introduction +------------ + +Coresight is an umbrella of technologies allowing for the debugging of ARM +based SoC. It includes solutions for JTAG and HW assisted tracing. This +document is concerned with the latter. + +HW assisted tracing is becoming increasingly useful when dealing with systems +that have many SoCs and other components like GPU and DMA engines. ARM has +developed a HW assisted tracing solution by means of different components, each +being added to a design at systhesis time to cater to specific tracing needs. +Compoments are generally categorised as source, link and sinks and are +(usually) discovered using the AMBA bus. + +"Sources" generate a compressed stream representing the processor instruction +path based on tracing scenarios as configured by users. From there the stream +flows through the coresight system (via ATB bus) using links that are connecting +the emanating source to a sink(s). Sinks serve as endpoints to the coresight +implementation, either storing the compressed stream in a memory buffer or +creating an interface to the outside world where data can be transferred to a +host without fear of filling up the onboard coresight memory buffer. + +At typical coresight system would look like this: + + ***************************************************************** + **************************** AMBA AXI ****************************===|| + ***************************************************************** || + ^ ^ | || + | | * ** + 0000000 ::::: 0000000 ::::: ::::: @@@@@@@ |||||||||||| + 0 CPU 0<-->: C : 0 CPU 0<-->: C : : C : @ STM @ || System || + |->0000000 : T : |->0000000 : T : : T :<--->@@@@@ || Memory || + | #######<-->: I : | #######<-->: I : : I : @@@<-| |||||||||||| + | # ETM # ::::: | # PTM # ::::: ::::: @ | + | ##### ^ ^ | ##### ^ ! ^ ! . | ||||||||| + | |->### | ! | |->### | ! | ! . | || DAP || + | | # | ! | | # | ! | ! . | ||||||||| + | | . | ! | | . | ! | ! . | | | + | | . | ! | | . | ! | ! . | | * + | | . | ! | | . | ! | ! . | | SWD/ + | | . | ! | | . | ! | ! . | | JTAG + *****************************************************************<-| + *************************** AMBA Debug APB ************************ + ***************************************************************** + | . ! . ! ! . | + | . * . * * . | + ***************************************************************** + ******************** Cross Trigger Matrix (CTM) ******************* + ***************************************************************** + | . ^ . . | + | * ! * * | + ***************************************************************** + ****************** AMBA Advanced Trace Bus (ATB) ****************** + ***************************************************************** + | ! =============== | + | * ===== F =====<---------| + | ::::::::: ==== U ==== + |-->:: CTI ::<!! === N === + | ::::::::: ! == N == + | ^ * == E == + | ! &&&&&&&&& IIIIIII == L == + |------>&& ETB &&<......II I ======= + | ! &&&&&&&&& II I . + | ! I I . + | ! I REP I<.......... + | ! I I + | !!>&&&&&&&&& II I *Source: ARM ltd. + |------>& TPIU &<......II I DAP = Debug Access Port + &&&&&&&&& IIIIIII ETM = Embedded Trace Macrocell + ; PTM = Program Trace Macrocell + ; CTI = Cross Trigger Interface + * ETB = Embedded Trace Buffer + To trace port TPIU= Trace Port Interface Unit + SWD = Serial Wire Debug + +While on target configuration of the components is done via the APB bus, +all trace data are carried out-of-band on the ATB bus. The CTM provides +a way to aggregate and distribute signals between CoreSight components. + +The coresight framework provides a central point to represent, configure and +manage coresight devices on a platform. This first implementation centers on +the basic tracing functionality, enabling components such ETM/PTM, funnel, +replicator, TMC, TPIU and ETB. Future work will enable more +intricate IP blocks such as STM and CTI. + + +Acronyms and Classification +--------------------------- + +Acronyms: + +PTM: Program Trace Macrocell +ETM: Embedded Trace Macrocell +STM: System trace Macrocell +ETB: Embedded Trace Buffer +ITM: Instrumentation Trace Macrocell +TPIU: Trace Port Interface Unit +TMC-ETR: Trace Memory Controller, configured as Embedded Trace Router +TMC-ETF: Trace Memory Controller, configured as Embedded Trace FIFO +CTI: Cross Trigger Interface + +Classification: + +Source: + ETMv3.x ETMv4, PTMv1.0, PTMv1.1, STM, STM500, ITM +Link: + Funnel, replicator (intelligent or not), TMC-ETR +Sinks: + ETBv1.0, ETB1.1, TPIU, TMC-ETF +Misc: + CTI + + +Device Tree Bindings +---------------------- + +See Documentation/devicetree/bindings/arm/coresight.txt for details. + +As of this writing drivers for ITM, STMs and CTIs are not provided but are +expected to be added as the solution matures. + + +Framework and implementation +---------------------------- + +The coresight framework provides a central point to represent, configure and +manage coresight devices on a platform. Any coresight compliant device can +register with the framework for as long as they use the right APIs: + +struct coresight_device *coresight_register(struct coresight_desc *desc); +void coresight_unregister(struct coresight_device *csdev); + +The registering function is taking a "struct coresight_device *csdev" and +register the device with the core framework. The unregister function takes +a reference to a "strut coresight_device", obtained at registration time. + +If everything goes well during the registration process the new devices will +show up under /sys/bus/coresight/devices, as showns here for a TC2 platform: + +root:~# ls /sys/bus/coresight/devices/ +replicator 20030000.tpiu 2201c000.ptm 2203c000.etm 2203e000.etm +20010000.etb 20040000.funnel 2201d000.ptm 2203d000.etm +root:~# + +The functions take a "struct coresight_device", which looks like this: + +struct coresight_desc { + enum coresight_dev_type type; + struct coresight_dev_subtype subtype; + const struct coresight_ops *ops; + struct coresight_platform_data *pdata; + struct device *dev; + const struct attribute_group **groups; +}; + + +The "coresight_dev_type" identifies what the device is, i.e, source link or +sink while the "coresight_dev_subtype" will characterise that type further. + +The "struct coresight_ops" is mandatory and will tell the framework how to +perform base operations related to the components, each component having +a different set of requirement. For that "struct coresight_ops_sink", +"struct coresight_ops_link" and "struct coresight_ops_source" have been +provided. + +The next field, "struct coresight_platform_data *pdata" is acquired by calling +"of_get_coresight_platform_data()", as part of the driver's _probe routine and +"struct device *dev" gets the device reference embedded in the "amba_device": + +static int etm_probe(struct amba_device *adev, const struct amba_id *id) +{ + ... + ... + drvdata->dev = &adev->dev; + ... +} + +Specific class of device (source, link, or sink) have generic operations +that can be performed on them (see "struct coresight_ops"). The +"**groups" is a list of sysfs entries pertaining to operations +specific to that component only. "Implementation defined" customisations are +expected to be accessed and controlled using those entries. + +Last but not least, "struct module *owner" is expected to be set to reflect +the information carried in "THIS_MODULE". + +How to use +---------- + +Before trace collection can start, a coresight sink needs to be identify. +There is no limit on the amount of sinks (nor sources) that can be enabled at +any given moment. As a generic operation, all device pertaining to the sink +class will have an "active" entry in sysfs: + +root:/sys/bus/coresight/devices# ls +replicator 20030000.tpiu 2201c000.ptm 2203c000.etm 2203e000.etm +20010000.etb 20040000.funnel 2201d000.ptm 2203d000.etm +root:/sys/bus/coresight/devices# ls 20010000.etb +enable_sink status trigger_cntr +root:/sys/bus/coresight/devices# echo 1 > 20010000.etb/enable_sink +root:/sys/bus/coresight/devices# cat 20010000.etb/enable_sink +1 +root:/sys/bus/coresight/devices# + +At boot time the current etm3x driver will configure the first address +comparator with "_stext" and "_etext", essentially tracing any instruction +that falls within that range. As such "enabling" a source will immediately +trigger a trace capture: + +root:/sys/bus/coresight/devices# echo 1 > 2201c000.ptm/enable_source +root:/sys/bus/coresight/devices# cat 2201c000.ptm/enable_source +1 +root:/sys/bus/coresight/devices# cat 20010000.etb/status +Depth: 0x2000 +Status: 0x1 +RAM read ptr: 0x0 +RAM wrt ptr: 0x19d3 <----- The write pointer is moving +Trigger cnt: 0x0 +Control: 0x1 +Flush status: 0x0 +Flush ctrl: 0x2001 +root:/sys/bus/coresight/devices# + +Trace collection is stopped the same way: + +root:/sys/bus/coresight/devices# echo 0 > 2201c000.ptm/enable_source +root:/sys/bus/coresight/devices# + +The content of the ETB buffer can be harvested directly from /dev: + +root:/sys/bus/coresight/devices# dd if=/dev/20010000.etb \ +of=~/cstrace.bin + +64+0 records in +64+0 records out +32768 bytes (33 kB) copied, 0.00125258 s, 26.2 MB/s +root:/sys/bus/coresight/devices# + +The file cstrace.bin can be decompressed using "ptm2human", DS-5 or Trace32. + +Following is a DS-5 output of an experimental loop that increments a variable up +to a certain value. The example is simple and yet provides a glimpse of the +wealth of possibilities that coresight provides. + +Info Tracing enabled +Instruction 106378866 0x8026B53C E52DE004 false PUSH {lr} +Instruction 0 0x8026B540 E24DD00C false SUB sp,sp,#0xc +Instruction 0 0x8026B544 E3A03000 false MOV r3,#0 +Instruction 0 0x8026B548 E58D3004 false STR r3,[sp,#4] +Instruction 0 0x8026B54C E59D3004 false LDR r3,[sp,#4] +Instruction 0 0x8026B550 E3530004 false CMP r3,#4 +Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1 +Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4] +Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c +Timestamp Timestamp: 17106715833 +Instruction 319 0x8026B54C E59D3004 false LDR r3,[sp,#4] +Instruction 0 0x8026B550 E3530004 false CMP r3,#4 +Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1 +Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4] +Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c +Instruction 9 0x8026B54C E59D3004 false LDR r3,[sp,#4] +Instruction 0 0x8026B550 E3530004 false CMP r3,#4 +Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1 +Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4] +Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c +Instruction 7 0x8026B54C E59D3004 false LDR r3,[sp,#4] +Instruction 0 0x8026B550 E3530004 false CMP r3,#4 +Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1 +Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4] +Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c +Instruction 7 0x8026B54C E59D3004 false LDR r3,[sp,#4] +Instruction 0 0x8026B550 E3530004 false CMP r3,#4 +Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1 +Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4] +Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c +Instruction 10 0x8026B54C E59D3004 false LDR r3,[sp,#4] +Instruction 0 0x8026B550 E3530004 false CMP r3,#4 +Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1 +Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4] +Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c +Instruction 6 0x8026B560 EE1D3F30 false MRC p15,#0x0,r3,c13,c0,#1 +Instruction 0 0x8026B564 E1A0100D false MOV r1,sp +Instruction 0 0x8026B568 E3C12D7F false BIC r2,r1,#0x1fc0 +Instruction 0 0x8026B56C E3C2203F false BIC r2,r2,#0x3f +Instruction 0 0x8026B570 E59D1004 false LDR r1,[sp,#4] +Instruction 0 0x8026B574 E59F0010 false LDR r0,[pc,#16] ; [0x8026B58C] = 0x80550368 +Instruction 0 0x8026B578 E592200C false LDR r2,[r2,#0xc] +Instruction 0 0x8026B57C E59221D0 false LDR r2,[r2,#0x1d0] +Instruction 0 0x8026B580 EB07A4CF true BL {pc}+0x1e9344 ; 0x804548c4 +Info Tracing enabled +Instruction 13570831 0x8026B584 E28DD00C false ADD sp,sp,#0xc +Instruction 0 0x8026B588 E8BD8000 true LDM sp!,{pc} +Timestamp Timestamp: 17107041535 diff --git a/Documentation/trace/ftrace.txt b/Documentation/trace/ftrace.txt index 4da42616939f..572ca923631a 100644 --- a/Documentation/trace/ftrace.txt +++ b/Documentation/trace/ftrace.txt @@ -234,6 +234,11 @@ of ftrace. Here is a list of some of the key files: will be displayed on the same line as the function that is returning registers. + If the callback registered to be traced by a function with + the "ip modify" attribute (thus the regs->ip can be changed), + an 'I' will be displayed on the same line as the function that + can be overridden. + function_profile_enabled: When set it will enable all functions with either the function @@ -680,9 +685,11 @@ The above is mostly meaningful for kernel developers. needs to be fixed to be only relative to the same CPU. The marks are determined by the difference between this current trace and the next trace. - '!' - greater than preempt_mark_thresh (default 100) - '+' - greater than 1 microsecond - ' ' - less than or equal to 1 microsecond. + '$' - greater than 1 second + '#' - greater than 1000 microsecond + '!' - greater than 100 microsecond + '+' - greater than 10 microsecond + ' ' - less than or equal to 10 microsecond. The rest is the same as the 'trace' file. @@ -1733,7 +1740,7 @@ no pid yum-updatesd-3111 [003] 1637.254683: lock_hrtimer_base <-hrtimer_try_to_cancel yum-updatesd-3111 [003] 1637.254685: fget_light <-do_sys_poll yum-updatesd-3111 [003] 1637.254686: pipe_poll <-do_sys_poll -# echo -1 > set_ftrace_pid +# echo > set_ftrace_pid # cat trace |head # tracer: function # @@ -1951,6 +1958,8 @@ want, depending on your needs. + means that the function exceeded 10 usecs. ! means that the function exceeded 100 usecs. + # means that the function exceeded 1000 usecs. + $ means that the function exceeded 1 sec. - The task/pid field displays the thread cmdline and pid which diff --git a/Documentation/usb/gadget-testing.txt b/Documentation/usb/gadget-testing.txt new file mode 100644 index 000000000000..076ac7ba7f93 --- /dev/null +++ b/Documentation/usb/gadget-testing.txt @@ -0,0 +1,728 @@ +This file summarizes information on basic testing of USB functions +provided by gadgets. + +1. ACM function +2. ECM function +3. ECM subset function +4. EEM function +5. FFS function +6. HID function +7. LOOPBACK function +8. MASS STORAGE function +9. MIDI function +10. NCM function +11. OBEX function +12. PHONET function +13. RNDIS function +14. SERIAL function +15. SOURCESINK function +16. UAC1 function +17. UAC2 function +18. UVC function + + +1. ACM function +=============== + +The function is provided by usb_f_acm.ko module. + +Function-specific configfs interface +------------------------------------ + +The function name to use when creating the function directory is "acm". +The ACM function provides just one attribute in its function directory: + + port_num + +The attribute is read-only. + +There can be at most 4 ACM/generic serial/OBEX ports in the system. + + +Testing the ACM function +------------------------ + +On the host: cat > /dev/ttyACM<X> +On the device : cat /dev/ttyGS<Y> + +then the other way round + +On the device: cat > /dev/ttyGS<Y> +On the host: cat /dev/ttyACM<X> + +2. ECM function +=============== + +The function is provided by usb_f_ecm.ko module. + +Function-specific configfs interface +------------------------------------ + +The function name to use when creating the function directory is "ecm". +The ECM function provides these attributes in its function directory: + + ifname - network device interface name associated with this + function instance + qmult - queue length multiplier for high and super speed + host_addr - MAC address of host's end of this + Ethernet over USB link + dev_addr - MAC address of device's end of this + Ethernet over USB link + +and after creating the functions/ecm.<instance name> they contain default +values: qmult is 5, dev_addr and host_addr are randomly selected. +Except for ifname they can be written to until the function is linked to a +configuration. The ifname is read-only and contains the name of the interface +which was assigned by the net core, e. g. usb0. + +Testing the ECM function +------------------------ + +Configure IP addresses of the device and the host. Then: + +On the device: ping <host's IP> +On the host: ping <device's IP> + +3. ECM subset function +====================== + +The function is provided by usb_f_ecm_subset.ko module. + +Function-specific configfs interface +------------------------------------ + +The function name to use when creating the function directory is "geth". +The ECM subset function provides these attributes in its function directory: + + ifname - network device interface name associated with this + function instance + qmult - queue length multiplier for high and super speed + host_addr - MAC address of host's end of this + Ethernet over USB link + dev_addr - MAC address of device's end of this + Ethernet over USB link + +and after creating the functions/ecm.<instance name> they contain default +values: qmult is 5, dev_addr and host_addr are randomly selected. +Except for ifname they can be written to until the function is linked to a +configuration. The ifname is read-only and contains the name of the interface +which was assigned by the net core, e. g. usb0. + +Testing the ECM subset function +------------------------------- + +Configure IP addresses of the device and the host. Then: + +On the device: ping <host's IP> +On the host: ping <device's IP> + +4. EEM function +=============== + +The function is provided by usb_f_eem.ko module. + +Function-specific configfs interface +------------------------------------ + +The function name to use when creating the function directory is "eem". +The EEM function provides these attributes in its function directory: + + ifname - network device interface name associated with this + function instance + qmult - queue length multiplier for high and super speed + host_addr - MAC address of host's end of this + Ethernet over USB link + dev_addr - MAC address of device's end of this + Ethernet over USB link + +and after creating the functions/eem.<instance name> they contain default +values: qmult is 5, dev_addr and host_addr are randomly selected. +Except for ifname they can be written to until the function is linked to a +configuration. The ifname is read-only and contains the name of the interface +which was assigned by the net core, e. g. usb0. + +Testing the EEM function +------------------------ + +Configure IP addresses of the device and the host. Then: + +On the device: ping <host's IP> +On the host: ping <device's IP> + +5. FFS function +=============== + +The function is provided by usb_f_fs.ko module. + +Function-specific configfs interface +------------------------------------ + +The function name to use when creating the function directory is "ffs". +The function directory is intentionally empty and not modifiable. + +After creating the directory there is a new instance (a "device") of FunctionFS +available in the system. Once a "device" is available, the user should follow +the standard procedure for using FunctionFS (mount it, run the userspace +process which implements the function proper). The gadget should be enabled +by writing a suitable string to usb_gadget/<gadget>/UDC. + +Testing the FFS function +------------------------ + +On the device: start the function's userspace daemon, enable the gadget +On the host: use the USB function provided by the device + +6. HID function +=============== + +The function is provided by usb_f_hid.ko module. + +Function-specific configfs interface +------------------------------------ + +The function name to use when creating the function directory is "hid". +The HID function provides these attributes in its function directory: + + protocol - HID protocol to use + report_desc - data to be used in HID reports, except data + passed with /dev/hidg<X> + report_length - HID report length + subclass - HID subclass to use + +For a keyboard the protocol and the subclass are 1, the report_length is 8, +while the report_desc is: + +$ hd my_report_desc +00000000 05 01 09 06 a1 01 05 07 19 e0 29 e7 15 00 25 01 |..........)...%.| +00000010 75 01 95 08 81 02 95 01 75 08 81 03 95 05 75 01 |u.......u.....u.| +00000020 05 08 19 01 29 05 91 02 95 01 75 03 91 03 95 06 |....).....u.....| +00000030 75 08 15 00 25 65 05 07 19 00 29 65 81 00 c0 |u...%e....)e...| +0000003f + +Such a sequence of bytes can be stored to the attribute with echo: + +$ echo -ne \\x05\\x01\\x09\\x06\\xa1..... + +Testing the HID function +------------------------ + +Device: +- create the gadget +- connect the gadget to a host, preferably not the one used +to control the gadget +- run a program which writes to /dev/hidg<N>, e.g. +a userspace program found in Documentation/usb/gadget_hid.txt: + +$ ./hid_gadget_test /dev/hidg0 keyboard + +Host: +- observe the keystrokes from the gadget + +7. LOOPBACK function +==================== + +The function is provided by usb_f_ss_lb.ko module. + +Function-specific configfs interface +------------------------------------ + +The function name to use when creating the function directory is "Loopback". +The LOOPBACK function provides these attributes in its function directory: + + qlen - depth of loopback queue + bulk_buflen - buffer length + +Testing the LOOPBACK function +----------------------------- + +device: run the gadget +host: test-usb + +http://www.linux-usb.org/usbtest/testusb.c + +8. MASS STORAGE function +======================== + +The function is provided by usb_f_mass_storage.ko module. + +Function-specific configfs interface +------------------------------------ + +The function name to use when creating the function directory is "mass_storage". +The MASS STORAGE function provides these attributes in its directory: +files: + + stall - Set to permit function to halt bulk endpoints. + Disabled on some USB devices known not to work + correctly. You should set it to true. + num_buffers - Number of pipeline buffers. Valid numbers + are 2..4. Available only if + CONFIG_USB_GADGET_DEBUG_FILES is set. + +and a default lun.0 directory corresponding to SCSI LUN #0. + +A new lun can be added with mkdir: + +$ mkdir functions/mass_storage.0/partition.5 + +Lun numbering does not have to be continuous, except for lun #0 which is +created by default. A maximum of 8 luns can be specified and they all must be +named following the <name>.<number> scheme. The numbers can be 0..8. +Probably a good convention is to name the luns "lun.<number>", +although it is not mandatory. + +In each lun directory there are the following attribute files: + + file - The path to the backing file for the LUN. + Required if LUN is not marked as removable. + ro - Flag specifying access to the LUN shall be + read-only. This is implied if CD-ROM emulation + is enabled as well as when it was impossible + to open "filename" in R/W mode. + removable - Flag specifying that LUN shall be indicated as + being removable. + cdrom - Flag specifying that LUN shall be reported as + being a CD-ROM. + nofua - Flag specifying that FUA flag + in SCSI WRITE(10,12) + +Testing the MASS STORAGE function +--------------------------------- + +device: connect the gadget, enable it +host: dmesg, see the USB drives appear (if system configured to automatically +mount) + +9. MIDI function +================ + +The function is provided by usb_f_midi.ko module. + +Function-specific configfs interface +------------------------------------ + +The function name to use when creating the function directory is "midi". +The MIDI function provides these attributes in its function directory: + + buflen - MIDI buffer length + id - ID string for the USB MIDI adapter + in_ports - number of MIDI input ports + index - index value for the USB MIDI adapter + out_ports - number of MIDI output ports + qlen - USB read request queue length + +Testing the MIDI function +------------------------- + +There are two cases: playing a mid from the gadget to +the host and playing a mid from the host to the gadget. + +1) Playing a mid from the gadget to the host +host) + +$ arecordmidi -l + Port Client name Port name + 14:0 Midi Through Midi Through Port-0 + 24:0 MIDI Gadget MIDI Gadget MIDI 1 +$ arecordmidi -p 24:0 from_gadget.mid + +gadget) + +$ aplaymidi -l + Port Client name Port name + 20:0 f_midi f_midi + +$ aplaymidi -p 20:0 to_host.mid + +2) Playing a mid from the host to the gadget +gadget) + +$ arecordmidi -l + Port Client name Port name + 20:0 f_midi f_midi + +$ arecordmidi -p 20:0 from_host.mid + +host) + +$ aplaymidi -l + Port Client name Port name + 14:0 Midi Through Midi Through Port-0 + 24:0 MIDI Gadget MIDI Gadget MIDI 1 + +$ aplaymidi -p24:0 to_gadget.mid + +The from_gadget.mid should sound identical to the to_host.mid. +The from_host.id should sound identical to the to_gadget.mid. + +MIDI files can be played to speakers/headphones with e.g. timidity installed + +$ aplaymidi -l + Port Client name Port name + 14:0 Midi Through Midi Through Port-0 + 24:0 MIDI Gadget MIDI Gadget MIDI 1 +128:0 TiMidity TiMidity port 0 +128:1 TiMidity TiMidity port 1 +128:2 TiMidity TiMidity port 2 +128:3 TiMidity TiMidity port 3 + +$ aplaymidi -p 128:0 file.mid + +MIDI ports can be logically connected using the aconnect utility, e.g.: + +$ aconnect 24:0 128:0 # try it on the host + +After the gadget's MIDI port is connected to timidity's MIDI port, +whatever is played at the gadget side with aplaymidi -l is audible +in host's speakers/headphones. + +10. NCM function +================ + +The function is provided by usb_f_ncm.ko module. + +Function-specific configfs interface +------------------------------------ + +The function name to use when creating the function directory is "ncm". +The NCM function provides these attributes in its function directory: + + ifname - network device interface name associated with this + function instance + qmult - queue length multiplier for high and super speed + host_addr - MAC address of host's end of this + Ethernet over USB link + dev_addr - MAC address of device's end of this + Ethernet over USB link + +and after creating the functions/ncm.<instance name> they contain default +values: qmult is 5, dev_addr and host_addr are randomly selected. +Except for ifname they can be written to until the function is linked to a +configuration. The ifname is read-only and contains the name of the interface +which was assigned by the net core, e. g. usb0. + +Testing the NCM function +------------------------ + +Configure IP addresses of the device and the host. Then: + +On the device: ping <host's IP> +On the host: ping <device's IP> + +11. OBEX function +================= + +The function is provided by usb_f_obex.ko module. + +Function-specific configfs interface +------------------------------------ + +The function name to use when creating the function directory is "obex". +The OBEX function provides just one attribute in its function directory: + + port_num + +The attribute is read-only. + +There can be at most 4 ACM/generic serial/OBEX ports in the system. + +Testing the OBEX function +------------------------- + +On device: seriald -f /dev/ttyGS<Y> -s 1024 +On host: serialc -v <vendorID> -p <productID> -i<interface#> -a1 -s1024 \ + -t<out endpoint addr> -r<in endpoint addr> + +where seriald and serialc are Felipe's utilities found here: + +https://git.gitorious.org/usb/usb-tools.git master + +12. PHONET function +=================== + +The function is provided by usb_f_phonet.ko module. + +Function-specific configfs interface +------------------------------------ + +The function name to use when creating the function directory is "phonet". +The PHONET function provides just one attribute in its function directory: + + ifname - network device interface name associated with this + function instance + +Testing the PHONET function +--------------------------- + +It is not possible to test the SOCK_STREAM protocol without a specific piece +of hardware, so only SOCK_DGRAM has been tested. For the latter to work, +in the past I had to apply the patch mentioned here: + +http://www.spinics.net/lists/linux-usb/msg85689.html + +These tools are required: + +git://git.gitorious.org/meego-cellular/phonet-utils.git + +On the host: + +$ ./phonet -a 0x10 -i usbpn0 +$ ./pnroute add 0x6c usbpn0 +$./pnroute add 0x10 usbpn0 +$ ifconfig usbpn0 up + +On the device: + +$ ./phonet -a 0x6c -i upnlink0 +$ ./pnroute add 0x10 upnlink0 +$ ifconfig upnlink0 up + +Then a test program can be used: + +http://www.spinics.net/lists/linux-usb/msg85690.html + +On the device: + +$ ./pnxmit -a 0x6c -r + +On the host: + +$ ./pnxmit -a 0x10 -s 0x6c + +As a result some data should be sent from host to device. +Then the other way round: + +On the host: + +$ ./pnxmit -a 0x10 -r + +On the device: + +$ ./pnxmit -a 0x6c -s 0x10 + +13. RNDIS function +================== + +The function is provided by usb_f_rndis.ko module. + +Function-specific configfs interface +------------------------------------ + +The function name to use when creating the function directory is "rndis". +The RNDIS function provides these attributes in its function directory: + + ifname - network device interface name associated with this + function instance + qmult - queue length multiplier for high and super speed + host_addr - MAC address of host's end of this + Ethernet over USB link + dev_addr - MAC address of device's end of this + Ethernet over USB link + +and after creating the functions/rndis.<instance name> they contain default +values: qmult is 5, dev_addr and host_addr are randomly selected. +Except for ifname they can be written to until the function is linked to a +configuration. The ifname is read-only and contains the name of the interface +which was assigned by the net core, e. g. usb0. + +By default there can be only 1 RNDIS interface in the system. + +Testing the RNDIS function +-------------------------- + +Configure IP addresses of the device and the host. Then: + +On the device: ping <host's IP> +On the host: ping <device's IP> + +14. SERIAL function +=================== + +The function is provided by usb_f_gser.ko module. + +Function-specific configfs interface +------------------------------------ + +The function name to use when creating the function directory is "gser". +The SERIAL function provides just one attribute in its function directory: + + port_num + +The attribute is read-only. + +There can be at most 4 ACM/generic serial/OBEX ports in the system. + +Testing the SERIAL function +--------------------------- + +On host: insmod usbserial + echo VID PID >/sys/bus/usb-serial/drivers/generic/new_id +On host: cat > /dev/ttyUSB<X> +On target: cat /dev/ttyGS<Y> + +then the other way round + +On target: cat > /dev/ttyGS<Y> +On host: cat /dev/ttyUSB<X> + +15. SOURCESINK function +======================= + +The function is provided by usb_f_ss_lb.ko module. + +Function-specific configfs interface +------------------------------------ + +The function name to use when creating the function directory is "SourceSink". +The SOURCESINK function provides these attributes in its function directory: + + pattern - 0 (all zeros), 1 (mod63), 2 (none) + isoc_interval - 1..16 + isoc_maxpacket - 0 - 1023 (fs), 0 - 1024 (hs/ss) + isoc_mult - 0..2 (hs/ss only) + isoc_maxburst - 0..15 (ss only) + bulk_buflen - buffer length + +Testing the SOURCESINK function +------------------------------- + +device: run the gadget +host: test-usb + +http://www.linux-usb.org/usbtest/testusb.c + +16. UAC1 function +================= + +The function is provided by usb_f_uac1.ko module. + +Function-specific configfs interface +------------------------------------ + +The function name to use when creating the function directory is "uac1". +The uac1 function provides these attributes in its function directory: + + audio_buf_size - audio buffer size + fn_cap - capture pcm device file name + fn_cntl - control device file name + fn_play - playback pcm device file name + req_buf_size - ISO OUT endpoint request buffer size + req_count - ISO OUT endpoint request count + +The attributes have sane default values. + +Testing the UAC1 function +------------------------- + +device: run the gadget +host: aplay -l # should list our USB Audio Gadget + +17. UAC2 function +================= + +The function is provided by usb_f_uac2.ko module. + +Function-specific configfs interface +------------------------------------ + +The function name to use when creating the function directory is "uac2". +The uac2 function provides these attributes in its function directory: + + chmask - capture channel mask + c_srate - capture sampling rate + c_ssize - capture sample size (bytes) + p_chmask - playback channel mask + p_srate - playback sampling rate + p_ssize - playback sample size (bytes) + +The attributes have sane default values. + +Testing the UAC2 function +------------------------- + +device: run the gadget +host: aplay -l # should list our USB Audio Gadget + +This function does not require real hardware support, it just +sends a stream of audio data to/from the host. In order to +actually hear something at the device side, a command similar +to this must be used at the device side: + +$ arecord -f dat -t wav -D hw:2,0 | aplay -D hw:0,0 & + +e.g.: + +$ arecord -f dat -t wav -D hw:CARD=UAC2Gadget,DEV=0 | \ +aplay -D default:CARD=OdroidU3 + +18. UVC function +================ + +The function is provided by usb_f_uvc.ko module. + +Function-specific configfs interface +------------------------------------ + +The function name to use when creating the function directory is "uvc". +The uvc function provides these attributes in its function directory: + + streaming_interval - interval for polling endpoint for data transfers + streaming_maxburst - bMaxBurst for super speed companion descriptor + streaming_maxpacket - maximum packet size this endpoint is capable of + sending or receiving when this configuration is + selected + +There are also "control" and "streaming" subdirectories, each of which contain +a number of their subdirectories. There are some sane defaults provided, but +the user must provide the following: + + control header - create in control/header, link from control/class/fs + and/or control/class/ss + streaming header - create in streaming/header, link from + streaming/class/fs and/or streaming/class/hs and/or + streaming/class/ss + format description - create in streaming/mjpeg and/or + streaming/uncompressed + frame description - create in streaming/mjpeg/<format> and/or in + streaming/uncompressed/<format> + +Each frame description contains frame interval specification, and each +such specification consists of a number of lines with an inverval value +in each line. The rules stated above are best illustrated with an example: + +# mkdir functions/uvc.usb0/control/header/h +# cd functions/uvc.usb0/control/header/h +# ln -s header/h class/fs +# ln -s header/h class/ss +# mkdir -p functions/uvc.usb0/streaming/uncompressed/u/360p +# cat <<EOF > functions/uvc.usb0/streaming/uncompressed/u/360p/dwFrameInterval +666666 +1000000 +5000000 +EOF +# cd $GADGET_CONFIGFS_ROOT +# mkdir functions/uvc.usb0/streaming/header/h +# cd functions/uvc.usb0/streaming/header/h +# ln -s ../../uncompressed/u +# cd ../../class/fs +# ln -s ../../header/h +# cd ../../class/hs +# ln -s ../../header/h +# cd ../../class/ss +# ln -s ../../header/h + + +Testing the UVC function +------------------------ + +device: run the gadget, modprobe vivid + +# uvc-gadget -u /dev/video<uvc video node #> -v /dev/video<vivid video node #> + +where uvc-gadget is this program: +http://git.ideasonboard.org/uvc-gadget.git + +with these patches: +http://www.spinics.net/lists/linux-usb/msg99220.html + +host: luvcview -f yuv diff --git a/Documentation/usb/gadget_configfs.txt b/Documentation/usb/gadget_configfs.txt index 4cf53e406613..635e57493709 100644 --- a/Documentation/usb/gadget_configfs.txt +++ b/Documentation/usb/gadget_configfs.txt @@ -376,7 +376,7 @@ functions and binds them. This way the whole gadget is bound. configured, so config_groups for particular functions are defined in the functions implementation files drivers/usb/gadget/f_*.c. -5. Funciton's code is written in such a way that it uses +5. Function's code is written in such a way that it uses usb_get_function_instance(), which, in turn, calls request_module. So, provided that modprobe works, modules for particular functions diff --git a/Documentation/usb/gadget_hid.txt b/Documentation/usb/gadget_hid.txt index 12696c2e43fb..7a0fb8e16e27 100644 --- a/Documentation/usb/gadget_hid.txt +++ b/Documentation/usb/gadget_hid.txt @@ -74,6 +74,13 @@ static struct platform_device my_hid = { You can add as many HID functions as you want, only limited by the amount of interrupt endpoints your gadget driver supports. +Configuration with configfs + + Instead of adding fake platform devices and drivers in order to pass + some data to the kernel, if HID is a part of a gadget composed with + configfs the hidg_func_descriptor.report_desc is passed to the kernel + by writing the appropriate stream of bytes to a configfs attribute. + Send and receive HID reports HID reports can be sent/received using read/write on the diff --git a/Documentation/usb/gadget_serial.txt b/Documentation/usb/gadget_serial.txt index 61e67f6a20a0..6b4a88a8c8e3 100644 --- a/Documentation/usb/gadget_serial.txt +++ b/Documentation/usb/gadget_serial.txt @@ -236,8 +236,12 @@ I: If#= 0 Alt= 0 #EPs= 2 Cls=0a(data ) Sub=00 Prot=00 Driver=serial E: Ad=81(I) Atr=02(Bulk) MxPS= 512 Ivl=0ms E: Ad=02(O) Atr=02(Bulk) MxPS= 512 Ivl=0ms -You must explicitly load the usbserial driver with parameters to -configure it to recognize the gadget serial device, like this: +You must load the usbserial driver and explicitly set its parameters +to configure it to recognize the gadget serial device, like this: + + echo 0x0525 0xA4A6 >/sys/bus/usb-serial/drivers/generic/new_id + +The legacy way is to use module parameters: modprobe usbserial vendor=0x0525 product=0xA4A6 diff --git a/Documentation/usb/power-management.txt b/Documentation/usb/power-management.txt index 7b90fe034c4b..b5f83911732a 100644 --- a/Documentation/usb/power-management.txt +++ b/Documentation/usb/power-management.txt @@ -47,14 +47,15 @@ dynamic PM is implemented in the USB subsystem, although system PM is covered to some extent (see Documentation/power/*.txt for more information about system PM). -Note: Dynamic PM support for USB is present only if the kernel was -built with CONFIG_USB_SUSPEND enabled (which depends on -CONFIG_PM_RUNTIME). System PM support is present only if the kernel -was built with CONFIG_SUSPEND or CONFIG_HIBERNATION enabled. - -(Starting with the 3.10 kernel release, dynamic PM support for USB is -present whenever the kernel was built with CONFIG_PM_RUNTIME enabled. -The CONFIG_USB_SUSPEND option has been eliminated.) +System PM support is present only if the kernel was built with CONFIG_SUSPEND +or CONFIG_HIBERNATION enabled. Dynamic PM support for USB is present whenever +the kernel was built with CONFIG_PM enabled. + +[Historically, dynamic PM support for USB was present only if the +kernel had been built with CONFIG_USB_SUSPEND enabled (which depended on +CONFIG_PM_RUNTIME). Starting with the 3.10 kernel release, dynamic PM support +for USB was present whenever the kernel was built with CONFIG_PM_RUNTIME +enabled. The CONFIG_USB_SUSPEND option had been eliminated.] What is Remote Wakeup? diff --git a/Documentation/usb/usb-serial.txt b/Documentation/usb/usb-serial.txt index 5bd7926185e8..947fa62bccf2 100644 --- a/Documentation/usb/usb-serial.txt +++ b/Documentation/usb/usb-serial.txt @@ -145,7 +145,7 @@ Keyspan PDA Serial Adapter Single port DB-9 serial adapter, pushed as a PDA adapter for iMacs (mostly sold in Macintosh catalogs, comes in a translucent white/green dongle). Fairly simple device. Firmware is homebrew. - This driver also works for the Xircom/Entrgra single port serial adapter. + This driver also works for the Xircom/Entrega single port serial adapter. Current status: Things that work: diff --git a/Documentation/usb/usbmon.txt b/Documentation/usb/usbmon.txt index c42bb9cd3b43..28425f736756 100644 --- a/Documentation/usb/usbmon.txt +++ b/Documentation/usb/usbmon.txt @@ -72,7 +72,7 @@ to listen on a single bus, otherwise, to listen on all buses, type: # cat /sys/kernel/debug/usb/usbmon/0u > /tmp/1.mon.out -This process will be reading until killed. Naturally, the output can be +This process will read until it is killed. Naturally, the output can be redirected to a desirable location. This is preferred, because it is going to be quite long. @@ -231,7 +231,7 @@ number. Number zero (/dev/usbmon0) is special and means "all buses". Note that specific naming policy is set by your Linux distribution. If you create /dev/usbmon0 by hand, make sure that it is owned by root -and has mode 0600. Otherwise, unpriviledged users will be able to snoop +and has mode 0600. Otherwise, unprivileged users will be able to snoop keyboard traffic. The following ioctl calls are available, with MON_IOC_MAGIC 0x92: diff --git a/Documentation/video4linux/CARDLIST.cx23885 b/Documentation/video4linux/CARDLIST.cx23885 index a74eeccfe700..4c84ec853265 100644 --- a/Documentation/video4linux/CARDLIST.cx23885 +++ b/Documentation/video4linux/CARDLIST.cx23885 @@ -43,3 +43,5 @@ 42 -> Leadtek Winfast PxPVR2200 [107d:6f21] 43 -> Hauppauge ImpactVCB-e [0070:7133] 44 -> DViCO FusionHDTV DVB-T Dual Express2 [18ac:db98] + 45 -> DVBSky T9580 [4254:9580] + 46 -> DVBSky T980C [4254:980c] diff --git a/Documentation/video4linux/CARDLIST.em28xx b/Documentation/video4linux/CARDLIST.em28xx index bc3351bb48b4..3700edb81db2 100644 --- a/Documentation/video4linux/CARDLIST.em28xx +++ b/Documentation/video4linux/CARDLIST.em28xx @@ -93,3 +93,4 @@ 92 -> PCTV DVB-S2 Stick (461e) (em28178) 93 -> KWorld USB ATSC TV Stick UB435-Q V3 (em2874) [1b80:e34c] 94 -> PCTV tripleStick (292e) (em28178) + 95 -> Leadtek VC100 (em2861) [0413:6f07] diff --git a/Documentation/video4linux/CARDLIST.saa7134 b/Documentation/video4linux/CARDLIST.saa7134 index 8df17d063499..a93d86455233 100644 --- a/Documentation/video4linux/CARDLIST.saa7134 +++ b/Documentation/video4linux/CARDLIST.saa7134 @@ -191,3 +191,4 @@ 190 -> Asus My Cinema PS3-100 [1043:48cd] 191 -> Hawell HW-9004V1 192 -> AverMedia AverTV Satellite Hybrid+FM A706 [1461:2055] +193 -> WIS Voyager or compatible [1905:7007] diff --git a/Documentation/video4linux/CQcam.txt b/Documentation/video4linux/CQcam.txt deleted file mode 100644 index 0b69e4ee8e31..000000000000 --- a/Documentation/video4linux/CQcam.txt +++ /dev/null @@ -1,205 +0,0 @@ -c-qcam - Connectix Color QuickCam video4linux kernel driver - -Copyright (C) 1999 Dave Forrest <drf5n@virginia.edu> - released under GNU GPL. - -1999-12-08 Dave Forrest, written with kernel version 2.2.12 in mind - - -Table of Contents - -1.0 Introduction -2.0 Compilation, Installation, and Configuration -3.0 Troubleshooting -4.0 Future Work / current work arounds -9.0 Sample Program, v4lgrab -10.0 Other Information - - -1.0 Introduction - - The file ../../drivers/media/parport/c-qcam.c is a device driver for -the Logitech (nee Connectix) parallel port interface color CCD camera. -This is a fairly inexpensive device for capturing images. Logitech -does not currently provide information for developers, but many people -have engineered several solutions for non-Microsoft use of the Color -Quickcam. - -1.1 Motivation - - I spent a number of hours trying to get my camera to work, and I -hope this document saves you some time. My camera will not work with -the 2.2.13 kernel as distributed, but with a few patches to the -module, I was able to grab some frames. See 4.0, Future Work. - - - -2.0 Compilation, Installation, and Configuration - - The c-qcam depends on parallel port support, video4linux, and the -Color Quickcam. It is also nice to have the parallel port readback -support enabled. I enabled these as modules during the kernel -configuration. The appropriate flags are: - - CONFIG_PRINTER M for lp.o, parport.o parport_pc.o modules - CONFIG_PNP_PARPORT M for autoprobe.o IEEE1284 readback module - CONFIG_PRINTER_READBACK M for parport_probe.o IEEE1284 readback module - CONFIG_VIDEO_DEV M for videodev.o video4linux module - CONFIG_VIDEO_CQCAM M for c-qcam.o Color Quickcam module - - With these flags, the kernel should compile and install the modules. -To record and monitor the compilation, I use: - - (make zlilo ; \ - make modules; \ - make modules_install ; - depmod -a ) &>log & - less log # then a capital 'F' to watch the progress - -But that is my personal preference. - -2.2 Configuration - - The configuration requires module configuration and device -configuration. The following sections detail these procedures. - - -2.1 Module Configuration - - Using modules requires a bit of work to install and pass the -parameters. Understand that entries in /etc/modprobe.d/*.conf of: - - alias parport_lowlevel parport_pc - options parport_pc io=0x378 irq=none - alias char-major-81 videodev - alias char-major-81-0 c-qcam - -2.2 Device Configuration - - At this point, we need to ensure that the device files exist. -Video4linux used the /dev/video* files, and we want to attach the -Quickcam to one of these. - - ls -lad /dev/video* # should produce a list of the video devices - -If the video devices do not exist, you can create them with: - - su - cd /dev - for ii in 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 ; do - mknod video$ii c 81 $ii # char-major-81-[0-16] - chown root.root video$ii # owned by root - chmod 600 video$ii # read/writable by root only - done - - Lots of people connect video0 to video and bttv, but you might want -your c-qcam to mean something more: - - ln -s video0 c-qcam # make /dev/c-qcam a working file - ln -s c-qcam video # make /dev/c-qcam your default video source - - But these are conveniences. The important part is to make the proper -special character files with the right major and minor numbers. All -of the special device files are listed in ../devices.txt. If you -would like the c-qcam readable by non-root users, you will need to -change the permissions. - -3.0 Troubleshooting - - If the sample program below, v4lgrab, gives you output then -everything is working. - - v4lgrab | wc # should give you a count of characters - - Otherwise, you have some problem. - - The c-qcam is IEEE1284 compatible, so if you are using the proc file -system (CONFIG_PROC_FS), the parallel printer support -(CONFIG_PRINTER), the IEEE 1284 system,(CONFIG_PRINTER_READBACK), you -should be able to read some identification from your quickcam with - - modprobe -v parport - modprobe -v parport_probe - cat /proc/parport/PORTNUMBER/autoprobe -Returns: - CLASS:MEDIA; - MODEL:Color QuickCam 2.0; - MANUFACTURER:Connectix; - - A good response to this indicates that your color quickcam is alive -and well. A common problem is that the current driver does not -reliably detect a c-qcam, even though one is attached. In this case, - - modprobe -v c-qcam -or - insmod -v c-qcam - - Returns a message saying "Device or resource busy" Development is -currently underway, but a workaround is to patch the module to skip -the detection code and attach to a defined port. Check the -video4linux mailing list and archive for more current information. - -3.1 Checklist: - - Can you get an image? - v4lgrab >qcam.ppm ; wc qcam.ppm ; xv qcam.ppm - - Is a working c-qcam connected to the port? - grep ^ /proc/parport/?/autoprobe - - Do the /dev/video* files exist? - ls -lad /dev/video - - Is the c-qcam module loaded? - modprobe -v c-qcam ; lsmod - - Does the camera work with alternate programs? cqcam, etc? - - - - -4.0 Future Work / current workarounds - - It is hoped that this section will soon become obsolete, but if it -isn't, you might try patching the c-qcam module to add a parport=xxx -option as in the bw-qcam module so you can specify the parallel port: - - insmod -v c-qcam parport=0 - -And bypass the detection code, see ../../drivers/char/c-qcam.c and -look for the 'qc_detect' code and call. - - Note that there is work in progress to change the video4linux API, -this work is documented at the video4linux2 site listed below. - - -9.0 --- A sample program using v4lgrabber, - -v4lgrab is a simple image grabber that will copy a frame from the -first video device, /dev/video0 to standard output in portable pixmap -format (.ppm) To produce .jpg output, you can use it like this: -'v4lgrab | convert - c-qcam.jpg' - - -10.0 --- Other Information - -Use the ../../Maintainers file, particularly the VIDEO FOR LINUX and PARALLEL -PORT SUPPORT sections - -The video4linux page: - http://linuxtv.org - -The V4L2 API spec: - http://v4l2spec.bytesex.org/ - -Some web pages about the quickcams: - http://www.pingouin-land.com/howto/QuickCam-HOWTO.html - - http://www.crynwr.com/qcpc/ QuickCam Third-Party Drivers - http://www.crynwr.com/qcpc/re.html Some Reverse Engineering - http://www.wirelesscouch.net/software/gqcam/ v4l client - http://phobos.illtel.denver.co.us/pub/qcread/ doesn't use v4l - ftp://ftp.cs.unm.edu/pub/chris/quickcam/ Has lots of drivers - http://www.cs.duke.edu/~reynolds/quickcam/ Has lots of information - - diff --git a/Documentation/video4linux/README.tlg2300 b/Documentation/video4linux/README.tlg2300 deleted file mode 100644 index 416ccb93d8c9..000000000000 --- a/Documentation/video4linux/README.tlg2300 +++ /dev/null @@ -1,47 +0,0 @@ -tlg2300 release notes -==================== - -This is a v4l2/dvb device driver for the tlg2300 chip. - - -current status -============== - -video - - support mmap and read().(no overlay) - -audio - - The driver will register a ALSA card for the audio input. - -vbi - - Works for almost TV norms. - -dvb-t - - works for DVB-T - -FM - - Works for radio. - ---------------------------------------------------------------------------- -TESTED APPLICATIONS: - --VLC1.0.4 test the video and dvb. The GUI is friendly to use. - --Mplayer test the video. - --Mplayer test the FM. The mplayer should be compiled with --enable-radio and - --enable-radio-capture. - The command runs as this(The alsa audio registers to card 1): - #mplayer radio://103.7/capture/ -radio adevice=hw=1,0:arate=48000 \ - -rawaudio rate=48000:channels=2 - ---------------------------------------------------------------------------- -KNOWN PROBLEMS: -about preemphasis: - You can set the preemphasis for radio by the following command: - #v4l2-ctl -d /dev/radio0 --set-ctrl=pre_emphasis_settings=1 - - "pre_emphasis_settings=1" means that you select the 50us. If you want - to select the 75us, please use "pre_emphasis_settings=2" - - diff --git a/Documentation/video4linux/soc-camera.txt b/Documentation/video4linux/soc-camera.txt index daa9e2ac162c..84f41cf1f3e8 100644 --- a/Documentation/video4linux/soc-camera.txt +++ b/Documentation/video4linux/soc-camera.txt @@ -151,7 +151,7 @@ they are transferred over a media bus. Soc-camera provides support to conveniently manage these formats. A table of standard transformations is maintained by soc-camera core, which describes, what FOURCC pixel format will be obtained, if a media-bus pixel format is stored in memory according to -certain rules. E.g. if V4L2_MBUS_FMT_YUYV8_2X8 data is sampled with 8 bits per +certain rules. E.g. if MEDIA_BUS_FMT_YUYV8_2X8 data is sampled with 8 bits per sample and stored in memory in the little-endian order with no gaps between bytes, data in memory will represent the V4L2_PIX_FMT_YUYV FOURCC format. These standard transformations will be used by soc-camera or by camera host drivers to diff --git a/Documentation/video4linux/v4l2-framework.txt b/Documentation/video4linux/v4l2-framework.txt index a11dff07ef71..f586e29ce221 100644 --- a/Documentation/video4linux/v4l2-framework.txt +++ b/Documentation/video4linux/v4l2-framework.txt @@ -793,8 +793,10 @@ video_register_device_no_warn() instead. Whenever a device node is created some attributes are also created for you. If you look in /sys/class/video4linux you see the devices. Go into e.g. -video0 and you will see 'name' and 'index' attributes. The 'name' attribute -is the 'name' field of the video_device struct. +video0 and you will see 'name', 'debug' and 'index' attributes. The 'name' +attribute is the 'name' field of the video_device struct. The 'debug' attribute +can be used to enable core debugging. See the next section for more detailed +information on this. The 'index' attribute is the index of the device node: for each call to video_register_device() the index is just increased by 1. The first video @@ -816,6 +818,25 @@ video_device was embedded in it. The vdev->release() callback will never be called if the registration failed, nor should you ever attempt to unregister the device if the registration failed. +video device debugging +---------------------- + +The 'debug' attribute that is created for each video, vbi, radio or swradio +device in /sys/class/video4linux/<devX>/ allows you to enable logging of +file operations. + +It is a bitmask and the following bits can be set: + +0x01: Log the ioctl name and error code. VIDIOC_(D)QBUF ioctls are only logged + if bit 0x08 is also set. +0x02: Log the ioctl name arguments and error code. VIDIOC_(D)QBUF ioctls are + only logged if bit 0x08 is also set. +0x04: Log the file operations open, release, read, write, mmap and + get_unmapped_area. The read and write operations are only logged if + bit 0x08 is also set. +0x08: Log the read and write file operations and the VIDIOC_QBUF and + VIDIOC_DQBUF ioctls. +0x10: Log the poll file operation. video_device cleanup -------------------- diff --git a/Documentation/video4linux/v4l2-pci-skeleton.c b/Documentation/video4linux/v4l2-pci-skeleton.c index 006721e43b2a..7bd1b975bfd2 100644 --- a/Documentation/video4linux/v4l2-pci-skeleton.c +++ b/Documentation/video4linux/v4l2-pci-skeleton.c @@ -42,7 +42,6 @@ MODULE_DESCRIPTION("V4L2 PCI Skeleton Driver"); MODULE_AUTHOR("Hans Verkuil"); MODULE_LICENSE("GPL v2"); -MODULE_DEVICE_TABLE(pci, skeleton_pci_tbl); /** * struct skeleton - All internal data for one instance of device @@ -95,6 +94,7 @@ static const struct pci_device_id skeleton_pci_tbl[] = { /* { PCI_DEVICE(PCI_VENDOR_ID_, PCI_DEVICE_ID_) }, */ { 0, } }; +MODULE_DEVICE_TABLE(pci, skeleton_pci_tbl); /* * HDTV: this structure has the capabilities of the HDTV receiver. diff --git a/Documentation/video4linux/vivid.txt b/Documentation/video4linux/vivid.txt index e5a940e3d304..6cfc8541a362 100644 --- a/Documentation/video4linux/vivid.txt +++ b/Documentation/video4linux/vivid.txt @@ -640,6 +640,21 @@ Colorspace: selects which colorspace should be used when generating the image. Changing the colorspace will result in the V4L2_EVENT_SOURCE_CHANGE to be sent since it emulates a detected colorspace change. +Y'CbCr Encoding: selects which Y'CbCr encoding should be used when generating + a Y'CbCr image. This only applies if the CSC Colorbar test pattern is + selected, and if the format is set to a Y'CbCr format as opposed to an + RGB format. + + Changing the Y'CbCr encoding will result in the V4L2_EVENT_SOURCE_CHANGE + to be sent since it emulates a detected colorspace change. + +Quantization: selects which quantization should be used for the RGB or Y'CbCr + encoding when generating the test pattern. This only applies if the CSC + Colorbar test pattern is selected. + + Changing the quantization will result in the V4L2_EVENT_SOURCE_CHANGE + to be sent since it emulates a detected colorspace change. + Limited RGB Range (16-235): selects if the RGB range of the HDMI source should be limited or full range. This combines with the Digital Video 'Rx RGB Quantization Range' control and can be used to test what happens if diff --git a/Documentation/video4linux/w9966.txt b/Documentation/video4linux/w9966.txt deleted file mode 100644 index 855024525fd2..000000000000 --- a/Documentation/video4linux/w9966.txt +++ /dev/null @@ -1,33 +0,0 @@ -W9966 Camera driver, written by Jakob Kemi (jakob.kemi@telia.com) - -After a lot of work in softice & wdasm, reading .pdf-files and tiresome -trial-and-error work I've finally got everything to work. I needed vision for a -robotics project so I borrowed this camera from a friend and started hacking. -Anyway I've converted my original code from the AVR 8bit RISC C/ASM code into -a working Linux driver. - -To get it working simply configure your kernel to support -parport, ieee1284, video4linux and w9966 - -If w9966 is statically linked it will always perform aggressive probing for -the camera. If built as a module you'll have more configuration options. - -Options: - modprobe w9966.o pardev=parport0(or whatever) parmode=0 (0=auto, 1=ecp, 2=epp) -voila! - -you can also type 'modinfo -p w9966.o' for option usage -(or checkout w9966.c) - -The only thing to keep in mind is that the image format is in Y-U-Y-V format -where every two pixels take 4 bytes. In SDL (www.libsdl.org) this format -is called VIDEO_PALETTE_YUV422 (16 bpp). - -A minimal test application (with source) is available from: - http://www.slackwaresupport.com/howtos/Webcam-HOWTO - -The slow framerate is due to missing DMA ECP read support in the -parport drivers. I might add working EPP support later. - -Good luck! - /Jakob Kemi diff --git a/Documentation/virtual/kvm/api.txt b/Documentation/virtual/kvm/api.txt index 7610eaa4d491..b112efc816f1 100644 --- a/Documentation/virtual/kvm/api.txt +++ b/Documentation/virtual/kvm/api.txt @@ -68,9 +68,12 @@ description: Capability: which KVM extension provides this ioctl. Can be 'basic', which means that is will be provided by any kernel that supports - API version 12 (see section 4.1), or a KVM_CAP_xyz constant, which + API version 12 (see section 4.1), a KVM_CAP_xyz constant, which means availability needs to be checked with KVM_CHECK_EXTENSION - (see section 4.4). + (see section 4.4), or 'none' which means that while not all kernels + support this ioctl, there's no capability bit to check its + availability: for kernels that don't support the ioctl, + the ioctl returns -ENOTTY. Architectures: which instruction set architectures provide this ioctl. x86 includes both i386 and x86_64. @@ -604,16 +607,19 @@ struct kvm_fpu { 4.24 KVM_CREATE_IRQCHIP Capability: KVM_CAP_IRQCHIP, KVM_CAP_S390_IRQCHIP (s390) -Architectures: x86, ia64, ARM, arm64, s390 +Architectures: x86, ARM, arm64, s390 Type: vm ioctl Parameters: none Returns: 0 on success, -1 on error -Creates an interrupt controller model in the kernel. On x86, creates a virtual -ioapic, a virtual PIC (two PICs, nested), and sets up future vcpus to have a -local APIC. IRQ routing for GSIs 0-15 is set to both PIC and IOAPIC; GSI 16-23 -only go to the IOAPIC. On ia64, a IOSAPIC is created. On ARM/arm64, a GIC is -created. On s390, a dummy irq routing table is created. +Creates an interrupt controller model in the kernel. +On x86, creates a virtual ioapic, a virtual PIC (two PICs, nested), and sets up +future vcpus to have a local APIC. IRQ routing for GSIs 0-15 is set to both +PIC and IOAPIC; GSI 16-23 only go to the IOAPIC. +On ARM/arm64, a GICv2 is created. Any other GIC versions require the usage of +KVM_CREATE_DEVICE, which also supports creating a GICv2. Using +KVM_CREATE_DEVICE is preferred over KVM_CREATE_IRQCHIP for GICv2. +On s390, a dummy irq routing table is created. Note that on s390 the KVM_CAP_S390_IRQCHIP vm capability needs to be enabled before KVM_CREATE_IRQCHIP can be used. @@ -622,7 +628,7 @@ before KVM_CREATE_IRQCHIP can be used. 4.25 KVM_IRQ_LINE Capability: KVM_CAP_IRQCHIP -Architectures: x86, ia64, arm, arm64 +Architectures: x86, arm, arm64 Type: vm ioctl Parameters: struct kvm_irq_level Returns: 0 on success, -1 on error @@ -676,7 +682,7 @@ struct kvm_irq_level { 4.26 KVM_GET_IRQCHIP Capability: KVM_CAP_IRQCHIP -Architectures: x86, ia64 +Architectures: x86 Type: vm ioctl Parameters: struct kvm_irqchip (in/out) Returns: 0 on success, -1 on error @@ -698,7 +704,7 @@ struct kvm_irqchip { 4.27 KVM_SET_IRQCHIP Capability: KVM_CAP_IRQCHIP -Architectures: x86, ia64 +Architectures: x86 Type: vm ioctl Parameters: struct kvm_irqchip (in) Returns: 0 on success, -1 on error @@ -991,7 +997,7 @@ for vm-wide capabilities. 4.38 KVM_GET_MP_STATE Capability: KVM_CAP_MP_STATE -Architectures: x86, ia64, s390 +Architectures: x86, s390 Type: vcpu ioctl Parameters: struct kvm_mp_state (out) Returns: 0 on success; -1 on error @@ -1005,16 +1011,15 @@ uniprocessor guests). Possible values are: - - KVM_MP_STATE_RUNNABLE: the vcpu is currently running [x86, ia64] + - KVM_MP_STATE_RUNNABLE: the vcpu is currently running [x86] - KVM_MP_STATE_UNINITIALIZED: the vcpu is an application processor (AP) - which has not yet received an INIT signal [x86, - ia64] + which has not yet received an INIT signal [x86] - KVM_MP_STATE_INIT_RECEIVED: the vcpu has received an INIT signal, and is - now ready for a SIPI [x86, ia64] + now ready for a SIPI [x86] - KVM_MP_STATE_HALTED: the vcpu has executed a HLT instruction and - is waiting for an interrupt [x86, ia64] + is waiting for an interrupt [x86] - KVM_MP_STATE_SIPI_RECEIVED: the vcpu has just received a SIPI (vector - accessible via KVM_GET_VCPU_EVENTS) [x86, ia64] + accessible via KVM_GET_VCPU_EVENTS) [x86] - KVM_MP_STATE_STOPPED: the vcpu is stopped [s390] - KVM_MP_STATE_CHECK_STOP: the vcpu is in a special error state [s390] - KVM_MP_STATE_OPERATING: the vcpu is operating (running or halted) @@ -1022,7 +1027,7 @@ Possible values are: - KVM_MP_STATE_LOAD: the vcpu is in a special load/startup state [s390] -On x86 and ia64, this ioctl is only useful after KVM_CREATE_IRQCHIP. Without an +On x86, this ioctl is only useful after KVM_CREATE_IRQCHIP. Without an in-kernel irqchip, the multiprocessing state must be maintained by userspace on these architectures. @@ -1030,7 +1035,7 @@ these architectures. 4.39 KVM_SET_MP_STATE Capability: KVM_CAP_MP_STATE -Architectures: x86, ia64, s390 +Architectures: x86, s390 Type: vcpu ioctl Parameters: struct kvm_mp_state (in) Returns: 0 on success; -1 on error @@ -1038,7 +1043,7 @@ Returns: 0 on success; -1 on error Sets the vcpu's current "multiprocessing state"; see KVM_GET_MP_STATE for arguments. -On x86 and ia64, this ioctl is only useful after KVM_CREATE_IRQCHIP. Without an +On x86, this ioctl is only useful after KVM_CREATE_IRQCHIP. Without an in-kernel irqchip, the multiprocessing state must be maintained by userspace on these architectures. @@ -1065,7 +1070,7 @@ documentation when it pops into existence). 4.41 KVM_SET_BOOT_CPU_ID Capability: KVM_CAP_SET_BOOT_CPU_ID -Architectures: x86, ia64 +Architectures: x86 Type: vm ioctl Parameters: unsigned long vcpu_id Returns: 0 on success, -1 on error @@ -1257,8 +1262,8 @@ The flags bitmap is defined as: 4.48 KVM_ASSIGN_PCI_DEVICE -Capability: KVM_CAP_DEVICE_ASSIGNMENT -Architectures: x86 ia64 +Capability: none +Architectures: x86 Type: vm ioctl Parameters: struct kvm_assigned_pci_dev (in) Returns: 0 on success, -1 on error @@ -1298,25 +1303,36 @@ Only PCI header type 0 devices with PCI BAR resources are supported by device assignment. The user requesting this ioctl must have read/write access to the PCI sysfs resource files associated with the device. +Errors: + ENOTTY: kernel does not support this ioctl + + Other error conditions may be defined by individual device types or + have their standard meanings. + 4.49 KVM_DEASSIGN_PCI_DEVICE -Capability: KVM_CAP_DEVICE_DEASSIGNMENT -Architectures: x86 ia64 +Capability: none +Architectures: x86 Type: vm ioctl Parameters: struct kvm_assigned_pci_dev (in) Returns: 0 on success, -1 on error Ends PCI device assignment, releasing all associated resources. -See KVM_CAP_DEVICE_ASSIGNMENT for the data structure. Only assigned_dev_id is +See KVM_ASSIGN_PCI_DEVICE for the data structure. Only assigned_dev_id is used in kvm_assigned_pci_dev to identify the device. +Errors: + ENOTTY: kernel does not support this ioctl + + Other error conditions may be defined by individual device types or + have their standard meanings. 4.50 KVM_ASSIGN_DEV_IRQ Capability: KVM_CAP_ASSIGN_DEV_IRQ -Architectures: x86 ia64 +Architectures: x86 Type: vm ioctl Parameters: struct kvm_assigned_irq (in) Returns: 0 on success, -1 on error @@ -1346,11 +1362,17 @@ The following flags are defined: It is not valid to specify multiple types per host or guest IRQ. However, the IRQ type of host and guest can differ or can even be null. +Errors: + ENOTTY: kernel does not support this ioctl + + Other error conditions may be defined by individual device types or + have their standard meanings. + 4.51 KVM_DEASSIGN_DEV_IRQ Capability: KVM_CAP_ASSIGN_DEV_IRQ -Architectures: x86 ia64 +Architectures: x86 Type: vm ioctl Parameters: struct kvm_assigned_irq (in) Returns: 0 on success, -1 on error @@ -1365,7 +1387,7 @@ KVM_ASSIGN_DEV_IRQ. Partial deassignment of host or guest IRQ is allowed. 4.52 KVM_SET_GSI_ROUTING Capability: KVM_CAP_IRQ_ROUTING -Architectures: x86 ia64 s390 +Architectures: x86 s390 Type: vm ioctl Parameters: struct kvm_irq_routing (in) Returns: 0 on success, -1 on error @@ -1423,8 +1445,8 @@ struct kvm_irq_routing_s390_adapter { 4.53 KVM_ASSIGN_SET_MSIX_NR -Capability: KVM_CAP_DEVICE_MSIX -Architectures: x86 ia64 +Capability: none +Architectures: x86 Type: vm ioctl Parameters: struct kvm_assigned_msix_nr (in) Returns: 0 on success, -1 on error @@ -1445,8 +1467,8 @@ struct kvm_assigned_msix_nr { 4.54 KVM_ASSIGN_SET_MSIX_ENTRY -Capability: KVM_CAP_DEVICE_MSIX -Architectures: x86 ia64 +Capability: none +Architectures: x86 Type: vm ioctl Parameters: struct kvm_assigned_msix_entry (in) Returns: 0 on success, -1 on error @@ -1461,6 +1483,12 @@ struct kvm_assigned_msix_entry { __u16 padding[3]; }; +Errors: + ENOTTY: kernel does not support this ioctl + + Other error conditions may be defined by individual device types or + have their standard meanings. + 4.55 KVM_SET_TSC_KHZ @@ -2287,7 +2315,7 @@ struct kvm_s390_interrupt { type can be one of the following: -KVM_S390_SIGP_STOP (vcpu) - sigp restart +KVM_S390_SIGP_STOP (vcpu) - sigp stop; optional flags in parm KVM_S390_PROGRAM_INT (vcpu) - program check; code in parm KVM_S390_SIGP_SET_PREFIX (vcpu) - sigp set prefix; prefix address in parm KVM_S390_RESTART (vcpu) - restart @@ -2453,9 +2481,15 @@ return ENOEXEC for that vcpu. Note that because some registers reflect machine topology, all vcpus should be created before this ioctl is invoked. +Userspace can call this function multiple times for a given vcpu, including +after the vcpu has been run. This will reset the vcpu to its initial +state. All calls to this function after the initial call must use the same +target and same set of feature flags, otherwise EINVAL will be returned. + Possible features: - KVM_ARM_VCPU_POWER_OFF: Starts the CPU in a power-off state. - Depends on KVM_CAP_ARM_PSCI. + Depends on KVM_CAP_ARM_PSCI. If not set, the CPU will be powered on + and execute guest code when KVM_RUN is called. - KVM_ARM_VCPU_EL1_32BIT: Starts the CPU in a 32bit mode. Depends on KVM_CAP_ARM_EL1_32BIT (arm64 only). - KVM_ARM_VCPU_PSCI_0_2: Emulate PSCI v0.2 for the CPU. @@ -2951,6 +2985,15 @@ HVC instruction based PSCI call from the vcpu. The 'type' field describes the system-level event type. The 'flags' field describes architecture specific flags for the system-level event. +Valid values for 'type' are: + KVM_SYSTEM_EVENT_SHUTDOWN -- the guest has requested a shutdown of the + VM. Userspace is not obliged to honour this, and if it does honour + this does not need to destroy the VM synchronously (ie it may call + KVM_RUN again before shutdown finally occurs). + KVM_SYSTEM_EVENT_RESET -- the guest has requested a reset of the VM. + As with SHUTDOWN, userspace can choose to ignore the request, or + to schedule the reset to occur in the future and may call KVM_RUN again. + /* Fix the size of the union. */ char padding[256]; }; @@ -3185,3 +3228,23 @@ userspace from doing that. If the hcall number specified is not one that has an in-kernel implementation, the KVM_ENABLE_CAP ioctl will fail with an EINVAL error. + +7.2 KVM_CAP_S390_USER_SIGP + +Architectures: s390 +Parameters: none + +This capability controls which SIGP orders will be handled completely in user +space. With this capability enabled, all fast orders will be handled completely +in the kernel: +- SENSE +- SENSE RUNNING +- EXTERNAL CALL +- EMERGENCY SIGNAL +- CONDITIONAL EMERGENCY SIGNAL + +All other orders will be handled completely in user space. + +Only privileged operation exceptions will be checked for in the kernel (or even +in the hardware prior to interception). If this capability is not enabled, the +old way of handling SIGP orders is used (partially in kernel and user space). diff --git a/Documentation/virtual/kvm/devices/arm-vgic.txt b/Documentation/virtual/kvm/devices/arm-vgic.txt index df8b0c7540b6..3fb905429e8a 100644 --- a/Documentation/virtual/kvm/devices/arm-vgic.txt +++ b/Documentation/virtual/kvm/devices/arm-vgic.txt @@ -3,22 +3,42 @@ ARM Virtual Generic Interrupt Controller (VGIC) Device types supported: KVM_DEV_TYPE_ARM_VGIC_V2 ARM Generic Interrupt Controller v2.0 + KVM_DEV_TYPE_ARM_VGIC_V3 ARM Generic Interrupt Controller v3.0 Only one VGIC instance may be instantiated through either this API or the legacy KVM_CREATE_IRQCHIP api. The created VGIC will act as the VM interrupt controller, requiring emulated user-space devices to inject interrupts to the VGIC instead of directly to CPUs. +Creating a guest GICv3 device requires a host GICv3 as well. +GICv3 implementations with hardware compatibility support allow a guest GICv2 +as well. + Groups: KVM_DEV_ARM_VGIC_GRP_ADDR Attributes: KVM_VGIC_V2_ADDR_TYPE_DIST (rw, 64-bit) Base address in the guest physical address space of the GIC distributor - register mappings. + register mappings. Only valid for KVM_DEV_TYPE_ARM_VGIC_V2. + This address needs to be 4K aligned and the region covers 4 KByte. KVM_VGIC_V2_ADDR_TYPE_CPU (rw, 64-bit) Base address in the guest physical address space of the GIC virtual cpu - interface register mappings. + interface register mappings. Only valid for KVM_DEV_TYPE_ARM_VGIC_V2. + This address needs to be 4K aligned and the region covers 4 KByte. + + KVM_VGIC_V3_ADDR_TYPE_DIST (rw, 64-bit) + Base address in the guest physical address space of the GICv3 distributor + register mappings. Only valid for KVM_DEV_TYPE_ARM_VGIC_V3. + This address needs to be 64K aligned and the region covers 64 KByte. + + KVM_VGIC_V3_ADDR_TYPE_REDIST (rw, 64-bit) + Base address in the guest physical address space of the GICv3 + redistributor register mappings. There are two 64K pages for each + VCPU and all of the redistributor pages are contiguous. + Only valid for KVM_DEV_TYPE_ARM_VGIC_V3. + This address needs to be 64K aligned. + KVM_DEV_ARM_VGIC_GRP_DIST_REGS Attributes: @@ -36,6 +56,7 @@ Groups: the register. Limitations: - Priorities are not implemented, and registers are RAZ/WI + - Currently only implemented for KVM_DEV_TYPE_ARM_VGIC_V2. Errors: -ENODEV: Getting or setting this register is not yet supported -EBUSY: One or more VCPUs are running @@ -68,6 +89,7 @@ Groups: Limitations: - Priorities are not implemented, and registers are RAZ/WI + - Currently only implemented for KVM_DEV_TYPE_ARM_VGIC_V2. Errors: -ENODEV: Getting or setting this register is not yet supported -EBUSY: One or more VCPUs are running @@ -81,3 +103,14 @@ Groups: -EINVAL: Value set is out of the expected range -EBUSY: Value has already be set, or GIC has already been initialized with default values. + + KVM_DEV_ARM_VGIC_GRP_CTRL + Attributes: + KVM_DEV_ARM_VGIC_CTRL_INIT + request the initialization of the VGIC, no additional parameter in + kvm_device_attr.addr. + Errors: + -ENXIO: VGIC not properly configured as required prior to calling + this attribute + -ENODEV: no online VCPU + -ENOMEM: memory shortage when allocating vgic internal data diff --git a/Documentation/virtual/kvm/devices/vm.txt b/Documentation/virtual/kvm/devices/vm.txt index 0d16f96c0eac..5542c4641a3c 100644 --- a/Documentation/virtual/kvm/devices/vm.txt +++ b/Documentation/virtual/kvm/devices/vm.txt @@ -12,15 +12,74 @@ specific. 1. GROUP: KVM_S390_VM_MEM_CTRL Architectures: s390 -1.1. ATTRIBUTE: KVM_S390_VM_MEM_CTRL +1.1. ATTRIBUTE: KVM_S390_VM_MEM_ENABLE_CMMA Parameters: none -Returns: -EBUSY if already a vcpus is defined, otherwise 0 +Returns: -EBUSY if a vcpu is already defined, otherwise 0 -Enables CMMA for the virtual machine +Enables Collaborative Memory Management Assist (CMMA) for the virtual machine. -1.2. ATTRIBUTE: KVM_S390_VM_CLR_CMMA -Parameteres: none +1.2. ATTRIBUTE: KVM_S390_VM_MEM_CLR_CMMA +Parameters: none Returns: 0 Clear the CMMA status for all guest pages, so any pages the guest marked as unused are again used any may not be reclaimed by the host. + +1.3. ATTRIBUTE KVM_S390_VM_MEM_LIMIT_SIZE +Parameters: in attr->addr the address for the new limit of guest memory +Returns: -EFAULT if the given address is not accessible + -EINVAL if the virtual machine is of type UCONTROL + -E2BIG if the given guest memory is to big for that machine + -EBUSY if a vcpu is already defined + -ENOMEM if not enough memory is available for a new shadow guest mapping + 0 otherwise + +Allows userspace to query the actual limit and set a new limit for +the maximum guest memory size. The limit will be rounded up to +2048 MB, 4096 GB, 8192 TB respectively, as this limit is governed by +the number of page table levels. + +2. GROUP: KVM_S390_VM_CPU_MODEL +Architectures: s390 + +2.1. ATTRIBUTE: KVM_S390_VM_CPU_MACHINE (r/o) + +Allows user space to retrieve machine and kvm specific cpu related information: + +struct kvm_s390_vm_cpu_machine { + __u64 cpuid; # CPUID of host + __u32 ibc; # IBC level range offered by host + __u8 pad[4]; + __u64 fac_mask[256]; # set of cpu facilities enabled by KVM + __u64 fac_list[256]; # set of cpu facilities offered by host +} + +Parameters: address of buffer to store the machine related cpu data + of type struct kvm_s390_vm_cpu_machine* +Returns: -EFAULT if the given address is not accessible from kernel space + -ENOMEM if not enough memory is available to process the ioctl + 0 in case of success + +2.2. ATTRIBUTE: KVM_S390_VM_CPU_PROCESSOR (r/w) + +Allows user space to retrieve or request to change cpu related information for a vcpu: + +struct kvm_s390_vm_cpu_processor { + __u64 cpuid; # CPUID currently (to be) used by this vcpu + __u16 ibc; # IBC level currently (to be) used by this vcpu + __u8 pad[6]; + __u64 fac_list[256]; # set of cpu facilities currently (to be) used + # by this vcpu +} + +KVM does not enforce or limit the cpu model data in any form. Take the information +retrieved by means of KVM_S390_VM_CPU_MACHINE as hint for reasonable configuration +setups. Instruction interceptions triggered by additionally set facilitiy bits that +are not handled by KVM need to by imlemented in the VM driver code. + +Parameters: address of buffer to store/set the processor related cpu + data of type struct kvm_s390_vm_cpu_processor*. +Returns: -EBUSY in case 1 or more vcpus are already activated (only in write case) + -EFAULT if the given address is not accessible from kernel space + -ENOMEM if not enough memory is available to process the ioctl + 0 in case of success diff --git a/Documentation/virtual/kvm/msr.txt b/Documentation/virtual/kvm/msr.txt index 6d470ae7b073..2a71c8f29f68 100644 --- a/Documentation/virtual/kvm/msr.txt +++ b/Documentation/virtual/kvm/msr.txt @@ -168,7 +168,7 @@ MSR_KVM_ASYNC_PF_EN: 0x4b564d02 64 byte memory area which must be in guest RAM and must be zeroed. Bits 5-2 are reserved and should be zero. Bit 0 is 1 when asynchronous page faults are enabled on the vcpu 0 when - disabled. Bit 2 is 1 if asynchronous page faults can be injected + disabled. Bit 1 is 1 if asynchronous page faults can be injected when vcpu is in cpl == 0. First 4 byte of 64 byte memory location will be written to by diff --git a/Documentation/vm/cleancache.txt b/Documentation/vm/cleancache.txt index 142fbb0f325a..01d76282444e 100644 --- a/Documentation/vm/cleancache.txt +++ b/Documentation/vm/cleancache.txt @@ -85,7 +85,7 @@ lock the page to ensure serial behavior. CLEANCACHE PERFORMANCE METRICS If properly configured, monitoring of cleancache is done via debugfs in -the /sys/kernel/debug/mm/cleancache directory. The effectiveness of cleancache +the /sys/kernel/debug/cleancache directory. The effectiveness of cleancache can be measured (across all filesystems) with: succ_gets - number of gets that were successful diff --git a/Documentation/vm/hugetlbpage.txt b/Documentation/vm/hugetlbpage.txt index b64e0af9cc56..f2d3a100fe38 100644 --- a/Documentation/vm/hugetlbpage.txt +++ b/Documentation/vm/hugetlbpage.txt @@ -1,8 +1,8 @@ The intent of this file is to give a brief summary of hugetlbpage support in the Linux kernel. This support is built on top of multiple page size support -that is provided by most modern architectures. For example, i386 -architecture supports 4K and 4M (2M in PAE mode) page sizes, ia64 +that is provided by most modern architectures. For example, x86 CPUs normally +support 4K and 2M (1G if architecturally supported) page sizes, ia64 architecture supports multiple page sizes 4K, 8K, 64K, 256K, 1M, 4M, 16M, 256M and ppc64 supports 4K and 16M. A TLB is a cache of virtual-to-physical translations. Typically this is a very scarce resource on processor. diff --git a/Documentation/vm/page_owner.txt b/Documentation/vm/page_owner.txt new file mode 100644 index 000000000000..8f3ce9b3aa11 --- /dev/null +++ b/Documentation/vm/page_owner.txt @@ -0,0 +1,81 @@ +page owner: Tracking about who allocated each page +----------------------------------------------------------- + +* Introduction + +page owner is for the tracking about who allocated each page. +It can be used to debug memory leak or to find a memory hogger. +When allocation happens, information about allocation such as call stack +and order of pages is stored into certain storage for each page. +When we need to know about status of all pages, we can get and analyze +this information. + +Although we already have tracepoint for tracing page allocation/free, +using it for analyzing who allocate each page is rather complex. We need +to enlarge the trace buffer for preventing overlapping until userspace +program launched. And, launched program continually dump out the trace +buffer for later analysis and it would change system behviour with more +possibility rather than just keeping it in memory, so bad for debugging. + +page owner can also be used for various purposes. For example, accurate +fragmentation statistics can be obtained through gfp flag information of +each page. It is already implemented and activated if page owner is +enabled. Other usages are more than welcome. + +page owner is disabled in default. So, if you'd like to use it, you need +to add "page_owner=on" into your boot cmdline. If the kernel is built +with page owner and page owner is disabled in runtime due to no enabling +boot option, runtime overhead is marginal. If disabled in runtime, it +doesn't require memory to store owner information, so there is no runtime +memory overhead. And, page owner inserts just two unlikely branches into +the page allocator hotpath and if it returns false then allocation is +done like as the kernel without page owner. These two unlikely branches +would not affect to allocation performance. Following is the kernel's +code size change due to this facility. + +- Without page owner + text data bss dec hex filename + 40662 1493 644 42799 a72f mm/page_alloc.o + +- With page owner + text data bss dec hex filename + 40892 1493 644 43029 a815 mm/page_alloc.o + 1427 24 8 1459 5b3 mm/page_ext.o + 2722 50 0 2772 ad4 mm/page_owner.o + +Although, roughly, 4 KB code is added in total, page_alloc.o increase by +230 bytes and only half of it is in hotpath. Building the kernel with +page owner and turning it on if needed would be great option to debug +kernel memory problem. + +There is one notice that is caused by implementation detail. page owner +stores information into the memory from struct page extension. This memory +is initialized some time later than that page allocator starts in sparse +memory system, so, until initialization, many pages can be allocated and +they would have no owner information. To fix it up, these early allocated +pages are investigated and marked as allocated in initialization phase. +Although it doesn't mean that they have the right owner information, +at least, we can tell whether the page is allocated or not, +more accurately. On 2GB memory x86-64 VM box, 13343 early allocated pages +are catched and marked, although they are mostly allocated from struct +page extension feature. Anyway, after that, no page is left in +un-tracking state. + +* Usage + +1) Build user-space helper + cd tools/vm + make page_owner_sort + +2) Enable page owner + Add "page_owner=on" to boot cmdline. + +3) Do the job what you want to debug + +4) Analyze information from page owner + cat /sys/kernel/debug/page_owner > page_owner_full.txt + grep -v ^PFN page_owner_full.txt > page_owner.txt + ./page_owner_sort page_owner.txt sorted_page_owner.txt + + See the result about who allocated each page + in the sorted_page_owner.txt. diff --git a/Documentation/vm/pagemap.txt b/Documentation/vm/pagemap.txt index 5948e455c4d2..6fbd55ef6b45 100644 --- a/Documentation/vm/pagemap.txt +++ b/Documentation/vm/pagemap.txt @@ -62,6 +62,8 @@ There are three components to pagemap: 20. NOPAGE 21. KSM 22. THP + 23. BALLOON + 24. ZERO_PAGE Short descriptions to the page flags: @@ -102,6 +104,12 @@ Short descriptions to the page flags: 22. THP contiguous pages which construct transparent hugepages +23. BALLOON + balloon compaction page + +24. ZERO_PAGE + zero page for pfn_zero or huge_zero page + [IO related page flags] 1. ERROR IO error occurred 3. UPTODATE page has up-to-date data diff --git a/Documentation/vm/remap_file_pages.txt b/Documentation/vm/remap_file_pages.txt index 560e4363a55d..f609142f406a 100644 --- a/Documentation/vm/remap_file_pages.txt +++ b/Documentation/vm/remap_file_pages.txt @@ -18,10 +18,9 @@ on 32-bit systems to map files bigger than can linearly fit into 32-bit virtual address space. This use-case is not critical anymore since 64-bit systems are widely available. -The plan is to deprecate the syscall and replace it with an emulation. -The emulation will create new VMAs instead of nonlinear mappings. It's -going to work slower for rare users of remap_file_pages() but ABI is -preserved. +The syscall is deprecated and replaced it with an emulation now. The +emulation creates new VMAs instead of nonlinear mappings. It's going to +work slower for rare users of remap_file_pages() but ABI is preserved. One side effect of emulation (apart from performance) is that user can hit vm.max_map_count limit more easily due to additional VMAs. See comment for diff --git a/Documentation/x86/entry_64.txt b/Documentation/x86/entry_64.txt index bc7226ef5055..9132b86176a3 100644 --- a/Documentation/x86/entry_64.txt +++ b/Documentation/x86/entry_64.txt @@ -7,9 +7,12 @@ http://lkml.kernel.org/r/<20110529191055.GC9835%40elte.hu> The x86 architecture has quite a few different ways to jump into kernel code. Most of these entry points are registered in arch/x86/kernel/traps.c and implemented in arch/x86/kernel/entry_64.S -and arch/x86/ia32/ia32entry.S. +for 64-bit, arch/x86/kernel/entry_32.S for 32-bit and finally +arch/x86/ia32/ia32entry.S which implements the 32-bit compatibility +syscall entry points and thus provides for 32-bit processes the +ability to execute syscalls when running on 64-bit kernels. -The IDT vector assignments are listed in arch/x86/include/irq_vectors.h. +The IDT vector assignments are listed in arch/x86/include/asm/irq_vectors.h. Some of these entries are: @@ -75,9 +78,6 @@ The expensive (paranoid) way is to read back the MSR_GS_BASE value xorl %ebx,%ebx 1: ret -and the whole paranoid non-paranoid macro complexity is about whether -to suffer that RDMSR cost. - If we are at an interrupt or user-trap/gate-alike boundary then we can use the faster check: the stack will be a reliable indicator of whether SWAPGS was already done: if we see that we are a secondary @@ -90,6 +90,15 @@ which might have triggered right after a normal entry wrote CS to the stack but before we executed SWAPGS, then the only safe way to check for GS is the slower method: the RDMSR. -So we try only to mark those entry methods 'paranoid' that absolutely -need the more expensive check for the GS base - and we generate all -'normal' entry points with the regular (faster) entry macros. +Therefore, super-atomic entries (except NMI, which is handled separately) +must use idtentry with paranoid=1 to handle gsbase correctly. This +triggers three main behavior changes: + + - Interrupt entry will use the slower gsbase check. + - Interrupt entry from user mode will switch off the IST stack. + - Interrupt exit to kernel mode will not attempt to reschedule. + +We try to only use IST entries and the paranoid entry code for vectors +that absolutely need the more expensive check for the GS base - and we +generate all 'normal' entry points with the regular (faster) paranoid=0 +variant. diff --git a/Documentation/x86/intel_mpx.txt b/Documentation/x86/intel_mpx.txt new file mode 100644 index 000000000000..818518a3ff01 --- /dev/null +++ b/Documentation/x86/intel_mpx.txt @@ -0,0 +1,244 @@ +1. Intel(R) MPX Overview +======================== + +Intel(R) Memory Protection Extensions (Intel(R) MPX) is a new capability +introduced into Intel Architecture. Intel MPX provides hardware features +that can be used in conjunction with compiler changes to check memory +references, for those references whose compile-time normal intentions are +usurped at runtime due to buffer overflow or underflow. + +You can tell if your CPU supports MPX by looking in /proc/cpuinfo: + + cat /proc/cpuinfo | grep ' mpx ' + +For more information, please refer to Intel(R) Architecture Instruction +Set Extensions Programming Reference, Chapter 9: Intel(R) Memory Protection +Extensions. + +Note: As of December 2014, no hardware with MPX is available but it is +possible to use SDE (Intel(R) Software Development Emulator) instead, which +can be downloaded from +http://software.intel.com/en-us/articles/intel-software-development-emulator + + +2. How to get the advantage of MPX +================================== + +For MPX to work, changes are required in the kernel, binutils and compiler. +No source changes are required for applications, just a recompile. + +There are a lot of moving parts of this to all work right. The following +is how we expect the compiler, application and kernel to work together. + +1) Application developer compiles with -fmpx. The compiler will add the + instrumentation as well as some setup code called early after the app + starts. New instruction prefixes are noops for old CPUs. +2) That setup code allocates (virtual) space for the "bounds directory", + points the "bndcfgu" register to the directory (must also set the valid + bit) and notifies the kernel (via the new prctl(PR_MPX_ENABLE_MANAGEMENT)) + that the app will be using MPX. The app must be careful not to access + the bounds tables between the time when it populates "bndcfgu" and + when it calls the prctl(). This might be hard to guarantee if the app + is compiled with MPX. You can add "__attribute__((bnd_legacy))" to + the function to disable MPX instrumentation to help guarantee this. + Also be careful not to call out to any other code which might be + MPX-instrumented. +3) The kernel detects that the CPU has MPX, allows the new prctl() to + succeed, and notes the location of the bounds directory. Userspace is + expected to keep the bounds directory at that locationWe note it + instead of reading it each time because the 'xsave' operation needed + to access the bounds directory register is an expensive operation. +4) If the application needs to spill bounds out of the 4 registers, it + issues a bndstx instruction. Since the bounds directory is empty at + this point, a bounds fault (#BR) is raised, the kernel allocates a + bounds table (in the user address space) and makes the relevant entry + in the bounds directory point to the new table. +5) If the application violates the bounds specified in the bounds registers, + a separate kind of #BR is raised which will deliver a signal with + information about the violation in the 'struct siginfo'. +6) Whenever memory is freed, we know that it can no longer contain valid + pointers, and we attempt to free the associated space in the bounds + tables. If an entire table becomes unused, we will attempt to free + the table and remove the entry in the directory. + +To summarize, there are essentially three things interacting here: + +GCC with -fmpx: + * enables annotation of code with MPX instructions and prefixes + * inserts code early in the application to call in to the "gcc runtime" +GCC MPX Runtime: + * Checks for hardware MPX support in cpuid leaf + * allocates virtual space for the bounds directory (malloc() essentially) + * points the hardware BNDCFGU register at the directory + * calls a new prctl(PR_MPX_ENABLE_MANAGEMENT) to notify the kernel to + start managing the bounds directories +Kernel MPX Code: + * Checks for hardware MPX support in cpuid leaf + * Handles #BR exceptions and sends SIGSEGV to the app when it violates + bounds, like during a buffer overflow. + * When bounds are spilled in to an unallocated bounds table, the kernel + notices in the #BR exception, allocates the virtual space, then + updates the bounds directory to point to the new table. It keeps + special track of the memory with a VM_MPX flag. + * Frees unused bounds tables at the time that the memory they described + is unmapped. + + +3. How does MPX kernel code work +================================ + +Handling #BR faults caused by MPX +--------------------------------- + +When MPX is enabled, there are 2 new situations that can generate +#BR faults. + * new bounds tables (BT) need to be allocated to save bounds. + * bounds violation caused by MPX instructions. + +We hook #BR handler to handle these two new situations. + +On-demand kernel allocation of bounds tables +-------------------------------------------- + +MPX only has 4 hardware registers for storing bounds information. If +MPX-enabled code needs more than these 4 registers, it needs to spill +them somewhere. It has two special instructions for this which allow +the bounds to be moved between the bounds registers and some new "bounds +tables". + +#BR exceptions are a new class of exceptions just for MPX. They are +similar conceptually to a page fault and will be raised by the MPX +hardware during both bounds violations or when the tables are not +present. The kernel handles those #BR exceptions for not-present tables +by carving the space out of the normal processes address space and then +pointing the bounds-directory over to it. + +The tables need to be accessed and controlled by userspace because +the instructions for moving bounds in and out of them are extremely +frequent. They potentially happen every time a register points to +memory. Any direct kernel involvement (like a syscall) to access the +tables would obviously destroy performance. + +Why not do this in userspace? MPX does not strictly require anything in +the kernel. It can theoretically be done completely from userspace. Here +are a few ways this could be done. We don't think any of them are practical +in the real-world, but here they are. + +Q: Can virtual space simply be reserved for the bounds tables so that we + never have to allocate them? +A: MPX-enabled application will possibly create a lot of bounds tables in + process address space to save bounds information. These tables can take + up huge swaths of memory (as much as 80% of the memory on the system) + even if we clean them up aggressively. In the worst-case scenario, the + tables can be 4x the size of the data structure being tracked. IOW, a + 1-page structure can require 4 bounds-table pages. An X-GB virtual + area needs 4*X GB of virtual space, plus 2GB for the bounds directory. + If we were to preallocate them for the 128TB of user virtual address + space, we would need to reserve 512TB+2GB, which is larger than the + entire virtual address space today. This means they can not be reserved + ahead of time. Also, a single process's pre-popualated bounds directory + consumes 2GB of virtual *AND* physical memory. IOW, it's completely + infeasible to prepopulate bounds directories. + +Q: Can we preallocate bounds table space at the same time memory is + allocated which might contain pointers that might eventually need + bounds tables? +A: This would work if we could hook the site of each and every memory + allocation syscall. This can be done for small, constrained applications. + But, it isn't practical at a larger scale since a given app has no + way of controlling how all the parts of the app might allocate memory + (think libraries). The kernel is really the only place to intercept + these calls. + +Q: Could a bounds fault be handed to userspace and the tables allocated + there in a signal handler intead of in the kernel? +A: mmap() is not on the list of safe async handler functions and even + if mmap() would work it still requires locking or nasty tricks to + keep track of the allocation state there. + +Having ruled out all of the userspace-only approaches for managing +bounds tables that we could think of, we create them on demand in +the kernel. + +Decoding MPX instructions +------------------------- + +If a #BR is generated due to a bounds violation caused by MPX. +We need to decode MPX instructions to get violation address and +set this address into extended struct siginfo. + +The _sigfault feild of struct siginfo is extended as follow: + +87 /* SIGILL, SIGFPE, SIGSEGV, SIGBUS */ +88 struct { +89 void __user *_addr; /* faulting insn/memory ref. */ +90 #ifdef __ARCH_SI_TRAPNO +91 int _trapno; /* TRAP # which caused the signal */ +92 #endif +93 short _addr_lsb; /* LSB of the reported address */ +94 struct { +95 void __user *_lower; +96 void __user *_upper; +97 } _addr_bnd; +98 } _sigfault; + +The '_addr' field refers to violation address, and new '_addr_and' +field refers to the upper/lower bounds when a #BR is caused. + +Glibc will be also updated to support this new siginfo. So user +can get violation address and bounds when bounds violations occur. + +Cleanup unused bounds tables +---------------------------- + +When a BNDSTX instruction attempts to save bounds to a bounds directory +entry marked as invalid, a #BR is generated. This is an indication that +no bounds table exists for this entry. In this case the fault handler +will allocate a new bounds table on demand. + +Since the kernel allocated those tables on-demand without userspace +knowledge, it is also responsible for freeing them when the associated +mappings go away. + +Here, the solution for this issue is to hook do_munmap() to check +whether one process is MPX enabled. If yes, those bounds tables covered +in the virtual address region which is being unmapped will be freed also. + +Adding new prctl commands +------------------------- + +Two new prctl commands are added to enable and disable MPX bounds tables +management in kernel. + +155 #define PR_MPX_ENABLE_MANAGEMENT 43 +156 #define PR_MPX_DISABLE_MANAGEMENT 44 + +Runtime library in userspace is responsible for allocation of bounds +directory. So kernel have to use XSAVE instruction to get the base +of bounds directory from BNDCFG register. + +But XSAVE is expected to be very expensive. In order to do performance +optimization, we have to get the base of bounds directory and save it +into struct mm_struct to be used in future during PR_MPX_ENABLE_MANAGEMENT +command execution. + + +4. Special rules +================ + +1) If userspace is requesting help from the kernel to do the management +of bounds tables, it may not create or modify entries in the bounds directory. + +Certainly users can allocate bounds tables and forcibly point the bounds +directory at them through XSAVE instruction, and then set valid bit +of bounds entry to have this entry valid. But, the kernel will decline +to assist in managing these tables. + +2) Userspace may not take multiple bounds directory entries and point +them at the same bounds table. + +This is allowed architecturally. See more information "Intel(R) Architecture +Instruction Set Extensions Programming Reference" (9.3.4). + +However, if users did this, the kernel might be fooled in to unmaping an +in-use bounds table since it does not recognize sharing. diff --git a/Documentation/x86/x86_64/kernel-stacks b/Documentation/x86/x86_64/kernel-stacks index a01eec5d1d0b..e3c8a49d1a2f 100644 --- a/Documentation/x86/x86_64/kernel-stacks +++ b/Documentation/x86/x86_64/kernel-stacks @@ -40,9 +40,11 @@ An IST is selected by a non-zero value in the IST field of an interrupt-gate descriptor. When an interrupt occurs and the hardware loads such a descriptor, the hardware automatically sets the new stack pointer based on the IST value, then invokes the interrupt handler. If -software wants to allow nested IST interrupts then the handler must -adjust the IST values on entry to and exit from the interrupt handler. -(This is occasionally done, e.g. for debug exceptions.) +the interrupt came from user mode, then the interrupt handler prologue +will switch back to the per-thread stack. If software wants to allow +nested IST interrupts then the handler must adjust the IST values on +entry to and exit from the interrupt handler. (This is occasionally +done, e.g. for debug exceptions.) Events with different IST codes (i.e. with different stacks) can be nested. For example, a debug interrupt can safely be interrupted by an diff --git a/Documentation/x86/x86_64/mm.txt b/Documentation/x86/x86_64/mm.txt index 052ee643a32e..05712ac83e38 100644 --- a/Documentation/x86/x86_64/mm.txt +++ b/Documentation/x86/x86_64/mm.txt @@ -12,6 +12,8 @@ ffffc90000000000 - ffffe8ffffffffff (=45 bits) vmalloc/ioremap space ffffe90000000000 - ffffe9ffffffffff (=40 bits) hole ffffea0000000000 - ffffeaffffffffff (=40 bits) virtual memory map (1TB) ... unused hole ... +ffffec0000000000 - fffffc0000000000 (=44 bits) kasan shadow memory (16TB) +... unused hole ... ffffff0000000000 - ffffff7fffffffff (=39 bits) %esp fixup stacks ... unused hole ... ffffffff80000000 - ffffffffa0000000 (=512 MB) kernel text mapping, from phys 0 |