diff options
Diffstat (limited to 'Documentation')
135 files changed, 6305 insertions, 520 deletions
diff --git a/Documentation/.gitignore b/Documentation/.gitignore new file mode 100644 index 000000000000..e74fec8693b2 --- /dev/null +++ b/Documentation/.gitignore @@ -0,0 +1,2 @@ +output +*.pyc diff --git a/Documentation/00-INDEX b/Documentation/00-INDEX index cd077ca0e1b8..cb9a6c6fa83b 100644 --- a/Documentation/00-INDEX +++ b/Documentation/00-INDEX @@ -255,10 +255,10 @@ kbuild/ - directory with info about the kernel build process. kdump/ - directory with mini HowTo on getting the crash dump code to work. -kernel-doc-nano-HOWTO.txt - - mini HowTo on generation and location of kernel documentation files. kernel-docs.txt - listing of various WWW + books that document kernel internals. +kernel-documentation.rst + - how to write and format reStructuredText kernel documentation kernel-parameters.txt - summary listing of command line / boot prompt args for the kernel. kernel-per-CPU-kthreads.txt diff --git a/Documentation/ABI/testing/configfs-acpi b/Documentation/ABI/testing/configfs-acpi new file mode 100644 index 000000000000..4ab4e99aa863 --- /dev/null +++ b/Documentation/ABI/testing/configfs-acpi @@ -0,0 +1,36 @@ +What: /config/acpi +Date: July 2016 +KernelVersion: 4.8 +Contact: linux-acpi@vger.kernel.org +Description: + This represents the ACPI subsystem entry point directory. It + contains sub-groups corresponding to ACPI configurable options. + +What: /config/acpi/table +Date: July 2016 +KernelVersion: 4.8 +Description: + + This group contains the configuration for user defined ACPI + tables. The attributes of a user define table are: + + aml - a binary attribute that the user can use to + fill in the ACPI aml definitions. Once the aml + data is written to this file and the file is + closed the table will be loaded and ACPI devices + will be enumerated. To check if the operation is + successful the user must check the error code + for close(). If the operation is successful, + subsequent writes to this attribute will fail. + + The rest of the attributes are read-only and are valid only + after the table has been loaded by filling the aml entry: + + signature - ASCII table signature + length - length of table in bytes, including the header + revision - ACPI Specification minor version number + oem_id - ASCII OEM identification + oem_table_id - ASCII OEM table identification + oem_revision - OEM revision number + asl_compiler_id - ASCII ASL compiler vendor ID + asl_compiler_revision - ASL compiler version diff --git a/Documentation/ABI/testing/configfs-iio b/Documentation/ABI/testing/configfs-iio index 2483756fccf5..aebda53ec0f7 100644 --- a/Documentation/ABI/testing/configfs-iio +++ b/Documentation/ABI/testing/configfs-iio @@ -19,3 +19,16 @@ KernelVersion: 4.4 Description: High resolution timers directory. Creating a directory here will result in creating a hrtimer trigger in the IIO subsystem. + +What: /config/iio/devices +Date: April 2016 +KernelVersion: 4.7 +Description: + Industrial IO software devices directory. + +What: /config/iio/devices/dummy +Date: April 2016 +KernelVersion: 4.7 +Description: + Dummy IIO devices directory. Creating a directory here will result + in creating a dummy IIO device in the IIO subystem. diff --git a/Documentation/ABI/testing/configfs-usb-gadget-uvc b/Documentation/ABI/testing/configfs-usb-gadget-uvc index 2f4a0051b32d..1ba0d0fda9c0 100644 --- a/Documentation/ABI/testing/configfs-usb-gadget-uvc +++ b/Documentation/ABI/testing/configfs-usb-gadget-uvc @@ -1,6 +1,6 @@ What: /config/usb-gadget/gadget/functions/uvc.name Date: Dec 2014 -KernelVersion: 3.20 +KernelVersion: 4.0 Description: UVC function directory streaming_maxburst - 0..15 (ss only) @@ -9,37 +9,37 @@ Description: UVC function directory What: /config/usb-gadget/gadget/functions/uvc.name/control Date: Dec 2014 -KernelVersion: 3.20 +KernelVersion: 4.0 Description: Control descriptors What: /config/usb-gadget/gadget/functions/uvc.name/control/class Date: Dec 2014 -KernelVersion: 3.20 +KernelVersion: 4.0 Description: Class descriptors What: /config/usb-gadget/gadget/functions/uvc.name/control/class/ss Date: Dec 2014 -KernelVersion: 3.20 +KernelVersion: 4.0 Description: Super speed control class descriptors What: /config/usb-gadget/gadget/functions/uvc.name/control/class/fs Date: Dec 2014 -KernelVersion: 3.20 +KernelVersion: 4.0 Description: Full speed control class descriptors What: /config/usb-gadget/gadget/functions/uvc.name/control/terminal Date: Dec 2014 -KernelVersion: 3.20 +KernelVersion: 4.0 Description: Terminal descriptors What: /config/usb-gadget/gadget/functions/uvc.name/control/terminal/output Date: Dec 2014 -KernelVersion: 3.20 +KernelVersion: 4.0 Description: Output terminal descriptors What: /config/usb-gadget/gadget/functions/uvc.name/control/terminal/output/default Date: Dec 2014 -KernelVersion: 3.20 +KernelVersion: 4.0 Description: Default output terminal descriptors All attributes read only: @@ -53,12 +53,12 @@ Description: Default output terminal descriptors What: /config/usb-gadget/gadget/functions/uvc.name/control/terminal/camera Date: Dec 2014 -KernelVersion: 3.20 +KernelVersion: 4.0 Description: Camera terminal descriptors What: /config/usb-gadget/gadget/functions/uvc.name/control/terminal/camera/default Date: Dec 2014 -KernelVersion: 3.20 +KernelVersion: 4.0 Description: Default camera terminal descriptors All attributes read only: @@ -75,12 +75,12 @@ Description: Default camera terminal descriptors What: /config/usb-gadget/gadget/functions/uvc.name/control/processing Date: Dec 2014 -KernelVersion: 3.20 +KernelVersion: 4.0 Description: Processing unit descriptors What: /config/usb-gadget/gadget/functions/uvc.name/control/processing/default Date: Dec 2014 -KernelVersion: 3.20 +KernelVersion: 4.0 Description: Default processing unit descriptors All attributes read only: @@ -94,49 +94,49 @@ Description: Default processing unit descriptors What: /config/usb-gadget/gadget/functions/uvc.name/control/header Date: Dec 2014 -KernelVersion: 3.20 +KernelVersion: 4.0 Description: Control header descriptors What: /config/usb-gadget/gadget/functions/uvc.name/control/header/name Date: Dec 2014 -KernelVersion: 3.20 +KernelVersion: 4.0 Description: Specific control header descriptors dwClockFrequency bcdUVC What: /config/usb-gadget/gadget/functions/uvc.name/streaming Date: Dec 2014 -KernelVersion: 3.20 +KernelVersion: 4.0 Description: Streaming descriptors What: /config/usb-gadget/gadget/functions/uvc.name/streaming/class Date: Dec 2014 -KernelVersion: 3.20 +KernelVersion: 4.0 Description: Streaming class descriptors What: /config/usb-gadget/gadget/functions/uvc.name/streaming/class/ss Date: Dec 2014 -KernelVersion: 3.20 +KernelVersion: 4.0 Description: Super speed streaming class descriptors What: /config/usb-gadget/gadget/functions/uvc.name/streaming/class/hs Date: Dec 2014 -KernelVersion: 3.20 +KernelVersion: 4.0 Description: High speed streaming class descriptors What: /config/usb-gadget/gadget/functions/uvc.name/streaming/class/fs Date: Dec 2014 -KernelVersion: 3.20 +KernelVersion: 4.0 Description: Full speed streaming class descriptors What: /config/usb-gadget/gadget/functions/uvc.name/streaming/color_matching Date: Dec 2014 -KernelVersion: 3.20 +KernelVersion: 4.0 Description: Color matching descriptors What: /config/usb-gadget/gadget/functions/uvc.name/streaming/color_matching/default Date: Dec 2014 -KernelVersion: 3.20 +KernelVersion: 4.0 Description: Default color matching descriptors All attributes read only: @@ -150,12 +150,12 @@ Description: Default color matching descriptors What: /config/usb-gadget/gadget/functions/uvc.name/streaming/mjpeg Date: Dec 2014 -KernelVersion: 3.20 +KernelVersion: 4.0 Description: MJPEG format descriptors What: /config/usb-gadget/gadget/functions/uvc.name/streaming/mjpeg/name Date: Dec 2014 -KernelVersion: 3.20 +KernelVersion: 4.0 Description: Specific MJPEG format descriptors All attributes read only, @@ -174,7 +174,7 @@ Description: Specific MJPEG format descriptors What: /config/usb-gadget/gadget/functions/uvc.name/streaming/mjpeg/name/name Date: Dec 2014 -KernelVersion: 3.20 +KernelVersion: 4.0 Description: Specific MJPEG frame descriptors dwFrameInterval - indicates how frame interval can be @@ -196,12 +196,12 @@ Description: Specific MJPEG frame descriptors What: /config/usb-gadget/gadget/functions/uvc.name/streaming/uncompressed Date: Dec 2014 -KernelVersion: 3.20 +KernelVersion: 4.0 Description: Uncompressed format descriptors What: /config/usb-gadget/gadget/functions/uvc.name/streaming/uncompressed/name Date: Dec 2014 -KernelVersion: 3.20 +KernelVersion: 4.0 Description: Specific uncompressed format descriptors bmaControls - this format's data for bmaControls in @@ -221,7 +221,7 @@ Description: Specific uncompressed format descriptors What: /config/usb-gadget/gadget/functions/uvc.name/streaming/uncompressed/name/name Date: Dec 2014 -KernelVersion: 3.20 +KernelVersion: 4.0 Description: Specific uncompressed frame descriptors dwFrameInterval - indicates how frame interval can be @@ -243,12 +243,12 @@ Description: Specific uncompressed frame descriptors What: /config/usb-gadget/gadget/functions/uvc.name/streaming/header Date: Dec 2014 -KernelVersion: 3.20 +KernelVersion: 4.0 Description: Streaming header descriptors What: /config/usb-gadget/gadget/functions/uvc.name/streaming/header/name Date: Dec 2014 -KernelVersion: 3.20 +KernelVersion: 4.0 Description: Specific streaming header descriptors All attributes read only: diff --git a/Documentation/ABI/testing/sysfs-bus-iio b/Documentation/ABI/testing/sysfs-bus-iio index df44998e7506..fee35c00cc4e 100644 --- a/Documentation/ABI/testing/sysfs-bus-iio +++ b/Documentation/ABI/testing/sysfs-bus-iio @@ -32,6 +32,13 @@ Description: Description of the physical chip / device for device X. Typically a part number. +What: /sys/bus/iio/devices/iio:deviceX/timestamp_clock +KernelVersion: 4.5 +Contact: linux-iio@vger.kernel.org +Description: + String identifying current posix clock used to timestamp + buffered samples and events for device X. + What: /sys/bus/iio/devices/iio:deviceX/sampling_frequency What: /sys/bus/iio/devices/iio:deviceX/buffer/sampling_frequency What: /sys/bus/iio/devices/triggerX/sampling_frequency @@ -1565,3 +1572,10 @@ Description: * X is in the plane of the propellers, perpendicular to Y axis, and positive towards the starboard side of the UAV ; * Z is perpendicular to propellers plane and positive upwards. + +What: /sys/bus/iio/devices/iio:deviceX/in_electricalconductivity_raw +KernelVersion: 4.8 +Contact: linux-iio@vger.kernel.org +Description: + Raw (unscaled no offset etc.) electric conductivity reading that + can be processed to siemens per meter. diff --git a/Documentation/ABI/testing/sysfs-bus-iio-health-afe440x b/Documentation/ABI/testing/sysfs-bus-iio-health-afe440x index 3740f253d406..6adba9058b22 100644 --- a/Documentation/ABI/testing/sysfs-bus-iio-health-afe440x +++ b/Documentation/ABI/testing/sysfs-bus-iio-health-afe440x @@ -1,54 +1,41 @@ -What: /sys/bus/iio/devices/iio:deviceX/tia_resistanceY - /sys/bus/iio/devices/iio:deviceX/tia_capacitanceY -Date: December 2015 -KernelVersion: -Contact: Andrew F. Davis <afd@ti.com> -Description: - Get and set the resistance and the capacitance settings for the - Transimpedance Amplifier. Y is 1 for Rf1 and Cf1, Y is 2 for - Rf2 and Cf2 values. - -What: /sys/bus/iio/devices/iio:deviceX/tia_separate_en -Date: December 2015 -KernelVersion: -Contact: Andrew F. Davis <afd@ti.com> -Description: - Enable or disable separate settings for the TransImpedance - Amplifier above, when disabled both values are set by the - first channel. - -What: /sys/bus/iio/devices/iio:deviceX/in_intensity_ledY_raw - /sys/bus/iio/devices/iio:deviceX/in_intensity_ledY_ambient_raw -Date: December 2015 +What: /sys/bus/iio/devices/iio:deviceX/in_intensityY_raw +Date: May 2016 KernelVersion: Contact: Andrew F. Davis <afd@ti.com> Description: Get measured values from the ADC for these stages. Y is the - specific LED number. The values are expressed in 24-bit twos - complement. + specific stage number corresponding to datasheet stage names + as follows: + 1 -> LED2 + 2 -> ALED2/LED3 + 3 -> LED1 + 4 -> ALED1/LED4 + Note that channels 5 and 6 represent LED2-ALED2 and LED1-ALED1 + respectively which simply helper channels containing the + calculated difference in the value of stage 1 - 2 and 3 - 4. + The values are expressed in 24-bit twos complement. -What: /sys/bus/iio/devices/iio:deviceX/in_intensity_ledY-ledY_ambient_raw -Date: December 2015 +What: /sys/bus/iio/devices/iio:deviceX/in_intensityY_offset +Date: May 2016 KernelVersion: Contact: Andrew F. Davis <afd@ti.com> Description: - Get differential values from the ADC for these stages. Y is the - specific LED number. The values are expressed in 24-bit twos - complement for the specified LEDs. + Get and set the offset cancellation DAC setting for these + stages. The values are expressed in 5-bit sign-magnitude. -What: /sys/bus/iio/devices/iio:deviceX/out_current_ledY_offset - /sys/bus/iio/devices/iio:deviceX/out_current_ledY_ambient_offset -Date: December 2015 +What: /sys/bus/iio/devices/iio:deviceX/in_intensityY_resistance +What: /sys/bus/iio/devices/iio:deviceX/in_intensityY_capacitance +Date: May 2016 KernelVersion: Contact: Andrew F. Davis <afd@ti.com> Description: - Get and set the offset cancellation DAC setting for these - stages. The values are expressed in 5-bit sign-magnitude. + Get and set the resistance and the capacitance settings for the + Transimpedance Amplifier during the associated stage. -What: /sys/bus/iio/devices/iio:deviceX/out_current_ledY_raw -Date: December 2015 +What: /sys/bus/iio/devices/iio:deviceX/out_currentY_raw +Date: May 2016 KernelVersion: Contact: Andrew F. Davis <afd@ti.com> Description: - Get and set the LED current for the specified LED. Y is the - specific LED number. + Get and set the LED current for the specified LED active during + this stage. Y is the specific stage number. diff --git a/Documentation/ABI/testing/sysfs-bus-iio-proximity-as3935 b/Documentation/ABI/testing/sysfs-bus-iio-proximity-as3935 index 6708c5e264aa..33e96f740639 100644 --- a/Documentation/ABI/testing/sysfs-bus-iio-proximity-as3935 +++ b/Documentation/ABI/testing/sysfs-bus-iio-proximity-as3935 @@ -1,4 +1,4 @@ -What /sys/bus/iio/devices/iio:deviceX/in_proximity_raw +What /sys/bus/iio/devices/iio:deviceX/in_proximity_input Date: March 2014 KernelVersion: 3.15 Contact: Matt Ranostay <mranostay@gmail.com> diff --git a/Documentation/CodingStyle b/Documentation/CodingStyle index 9a70ddd16584..a096836723ca 100644 --- a/Documentation/CodingStyle +++ b/Documentation/CodingStyle @@ -458,7 +458,7 @@ of the function, telling people what it does, and possibly WHY it does it. When commenting the kernel API functions, please use the kernel-doc format. -See the files Documentation/kernel-doc-nano-HOWTO.txt and scripts/kernel-doc +See the files Documentation/kernel-documentation.rst and scripts/kernel-doc for details. Linux style for comments is the C89 "/* ... */" style. diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile index d70f9b68174e..01bab5014a4a 100644 --- a/Documentation/DocBook/Makefile +++ b/Documentation/DocBook/Makefile @@ -6,6 +6,8 @@ # To add a new book the only step required is to add the book to the # list of DOCBOOKS. +ifeq ($(IGNORE_DOCBOOKS),) + DOCBOOKS := z8530book.xml device-drivers.xml \ kernel-hacking.xml kernel-locking.xml deviceiobook.xml \ writing_usb_driver.xml networking.xml \ @@ -33,10 +35,6 @@ PDF_METHOD = $(prefer-db2x) PS_METHOD = $(prefer-db2x) -### -# The targets that may be used. -PHONY += xmldocs sgmldocs psdocs pdfdocs htmldocs mandocs installmandocs cleandocs - targets += $(DOCBOOKS) BOOKS := $(addprefix $(obj)/,$(DOCBOOKS)) xmldocs: $(BOOKS) @@ -63,6 +61,9 @@ installmandocs: mandocs sort -k 2 -k 1 | uniq -f 1 | sed -e 's: :/:' | \ xargs install -m 644 -t /usr/local/man/man9/ +# no-op for the DocBook toolchain +epubdocs: + ### #External programs used KERNELDOCXMLREF = $(srctree)/scripts/kernel-doc-xml-ref @@ -216,10 +217,24 @@ silent_gen_xml = : -e "s/>/\\>/g"; \ echo "</programlisting>") > $@ +else + +# Needed, due to cleanmediadocs +include Documentation/DocBook/media/Makefile + +htmldocs: +pdfdocs: +psdocs: +xmldocs: +installmandocs: + +endif # IGNORE_DOCBOOKS + + ### # Help targets as used by the top-level makefile dochelp: - @echo ' Linux kernel internal documentation in different formats:' + @echo ' Linux kernel internal documentation in different formats (DocBook):' @echo ' htmldocs - HTML' @echo ' pdfdocs - PDF' @echo ' psdocs - Postscript' @@ -228,8 +243,11 @@ dochelp: @echo ' installmandocs - install man pages generated by mandocs' @echo ' cleandocs - clean all generated DocBook files' @echo - @echo 'make DOCBOOKS="s1.xml s2.xml" [target] Generate only docs s1.xml s2.xml' + @echo ' make DOCBOOKS="s1.xml s2.xml" [target] Generate only docs s1.xml s2.xml' @echo ' valid values for DOCBOOKS are: $(DOCBOOKS)' + @echo + @echo " make IGNORE_DOCBOOKS=1 [target] Don't generate docs from Docbook" + @echo ' This is useful to generate only the ReST docs (Sphinx)' ### diff --git a/Documentation/DocBook/crypto-API.tmpl b/Documentation/DocBook/crypto-API.tmpl index d55dc5a39bad..fb2a1526f6ec 100644 --- a/Documentation/DocBook/crypto-API.tmpl +++ b/Documentation/DocBook/crypto-API.tmpl @@ -440,8 +440,8 @@ 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: + following selections which match the aforementioned cipher + types: </para> <itemizedlist> diff --git a/Documentation/DocBook/device-drivers.tmpl b/Documentation/DocBook/device-drivers.tmpl index 8c68768ebee5..58af32b01b90 100644 --- a/Documentation/DocBook/device-drivers.tmpl +++ b/Documentation/DocBook/device-drivers.tmpl @@ -300,6 +300,9 @@ X!Isound/sound_firmware.c !Iinclude/media/media-devnode.h !Iinclude/media/media-entity.h </sect1> + <sect1><title>Consumer Electronics Control devices</title> +!Iinclude/media/cec-edid.h + </sect1> </chapter> diff --git a/Documentation/DocBook/iio.tmpl b/Documentation/DocBook/iio.tmpl index f525bf56d1dd..e2ab6a1f223e 100644 --- a/Documentation/DocBook/iio.tmpl +++ b/Documentation/DocBook/iio.tmpl @@ -594,7 +594,7 @@ irqreturn_t sensor_iio_pollfunc(int irq, void *p) { - pf->timestamp = iio_get_time_ns(); + pf->timestamp = iio_get_time_ns((struct indio_dev *)p); return IRQ_WAKE_THREAD; } diff --git a/Documentation/DocBook/media/Makefile b/Documentation/DocBook/media/Makefile index 2840ff483d5a..fdc138624800 100644 --- a/Documentation/DocBook/media/Makefile +++ b/Documentation/DocBook/media/Makefile @@ -64,6 +64,7 @@ IOCTLS = \ $(shell perl -ne 'print "$$1 " if /\#define\s+([A-Z][^\s]+)\s+_IO/' $(srctree)/include/uapi/linux/dvb/net.h) \ $(shell perl -ne 'print "$$1 " if /\#define\s+([^\s]+)\s+_IO/' $(srctree)/include/uapi/linux/dvb/video.h) \ $(shell perl -ne 'print "$$1 " if /\#define\s+([^\s]+)\s+_IO/' $(srctree)/include/uapi/linux/media.h) \ + $(shell perl -ne 'print "$$1 " if /\#define\s+([^\s]+)\s+_IO/' $(srctree)/include/linux/cec.h) \ $(shell perl -ne 'print "$$1 " if /\#define\s+([^\s]+)\s+_IO/' $(srctree)/include/uapi/linux/v4l2-subdev.h) \ DEFINES = \ @@ -100,6 +101,7 @@ STRUCTS = \ $(shell perl -ne 'print "$$1 " if (/^struct\s+([^\s]+)\s+/ && !/_old/)' $(srctree)/include/uapi/linux/dvb/net.h) \ $(shell perl -ne 'print "$$1 " if (/^struct\s+([^\s]+)\s+/)' $(srctree)/include/uapi/linux/dvb/video.h) \ $(shell perl -ne 'print "$$1 " if /^struct\s+([^\s]+)\s+/' $(srctree)/include/uapi/linux/media.h) \ + $(shell perl -ne 'print "$$1 " if /^struct\s+([^\s]+)\s+/' $(srctree)/include/linux/cec.h) \ $(shell perl -ne 'print "$$1 " if /^struct\s+([^\s]+)\s+/' $(srctree)/include/uapi/linux/v4l2-subdev.h) \ $(shell perl -ne 'print "$$1 " if /^struct\s+([^\s]+)\s+/' $(srctree)/include/uapi/linux/v4l2-mediabus.h) diff --git a/Documentation/DocBook/media/v4l/biblio.xml b/Documentation/DocBook/media/v4l/biblio.xml index 9beb30f0071b..87f1d24958aa 100644 --- a/Documentation/DocBook/media/v4l/biblio.xml +++ b/Documentation/DocBook/media/v4l/biblio.xml @@ -342,6 +342,16 @@ in the frequency range from 87,5 to 108,0 MHz</title> <subtitle>Specification Version 1.4a</subtitle> </biblioentry> + <biblioentry id="hdmi2"> + <abbrev>HDMI2</abbrev> + <authorgroup> + <corpauthor>HDMI Licensing LLC +(<ulink url="http://www.hdmi.org">http://www.hdmi.org</ulink>)</corpauthor> + </authorgroup> + <title>High-Definition Multimedia Interface</title> + <subtitle>Specification Version 2.0</subtitle> + </biblioentry> + <biblioentry id="dp"> <abbrev>DP</abbrev> <authorgroup> diff --git a/Documentation/DocBook/media/v4l/cec-api.xml b/Documentation/DocBook/media/v4l/cec-api.xml new file mode 100644 index 000000000000..7062c1fa4904 --- /dev/null +++ b/Documentation/DocBook/media/v4l/cec-api.xml @@ -0,0 +1,75 @@ +<partinfo> + <authorgroup> + <author> + <firstname>Hans</firstname> + <surname>Verkuil</surname> + <affiliation><address><email>hans.verkuil@cisco.com</email></address></affiliation> + <contrib>Initial version.</contrib> + </author> + </authorgroup> + <copyright> + <year>2016</year> + <holder>Hans Verkuil</holder> + </copyright> + + <revhistory> + <!-- Put document revisions here, newest first. --> + <revision> + <revnumber>1.0.0</revnumber> + <date>2016-03-17</date> + <authorinitials>hv</authorinitials> + <revremark>Initial revision</revremark> + </revision> + </revhistory> +</partinfo> + +<title>CEC API</title> + +<chapter id="cec-api"> + <title>CEC: Consumer Electronics Control</title> + + <section id="cec-intro"> + <title>Introduction</title> + <para> + Note: this documents the proposed CEC API. This API is not yet finalized and + is currently only available as a staging kernel module. + </para> + <para>HDMI connectors provide a single pin for use by the Consumer Electronics + Control protocol. This protocol allows different devices connected by an HDMI cable + to communicate. The protocol for CEC version 1.4 is defined in supplements 1 (CEC) + and 2 (HEAC or HDMI Ethernet and Audio Return Channel) of the HDMI 1.4a + (<xref linkend="hdmi" />) specification and the extensions added to CEC version 2.0 + are defined in chapter 11 of the HDMI 2.0 (<xref linkend="hdmi2" />) specification. + </para> + + <para>The bitrate is very slow (effectively no more than 36 bytes per second) and + is based on the ancient AV.link protocol used in old SCART connectors. The protocol + closely resembles a crazy Rube Goldberg contraption and is an unholy mix of low and + high level messages. Some messages, especially those part of the HEAC protocol layered + on top of CEC, need to be handled by the kernel, others can be handled either by the + kernel or by userspace.</para> + + <para>In addition, CEC can be implemented in HDMI receivers, transmitters and in USB + devices that have an HDMI input and an HDMI output and that control just the CEC pin.</para> + + <para>Drivers that support CEC will create a CEC device node (/dev/cecX) + to give userspace access to the CEC adapter. The &CEC-ADAP-G-CAPS; ioctl will tell userspace + what it is allowed to do.</para> + </section> +</chapter> + +<appendix id="cec-user-func"> + <title>Function Reference</title> + <!-- Keep this alphabetically sorted. --> + &sub-cec-func-open; + &sub-cec-func-close; + &sub-cec-func-ioctl; + &sub-cec-func-poll; + <!-- All ioctls go here. --> + &sub-cec-ioc-adap-g-caps; + &sub-cec-ioc-adap-g-log-addrs; + &sub-cec-ioc-adap-g-phys-addr; + &sub-cec-ioc-dqevent; + &sub-cec-ioc-g-mode; + &sub-cec-ioc-receive; +</appendix> diff --git a/Documentation/DocBook/media/v4l/cec-func-close.xml b/Documentation/DocBook/media/v4l/cec-func-close.xml new file mode 100644 index 000000000000..0812c8cd9634 --- /dev/null +++ b/Documentation/DocBook/media/v4l/cec-func-close.xml @@ -0,0 +1,64 @@ +<refentry id="cec-func-close"> + <refmeta> + <refentrytitle>cec close()</refentrytitle> + &manvol; + </refmeta> + + <refnamediv> + <refname>cec-close</refname> + <refpurpose>Close a cec device</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <unistd.h></funcsynopsisinfo> + <funcprototype> + <funcdef>int <function>close</function></funcdef> + <paramdef>int <parameter>fd</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Arguments</title> + + <variablelist> + <varlistentry> + <term><parameter>fd</parameter></term> + <listitem> + <para>&fd;</para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Description</title> + + <para> + Note: this documents the proposed CEC API. This API is not yet finalized and + is currently only available as a staging kernel module. + </para> + + <para>Closes the cec device. Resources associated with the file descriptor + are freed. The device configuration remain unchanged.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para><function>close</function> returns 0 on success. On error, -1 is + returned, and <varname>errno</varname> is set appropriately. Possible error + codes are:</para> + + <variablelist> + <varlistentry> + <term><errorcode>EBADF</errorcode></term> + <listitem> + <para><parameter>fd</parameter> is not a valid open file descriptor. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> +</refentry> diff --git a/Documentation/DocBook/media/v4l/cec-func-ioctl.xml b/Documentation/DocBook/media/v4l/cec-func-ioctl.xml new file mode 100644 index 000000000000..f92817a2dc80 --- /dev/null +++ b/Documentation/DocBook/media/v4l/cec-func-ioctl.xml @@ -0,0 +1,78 @@ +<refentry id="cec-func-ioctl"> + <refmeta> + <refentrytitle>cec ioctl()</refentrytitle> + &manvol; + </refmeta> + + <refnamediv> + <refname>cec-ioctl</refname> + <refpurpose>Control a cec device</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <sys/ioctl.h></funcsynopsisinfo> + <funcprototype> + <funcdef>int <function>ioctl</function></funcdef> + <paramdef>int <parameter>fd</parameter></paramdef> + <paramdef>int <parameter>request</parameter></paramdef> + <paramdef>void *<parameter>argp</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Arguments</title> + + <variablelist> + <varlistentry> + <term><parameter>fd</parameter></term> + <listitem> + <para>&fd;</para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>request</parameter></term> + <listitem> + <para>CEC ioctl request code as defined in the cec.h header file, + for example CEC_ADAP_G_CAPS.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>argp</parameter></term> + <listitem> + <para>Pointer to a request-specific structure.</para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Description</title> + <para> + Note: this documents the proposed CEC API. This API is not yet finalized and + is currently only available as a staging kernel module. + </para> + + <para>The <function>ioctl()</function> function manipulates cec device + parameters. The argument <parameter>fd</parameter> must be an open file + descriptor.</para> + <para>The ioctl <parameter>request</parameter> code specifies the cec + function to be called. It has encoded in it whether the argument is an + input, output or read/write parameter, and the size of the argument + <parameter>argp</parameter> in bytes.</para> + <para>Macros and structures definitions specifying cec ioctl requests and + their parameters are located in the cec.h header file. All cec ioctl + requests, their respective function and parameters are specified in + <xref linkend="cec-user-func" />.</para> + </refsect1> + + <refsect1> + &return-value; + + <para>Request-specific error codes are listed in the + individual requests descriptions.</para> + <para>When an ioctl that takes an output or read/write parameter fails, + the parameter remains unmodified.</para> + </refsect1> +</refentry> diff --git a/Documentation/DocBook/media/v4l/cec-func-open.xml b/Documentation/DocBook/media/v4l/cec-func-open.xml new file mode 100644 index 000000000000..2edc5555b81a --- /dev/null +++ b/Documentation/DocBook/media/v4l/cec-func-open.xml @@ -0,0 +1,104 @@ +<refentry id="cec-func-open"> + <refmeta> + <refentrytitle>cec open()</refentrytitle> + &manvol; + </refmeta> + + <refnamediv> + <refname>cec-open</refname> + <refpurpose>Open a cec device</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <fcntl.h></funcsynopsisinfo> + <funcprototype> + <funcdef>int <function>open</function></funcdef> + <paramdef>const char *<parameter>device_name</parameter></paramdef> + <paramdef>int <parameter>flags</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Arguments</title> + + <variablelist> + <varlistentry> + <term><parameter>device_name</parameter></term> + <listitem> + <para>Device to be opened.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>flags</parameter></term> + <listitem> + <para>Open flags. Access mode must be <constant>O_RDWR</constant>. + </para> + <para>When the <constant>O_NONBLOCK</constant> flag is +given, the &CEC-RECEIVE; ioctl will return &EAGAIN; when no message is +available, and the &CEC-TRANSMIT;, &CEC-ADAP-S-PHYS-ADDR; and +&CEC-ADAP-S-LOG-ADDRS; ioctls all act in non-blocking mode.</para> + <para>Other flags have no effect.</para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + <refsect1> + <title>Description</title> + <para> + Note: this documents the proposed CEC API. This API is not yet finalized and + is currently only available as a staging kernel module. + </para> + + <para>To open a cec device applications call <function>open()</function> + with the desired device name. The function has no side effects; the device + configuration remain unchanged.</para> + <para>When the device is opened in read-only mode, attempts to modify its + configuration will result in an error, and <varname>errno</varname> will be + set to <errorcode>EBADF</errorcode>.</para> + </refsect1> + <refsect1> + <title>Return Value</title> + + <para><function>open</function> returns the new file descriptor on success. + On error, -1 is returned, and <varname>errno</varname> is set appropriately. + Possible error codes include:</para> + + <variablelist> + <varlistentry> + <term><errorcode>EACCES</errorcode></term> + <listitem> + <para>The requested access to the file is not allowed.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><errorcode>EMFILE</errorcode></term> + <listitem> + <para>The process already has the maximum number of files open. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><errorcode>ENFILE</errorcode></term> + <listitem> + <para>The system limit on the total number of open files has been + reached.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><errorcode>ENOMEM</errorcode></term> + <listitem> + <para>Insufficient kernel memory was available.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><errorcode>ENXIO</errorcode></term> + <listitem> + <para>No device corresponding to this device special file exists. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> +</refentry> diff --git a/Documentation/DocBook/media/v4l/cec-func-poll.xml b/Documentation/DocBook/media/v4l/cec-func-poll.xml new file mode 100644 index 000000000000..1bddbde0142d --- /dev/null +++ b/Documentation/DocBook/media/v4l/cec-func-poll.xml @@ -0,0 +1,94 @@ +<refentry id="cec-func-poll"> + <refmeta> + <refentrytitle>cec poll()</refentrytitle> + &manvol; + </refmeta> + + <refnamediv> + <refname>cec-poll</refname> + <refpurpose>Wait for some event on a file descriptor</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <sys/poll.h></funcsynopsisinfo> + <funcprototype> + <funcdef>int <function>poll</function></funcdef> + <paramdef>struct pollfd *<parameter>ufds</parameter></paramdef> + <paramdef>unsigned int <parameter>nfds</parameter></paramdef> + <paramdef>int <parameter>timeout</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para> + Note: this documents the proposed CEC API. This API is not yet finalized and + is currently only available as a staging kernel module. + </para> + + <para>With the <function>poll()</function> function applications +can wait for CEC events.</para> + + <para>On success <function>poll()</function> returns the number of +file descriptors that have been selected (that is, file descriptors +for which the <structfield>revents</structfield> field of the +respective <structname>pollfd</structname> structure is non-zero). +CEC devices set the <constant>POLLIN</constant> and +<constant>POLLRDNORM</constant> flags in the +<structfield>revents</structfield> field if there are messages in the +receive queue. If the transmit queue has room for new messages, the +<constant>POLLOUT</constant> and <constant>POLLWRNORM</constant> +flags are set. If there are events in the event queue, then the +<constant>POLLPRI</constant> flag is set. +When the function timed out it returns a value of zero, on +failure it returns <returnvalue>-1</returnvalue> and the +<varname>errno</varname> variable is set appropriately. +</para> + + <para>For more details see the +<function>poll()</function> manual page.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para>On success, <function>poll()</function> returns the number +structures which have non-zero <structfield>revents</structfield> +fields, or zero if the call timed out. On error +<returnvalue>-1</returnvalue> is returned, and the +<varname>errno</varname> variable is set appropriately:</para> + + <variablelist> + <varlistentry> + <term><errorcode>EBADF</errorcode></term> + <listitem> + <para>One or more of the <parameter>ufds</parameter> members +specify an invalid file descriptor.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><errorcode>EFAULT</errorcode></term> + <listitem> + <para><parameter>ufds</parameter> references an inaccessible +memory area.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><errorcode>EINTR</errorcode></term> + <listitem> + <para>The call was interrupted by a signal.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><errorcode>EINVAL</errorcode></term> + <listitem> + <para>The <parameter>nfds</parameter> argument is greater +than <constant>OPEN_MAX</constant>.</para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> +</refentry> diff --git a/Documentation/DocBook/media/v4l/cec-ioc-adap-g-caps.xml b/Documentation/DocBook/media/v4l/cec-ioc-adap-g-caps.xml new file mode 100644 index 000000000000..3523ef2259b1 --- /dev/null +++ b/Documentation/DocBook/media/v4l/cec-ioc-adap-g-caps.xml @@ -0,0 +1,151 @@ +<refentry id="cec-ioc-adap-g-caps"> + <refmeta> + <refentrytitle>ioctl CEC_ADAP_G_CAPS</refentrytitle> + &manvol; + </refmeta> + + <refnamediv> + <refname>CEC_ADAP_G_CAPS</refname> + <refpurpose>Query device capabilities</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>ioctl</function></funcdef> + <paramdef>int <parameter>fd</parameter></paramdef> + <paramdef>int <parameter>request</parameter></paramdef> + <paramdef>struct cec_caps *<parameter>argp</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Arguments</title> + + <variablelist> + <varlistentry> + <term><parameter>fd</parameter></term> + <listitem> + <para>File descriptor returned by + <link linkend='cec-func-open'><function>open()</function></link>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>request</parameter></term> + <listitem> + <para>CEC_ADAP_G_CAPS</para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>argp</parameter></term> + <listitem> + <para></para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Description</title> + + <para> + Note: this documents the proposed CEC API. This API is not yet finalized and + is currently only available as a staging kernel module. + </para> + + <para>All cec devices must support the <constant>CEC_ADAP_G_CAPS</constant> + ioctl. To query device information, applications call the ioctl with a + pointer to a &cec-caps;. The driver fills the structure and returns + the information to the application. + The ioctl never fails.</para> + + <table pgwide="1" frame="none" id="cec-caps"> + <title>struct <structname>cec_caps</structname></title> + <tgroup cols="3"> + &cs-str; + <tbody valign="top"> + <row> + <entry>char</entry> + <entry><structfield>driver[32]</structfield></entry> + <entry>The name of the cec adapter driver.</entry> + </row> + <row> + <entry>char</entry> + <entry><structfield>name[32]</structfield></entry> + <entry>The name of this CEC adapter. The combination <structfield>driver</structfield> + and <structfield>name</structfield> must be unique.</entry> + </row> + <row> + <entry>__u32</entry> + <entry><structfield>capabilities</structfield></entry> + <entry>The capabilities of the CEC adapter, see <xref + linkend="cec-capabilities" />.</entry> + </row> + <row> + <entry>__u32</entry> + <entry><structfield>version</structfield></entry> + <entry>CEC Framework API version, formatted with the + <constant>KERNEL_VERSION()</constant> macro.</entry> + </row> + </tbody> + </tgroup> + </table> + + <table pgwide="1" frame="none" id="cec-capabilities"> + <title>CEC Capabilities Flags</title> + <tgroup cols="3"> + &cs-def; + <tbody valign="top"> + <row> + <entry><constant>CEC_CAP_PHYS_ADDR</constant></entry> + <entry>0x00000001</entry> + <entry>Userspace has to configure the physical address by + calling &CEC-ADAP-S-PHYS-ADDR;. If this capability isn't set, + then setting the physical address is handled by the kernel + whenever the EDID is set (for an HDMI receiver) or read (for + an HDMI transmitter).</entry> + </row> + <row> + <entry><constant>CEC_CAP_LOG_ADDRS</constant></entry> + <entry>0x00000002</entry> + <entry>Userspace has to configure the logical addresses by + calling &CEC-ADAP-S-LOG-ADDRS;. If this capability isn't set, + then the kernel will have configured this.</entry> + </row> + <row> + <entry><constant>CEC_CAP_TRANSMIT</constant></entry> + <entry>0x00000004</entry> + <entry>Userspace can transmit CEC messages by calling &CEC-TRANSMIT;. This + implies that userspace can be a follower as well, since being able to + transmit messages is a prerequisite of becoming a follower. If this + capability isn't set, then the kernel will handle all CEC transmits + and process all CEC messages it receives. + </entry> + </row> + <row> + <entry><constant>CEC_CAP_PASSTHROUGH</constant></entry> + <entry>0x00000008</entry> + <entry>Userspace can use the passthrough mode by + calling &CEC-S-MODE;.</entry> + </row> + <row> + <entry><constant>CEC_CAP_RC</constant></entry> + <entry>0x00000010</entry> + <entry>This adapter supports the remote control protocol.</entry> + </row> + <row> + <entry><constant>CEC_CAP_MONITOR_ALL</constant></entry> + <entry>0x00000020</entry> + <entry>The CEC hardware can monitor all messages, not just directed and + broadcast messages.</entry> + </row> + </tbody> + </tgroup> + </table> + </refsect1> + + <refsect1> + &return-value; + </refsect1> +</refentry> diff --git a/Documentation/DocBook/media/v4l/cec-ioc-adap-g-log-addrs.xml b/Documentation/DocBook/media/v4l/cec-ioc-adap-g-log-addrs.xml new file mode 100644 index 000000000000..302b8294f7fc --- /dev/null +++ b/Documentation/DocBook/media/v4l/cec-ioc-adap-g-log-addrs.xml @@ -0,0 +1,329 @@ +<refentry id="cec-ioc-adap-g-log-addrs"> + <refmeta> + <refentrytitle>ioctl CEC_ADAP_G_LOG_ADDRS, CEC_ADAP_S_LOG_ADDRS</refentrytitle> + &manvol; + </refmeta> + + <refnamediv> + <refname>CEC_ADAP_G_LOG_ADDRS</refname> + <refname>CEC_ADAP_S_LOG_ADDRS</refname> + <refpurpose>Get or set the logical addresses</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>ioctl</function></funcdef> + <paramdef>int <parameter>fd</parameter></paramdef> + <paramdef>int <parameter>request</parameter></paramdef> + <paramdef>struct cec_log_addrs *<parameter>argp</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Arguments</title> + + <variablelist> + <varlistentry> + <term><parameter>fd</parameter></term> + <listitem> + <para>File descriptor returned by + <link linkend='cec-func-open'><function>open()</function></link>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>request</parameter></term> + <listitem> + <para>CEC_ADAP_G_LOG_ADDRS, CEC_ADAP_S_LOG_ADDRS</para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>argp</parameter></term> + <listitem> + <para></para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Description</title> + + <para> + Note: this documents the proposed CEC API. This API is not yet finalized and + is currently only available as a staging kernel module. + </para> + + <para>To query the current CEC logical addresses, applications call the +<constant>CEC_ADAP_G_LOG_ADDRS</constant> ioctl with a pointer to a +<structname>cec_log_addrs</structname> structure where the drivers stores the +logical addresses.</para> + + <para>To set new logical addresses, applications fill in struct <structname>cec_log_addrs</structname> +and call the <constant>CEC_ADAP_S_LOG_ADDRS</constant> ioctl with a pointer to this struct. +The <constant>CEC_ADAP_S_LOG_ADDRS</constant> ioctl is only available if +<constant>CEC_CAP_LOG_ADDRS</constant> is set (&ENOTTY; is returned otherwise). This ioctl will block until all +requested logical addresses have been claimed. <constant>CEC_ADAP_S_LOG_ADDRS</constant> +can only be called by a file handle in initiator mode (see &CEC-S-MODE;).</para> + + <table pgwide="1" frame="none" id="cec-log-addrs"> + <title>struct <structname>cec_log_addrs</structname></title> + <tgroup cols="3"> + &cs-str; + <tbody valign="top"> + <row> + <entry>__u8</entry> + <entry><structfield>log_addr</structfield>[CEC_MAX_LOG_ADDRS]</entry> + <entry>The actual logical addresses that were claimed. This is set by the + driver. If no logical address could be claimed, then it is set to + <constant>CEC_LOG_ADDR_INVALID</constant>. If this adapter is Unregistered, + then <structfield>log_addr[0]</structfield> is set to 0xf and all others to + <constant>CEC_LOG_ADDR_INVALID</constant>.</entry> + </row> + <row> + <entry>__u16</entry> + <entry><structfield>log_addr_mask</structfield></entry> + <entry>The bitmask of all logical addresses this adapter has claimed. + If this adapter is Unregistered then <structfield>log_addr_mask</structfield> + sets bit 15 and clears all other bits. If this adapter is not configured at all, then + <structfield>log_addr_mask</structfield> is set to 0. Set by the driver.</entry> + </row> + <row> + <entry>__u8</entry> + <entry><structfield>cec_version</structfield></entry> + <entry>The CEC version that this adapter shall use. See + <xref linkend="cec-versions" />. + Used to implement the <constant>CEC_MSG_CEC_VERSION</constant> and + <constant>CEC_MSG_REPORT_FEATURES</constant> messages. Note that + <constant>CEC_OP_CEC_VERSION_1_3A</constant> is not allowed + by the CEC framework. + </entry> + </row> + <row> + <entry>__u8</entry> + <entry><structfield>num_log_addrs</structfield></entry> + <entry>Number of logical addresses to set up. Must be ≤ + <structfield>available_log_addrs</structfield> as returned by + &CEC-ADAP-G-CAPS;. All arrays in this structure are only filled up to + index <structfield>available_log_addrs</structfield>-1. The remaining + array elements will be ignored. Note that the CEC 2.0 standard allows + for a maximum of 2 logical addresses, although some hardware has support + for more. <constant>CEC_MAX_LOG_ADDRS</constant> is 4. The driver will + return the actual number of logical addresses it could claim, which may + be less than what was requested. If this field is set to 0, then the + CEC adapter shall clear all claimed logical addresses and all other + fields will be ignored.</entry> + </row> + <row> + <entry>__u32</entry> + <entry><structfield>vendor_id</structfield></entry> + <entry>The vendor ID is a 24-bit number that identifies the specific + vendor or entity. Based on this ID vendor specific commands may be + defined. If you do not want a vendor ID then set it to + <constant>CEC_VENDOR_ID_NONE</constant>.</entry> + </row> + <row> + <entry>__u32</entry> + <entry><structfield>flags</structfield></entry> + <entry>Flags. No flags are defined yet, so set this to 0.</entry> + </row> + <row> + <entry>char</entry> + <entry><structfield>osd_name</structfield>[15]</entry> + <entry>The On-Screen Display name as is returned by the + <constant>CEC_MSG_SET_OSD_NAME</constant> message.</entry> + </row> + <row> + <entry>__u8</entry> + <entry><structfield>primary_device_type</structfield>[CEC_MAX_LOG_ADDRS]</entry> + <entry>Primary device type for each logical address. See + <xref linkend="cec-prim-dev-types" /> for possible types.</entry> + </row> + <row> + <entry>__u8</entry> + <entry><structfield>log_addr_type</structfield>[CEC_MAX_LOG_ADDRS]</entry> + <entry>Logical address types. See <xref linkend="cec-log-addr-types" /> for + possible types. The driver will update this with the actual logical address + type that it claimed (e.g. it may have to fallback to + <constant>CEC_LOG_ADDR_TYPE_UNREGISTERED</constant>).</entry> + </row> + <row> + <entry>__u8</entry> + <entry><structfield>all_device_types</structfield>[CEC_MAX_LOG_ADDRS]</entry> + <entry>CEC 2.0 specific: all device types. See <xref linkend="cec-all-dev-types-flags" />. + Used to implement the <constant>CEC_MSG_REPORT_FEATURES</constant> message. + This field is ignored if <structfield>cec_version</structfield> < + <constant>CEC_OP_CEC_VERSION_2_0</constant>.</entry> + </row> + <row> + <entry>__u8</entry> + <entry><structfield>features</structfield>[CEC_MAX_LOG_ADDRS][12]</entry> + <entry>Features for each logical address. Used to implement the + <constant>CEC_MSG_REPORT_FEATURES</constant> message. The 12 bytes include + both the RC Profile and the Device Features. + This field is ignored if <structfield>cec_version</structfield> < + <constant>CEC_OP_CEC_VERSION_2_0</constant>.</entry> + </row> + </tbody> + </tgroup> + </table> + + <table pgwide="1" frame="none" id="cec-versions"> + <title>CEC Versions</title> + <tgroup cols="3"> + &cs-def; + <tbody valign="top"> + <row> + <entry><constant>CEC_OP_CEC_VERSION_1_3A</constant></entry> + <entry>4</entry> + <entry>CEC version according to the HDMI 1.3a standard.</entry> + </row> + <row> + <entry><constant>CEC_OP_CEC_VERSION_1_4B</constant></entry> + <entry>5</entry> + <entry>CEC version according to the HDMI 1.4b standard.</entry> + </row> + <row> + <entry><constant>CEC_OP_CEC_VERSION_2_0</constant></entry> + <entry>6</entry> + <entry>CEC version according to the HDMI 2.0 standard.</entry> + </row> + </tbody> + </tgroup> + </table> + + <table pgwide="1" frame="none" id="cec-prim-dev-types"> + <title>CEC Primary Device Types</title> + <tgroup cols="3"> + &cs-def; + <tbody valign="top"> + <row> + <entry><constant>CEC_OP_PRIM_DEVTYPE_TV</constant></entry> + <entry>0</entry> + <entry>Use for a TV.</entry> + </row> + <row> + <entry><constant>CEC_OP_PRIM_DEVTYPE_RECORD</constant></entry> + <entry>1</entry> + <entry>Use for a recording device.</entry> + </row> + <row> + <entry><constant>CEC_OP_PRIM_DEVTYPE_TUNER</constant></entry> + <entry>3</entry> + <entry>Use for a device with a tuner.</entry> + </row> + <row> + <entry><constant>CEC_OP_PRIM_DEVTYPE_PLAYBACK</constant></entry> + <entry>4</entry> + <entry>Use for a playback device.</entry> + </row> + <row> + <entry><constant>CEC_OP_PRIM_DEVTYPE_AUDIOSYSTEM</constant></entry> + <entry>5</entry> + <entry>Use for an audio system (e.g. an audio/video receiver).</entry> + </row> + <row> + <entry><constant>CEC_OP_PRIM_DEVTYPE_SWITCH</constant></entry> + <entry>6</entry> + <entry>Use for a CEC switch.</entry> + </row> + <row> + <entry><constant>CEC_OP_PRIM_DEVTYPE_VIDEOPROC</constant></entry> + <entry>7</entry> + <entry>Use for a video processor device.</entry> + </row> + </tbody> + </tgroup> + </table> + + <table pgwide="1" frame="none" id="cec-log-addr-types"> + <title>CEC Logical Address Types</title> + <tgroup cols="3"> + &cs-def; + <tbody valign="top"> + <row> + <entry><constant>CEC_LOG_ADDR_TYPE_TV</constant></entry> + <entry>0</entry> + <entry>Use for a TV.</entry> + </row> + <row> + <entry><constant>CEC_LOG_ADDR_TYPE_RECORD</constant></entry> + <entry>1</entry> + <entry>Use for a recording device.</entry> + </row> + <row> + <entry><constant>CEC_LOG_ADDR_TYPE_TUNER</constant></entry> + <entry>2</entry> + <entry>Use for a tuner device.</entry> + </row> + <row> + <entry><constant>CEC_LOG_ADDR_TYPE_PLAYBACK</constant></entry> + <entry>3</entry> + <entry>Use for a playback device.</entry> + </row> + <row> + <entry><constant>CEC_LOG_ADDR_TYPE_AUDIOSYSTEM</constant></entry> + <entry>4</entry> + <entry>Use for an audio system device.</entry> + </row> + <row> + <entry><constant>CEC_LOG_ADDR_TYPE_SPECIFIC</constant></entry> + <entry>5</entry> + <entry>Use for a second TV or for a video processor device.</entry> + </row> + <row> + <entry><constant>CEC_LOG_ADDR_TYPE_UNREGISTERED</constant></entry> + <entry>6</entry> + <entry>Use this if you just want to remain unregistered. + Used for pure CEC switches or CDC-only devices (CDC: + Capability Discovery and Control).</entry> + </row> + </tbody> + </tgroup> + </table> + + <table pgwide="1" frame="none" id="cec-all-dev-types-flags"> + <title>CEC All Device Types Flags</title> + <tgroup cols="3"> + &cs-def; + <tbody valign="top"> + <row> + <entry><constant>CEC_OP_ALL_DEVTYPE_TV</constant></entry> + <entry>0x80</entry> + <entry>This supports the TV type.</entry> + </row> + <row> + <entry><constant>CEC_OP_ALL_DEVTYPE_RECORD</constant></entry> + <entry>0x40</entry> + <entry>This supports the Recording type.</entry> + </row> + <row> + <entry><constant>CEC_OP_ALL_DEVTYPE_TUNER</constant></entry> + <entry>0x20</entry> + <entry>This supports the Tuner type.</entry> + </row> + <row> + <entry><constant>CEC_OP_ALL_DEVTYPE_PLAYBACK</constant></entry> + <entry>0x10</entry> + <entry>This supports the Playback type.</entry> + </row> + <row> + <entry><constant>CEC_OP_ALL_DEVTYPE_AUDIOSYSTEM</constant></entry> + <entry>0x08</entry> + <entry>This supports the Audio System type.</entry> + </row> + <row> + <entry><constant>CEC_OP_ALL_DEVTYPE_SWITCH</constant></entry> + <entry>0x04</entry> + <entry>This supports the CEC Switch or Video Processing type.</entry> + </row> + </tbody> + </tgroup> + </table> + </refsect1> + + <refsect1> + &return-value; + </refsect1> +</refentry> diff --git a/Documentation/DocBook/media/v4l/cec-ioc-adap-g-phys-addr.xml b/Documentation/DocBook/media/v4l/cec-ioc-adap-g-phys-addr.xml new file mode 100644 index 000000000000..d95f1785080c --- /dev/null +++ b/Documentation/DocBook/media/v4l/cec-ioc-adap-g-phys-addr.xml @@ -0,0 +1,86 @@ +<refentry id="cec-ioc-adap-g-phys-addr"> + <refmeta> + <refentrytitle>ioctl CEC_ADAP_G_PHYS_ADDR, CEC_ADAP_S_PHYS_ADDR</refentrytitle> + &manvol; + </refmeta> + + <refnamediv> + <refname>CEC_ADAP_G_PHYS_ADDR</refname> + <refname>CEC_ADAP_S_PHYS_ADDR</refname> + <refpurpose>Get or set the physical address</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>ioctl</function></funcdef> + <paramdef>int <parameter>fd</parameter></paramdef> + <paramdef>int <parameter>request</parameter></paramdef> + <paramdef>__u16 *<parameter>argp</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Arguments</title> + + <variablelist> + <varlistentry> + <term><parameter>fd</parameter></term> + <listitem> + <para>File descriptor returned by + <link linkend='cec-func-open'><function>open()</function></link>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>request</parameter></term> + <listitem> + <para>CEC_ADAP_G_PHYS_ADDR, CEC_ADAP_S_PHYS_ADDR</para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>argp</parameter></term> + <listitem> + <para></para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Description</title> + + <para> + Note: this documents the proposed CEC API. This API is not yet finalized and + is currently only available as a staging kernel module. + </para> + + <para>To query the current physical address applications call the +<constant>CEC_ADAP_G_PHYS_ADDR</constant> ioctl with a pointer to an __u16 +where the driver stores the physical address.</para> + + <para>To set a new physical address applications store the physical address in +an __u16 and call the <constant>CEC_ADAP_S_PHYS_ADDR</constant> ioctl with a +pointer to this integer. <constant>CEC_ADAP_S_PHYS_ADDR</constant> is only +available if <constant>CEC_CAP_PHYS_ADDR</constant> is set (&ENOTTY; will be returned +otherwise). <constant>CEC_ADAP_S_PHYS_ADDR</constant> +can only be called by a file handle in initiator mode (see &CEC-S-MODE;), if not +&EBUSY; will be returned.</para> + + <para>The physical address is a 16-bit number where each group of 4 bits +represent a digit of the physical address a.b.c.d where the most significant +4 bits represent 'a'. The CEC root device (usually the TV) has address 0.0.0.0. +Every device that is hooked up to an input of the TV has address a.0.0.0 (where +'a' is ≥ 1), devices hooked up to those in turn have addresses a.b.0.0, etc. +So a topology of up to 5 devices deep is supported. The physical address a +device shall use is stored in the EDID of the sink.</para> + +<para>For example, the EDID for each HDMI input of the TV will have a different +physical address of the form a.0.0.0 that the sources will read out and use as +their physical address.</para> + </refsect1> + + <refsect1> + &return-value; + </refsect1> +</refentry> diff --git a/Documentation/DocBook/media/v4l/cec-ioc-dqevent.xml b/Documentation/DocBook/media/v4l/cec-ioc-dqevent.xml new file mode 100644 index 000000000000..697dde575cd4 --- /dev/null +++ b/Documentation/DocBook/media/v4l/cec-ioc-dqevent.xml @@ -0,0 +1,202 @@ +<refentry id="cec-ioc-g-event"> + <refmeta> + <refentrytitle>ioctl CEC_DQEVENT</refentrytitle> + &manvol; + </refmeta> + + <refnamediv> + <refname>CEC_DQEVENT</refname> + <refpurpose>Dequeue a CEC event</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>ioctl</function></funcdef> + <paramdef>int <parameter>fd</parameter></paramdef> + <paramdef>int <parameter>request</parameter></paramdef> + <paramdef>struct cec_event *<parameter>argp</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Arguments</title> + + <variablelist> + <varlistentry> + <term><parameter>fd</parameter></term> + <listitem> + <para>File descriptor returned by + <link linkend='cec-func-open'><function>open()</function></link>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>request</parameter></term> + <listitem> + <para>CEC_DQEVENT</para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>argp</parameter></term> + <listitem> + <para></para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Description</title> + + <para> + Note: this documents the proposed CEC API. This API is not yet finalized and + is currently only available as a staging kernel module. + </para> + + <para>CEC devices can send asynchronous events. These can be retrieved by calling + the <constant>CEC_DQEVENT</constant> ioctl. If the file descriptor is in non-blocking + mode and no event is pending, then it will return -1 and set errno to the &EAGAIN;.</para> + + <para>The internal event queues are per-filehandle and per-event type. If there is + no more room in a queue then the last event is overwritten with the new one. This + means that intermediate results can be thrown away but that the latest event is always + available. This also means that is it possible to read two successive events that have + the same value (e.g. two CEC_EVENT_STATE_CHANGE events with the same state). In that + case the intermediate state changes were lost but it is guaranteed that the state + did change in between the two events.</para> + + <table pgwide="1" frame="none" id="cec-event-state-change"> + <title>struct <structname>cec_event_state_change</structname></title> + <tgroup cols="3"> + &cs-str; + <tbody valign="top"> + <row> + <entry>__u16</entry> + <entry><structfield>phys_addr</structfield></entry> + <entry>The current physical address.</entry> + </row> + <row> + <entry>__u16</entry> + <entry><structfield>log_addr_mask</structfield></entry> + <entry>The current set of claimed logical addresses.</entry> + </row> + </tbody> + </tgroup> + </table> + + <table pgwide="1" frame="none" id="cec-event-lost-msgs"> + <title>struct <structname>cec_event_lost_msgs</structname></title> + <tgroup cols="3"> + &cs-str; + <tbody valign="top"> + <row> + <entry>__u32</entry> + <entry><structfield>lost_msgs</structfield></entry> + <entry>Set to the number of lost messages since the filehandle + was opened or since the last time this event was dequeued for + this filehandle. The messages lost are the oldest messages. So + when a new message arrives and there is no more room, then the + oldest message is discarded to make room for the new one. The + internal size of the message queue guarantees that all messages + received in the last two seconds will be stored. Since messages + should be replied to within a second according to the CEC + specification, this is more than enough. + </entry> + </row> + </tbody> + </tgroup> + </table> + + <table pgwide="1" frame="none" id="cec-event"> + <title>struct <structname>cec_event</structname></title> + <tgroup cols="4"> + &cs-str; + <tbody valign="top"> + <row> + <entry>__u64</entry> + <entry><structfield>ts</structfield></entry> + <entry>Timestamp of the event in ns.</entry> + <entry></entry> + </row> + <row> + <entry>__u32</entry> + <entry><structfield>event</structfield></entry> + <entry>The CEC event type, see <xref linkend="cec-events" />.</entry> + <entry></entry> + </row> + <row> + <entry>__u32</entry> + <entry><structfield>flags</structfield></entry> + <entry>Event flags, see <xref linkend="cec-event-flags" />.</entry> + <entry></entry> + </row> + <row> + <entry>union</entry> + <entry>(anonymous)</entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry></entry> + <entry>struct cec_event_state_change</entry> + <entry><structfield>state_change</structfield></entry> + <entry>The new adapter state as sent by the <constant>CEC_EVENT_STATE_CHANGE</constant> + event.</entry> + </row> + <row> + <entry></entry> + <entry>struct cec_event_lost_msgs</entry> + <entry><structfield>lost_msgs</structfield></entry> + <entry>The number of lost messages as sent by the <constant>CEC_EVENT_LOST_MSGS</constant> + event.</entry> + </row> + </tbody> + </tgroup> + </table> + + <table pgwide="1" frame="none" id="cec-events"> + <title>CEC Events Types</title> + <tgroup cols="3"> + &cs-def; + <tbody valign="top"> + <row> + <entry><constant>CEC_EVENT_STATE_CHANGE</constant></entry> + <entry>1</entry> + <entry>Generated when the CEC Adapter's state changes. When open() is + called an initial event will be generated for that filehandle with the + CEC Adapter's state at that time. + </entry> + </row> + <row> + <entry><constant>CEC_EVENT_LOST_MSGS</constant></entry> + <entry>2</entry> + <entry>Generated if one or more CEC messages were lost because the + application didn't dequeue CEC messages fast enough.</entry> + </row> + </tbody> + </tgroup> + </table> + + <table pgwide="1" frame="none" id="cec-event-flags"> + <title>CEC Event Flags</title> + <tgroup cols="3"> + &cs-def; + <tbody valign="top"> + <row> + <entry><constant>CEC_EVENT_FL_INITIAL_VALUE</constant></entry> + <entry>1</entry> + <entry>Set for the initial events that are generated when the device is + opened. See the table above for which events do this. This allows + applications to learn the initial state of the CEC adapter at open() + time.</entry> + </row> + </tbody> + </tgroup> + </table> + </refsect1> + + <refsect1> + &return-value; + </refsect1> +</refentry> diff --git a/Documentation/DocBook/media/v4l/cec-ioc-g-mode.xml b/Documentation/DocBook/media/v4l/cec-ioc-g-mode.xml new file mode 100644 index 000000000000..26b4282ad134 --- /dev/null +++ b/Documentation/DocBook/media/v4l/cec-ioc-g-mode.xml @@ -0,0 +1,255 @@ +<refentry id="cec-ioc-g-mode"> + <refmeta> + <refentrytitle>ioctl CEC_G_MODE, CEC_S_MODE</refentrytitle> + &manvol; + </refmeta> + + <refnamediv> + <refname>CEC_G_MODE</refname> + <refname>CEC_S_MODE</refname> + <refpurpose>Get or set exclusive use of the CEC adapter</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>ioctl</function></funcdef> + <paramdef>int <parameter>fd</parameter></paramdef> + <paramdef>int <parameter>request</parameter></paramdef> + <paramdef>__u32 *<parameter>argp</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Arguments</title> + + <variablelist> + <varlistentry> + <term><parameter>fd</parameter></term> + <listitem> + <para>File descriptor returned by + <link linkend='cec-func-open'><function>open()</function></link>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>request</parameter></term> + <listitem> + <para>CEC_G_MODE, CEC_S_MODE</para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>argp</parameter></term> + <listitem> + <para></para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Description</title> + + <para> + Note: this documents the proposed CEC API. This API is not yet finalized and + is currently only available as a staging kernel module. + </para> + + <para>By default any filehandle can use &CEC-TRANSMIT; and &CEC-RECEIVE;, but +in order to prevent applications from stepping on each others toes it must be possible +to obtain exclusive access to the CEC adapter. This ioctl sets the filehandle +to initiator and/or follower mode which can be exclusive depending on the chosen +mode. The initiator is the filehandle that is used +to initiate messages, i.e. it commands other CEC devices. The follower is the filehandle +that receives messages sent to the CEC adapter and processes them. The same filehandle +can be both initiator and follower, or this role can be taken by two different +filehandles.</para> + + <para>When a CEC message is received, then the CEC framework will decide how +it will be processed. If the message is a reply to an earlier transmitted message, +then the reply is sent back to the filehandle that is waiting for it. In addition +the CEC framework will process it.</para> + + <para>If the message is not a reply, then the CEC framework will process it +first. If there is no follower, then the message is just discarded and a feature +abort is sent back to the initiator if the framework couldn't process it. If there +is a follower, then the message is passed on to the follower who will use +&CEC-RECEIVE; to dequeue the new message. The framework expects the follower to +make the right decisions.</para> + + <para>The CEC framework will process core messages unless requested otherwise +by the follower. The follower can enable the passthrough mode. In that case, the +CEC framework will pass on most core messages without processing them and +the follower will have to implement those messages. There are some messages +that the core will always process, regardless of the passthrough mode. See +<xref linkend="cec-core-processing" /> for details.</para> + + <para>If there is no initiator, then any CEC filehandle can use &CEC-TRANSMIT;. +If there is an exclusive initiator then only that initiator can call &CEC-TRANSMIT;. +The follower can of course always call &CEC-TRANSMIT;.</para> + + <para>Available initiator modes are:</para> + + <table pgwide="1" frame="none" id="cec-mode-initiator"> + <title>Initiator Modes</title> + <tgroup cols="3"> + &cs-def; + <tbody valign="top"> + <row> + <entry><constant>CEC_MODE_NO_INITIATOR</constant></entry> + <entry>0x0</entry> + <entry>This is not an initiator, i.e. it cannot transmit CEC messages + or make any other changes to the CEC adapter.</entry> + </row> + <row> + <entry><constant>CEC_MODE_INITIATOR</constant></entry> + <entry>0x1</entry> + <entry>This is an initiator (the default when the device is opened) and it + can transmit CEC messages and make changes to the CEC adapter, unless there + is an exclusive initiator.</entry> + </row> + <row> + <entry><constant>CEC_MODE_EXCL_INITIATOR</constant></entry> + <entry>0x2</entry> + <entry>This is an exclusive initiator and this file descriptor is the only one + that can transmit CEC messages and make changes to the CEC adapter. If someone + else is already the exclusive initiator then an attempt to become one will return + the &EBUSY; error.</entry> + </row> + </tbody> + </tgroup> + </table> + + <para>Available follower modes are:</para> + + <table pgwide="1" frame="none" id="cec-mode-follower"> + <title>Follower Modes</title> + <tgroup cols="3"> + &cs-def; + <tbody valign="top"> + <row> + <entry><constant>CEC_MODE_NO_FOLLOWER</constant></entry> + <entry>0x00</entry> + <entry>This is not a follower (the default when the device is opened).</entry> + </row> + <row> + <entry><constant>CEC_MODE_FOLLOWER</constant></entry> + <entry>0x10</entry> + <entry>This is a follower and it will receive CEC messages unless there is + an exclusive follower. You cannot become a follower if <constant>CEC_CAP_TRANSMIT</constant> + is not set or if <constant>CEC_MODE_NO_INITIATOR</constant> was specified, + &EINVAL; is returned in that case.</entry> + </row> + <row> + <entry><constant>CEC_MODE_EXCL_FOLLOWER</constant></entry> + <entry>0x20</entry> + <entry>This is an exclusive follower and only this file descriptor will receive + CEC messages for processing. If someone else is already the exclusive follower + then an attempt to become one will return the &EBUSY; error. You cannot become + a follower if <constant>CEC_CAP_TRANSMIT</constant> is not set or if + <constant>CEC_MODE_NO_INITIATOR</constant> was specified, &EINVAL; is returned + in that case.</entry> + </row> + <row> + <entry><constant>CEC_MODE_EXCL_FOLLOWER_PASSTHRU</constant></entry> + <entry>0x30</entry> + <entry>This is an exclusive follower and only this file descriptor will receive + CEC messages for processing. In addition it will put the CEC device into + passthrough mode, allowing the exclusive follower to handle most core messages + instead of relying on the CEC framework for that. If someone else is already the + exclusive follower then an attempt to become one will return the &EBUSY; error. + You cannot become a follower if <constant>CEC_CAP_TRANSMIT</constant> + is not set or if <constant>CEC_MODE_NO_INITIATOR</constant> was specified, + &EINVAL; is returned in that case.</entry> + </row> + <row> + <entry><constant>CEC_MODE_MONITOR</constant></entry> + <entry>0xe0</entry> + <entry>Put the file descriptor into monitor mode. Can only be used in combination + with <constant>CEC_MODE_NO_INITIATOR</constant>, otherwise &EINVAL; will be + returned. In monitor mode all messages this CEC device transmits and all messages + it receives (both broadcast messages and directed messages for one its logical + addresses) will be reported. This is very useful for debugging. This is only + allowed if the process has the <constant>CAP_NET_ADMIN</constant> + capability. If that is not set, then &EPERM; is returned.</entry> + </row> + <row> + <entry><constant>CEC_MODE_MONITOR_ALL</constant></entry> + <entry>0xf0</entry> + <entry>Put the file descriptor into 'monitor all' mode. Can only be used in combination + with <constant>CEC_MODE_NO_INITIATOR</constant>, otherwise &EINVAL; will be + returned. In 'monitor all' mode all messages this CEC device transmits and all messages + it receives, including directed messages for other CEC devices will be reported. This + is very useful for debugging, but not all devices support this. This mode requires that + the <constant>CEC_CAP_MONITOR_ALL</constant> capability is set, otherwise &EINVAL; is + returned. This is only allowed if the process has the <constant>CAP_NET_ADMIN</constant> + capability. If that is not set, then &EPERM; is returned.</entry> + </row> + </tbody> + </tgroup> + </table> + + <para>Core message processing details:</para> + + <table pgwide="1" frame="none" id="cec-core-processing"> + <title>Core Message Processing</title> + <tgroup cols="2"> + &cs-def; + <tbody valign="top"> + <row> + <entry><constant>CEC_MSG_GET_CEC_VERSION</constant></entry> + <entry>When in passthrough mode this message has to be handled by userspace, + otherwise the core will return the CEC version that was set with &CEC-ADAP-S-LOG-ADDRS;.</entry> + </row> + <row> + <entry><constant>CEC_MSG_GIVE_DEVICE_VENDOR_ID</constant></entry> + <entry>When in passthrough mode this message has to be handled by userspace, + otherwise the core will return the vendor ID that was set with &CEC-ADAP-S-LOG-ADDRS;.</entry> + </row> + <row> + <entry><constant>CEC_MSG_ABORT</constant></entry> + <entry>When in passthrough mode this message has to be handled by userspace, + otherwise the core will return a feature refused message as per the specification.</entry> + </row> + <row> + <entry><constant>CEC_MSG_GIVE_PHYSICAL_ADDR</constant></entry> + <entry>When in passthrough mode this message has to be handled by userspace, + otherwise the core will report the current physical address.</entry> + </row> + <row> + <entry><constant>CEC_MSG_GIVE_OSD_NAME</constant></entry> + <entry>When in passthrough mode this message has to be handled by userspace, + otherwise the core will report the current OSD name as was set with + &CEC-ADAP-S-LOG-ADDRS;.</entry> + </row> + <row> + <entry><constant>CEC_MSG_GIVE_FEATURES</constant></entry> + <entry>When in passthrough mode this message has to be handled by userspace, + otherwise the core will report the current features as was set with + &CEC-ADAP-S-LOG-ADDRS; or the message is ignore if the CEC version was + older than 2.0.</entry> + </row> + <row> + <entry><constant>CEC_MSG_USER_CONTROL_PRESSED</constant></entry> + <entry>If <constant>CEC_CAP_RC</constant> is set, then generate a remote control + key press. This message is always passed on to userspace.</entry> + </row> + <row> + <entry><constant>CEC_MSG_USER_CONTROL_RELEASED</constant></entry> + <entry>If <constant>CEC_CAP_RC</constant> is set, then generate a remote control + key release. This message is always passed on to userspace.</entry> + </row> + <row> + <entry><constant>CEC_MSG_REPORT_PHYSICAL_ADDR</constant></entry> + <entry>The CEC framework will make note of the reported physical address + and then just pass the message on to userspace.</entry> + </row> + </tbody> + </tgroup> + </table> + </refsect1> + + <refsect1> + &return-value; + </refsect1> +</refentry> diff --git a/Documentation/DocBook/media/v4l/cec-ioc-receive.xml b/Documentation/DocBook/media/v4l/cec-ioc-receive.xml new file mode 100644 index 000000000000..fde9f8678e67 --- /dev/null +++ b/Documentation/DocBook/media/v4l/cec-ioc-receive.xml @@ -0,0 +1,274 @@ +<refentry id="cec-ioc-receive"> + <refmeta> + <refentrytitle>ioctl CEC_RECEIVE, CEC_TRANSMIT</refentrytitle> + &manvol; + </refmeta> + + <refnamediv> + <refname>CEC_RECEIVE</refname> + <refname>CEC_TRANSMIT</refname> + <refpurpose>Receive or transmit a CEC message</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>ioctl</function></funcdef> + <paramdef>int <parameter>fd</parameter></paramdef> + <paramdef>int <parameter>request</parameter></paramdef> + <paramdef>struct cec_msg *<parameter>argp</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Arguments</title> + + <variablelist> + <varlistentry> + <term><parameter>fd</parameter></term> + <listitem> + <para>File descriptor returned by + <link linkend='cec-func-open'><function>open()</function></link>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>request</parameter></term> + <listitem> + <para>CEC_RECEIVE, CEC_TRANSMIT</para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>argp</parameter></term> + <listitem> + <para></para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Description</title> + + <para> + Note: this documents the proposed CEC API. This API is not yet finalized and + is currently only available as a staging kernel module. + </para> + + <para>To receive a CEC message the application has to fill in the + <structname>cec_msg</structname> structure and pass it to the + <constant>CEC_RECEIVE</constant> ioctl. <constant>CEC_RECEIVE</constant> is + only available if <constant>CEC_CAP_RECEIVE</constant> is set. If the + file descriptor is in non-blocking mode and there are no received + messages pending, then it will return -1 and set errno to the &EAGAIN;. + If the file descriptor is in blocking mode and <structfield>timeout</structfield> + is non-zero and no message arrived within <structfield>timeout</structfield> + milliseconds, then it will return -1 and set errno to the &ETIMEDOUT;.</para> + + <para>To send a CEC message the application has to fill in the + <structname>cec_msg</structname> structure and pass it to the + <constant>CEC_TRANSMIT</constant> ioctl. <constant>CEC_TRANSMIT</constant> is + only available if <constant>CEC_CAP_TRANSMIT</constant> is set. + If there is no more room in the transmit queue, then it will return + -1 and set errno to the &EBUSY;.</para> + + <table pgwide="1" frame="none" id="cec-msg"> + <title>struct <structname>cec_msg</structname></title> + <tgroup cols="3"> + &cs-str; + <tbody valign="top"> + <row> + <entry>__u64</entry> + <entry><structfield>ts</structfield></entry> + <entry>Timestamp of when the message was transmitted in ns in the case + of <constant>CEC_TRANSMIT</constant> with <structfield>reply</structfield> + set to 0, or the timestamp of the received message in all other cases.</entry> + </row> + <row> + <entry>__u32</entry> + <entry><structfield>len</structfield></entry> + <entry>The length of the message. For <constant>CEC_TRANSMIT</constant> this + is filled in by the application. The driver will fill this in for + <constant>CEC_RECEIVE</constant> and for <constant>CEC_TRANSMIT</constant> + it will be filled in with the length of the reply message if + <structfield>reply</structfield> was set.</entry> + </row> + <row> + <entry>__u32</entry> + <entry><structfield>timeout</structfield></entry> + <entry>The timeout in milliseconds. This is the time the device will wait for a message to + be received before timing out. If it is set to 0, then it will wait indefinitely when it + is called by <constant>CEC_RECEIVE</constant>. If it is 0 and it is called by + <constant>CEC_TRANSMIT</constant>, then it will be replaced by 1000 if the + <structfield>reply</structfield> is non-zero or ignored if <structfield>reply</structfield> + is 0.</entry> + </row> + <row> + <entry>__u32</entry> + <entry><structfield>sequence</structfield></entry> + <entry>The sequence number is automatically assigned by the CEC + framework for all transmitted messages. It can be later used by the + framework to generate an event if a reply for a message was + requested and the message was transmitted in a non-blocking mode. + </entry> + </row> + <row> + <entry>__u32</entry> + <entry><structfield>flags</structfield></entry> + <entry>Flags. No flags are defined yet, so set this to 0.</entry> + </row> + <row> + <entry>__u8</entry> + <entry><structfield>rx_status</structfield></entry> + <entry>The status bits of the received message. See <xref linkend="cec-rx-status" /> + for the possible status values. It is 0 if this message was transmitted, not + received, unless this is the reply to a transmitted message. In that case both + <structfield>rx_status</structfield> and <structfield>tx_status</structfield> + are set.</entry> + </row> + <row> + <entry>__u8</entry> + <entry><structfield>tx_status</structfield></entry> + <entry>The status bits of the transmitted message. See <xref linkend="cec-tx-status" /> + for the possible status values. It is 0 if this messages was received, not + transmitted.</entry> + </row> + <row> + <entry>__u8</entry> + <entry><structfield>msg</structfield>[16]</entry> + <entry>The message payload. For <constant>CEC_TRANSMIT</constant> this + is filled in by the application. The driver will fill this in for + <constant>CEC_RECEIVE</constant> and for <constant>CEC_TRANSMIT</constant> + it will be filled in with the payload of the reply message if + <structfield>reply</structfield> was set.</entry> + </row> + <row> + <entry>__u8</entry> + <entry><structfield>reply</structfield></entry> + <entry>Wait until this message is replied. If <structfield>reply</structfield> + is 0 and the <structfield>timeout</structfield> is 0, then don't wait for a reply but + return after transmitting the message. If there was an error as indicated by a non-zero + <structfield>tx_status</structfield> field, then <structfield>reply</structfield> and + <structfield>timeout</structfield> are both set to 0 by the driver. Ignored by + <constant>CEC_RECEIVE</constant>. The case where <structfield>reply</structfield> is 0 + (this is the opcode for the Feature Abort message) and <structfield>timeout</structfield> + is non-zero is specifically allowed to send a message and wait up to <structfield>timeout</structfield> + milliseconds for a Feature Abort reply. In this case <structfield>rx_status</structfield> + will either be set to <constant>CEC_RX_STATUS_TIMEOUT</constant> or + <constant>CEC_RX_STATUS_FEATURE_ABORT</constant>.</entry> + </row> + <row> + <entry>__u8</entry> + <entry><structfield>tx_arb_lost_cnt</structfield></entry> + <entry>A counter of the number of transmit attempts that resulted in the + Arbitration Lost error. This is only set if the hardware supports this, otherwise + it is always 0. This counter is only valid if the <constant>CEC_TX_STATUS_ARB_LOST</constant> + status bit is set.</entry> + </row> + <row> + <entry>__u8</entry> + <entry><structfield>tx_nack_cnt</structfield></entry> + <entry>A counter of the number of transmit attempts that resulted in the + Not Acknowledged error. This is only set if the hardware supports this, otherwise + it is always 0. This counter is only valid if the <constant>CEC_TX_STATUS_NACK</constant> + status bit is set.</entry> + </row> + <row> + <entry>__u8</entry> + <entry><structfield>tx_low_drive_cnt</structfield></entry> + <entry>A counter of the number of transmit attempts that resulted in the + Arbitration Lost error. This is only set if the hardware supports this, otherwise + it is always 0. This counter is only valid if the <constant>CEC_TX_STATUS_LOW_DRIVE</constant> + status bit is set.</entry> + </row> + <row> + <entry>__u8</entry> + <entry><structfield>tx_error_cnt</structfield></entry> + <entry>A counter of the number of transmit errors other than Arbitration Lost + or Not Acknowledged. This is only set if the hardware supports this, otherwise + it is always 0. This counter is only valid if the <constant>CEC_TX_STATUS_ERROR</constant> + status bit is set.</entry> + </row> + </tbody> + </tgroup> + </table> + + <table pgwide="1" frame="none" id="cec-tx-status"> + <title>CEC Transmit Status</title> + <tgroup cols="3"> + &cs-def; + <tbody valign="top"> + <row> + <entry><constant>CEC_TX_STATUS_OK</constant></entry> + <entry>0x01</entry> + <entry>The message was transmitted successfully. This is mutually exclusive with + <constant>CEC_TX_STATUS_MAX_RETRIES</constant>. Other bits can still be set if + earlier attempts met with failure before the transmit was eventually successful.</entry> + </row> + <row> + <entry><constant>CEC_TX_STATUS_ARB_LOST</constant></entry> + <entry>0x02</entry> + <entry>CEC line arbitration was lost.</entry> + </row> + <row> + <entry><constant>CEC_TX_STATUS_NACK</constant></entry> + <entry>0x04</entry> + <entry>Message was not acknowledged.</entry> + </row> + <row> + <entry><constant>CEC_TX_STATUS_LOW_DRIVE</constant></entry> + <entry>0x08</entry> + <entry>Low drive was detected on the CEC bus. This indicates that a follower + detected an error on the bus and requests a retransmission.</entry> + </row> + <row> + <entry><constant>CEC_TX_STATUS_ERROR</constant></entry> + <entry>0x10</entry> + <entry>Some error occurred. This is used for any errors that do not + fit the previous two, either because the hardware could not tell + which error occurred, or because the hardware tested for other conditions + besides those two.</entry> + </row> + <row> + <entry><constant>CEC_TX_STATUS_MAX_RETRIES</constant></entry> + <entry>0x20</entry> + <entry>The transmit failed after one or more retries. This status bit is mutually + exclusive with <constant>CEC_TX_STATUS_OK</constant>. Other bits can still be set + to explain which failures were seen.</entry> + </row> + </tbody> + </tgroup> + </table> + + <table pgwide="1" frame="none" id="cec-rx-status"> + <title>CEC Receive Status</title> + <tgroup cols="3"> + &cs-def; + <tbody valign="top"> + <row> + <entry><constant>CEC_RX_STATUS_OK</constant></entry> + <entry>0x01</entry> + <entry>The message was received successfully.</entry> + </row> + <row> + <entry><constant>CEC_RX_STATUS_TIMEOUT</constant></entry> + <entry>0x02</entry> + <entry>The reply to an earlier transmitted message timed out.</entry> + </row> + <row> + <entry><constant>CEC_RX_STATUS_FEATURE_ABORT</constant></entry> + <entry>0x04</entry> + <entry>The message was received successfully but the reply was + <constant>CEC_MSG_FEATURE_ABORT</constant>. This status is only + set if this message was the reply to an earlier transmitted + message.</entry> + </row> + </tbody> + </tgroup> + </table> + </refsect1> + + <refsect1> + &return-value; + </refsect1> +</refentry> diff --git a/Documentation/DocBook/media/v4l/io.xml b/Documentation/DocBook/media/v4l/io.xml index e09025db92bd..21a3dde8f95d 100644 --- a/Documentation/DocBook/media/v4l/io.xml +++ b/Documentation/DocBook/media/v4l/io.xml @@ -88,7 +88,7 @@ function.<footnote> <structfield>capabilities</structfield> field of &v4l2-capability; returned by the &VIDIOC-QUERYCAP; ioctl is set. There are two streaming methods, to determine if the memory mapping flavor is -supported applications must call the &VIDIOC-REQBUFS; ioctl.</para> +supported applications must call the &VIDIOC-REQBUFS; ioctl with the memory type set to <constant>V4L2_MEMORY_MMAP</constant>.</para> <para>Streaming is an I/O method where only pointers to buffers are exchanged between application and driver, the data itself is not @@ -369,7 +369,7 @@ rest should be evident.</para> <structfield>capabilities</structfield> field of &v4l2-capability; returned by the &VIDIOC-QUERYCAP; ioctl is set. If the particular user pointer method (not only memory mapping) is supported must be -determined by calling the &VIDIOC-REQBUFS; ioctl.</para> +determined by calling the &VIDIOC-REQBUFS; ioctl with the memory type set to <constant>V4L2_MEMORY_USERPTR</constant>.</para> <para>This I/O method combines advantages of the read/write and memory mapping methods. Buffers (planes) are allocated by the application diff --git a/Documentation/DocBook/media/v4l/lirc_device_interface.xml b/Documentation/DocBook/media/v4l/lirc_device_interface.xml index 34cada2ca710..71f9dbb81ec7 100644 --- a/Documentation/DocBook/media/v4l/lirc_device_interface.xml +++ b/Documentation/DocBook/media/v4l/lirc_device_interface.xml @@ -157,7 +157,7 @@ on working with the default settings initially.</para> <varlistentry> <term>LIRC_SET_{SEND,REC}_CARRIER</term> <listitem> - <para>Set send/receive carrier (in Hz).</para> + <para>Set send/receive carrier (in Hz). Return 0 on success.</para> </listitem> </varlistentry> <varlistentry> diff --git a/Documentation/DocBook/media/v4l/media-types.xml b/Documentation/DocBook/media/v4l/media-types.xml index 5e3f20fdcf17..95aa1f9c836a 100644 --- a/Documentation/DocBook/media/v4l/media-types.xml +++ b/Documentation/DocBook/media/v4l/media-types.xml @@ -121,6 +121,70 @@ <entry><constant>MEDIA_ENT_F_AUDIO_MIXER</constant></entry> <entry>Audio Mixer Function Entity.</entry> </row> + <row> + <entry><constant>MEDIA_ENT_F_PROC_VIDEO_COMPOSER</constant></entry> + <entry>Video composer (blender). An entity capable of video + composing must have at least two sink pads and one source + pad, and composes input video frames onto output video + frames. Composition can be performed using alpha blending, + color keying, raster operations (ROP), stitching or any other + means. + </entry> + </row> + <row> + <entry><constant>MEDIA_ENT_F_PROC_VIDEO_PIXEL_FORMATTER</constant></entry> + <entry>Video pixel formatter. An entity capable of pixel formatting + must have at least one sink pad and one source pad. Read + pixel formatters read pixels from memory and perform a subset + of unpacking, cropping, color keying, alpha multiplication + and pixel encoding conversion. Write pixel formatters perform + a subset of dithering, pixel encoding conversion and packing + and write pixels to memory. + </entry> + </row> + <row> + <entry><constant>MEDIA_ENT_F_PROC_VIDEO_PIXEL_ENC_CONV</constant></entry> + <entry>Video pixel encoding converter. An entity capable of pixel + enconding conversion must have at least one sink pad and one + source pad, and convert the encoding of pixels received on + its sink pad(s) to a different encoding output on its source + pad(s). Pixel encoding conversion includes but isn't limited + to RGB to/from HSV, RGB to/from YUV and CFA (Bayer) to RGB + conversions. + </entry> + </row> + <row> + <entry><constant>MEDIA_ENT_F_PROC_VIDEO_LUT</constant></entry> + <entry>Video look-up table. An entity capable of video lookup table + processing must have one sink pad and one source pad. It uses + the values of the pixels received on its sink pad to look up + entries in internal tables and output them on its source pad. + The lookup processing can be performed on all components + separately or combine them for multi-dimensional table + lookups. + </entry> + </row> + <row> + <entry><constant>MEDIA_ENT_F_PROC_VIDEO_SCALER</constant></entry> + <entry>Video scaler. An entity capable of video scaling must have + at least one sink pad and one source pad, and scale the + video frame(s) received on its sink pad(s) to a different + resolution output on its source pad(s). The range of + supported scaling ratios is entity-specific and can differ + between the horizontal and vertical directions (in particular + scaling can be supported in one direction only). Binning and + skipping are considered as scaling. + </entry> + </row> + <row> + <entry><constant>MEDIA_ENT_F_PROC_VIDEO_STATISTICS</constant></entry> + <entry>Video statistics computation (histogram, 3A, ...). An entity + capable of statistics computation must have one sink pad and + one source pad. It computes statistics over the frames + received on its sink pad and outputs the statistics data on + its source pad. + </entry> + </row> </tbody> </tgroup> </table> diff --git a/Documentation/DocBook/media/v4l/pixfmt-z16.xml b/Documentation/DocBook/media/v4l/pixfmt-z16.xml index 3d87e4bf87b8..1d9cb1684bd3 100644 --- a/Documentation/DocBook/media/v4l/pixfmt-z16.xml +++ b/Documentation/DocBook/media/v4l/pixfmt-z16.xml @@ -5,7 +5,7 @@ </refmeta> <refnamediv> <refname><constant>V4L2_PIX_FMT_Z16</constant></refname> - <refpurpose>Interleaved grey-scale image, e.g. from a stereo-pair</refpurpose> + <refpurpose>16-bit depth data with distance values at each pixel</refpurpose> </refnamediv> <refsect1> <title>Description</title> diff --git a/Documentation/DocBook/media/v4l/vidioc-reqbufs.xml b/Documentation/DocBook/media/v4l/vidioc-reqbufs.xml index 0f193fda0470..6f529e100ea4 100644 --- a/Documentation/DocBook/media/v4l/vidioc-reqbufs.xml +++ b/Documentation/DocBook/media/v4l/vidioc-reqbufs.xml @@ -6,7 +6,7 @@ <refnamediv> <refname>VIDIOC_REQBUFS</refname> - <refpurpose>Initiate Memory Mapping or User Pointer I/O</refpurpose> + <refpurpose>Initiate Memory Mapping, User Pointer or DMA Buffer I/O</refpurpose> </refnamediv> <refsynopsisdiv> diff --git a/Documentation/DocBook/media_api.tmpl b/Documentation/DocBook/media_api.tmpl index 7b77e0f7b87d..a2765d8ad05c 100644 --- a/Documentation/DocBook/media_api.tmpl +++ b/Documentation/DocBook/media_api.tmpl @@ -75,7 +75,7 @@ </mediaobject> </figure> <para>The media infrastructure API was designed to control such - devices. It is divided into four parts.</para> + devices. It is divided into five parts.</para> <para>The first part covers radio, video capture and output, cameras, analog TV devices and codecs.</para> <para>The second part covers the @@ -87,6 +87,7 @@ <xref linkend="fe-delivery-system-t" />.</para> <para>The third part covers the Remote Controller API.</para> <para>The fourth part covers the Media Controller API.</para> + <para>The fifth part covers the CEC (Consumer Electronics Control) API.</para> <para>It should also be noted that a media device may also have audio components, like mixers, PCM capture, PCM playback, etc, which are controlled via ALSA API.</para> @@ -107,6 +108,9 @@ <part id="media_common"> &sub-media-controller; </part> +<part id="cec"> +&sub-cec-api; +</part> <chapter id="gen_errors"> &sub-gen-errors; diff --git a/Documentation/Makefile.sphinx b/Documentation/Makefile.sphinx new file mode 100644 index 000000000000..d8d13c92a178 --- /dev/null +++ b/Documentation/Makefile.sphinx @@ -0,0 +1,78 @@ +# -*- makefile -*- +# Makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXBUILD = sphinx-build +SPHINXOPTS = +PAPER = +BUILDDIR = $(obj)/output + +# User-friendly check for sphinx-build +HAVE_SPHINX := $(shell if which $(SPHINXBUILD) >/dev/null 2>&1; then echo 1; else echo 0; fi) + +ifeq ($(HAVE_SPHINX),0) + +.DEFAULT: + $(warning The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed and in PATH, or set the SPHINXBUILD make variable to point to the full path of the '$(SPHINXBUILD)' executable.) + @echo " SKIP Sphinx $@ target." + +else ifneq ($(DOCBOOKS),) + +# Skip Sphinx build if the user explicitly requested DOCBOOKS. +.DEFAULT: + @echo " SKIP Sphinx $@ target (DOCBOOKS specified)." + +else # HAVE_SPHINX + +# User-friendly check for rst2pdf +HAVE_RST2PDF := $(shell if python -c "import rst2pdf" >/dev/null 2>&1; then echo 1; else echo 0; fi) + +# Internal variables. +PAPEROPT_a4 = -D latex_paper_size=a4 +PAPEROPT_letter = -D latex_paper_size=letter +KERNELDOC = $(srctree)/scripts/kernel-doc +KERNELDOC_CONF = -D kerneldoc_srctree=$(srctree) -D kerneldoc_bin=$(KERNELDOC) +ALLSPHINXOPTS = -D version=$(KERNELVERSION) -D release=$(KERNELRELEASE) -d $(BUILDDIR)/.doctrees $(KERNELDOC_CONF) $(PAPEROPT_$(PAPER)) -c $(srctree)/$(src) $(SPHINXOPTS) $(srctree)/$(src) +# the i18n builder cannot share the environment and doctrees with the others +I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . + +quiet_cmd_sphinx = SPHINX $@ + cmd_sphinx = $(SPHINXBUILD) -b $2 $(ALLSPHINXOPTS) $(BUILDDIR)/$2 + +htmldocs: + $(call cmd,sphinx,html) + +pdfdocs: +ifeq ($(HAVE_RST2PDF),0) + $(warning The Python 'rst2pdf' module was not found. Make sure you have the module installed to produce PDF output.) + @echo " SKIP Sphinx $@ target." +else # HAVE_RST2PDF + $(call cmd,sphinx,pdf) +endif # HAVE_RST2PDF + +epubdocs: + $(call cmd,sphinx,epub) + +xmldocs: + $(call cmd,sphinx,xml) + +# no-ops for the Sphinx toolchain +sgmldocs: +psdocs: +mandocs: +installmandocs: +cleanmediadocs: + +cleandocs: + $(Q)rm -rf $(BUILDDIR) + +dochelp: + @echo ' Linux kernel internal documentation in different formats (Sphinx):' + @echo ' htmldocs - HTML' + @echo ' pdfdocs - PDF' + @echo ' epubdocs - EPUB' + @echo ' xmldocs - XML' + @echo ' cleandocs - clean all generated files' + +endif # HAVE_SPHINX diff --git a/Documentation/RCU/Design/Requirements/Requirements.html b/Documentation/RCU/Design/Requirements/Requirements.html index e7e24b3e86e2..ece410f40436 100644 --- a/Documentation/RCU/Design/Requirements/Requirements.html +++ b/Documentation/RCU/Design/Requirements/Requirements.html @@ -2391,6 +2391,41 @@ and <tt>RCU_NONIDLE()</tt> on the other while inspecting idle-loop code. Steven Rostedt supplied <tt>_rcuidle</tt> event tracing, which is used quite heavily in the idle loop. +However, there are some restrictions on the code placed within +<tt>RCU_NONIDLE()</tt>: + +<ol> +<li> Blocking is prohibited. + In practice, this is not a serious restriction given that idle + tasks are prohibited from blocking to begin with. +<li> Although nesting <tt>RCU_NONIDLE()</tt> is permited, they cannot + nest indefinitely deeply. + However, given that they can be nested on the order of a million + deep, even on 32-bit systems, this should not be a serious + restriction. + This nesting limit would probably be reached long after the + compiler OOMed or the stack overflowed. +<li> Any code path that enters <tt>RCU_NONIDLE()</tt> must sequence + out of that same <tt>RCU_NONIDLE()</tt>. + For example, the following is grossly illegal: + + <blockquote> + <pre> + 1 RCU_NONIDLE({ + 2 do_something(); + 3 goto bad_idea; /* BUG!!! */ + 4 do_something_else();}); + 5 bad_idea: + </pre> + </blockquote> + + <p> + It is just as illegal to transfer control into the middle of + <tt>RCU_NONIDLE()</tt>'s argument. + Yes, in theory, you could transfer in as long as you also + transferred out, but in practice you could also expect to get sharply + worded review comments. +</ol> <p> It is similarly socially unacceptable to interrupt an diff --git a/Documentation/RCU/stallwarn.txt b/Documentation/RCU/stallwarn.txt index 0f7fb4298e7e..e93d04133fe7 100644 --- a/Documentation/RCU/stallwarn.txt +++ b/Documentation/RCU/stallwarn.txt @@ -49,7 +49,7 @@ rcupdate.rcu_task_stall_timeout This boot/sysfs parameter controls the RCU-tasks stall warning interval. A value of zero or less suppresses RCU-tasks stall warnings. A positive value sets the stall-warning interval - in jiffies. An RCU-tasks stall warning starts wtih the line: + in jiffies. An RCU-tasks stall warning starts with the line: INFO: rcu_tasks detected stalls on tasks: diff --git a/Documentation/RCU/whatisRCU.txt b/Documentation/RCU/whatisRCU.txt index 111770ffa10e..204422719197 100644 --- a/Documentation/RCU/whatisRCU.txt +++ b/Documentation/RCU/whatisRCU.txt @@ -5,6 +5,9 @@ to start learning about RCU: 2. What is RCU? Part 2: Usage http://lwn.net/Articles/263130/ 3. RCU part 3: the RCU API http://lwn.net/Articles/264090/ 4. The RCU API, 2010 Edition http://lwn.net/Articles/418853/ + 2010 Big API Table http://lwn.net/Articles/419086/ +5. The RCU API, 2014 Edition http://lwn.net/Articles/609904/ + 2014 Big API Table http://lwn.net/Articles/609973/ What is RCU? diff --git a/Documentation/acpi/aml-debugger.txt b/Documentation/acpi/aml-debugger.txt new file mode 100644 index 000000000000..5f62aa4a493b --- /dev/null +++ b/Documentation/acpi/aml-debugger.txt @@ -0,0 +1,66 @@ +The AML Debugger + +Copyright (C) 2016, Intel Corporation +Author: Lv Zheng <lv.zheng@intel.com> + + +This document describes the usage of the AML debugger embedded in the Linux +kernel. + +1. Build the debugger + + The following kernel configuration items are required to enable the AML + debugger interface from the Linux kernel: + + CONFIG_ACPI_DEBUGGER=y + CONFIG_ACPI_DEBUGGER_USER=m + + The userspace utlities can be built from the kernel source tree using + the following commands: + + $ cd tools + $ make acpi + + The resultant userspace tool binary is then located at: + + tools/acpi/power/acpi/acpidbg/acpidbg + + It can be installed to system directories by running "make install" (as a + sufficiently privileged user). + +2. Start the userspace debugger interface + + After booting the kernel with the debugger built-in, the debugger can be + started by using the following commands: + + # mount -t debugfs none /sys/kernel/debug + # modprobe acpi_dbg + # tools/acpi/power/acpi/acpidbg/acpidbg + + That spawns the interactive AML debugger environment where you can execute + debugger commands. + + The commands are documented in the "ACPICA Overview and Programmer Reference" + that can be downloaded from + + https://acpica.org/documentation + + The detailed debugger commands reference is located in Chapter 12 "ACPICA + Debugger Reference". The "help" command can be used for a quick reference. + +3. Stop the userspace debugger interface + + The interactive debugger interface can be closed by pressing Ctrl+C or using + the "quit" or "exit" commands. When finished, unload the module with: + + # rmmod acpi_dbg + + The module unloading may fail if there is an acpidbg instance running. + +4. Run the debugger in a script + + It may be useful to run the AML debugger in a test script. "acpidbg" supports + this in a special "batch" mode. For example, the following command outputs + the entire ACPI namespace: + + # acpidbg -b "namespace" diff --git a/Documentation/acpi/linuxized-acpica.txt b/Documentation/acpi/linuxized-acpica.txt new file mode 100644 index 000000000000..defe2eec5331 --- /dev/null +++ b/Documentation/acpi/linuxized-acpica.txt @@ -0,0 +1,262 @@ +Linuxized ACPICA - Introduction to ACPICA Release Automation + +Copyright (C) 2013-2016, Intel Corporation +Author: Lv Zheng <lv.zheng@intel.com> + + +Abstract: + +This document describes the ACPICA project and the relationship between +ACPICA and Linux. It also describes how ACPICA code in drivers/acpi/acpica, +include/acpi and tools/power/acpi is automatically updated to follow the +upstream. + + +1. ACPICA Project + + The ACPI Component Architecture (ACPICA) project provides an operating + system (OS)-independent reference implementation of the Advanced + Configuration and Power Interface Specification (ACPI). It has been + adapted by various host OSes. By directly integrating ACPICA, Linux can + also benefit from the application experiences of ACPICA from other host + OSes. + + The homepage of ACPICA project is: www.acpica.org, it is maintained and + supported by Intel Corporation. + + The following figure depicts the Linux ACPI subystem where the ACPICA + adaptation is included: + + +---------------------------------------------------------+ + | | + | +---------------------------------------------------+ | + | | +------------------+ | | + | | | Table Management | | | + | | +------------------+ | | + | | +----------------------+ | | + | | | Namespace Management | | | + | | +----------------------+ | | + | | +------------------+ ACPICA Components | | + | | | Event Management | | | + | | +------------------+ | | + | | +---------------------+ | | + | | | Resource Management | | | + | | +---------------------+ | | + | | +---------------------+ | | + | | | Hardware Management | | | + | | +---------------------+ | | + | +---------------------------------------------------+ | | + | | | +------------------+ | | | + | | | | OS Service Layer | | | | + | | | +------------------+ | | | + | | +-------------------------------------------------|-+ | + | | +--------------------+ | | + | | | Device Enumeration | | | + | | +--------------------+ | | + | | +------------------+ | | + | | | Power Management | | | + | | +------------------+ Linux/ACPI Components | | + | | +--------------------+ | | + | | | Thermal Management | | | + | | +--------------------+ | | + | | +--------------------------+ | | + | | | Drivers for ACPI Devices | | | + | | +--------------------------+ | | + | | +--------+ | | + | | | ...... | | | + | | +--------+ | | + | +---------------------------------------------------+ | + | | + +---------------------------------------------------------+ + + Figure 1. Linux ACPI Software Components + + NOTE: + A. OS Service Layer - Provided by Linux to offer OS dependent + implementation of the predefined ACPICA interfaces (acpi_os_*). + include/acpi/acpiosxf.h + drivers/acpi/osl.c + include/acpi/platform + include/asm/acenv.h + B. ACPICA Functionality - Released from ACPICA code base to offer + OS independent implementation of the ACPICA interfaces (acpi_*). + drivers/acpi/acpica + include/acpi/ac*.h + tools/power/acpi + C. Linux/ACPI Functionality - Providing Linux specific ACPI + functionality to the other Linux kernel subsystems and user space + programs. + drivers/acpi + include/linux/acpi.h + include/linux/acpi*.h + include/acpi + tools/power/acpi + D. Architecture Specific ACPICA/ACPI Functionalities - Provided by the + ACPI subsystem to offer architecture specific implementation of the + ACPI interfaces. They are Linux specific components and are out of + the scope of this document. + include/asm/acpi.h + include/asm/acpi*.h + arch/*/acpi + +2. ACPICA Release + + The ACPICA project maintains its code base at the following repository URL: + https://github.com/acpica/acpica.git. As a rule, a release is made every + month. + + As the coding style adopted by the ACPICA project is not acceptable by + Linux, there is a release process to convert the ACPICA git commits into + Linux patches. The patches generated by this process are referred to as + "linuxized ACPICA patches". The release process is carried out on a local + copy the ACPICA git repository. Each commit in the monthly release is + converted into a linuxized ACPICA patch. Together, they form the montly + ACPICA release patchset for the Linux ACPI community. This process is + illustrated in the following figure: + + +-----------------------------+ + | acpica / master (-) commits | + +-----------------------------+ + /|\ | + | \|/ + | /---------------------\ +----------------------+ + | < Linuxize repo Utility >-->| old linuxized acpica |--+ + | \---------------------/ +----------------------+ | + | | + /---------\ | + < git reset > \ + \---------/ \ + /|\ /+-+ + | / | + +-----------------------------+ | | + | acpica / master (+) commits | | | + +-----------------------------+ | | + | | | + \|/ | | + /-----------------------\ +----------------------+ | | + < Linuxize repo Utilities >-->| new linuxized acpica |--+ | + \-----------------------/ +----------------------+ | + \|/ + +--------------------------+ /----------------------\ + | Linuxized ACPICA Patches |<----------------< Linuxize patch Utility > + +--------------------------+ \----------------------/ + | + \|/ + /---------------------------\ + < Linux ACPI Community Review > + \---------------------------/ + | + \|/ + +-----------------------+ /------------------\ +----------------+ + | linux-pm / linux-next |-->< Linux Merge Window >-->| linux / master | + +-----------------------+ \------------------/ +----------------+ + + Figure 2. ACPICA -> Linux Upstream Process + + NOTE: + A. Linuxize Utilities - Provided by the ACPICA repository, including a + utility located in source/tools/acpisrc folder and a number of + scripts located in generate/linux folder. + B. acpica / master - "master" branch of the git repository at + <https://github.com/acpica/acpica.git>. + C. linux-pm / linux-next - "linux-next" branch of the git repository at + <http://git.kernel.org/pub/scm/linux/kernel/git/rafael/linux-pm.git>. + D. linux / master - "master" branch of the git repository at + <http://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git>. + + Before the linuxized ACPICA patches are sent to the Linux ACPI community + for review, there is a quality ensurance build test process to reduce + porting issues. Currently this build process only takes care of the + following kernel configuration options: + CONFIG_ACPI/CONFIG_ACPI_DEBUG/CONFIG_ACPI_DEBUGGER + +3. ACPICA Divergences + + Ideally, all of the ACPICA commits should be converted into Linux patches + automatically without manual modifications, the "linux / master" tree should + contain the ACPICA code that exactly corresponds to the ACPICA code + contained in "new linuxized acpica" tree and it should be possible to run + the release process fully automatically. + + As a matter of fact, however, there are source code differences between + the ACPICA code in Linux and the upstream ACPICA code, referred to as + "ACPICA Divergences". + + The various sources of ACPICA divergences include: + 1. Legacy divergences - Before the current ACPICA release process was + established, there already had been divergences between Linux and + ACPICA. Over the past several years those divergences have been greatly + reduced, but there still are several ones and it takes time to figure + out the underlying reasons for their existence. + 2. Manual modifications - Any manual modification (eg. coding style fixes) + made directly in the Linux sources obviously hurts the ACPICA release + automation. Thus it is recommended to fix such issues in the ACPICA + upstream source code and generate the linuxized fix using the ACPICA + release utilities (please refer to Section 4 below for the details). + 3. Linux specific features - Sometimes it's impossible to use the + current ACPICA APIs to implement features required by the Linux kernel, + so Linux developers occasionaly have to change ACPICA code directly. + Those changes may not be acceptable by ACPICA upstream and in such cases + they are left as committed ACPICA divergences unless the ACPICA side can + implement new mechanisms as replacements for them. + 4. ACPICA release fixups - ACPICA only tests commits using a set of the + user space simulation utilies, thus the linuxized ACPICA patches may + break the Linux kernel, leaving us build/boot failures. In order to + avoid breaking Linux bisection, fixes are applied directly to the + linuxized ACPICA patches during the release process. When the release + fixups are backported to the upstream ACPICA sources, they must follow + the upstream ACPICA rules and so further modifications may appear. + That may result in the appearance of new divergences. + 5. Fast tracking of ACPICA commits - Some ACPICA commits are regression + fixes or stable-candidate material, so they are applied in advance with + respect to the ACPICA release process. If such commits are reverted or + rebased on the ACPICA side in order to offer better solutions, new ACPICA + divergences are generated. + +4. ACPICA Development + + This paragraph guides Linux developers to use the ACPICA upstream release + utilities to obtain Linux patches corresponding to upstream ACPICA commits + before they become available from the ACPICA release process. + + 1. Cherry-pick an ACPICA commit + + First you need to git clone the ACPICA repository and the ACPICA change + you want to cherry pick must be committed into the local repository. + + Then the gen-patch.sh command can help to cherry-pick an ACPICA commit + from the ACPICA local repository: + + $ git clone https://github.com/acpica/acpica + $ cd acpica + $ generate/linux/gen-patch.sh -u [commit ID] + + Here the commit ID is the ACPICA local repository commit ID you want to + cherry pick. It can be omitted if the commit is "HEAD". + + 2. Cherry-pick recent ACPICA commits + + Sometimes you need to rebase your code on top of the most recent ACPICA + changes that haven't been applied to Linux yet. + + You can generate the ACPICA release series yourself and rebase your code on + top of the generated ACPICA release patches: + + $ git clone https://github.com/acpica/acpica + $ cd acpica + $ generate/linux/make-patches.sh -u [commit ID] + + The commit ID should be the last ACPICA commit accepted by Linux. Usually, + it is the commit modifying ACPI_CA_VERSION. It can be found by executing + "git blame source/include/acpixf.h" and referencing the line that contains + "ACPI_CA_VERSION". + + 3. Inspect the current divergences + + If you have local copies of both Linux and upstream ACPICA, you can generate + a diff file indicating the state of the current divergences: + + # git clone https://github.com/acpica/acpica + # git clone http://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git + # cd acpica + # generate/linux/divergences.sh -s ../linux diff --git a/Documentation/acpi/ssdt-overlays.txt b/Documentation/acpi/ssdt-overlays.txt new file mode 100644 index 000000000000..5ae13f161ea2 --- /dev/null +++ b/Documentation/acpi/ssdt-overlays.txt @@ -0,0 +1,172 @@ + +In order to support ACPI open-ended hardware configurations (e.g. development +boards) we need a way to augment the ACPI configuration provided by the firmware +image. A common example is connecting sensors on I2C / SPI buses on development +boards. + +Although this can be accomplished by creating a kernel platform driver or +recompiling the firmware image with updated ACPI tables, neither is practical: +the former proliferates board specific kernel code while the latter requires +access to firmware tools which are often not publicly available. + +Because ACPI supports external references in AML code a more practical +way to augment firmware ACPI configuration is by dynamically loading +user defined SSDT tables that contain the board specific information. + +For example, to enumerate a Bosch BMA222E accelerometer on the I2C bus of the +Minnowboard MAX development board exposed via the LSE connector [1], the +following ASL code can be used: + +DefinitionBlock ("minnowmax.aml", "SSDT", 1, "Vendor", "Accel", 0x00000003) +{ + External (\_SB.I2C6, DeviceObj) + + Scope (\_SB.I2C6) + { + Device (STAC) + { + Name (_ADR, Zero) + Name (_HID, "BMA222E") + + Method (_CRS, 0, Serialized) + { + Name (RBUF, ResourceTemplate () + { + I2cSerialBus (0x0018, ControllerInitiated, 0x00061A80, + AddressingMode7Bit, "\\_SB.I2C6", 0x00, + ResourceConsumer, ,) + GpioInt (Edge, ActiveHigh, Exclusive, PullDown, 0x0000, + "\\_SB.GPO2", 0x00, ResourceConsumer, , ) + { // Pin list + 0 + } + }) + Return (RBUF) + } + } + } +} + +which can then be compiled to AML binary format: + +$ iasl minnowmax.asl + +Intel ACPI Component Architecture +ASL Optimizing Compiler version 20140214-64 [Mar 29 2014] +Copyright (c) 2000 - 2014 Intel Corporation + +ASL Input: minnomax.asl - 30 lines, 614 bytes, 7 keywords +AML Output: minnowmax.aml - 165 bytes, 6 named objects, 1 executable opcodes + +[1] http://wiki.minnowboard.org/MinnowBoard_MAX#Low_Speed_Expansion_Connector_.28Top.29 + +The resulting AML code can then be loaded by the kernel using one of the methods +below. + +== Loading ACPI SSDTs from initrd == + +This option allows loading of user defined SSDTs from initrd and it is useful +when the system does not support EFI or when there is not enough EFI storage. + +It works in a similar way with initrd based ACPI tables override/upgrade: SSDT +aml code must be placed in the first, uncompressed, initrd under the +"kernel/firmware/acpi" path. Multiple files can be used and this will translate +in loading multiple tables. Only SSDT and OEM tables are allowed. See +initrd_table_override.txt for more details. + +Here is an example: + +# Add the raw ACPI tables to an uncompressed cpio archive. +# They must be put into a /kernel/firmware/acpi directory inside the +# cpio archive. +# The uncompressed cpio archive must be the first. +# Other, typically compressed cpio archives, must be +# concatenated on top of the uncompressed one. +mkdir -p kernel/firmware/acpi +cp ssdt.aml kernel/firmware/acpi + +# Create the uncompressed cpio archive and concatenate the original initrd +# on top: +find kernel | cpio -H newc --create > /boot/instrumented_initrd +cat /boot/initrd >>/boot/instrumented_initrd + +== Loading ACPI SSDTs from EFI variables == + +This is the preferred method, when EFI is supported on the platform, because it +allows a persistent, OS independent way of storing the user defined SSDTs. There +is also work underway to implement EFI support for loading user defined SSDTs +and using this method will make it easier to convert to the EFI loading +mechanism when that will arrive. + +In order to load SSDTs from an EFI variable the efivar_ssdt kernel command line +parameter can be used. The argument for the option is the variable name to +use. If there are multiple variables with the same name but with different +vendor GUIDs, all of them will be loaded. + +In order to store the AML code in an EFI variable the efivarfs filesystem can be +used. It is enabled and mounted by default in /sys/firmware/efi/efivars in all +recent distribution. + +Creating a new file in /sys/firmware/efi/efivars will automatically create a new +EFI variable. Updating a file in /sys/firmware/efi/efivars will update the EFI +variable. Please note that the file name needs to be specially formatted as +"Name-GUID" and that the first 4 bytes in the file (little-endian format) +represent the attributes of the EFI variable (see EFI_VARIABLE_MASK in +include/linux/efi.h). Writing to the file must also be done with one write +operation. + +For example, you can use the following bash script to create/update an EFI +variable with the content from a given file: + +#!/bin/sh -e + +while ! [ -z "$1" ]; do + case "$1" in + "-f") filename="$2"; shift;; + "-g") guid="$2"; shift;; + *) name="$1";; + esac + shift +done + +usage() +{ + echo "Syntax: ${0##*/} -f filename [ -g guid ] name" + exit 1 +} + +[ -n "$name" -a -f "$filename" ] || usage + +EFIVARFS="/sys/firmware/efi/efivars" + +[ -d "$EFIVARFS" ] || exit 2 + +if stat -tf $EFIVARFS | grep -q -v de5e81e4; then + mount -t efivarfs none $EFIVARFS +fi + +# try to pick up an existing GUID +[ -n "$guid" ] || guid=$(find "$EFIVARFS" -name "$name-*" | head -n1 | cut -f2- -d-) + +# use a randomly generated GUID +[ -n "$guid" ] || guid="$(cat /proc/sys/kernel/random/uuid)" + +# efivarfs expects all of the data in one write +tmp=$(mktemp) +/bin/echo -ne "\007\000\000\000" | cat - $filename > $tmp +dd if=$tmp of="$EFIVARFS/$name-$guid" bs=$(stat -c %s $tmp) +rm $tmp + +== Loading ACPI SSDTs from configfs == + +This option allows loading of user defined SSDTs from userspace via the configfs +interface. The CONFIG_ACPI_CONFIGFS option must be select and configfs must be +mounted. In the following examples, we assume that configfs has been mounted in +/config. + +New tables can be loading by creating new directories in /config/acpi/table/ and +writing the SSDT aml code in the aml attribute: + +cd /config/acpi/table +mkdir my_ssdt +cat ~/ssdt.aml > my_ssdt/aml diff --git a/Documentation/bcache.txt b/Documentation/bcache.txt index 32b6c3189d98..a9259b562d5c 100644 --- a/Documentation/bcache.txt +++ b/Documentation/bcache.txt @@ -1,4 +1,4 @@ -Say you've got a big slow raid 6, and an X-25E or three. Wouldn't it be +Say you've got a big slow raid 6, and an ssd or three. Wouldn't it be nice if you could use them as cache... Hence bcache. Wiki and git repositories are at: @@ -8,7 +8,7 @@ Wiki and git repositories are at: It's designed around the performance characteristics of SSDs - it only allocates in erase block sized buckets, and it uses a hybrid btree/log to track cached -extants (which can be anywhere from a single sector to the bucket size). It's +extents (which can be anywhere from a single sector to the bucket size). It's designed to avoid random writes at all costs; it fills up an erase block sequentially, then issues a discard before reusing it. @@ -55,7 +55,10 @@ immediately. Without udev, you can manually register devices like this: Registering the backing device makes the bcache device show up in /dev; you can now format it and use it as normal. But the first time using a new bcache device, it'll be running in passthrough mode until you attach it to a cache. -See the section on attaching. +If you are thinking about using bcache later, it is recommended to setup all your +slow devices as bcache backing devices without a cache, and you can choose to add +a caching device later. +See 'ATTACHING' section below. The devices show up as: @@ -72,12 +75,14 @@ To get started: mount /dev/bcache0 /mnt You can control bcache devices through sysfs at /sys/block/bcache<N>/bcache . +You can also control them through /sys/fs//bcache/<cset-uuid>/ . Cache devices are managed as sets; multiple caches per set isn't supported yet but will allow for mirroring of metadata and dirty data in the future. Your new cache set shows up as /sys/fs/bcache/<UUID> -ATTACHING: +ATTACHING +--------- After your cache device and backing device are registered, the backing device must be attached to your cache set to enable caching. Attaching a backing @@ -105,7 +110,8 @@ but all the cached data will be invalidated. If there was dirty data in the cache, don't expect the filesystem to be recoverable - you will have massive filesystem corruption, though ext4's fsck does work miracles. -ERROR HANDLING: +ERROR HANDLING +-------------- Bcache tries to transparently handle IO errors to/from the cache device without affecting normal operation; if it sees too many errors (the threshold is @@ -127,12 +133,181 @@ the backing devices to passthrough mode. writeback mode). It currently doesn't do anything intelligent if it fails to read some of the dirty data, though. -TROUBLESHOOTING PERFORMANCE: + +HOWTO/COOKBOOK +-------------- + +A) Starting a bcache with a missing caching device + +If registering the backing device doesn't help, it's already there, you just need +to force it to run without the cache: + host:~# echo /dev/sdb1 > /sys/fs/bcache/register + [ 119.844831] bcache: register_bcache() error opening /dev/sdb1: device already registered + +Next, you try to register your caching device if it's present. However +if it's absent, or registration fails for some reason, you can still +start your bcache without its cache, like so: + host:/sys/block/sdb/sdb1/bcache# echo 1 > running + +Note that this may cause data loss if you were running in writeback mode. + + +B) Bcache does not find its cache + + host:/sys/block/md5/bcache# echo 0226553a-37cf-41d5-b3ce-8b1e944543a8 > attach + [ 1933.455082] bcache: bch_cached_dev_attach() Couldn't find uuid for md5 in set + [ 1933.478179] bcache: __cached_dev_store() Can't attach 0226553a-37cf-41d5-b3ce-8b1e944543a8 + [ 1933.478179] : cache set not found + +In this case, the caching device was simply not registered at boot +or disappeared and came back, and needs to be (re-)registered: + host:/sys/block/md5/bcache# echo /dev/sdh2 > /sys/fs/bcache/register + + +C) Corrupt bcache crashes the kernel at device registration time: + +This should never happen. If it does happen, then you have found a bug! +Please report it to the bcache development list: linux-bcache@vger.kernel.org + +Be sure to provide as much information that you can including kernel dmesg +output if available so that we may assist. + + +D) Recovering data without bcache: + +If bcache is not available in the kernel, a filesystem on the backing +device is still available at an 8KiB offset. So either via a loopdev +of the backing device created with --offset 8K, or any value defined by +--data-offset when you originally formatted bcache with `make-bcache`. + +For example: + losetup -o 8192 /dev/loop0 /dev/your_bcache_backing_dev + +This should present your unmodified backing device data in /dev/loop0 + +If your cache is in writethrough mode, then you can safely discard the +cache device without loosing data. + + +E) Wiping a cache device + +host:~# wipefs -a /dev/sdh2 +16 bytes were erased at offset 0x1018 (bcache) +they were: c6 85 73 f6 4e 1a 45 ca 82 65 f5 7f 48 ba 6d 81 + +After you boot back with bcache enabled, you recreate the cache and attach it: +host:~# make-bcache -C /dev/sdh2 +UUID: 7be7e175-8f4c-4f99-94b2-9c904d227045 +Set UUID: 5bc072a8-ab17-446d-9744-e247949913c1 +version: 0 +nbuckets: 106874 +block_size: 1 +bucket_size: 1024 +nr_in_set: 1 +nr_this_dev: 0 +first_bucket: 1 +[ 650.511912] bcache: run_cache_set() invalidating existing data +[ 650.549228] bcache: register_cache() registered cache device sdh2 + +start backing device with missing cache: +host:/sys/block/md5/bcache# echo 1 > running + +attach new cache: +host:/sys/block/md5/bcache# echo 5bc072a8-ab17-446d-9744-e247949913c1 > attach +[ 865.276616] bcache: bch_cached_dev_attach() Caching md5 as bcache0 on set 5bc072a8-ab17-446d-9744-e247949913c1 + + +F) Remove or replace a caching device + + host:/sys/block/sda/sda7/bcache# echo 1 > detach + [ 695.872542] bcache: cached_dev_detach_finish() Caching disabled for sda7 + + host:~# wipefs -a /dev/nvme0n1p4 + wipefs: error: /dev/nvme0n1p4: probing initialization failed: Device or resource busy + Ooops, it's disabled, but not unregistered, so it's still protected + +We need to go and unregister it: + host:/sys/fs/bcache/b7ba27a1-2398-4649-8ae3-0959f57ba128# ls -l cache0 + lrwxrwxrwx 1 root root 0 Feb 25 18:33 cache0 -> ../../../devices/pci0000:00/0000:00:1d.0/0000:70:00.0/nvme/nvme0/nvme0n1/nvme0n1p4/bcache/ + host:/sys/fs/bcache/b7ba27a1-2398-4649-8ae3-0959f57ba128# echo 1 > stop + kernel: [ 917.041908] bcache: cache_set_free() Cache set b7ba27a1-2398-4649-8ae3-0959f57ba128 unregistered + +Now we can wipe it: + host:~# wipefs -a /dev/nvme0n1p4 + /dev/nvme0n1p4: 16 bytes were erased at offset 0x00001018 (bcache): c6 85 73 f6 4e 1a 45 ca 82 65 f5 7f 48 ba 6d 81 + + +G) dm-crypt and bcache + +First setup bcache unencrypted and then install dmcrypt on top of +/dev/bcache<N> This will work faster than if you dmcrypt both the backing +and caching devices and then install bcache on top. [benchmarks?] + + +H) Stop/free a registered bcache to wipe and/or recreate it + +Suppose that you need to free up all bcache references so that you can +fdisk run and re-register a changed partition table, which won't work +if there are any active backing or caching devices left on it: + +1) Is it present in /dev/bcache* ? (there are times where it won't be) + +If so, it's easy: + host:/sys/block/bcache0/bcache# echo 1 > stop + +2) But if your backing device is gone, this won't work: + host:/sys/block/bcache0# cd bcache + bash: cd: bcache: No such file or directory + +In this case, you may have to unregister the dmcrypt block device that +references this bcache to free it up: + host:~# dmsetup remove oldds1 + bcache: bcache_device_free() bcache0 stopped + bcache: cache_set_free() Cache set 5bc072a8-ab17-446d-9744-e247949913c1 unregistered + +This causes the backing bcache to be removed from /sys/fs/bcache and +then it can be reused. This would be true of any block device stacking +where bcache is a lower device. + +3) In other cases, you can also look in /sys/fs/bcache/: + +host:/sys/fs/bcache# ls -l */{cache?,bdev?} +lrwxrwxrwx 1 root root 0 Mar 5 09:39 0226553a-37cf-41d5-b3ce-8b1e944543a8/bdev1 -> ../../../devices/virtual/block/dm-1/bcache/ +lrwxrwxrwx 1 root root 0 Mar 5 09:39 0226553a-37cf-41d5-b3ce-8b1e944543a8/cache0 -> ../../../devices/virtual/block/dm-4/bcache/ +lrwxrwxrwx 1 root root 0 Mar 5 09:39 5bc072a8-ab17-446d-9744-e247949913c1/cache0 -> ../../../devices/pci0000:00/0000:00:01.0/0000:01:00.0/ata10/host9/target9:0:0/9:0:0:0/block/sdl/sdl2/bcache/ + +The device names will show which UUID is relevant, cd in that directory +and stop the cache: + host:/sys/fs/bcache/5bc072a8-ab17-446d-9744-e247949913c1# echo 1 > stop + +This will free up bcache references and let you reuse the partition for +other purposes. + + + +TROUBLESHOOTING PERFORMANCE +--------------------------- Bcache has a bunch of config options and tunables. The defaults are intended to be reasonable for typical desktop and server workloads, but they're not what you want for getting the best possible numbers when benchmarking. + - Backing device alignment + + The default metadata size in bcache is 8k. If your backing device is + RAID based, then be sure to align this by a multiple of your stride + width using `make-bcache --data-offset`. If you intend to expand your + disk array in the future, then multiply a series of primes by your + raid stripe size to get the disk multiples that you would like. + + For example: If you have a 64k stripe size, then the following offset + would provide alignment for many common RAID5 data spindle counts: + 64k * 2*2*2*3*3*5*7 bytes = 161280k + + That space is wasted, but for only 157.5MB you can grow your RAID 5 + volume to the following data-spindle counts without re-aligning: + 3,4,5,6,7,8,9,10,12,14,15,18,20,21 ... + - Bad write performance If write performance is not what you expected, you probably wanted to be @@ -140,7 +315,7 @@ want for getting the best possible numbers when benchmarking. maturity, but simply because in writeback mode you'll lose data if something happens to your SSD) - # echo writeback > /sys/block/bcache0/cache_mode + # echo writeback > /sys/block/bcache0/bcache/cache_mode - Bad performance, or traffic not going to the SSD that you'd expect @@ -193,7 +368,9 @@ want for getting the best possible numbers when benchmarking. Solution: warm the cache by doing writes, or use the testing branch (there's a fix for the issue there). -SYSFS - BACKING DEVICE: + +SYSFS - BACKING DEVICE +---------------------- Available at /sys/block/<bdev>/bcache, /sys/block/bcache*/bcache and (if attached) /sys/fs/bcache/<cset-uuid>/bdev* @@ -238,7 +415,7 @@ sequential_merge against all new requests to determine which new requests are sequential continuations of previous requests for the purpose of determining sequential cutoff. This is necessary if the sequential cutoff value is greater than the - maximum acceptable sequential size for any single request. + maximum acceptable sequential size for any single request. state The backing device can be in one of four different states: @@ -325,7 +502,7 @@ bucket_size Size of buckets cache<0..n> - Symlink to each of the cache devices comprising this cache set. + Symlink to each of the cache devices comprising this cache set. cache_available_percent Percentage of cache device which doesn't contain dirty data, and could diff --git a/Documentation/block/queue-sysfs.txt b/Documentation/block/queue-sysfs.txt index dce25d848d92..d515d58962b9 100644 --- a/Documentation/block/queue-sysfs.txt +++ b/Documentation/block/queue-sysfs.txt @@ -53,7 +53,7 @@ disk. logical_block_size (RO) ----------------------- -This is the logcal block size of the device, in bytes. +This is the logical block size of the device, in bytes. max_hw_sectors_kb (RO) ---------------------- diff --git a/Documentation/block/writeback_cache_control.txt b/Documentation/block/writeback_cache_control.txt index 59e0516cbf6b..8a6bdada5f6b 100644 --- a/Documentation/block/writeback_cache_control.txt +++ b/Documentation/block/writeback_cache_control.txt @@ -20,11 +20,11 @@ a forced cache flush, and the Force Unit Access (FUA) flag for requests. Explicit cache flushes ---------------------- -The REQ_FLUSH flag can be OR ed into the r/w flags of a bio submitted from +The REQ_PREFLUSH flag can be OR ed into the r/w flags of a bio submitted from the filesystem and will make sure the volatile cache of the storage device has been flushed before the actual I/O operation is started. This explicitly guarantees that previously completed write requests are on non-volatile -storage before the flagged bio starts. In addition the REQ_FLUSH flag can be +storage before the flagged bio starts. In addition the REQ_PREFLUSH flag can be set on an otherwise empty bio structure, which causes only an explicit cache flush without any dependent I/O. It is recommend to use the blkdev_issue_flush() helper for a pure cache flush. @@ -41,21 +41,21 @@ signaled after the data has been committed to non-volatile storage. Implementation details for filesystems -------------------------------------- -Filesystems can simply set the REQ_FLUSH and REQ_FUA bits and do not have to +Filesystems can simply set the REQ_PREFLUSH and REQ_FUA bits and do not have to worry if the underlying devices need any explicit cache flushing and how -the Forced Unit Access is implemented. The REQ_FLUSH and REQ_FUA flags +the Forced Unit Access is implemented. The REQ_PREFLUSH and REQ_FUA flags may both be set on a single bio. Implementation details for make_request_fn based block drivers -------------------------------------------------------------- -These drivers will always see the REQ_FLUSH and REQ_FUA bits as they sit +These drivers will always see the REQ_PREFLUSH and REQ_FUA bits as they sit directly below the submit_bio interface. For remapping drivers the REQ_FUA bits need to be propagated to underlying devices, and a global flush needs -to be implemented for bios with the REQ_FLUSH bit set. For real device -drivers that do not have a volatile cache the REQ_FLUSH and REQ_FUA bits -on non-empty bios can simply be ignored, and REQ_FLUSH requests without +to be implemented for bios with the REQ_PREFLUSH bit set. For real device +drivers that do not have a volatile cache the REQ_PREFLUSH and REQ_FUA bits +on non-empty bios can simply be ignored, and REQ_PREFLUSH requests without data can be completed successfully without doing any work. Drivers for devices with volatile caches need to implement the support for these flags themselves without any help from the block layer. @@ -65,17 +65,17 @@ Implementation details for request_fn based block drivers -------------------------------------------------------------- For devices that do not support volatile write caches there is no driver -support required, the block layer completes empty REQ_FLUSH requests before -entering the driver and strips off the REQ_FLUSH and REQ_FUA bits from +support required, the block layer completes empty REQ_PREFLUSH requests before +entering the driver and strips off the REQ_PREFLUSH and REQ_FUA bits from requests that have a payload. For devices with volatile write caches the driver needs to tell the block layer that it supports flushing caches by doing: blk_queue_write_cache(sdkp->disk->queue, true, false); -and handle empty REQ_FLUSH requests in its prep_fn/request_fn. Note that -REQ_FLUSH requests with a payload are automatically turned into a sequence -of an empty REQ_FLUSH request followed by the actual write by the block +and handle empty REQ_OP_FLUSH requests in its prep_fn/request_fn. Note that +REQ_PREFLUSH requests with a payload are automatically turned into a sequence +of an empty REQ_OP_FLUSH request followed by the actual write by the block layer. For devices that also support the FUA bit the block layer needs to be told to pass through the REQ_FUA bit using: @@ -83,4 +83,4 @@ to be told to pass through the REQ_FUA bit using: and the driver must handle write requests that have the REQ_FUA bit set in prep_fn/request_fn. If the FUA bit is not natively supported the block -layer turns it into an empty REQ_FLUSH request after the actual write. +layer turns it into an empty REQ_OP_FLUSH request after the actual write. diff --git a/Documentation/cec.txt b/Documentation/cec.txt new file mode 100644 index 000000000000..75155fe37153 --- /dev/null +++ b/Documentation/cec.txt @@ -0,0 +1,267 @@ +CEC Kernel Support +================== + +The CEC framework provides a unified kernel interface for use with HDMI CEC +hardware. It is designed to handle a multiple types of hardware (receivers, +transmitters, USB dongles). The framework also gives the option to decide +what to do in the kernel driver and what should be handled by userspace +applications. In addition it integrates the remote control passthrough +feature into the kernel's remote control framework. + + +The CEC Protocol +---------------- + +The CEC protocol enables consumer electronic devices to communicate with each +other through the HDMI connection. The protocol uses logical addresses in the +communication. The logical address is strictly connected with the functionality +provided by the device. The TV acting as the communication hub is always +assigned address 0. The physical address is determined by the physical +connection between devices. + +The CEC framework described here is up to date with the CEC 2.0 specification. +It is documented in the HDMI 1.4 specification with the new 2.0 bits documented +in the HDMI 2.0 specification. But for most of the features the freely available +HDMI 1.3a specification is sufficient: + +http://www.microprocessor.org/HDMISpecification13a.pdf + + +The Kernel Interface +==================== + +CEC Adapter +----------- + +The struct cec_adapter represents the CEC adapter hardware. It is created by +calling cec_allocate_adapter() and deleted by calling cec_delete_adapter(): + +struct cec_adapter *cec_allocate_adapter(const struct cec_adap_ops *ops, + void *priv, const char *name, u32 caps, u8 available_las, + struct device *parent); +void cec_delete_adapter(struct cec_adapter *adap); + +To create an adapter you need to pass the following information: + +ops: adapter operations which are called by the CEC framework and that you +have to implement. + +priv: will be stored in adap->priv and can be used by the adapter ops. + +name: the name of the CEC adapter. Note: this name will be copied. + +caps: capabilities of the CEC adapter. These capabilities determine the + capabilities of the hardware and which parts are to be handled + by userspace and which parts are handled by kernelspace. The + capabilities are returned by CEC_ADAP_G_CAPS. + +available_las: the number of simultaneous logical addresses that this + adapter can handle. Must be 1 <= available_las <= CEC_MAX_LOG_ADDRS. + +parent: the parent device. + + +To register the /dev/cecX device node and the remote control device (if +CEC_CAP_RC is set) you call: + +int cec_register_adapter(struct cec_adapter *adap); + +To unregister the devices call: + +void cec_unregister_adapter(struct cec_adapter *adap); + +Note: if cec_register_adapter() fails, then call cec_delete_adapter() to +clean up. But if cec_register_adapter() succeeded, then only call +cec_unregister_adapter() to clean up, never cec_delete_adapter(). The +unregister function will delete the adapter automatically once the last user +of that /dev/cecX device has closed its file handle. + + +Implementing the Low-Level CEC Adapter +-------------------------------------- + +The following low-level adapter operations have to be implemented in +your driver: + +struct cec_adap_ops { + /* Low-level callbacks */ + int (*adap_enable)(struct cec_adapter *adap, bool enable); + int (*adap_monitor_all_enable)(struct cec_adapter *adap, bool enable); + int (*adap_log_addr)(struct cec_adapter *adap, u8 logical_addr); + int (*adap_transmit)(struct cec_adapter *adap, u8 attempts, + u32 signal_free_time, struct cec_msg *msg); + void (*adap_log_status)(struct cec_adapter *adap); + + /* High-level callbacks */ + ... +}; + +The three low-level ops deal with various aspects of controlling the CEC adapter +hardware: + + +To enable/disable the hardware: + + int (*adap_enable)(struct cec_adapter *adap, bool enable); + +This callback enables or disables the CEC hardware. Enabling the CEC hardware +means powering it up in a state where no logical addresses are claimed. This +op assumes that the physical address (adap->phys_addr) is valid when enable is +true and will not change while the CEC adapter remains enabled. The initial +state of the CEC adapter after calling cec_allocate_adapter() is disabled. + +Note that adap_enable must return 0 if enable is false. + + +To enable/disable the 'monitor all' mode: + + int (*adap_monitor_all_enable)(struct cec_adapter *adap, bool enable); + +If enabled, then the adapter should be put in a mode to also monitor messages +that not for us. Not all hardware supports this and this function is only +called if the CEC_CAP_MONITOR_ALL capability is set. This callback is optional +(some hardware may always be in 'monitor all' mode). + +Note that adap_monitor_all_enable must return 0 if enable is false. + + +To program a new logical address: + + int (*adap_log_addr)(struct cec_adapter *adap, u8 logical_addr); + +If logical_addr == CEC_LOG_ADDR_INVALID then all programmed logical addresses +are to be erased. Otherwise the given logical address should be programmed. +If the maximum number of available logical addresses is exceeded, then it +should return -ENXIO. Once a logical address is programmed the CEC hardware +can receive directed messages to that address. + +Note that adap_log_addr must return 0 if logical_addr is CEC_LOG_ADDR_INVALID. + + +To transmit a new message: + + int (*adap_transmit)(struct cec_adapter *adap, u8 attempts, + u32 signal_free_time, struct cec_msg *msg); + +This transmits a new message. The attempts argument is the suggested number of +attempts for the transmit. + +The signal_free_time is the number of data bit periods that the adapter should +wait when the line is free before attempting to send a message. This value +depends on whether this transmit is a retry, a message from a new initiator or +a new message for the same initiator. Most hardware will handle this +automatically, but in some cases this information is needed. + +The CEC_FREE_TIME_TO_USEC macro can be used to convert signal_free_time to +microseconds (one data bit period is 2.4 ms). + + +To log the current CEC hardware status: + + void (*adap_status)(struct cec_adapter *adap, struct seq_file *file); + +This optional callback can be used to show the status of the CEC hardware. +The status is available through debugfs: cat /sys/kernel/debug/cec/cecX/status + + +Your adapter driver will also have to react to events (typically interrupt +driven) by calling into the framework in the following situations: + +When a transmit finished (successfully or otherwise): + +void cec_transmit_done(struct cec_adapter *adap, u8 status, u8 arb_lost_cnt, + u8 nack_cnt, u8 low_drive_cnt, u8 error_cnt); + +The status can be one of: + +CEC_TX_STATUS_OK: the transmit was successful. +CEC_TX_STATUS_ARB_LOST: arbitration was lost: another CEC initiator +took control of the CEC line and you lost the arbitration. +CEC_TX_STATUS_NACK: the message was nacked (for a directed message) or +acked (for a broadcast message). A retransmission is needed. +CEC_TX_STATUS_LOW_DRIVE: low drive was detected on the CEC bus. This +indicates that a follower detected an error on the bus and requested a +retransmission. +CEC_TX_STATUS_ERROR: some unspecified error occurred: this can be one of +the previous two if the hardware cannot differentiate or something else +entirely. +CEC_TX_STATUS_MAX_RETRIES: could not transmit the message after +trying multiple times. Should only be set by the driver if it has hardware +support for retrying messages. If set, then the framework assumes that it +doesn't have to make another attempt to transmit the message since the +hardware did that already. + +The *_cnt arguments are the number of error conditions that were seen. +This may be 0 if no information is available. Drivers that do not support +hardware retry can just set the counter corresponding to the transmit error +to 1, if the hardware does support retry then either set these counters to +0 if the hardware provides no feedback of which errors occurred and how many +times, or fill in the correct values as reported by the hardware. + +When a CEC message was received: + +void cec_received_msg(struct cec_adapter *adap, struct cec_msg *msg); + +Speaks for itself. + +Implementing the High-Level CEC Adapter +--------------------------------------- + +The low-level operations drive the hardware, the high-level operations are +CEC protocol driven. The following high-level callbacks are available: + +struct cec_adap_ops { + /* Low-level callbacks */ + ... + + /* High-level CEC message callback */ + int (*received)(struct cec_adapter *adap, struct cec_msg *msg); +}; + +The received() callback allows the driver to optionally handle a newly +received CEC message + + int (*received)(struct cec_adapter *adap, struct cec_msg *msg); + +If the driver wants to process a CEC message, then it can implement this +callback. If it doesn't want to handle this message, then it should return +-ENOMSG, otherwise the CEC framework assumes it processed this message and +it will not no anything with it. + + +CEC framework functions +----------------------- + +CEC Adapter drivers can call the following CEC framework functions: + +int cec_transmit_msg(struct cec_adapter *adap, struct cec_msg *msg, + bool block); + +Transmit a CEC message. If block is true, then wait until the message has been +transmitted, otherwise just queue it and return. + +void cec_s_phys_addr(struct cec_adapter *adap, u16 phys_addr, bool block); + +Change the physical address. This function will set adap->phys_addr and +send an event if it has changed. If cec_s_log_addrs() has been called and +the physical address has become valid, then the CEC framework will start +claiming the logical addresses. If block is true, then this function won't +return until this process has finished. + +When the physical address is set to a valid value the CEC adapter will +be enabled (see the adap_enable op). When it is set to CEC_PHYS_ADDR_INVALID, +then the CEC adapter will be disabled. If you change a valid physical address +to another valid physical address, then this function will first set the +address to CEC_PHYS_ADDR_INVALID before enabling the new physical address. + +int cec_s_log_addrs(struct cec_adapter *adap, + struct cec_log_addrs *log_addrs, bool block); + +Claim the CEC logical addresses. Should never be called if CEC_CAP_LOG_ADDRS +is set. If block is true, then wait until the logical addresses have been +claimed, otherwise just queue it and return. To unconfigure all logical +addresses call this function with log_addrs set to NULL or with +log_addrs->num_log_addrs set to 0. The block argument is ignored when +unconfiguring. This function will just return if the physical address is +invalid. Once the physical address becomes valid, then the framework will +attempt to claim these logical addresses. diff --git a/Documentation/conf.py b/Documentation/conf.py new file mode 100644 index 000000000000..792b6338ef19 --- /dev/null +++ b/Documentation/conf.py @@ -0,0 +1,414 @@ +# -*- coding: utf-8 -*- +# +# The Linux Kernel documentation build configuration file, created by +# sphinx-quickstart on Fri Feb 12 13:51:46 2016. +# +# This file is execfile()d with the current directory set to its +# containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +import sys +import os + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +sys.path.insert(0, os.path.abspath('sphinx')) + +# -- General configuration ------------------------------------------------ + +# If your documentation needs a minimal Sphinx version, state it here. +#needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = ['kernel-doc', 'rstFlatTable'] + +# Gracefully handle missing rst2pdf. +try: + import rst2pdf + extensions += ['rst2pdf.pdfbuilder'] +except ImportError: + pass + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix(es) of source filenames. +# You can specify multiple suffix as a list of string: +# source_suffix = ['.rst', '.md'] +source_suffix = '.rst' + +# The encoding of source files. +#source_encoding = 'utf-8-sig' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = 'The Linux Kernel' +copyright = '2016, The kernel development community' +author = 'The kernel development community' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# In a normal build, version and release are are set to KERNELVERSION and +# KERNELRELEASE, respectively, from the Makefile via Sphinx command line +# arguments. +# +# The following code tries to extract the information by reading the Makefile, +# when Sphinx is run directly (e.g. by Read the Docs). +try: + makefile_version = None + makefile_patchlevel = None + for line in open('../Makefile'): + key, val = [x.strip() for x in line.split('=', 2)] + if key == 'VERSION': + makefile_version = val + elif key == 'PATCHLEVEL': + makefile_patchlevel = val + if makefile_version and makefile_patchlevel: + break +except: + pass +finally: + if makefile_version and makefile_patchlevel: + version = release = makefile_version + '.' + makefile_patchlevel + else: + sys.stderr.write('Warning: Could not extract kernel version\n') + version = release = "unknown version" + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# +# This is also used if you do content translation via gettext catalogs. +# Usually you set "language" from the command line for these cases. +language = None + +# There are two options for replacing |today|: either, you set today to some +# non-false value, then it is used: +#today = '' +# Else, today_fmt is used as the format for a strftime call. +#today_fmt = '%B %d, %Y' + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +exclude_patterns = ['output'] + +# The reST default role (used for this markup: `text`) to use for all +# documents. +#default_role = None + +# If true, '()' will be appended to :func: etc. cross-reference text. +#add_function_parentheses = True + +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +#add_module_names = True + +# If true, sectionauthor and moduleauthor directives will be shown in the +# output. They are ignored by default. +#show_authors = False + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# A list of ignored prefixes for module index sorting. +#modindex_common_prefix = [] + +# If true, keep warnings as "system message" paragraphs in the built documents. +#keep_warnings = False + +# If true, `todo` and `todoList` produce output, else they produce nothing. +todo_include_todos = False + +primary_domain = 'C' +highlight_language = 'C' + +# -- Options for HTML output ---------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. + +# The Read the Docs theme is available from +# - https://github.com/snide/sphinx_rtd_theme +# - https://pypi.python.org/pypi/sphinx_rtd_theme +# - python-sphinx-rtd-theme package (on Debian) +try: + import sphinx_rtd_theme + html_theme = 'sphinx_rtd_theme' + html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] +except ImportError: + sys.stderr.write('Warning: The Sphinx \'sphinx_rtd_theme\' HTML theme was not found. Make sure you have the theme installed to produce pretty HTML output. Falling back to the default theme.\n') + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +#html_theme_options = {} + +# Add any paths that contain custom themes here, relative to this directory. +#html_theme_path = [] + +# The name for this set of Sphinx documents. If None, it defaults to +# "<project> v<release> documentation". +#html_title = None + +# A shorter title for the navigation bar. Default is the same as html_title. +#html_short_title = None + +# The name of an image file (relative to this directory) to place at the top +# of the sidebar. +#html_logo = None + +# The name of an image file (within the static path) to use as favicon of the +# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 +# pixels large. +#html_favicon = None + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +#html_static_path = ['_static'] + +# Add any extra paths that contain custom files (such as robots.txt or +# .htaccess) here, relative to this directory. These files are copied +# directly to the root of the documentation. +#html_extra_path = [] + +# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, +# using the given strftime format. +#html_last_updated_fmt = '%b %d, %Y' + +# If true, SmartyPants will be used to convert quotes and dashes to +# typographically correct entities. +#html_use_smartypants = True + +# Custom sidebar templates, maps document names to template names. +#html_sidebars = {} + +# Additional templates that should be rendered to pages, maps page names to +# template names. +#html_additional_pages = {} + +# If false, no module index is generated. +#html_domain_indices = True + +# If false, no index is generated. +#html_use_index = True + +# If true, the index is split into individual pages for each letter. +#html_split_index = False + +# If true, links to the reST sources are added to the pages. +#html_show_sourcelink = True + +# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. +#html_show_sphinx = True + +# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. +#html_show_copyright = True + +# If true, an OpenSearch description file will be output, and all pages will +# contain a <link> tag referring to it. The value of this option must be the +# base URL from which the finished HTML is served. +#html_use_opensearch = '' + +# This is the file name suffix for HTML files (e.g. ".xhtml"). +#html_file_suffix = None + +# Language to be used for generating the HTML full-text search index. +# Sphinx supports the following languages: +# 'da', 'de', 'en', 'es', 'fi', 'fr', 'h', 'it', 'ja' +# 'nl', 'no', 'pt', 'ro', 'r', 'sv', 'tr' +#html_search_language = 'en' + +# A dictionary with options for the search language support, empty by default. +# Now only 'ja' uses this config value +#html_search_options = {'type': 'default'} + +# The name of a javascript file (relative to the configuration directory) that +# implements a search results scorer. If empty, the default will be used. +#html_search_scorer = 'scorer.js' + +# Output file base name for HTML help builder. +htmlhelp_basename = 'TheLinuxKerneldoc' + +# -- Options for LaTeX output --------------------------------------------- + +latex_elements = { +# The paper size ('letterpaper' or 'a4paper'). +#'papersize': 'letterpaper', + +# The font size ('10pt', '11pt' or '12pt'). +#'pointsize': '10pt', + +# Additional stuff for the LaTeX preamble. +#'preamble': '', + +# Latex figure (float) alignment +#'figure_align': 'htbp', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). +latex_documents = [ + (master_doc, 'TheLinuxKernel.tex', 'The Linux Kernel Documentation', + 'The kernel development community', 'manual'), +] + +# The name of an image file (relative to this directory) to place at the top of +# the title page. +#latex_logo = None + +# For "manual" documents, if this is true, then toplevel headings are parts, +# not chapters. +#latex_use_parts = False + +# If true, show page references after internal links. +#latex_show_pagerefs = False + +# If true, show URL addresses after external links. +#latex_show_urls = False + +# Documents to append as an appendix to all manuals. +#latex_appendices = [] + +# If false, no module index is generated. +#latex_domain_indices = True + + +# -- Options for manual page output --------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + (master_doc, 'thelinuxkernel', 'The Linux Kernel Documentation', + [author], 1) +] + +# If true, show URL addresses after external links. +#man_show_urls = False + + +# -- Options for Texinfo output ------------------------------------------- + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + (master_doc, 'TheLinuxKernel', 'The Linux Kernel Documentation', + author, 'TheLinuxKernel', 'One line description of project.', + 'Miscellaneous'), +] + +# Documents to append as an appendix to all manuals. +#texinfo_appendices = [] + +# If false, no module index is generated. +#texinfo_domain_indices = True + +# How to display URL addresses: 'footnote', 'no', or 'inline'. +#texinfo_show_urls = 'footnote' + +# If true, do not generate a @detailmenu in the "Top" node's menu. +#texinfo_no_detailmenu = False + + +# -- Options for Epub output ---------------------------------------------- + +# Bibliographic Dublin Core info. +epub_title = project +epub_author = author +epub_publisher = author +epub_copyright = copyright + +# The basename for the epub file. It defaults to the project name. +#epub_basename = project + +# The HTML theme for the epub output. Since the default themes are not +# optimized for small screen space, using the same theme for HTML and epub +# output is usually not wise. This defaults to 'epub', a theme designed to save +# visual space. +#epub_theme = 'epub' + +# The language of the text. It defaults to the language option +# or 'en' if the language is not set. +#epub_language = '' + +# The scheme of the identifier. Typical schemes are ISBN or URL. +#epub_scheme = '' + +# The unique identifier of the text. This can be a ISBN number +# or the project homepage. +#epub_identifier = '' + +# A unique identification for the text. +#epub_uid = '' + +# A tuple containing the cover image and cover page html template filenames. +#epub_cover = () + +# A sequence of (type, uri, title) tuples for the guide element of content.opf. +#epub_guide = () + +# HTML files that should be inserted before the pages created by sphinx. +# The format is a list of tuples containing the path and title. +#epub_pre_files = [] + +# HTML files that should be inserted after the pages created by sphinx. +# The format is a list of tuples containing the path and title. +#epub_post_files = [] + +# A list of files that should not be packed into the epub file. +epub_exclude_files = ['search.html'] + +# The depth of the table of contents in toc.ncx. +#epub_tocdepth = 3 + +# Allow duplicate toc entries. +#epub_tocdup = True + +# Choose between 'default' and 'includehidden'. +#epub_tocscope = 'default' + +# Fix unsupported image types using the Pillow. +#epub_fix_images = False + +# Scale large images. +#epub_max_image_width = 0 + +# How to display URL addresses: 'footnote', 'no', or 'inline'. +#epub_show_urls = 'inline' + +# If false, no index is generated. +#epub_use_index = True + +#======= +# rst2pdf +# +# Grouping the document tree into PDF files. List of tuples +# (source start file, target name, title, author, options). +# +# See the Sphinx chapter of http://ralsina.me/static/manual.pdf +# +# FIXME: Do not add the index file here; the result will be too big. Adding +# multiple PDF files here actually tries to get the cross-referencing right +# *between* PDF files. +pdf_documents = [ + ('index', u'Kernel', u'Kernel', u'J. Random Bozo'), +] + +# kernel-doc extension configuration for running Sphinx directly (e.g. by Read +# the Docs). In a normal build, these are supplied from the Makefile via command +# line arguments. +kerneldoc_bin = '../scripts/kernel-doc' +kerneldoc_srctree = '..' diff --git a/Documentation/cpu-freq/core.txt b/Documentation/cpu-freq/core.txt index ba78e7c2a069..4bc7287806de 100644 --- a/Documentation/cpu-freq/core.txt +++ b/Documentation/cpu-freq/core.txt @@ -96,7 +96,7 @@ new - new frequency For details about OPP, see Documentation/power/opp.txt dev_pm_opp_init_cpufreq_table - cpufreq framework typically is initialized with - cpufreq_frequency_table_cpuinfo which is provided with the list of + cpufreq_table_validate_and_show() which is provided with the list of frequencies that are available for operation. This function provides a ready to use conversion routine to translate the OPP layer's internal information about the available frequencies into a format readily @@ -110,7 +110,7 @@ dev_pm_opp_init_cpufreq_table - cpufreq framework typically is initialized with /* Do things */ r = dev_pm_opp_init_cpufreq_table(dev, &freq_table); if (!r) - cpufreq_frequency_table_cpuinfo(policy, freq_table); + cpufreq_table_validate_and_show(policy, freq_table); /* Do other things */ } diff --git a/Documentation/cpu-freq/cpu-drivers.txt b/Documentation/cpu-freq/cpu-drivers.txt index 14f4e6336d88..772b94fde264 100644 --- a/Documentation/cpu-freq/cpu-drivers.txt +++ b/Documentation/cpu-freq/cpu-drivers.txt @@ -231,7 +231,7 @@ if you want to skip one entry in the table, set the frequency to CPUFREQ_ENTRY_INVALID. The entries don't need to be in ascending order. -By calling cpufreq_frequency_table_cpuinfo(struct cpufreq_policy *policy, +By calling cpufreq_table_validate_and_show(struct cpufreq_policy *policy, struct cpufreq_frequency_table *table); the cpuinfo.min_freq and cpuinfo.max_freq values are detected, and policy->min and policy->max are set to the same values. This is @@ -244,14 +244,12 @@ policy->max, and all other criteria are met. This is helpful for the ->verify call. int cpufreq_frequency_table_target(struct cpufreq_policy *policy, - struct cpufreq_frequency_table *table, unsigned int target_freq, - unsigned int relation, - unsigned int *index); + unsigned int relation); is the corresponding frequency table helper for the ->target -stage. Just pass the values to this function, and the unsigned int -index returns the number of the frequency table entry which contains +stage. Just pass the values to this function, and this function +returns the number of the frequency table entry which contains the frequency the CPU shall be set to. The following macros can be used as iterators over cpufreq_frequency_table: diff --git a/Documentation/cpu-freq/pcc-cpufreq.txt b/Documentation/cpu-freq/pcc-cpufreq.txt index 0a94224ad296..9e3c3b33514c 100644 --- a/Documentation/cpu-freq/pcc-cpufreq.txt +++ b/Documentation/cpu-freq/pcc-cpufreq.txt @@ -159,8 +159,8 @@ to be strictly associated with a P-state. 2.2 cpuinfo_transition_latency: ------------------------------- -The cpuinfo_transition_latency field is CPUFREQ_ETERNAL. The PCC specification -does not include a field to expose this value currently. +The cpuinfo_transition_latency field is 0. The PCC specification does +not include a field to expose this value currently. 2.3 cpuinfo_cur_freq: --------------------- diff --git a/Documentation/cputopology.txt b/Documentation/cputopology.txt index 12b1b25b4da9..f722f227a73b 100644 --- a/Documentation/cputopology.txt +++ b/Documentation/cputopology.txt @@ -20,48 +20,70 @@ to /proc/cpuinfo output of some architectures: identifier (rather than the kernel's). The actual value is architecture and platform dependent. -4) /sys/devices/system/cpu/cpuX/topology/thread_siblings: +4) /sys/devices/system/cpu/cpuX/topology/drawer_id: + + the drawer ID of cpuX. Typically it is the hardware platform's + identifier (rather than the kernel's). The actual value is + architecture and platform dependent. + +5) /sys/devices/system/cpu/cpuX/topology/thread_siblings: internal kernel map of cpuX's hardware threads within the same core as cpuX. -5) /sys/devices/system/cpu/cpuX/topology/thread_siblings_list: +6) /sys/devices/system/cpu/cpuX/topology/thread_siblings_list: human-readable list of cpuX's hardware threads within the same core as cpuX. -6) /sys/devices/system/cpu/cpuX/topology/core_siblings: +7) /sys/devices/system/cpu/cpuX/topology/core_siblings: internal kernel map of cpuX's hardware threads within the same physical_package_id. -7) /sys/devices/system/cpu/cpuX/topology/core_siblings_list: +8) /sys/devices/system/cpu/cpuX/topology/core_siblings_list: human-readable list of cpuX's hardware threads within the same physical_package_id. -8) /sys/devices/system/cpu/cpuX/topology/book_siblings: +9) /sys/devices/system/cpu/cpuX/topology/book_siblings: internal kernel map of cpuX's hardware threads within the same book_id. -9) /sys/devices/system/cpu/cpuX/topology/book_siblings_list: +10) /sys/devices/system/cpu/cpuX/topology/book_siblings_list: human-readable list of cpuX's hardware threads within the same book_id. +11) /sys/devices/system/cpu/cpuX/topology/drawer_siblings: + + internal kernel map of cpuX's hardware threads within the same + drawer_id. + +12) /sys/devices/system/cpu/cpuX/topology/drawer_siblings_list: + + human-readable list of cpuX's hardware threads within the same + drawer_id. + To implement it in an architecture-neutral way, a new source file, -drivers/base/topology.c, is to export the 6 or 9 attributes. The three book -related sysfs files will only be created if CONFIG_SCHED_BOOK is selected. +drivers/base/topology.c, is to export the 6 to 12 attributes. The book +and drawer related sysfs files will only be created if CONFIG_SCHED_BOOK +and CONFIG_SCHED_DRAWER are selected. + +CONFIG_SCHED_BOOK and CONFIG_DRAWER are currently only used on s390, where +they reflect the cpu and cache hierarchy. For an architecture to support this feature, it must define some of these macros in include/asm-XXX/topology.h: #define topology_physical_package_id(cpu) #define topology_core_id(cpu) #define topology_book_id(cpu) +#define topology_drawer_id(cpu) #define topology_sibling_cpumask(cpu) #define topology_core_cpumask(cpu) #define topology_book_cpumask(cpu) +#define topology_drawer_cpumask(cpu) The type of **_id macros is int. The type of **_cpumask macros is (const) struct cpumask *. The latter @@ -78,6 +100,8 @@ not defined by include/asm-XXX/topology.h: For architectures that don't support books (CONFIG_SCHED_BOOK) there are no default definitions for topology_book_id() and topology_book_cpumask(). +For architectures that don't support drawes (CONFIG_SCHED_DRAWER) there are +no default definitions for topology_drawer_id() and topology_drawer_cpumask(). Additionally, CPU topology information is provided under /sys/devices/system/cpu and includes these files. The internal diff --git a/Documentation/crypto/asymmetric-keys.txt b/Documentation/crypto/asymmetric-keys.txt index 8c07e0ea6bc0..2b7816dea370 100644 --- a/Documentation/crypto/asymmetric-keys.txt +++ b/Documentation/crypto/asymmetric-keys.txt @@ -76,7 +76,7 @@ the criterion string: Looking in /proc/keys, the last 8 hex digits of the key fingerprint are displayed, along with the subtype: - 1a39e171 I----- 1 perm 3f010000 0 0 asymmetri modsign.0: DSA 5acc2142 [] + 1a39e171 I----- 1 perm 3f010000 0 0 asymmetric modsign.0: DSA 5acc2142 [] ========================= diff --git a/Documentation/development-process/4.Coding b/Documentation/development-process/4.Coding index e3cb6a56653a..9a3ee77cefb1 100644 --- a/Documentation/development-process/4.Coding +++ b/Documentation/development-process/4.Coding @@ -346,7 +346,7 @@ which have not been so documented, there is no harm in adding kerneldoc comments for the future; indeed, this can be a useful activity for beginning kernel developers. The format of these comments, along with some information on how to create kerneldoc templates can be found in the file -Documentation/kernel-doc-nano-HOWTO.txt. +Documentation/kernel-documentation.rst. Anybody who reads through a significant amount of existing kernel code will note that, often, comments are most notable by their absence. Once again, diff --git a/Documentation/device-mapper/dm-raid.txt b/Documentation/device-mapper/dm-raid.txt index df2d636b6088..e5b6497116f4 100644 --- a/Documentation/device-mapper/dm-raid.txt +++ b/Documentation/device-mapper/dm-raid.txt @@ -14,8 +14,12 @@ The target is named "raid" and it accepts the following parameters: <#raid_devs> <metadata_dev0> <dev0> [.. <metadata_devN> <devN>] <raid_type>: + raid0 RAID0 striping (no resilience) raid1 RAID1 mirroring - raid4 RAID4 dedicated parity disk + raid4 RAID4 with dedicated last parity disk + raid5_n RAID5 with dedicated last parity disk suporting takeover + Same as raid4 + -Transitory layout raid5_la RAID5 left asymmetric - rotating parity 0 with data continuation raid5_ra RAID5 right asymmetric @@ -30,7 +34,19 @@ The target is named "raid" and it accepts the following parameters: - rotating parity N (right-to-left) with data restart raid6_nc RAID6 N continue - rotating parity N (right-to-left) with data continuation + raid6_n_6 RAID6 with dedicate parity disks + - parity and Q-syndrome on the last 2 disks; + laylout for takeover from/to raid4/raid5_n + raid6_la_6 Same as "raid_la" plus dedicated last Q-syndrome disk + - layout for takeover from raid5_la from/to raid6 + raid6_ra_6 Same as "raid5_ra" dedicated last Q-syndrome disk + - layout for takeover from raid5_ra from/to raid6 + raid6_ls_6 Same as "raid5_ls" dedicated last Q-syndrome disk + - layout for takeover from raid5_ls from/to raid6 + raid6_rs_6 Same as "raid5_rs" dedicated last Q-syndrome disk + - layout for takeover from raid5_rs from/to raid6 raid10 Various RAID10 inspired algorithms chosen by additional params + (see raid10_format and raid10_copies below) - RAID10: Striped Mirrors (aka 'Striping on top of mirrors') - RAID1E: Integrated Adjacent Stripe Mirroring - RAID1E: Integrated Offset Stripe Mirroring @@ -116,10 +132,41 @@ The target is named "raid" and it accepts the following parameters: Here we see layouts closely akin to 'RAID1E - Integrated Offset Stripe Mirroring'. + [delta_disks <N>] + The delta_disks option value (-251 < N < +251) triggers + device removal (negative value) or device addition (positive + value) to any reshape supporting raid levels 4/5/6 and 10. + RAID levels 4/5/6 allow for addition of devices (metadata + and data device tupel), raid10_near and raid10_offset only + allow for device addtion. raid10_far does not support any + reshaping at all. + A minimum of devices have to be kept to enforce resilience, + which is 3 devices for raid4/5 and 4 devices for raid6. + + [data_offset <sectors>] + This option value defines the offset into each data device + where the data starts. This is used to provide out-of-place + reshaping space to avoid writing over data whilst + changing the layout of stripes, hence an interruption/crash + may happen at any time without the risk of losing data. + E.g. when adding devices to an existing raid set during + forward reshaping, the out-of-place space will be allocated + at the beginning of each raid device. The kernel raid4/5/6/10 + MD personalities supporting such device addition will read the data from + the existing first stripes (those with smaller number of stripes) + starting at data_offset to fill up a new stripe with the larger + number of stripes, calculate the redundancy blocks (CRC/Q-syndrome) + and write that new stripe to offset 0. Same will be applied to all + N-1 other new stripes. This out-of-place scheme is used to change + the RAID type (i.e. the allocation algorithm) as well, e.g. + changing from raid5_ls to raid5_n. + <#raid_devs>: The number of devices composing the array. Each device consists of two entries. The first is the device containing the metadata (if any); the second is the one containing the - data. + data. A Maximum of 64 metadata/data device entries are supported + up to target version 1.8.0. + 1.9.0 supports up to 253 which is enforced by the used MD kernel runtime. If a drive has failed or is missing at creation time, a '-' can be given for both the metadata and data drives for a given position. @@ -207,7 +254,6 @@ include: "recover"- Initiate/continue a recover process. "check" - Initiate a check (i.e. a "scrub") of the array. "repair" - Initiate a repair of the array. - "reshape"- Currently unsupported (-EINVAL). Discard Support @@ -257,3 +303,9 @@ Version History 1.5.2 'mismatch_cnt' is zero unless [last_]sync_action is "check". 1.6.0 Add discard support (and devices_handle_discard_safely module param). 1.7.0 Add support for MD RAID0 mappings. +1.8.0 Explictely check for compatible flags in the superblock metadata + and reject to start the raid set if any are set by a newer + target version, thus avoiding data corruption on a raid set + with a reshape in progress. +1.9.0 Add support for RAID level takeover/reshape/region size + and set size reduction. diff --git a/Documentation/device-mapper/log-writes.txt b/Documentation/device-mapper/log-writes.txt index c10f30c9b534..f4ebcbaf50f3 100644 --- a/Documentation/device-mapper/log-writes.txt +++ b/Documentation/device-mapper/log-writes.txt @@ -14,14 +14,14 @@ Log Ordering We log things in order of completion once we are sure the write is no longer in cache. This means that normal WRITE requests are not actually logged until the -next REQ_FLUSH request. This is to make it easier for userspace to replay the -log in a way that correlates to what is on disk and not what is in cache, to -make it easier to detect improper waiting/flushing. +next REQ_PREFLUSH request. This is to make it easier for userspace to replay +the log in a way that correlates to what is on disk and not what is in cache, +to make it easier to detect improper waiting/flushing. This works by attaching all WRITE requests to a list once the write completes. -Once we see a REQ_FLUSH request we splice this list onto the request and once +Once we see a REQ_PREFLUSH request we splice this list onto the request and once the FLUSH request completes we log all of the WRITEs and then the FLUSH. Only -completed WRITEs, at the time the REQ_FLUSH is issued, are added in order to +completed WRITEs, at the time the REQ_PREFLUSH is issued, are added in order to simulate the worst case scenario with regard to power failures. Consider the following example (W means write, C means complete): diff --git a/Documentation/devicetree/bindings/ata/brcm,sata-brcmstb.txt b/Documentation/devicetree/bindings/ata/brcm,sata-brcm.txt index 60872838f1ad..0a5b3b47f217 100644 --- a/Documentation/devicetree/bindings/ata/brcm,sata-brcmstb.txt +++ b/Documentation/devicetree/bindings/ata/brcm,sata-brcm.txt @@ -1,13 +1,14 @@ -* Broadcom SATA3 AHCI Controller for STB +* Broadcom SATA3 AHCI Controller SATA nodes are defined to describe on-chip Serial ATA controllers. Each SATA controller should have its own node. Required properties: - compatible : should be one or more of - "brcm,bcm7425-ahci" - "brcm,bcm7445-ahci" - "brcm,sata3-ahci" + "brcm,bcm7425-ahci" + "brcm,bcm7445-ahci" + "brcm,bcm-nsp-ahci" + "brcm,sata3-ahci" - reg : register mappings for AHCI and SATA_TOP_CTRL - reg-names : "ahci" and "top-ctrl" - interrupts : interrupt mapping for SATA IRQ diff --git a/Documentation/devicetree/bindings/extcon/extcon-arizona.txt b/Documentation/devicetree/bindings/extcon/extcon-arizona.txt index e27341f8a4c7..7f3d94ae81ff 100644 --- a/Documentation/devicetree/bindings/extcon/extcon-arizona.txt +++ b/Documentation/devicetree/bindings/extcon/extcon-arizona.txt @@ -46,7 +46,8 @@ Optional properties: The second cell represents the MICBIAS to be used. The third cell represents the value of the micd-pol-gpio pin. - - wlf,gpsw : Settings for the general purpose switch + - wlf,gpsw : Settings for the general purpose switch, set as one of the + ARIZONA_GPSW_XXX defines. Example: diff --git a/Documentation/devicetree/bindings/hwmon/apm-xgene-hwmon.txt b/Documentation/devicetree/bindings/hwmon/apm-xgene-hwmon.txt new file mode 100644 index 000000000000..59b38557f1bb --- /dev/null +++ b/Documentation/devicetree/bindings/hwmon/apm-xgene-hwmon.txt @@ -0,0 +1,14 @@ +APM X-Gene hwmon driver + +APM X-Gene SOC sensors are accessed over the "SLIMpro" mailbox. + +Required properties : + - compatible : should be "apm,xgene-slimpro-hwmon" + - mboxes : use the label reference for the mailbox as the first parameter. + The second parameter is the channel number. + +Example : + hwmonslimpro { + compatible = "apm,xgene-slimpro-hwmon"; + mboxes = <&mailbox 7>; + }; diff --git a/Documentation/devicetree/bindings/hwmon/ina2xx.txt b/Documentation/devicetree/bindings/hwmon/ina2xx.txt index 9bcd5e87830d..02af0d94e921 100644 --- a/Documentation/devicetree/bindings/hwmon/ina2xx.txt +++ b/Documentation/devicetree/bindings/hwmon/ina2xx.txt @@ -7,6 +7,7 @@ Required properties: - "ti,ina220" for ina220 - "ti,ina226" for ina226 - "ti,ina230" for ina230 + - "ti,ina231" for ina231 - reg: I2C address Optional properties: diff --git a/Documentation/devicetree/bindings/hwmon/jc42.txt b/Documentation/devicetree/bindings/hwmon/jc42.txt new file mode 100644 index 000000000000..07a250498fbb --- /dev/null +++ b/Documentation/devicetree/bindings/hwmon/jc42.txt @@ -0,0 +1,42 @@ +Properties for Jedec JC-42.4 compatible temperature sensors + +Required properties: +- compatible: May include a device-specific string consisting of the + manufacturer and the name of the chip. A list of supported + chip names follows. + Must include "jedec,jc-42.4-temp" for any Jedec JC-42.4 + compatible temperature sensor. + + Supported chip names: + adi,adt7408 + atmel,at30ts00 + atmel,at30tse004 + onnn,cat6095 + onnn,cat34ts02 + maxim,max6604 + microchip,mcp9804 + microchip,mcp9805 + microchip,mcp9808 + microchip,mcp98243 + microchip,mcp98244 + microchip,mcp9843 + nxp,se97 + nxp,se98 + st,stts2002 + st,stts2004 + st,stts3000 + st,stts424 + st,stts424e + idt,tse2002 + idt,tse2004 + idt,ts3000 + idt,ts3001 + +- reg: I2C address + +Example: + +temp-sensor@1a { + compatible = "jedec,jc-42.4-temp"; + reg = <0x1a>; +}; diff --git a/Documentation/devicetree/bindings/i2c/i2c-arb-gpio-challenge.txt b/Documentation/devicetree/bindings/i2c/i2c-arb-gpio-challenge.txt index bfeabb843941..71191ff0e781 100644 --- a/Documentation/devicetree/bindings/i2c/i2c-arb-gpio-challenge.txt +++ b/Documentation/devicetree/bindings/i2c/i2c-arb-gpio-challenge.txt @@ -44,8 +44,8 @@ Required properties: - our-claim-gpio: The GPIO that we use to claim the bus. - their-claim-gpios: The GPIOs that the other sides use to claim the bus. Note that some implementations may only support a single other master. -- Standard I2C mux properties. See mux.txt in this directory. -- Single I2C child bus node at reg 0. See mux.txt in this directory. +- Standard I2C mux properties. See i2c-mux.txt in this directory. +- Single I2C child bus node at reg 0. See i2c-mux.txt in this directory. Optional properties: - slew-delay-us: microseconds to wait for a GPIO to go high. Default is 10 us. diff --git a/Documentation/devicetree/bindings/i2c/i2c-demux-pinctrl.txt b/Documentation/devicetree/bindings/i2c/i2c-demux-pinctrl.txt index 6078aefe7ed4..7ce23ac61308 100644 --- a/Documentation/devicetree/bindings/i2c/i2c-demux-pinctrl.txt +++ b/Documentation/devicetree/bindings/i2c/i2c-demux-pinctrl.txt @@ -27,7 +27,8 @@ Required properties: - i2c-bus-name: The name of this bus. Also needed as pinctrl-name for the I2C parents. -Furthermore, I2C mux properties and child nodes. See mux.txt in this directory. +Furthermore, I2C mux properties and child nodes. See i2c-mux.txt in this +directory. Example: diff --git a/Documentation/devicetree/bindings/i2c/i2c-mux-gpio.txt b/Documentation/devicetree/bindings/i2c/i2c-mux-gpio.txt index 66709a825541..21da3ecbb370 100644 --- a/Documentation/devicetree/bindings/i2c/i2c-mux-gpio.txt +++ b/Documentation/devicetree/bindings/i2c/i2c-mux-gpio.txt @@ -22,8 +22,8 @@ Required properties: - i2c-parent: The phandle of the I2C bus that this multiplexer's master-side port is connected to. - mux-gpios: list of gpios used to control the muxer -* Standard I2C mux properties. See mux.txt in this directory. -* I2C child bus nodes. See mux.txt in this directory. +* Standard I2C mux properties. See i2c-mux.txt in this directory. +* I2C child bus nodes. See i2c-mux.txt in this directory. Optional properties: - idle-state: value to set the muxer to when idle. When no value is @@ -33,7 +33,7 @@ For each i2c child node, an I2C child bus will be created. They will be numbered based on their order in the device tree. Whenever an access is made to a device on a child bus, the value set -in the revelant node's reg property will be output using the list of +in the relevant node's reg property will be output using the list of GPIOs, the first in the list holding the least-significant value. If an idle state is defined, using the idle-state (optional) property, diff --git a/Documentation/devicetree/bindings/i2c/i2c-mux-pinctrl.txt b/Documentation/devicetree/bindings/i2c/i2c-mux-pinctrl.txt index ae8af1694e95..33119a98e144 100644 --- a/Documentation/devicetree/bindings/i2c/i2c-mux-pinctrl.txt +++ b/Documentation/devicetree/bindings/i2c/i2c-mux-pinctrl.txt @@ -28,9 +28,9 @@ Also required are: * Standard pinctrl properties that specify the pin mux state for each child bus. See ../pinctrl/pinctrl-bindings.txt. -* Standard I2C mux properties. See mux.txt in this directory. +* Standard I2C mux properties. See i2c-mux.txt in this directory. -* I2C child bus nodes. See mux.txt in this directory. +* I2C child bus nodes. See i2c-mux.txt in this directory. For each named state defined in the pinctrl-names property, an I2C child bus will be created. I2C child bus numbers are assigned based on the index into diff --git a/Documentation/devicetree/bindings/i2c/i2c-mux-reg.txt b/Documentation/devicetree/bindings/i2c/i2c-mux-reg.txt index 688783fbe696..de00d7fc450b 100644 --- a/Documentation/devicetree/bindings/i2c/i2c-mux-reg.txt +++ b/Documentation/devicetree/bindings/i2c/i2c-mux-reg.txt @@ -7,8 +7,8 @@ Required properties: - compatible: i2c-mux-reg - i2c-parent: The phandle of the I2C bus that this multiplexer's master-side port is connected to. -* Standard I2C mux properties. See mux.txt in this directory. -* I2C child bus nodes. See mux.txt in this directory. +* Standard I2C mux properties. See i2c-mux.txt in this directory. +* I2C child bus nodes. See i2c-mux.txt in this directory. Optional properties: - reg: this pair of <offset size> specifies the register to control the mux. @@ -24,7 +24,7 @@ Optional properties: given, it defaults to the last value used. Whenever an access is made to a device on a child bus, the value set -in the revelant node's reg property will be output to the register. +in the relevant node's reg property will be output to the register. If an idle state is defined, using the idle-state (optional) property, whenever an access is not being made to a device on a child bus, the diff --git a/Documentation/devicetree/bindings/i2c/trivial-devices.txt b/Documentation/devicetree/bindings/i2c/trivial-devices.txt index 539874490492..acc5cd64711c 100644 --- a/Documentation/devicetree/bindings/i2c/trivial-devices.txt +++ b/Documentation/devicetree/bindings/i2c/trivial-devices.txt @@ -56,6 +56,70 @@ 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 mc,rv3029c2 Real Time Clock Module with I2C-Bus +microchip,mcp4531-502 Microchip 7-bit Single I2C Digital Potentiometer (5k) +microchip,mcp4531-103 Microchip 7-bit Single I2C Digital Potentiometer (10k) +microchip,mcp4531-503 Microchip 7-bit Single I2C Digital Potentiometer (50k) +microchip,mcp4531-104 Microchip 7-bit Single I2C Digital Potentiometer (100k) +microchip,mcp4532-502 Microchip 7-bit Single I2C Digital Potentiometer (5k) +microchip,mcp4532-103 Microchip 7-bit Single I2C Digital Potentiometer (10k) +microchip,mcp4532-503 Microchip 7-bit Single I2C Digital Potentiometer (50k) +microchip,mcp4532-104 Microchip 7-bit Single I2C Digital Potentiometer (100k) +microchip,mcp4541-502 Microchip 7-bit Single I2C Digital Potentiometer with NV Memory (5k) +microchip,mcp4541-103 Microchip 7-bit Single I2C Digital Potentiometer with NV Memory (10k) +microchip,mcp4541-503 Microchip 7-bit Single I2C Digital Potentiometer with NV Memory (50k) +microchip,mcp4541-104 Microchip 7-bit Single I2C Digital Potentiometer with NV Memory (100k) +microchip,mcp4542-502 Microchip 7-bit Single I2C Digital Potentiometer with NV Memory (5k) +microchip,mcp4542-103 Microchip 7-bit Single I2C Digital Potentiometer with NV Memory (10k) +microchip,mcp4542-503 Microchip 7-bit Single I2C Digital Potentiometer with NV Memory (50k) +microchip,mcp4542-104 Microchip 7-bit Single I2C Digital Potentiometer with NV Memory (100k) +microchip,mcp4551-502 Microchip 8-bit Single I2C Digital Potentiometer (5k) +microchip,mcp4551-103 Microchip 8-bit Single I2C Digital Potentiometer (10k) +microchip,mcp4551-503 Microchip 8-bit Single I2C Digital Potentiometer (50k) +microchip,mcp4551-104 Microchip 8-bit Single I2C Digital Potentiometer (100k) +microchip,mcp4552-502 Microchip 8-bit Single I2C Digital Potentiometer (5k) +microchip,mcp4552-103 Microchip 8-bit Single I2C Digital Potentiometer (10k) +microchip,mcp4552-503 Microchip 8-bit Single I2C Digital Potentiometer (50k) +microchip,mcp4552-104 Microchip 8-bit Single I2C Digital Potentiometer (100k) +microchip,mcp4561-502 Microchip 8-bit Single I2C Digital Potentiometer with NV Memory (5k) +microchip,mcp4561-103 Microchip 8-bit Single I2C Digital Potentiometer with NV Memory (10k) +microchip,mcp4561-503 Microchip 8-bit Single I2C Digital Potentiometer with NV Memory (50k) +microchip,mcp4561-104 Microchip 8-bit Single I2C Digital Potentiometer with NV Memory (100k) +microchip,mcp4562-502 Microchip 8-bit Single I2C Digital Potentiometer with NV Memory (5k) +microchip,mcp4562-103 Microchip 8-bit Single I2C Digital Potentiometer with NV Memory (10k) +microchip,mcp4562-503 Microchip 8-bit Single I2C Digital Potentiometer with NV Memory (50k) +microchip,mcp4562-104 Microchip 8-bit Single I2C Digital Potentiometer with NV Memory (100k) +microchip,mcp4631-502 Microchip 7-bit Dual I2C Digital Potentiometer (5k) +microchip,mcp4631-103 Microchip 7-bit Dual I2C Digital Potentiometer (10k) +microchip,mcp4631-503 Microchip 7-bit Dual I2C Digital Potentiometer (50k) +microchip,mcp4631-104 Microchip 7-bit Dual I2C Digital Potentiometer (100k) +microchip,mcp4632-502 Microchip 7-bit Dual I2C Digital Potentiometer (5k) +microchip,mcp4632-103 Microchip 7-bit Dual I2C Digital Potentiometer (10k) +microchip,mcp4632-503 Microchip 7-bit Dual I2C Digital Potentiometer (50k) +microchip,mcp4632-104 Microchip 7-bit Dual I2C Digital Potentiometer (100k) +microchip,mcp4641-502 Microchip 7-bit Dual I2C Digital Potentiometer with NV Memory (5k) +microchip,mcp4641-103 Microchip 7-bit Dual I2C Digital Potentiometer with NV Memory (10k) +microchip,mcp4641-503 Microchip 7-bit Dual I2C Digital Potentiometer with NV Memory (50k) +microchip,mcp4641-104 Microchip 7-bit Dual I2C Digital Potentiometer with NV Memory (100k) +microchip,mcp4642-502 Microchip 7-bit Dual I2C Digital Potentiometer with NV Memory (5k) +microchip,mcp4642-103 Microchip 7-bit Dual I2C Digital Potentiometer with NV Memory (10k) +microchip,mcp4642-503 Microchip 7-bit Dual I2C Digital Potentiometer with NV Memory (50k) +microchip,mcp4642-104 Microchip 7-bit Dual I2C Digital Potentiometer with NV Memory (100k) +microchip,mcp4651-502 Microchip 8-bit Dual I2C Digital Potentiometer (5k) +microchip,mcp4651-103 Microchip 8-bit Dual I2C Digital Potentiometer (10k) +microchip,mcp4651-503 Microchip 8-bit Dual I2C Digital Potentiometer (50k) +microchip,mcp4651-104 Microchip 8-bit Dual I2C Digital Potentiometer (100k) +microchip,mcp4652-502 Microchip 8-bit Dual I2C Digital Potentiometer (5k) +microchip,mcp4652-103 Microchip 8-bit Dual I2C Digital Potentiometer (10k) +microchip,mcp4652-503 Microchip 8-bit Dual I2C Digital Potentiometer (50k) +microchip,mcp4652-104 Microchip 8-bit Dual I2C Digital Potentiometer (100k) +microchip,mcp4661-502 Microchip 8-bit Dual I2C Digital Potentiometer with NV Memory (5k) +microchip,mcp4661-103 Microchip 8-bit Dual I2C Digital Potentiometer with NV Memory (10k) +microchip,mcp4661-503 Microchip 8-bit Dual I2C Digital Potentiometer with NV Memory (50k) +microchip,mcp4661-104 Microchip 8-bit Dual I2C Digital Potentiometer with NV Memory (100k) +microchip,mcp4662-502 Microchip 8-bit Dual I2C Digital Potentiometer with NV Memory (5k) +microchip,mcp4662-103 Microchip 8-bit Dual I2C Digital Potentiometer with NV Memory (10k) +microchip,mcp4662-503 Microchip 8-bit Dual I2C Digital Potentiometer with NV Memory (50k) +microchip,mcp4662-104 Microchip 8-bit Dual I2C Digital Potentiometer with NV Memory (100k) national,lm63 Temperature sensor with integrated fan control national,lm75 I2C TEMP SENSOR national,lm80 Serial Interface ACPI-Compatible Microprocessor System Hardware Monitor diff --git a/Documentation/devicetree/bindings/iio/adc/brcm,iproc-static-adc.txt b/Documentation/devicetree/bindings/iio/adc/brcm,iproc-static-adc.txt new file mode 100644 index 000000000000..caaaed765ce4 --- /dev/null +++ b/Documentation/devicetree/bindings/iio/adc/brcm,iproc-static-adc.txt @@ -0,0 +1,41 @@ +* Broadcom's IPROC Static ADC controller + +Broadcom iProc ADC controller has 8 channels 10bit ADC. +Allows user to convert analog input voltage values to digital. + +Required properties: + +- compatible: Must be "brcm,iproc-static-adc" + +- adc-syscon: Handler of syscon node defining physical base address of the + controller and length of memory mapped region. + +- #io-channel-cells = <1>; As ADC has multiple outputs + refer to Documentation/devicetree/bindings/iio/iio-bindings.txt for details. + +- io-channel-ranges: + refer to Documentation/devicetree/bindings/iio/iio-bindings.txt for details. + +- clocks: Clock used for this block. + +- clock-names: Clock name should be given as tsc_clk. + +- interrupts: interrupt line number. + +For example: + + ts_adc_syscon: ts_adc_syscon@180a6000 { + compatible = "brcm,iproc-ts-adc-syscon","syscon"; + reg = <0x180a6000 0xc30>; + }; + + adc: adc@180a6000 { + compatible = "brcm,iproc-static-adc"; + adc-syscon = <&ts_adc_syscon>; + #io-channel-cells = <1>; + io-channel-ranges; + clocks = <&asiu_clks BCM_CYGNUS_ASIU_ADC_CLK>; + clock-names = "tsc_clk"; + interrupts = <GIC_SPI 164 IRQ_TYPE_LEVEL_HIGH>; + status = "disabled"; + }; diff --git a/Documentation/devicetree/bindings/iio/adc/max1363.txt b/Documentation/devicetree/bindings/iio/adc/max1363.txt new file mode 100644 index 000000000000..94a9011dd860 --- /dev/null +++ b/Documentation/devicetree/bindings/iio/adc/max1363.txt @@ -0,0 +1,63 @@ +* Maxim 1x3x/136x/116xx Analog to Digital Converter (ADC) + +The node for this driver must be a child node of a I2C controller, hence +all mandatory properties for your controller must be specified. See directory: + + Documentation/devicetree/bindings/i2c + +for more details. + +Required properties: + - compatible: Should be one of + "maxim,max1361" + "maxim,max1362" + "maxim,max1363" + "maxim,max1364" + "maxim,max1036" + "maxim,max1037" + "maxim,max1038" + "maxim,max1039" + "maxim,max1136" + "maxim,max1137" + "maxim,max1138" + "maxim,max1139" + "maxim,max1236" + "maxim,max1237" + "maxim,max1238" + "maxim,max1239" + "maxim,max11600" + "maxim,max11601" + "maxim,max11602" + "maxim,max11603" + "maxim,max11604" + "maxim,max11605" + "maxim,max11606" + "maxim,max11607" + "maxim,max11608" + "maxim,max11609" + "maxim,max11610" + "maxim,max11611" + "maxim,max11612" + "maxim,max11613" + "maxim,max11614" + "maxim,max11615" + "maxim,max11616" + "maxim,max11617" + "maxim,max11644" + "maxim,max11645" + "maxim,max11646" + "maxim,max11647" + - reg: Should contain the ADC I2C address + +Optional properties: + - vcc-supply: phandle to the regulator that provides power to the ADC. + - vref-supply: phandle to the regulator for ADC reference voltage. + - interrupts: IRQ line for the ADC. If not used the driver will use + polling. + +Example: +adc: max11644@36 { + compatible = "maxim,max11644"; + reg = <0x36>; + vref-supply = <&adc_vref>; +}; diff --git a/Documentation/devicetree/bindings/iio/chemical/atlas,ec-sm.txt b/Documentation/devicetree/bindings/iio/chemical/atlas,ec-sm.txt new file mode 100644 index 000000000000..2962bd9a2b3d --- /dev/null +++ b/Documentation/devicetree/bindings/iio/chemical/atlas,ec-sm.txt @@ -0,0 +1,22 @@ +* Atlas Scientific EC-SM OEM sensor + +http://www.atlas-scientific.com/_files/_datasheets/_oem/EC_oem_datasheet.pdf + +Required properties: + + - compatible: must be "atlas,ec-sm" + - reg: the I2C address of the sensor + - interrupt-parent: should be the phandle for the interrupt controller + - interrupts: the sole interrupt generated by the device + + Refer to interrupt-controller/interrupts.txt for generic interrupt client + node bindings. + +Example: + +atlas@64 { + compatible = "atlas,ec-sm"; + reg = <0x64>; + interrupt-parent = <&gpio1>; + interrupts = <16 2>; +}; diff --git a/Documentation/devicetree/bindings/iio/dac/ad5755.txt b/Documentation/devicetree/bindings/iio/dac/ad5755.txt new file mode 100644 index 000000000000..f0bbd7e1029b --- /dev/null +++ b/Documentation/devicetree/bindings/iio/dac/ad5755.txt @@ -0,0 +1,124 @@ +* Analog Device AD5755 IIO Multi-Channel DAC Linux Driver + +Required properties: + - compatible: Has to contain one of the following: + adi,ad5755 + adi,ad5755-1 + adi,ad5757 + adi,ad5735 + adi,ad5737 + + - reg: spi chip select number for the device + - spi-cpha or spi-cpol: is the only modes that is supported + +Recommended properties: + - spi-max-frequency: Definition as per + Documentation/devicetree/bindings/spi/spi-bus.txt + +Optional properties: +See include/dt-bindings/iio/ad5755.h + - adi,ext-dc-dc-compenstation-resistor: boolean set if the hardware have an + external resistor and thereby bypasses + the internal compensation resistor. + - adi,dc-dc-phase: + Valid values for DC DC Phase control is: + 0: All dc-to-dc converters clock on the same edge. + 1: Channel A and Channel B clock on the same edge, + Channel C and Channel D clock on opposite edges. + 2: Channel A and Channel C clock on the same edge, + Channel B and Channel D clock on opposite edges. + 3: Channel A, Channel B, Channel C, and Channel D + clock 90 degrees out of phase from each other. + - adi,dc-dc-freq-hz: + Valid values for DC DC frequency is [Hz]: + 250000 + 410000 + 650000 + - adi,dc-dc-max-microvolt: + Valid values for the maximum allowed Vboost voltage supplied by + the dc-to-dc converter is: + 23000000 + 24500000 + 27000000 + 29500000 + +Optional for every channel: + - adi,mode: + Valid values for DAC modes is: + 0: 0 V to 5 V voltage range. + 1: 0 V to 10 V voltage range. + 2: Plus minus 5 V voltage range. + 3: Plus minus 10 V voltage range. + 4: 4 mA to 20 mA current range. + 5: 0 mA to 20 mA current range. + 6: 0 mA to 24 mA current range. + - adi,ext-current-sense-resistor: boolean set if the hardware a external + current sense resistor. + - adi,enable-voltage-overrange: boolean enable voltage overrange + - adi,slew: Array of slewrate settings should contain 3 fields: + 1: Should be either 0 or 1 in order to enable or disable slewrate. + 2: Slew rate settings: + Valid values for the slew rate update frequency: + 64000 + 32000 + 16000 + 8000 + 4000 + 2000 + 1000 + 500 + 250 + 125 + 64 + 32 + 16 + 8 + 4 + 0 + 3: Slew step size: + Valid values for the step size LSBs: + 1 + 2 + 4 + 16 + 32 + 64 + 128 + 256 + +Example: +dac@0 { + #address-cells = <1>; + #size-cells = <0>; + compatible = "adi,ad5755"; + reg = <0>; + spi-max-frequency = <1000000>; + spi-cpha; + adi,dc-dc-phase = <0>; + adi,dc-dc-freq-hz = <410000>; + adi,dc-dc-max-microvolt = <23000000>; + channel@0 { + reg = <0>; + adi,mode = <4>; + adi,ext-current-sense-resistor; + adi,slew = <0 64000 1>; + }; + channel@1 { + reg = <1>; + adi,mode = <4>; + adi,ext-current-sense-resistor; + adi,slew = <0 64000 1>; + }; + channel@2 { + reg = <2>; + adi,mode = <4>; + adi,ext-current-sense-resistor; + adi,slew = <0 64000 1>; + }; + channel@3 { + reg = <3>; + adi,mode = <4>; + adi,ext-current-sense-resistor; + adi,slew = <0 64000 1>; + }; +}; diff --git a/Documentation/devicetree/bindings/iio/pressure/bmp085.txt b/Documentation/devicetree/bindings/iio/pressure/bmp085.txt index d7a6deb6b21e..c7198a03c906 100644 --- a/Documentation/devicetree/bindings/iio/pressure/bmp085.txt +++ b/Documentation/devicetree/bindings/iio/pressure/bmp085.txt @@ -1,7 +1,11 @@ -BMP085/BMP18x digital pressure sensors +BMP085/BMP18x/BMP28x digital pressure sensors Required properties: -- compatible: bosch,bmp085 +- compatible: must be one of: + "bosch,bmp085" + "bosch,bmp180" + "bosch,bmp280" + "bosch,bme280" Optional properties: - chip-id: configurable chip id for non-default chip revisions @@ -10,6 +14,10 @@ Optional properties: value range is 0-3 with rising sensitivity. - interrupt-parent: should be the phandle for the interrupt controller - interrupts: interrupt mapping for IRQ +- reset-gpios: a GPIO line handling reset of the sensor: as the line is + active low, it should be marked GPIO_ACTIVE_LOW (see gpio/gpio.txt) +- vddd-supply: digital voltage regulator (see regulator/regulator.txt) +- vdda-supply: analog voltage regulator (see regulator/regulator.txt) Example: @@ -21,4 +29,7 @@ pressure@77 { default-oversampling = <2>; interrupt-parent = <&gpio0>; interrupts = <25 IRQ_TYPE_EDGE_RISING>; + reset-gpios = <&gpio0 26 GPIO_ACTIVE_LOW>; + vddd-supply = <&foo>; + vdda-supply = <&bar>; }; diff --git a/Documentation/devicetree/bindings/iio/st-sensors.txt b/Documentation/devicetree/bindings/iio/st-sensors.txt index 5844cf72862d..e41fe340162b 100644 --- a/Documentation/devicetree/bindings/iio/st-sensors.txt +++ b/Documentation/devicetree/bindings/iio/st-sensors.txt @@ -64,3 +64,4 @@ Pressure sensors: - st,lps001wp-press - st,lps25h-press - st,lps331ap-press +- st,lps22hb-press diff --git a/Documentation/devicetree/bindings/interrupt-controller/arm,gic.txt b/Documentation/devicetree/bindings/interrupt-controller/arm,gic.txt index 793c20ff8fcc..5393e2a45a42 100644 --- a/Documentation/devicetree/bindings/interrupt-controller/arm,gic.txt +++ b/Documentation/devicetree/bindings/interrupt-controller/arm,gic.txt @@ -21,6 +21,7 @@ Main node required properties: "arm,pl390" "arm,tc11mp-gic" "brcm,brahma-b15-gic" + "nvidia,tegra210-agic" "qcom,msm-8660-qgic" "qcom,msm-qgic2" - interrupt-controller : Identifies the node as an interrupt controller @@ -68,7 +69,7 @@ Optional "ic_clk" (for "arm,arm11mp-gic") "PERIPHCLKEN" (for "arm,cortex-a15-gic") "PERIPHCLK", "PERIPHCLKEN" (for "arm,cortex-a9-gic") - "clk" (for "arm,gic-400") + "clk" (for "arm,gic-400" and "nvidia,tegra210") "gclk" (for "arm,pl390") - power-domains : A phandle and PM domain specifier as defined by bindings of diff --git a/Documentation/devicetree/bindings/interrupt-controller/aspeed,ast2400-vic.txt b/Documentation/devicetree/bindings/interrupt-controller/aspeed,ast2400-vic.txt new file mode 100644 index 000000000000..6c6e85324b9d --- /dev/null +++ b/Documentation/devicetree/bindings/interrupt-controller/aspeed,ast2400-vic.txt @@ -0,0 +1,22 @@ +Aspeed Vectored Interrupt Controller + +These bindings are for the Aspeed AST2400 interrupt controller register layout. +The SoC has an legacy register layout, but this driver does not support that +mode of operation. + +Required properties: + +- compatible : should be "aspeed,ast2400-vic". + +- 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. + +Example: + + vic: interrupt-controller@1e6c0080 { + compatible = "aspeed,ast2400-vic"; + interrupt-controller; + #interrupt-cells = <1>; + reg = <0x1e6c0080 0x80>; + }; diff --git a/Documentation/devicetree/bindings/media/mediatek-vcodec.txt b/Documentation/devicetree/bindings/media/mediatek-vcodec.txt new file mode 100644 index 000000000000..59a47a5b924b --- /dev/null +++ b/Documentation/devicetree/bindings/media/mediatek-vcodec.txt @@ -0,0 +1,59 @@ +Mediatek Video Codec + +Mediatek Video Codec is the video codec hw present in Mediatek SoCs which +supports high resolution encoding functionalities. + +Required properties: +- compatible : "mediatek,mt8173-vcodec-enc" for encoder +- reg : Physical base address of the video codec registers and length of + memory mapped region. +- interrupts : interrupt number to the cpu. +- mediatek,larb : must contain the local arbiters in the current Socs. +- clocks : list of clock specifiers, corresponding to entries in + the clock-names property. +- clock-names: encoder must contain "venc_sel_src", "venc_sel", +- "venc_lt_sel_src", "venc_lt_sel". +- iommus : should point to the respective IOMMU block with master port as + argument, see Documentation/devicetree/bindings/iommu/mediatek,iommu.txt + for details. +- mediatek,vpu : the node of video processor unit + +Example: +vcodec_enc: vcodec@0x18002000 { + compatible = "mediatek,mt8173-vcodec-enc"; + reg = <0 0x18002000 0 0x1000>, /*VENC_SYS*/ + <0 0x19002000 0 0x1000>; /*VENC_LT_SYS*/ + interrupts = <GIC_SPI 198 IRQ_TYPE_LEVEL_LOW>, + <GIC_SPI 202 IRQ_TYPE_LEVEL_LOW>; + mediatek,larb = <&larb3>, + <&larb5>; + iommus = <&iommu M4U_PORT_VENC_RCPU>, + <&iommu M4U_PORT_VENC_REC>, + <&iommu M4U_PORT_VENC_BSDMA>, + <&iommu M4U_PORT_VENC_SV_COMV>, + <&iommu M4U_PORT_VENC_RD_COMV>, + <&iommu M4U_PORT_VENC_CUR_LUMA>, + <&iommu M4U_PORT_VENC_CUR_CHROMA>, + <&iommu M4U_PORT_VENC_REF_LUMA>, + <&iommu M4U_PORT_VENC_REF_CHROMA>, + <&iommu M4U_PORT_VENC_NBM_RDMA>, + <&iommu M4U_PORT_VENC_NBM_WDMA>, + <&iommu M4U_PORT_VENC_RCPU_SET2>, + <&iommu M4U_PORT_VENC_REC_FRM_SET2>, + <&iommu M4U_PORT_VENC_BSDMA_SET2>, + <&iommu M4U_PORT_VENC_SV_COMA_SET2>, + <&iommu M4U_PORT_VENC_RD_COMA_SET2>, + <&iommu M4U_PORT_VENC_CUR_LUMA_SET2>, + <&iommu M4U_PORT_VENC_CUR_CHROMA_SET2>, + <&iommu M4U_PORT_VENC_REF_LUMA_SET2>, + <&iommu M4U_PORT_VENC_REC_CHROMA_SET2>; + mediatek,vpu = <&vpu>; + clocks = <&topckgen CLK_TOP_VENCPLL_D2>, + <&topckgen CLK_TOP_VENC_SEL>, + <&topckgen CLK_TOP_UNIVPLL1_D2>, + <&topckgen CLK_TOP_VENC_LT_SEL>; + clock-names = "venc_sel_src", + "venc_sel", + "venc_lt_sel_src", + "venc_lt_sel"; + }; diff --git a/Documentation/devicetree/bindings/media/mediatek-vpu.txt b/Documentation/devicetree/bindings/media/mediatek-vpu.txt new file mode 100644 index 000000000000..2a5bac37f9a2 --- /dev/null +++ b/Documentation/devicetree/bindings/media/mediatek-vpu.txt @@ -0,0 +1,31 @@ +* Mediatek Video Processor Unit + +Video Processor Unit is a HW video controller. It controls HW Codec including +H.264/VP8/VP9 Decode, H.264/VP8 Encode and Image Processor (scale/rotate/color convert). + +Required properties: + - compatible: "mediatek,mt8173-vpu" + - reg: Must contain an entry for each entry in reg-names. + - reg-names: Must include the following entries: + "tcm": tcm base + "cfg_reg": Main configuration registers base + - interrupts: interrupt number to the cpu. + - clocks : clock name from clock manager + - clock-names: must be main. It is the main clock of VPU + +Optional properties: + - memory-region: phandle to a node describing memory (see + Documentation/devicetree/bindings/reserved-memory/reserved-memory.txt) + to be used for VPU extended memory; if not present, VPU may be located + anywhere in the memory + +Example: + vpu: vpu@10020000 { + compatible = "mediatek,mt8173-vpu"; + reg = <0 0x10020000 0 0x30000>, + <0 0x10050000 0 0x100>; + reg-names = "tcm", "cfg_reg"; + interrupts = <GIC_SPI 166 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&topckgen TOP_SCP_SEL>; + clock-names = "main"; + }; diff --git a/Documentation/devicetree/bindings/media/renesas,fcp.txt b/Documentation/devicetree/bindings/media/renesas,fcp.txt new file mode 100644 index 000000000000..6a12960609d8 --- /dev/null +++ b/Documentation/devicetree/bindings/media/renesas,fcp.txt @@ -0,0 +1,32 @@ +Renesas R-Car Frame Compression Processor (FCP) +----------------------------------------------- + +The FCP is a companion module of video processing modules in the Renesas R-Car +Gen3 SoCs. It provides data compression and decompression, data caching, and +conversion of AXI transactions in order to reduce the memory bandwidth. + +There are three types of FCP: FCP for Codec (FCPC), FCP for VSP (FCPV) and FCP +for FDP (FCPF). Their configuration and behaviour depend on the module they +are paired with. These DT bindings currently support the FCPV only. + + - compatible: Must be one or more of the following + + - "renesas,r8a7795-fcpv" for R8A7795 (R-Car H3) compatible 'FCP for VSP' + - "renesas,fcpv" for generic compatible 'FCP for VSP' + + When compatible with the generic version, nodes must list the + SoC-specific version corresponding to the platform first, followed by the + family-specific and/or generic versions. + + - reg: the register base and size for the device registers + - clocks: Reference to the functional clock + + +Device node example +------------------- + + fcpvd1: fcp@fea2f000 { + compatible = "renesas,r8a7795-fcpv", "renesas,fcpv"; + reg = <0 0xfea2f000 0 0x200>; + clocks = <&cpg CPG_MOD 602>; + }; diff --git a/Documentation/devicetree/bindings/media/renesas,vsp1.txt b/Documentation/devicetree/bindings/media/renesas,vsp1.txt index 627405abd144..9b695bcbf219 100644 --- a/Documentation/devicetree/bindings/media/renesas,vsp1.txt +++ b/Documentation/devicetree/bindings/media/renesas,vsp1.txt @@ -14,6 +14,11 @@ Required properties: - interrupts: VSP interrupt specifier. - clocks: A phandle + clock-specifier pair for the VSP functional clock. +Optional properties: + + - renesas,fcp: A phandle referencing the FCP that handles memory accesses + for the VSP. Not needed on Gen2, mandatory on Gen3. + Example: R8A7790 (R-Car H2) VSP1-S node diff --git a/Documentation/devicetree/bindings/media/s5p-cec.txt b/Documentation/devicetree/bindings/media/s5p-cec.txt new file mode 100644 index 000000000000..925ab4d72eaa --- /dev/null +++ b/Documentation/devicetree/bindings/media/s5p-cec.txt @@ -0,0 +1,31 @@ +* Samsung HDMI CEC driver + +The HDMI CEC module is present is Samsung SoCs and its purpose is to +handle communication between HDMI connected devices over the CEC bus. + +Required properties: + - compatible : value should be following + "samsung,s5p-cec" + + - reg : Physical base address of the IP registers and length of memory + mapped region. + + - interrupts : HDMI CEC interrupt number to the CPU. + - clocks : from common clock binding: handle to HDMI CEC clock. + - clock-names : from common clock binding: must contain "hdmicec", + corresponding to entry in the clocks property. + - samsung,syscon-phandle - phandle to the PMU system controller + +Example: + +hdmicec: cec@100B0000 { + compatible = "samsung,s5p-cec"; + reg = <0x100B0000 0x200>; + interrupts = <0 114 0>; + clocks = <&clock CLK_HDMI_CEC>; + clock-names = "hdmicec"; + samsung,syscon-phandle = <&pmu_system_controller>; + pinctrl-names = "default"; + pinctrl-0 = <&hdmi_cec>; + status = "okay"; +}; diff --git a/Documentation/devicetree/bindings/media/s5p-mfc.txt b/Documentation/devicetree/bindings/media/s5p-mfc.txt index 2d5787eac91a..92c94f5ecbf1 100644 --- a/Documentation/devicetree/bindings/media/s5p-mfc.txt +++ b/Documentation/devicetree/bindings/media/s5p-mfc.txt @@ -21,15 +21,18 @@ Required properties: - clock-names : from common clock binding: must contain "mfc", corresponding to entry in the clocks property. - - samsung,mfc-r : Base address of the first memory bank used by MFC - for DMA contiguous memory allocation and its size. - - - samsung,mfc-l : Base address of the second memory bank used by MFC - for DMA contiguous memory allocation and its size. - Optional properties: - power-domains : power-domain property defined with a phandle to respective power domain. + - memory-region : from reserved memory binding: phandles to two reserved + memory regions, first is for "left" mfc memory bus interfaces, + second if for the "right" mfc memory bus, used when no SYSMMU + support is available + +Obsolete properties: + - samsung,mfc-r, samsung,mfc-l : support removed, please use memory-region + property instead + Example: SoC specific DT entry: @@ -43,9 +46,29 @@ mfc: codec@13400000 { clock-names = "mfc"; }; +Reserved memory specific DT entry for given board (see reserved memory binding +for more information): + +reserved-memory { + #address-cells = <1>; + #size-cells = <1>; + ranges; + + mfc_left: region@51000000 { + compatible = "shared-dma-pool"; + no-map; + reg = <0x51000000 0x800000>; + }; + + mfc_right: region@43000000 { + compatible = "shared-dma-pool"; + no-map; + reg = <0x43000000 0x800000>; + }; +}; + Board specific DT entry: codec@13400000 { - samsung,mfc-r = <0x43000000 0x800000>; - samsung,mfc-l = <0x51000000 0x800000>; + memory-region = <&mfc_left>, <&mfc_right>; }; diff --git a/Documentation/devicetree/bindings/misc/ramoops.txt b/Documentation/devicetree/bindings/misc/ramoops.txt new file mode 100644 index 000000000000..cd02cec67d38 --- /dev/null +++ b/Documentation/devicetree/bindings/misc/ramoops.txt @@ -0,0 +1,48 @@ +Ramoops oops/panic logger +========================= + +ramoops provides persistent RAM storage for oops and panics, so they can be +recovered after a reboot. It is a backend to pstore, so this node is named +"ramoops" after the backend, rather than "pstore" which is the subsystem. + +Parts of this storage may be set aside for other persistent log buffers, such +as kernel log messages, or for optional ECC error-correction data. The total +size of these optional buffers must fit in the reserved region. + +Any remaining space will be used for a circular buffer of oops and panic +records. These records have a configurable size, with a size of 0 indicating +that they should be disabled. + +At least one of "record-size", "console-size", "ftrace-size", or "pmsg-size" +must be set non-zero, but are otherwise optional as listed below. + + +Required properties: + +- compatible: must be "ramoops" + +- memory-region: phandle to a region of memory that is preserved between + reboots + + +Optional properties: + +- ecc-size: enables ECC support and specifies ECC buffer size in bytes + (defaults to 0: no ECC) + +- record-size: maximum size in bytes of each dump done on oops/panic + (defaults to 0: disabled) + +- console-size: size in bytes of log buffer reserved for kernel messages + (defaults to 0: disabled) + +- ftrace-size: size in bytes of log buffer reserved for function tracing and + profiling (defaults to 0: disabled) + +- pmsg-size: size in bytes of log buffer reserved for userspace messages + (defaults to 0: disabled) + +- unbuffered: if present, use unbuffered mappings to map the reserved region + (defaults to buffered mappings) + +- no-dump-oops: if present, only dump panics (defaults to panics and oops) diff --git a/Documentation/devicetree/bindings/net/marvell-bt-sd8xxx.txt b/Documentation/devicetree/bindings/net/marvell-bt-sd8xxx.txt index 14aa6cf58201..6a9a63cb0543 100644 --- a/Documentation/devicetree/bindings/net/marvell-bt-sd8xxx.txt +++ b/Documentation/devicetree/bindings/net/marvell-bt-sd8xxx.txt @@ -13,10 +13,10 @@ Optional properties: initialization. This is an array of 28 values(u8). - marvell,wakeup-pin: It represents wakeup pin number of the bluetooth chip. - firmware will use the pin to wakeup host system. + firmware will use the pin to wakeup host system (u16). - marvell,wakeup-gap-ms: wakeup gap represents wakeup latency of the host platform. The value will be configured to firmware. This - is needed to work chip's sleep feature as expected. + is needed to work chip's sleep feature as expected (u16). - interrupt-parent: phandle of the parent interrupt controller - interrupts : interrupt pin number to the cpu. Driver will request an irq based on this interrupt number. During system suspend, the irq will be @@ -50,7 +50,7 @@ calibration data is also available in below example. 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>; - marvell,wakeup-pin = <0x0d>; - marvell,wakeup-gap-ms = <0x64>; + marvell,wakeup-pin = /bits/ 16 <0x0d>; + marvell,wakeup-gap-ms = /bits/ 16 <0x64>; }; }; diff --git a/Documentation/devicetree/bindings/phy/brcm-sata-phy.txt b/Documentation/devicetree/bindings/phy/brcm-sata-phy.txt index d0231209d846..6ccce09d8bbf 100644 --- a/Documentation/devicetree/bindings/phy/brcm-sata-phy.txt +++ b/Documentation/devicetree/bindings/phy/brcm-sata-phy.txt @@ -5,6 +5,7 @@ Required properties: "brcm,bcm7425-sata-phy" "brcm,bcm7445-sata-phy" "brcm,iproc-ns2-sata-phy" + "brcm,iproc-nsp-sata-phy" "brcm,phy-sata3" - address-cells: should be 1 - size-cells: should be 0 @@ -22,7 +23,8 @@ Sub-nodes required properties: Sub-nodes optional properties: - brcm,enable-ssc: use spread spectrum clocking (SSC) on this port - This property is not applicable for "brcm,iproc-ns2-sata-phy". + This property is not applicable for "brcm,iproc-ns2-sata-phy" and + "brcm,iproc-nsp-sata-phy". Example: sata-phy@f0458100 { diff --git a/Documentation/devicetree/bindings/phy/phy-da8xx-usb.txt b/Documentation/devicetree/bindings/phy/phy-da8xx-usb.txt new file mode 100644 index 000000000000..c26478be391b --- /dev/null +++ b/Documentation/devicetree/bindings/phy/phy-da8xx-usb.txt @@ -0,0 +1,40 @@ +TI DA8xx/OMAP-L1xx/AM18xx USB PHY + +Required properties: + - compatible: must be "ti,da830-usb-phy". + - #phy-cells: must be 1. + +This device controls the PHY for both the USB 1.1 OHCI and USB 2.0 OTG +controllers on DA8xx SoCs. Consumers of this device should use index 0 for +the USB 2.0 phy device and index 1 for the USB 1.1 phy device. + +It also requires a "syscon" node with compatible = "ti,da830-cfgchip", "syscon" +to access the CFGCHIP2 register. + +Example: + + cfgchip: cfgchip@1417c { + compatible = "ti,da830-cfgchip", "syscon"; + reg = <0x1417c 0x14>; + }; + + usb_phy: usb-phy { + compatible = "ti,da830-usb-phy"; + #phy-cells = <1>; + }; + + usb20: usb@200000 { + compatible = "ti,da830-musb"; + reg = <0x200000 0x1000>; + interrupts = <58>; + phys = <&usb_phy 0>; + phy-names = "usb-phy"; + }; + + usb11: usb@225000 { + compatible = "ti,da830-ohci"; + reg = <0x225000 0x1000>; + interrupts = <59>; + phys = <&usb_phy 1>; + phy-names = "usb-phy"; + }; diff --git a/Documentation/devicetree/bindings/phy/rockchip-usb-phy.txt b/Documentation/devicetree/bindings/phy/rockchip-usb-phy.txt index 68498d560354..cc6be9680a6d 100644 --- a/Documentation/devicetree/bindings/phy/rockchip-usb-phy.txt +++ b/Documentation/devicetree/bindings/phy/rockchip-usb-phy.txt @@ -5,11 +5,13 @@ Required properties: "rockchip,rk3066a-usb-phy" "rockchip,rk3188-usb-phy" "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 +Deprecated properties: + - rockchip,grf : phandle to the syscon managing the "general + register files" - phy should be a child of the GRF instead + Sub-nodes: Each PHY should be represented as a sub-node. @@ -28,14 +30,19 @@ Optional Properties: Example: -usbphy: phy { - compatible = "rockchip,rk3288-usb-phy"; - rockchip,grf = <&grf>; - #address-cells = <1>; - #size-cells = <0>; +grf: syscon@ff770000 { + compatible = "rockchip,rk3288-grf", "syscon", "simple-mfd"; + +... + + usbphy: phy { + compatible = "rockchip,rk3288-usb-phy"; + #address-cells = <1>; + #size-cells = <0>; - usbphy0: usb-phy0 { - #phy-cells = <0>; - reg = <0x320>; + usbphy0: usb-phy0 { + #phy-cells = <0>; + reg = <0x320>; + }; }; }; diff --git a/Documentation/devicetree/bindings/rng/brcm,bcm2835.txt b/Documentation/devicetree/bindings/rng/brcm,bcm2835.txt index 07ccdaa68324..26542690b578 100644 --- a/Documentation/devicetree/bindings/rng/brcm,bcm2835.txt +++ b/Documentation/devicetree/bindings/rng/brcm,bcm2835.txt @@ -2,7 +2,8 @@ BCM2835 Random number generator Required properties: -- compatible : should be "brcm,bcm2835-rng" +- compatible : should be "brcm,bcm2835-rng" or "brcm,bcm-nsp-rng" or + "brcm,bcm5301x-rng" - reg : Specifies base physical address and size of the registers. Example: @@ -11,3 +12,8 @@ rng { compatible = "brcm,bcm2835-rng"; reg = <0x7e104000 0x10>; }; + +rng@18033000 { + compatible = "brcm,bcm-nsp-rng"; + reg = <0x18033000 0x14>; +}; diff --git a/Documentation/devicetree/bindings/serial/8250.txt b/Documentation/devicetree/bindings/serial/8250.txt index 936ab5b87324..f5561ac7e17e 100644 --- a/Documentation/devicetree/bindings/serial/8250.txt +++ b/Documentation/devicetree/bindings/serial/8250.txt @@ -42,6 +42,9 @@ Optional properties: - auto-flow-control: one way to enable automatic flow control support. The driver is allowed to detect support for the capability even without this property. +- {rts,cts,dtr,dsr,rng,dcd}-gpios: specify a GPIO for RTS/CTS/DTR/DSR/RI/DCD + line respectively. It will use specified GPIO instead of the peripheral + function pin for the UART feature. If unsure, don't specify this property. Note: * fsl,ns16550: @@ -63,3 +66,19 @@ Example: interrupts = <10>; reg-shift = <2>; }; + +Example for OMAP UART using GPIO-based modem control signals: + + uart4: serial@49042000 { + compatible = "ti,omap3-uart"; + reg = <0x49042000 0x400>; + interrupts = <80>; + ti,hwmods = "uart4"; + clock-frequency = <48000000>; + cts-gpios = <&gpio3 5 GPIO_ACTIVE_LOW>; + rts-gpios = <&gpio3 6 GPIO_ACTIVE_LOW>; + dtr-gpios = <&gpio1 12 GPIO_ACTIVE_LOW>; + dsr-gpios = <&gpio1 13 GPIO_ACTIVE_LOW>; + dcd-gpios = <&gpio1 14 GPIO_ACTIVE_LOW>; + rng-gpios = <&gpio1 15 GPIO_ACTIVE_LOW>; + }; diff --git a/Documentation/devicetree/bindings/serial/renesas,sci-serial.txt b/Documentation/devicetree/bindings/serial/renesas,sci-serial.txt index 528c3b90f23c..1e4000d83aee 100644 --- a/Documentation/devicetree/bindings/serial/renesas,sci-serial.txt +++ b/Documentation/devicetree/bindings/serial/renesas,sci-serial.txt @@ -31,6 +31,8 @@ Required properties: - "renesas,hscif-r8a7794" for R8A7794 (R-Car E2) HSCIF compatible UART. - "renesas,scif-r8a7795" for R8A7795 (R-Car H3) SCIF compatible UART. - "renesas,hscif-r8a7795" for R8A7795 (R-Car H3) HSCIF compatible UART. + - "renesas,scif-r8a7796" for R8A7796 (R-Car M3-W) SCIF compatible UART. + - "renesas,hscif-r8a7796" for R8A7796 (R-Car M3-W) 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,rcar-gen1-scif" for R-Car Gen1 SCIF compatible UART, @@ -76,6 +78,10 @@ Optional properties: - 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". + - {cts,dsr,dcd,rng,rts,dtr}-gpios: Specify GPIOs for modem lines, cfr. the + generic serial DT bindings in serial.txt. + - uart-has-rtscts: Indicates dedicated lines for RTS/CTS hardware flow + control, cfr. the generic serial DT bindings in serial.txt. Example: aliases { diff --git a/Documentation/devicetree/bindings/timer/oxsemi,rps-timer.txt b/Documentation/devicetree/bindings/timer/oxsemi,rps-timer.txt new file mode 100644 index 000000000000..3ca89cd1caef --- /dev/null +++ b/Documentation/devicetree/bindings/timer/oxsemi,rps-timer.txt @@ -0,0 +1,17 @@ +Oxford Semiconductor OXNAS SoCs Family RPS Timer +================================================ + +Required properties: +- compatible: Should be "oxsemi,ox810se-rps-timer" +- reg : Specifies base physical address and size of the registers. +- interrupts : The interrupts of the two timers +- clocks : The phandle of the timer clock source + +example: + +timer0: timer@200 { + compatible = "oxsemi,ox810se-rps-timer"; + reg = <0x200 0x40>; + clocks = <&rpsclk>; + interrupts = <4 5>; +}; diff --git a/Documentation/devicetree/bindings/timer/rockchip,rk3288-timer.txt b/Documentation/devicetree/bindings/timer/rockchip,rk-timer.txt index 87f0b0042bae..a41b184d5538 100644 --- a/Documentation/devicetree/bindings/timer/rockchip,rk3288-timer.txt +++ b/Documentation/devicetree/bindings/timer/rockchip,rk-timer.txt @@ -1,7 +1,9 @@ -Rockchip rk3288 timer +Rockchip rk timer Required properties: -- compatible: shall be "rockchip,rk3288-timer" +- compatible: shall be one of: + "rockchip,rk3288-timer" - for rk3066, rk3036, rk3188, rk322x, rk3288, rk3368 + "rockchip,rk3399-timer" - for rk3399 - 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 diff --git a/Documentation/devicetree/bindings/usb/ci-hdrc-usb2.txt b/Documentation/devicetree/bindings/usb/ci-hdrc-usb2.txt index 1084e2bcbe1c..341dc67f3472 100644 --- a/Documentation/devicetree/bindings/usb/ci-hdrc-usb2.txt +++ b/Documentation/devicetree/bindings/usb/ci-hdrc-usb2.txt @@ -93,7 +93,7 @@ Example: phys = <&usb_phy0>; phy-names = "usb-phy"; vbus-supply = <®_usb0_vbus>; - gadget-itc-setting = <0x4>; /* 4 micro-frames */ + itc-setting = <0x4>; /* 4 micro-frames */ /* Incremental burst of unspecified length */ ahb-burst-config = <0x0>; tx-burst-size-dword = <0x10>; /* 64 bytes */ diff --git a/Documentation/devicetree/bindings/usb/usb-ohci.txt b/Documentation/devicetree/bindings/usb/usb-ohci.txt index 19233b7365e1..9df456968596 100644 --- a/Documentation/devicetree/bindings/usb/usb-ohci.txt +++ b/Documentation/devicetree/bindings/usb/usb-ohci.txt @@ -14,7 +14,7 @@ Optional properties: - clocks : a list of phandle + clock specifier pairs - phys : phandle + phy specifier pair - phy-names : "usb" -- resets : phandle + reset specifier pair +- resets : a list of phandle + reset specifier pairs Example: diff --git a/Documentation/devicetree/bindings/vendor-prefixes.txt b/Documentation/devicetree/bindings/vendor-prefixes.txt index a7440bcd67ff..2c2500df0dce 100644 --- a/Documentation/devicetree/bindings/vendor-prefixes.txt +++ b/Documentation/devicetree/bindings/vendor-prefixes.txt @@ -255,6 +255,7 @@ synology Synology, Inc. SUNW Sun Microsystems, Inc tbs TBS Technologies tcl Toby Churchill Ltd. +technexion TechNexion technologic Technologic Systems thine THine Electronics, Inc. ti Texas Instruments @@ -269,6 +270,7 @@ tronsmart Tronsmart truly Truly Semiconductors Limited tyan Tyan Computer Corporation upisemi uPI Semiconductor Corp. +uniwest United Western Technologies Corp (UniWest) urt United Radiant Technology Corporation usi Universal Scientific Industrial Co., Ltd. v3 V3 Semiconductor diff --git a/Documentation/dmaengine/provider.txt b/Documentation/dmaengine/provider.txt index 122b7f4876bb..91ce82d5f0c4 100644 --- a/Documentation/dmaengine/provider.txt +++ b/Documentation/dmaengine/provider.txt @@ -323,7 +323,7 @@ supported. * device_resume - Resumes a transfer on the channel - This command should operate synchronously on the channel, - pausing right away the work of the given channel + resuming right away the work of the given channel * device_terminate_all - Aborts all the pending and ongoing transfers on the channel diff --git a/Documentation/filesystems/ocfs2-online-filecheck.txt b/Documentation/filesystems/ocfs2-online-filecheck.txt index 1ab07860430d..139fab175c8a 100644 --- a/Documentation/filesystems/ocfs2-online-filecheck.txt +++ b/Documentation/filesystems/ocfs2-online-filecheck.txt @@ -5,12 +5,12 @@ This document will describe OCFS2 online file check feature. Introduction ============ -OCFS2 is often used in high-availaibility systems. However, OCFS2 usually +OCFS2 is often used in high-availability systems. However, OCFS2 usually converts the filesystem to read-only when encounters an error. This may not be necessary, since turning the filesystem read-only would affect other running processes as well, decreasing availability. Then, a mount option (errors=continue) is introduced, which would return the --EIO errno to the calling process and terminate furhter processing so that the +-EIO errno to the calling process and terminate further processing so that the filesystem is not corrupted further. The filesystem is not converted to read-only, and the problematic file's inode number is reported in the kernel log. The user can try to check/fix this file via online filecheck feature. @@ -44,7 +44,7 @@ There is a sysfs directory for each OCFS2 file system mounting: /sys/fs/ocfs2/<devname>/filecheck -Here, <devname> indicates the name of OCFS2 volumn device which has been already +Here, <devname> indicates the name of OCFS2 volume device which has been already mounted. The file above would accept inode numbers. This could be used to communicate with kernel space, tell which file(inode number) will be checked or fixed. Currently, three operations are supported, which includes checking @@ -76,14 +76,14 @@ The output is like this: This time, the <ERROR> column indicates whether this fix is successful or not. 3. The record cache is used to store the history of check/fix results. It's -defalut size is 10, and can be adjust between the range of 10 ~ 100. You can +default size is 10, and can be adjust between the range of 10 ~ 100. You can adjust the size like this: # echo "<size>" > /sys/fs/ocfs2/<devname>/filecheck/set Fixing stuff ============ -On receivng the inode, the filesystem would read the inode and the +On receiving the inode, the filesystem would read the inode and the file metadata. In case of errors, the filesystem would fix the errors and report the problems it fixed in the kernel log. As a precautionary measure, the inode must first be checked for errors before performing a final fix. diff --git a/Documentation/filesystems/proc.txt b/Documentation/filesystems/proc.txt index e8d00759bfa5..5b61eeae3f6e 100644 --- a/Documentation/filesystems/proc.txt +++ b/Documentation/filesystems/proc.txt @@ -725,7 +725,7 @@ IRQ, you can set it by doing: > echo 1 > /proc/irq/10/smp_affinity This means that only the first CPU will handle the IRQ, but you can also echo -5 which means that only the first and fourth CPU can handle the IRQ. +5 which means that only the first and third CPU can handle the IRQ. The contents of each smp_affinity file is the same by default: diff --git a/Documentation/gdb-kernel-debugging.txt b/Documentation/gdb-kernel-debugging.txt index 4ab7d43d0754..7050ce8794b9 100644 --- a/Documentation/gdb-kernel-debugging.txt +++ b/Documentation/gdb-kernel-debugging.txt @@ -139,27 +139,6 @@ Examples of using the Linux-provided gdb helpers start_comm = "swapper/2\000\000\000\000\000\000" } - o Dig into a radix tree data structure, such as the IRQ descriptors: - (gdb) print (struct irq_desc)$lx_radix_tree_lookup(irq_desc_tree, 18) - $6 = { - irq_common_data = { - state_use_accessors = 67584, - handler_data = 0x0 <__vectors_start>, - msi_desc = 0x0 <__vectors_start>, - affinity = {{ - bits = {65535} - }} - }, - irq_data = { - mask = 0, - irq = 18, - hwirq = 27, - common = 0xee803d80, - chip = 0xc0eb0854 <gic_data>, - domain = 0xee808000, - parent_data = 0x0 <__vectors_start>, - chip_data = 0xc0eb0854 <gic_data> - } <... trimmed ...> List of commands and functions ------------------------------ diff --git a/Documentation/hwmon/abituguru b/Documentation/hwmon/abituguru index f1d4fe4c366c..44013d23b3f0 100644 --- a/Documentation/hwmon/abituguru +++ b/Documentation/hwmon/abituguru @@ -24,7 +24,7 @@ Supported chips: AW9D-MAX) (2) 1) For revisions 2 and 3 uGuru's the driver can autodetect the sensortype (Volt or Temp) for bank1 sensors, for revision 1 uGuru's - this doesnot always work. For these uGuru's the autodection can + this does not always work. For these uGuru's the autodetection can be overridden with the bank1_types module param. For all 3 known revison 1 motherboards the correct use of this param is: bank1_types=1,1,0,0,0,0,0,2,0,0,0,0,2,0,0,1 diff --git a/Documentation/hwmon/ftsteutates b/Documentation/hwmon/ftsteutates new file mode 100644 index 000000000000..2a1bf69c6a26 --- /dev/null +++ b/Documentation/hwmon/ftsteutates @@ -0,0 +1,23 @@ +Kernel driver ftsteutates +===================== + +Supported chips: + * FTS Teutates + Prefix: 'ftsteutates' + Addresses scanned: I2C 0x73 (7-Bit) + +Author: Thilo Cestonaro <thilo.cestonaro@ts.fujitsu.com> + + +Description +----------- +The BMC Teutates is the Eleventh generation of Superior System +monitoring and thermal management solution. It is builds on the basic +functionality of the BMC Theseus and contains several new features and +enhancements. It can monitor up to 4 voltages, 16 temperatures and +8 fans. It also contains an integrated watchdog which is currently +implemented in this driver. + +Specification of the chip can be found here: +ftp:///pub/Mainboard-OEM-Sales/Services/Software&Tools/Linux_SystemMonitoring&Watchdog&GPIO/BMC-Teutates_Specification_V1.21.pdf +ftp:///pub/Mainboard-OEM-Sales/Services/Software&Tools/Linux_SystemMonitoring&Watchdog&GPIO/Fujitsu_mainboards-1-Sensors_HowTo-en-US.pdf diff --git a/Documentation/hwmon/ina3221 b/Documentation/hwmon/ina3221 new file mode 100644 index 000000000000..0ff74854cb2e --- /dev/null +++ b/Documentation/hwmon/ina3221 @@ -0,0 +1,35 @@ +Kernel driver ina3221 +===================== + +Supported chips: + * Texas Instruments INA3221 + Prefix: 'ina3221' + Addresses: I2C 0x40 - 0x43 + Datasheet: Publicly available at the Texas Instruments website + http://www.ti.com/ + +Author: Andrew F. Davis <afd@ti.com> + +Description +----------- + +The Texas Instruments INA3221 monitors voltage, current, and power on the high +side of up to three D.C. power supplies. The INA3221 monitors both shunt drop +and supply voltage, with programmable conversion times and averaging, current +and power are calculated host-side from these. + +Sysfs entries +------------- + +in[123]_input Bus voltage(mV) channels +curr[123]_input Current(mA) measurement channels +shunt[123]_resistor Shunt resistance(uOhm) channels +curr[123]_crit Critical alert current(mA) setting, activates the + corresponding alarm when the respective current + is above this value +curr[123]_crit_alarm Critical alert current limit exceeded +curr[123]_max Warning alert current(mA) setting, activates the + corresponding alarm when the respective current + average is above this value. +curr[123]_max_alarm Warning alert current limit exceeded +in[456]_input Shunt voltage(uV) for channels 1, 2, and 3 respectively diff --git a/Documentation/hwmon/jc42 b/Documentation/hwmon/jc42 index f7f1830a2566..b4b671f22453 100644 --- a/Documentation/hwmon/jc42 +++ b/Documentation/hwmon/jc42 @@ -18,10 +18,11 @@ Supported chips: * Maxim MAX6604 Datasheets: http://datasheets.maxim-ic.com/en/ds/MAX6604.pdf - * Microchip MCP9804, MCP9805, MCP98242, MCP98243, MCP98244, MCP9843 + * Microchip MCP9804, MCP9805, MCP9808, MCP98242, MCP98243, MCP98244, MCP9843 Datasheets: http://ww1.microchip.com/downloads/en/DeviceDoc/22203C.pdf http://ww1.microchip.com/downloads/en/DeviceDoc/21977b.pdf + http://ww1.microchip.com/downloads/en/DeviceDoc/25095A.pdf http://ww1.microchip.com/downloads/en/DeviceDoc/21996a.pdf http://ww1.microchip.com/downloads/en/DeviceDoc/22153c.pdf http://ww1.microchip.com/downloads/en/DeviceDoc/22327A.pdf diff --git a/Documentation/hwmon/max1668 b/Documentation/hwmon/max1668 index 0616ed9758df..8f9d570dbfec 100644 --- a/Documentation/hwmon/max1668 +++ b/Documentation/hwmon/max1668 @@ -17,7 +17,7 @@ This driver implements support for the Maxim MAX1668, MAX1805 and MAX1989 chips. The three devices are very similar, but the MAX1805 has a reduced feature -set; only two remote temperature inputs vs the four avaible on the other +set; only two remote temperature inputs vs the four available on the other two ICs. The driver is able to distinguish between the devices and creates sysfs diff --git a/Documentation/hwmon/sht3x b/Documentation/hwmon/sht3x new file mode 100644 index 000000000000..b0d88184f48e --- /dev/null +++ b/Documentation/hwmon/sht3x @@ -0,0 +1,76 @@ +Kernel driver sht3x +=================== + +Supported chips: + * Sensirion SHT3x-DIS + Prefix: 'sht3x' + Addresses scanned: none + Datasheet: http://www.sensirion.com/fileadmin/user_upload/customers/sensirion/Dokumente/Humidity/Sensirion_Humidity_Datasheet_SHT3x_DIS.pdf + +Author: + David Frey <david.frey@sensirion.com> + Pascal Sachs <pascal.sachs@sensirion.com> + +Description +----------- + +This driver implements support for the Sensirion SHT3x-DIS chip, a humidity +and temperature sensor. Temperature is measured in degrees celsius, relative +humidity is expressed as a percentage. In the sysfs interface, all values are +scaled by 1000, i.e. the value for 31.5 degrees celsius is 31500. + +The device communicates with the I2C protocol. Sensors can have the I2C +addresses 0x44 or 0x45, depending on the wiring. See +Documentation/i2c/instantiating-devices for methods to instantiate the device. + +There are two options configurable by means of sht3x_platform_data: +1. blocking (pull the I2C clock line down while performing the measurement) or + non-blocking mode. Blocking mode will guarantee the fastest result but + the I2C bus will be busy during that time. By default, non-blocking mode + is used. Make sure clock-stretching works properly on your device if you + want to use blocking mode. +2. high or low accuracy. High accuracy is used by default and using it is + strongly recommended. + +The sht3x sensor supports a single shot mode as well as 5 periodic measure +modes, which can be controlled with the update_interval sysfs interface. +The allowed update_interval in milliseconds are as follows: + * 0 single shot mode + * 2000 0.5 Hz periodic measurement + * 1000 1 Hz periodic measurement + * 500 2 Hz periodic measurement + * 250 4 Hz periodic measurement + * 100 10 Hz periodic measurement + +In the periodic measure mode, the sensor automatically triggers a measurement +with the configured update interval on the chip. When a temperature or humidity +reading exceeds the configured limits, the alert attribute is set to 1 and +the alert pin on the sensor is set to high. +When the temperature and humidity readings move back between the hysteresis +values, the alert bit is set to 0 and the alert pin on the sensor is set to +low. + +sysfs-Interface +--------------- + +temp1_input: temperature input +humidity1_input: humidity input +temp1_max: temperature max value +temp1_max_hyst: temperature hysteresis value for max limit +humidity1_max: humidity max value +humidity1_max_hyst: humidity hysteresis value for max limit +temp1_min: temperature min value +temp1_min_hyst: temperature hysteresis value for min limit +humidity1_min: humidity min value +humidity1_min_hyst: humidity hysteresis value for min limit +temp1_alarm: alarm flag is set to 1 if the temperature is outside the + configured limits. Alarm only works in periodic measure mode +humidity1_alarm: alarm flag is set to 1 if the humidity is outside the + configured limits. Alarm only works in periodic measure mode +heater_enable: heater enable, heating element removes excess humidity from + sensor + 0: turned off + 1: turned on +update_interval: update interval, 0 for single shot, interval in msec + for periodic measurement. If the interval is not supported + by the sensor, the next faster interval is chosen diff --git a/Documentation/hwmon/submitting-patches b/Documentation/hwmon/submitting-patches index d201828d202f..57f60307accc 100644 --- a/Documentation/hwmon/submitting-patches +++ b/Documentation/hwmon/submitting-patches @@ -15,10 +15,15 @@ increase the chances of your change being accepted. Documentation/SubmittingPatches Documentation/CodingStyle -* If your patch generates checkpatch warnings, please refrain from explanations - such as "I don't like that coding style". Keep in mind that each unnecessary - warning helps hiding a real problem. If you don't like the kernel coding - style, don't write kernel drivers. +* Please run your patch through 'checkpatch --strict'. There should be no + errors, no warnings, and few if any check messages. If there are any + messages, please be prepared to explain. + +* If your patch generates checkpatch errors, warnings, or check messages, + please refrain from explanations such as "I prefer that coding style". + Keep in mind that each unnecessary message helps hiding a real problem, + and a consistent coding style makes it easier for others to understand + and review the code. * Please test your patch thoroughly. We are not your test group. Sometimes a patch can not or not completely be tested because of missing @@ -61,15 +66,30 @@ increase the chances of your change being accepted. * Make sure that all dependencies are listed in Kconfig. +* Please list include files in alphabetic order. + +* Please align continuation lines with '(' on the previous line. + * Avoid forward declarations if you can. Rearrange the code if necessary. +* Avoid macros to generate groups of sensor attributes. It not only confuses + checkpatch, but also makes it more difficult to review the code. + * Avoid calculations in macros and macro-generated functions. While such macros may save a line or so in the source, it obfuscates the code and makes code review more difficult. It may also result in code which is more complicated than necessary. Use inline functions or just regular functions instead. +* Limit the number of kernel log messages. In general, your driver should not + generate an error message just because a runtime operation failed. Report + errors to user space instead, using an appropriate error code. Keep in mind + that kernel error log messages not only fill up the kernel log, but also are + printed synchronously, most likely with interrupt disabled, often to a serial + console. Excessive logging can seriously affect system performance. + * Use devres functions whenever possible to allocate resources. For rationale and supported functions, please see Documentation/driver-model/devres.txt. + If a function is not supported by devres, consider using devm_add_action(). * If the driver has a detect function, make sure it is silent. Debug messages and messages printed after a successful detection are acceptable, but it @@ -96,8 +116,16 @@ increase the chances of your change being accepted. writing to it might cause a bad misconfiguration. * Make sure there are no race conditions in the probe function. Specifically, - completely initialize your chip first, then create sysfs entries and register - with the hwmon subsystem. + completely initialize your chip and your driver first, then register with + the hwmon subsystem. + +* Use devm_hwmon_device_register_with_groups() or, if your driver needs a remove + function, hwmon_device_register_with_groups() to register your driver with the + hwmon subsystem. Try using devm_add_action() instead of a remove function if + possible. Do not use hwmon_device_register(). + +* Your driver should be buildable as module. If not, please be prepared to + explain why it has to be built into the kernel. * Do not provide support for deprecated sysfs attributes. diff --git a/Documentation/hwmon/tmp401 b/Documentation/hwmon/tmp401 index 711f75e189eb..2d9ca42213cf 100644 --- a/Documentation/hwmon/tmp401 +++ b/Documentation/hwmon/tmp401 @@ -22,6 +22,9 @@ Supported chips: Prefix: 'tmp435' Addresses scanned: I2C 0x48 - 0x4f Datasheet: http://focus.ti.com/docs/prod/folders/print/tmp435.html + * Texas Instruments TMP461 + Prefix: 'tmp461' + Datasheet: http://www.ti.com/product/tmp461 Authors: Hans de Goede <hdegoede@redhat.com> @@ -31,8 +34,8 @@ Description ----------- This driver implements support for Texas Instruments TMP401, TMP411, -TMP431, TMP432 and TMP435 chips. These chips implement one or two remote -and one local temperature sensors. Temperature is measured in degrees +TMP431, TMP432, TMP435, and TMP461 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 @@ -55,3 +58,10 @@ some additional features. TMP432 is compatible with TMP401 and TMP431. It supports two external temperature sensors. + +TMP461 is compatible with TMP401. It supports offset correction +that is applied to the remote sensor. + +* Sensor offset values are temperature values + + Exported via sysfs attribute tempX_offset diff --git a/Documentation/index.rst b/Documentation/index.rst new file mode 100644 index 000000000000..f92854f01773 --- /dev/null +++ b/Documentation/index.rst @@ -0,0 +1,22 @@ +.. The Linux Kernel documentation master file, created by + sphinx-quickstart on Fri Feb 12 13:51:46 2016. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Welcome to The Linux Kernel's documentation! +============================================ + +Nothing for you to see here *yet*. Please move along. + +Contents: + +.. toctree:: + :maxdepth: 2 + + kernel-documentation + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`search` diff --git a/Documentation/ioctl/cdrom.txt b/Documentation/ioctl/cdrom.txt index 59df81c8da2b..a4d62a9d6771 100644 --- a/Documentation/ioctl/cdrom.txt +++ b/Documentation/ioctl/cdrom.txt @@ -340,7 +340,8 @@ CDROMSUBCHNL Read subchannel data (struct cdrom_subchnl) EINVAL format not CDROM_MSF or CDROM_LBA notes: - Format is converted to CDROM_MSF on return + Format is converted to CDROM_MSF or CDROM_LBA + as per user request on return diff --git a/Documentation/kbuild/makefiles.txt b/Documentation/kbuild/makefiles.txt index 13f888a02a3d..385a5ef41c17 100644 --- a/Documentation/kbuild/makefiles.txt +++ b/Documentation/kbuild/makefiles.txt @@ -47,6 +47,7 @@ This document describes the Linux kernel Makefiles. --- 7.2 genhdr-y --- 7.3 destination-y --- 7.4 generic-y + --- 7.5 generated-y === 8 Kbuild Variables === 9 Makefile language @@ -1319,6 +1320,19 @@ See subsequent chapter for the syntax of the Kbuild file. Example: termios.h #include <asm-generic/termios.h> + --- 7.5 generated-y + + If an architecture generates other header files alongside generic-y + wrappers, and not included in genhdr-y, then generated-y specifies + them. + + This prevents them being treated as stale asm-generic wrappers and + removed. + + Example: + #arch/x86/include/asm/Kbuild + generated-y += syscalls_32.h + === 8 Kbuild Variables The top Makefile exports the following variables: diff --git a/Documentation/kernel-doc-nano-HOWTO.txt b/Documentation/kernel-doc-nano-HOWTO.txt index 78f69cdc9b3f..062e3af271b7 100644 --- a/Documentation/kernel-doc-nano-HOWTO.txt +++ b/Documentation/kernel-doc-nano-HOWTO.txt @@ -1,3 +1,6 @@ +NOTE: this document is outdated and will eventually be removed. See +Documentation/kernel-documentation.rst for current information. + kernel-doc nano-HOWTO ===================== diff --git a/Documentation/kernel-documentation.rst b/Documentation/kernel-documentation.rst new file mode 100644 index 000000000000..c4eb5049da39 --- /dev/null +++ b/Documentation/kernel-documentation.rst @@ -0,0 +1,654 @@ +========================== +Linux Kernel Documentation +========================== + +Introduction +============ + +The Linux kernel uses `Sphinx`_ to generate pretty documentation from +`reStructuredText`_ files under ``Documentation``. To build the documentation in +HTML or PDF formats, use ``make htmldocs`` or ``make pdfdocs``. The generated +documentation is placed in ``Documentation/output``. + +.. _Sphinx: http://www.sphinx-doc.org/ +.. _reStructuredText: http://docutils.sourceforge.net/rst.html + +The reStructuredText files may contain directives to include structured +documentation comments, or kernel-doc comments, from source files. Usually these +are used to describe the functions and types and design of the code. The +kernel-doc comments have some special structure and formatting, but beyond that +they are also treated as reStructuredText. + +There is also the deprecated DocBook toolchain to generate documentation from +DocBook XML template files under ``Documentation/DocBook``. The DocBook files +are to be converted to reStructuredText, and the toolchain is slated to be +removed. + +Finally, there are thousands of plain text documentation files scattered around +``Documentation``. Some of these will likely be converted to reStructuredText +over time, but the bulk of them will remain in plain text. + +Sphinx Build +============ + +The usual way to generate the documentation is to run ``make htmldocs`` or +``make pdfdocs``. There are also other formats available, see the documentation +section of ``make help``. The generated documentation is placed in +format-specific subdirectories under ``Documentation/output``. + +To generate documentation, Sphinx (``sphinx-build``) must obviously be +installed. For prettier HTML output, the Read the Docs Sphinx theme +(``sphinx_rtd_theme``) is used if available. For PDF output, ``rst2pdf`` is also +needed. All of these are widely available and packaged in distributions. + +To pass extra options to Sphinx, you can use the ``SPHINXOPTS`` make +variable. For example, use ``make SPHINXOPTS=-v htmldocs`` to get more verbose +output. + +To remove the generated documentation, run ``make cleandocs``. + +Writing Documentation +===================== + +Adding new documentation can be as simple as: + +1. Add a new ``.rst`` file somewhere under ``Documentation``. +2. Refer to it from the Sphinx main `TOC tree`_ in ``Documentation/index.rst``. + +.. _TOC tree: http://www.sphinx-doc.org/en/stable/markup/toctree.html + +This is usually good enough for simple documentation (like the one you're +reading right now), but for larger documents it may be advisable to create a +subdirectory (or use an existing one). For example, the graphics subsystem +documentation is under ``Documentation/gpu``, split to several ``.rst`` files, +and has a separate ``index.rst`` (with a ``toctree`` of its own) referenced from +the main index. + +See the documentation for `Sphinx`_ and `reStructuredText`_ on what you can do +with them. In particular, the Sphinx `reStructuredText Primer`_ is a good place +to get started with reStructuredText. There are also some `Sphinx specific +markup constructs`_. + +.. _reStructuredText Primer: http://www.sphinx-doc.org/en/stable/rest.html +.. _Sphinx specific markup constructs: http://www.sphinx-doc.org/en/stable/markup/index.html + +Specific guidelines for the kernel documentation +------------------------------------------------ + +Here are some specific guidelines for the kernel documentation: + +* Please don't go overboard with reStructuredText markup. Keep it simple. + +* Please stick to this order of heading adornments: + + 1. ``=`` with overline for document title:: + + ============== + Document title + ============== + + 2. ``=`` for chapters:: + + Chapters + ======== + + 3. ``-`` for sections:: + + Section + ------- + + 4. ``~`` for subsections:: + + Subsection + ~~~~~~~~~~ + + Although RST doesn't mandate a specific order ("Rather than imposing a fixed + number and order of section title adornment styles, the order enforced will be + the order as encountered."), having the higher levels the same overall makes + it easier to follow the documents. + +list tables +----------- + +We recommend the use of *list table* formats. The *list table* formats are +double-stage lists. Compared to the ASCII-art they might not be as +comfortable for +readers of the text files. Their advantage is that they are easy to +create or modify and that the diff of a modification is much more meaningful, +because it is limited to the modified content. + +The ``flat-table`` is a double-stage list similar to the ``list-table`` with +some additional features: + +* column-span: with the role ``cspan`` a cell can be extended through + additional columns + +* row-span: with the role ``rspan`` a cell can be extended through + additional rows + +* auto span rightmost cell of a table row over the missing cells on the right + side of that table-row. With Option ``:fill-cells:`` this behavior can + changed from *auto span* to *auto fill*, which automatically inserts (empty) + cells instead of spanning the last cell. + +options: + +* ``:header-rows:`` [int] count of header rows +* ``:stub-columns:`` [int] count of stub columns +* ``:widths:`` [[int] [int] ... ] widths of columns +* ``:fill-cells:`` instead of auto-spanning missing cells, insert missing cells + +roles: + +* ``:cspan:`` [int] additional columns (*morecols*) +* ``:rspan:`` [int] additional rows (*morerows*) + +The example below shows how to use this markup. The first level of the staged +list is the *table-row*. In the *table-row* there is only one markup allowed, +the list of the cells in this *table-row*. Exceptions are *comments* ( ``..`` ) +and *targets* (e.g. a ref to ``:ref:`last row <last row>``` / :ref:`last row +<last row>`). + +.. code-block:: rst + + .. flat-table:: table title + :widths: 2 1 1 3 + + * - head col 1 + - head col 2 + - head col 3 + - head col 4 + + * - column 1 + - field 1.1 + - field 1.2 with autospan + + * - column 2 + - field 2.1 + - :rspan:`1` :cspan:`1` field 2.2 - 3.3 + + * .. _`last row`: + + - column 3 + +Rendered as: + + .. flat-table:: table title + :widths: 2 1 1 3 + + * - head col 1 + - head col 2 + - head col 3 + - head col 4 + + * - column 1 + - field 1.1 + - field 1.2 with autospan + + * - column 2 + - field 2.1 + - :rspan:`1` :cspan:`1` field 2.2 - 3.3 + + * .. _`last row`: + + - column 3 + + +Including kernel-doc comments +============================= + +The Linux kernel source files may contain structured documentation comments, or +kernel-doc comments to describe the functions and types and design of the +code. The documentation comments may be included to any of the reStructuredText +documents using a dedicated kernel-doc Sphinx directive extension. + +The kernel-doc directive is of the format:: + + .. kernel-doc:: source + :option: + +The *source* is the path to a source file, relative to the kernel source +tree. The following directive options are supported: + +export: *[source-pattern ...]* + Include documentation for all functions in *source* that have been exported + using ``EXPORT_SYMBOL`` or ``EXPORT_SYMBOL_GPL`` either in *source* or in any + of the files specified by *source-pattern*. + + The *source-pattern* is useful when the kernel-doc comments have been placed + in header files, while ``EXPORT_SYMBOL`` and ``EXPORT_SYMBOL_GPL`` are next to + the function definitions. + + Examples:: + + .. kernel-doc:: lib/bitmap.c + :export: + + .. kernel-doc:: include/net/mac80211.h + :export: net/mac80211/*.c + +internal: *[source-pattern ...]* + Include documentation for all functions and types in *source* that have + **not** been exported using ``EXPORT_SYMBOL`` or ``EXPORT_SYMBOL_GPL`` either + in *source* or in any of the files specified by *source-pattern*. + + Example:: + + .. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c + :internal: + +doc: *title* + Include documentation for the ``DOC:`` paragraph identified by *title* in + *source*. Spaces are allowed in *title*; do not quote the *title*. The *title* + is only used as an identifier for the paragraph, and is not included in the + output. Please make sure to have an appropriate heading in the enclosing + reStructuredText document. + + Example:: + + .. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c + :doc: High Definition Audio over HDMI and Display Port + +functions: *function* *[...]* + Include documentation for each *function* in *source*. + + Example:: + + .. kernel-doc:: lib/bitmap.c + :functions: bitmap_parselist bitmap_parselist_user + +Without options, the kernel-doc directive includes all documentation comments +from the source file. + +The kernel-doc extension is included in the kernel source tree, at +``Documentation/sphinx/kernel-doc.py``. Internally, it uses the +``scripts/kernel-doc`` script to extract the documentation comments from the +source. + +Writing kernel-doc comments +=========================== + +In order to provide embedded, "C" friendly, easy to maintain, but consistent and +extractable overview, function and type documentation, the Linux kernel has +adopted a consistent style for documentation comments. The format for this +documentation is called the kernel-doc format, described below. This style +embeds the documentation within the source files, using a few simple conventions +for adding documentation paragraphs and documenting functions and their +parameters, structures and unions and their members, enumerations, and typedefs. + +.. note:: The kernel-doc format is deceptively similar to gtk-doc or Doxygen, + yet distinctively different, for historical reasons. The kernel source + contains tens of thousands of kernel-doc comments. Please stick to the style + described here. + +The ``scripts/kernel-doc`` script is used by the Sphinx kernel-doc extension in +the documentation build to extract this embedded documentation into the various +HTML, PDF, and other format documents. + +In order to provide good documentation of kernel functions and data structures, +please use the following conventions to format your kernel-doc comments in the +Linux kernel source. + +How to format kernel-doc comments +--------------------------------- + +The opening comment mark ``/**`` is reserved for kernel-doc comments. Only +comments so marked will be considered by the ``kernel-doc`` tool. Use it only +for comment blocks that contain kernel-doc formatted comments. The usual ``*/`` +should be used as the closing comment marker. The lines in between should be +prefixed by `` * `` (space star space). + +The function and type kernel-doc comments should be placed just before the +function or type being described. The overview kernel-doc comments may be freely +placed at the top indentation level. + +Example kernel-doc function comment:: + + /** + * foobar() - Brief description of foobar. + * @arg: Description of argument of foobar. + * + * Longer description of foobar. + * + * Return: Description of return value of foobar. + */ + int foobar(int arg) + +The format is similar for documentation for structures, enums, paragraphs, +etc. See the sections below for details. + +The kernel-doc structure is extracted from the comments, and proper `Sphinx C +Domain`_ function and type descriptions with anchors are generated for them. The +descriptions are filtered for special kernel-doc highlights and +cross-references. See below for details. + +.. _Sphinx C Domain: http://www.sphinx-doc.org/en/stable/domains.html + +Highlights and cross-references +------------------------------- + +The following special patterns are recognized in the kernel-doc comment +descriptive text and converted to proper reStructuredText markup and `Sphinx C +Domain`_ references. + +.. attention:: The below are **only** recognized within kernel-doc comments, + **not** within normal reStructuredText documents. + +``funcname()`` + Function reference. + +``@parameter`` + Name of a function parameter. (No cross-referencing, just formatting.) + +``%CONST`` + Name of a constant. (No cross-referencing, just formatting.) + +``$ENVVAR`` + Name of an environment variable. (No cross-referencing, just formatting.) + +``&struct name`` + Structure reference. + +``&enum name`` + Enum reference. + +``&typedef name`` + Typedef reference. + +``&struct_name->member`` or ``&struct_name.member`` + Structure or union member reference. The cross-reference will be to the struct + or union definition, not the member directly. + +``&name`` + A generic type reference. Prefer using the full reference described above + instead. This is mostly for legacy comments. + +Cross-referencing from reStructuredText +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. highlight:: none + +To cross-reference the functions and types defined in the kernel-doc comments +from reStructuredText documents, please use the `Sphinx C Domain`_ +references. For example:: + + See function :c:func:`foo` and struct/union/enum/typedef :c:type:`bar`. + +While the type reference works with just the type name, without the +struct/union/enum/typedef part in front, you may want to use:: + + See :c:type:`struct foo <foo>`. + See :c:type:`union bar <bar>`. + See :c:type:`enum baz <baz>`. + See :c:type:`typedef meh <meh>`. + +This will produce prettier links, and is in line with how kernel-doc does the +cross-references. + +For further details, please refer to the `Sphinx C Domain`_ documentation. + +Function documentation +---------------------- + +.. highlight:: c + +The general format of a function and function-like macro kernel-doc comment is:: + + /** + * function_name() - Brief description of function. + * @arg1: Describe the first argument. + * @arg2: Describe the second argument. + * One can provide multiple line descriptions + * for arguments. + * + * A longer description, with more discussion of the function function_name() + * that might be useful to those using or modifying it. Begins with an + * empty comment line, and may include additional embedded empty + * comment lines. + * + * The longer description may have multiple paragraphs. + * + * Return: Describe the return value of foobar. + * + * The return value description can also have multiple paragraphs, and should + * be placed at the end of the comment block. + */ + +The brief description following the function name may span multiple lines, and +ends with an ``@argument:`` description, a blank comment line, or the end of the +comment block. + +The kernel-doc function comments describe each parameter to the function, in +order, with the ``@argument:`` descriptions. The ``@argument:`` descriptions +must begin on the very next line following the opening brief function +description line, with no intervening blank comment lines. The ``@argument:`` +descriptions may span multiple lines. The continuation lines may contain +indentation. If a function parameter is ``...`` (varargs), it should be listed +in kernel-doc notation as: ``@...:``. + +The return value, if any, should be described in a dedicated section at the end +of the comment starting with "Return:". + +Structure, union, and enumeration documentation +----------------------------------------------- + +The general format of a struct, union, and enum kernel-doc comment is:: + + /** + * struct struct_name - Brief description. + * @member_name: Description of member member_name. + * + * Description of the structure. + */ + +Below, "struct" is used to mean structs, unions and enums, and "member" is used +to mean struct and union members as well as enumerations in an enum. + +The brief description following the structure name may span multiple lines, and +ends with a ``@member:`` description, a blank comment line, or the end of the +comment block. + +The kernel-doc data structure comments describe each member of the structure, in +order, with the ``@member:`` descriptions. The ``@member:`` descriptions must +begin on the very next line following the opening brief function description +line, with no intervening blank comment lines. The ``@member:`` descriptions may +span multiple lines. The continuation lines may contain indentation. + +In-line member documentation comments +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The structure members may also be documented in-line within the definition:: + + /** + * struct foo - Brief description. + * @foo: The Foo member. + */ + struct foo { + int foo; + /** + * @bar: The Bar member. + */ + int bar; + /** + * @baz: The Baz member. + * + * Here, the member description may contain several paragraphs. + */ + int baz; + } + +Private members +~~~~~~~~~~~~~~~ + +Inside a struct description, you can use the "private:" and "public:" comment +tags. Structure fields that are inside a "private:" area are not listed in the +generated output documentation. The "private:" and "public:" tags must begin +immediately following a ``/*`` comment marker. They may optionally include +comments between the ``:`` and the ending ``*/`` marker. + +Example:: + + /** + * struct my_struct - short description + * @a: first member + * @b: second member + * + * Longer description + */ + struct my_struct { + int a; + int b; + /* private: internal use only */ + int c; + }; + + +Typedef documentation +--------------------- + +The general format of a typedef kernel-doc comment is:: + + /** + * typedef type_name - Brief description. + * + * Description of the type. + */ + +Overview documentation comments +------------------------------- + +To facilitate having source code and comments close together, you can include +kernel-doc documentation blocks that are free-form comments instead of being +kernel-doc for functions, structures, unions, enums, or typedefs. This could be +used for something like a theory of operation for a driver or library code, for +example. + +This is done by using a ``DOC:`` section keyword with a section title. + +The general format of an overview or high-level documentation comment is:: + + /** + * DOC: Theory of Operation + * + * The whizbang foobar is a dilly of a gizmo. It can do whatever you + * want it to do, at any time. It reads your mind. Here's how it works. + * + * foo bar splat + * + * The only drawback to this gizmo is that is can sometimes damage + * hardware, software, or its subject(s). + */ + +The title following ``DOC:`` acts as a heading within the source file, but also +as an identifier for extracting the documentation comment. Thus, the title must +be unique within the file. + +Recommendations +--------------- + +We definitely need kernel-doc formatted documentation for functions that are +exported to loadable modules using ``EXPORT_SYMBOL`` or ``EXPORT_SYMBOL_GPL``. + +We also look to provide kernel-doc formatted documentation for functions +externally visible to other kernel files (not marked "static"). + +We also recommend providing kernel-doc formatted documentation for private (file +"static") routines, for consistency of kernel source code layout. But this is +lower priority and at the discretion of the MAINTAINER of that kernel source +file. + +Data structures visible in kernel include files should also be documented using +kernel-doc formatted comments. + +DocBook XML [DEPRECATED] +======================== + +.. attention:: + + This section describes the deprecated DocBook XML toolchain. Please do not + create new DocBook XML template files. Please consider converting existing + DocBook XML templates files to Sphinx/reStructuredText. + +Converting DocBook to Sphinx +---------------------------- + +.. highlight:: none + +Over time, we expect all of the documents under ``Documentation/DocBook`` to be +converted to Sphinx and reStructuredText. For most DocBook XML documents, a good +enough solution is to use the simple ``Documentation/sphinx/tmplcvt`` script, +which uses ``pandoc`` under the hood. For example:: + + $ cd Documentation/sphinx + $ ./tmplcvt ../DocBook/in.tmpl ../out.rst + +Then edit the resulting rst files to fix any remaining issues, and add the +document in the ``toctree`` in ``Documentation/index.rst``. + +Components of the kernel-doc system +----------------------------------- + +Many places in the source tree have extractable documentation in the form of +block comments above functions. The components of this system are: + +- ``scripts/kernel-doc`` + + This is a perl script that hunts for the block comments and can mark them up + directly into reStructuredText, DocBook, man, text, and HTML. (No, not + texinfo.) + +- ``Documentation/DocBook/*.tmpl`` + + These are XML template files, which are normal XML files with special + place-holders for where the extracted documentation should go. + +- ``scripts/docproc.c`` + + This is a program for converting XML template files into XML files. When a + file is referenced it is searched for symbols exported (EXPORT_SYMBOL), to be + able to distinguish between internal and external functions. + + It invokes kernel-doc, giving it the list of functions that are to be + documented. + + Additionally it is used to scan the XML template files to locate all the files + referenced herein. This is used to generate dependency information as used by + make. + +- ``Makefile`` + + The targets 'xmldocs', 'psdocs', 'pdfdocs', and 'htmldocs' are used to build + DocBook XML files, PostScript files, PDF files, and html files in + Documentation/DocBook. The older target 'sgmldocs' is equivalent to 'xmldocs'. + +- ``Documentation/DocBook/Makefile`` + + This is where C files are associated with SGML templates. + +How to use kernel-doc comments in DocBook XML template files +------------------------------------------------------------ + +DocBook XML template files (\*.tmpl) are like normal XML files, except that they +can contain escape sequences where extracted documentation should be inserted. + +``!E<filename>`` is replaced by the documentation, in ``<filename>``, for +functions that are exported using ``EXPORT_SYMBOL``: the function list is +collected from files listed in ``Documentation/DocBook/Makefile``. + +``!I<filename>`` is replaced by the documentation for functions that are **not** +exported using ``EXPORT_SYMBOL``. + +``!D<filename>`` is used to name additional files to search for functions +exported using ``EXPORT_SYMBOL``. + +``!F<filename> <function [functions...]>`` is replaced by the documentation, in +``<filename>``, for the functions listed. + +``!P<filename> <section title>`` is replaced by the contents of the ``DOC:`` +section titled ``<section title>`` from ``<filename>``. Spaces are allowed in +``<section title>``; do not quote the ``<section title>``. + +``!C<filename>`` is replaced by nothing, but makes the tools check that all DOC: +sections and documented functions, symbols, etc. are used. This makes sense to +use when you use ``!F`` or ``!P`` only and want to verify that all documentation +is included. diff --git a/Documentation/kernel-parameters.txt b/Documentation/kernel-parameters.txt index 82b42c958d1c..769db8399ac8 100644 --- a/Documentation/kernel-parameters.txt +++ b/Documentation/kernel-parameters.txt @@ -582,6 +582,9 @@ bytes respectively. Such letter suffixes can also be entirely omitted. bootmem_debug [KNL] Enable bootmem allocator debug messages. + bert_disable [ACPI] + Disable BERT OS support on buggy BIOSes. + bttv.card= [HW,V4L] bttv (bt848 + bt878 based grabber cards) bttv.radio= Most important insmod options are available as kernel args too. @@ -687,6 +690,14 @@ bytes respectively. Such letter suffixes can also be entirely omitted. [SPARC64] tick [X86-64] hpet,tsc + clocksource.arm_arch_timer.evtstrm= + [ARM,ARM64] + Format: <bool> + Enable/disable the eventstream feature of the ARM + architected timer so that code using WFE-based polling + loops can be debugged more effectively on production + systems. + clearcpuid=BITNUM [X86] Disable CPUID feature X for the kernel. See arch/x86/include/asm/cpufeatures.h for the valid bit @@ -1185,6 +1196,13 @@ bytes respectively. Such letter suffixes can also be entirely omitted. Address Range Mirroring feature even if your box doesn't support it. + efivar_ssdt= [EFI; X86] Name of an EFI variable that contains an SSDT + that is to be dynamically loaded by Linux. If there are + multiple variables with the same name but with different + vendor GUIDs, all of them will be loaded. See + Documentation/acpi/ssdt-overlays.txt for details. + + eisa_irq_edge= [PARISC,HW] See header of drivers/parisc/eisa.c. @@ -1803,12 +1821,10 @@ bytes respectively. Such letter suffixes can also be entirely omitted. js= [HW,JOY] Analog joystick See Documentation/input/joystick.txt. - kaslr/nokaslr [X86] - Enable/disable kernel and module base offset ASLR - (Address Space Layout Randomization) if built into - the kernel. When CONFIG_HIBERNATION is selected, - kASLR is disabled by default. When kASLR is enabled, - hibernation will be disabled. + nokaslr [KNL] + When CONFIG_RANDOMIZE_BASE is set, this disables + kernel and module base offset ASLR (Address Space + Layout Randomization). keepinitrd [HW,ARM] @@ -2788,8 +2804,6 @@ bytes respectively. Such letter suffixes can also be entirely omitted. timer: [X86] Force use of architectural NMI timer mode (see also oprofile.timer for generic hr timer mode) - [s390] Force legacy basic mode sampling - (report cpu_type "timer") oops=panic Always panic on oopses. Default is to just kill the process, but there is a small probability of @@ -3594,6 +3608,9 @@ bytes respectively. Such letter suffixes can also be entirely omitted. present during boot. nocompress Don't compress/decompress hibernation images. no Disable hibernation and resume. + protect_image Turn on image protection during restoration + (that will set all pages holding image data + during restoration read-only). retain_initrd [RAM] Keep initrd memory after extraction @@ -3992,8 +4009,9 @@ bytes respectively. Such letter suffixes can also be entirely omitted. trace_event=[event-list] [FTRACE] Set and start specified trace events in order - to facilitate early boot debugging. - See also Documentation/trace/events.txt + to facilitate early boot debugging. The event-list is a + comma separated list of trace events to enable. See + also Documentation/trace/events.txt trace_options=[option-list] [FTRACE] Enable or disable tracer options at boot. diff --git a/Documentation/leds/leds-class.txt b/Documentation/leds/leds-class.txt index d406d98339b2..44f5e6bccd97 100644 --- a/Documentation/leds/leds-class.txt +++ b/Documentation/leds/leds-class.txt @@ -74,8 +74,8 @@ blink_set() function (see <linux/leds.h>). To set an LED to blinking, however, it is better to use the API function led_blink_set(), as it will check and implement software fallback if necessary. -To turn off blinking again, use the API function led_brightness_set() -as that will not just set the LED brightness but also stop any software +To turn off blinking, use the API function led_brightness_set() +with brightness value LED_OFF, which should stop any software timers that may have been required for blinking. The blink_set() function should choose a user friendly blinking value diff --git a/Documentation/md.txt b/Documentation/md.txt index 1a2ada46aaed..d6e2fcf27337 100644 --- a/Documentation/md.txt +++ b/Documentation/md.txt @@ -602,7 +602,7 @@ These currently include stripe_cache_size (currently raid5 only) number of entries in the stripe cache. This is writable, but - there are upper and lower limits (32768, 16). Default is 128. + there are upper and lower limits (32768, 17). Default is 256. strip_cache_active (currently raid5 only) number of active entries in the stripe cache preread_bypass_threshold (currently raid5 only) diff --git a/Documentation/memory-barriers.txt b/Documentation/memory-barriers.txt index 147ae8ec836f..a4d0a99de04d 100644 --- a/Documentation/memory-barriers.txt +++ b/Documentation/memory-barriers.txt @@ -806,6 +806,41 @@ out-guess your code. More generally, although READ_ONCE() does force the compiler to actually emit code for a given load, it does not force the compiler to use the results. +In addition, control dependencies apply only to the then-clause and +else-clause of the if-statement in question. In particular, it does +not necessarily apply to code following the if-statement: + + q = READ_ONCE(a); + if (q) { + WRITE_ONCE(b, p); + } else { + WRITE_ONCE(b, r); + } + WRITE_ONCE(c, 1); /* BUG: No ordering against the read from "a". */ + +It is tempting to argue that there in fact is ordering because the +compiler cannot reorder volatile accesses and also cannot reorder +the writes to "b" with the condition. Unfortunately for this line +of reasoning, the compiler might compile the two writes to "b" as +conditional-move instructions, as in this fanciful pseudo-assembly +language: + + ld r1,a + ld r2,p + ld r3,r + cmp r1,$0 + cmov,ne r4,r2 + cmov,eq r4,r3 + st r4,b + st $1,c + +A weakly ordered CPU would have no dependency of any sort between the load +from "a" and the store to "c". The control dependencies would extend +only to the pair of cmov instructions and the store depending on them. +In short, control dependencies apply only to the stores in the then-clause +and else-clause of the if-statement in question (including functions +invoked by those two clauses), not to code following that if-statement. + 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: @@ -869,6 +904,12 @@ In summary: atomic{,64}_read() can help to preserve your control dependency. Please see the COMPILER BARRIER section for more information. + (*) Control dependencies apply only to the then-clause and else-clause + of the if-statement containing the control dependency, including + any functions that these two clauses call. Control dependencies + do -not- apply to code following the if-statement containing the + control dependency. + (*) Control dependencies pair normally with other types of barriers. (*) Control dependencies do -not- provide transitivity. If you diff --git a/Documentation/mic/mpssd/mpssd.c b/Documentation/mic/mpssd/mpssd.c index 30fb842a976d..49db1def1721 100644 --- a/Documentation/mic/mpssd/mpssd.c +++ b/Documentation/mic/mpssd/mpssd.c @@ -1538,9 +1538,9 @@ set_cmdline(struct mic_info *mic) len = snprintf(buffer, PATH_MAX, "clocksource=tsc highres=off nohz=off "); - len += snprintf(buffer + len, PATH_MAX, + len += snprintf(buffer + len, PATH_MAX - len, "cpufreq_on;corec6_off;pc3_off;pc6_off "); - len += snprintf(buffer + len, PATH_MAX, + len += snprintf(buffer + len, PATH_MAX - len, "ifcfg=static;address,172.31.%d.1;netmask,255.255.255.0", mic->id + 1); diff --git a/Documentation/ramoops.txt b/Documentation/ramoops.txt index 5d8675615e59..9264bcab4099 100644 --- a/Documentation/ramoops.txt +++ b/Documentation/ramoops.txt @@ -45,7 +45,7 @@ corrupt, but usually it is restorable. 2. Setting the parameters -Setting the ramoops parameters can be done in 2 different manners: +Setting the ramoops parameters can be done in 3 different manners: 1. Use the module parameters (which have the names of the variables described as before). For quick debugging, you can also reserve parts of memory during boot @@ -54,7 +54,9 @@ Setting the ramoops parameters can be done in 2 different manners: kernel to use only the first 128 MB of memory, and place ECC-protected ramoops region at 128 MB boundary: "mem=128M ramoops.mem_address=0x8000000 ramoops.ecc=1" - 2. Use a platform device and set the platform data. The parameters can then + 2. Use Device Tree bindings, as described in + Documentation/device-tree/bindings/misc/ramoops.txt. + 3. Use a platform device and set the platform data. The parameters can then be set through that platform data. An example of doing that is: #include <linux/pstore_ram.h> diff --git a/Documentation/s390/s390dbf.txt b/Documentation/s390/s390dbf.txt index 3da163383c93..61329fd62e89 100644 --- a/Documentation/s390/s390dbf.txt +++ b/Documentation/s390/s390dbf.txt @@ -405,7 +405,7 @@ Example: > ls /sys/kernel/debug/s390dbf/dasd flush hex_ascii level pages raw -> cat /sys/kernel/debug/s390dbf/dasd/hex_ascii | sort +1 +> cat /sys/kernel/debug/s390dbf/dasd/hex_ascii | sort -k2,2 -s 00 00974733272:680099 2 - 02 0006ad7e 07 ea 4a 90 | .... 00 00974733272:682210 2 - 02 0006ade6 46 52 45 45 | FREE 00 00974733272:682213 2 - 02 0006adf6 07 ea 4a 90 | .... diff --git a/Documentation/scsi/scsi_eh.txt b/Documentation/scsi/scsi_eh.txt index 8638f61c8c9d..37eca00796ee 100644 --- a/Documentation/scsi/scsi_eh.txt +++ b/Documentation/scsi/scsi_eh.txt @@ -263,19 +263,23 @@ scmd->allowed. 3. scmd recovered ACTION: scsi_eh_finish_cmd() is invoked to EH-finish scmd - - shost->host_failed-- - clear scmd->eh_eflags - scsi_setup_cmd_retry() - move from local eh_work_q to local eh_done_q LOCKING: none + CONCURRENCY: at most one thread per separate eh_work_q to + keep queue manipulation lockless 4. EH completes ACTION: scsi_eh_flush_done_q() retries scmds or notifies upper - layer of failure. + layer of failure. May be called concurrently but must have + a no more than one thread per separate eh_work_q to + manipulate the queue locklessly - scmd is removed from eh_done_q and scmd->eh_entry is cleared - if retry is necessary, scmd is requeued using scsi_queue_insert() - otherwise, scsi_finish_command() is invoked for scmd + - zero shost->host_failed LOCKING: queue or finish function performs appropriate locking diff --git a/Documentation/security/self-protection.txt b/Documentation/security/self-protection.txt index babd6378ec05..3010576c9fca 100644 --- a/Documentation/security/self-protection.txt +++ b/Documentation/security/self-protection.txt @@ -183,8 +183,9 @@ provide meaningful defenses. ### Canaries, blinding, and other secrets It should be noted that things like the stack canary discussed earlier -are technically statistical defenses, since they rely on a (leakable) -secret value. +are technically statistical defenses, since they rely on a secret value, +and such values may become discoverable through an information exposure +flaw. Blinding literal values for things like JITs, where the executable contents may be partially under the control of userspace, need a similar @@ -199,8 +200,8 @@ working?) in order to maximize their success. Since the location of kernel memory is almost always instrumental in mounting a successful attack, making the location non-deterministic raises the difficulty of an exploit. (Note that this in turn makes -the value of leaks higher, since they may be used to discover desired -memory locations.) +the value of information exposures higher, since they may be used to +discover desired memory locations.) #### Text and module base @@ -222,14 +223,21 @@ become more difficult to locate. Much of the kernel's dynamic memory (e.g. kmalloc, vmalloc, etc) ends up being relatively deterministic in layout due to the order of early-boot initializations. If the base address of these areas is not the same -between boots, targeting them is frustrated, requiring a leak specific -to the region. +between boots, targeting them is frustrated, requiring an information +exposure specific to the region. + +#### Structure layout + +By performing a per-build randomization of the layout of sensitive +structures, attacks must either be tuned to known kernel builds or expose +enough kernel memory to determine structure layouts before manipulating +them. -## Preventing Leaks +## Preventing Information Exposures Since the locations of sensitive structures are the primary target for -attacks, it is important to defend against leaks of both kernel memory +attacks, it is important to defend against exposure of both kernel memory addresses and kernel memory contents (since they may contain kernel addresses or other sensitive things like canary values). @@ -250,8 +258,8 @@ sure structure holes are cleared. When releasing memory, it is best to poison the contents (clear stack on syscall return, wipe heap memory on a free), to avoid reuse attacks that rely on the old contents of memory. This frustrates many uninitialized -variable attacks, stack info leaks, heap info leaks, and use-after-free -attacks. +variable attacks, stack content exposures, heap content exposures, and +use-after-free attacks. ### Destination tracking diff --git a/Documentation/sphinx/convert_template.sed b/Documentation/sphinx/convert_template.sed new file mode 100644 index 000000000000..c1503fcca4ec --- /dev/null +++ b/Documentation/sphinx/convert_template.sed @@ -0,0 +1,18 @@ +# +# Pandoc doesn't grok <function> or <structname>, so convert them +# ahead of time. +# +# Use the following escapes to pass through pandoc: +# $bq = "`" +# $lt = "<" +# $gt = ">" +# +s%<function>\([^<(]\+\)()</function>%:c:func:$bq\1()$bq%g +s%<function>\([^<(]\+\)</function>%:c:func:$bq\1()$bq%g +s%<structname>struct *\([^<]\+\)</structname>%:c:type:$bqstruct \1 $lt\1$gt$bq%g +s%struct <structname>\([^<]\+\)</structname>%:c:type:$bqstruct \1 $lt\1$gt$bq%g +s%<structname>\([^<]\+\)</structname>%:c:type:$bqstruct \1 $lt\1$gt$bq%g +# +# Wrap docproc directives in para and code blocks. +# +s%^\(!.*\)$%<para><code>DOCPROC: \1</code></para>% diff --git a/Documentation/sphinx/kernel-doc.py b/Documentation/sphinx/kernel-doc.py new file mode 100644 index 000000000000..f6920c0af6ee --- /dev/null +++ b/Documentation/sphinx/kernel-doc.py @@ -0,0 +1,141 @@ +# coding=utf-8 +# +# Copyright © 2016 Intel Corporation +# +# Permission is hereby granted, free of charge, to any person obtaining a +# copy of this software and associated documentation files (the "Software"), +# to deal in the Software without restriction, including without limitation +# the rights to use, copy, modify, merge, publish, distribute, sublicense, +# and/or sell copies of the Software, and to permit persons to whom the +# Software is furnished to do so, subject to the following conditions: +# +# The above copyright notice and this permission notice (including the next +# paragraph) shall be included in all copies or substantial portions of the +# Software. +# +# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL +# THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING +# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS +# IN THE SOFTWARE. +# +# Authors: +# Jani Nikula <jani.nikula@intel.com> +# +# Please make sure this works on both python2 and python3. +# + +import os +import subprocess +import sys +import re +import glob + +from docutils import nodes, statemachine +from docutils.statemachine import ViewList +from docutils.parsers.rst import directives +from sphinx.util.compat import Directive +from sphinx.ext.autodoc import AutodocReporter + +class KernelDocDirective(Directive): + """Extract kernel-doc comments from the specified file""" + required_argument = 1 + optional_arguments = 4 + option_spec = { + 'doc': directives.unchanged_required, + 'functions': directives.unchanged_required, + 'export': directives.unchanged, + 'internal': directives.unchanged, + } + has_content = False + + def run(self): + env = self.state.document.settings.env + cmd = [env.config.kerneldoc_bin, '-rst', '-enable-lineno'] + + filename = env.config.kerneldoc_srctree + '/' + self.arguments[0] + export_file_patterns = [] + + # Tell sphinx of the dependency + env.note_dependency(os.path.abspath(filename)) + + tab_width = self.options.get('tab-width', self.state.document.settings.tab_width) + + # FIXME: make this nicer and more robust against errors + if 'export' in self.options: + cmd += ['-export'] + export_file_patterns = str(self.options.get('export')).split() + elif 'internal' in self.options: + cmd += ['-internal'] + export_file_patterns = str(self.options.get('internal')).split() + elif 'doc' in self.options: + cmd += ['-function', str(self.options.get('doc'))] + elif 'functions' in self.options: + for f in str(self.options.get('functions')).split(): + cmd += ['-function', f] + + for pattern in export_file_patterns: + for f in glob.glob(env.config.kerneldoc_srctree + '/' + pattern): + env.note_dependency(os.path.abspath(f)) + cmd += ['-export-file', f] + + cmd += [filename] + + try: + env.app.verbose('calling kernel-doc \'%s\'' % (" ".join(cmd))) + + p = subprocess.Popen(cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE, universal_newlines=True) + out, err = p.communicate() + + # python2 needs conversion to unicode. + # python3 with universal_newlines=True returns strings. + if sys.version_info.major < 3: + out, err = unicode(out, 'utf-8'), unicode(err, 'utf-8') + + if p.returncode != 0: + sys.stderr.write(err) + + env.app.warn('kernel-doc \'%s\' failed with return code %d' % (" ".join(cmd), p.returncode)) + return [nodes.error(None, nodes.paragraph(text = "kernel-doc missing"))] + elif env.config.kerneldoc_verbosity > 0: + sys.stderr.write(err) + + lines = statemachine.string2lines(out, tab_width, convert_whitespace=True) + result = ViewList() + + lineoffset = 0; + line_regex = re.compile("^#define LINENO ([0-9]+)$") + for line in lines: + match = line_regex.search(line) + if match: + # sphinx counts lines from 0 + lineoffset = int(match.group(1)) - 1 + # we must eat our comments since the upset the markup + else: + result.append(line, filename, lineoffset) + lineoffset += 1 + + node = nodes.section() + buf = self.state.memo.title_styles, self.state.memo.section_level, self.state.memo.reporter + self.state.memo.reporter = AutodocReporter(result, self.state.memo.reporter) + self.state.memo.title_styles, self.state.memo.section_level = [], 0 + try: + self.state.nested_parse(result, 0, node, match_titles=1) + finally: + self.state.memo.title_styles, self.state.memo.section_level, self.state.memo.reporter = buf + + return node.children + + except Exception as e: # pylint: disable=W0703 + env.app.warn('kernel-doc \'%s\' processing failed with: %s' % + (" ".join(cmd), str(e))) + return [nodes.error(None, nodes.paragraph(text = "kernel-doc missing"))] + +def setup(app): + app.add_config_value('kerneldoc_bin', None, 'env') + app.add_config_value('kerneldoc_srctree', None, 'env') + app.add_config_value('kerneldoc_verbosity', 1, 'env') + + app.add_directive('kernel-doc', KernelDocDirective) diff --git a/Documentation/sphinx/post_convert.sed b/Documentation/sphinx/post_convert.sed new file mode 100644 index 000000000000..392770bac53b --- /dev/null +++ b/Documentation/sphinx/post_convert.sed @@ -0,0 +1,23 @@ +# +# Unescape. +# +s/$bq/`/g +s/$lt/</g +s/$gt/>/g +# +# pandoc thinks that both "_" needs to be escaped. Remove the extra +# backslashes. +# +s/\\_/_/g +# +# Unwrap docproc directives. +# +s/^``DOCPROC: !E\(.*\)``$/.. kernel-doc:: \1\n :export:/ +s/^``DOCPROC: !I\(.*\)``$/.. kernel-doc:: \1\n :internal:/ +s/^``DOCPROC: !F\([^ ]*\) \(.*\)``$/.. kernel-doc:: \1\n :functions: \2/ +s/^``DOCPROC: !P\([^ ]*\) \(.*\)``$/.. kernel-doc:: \1\n :doc: \2/ +s/^``DOCPROC: \(!.*\)``$/.. WARNING: DOCPROC directive not supported: \1/ +# +# Trim trailing whitespace. +# +s/[[:space:]]*$// diff --git a/Documentation/sphinx/rstFlatTable.py b/Documentation/sphinx/rstFlatTable.py new file mode 100644 index 000000000000..26db852e3c74 --- /dev/null +++ b/Documentation/sphinx/rstFlatTable.py @@ -0,0 +1,365 @@ +#!/usr/bin/env python3 +# -*- coding: utf-8; mode: python -*- +# pylint: disable=C0330, R0903, R0912 + +u""" + flat-table + ~~~~~~~~~~ + + Implementation of the ``flat-table`` reST-directive. + + :copyright: Copyright (C) 2016 Markus Heiser + :license: GPL Version 2, June 1991 see linux/COPYING for details. + + The ``flat-table`` (:py:class:`FlatTable`) is a double-stage list similar to + the ``list-table`` with some additional features: + + * *column-span*: with the role ``cspan`` a cell can be extended through + additional columns + + * *row-span*: with the role ``rspan`` a cell can be extended through + additional rows + + * *auto span* rightmost cell of a table row over the missing cells on the + right side of that table-row. With Option ``:fill-cells:`` this behavior + can changed from *auto span* to *auto fill*, which automaticly inserts + (empty) cells instead of spanning the last cell. + + Options: + + * header-rows: [int] count of header rows + * stub-columns: [int] count of stub columns + * widths: [[int] [int] ... ] widths of columns + * fill-cells: instead of autospann missing cells, insert missing cells + + roles: + + * cspan: [int] additionale columns (*morecols*) + * rspan: [int] additionale rows (*morerows*) +""" + +# ============================================================================== +# imports +# ============================================================================== + +import sys + +from docutils import nodes +from docutils.parsers.rst import directives, roles +from docutils.parsers.rst.directives.tables import Table +from docutils.utils import SystemMessagePropagation + +# ============================================================================== +# common globals +# ============================================================================== + +# The version numbering follows numbering of the specification +# (Documentation/books/kernel-doc-HOWTO). +__version__ = '1.0' + +PY3 = sys.version_info[0] == 3 +PY2 = sys.version_info[0] == 2 + +if PY3: + # pylint: disable=C0103, W0622 + unicode = str + basestring = str + +# ============================================================================== +def setup(app): +# ============================================================================== + + app.add_directive("flat-table", FlatTable) + roles.register_local_role('cspan', c_span) + roles.register_local_role('rspan', r_span) + +# ============================================================================== +def c_span(name, rawtext, text, lineno, inliner, options=None, content=None): +# ============================================================================== + # pylint: disable=W0613 + + options = options if options is not None else {} + content = content if content is not None else [] + nodelist = [colSpan(span=int(text))] + msglist = [] + return nodelist, msglist + +# ============================================================================== +def r_span(name, rawtext, text, lineno, inliner, options=None, content=None): +# ============================================================================== + # pylint: disable=W0613 + + options = options if options is not None else {} + content = content if content is not None else [] + nodelist = [rowSpan(span=int(text))] + msglist = [] + return nodelist, msglist + + +# ============================================================================== +class rowSpan(nodes.General, nodes.Element): pass # pylint: disable=C0103,C0321 +class colSpan(nodes.General, nodes.Element): pass # pylint: disable=C0103,C0321 +# ============================================================================== + +# ============================================================================== +class FlatTable(Table): +# ============================================================================== + + u"""FlatTable (``flat-table``) directive""" + + option_spec = { + 'name': directives.unchanged + , 'class': directives.class_option + , 'header-rows': directives.nonnegative_int + , 'stub-columns': directives.nonnegative_int + , 'widths': directives.positive_int_list + , 'fill-cells' : directives.flag } + + def run(self): + + if not self.content: + error = self.state_machine.reporter.error( + 'The "%s" directive is empty; content required.' % self.name, + nodes.literal_block(self.block_text, self.block_text), + line=self.lineno) + return [error] + + title, messages = self.make_title() + node = nodes.Element() # anonymous container for parsing + self.state.nested_parse(self.content, self.content_offset, node) + + tableBuilder = ListTableBuilder(self) + tableBuilder.parseFlatTableNode(node) + tableNode = tableBuilder.buildTableNode() + # SDK.CONSOLE() # print --> tableNode.asdom().toprettyxml() + if title: + tableNode.insert(0, title) + return [tableNode] + messages + + +# ============================================================================== +class ListTableBuilder(object): +# ============================================================================== + + u"""Builds a table from a double-stage list""" + + def __init__(self, directive): + self.directive = directive + self.rows = [] + self.max_cols = 0 + + def buildTableNode(self): + + colwidths = self.directive.get_column_widths(self.max_cols) + stub_columns = self.directive.options.get('stub-columns', 0) + header_rows = self.directive.options.get('header-rows', 0) + + table = nodes.table() + tgroup = nodes.tgroup(cols=len(colwidths)) + table += tgroup + + + for colwidth in colwidths: + colspec = nodes.colspec(colwidth=colwidth) + # FIXME: It seems, that the stub method only works well in the + # absence of rowspan (observed by the html buidler, the docutils-xml + # build seems OK). This is not extraordinary, because there exists + # no table directive (except *this* flat-table) which allows to + # define coexistent of rowspan and stubs (there was no use-case + # before flat-table). This should be reviewed (later). + if stub_columns: + colspec.attributes['stub'] = 1 + stub_columns -= 1 + tgroup += colspec + stub_columns = self.directive.options.get('stub-columns', 0) + + if header_rows: + thead = nodes.thead() + tgroup += thead + for row in self.rows[:header_rows]: + thead += self.buildTableRowNode(row) + + tbody = nodes.tbody() + tgroup += tbody + + for row in self.rows[header_rows:]: + tbody += self.buildTableRowNode(row) + return table + + def buildTableRowNode(self, row_data, classes=None): + classes = [] if classes is None else classes + row = nodes.row() + for cell in row_data: + if cell is None: + continue + cspan, rspan, cellElements = cell + + attributes = {"classes" : classes} + if rspan: + attributes['morerows'] = rspan + if cspan: + attributes['morecols'] = cspan + entry = nodes.entry(**attributes) + entry.extend(cellElements) + row += entry + return row + + def raiseError(self, msg): + error = self.directive.state_machine.reporter.error( + msg + , nodes.literal_block(self.directive.block_text + , self.directive.block_text) + , line = self.directive.lineno ) + raise SystemMessagePropagation(error) + + def parseFlatTableNode(self, node): + u"""parses the node from a :py:class:`FlatTable` directive's body""" + + if len(node) != 1 or not isinstance(node[0], nodes.bullet_list): + self.raiseError( + 'Error parsing content block for the "%s" directive: ' + 'exactly one bullet list expected.' % self.directive.name ) + + for rowNum, rowItem in enumerate(node[0]): + row = self.parseRowItem(rowItem, rowNum) + self.rows.append(row) + self.roundOffTableDefinition() + + def roundOffTableDefinition(self): + u"""Round off the table definition. + + This method rounds off the table definition in :py:member:`rows`. + + * This method inserts the needed ``None`` values for the missing cells + arising from spanning cells over rows and/or columns. + + * recount the :py:member:`max_cols` + + * Autospan or fill (option ``fill-cells``) missing cells on the right + side of the table-row + """ + + y = 0 + while y < len(self.rows): + x = 0 + + while x < len(self.rows[y]): + cell = self.rows[y][x] + if cell is None: + x += 1 + continue + cspan, rspan = cell[:2] + # handle colspan in current row + for c in range(cspan): + try: + self.rows[y].insert(x+c+1, None) + except: # pylint: disable=W0702 + # the user sets ambiguous rowspans + pass # SDK.CONSOLE() + # handle colspan in spanned rows + for r in range(rspan): + for c in range(cspan + 1): + try: + self.rows[y+r+1].insert(x+c, None) + except: # pylint: disable=W0702 + # the user sets ambiguous rowspans + pass # SDK.CONSOLE() + x += 1 + y += 1 + + # Insert the missing cells on the right side. For this, first + # re-calculate the max columns. + + for row in self.rows: + if self.max_cols < len(row): + self.max_cols = len(row) + + # fill with empty cells or cellspan? + + fill_cells = False + if 'fill-cells' in self.directive.options: + fill_cells = True + + for row in self.rows: + x = self.max_cols - len(row) + if x and not fill_cells: + if row[-1] is None: + row.append( ( x - 1, 0, []) ) + else: + cspan, rspan, content = row[-1] + row[-1] = (cspan + x, rspan, content) + elif x and fill_cells: + for i in range(x): + row.append( (0, 0, nodes.comment()) ) + + def pprint(self): + # for debugging + retVal = "[ " + for row in self.rows: + retVal += "[ " + for col in row: + if col is None: + retVal += ('%r' % col) + retVal += "\n , " + else: + content = col[2][0].astext() + if len (content) > 30: + content = content[:30] + "..." + retVal += ('(cspan=%s, rspan=%s, %r)' + % (col[0], col[1], content)) + retVal += "]\n , " + retVal = retVal[:-2] + retVal += "]\n , " + retVal = retVal[:-2] + return retVal + "]" + + def parseRowItem(self, rowItem, rowNum): + row = [] + childNo = 0 + error = False + cell = None + target = None + + for child in rowItem: + if (isinstance(child , nodes.comment) + or isinstance(child, nodes.system_message)): + pass + elif isinstance(child , nodes.target): + target = child + elif isinstance(child, nodes.bullet_list): + childNo += 1 + cell = child + else: + error = True + break + + if childNo != 1 or error: + self.raiseError( + 'Error parsing content block for the "%s" directive: ' + 'two-level bullet list expected, but row %s does not ' + 'contain a second-level bullet list.' + % (self.directive.name, rowNum + 1)) + + for cellItem in cell: + cspan, rspan, cellElements = self.parseCellItem(cellItem) + if target is not None: + cellElements.insert(0, target) + row.append( (cspan, rspan, cellElements) ) + return row + + def parseCellItem(self, cellItem): + # search and remove cspan, rspan colspec from the first element in + # this listItem (field). + cspan = rspan = 0 + if not len(cellItem): + return cspan, rspan, [] + for elem in cellItem[0]: + if isinstance(elem, colSpan): + cspan = elem.get("span") + elem.parent.remove(elem) + continue + if isinstance(elem, rowSpan): + rspan = elem.get("span") + elem.parent.remove(elem) + continue + return cspan, rspan, cellItem[:] diff --git a/Documentation/sphinx/tmplcvt b/Documentation/sphinx/tmplcvt new file mode 100755 index 000000000000..909a73065e0a --- /dev/null +++ b/Documentation/sphinx/tmplcvt @@ -0,0 +1,19 @@ +#!/bin/bash +# +# Convert a template file into something like RST +# +# fix <function> +# feed to pandoc +# fix \_ +# title line? +# + +in=$1 +rst=$2 +tmp=$rst.tmp + +cp $in $tmp +sed --in-place -f convert_template.sed $tmp +pandoc -s -S -f docbook -t rst -o $rst $tmp +sed --in-place -f post_convert.sed $rst +rm $tmp diff --git a/Documentation/sync_file.txt b/Documentation/sync_file.txt index eaf8297dbca2..e8e2ebafe5fa 100644 --- a/Documentation/sync_file.txt +++ b/Documentation/sync_file.txt @@ -6,8 +6,8 @@ This document serves as a guide for device drivers writers on what the sync_file API is, and how drivers can support it. Sync file is the carrier of -the fences(struct fence) that needs to synchronized between drivers or across -process boundaries. +the fences(struct fence) that are needed to synchronize between drivers or +across process boundaries. The sync_file API is meant to be used to send and receive fence information to/from userspace. It enables userspace to do explicit fencing, where instead @@ -32,7 +32,7 @@ in-fences and out-fences Sync files can go either to or from userspace. When a sync_file is sent from the driver to userspace we call the fences it contains 'out-fences'. They are related to a buffer that the driver is processing or is going to process, so -the driver an create out-fence to be able to notify, through fence_signal(), +the driver creates an out-fence to be able to notify, through fence_signal(), when it has finished using (or processing) that buffer. Out-fences are fences that the driver creates. diff --git a/Documentation/sysctl/kernel.txt b/Documentation/sysctl/kernel.txt index a3683ce2a2f3..33204604de6c 100644 --- a/Documentation/sysctl/kernel.txt +++ b/Documentation/sysctl/kernel.txt @@ -58,6 +58,7 @@ show up in /proc/sys/kernel: - panic_on_stackoverflow - panic_on_unrecovered_nmi - panic_on_warn +- panic_on_rcu_stall - perf_cpu_time_max_percent - perf_event_paranoid - perf_event_max_stack @@ -618,6 +619,17 @@ a kernel rebuild when attempting to kdump at the location of a WARN(). ============================================================== +panic_on_rcu_stall: + +When set to 1, calls panic() after RCU stall detection messages. This +is useful to define the root cause of RCU stalls using a vmcore. + +0: do not panic() when RCU stall takes place, default behavior. + +1: panic() after printing RCU stall messages. + +============================================================== + perf_cpu_time_max_percent: Hints to the kernel how much CPU time it should be allowed to diff --git a/Documentation/sysctl/vm.txt b/Documentation/sysctl/vm.txt index 720355cbdf45..95ccbe6d79ce 100644 --- a/Documentation/sysctl/vm.txt +++ b/Documentation/sysctl/vm.txt @@ -61,6 +61,7 @@ Currently, these files are in /proc/sys/vm: - swappiness - user_reserve_kbytes - vfs_cache_pressure +- watermark_scale_factor - zone_reclaim_mode ============================================================== diff --git a/Documentation/thermal/intel_powerclamp.txt b/Documentation/thermal/intel_powerclamp.txt index 332de4a39b5a..60073dc9f748 100644 --- a/Documentation/thermal/intel_powerclamp.txt +++ b/Documentation/thermal/intel_powerclamp.txt @@ -121,7 +121,7 @@ time is considered largely as a non-causal system where its behavior cannot be based on the past or current input. Therefore, the intel_powerclamp driver attempts to enforce the desired idle time instantly as given input (target idle ratio). After injection, -powerclamp moniors the actual idle for a given time window and adjust +powerclamp monitors the actual idle for a given time window and adjust the next injection accordingly to avoid over/under correction. When used in a causal control system, such as a temperature control, diff --git a/Documentation/usb/gadget_multi.txt b/Documentation/usb/gadget_multi.txt index 5faf514047e9..b3146dd7aa43 100644 --- a/Documentation/usb/gadget_multi.txt +++ b/Documentation/usb/gadget_multi.txt @@ -36,7 +36,7 @@ configuration with CDC ECM which should work better under Linux. ** Windows host drivers -For the gadget two work under Windows two conditions have to be met: +For the gadget to work under Windows two conditions have to be met: *** Detecting as composite gadget diff --git a/Documentation/video4linux/CARDLIST.cx23885 b/Documentation/video4linux/CARDLIST.cx23885 index 85a8fdcfcdaa..c9b4959fd04e 100644 --- a/Documentation/video4linux/CARDLIST.cx23885 +++ b/Documentation/video4linux/CARDLIST.cx23885 @@ -54,3 +54,4 @@ 53 -> Hauppauge WinTV Starburst [0070:c12a] 54 -> ViewCast 260e [1576:0260] 55 -> ViewCast 460e [1576:0460] + 56 -> Hauppauge WinTV-quadHD (DVB) [0070:6a28,0070:6b28] diff --git a/Documentation/video4linux/v4l2-controls.txt b/Documentation/video4linux/v4l2-controls.txt index 5e759cab4538..f930b80e9111 100644 --- a/Documentation/video4linux/v4l2-controls.txt +++ b/Documentation/video4linux/v4l2-controls.txt @@ -96,21 +96,6 @@ Basic usage for V4L2 and sub-device drivers Where foo->sd is of type struct v4l2_subdev. - And set all core control ops in your struct v4l2_subdev_core_ops to these - helpers: - - .queryctrl = v4l2_subdev_queryctrl, - .querymenu = v4l2_subdev_querymenu, - .g_ctrl = v4l2_subdev_g_ctrl, - .s_ctrl = v4l2_subdev_s_ctrl, - .g_ext_ctrls = v4l2_subdev_g_ext_ctrls, - .try_ext_ctrls = v4l2_subdev_try_ext_ctrls, - .s_ext_ctrls = v4l2_subdev_s_ext_ctrls, - - Note: this is a temporary solution only. Once all V4L2 drivers that depend - on subdev drivers are converted to the control framework these helpers will - no longer be needed. - 1.4) Clean up the handler at the end: v4l2_ctrl_handler_free(&foo->ctrl_handler); diff --git a/Documentation/video4linux/vivid.txt b/Documentation/video4linux/vivid.txt index 8da5d2a576bc..1b26519c6ddc 100644 --- a/Documentation/video4linux/vivid.txt +++ b/Documentation/video4linux/vivid.txt @@ -74,7 +74,8 @@ Section 11: Cropping, Composing, Scaling Section 12: Formats Section 13: Capture Overlay Section 14: Output Overlay -Section 15: Some Future Improvements +Section 15: CEC (Consumer Electronics Control) +Section 16: Some Future Improvements Section 1: Configuring the driver @@ -364,7 +365,11 @@ For HDMI inputs it is possible to set the EDID. By default a simple EDID is provided. You can only set the EDID for HDMI inputs. Internally, however, the EDID is shared between all HDMI inputs. -No interpretation is done of the EDID data. +No interpretation is done of the EDID data with the exception of the +physical address. See the CEC section for more details. + +There is a maximum of 15 HDMI inputs (if there are more, then they will be +reduced to 15) since that's the limitation of the EDID physical address. Section 3: Video Output @@ -409,6 +414,9 @@ standard, and for all others a 1:1 pixel aspect ratio is returned. An HDMI output has a valid EDID which can be obtained through VIDIOC_G_EDID. +There is a maximum of 15 HDMI outputs (if there are more, then they will be +reduced to 15) since that's the limitation of the EDID physical address. See +also the CEC section for more details. Section 4: VBI Capture ---------------------- @@ -1108,7 +1116,26 @@ capabilities will slow down the video loop considerably as a lot of checks have to be done per pixel. -Section 15: Some Future Improvements +Section 15: CEC (Consumer Electronics Control) +---------------------------------------------- + +If there are HDMI inputs then a CEC adapter will be created that has +the same number of input ports. This is the equivalent of e.g. a TV that +has that number of inputs. Each HDMI output will also create a +CEC adapter that is hooked up to the corresponding input port, or (if there +are more outputs than inputs) is not hooked up at all. In other words, +this is the equivalent of hooking up each output device to an input port of +the TV. Any remaining output devices remain unconnected. + +The EDID that each output reads reports a unique CEC physical address that is +based on the physical address of the EDID of the input. So if the EDID of the +receiver has physical address A.B.0.0, then each output will see an EDID +containing physical address A.B.C.0 where C is 1 to the number of inputs. If +there are more outputs than inputs then the remaining outputs have a CEC adapter +that is disabled and reports an invalid physical address. + + +Section 16: Some Future Improvements ------------------------------------ Just as a reminder and in no particular order: @@ -1121,8 +1148,6 @@ Just as a reminder and in no particular order: - Fix sequence/field numbering when looping of video with alternate fields - Add support for V4L2_CID_BG_COLOR for video outputs - Add ARGB888 overlay support: better testing of the alpha channel -- Add custom DV timings support -- Add support for V4L2_DV_FL_REDUCED_FPS - Improve pixel aspect support in the tpg code by passing a real v4l2_fract - Use per-queue locks and/or per-device locks to improve throughput - Add support to loop from a specific output to a specific input across @@ -1133,3 +1158,4 @@ Just as a reminder and in no particular order: - Make a thread for the RDS generation, that would help in particular for the "Controls" RDS Rx I/O Mode as the read-only RDS controls could be updated in real-time. +- Changing the EDID should cause hotplug detect emulation to happen. diff --git a/Documentation/workqueue.txt b/Documentation/workqueue.txt index 5e0e05c5183e..c49e3178178d 100644 --- a/Documentation/workqueue.txt +++ b/Documentation/workqueue.txt @@ -169,7 +169,7 @@ resources, scheduled and executed. WQ_UNBOUND Work items queued to an unbound wq are served by the special - woker-pools which host workers which are not bound to any + worker-pools which host workers which are not bound to any specific CPU. This makes the wq behave as a simple execution context provider without concurrency management. The unbound worker-pools try to start execution of work items as soon as diff --git a/Documentation/x86/intel_mpx.txt b/Documentation/x86/intel_mpx.txt index 1a5a12184a35..85d0549ad846 100644 --- a/Documentation/x86/intel_mpx.txt +++ b/Documentation/x86/intel_mpx.txt @@ -45,7 +45,7 @@ is how we expect the compiler, application and kernel to work together. 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 + expected to keep the bounds directory at that location. We 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 @@ -167,7 +167,7 @@ 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: +The _sigfault field of struct siginfo is extended as follow: 87 /* SIGILL, SIGFPE, SIGSEGV, SIGBUS */ 88 struct { @@ -240,5 +240,5 @@ 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 +However, if users did this, the kernel might be fooled in to unmapping an in-use bounds table since it does not recognize sharing. diff --git a/Documentation/x86/tlb.txt b/Documentation/x86/tlb.txt index 39d172326703..6a0607b99ed8 100644 --- a/Documentation/x86/tlb.txt +++ b/Documentation/x86/tlb.txt @@ -5,7 +5,7 @@ memory, it has two choices: from areas other than the one we are trying to flush will be destroyed and must be refilled later, at some cost. 2. Use the invlpg instruction to invalidate a single page at a - time. This could potentialy cost many more instructions, but + time. This could potentially cost many more instructions, but it is a much more precise operation, causing no collateral damage to other TLB entries. @@ -19,7 +19,7 @@ Which method to do depends on a few things: work. 3. The size of the TLB. The larger the TLB, the more collateral damage we do with a full flush. So, the larger the TLB, the - more attrative an individual flush looks. Data and + more attractive an individual flush looks. Data and instructions have separate TLBs, as do different page sizes. 4. The microarchitecture. The TLB has become a multi-level cache on modern CPUs, and the global flushes have become more diff --git a/Documentation/x86/x86_64/machinecheck b/Documentation/x86/x86_64/machinecheck index b1fb30273286..d0648a74fceb 100644 --- a/Documentation/x86/x86_64/machinecheck +++ b/Documentation/x86/x86_64/machinecheck @@ -36,7 +36,7 @@ between all CPUs. check_interval How often to poll for corrected machine check errors, in seconds - (Note output is hexademical). Default 5 minutes. When the poller + (Note output is hexadecimal). Default 5 minutes. When the poller finds MCEs it triggers an exponential speedup (poll more often) on the polling interval. When the poller stops finding MCEs, it triggers an exponential backoff (poll less often) on the polling diff --git a/Documentation/x86/x86_64/mm.txt b/Documentation/x86/x86_64/mm.txt index 5aa738346062..8c7dd5957ae1 100644 --- a/Documentation/x86/x86_64/mm.txt +++ b/Documentation/x86/x86_64/mm.txt @@ -39,4 +39,8 @@ memory window (this size is arbitrary, it can be raised later if needed). The mappings are not part of any other kernel PGD and are only available during EFI runtime calls. +Note that if CONFIG_RANDOMIZE_MEMORY is enabled, the direct mapping of all +physical memory, vmalloc/ioremap space and virtual memory map are randomized. +Their order is preserved but their base will be offset early at boot time. + -Andi Kleen, Jul 2004 diff --git a/Documentation/zh_CN/CodingStyle b/Documentation/zh_CN/CodingStyle index 654afd72eb24..12717791baac 100644 --- a/Documentation/zh_CN/CodingStyle +++ b/Documentation/zh_CN/CodingStyle @@ -24,34 +24,33 @@ Documentation/CodingStyle的中文翻译 Linux内核代码风格 -这是一个简短的文档，描述了linux内核的首选代码风格。代码风格是因人而异的，而且我 -不愿意把我的观点强加给任何人，不过这里所讲述的是我必须要维护的代码所遵守的风格， -并且我也希望绝大多数其他代码也能遵守这个风格。请在写代码时至少考虑一下本文所述的 -风格。 +这是一个简短的文档，描述了 linux 内核的首选代码风格。代码风格是因人而异的，而且我 +不愿意把自己的观点强加给任何人，但这就像我去做任何事情都必须遵循的原则那样，我也 +希望在绝大多数事上保持这种的态度。请（在写代码时）至少考虑一下这里的代码风格。 -首先，我建议你打印一份GNU代码规范，然后不要读它。烧了它，这是一个具有重大象征性 -意义的动作。 +首先，我建议你打印一份 GNU 代码规范，然后不要读。烧了它，这是一个具有重大象征性意义 +的动作。 不管怎样，现在我们开始： - 第一章：缩进 + 第一章：缩进 -制表符是8个字符，所以缩进也是8个字符。有些异端运动试图将缩进变为4（乃至2）个字符 -深，这几乎相当于尝试将圆周率的值定义为3。 +制表符是 8 个字符，所以缩进也是 8 个字符。有些异端运动试图将缩进变为 4（甚至 2！） +个字符深，这几乎相当于尝试将圆周率的值定义为 3。 理由：缩进的全部意义就在于清楚的定义一个控制块起止于何处。尤其是当你盯着你的屏幕 -连续看了20小时之后，你将会发现大一点的缩进会使你更容易分辨缩进。 +连续看了 20 小时之后，你将会发现大一点的缩进会使你更容易分辨缩进。 -现在，有些人会抱怨8个字符的缩进会使代码向右边移动的太远，在80个字符的终端屏幕上 -就很难读这样的代码。这个问题的答案是，如果你需要3级以上的缩进，不管用何种方式你 +现在，有些人会抱怨 8 个字符的缩进会使代码向右边移动的太远，在 80 个字符的终端屏幕上 +就很难读这样的代码。这个问题的答案是，如果你需要 3 级以上的缩进，不管用何种方式你 的代码已经有问题了，应该修正你的程序。 -简而言之，8个字符的缩进可以让代码更容易阅读，还有一个好处是当你的函数嵌套太深的 +简而言之，8 个字符的缩进可以让代码更容易阅读，还有一个好处是当你的函数嵌套太深的 时候可以给你警告。留心这个警告。 -在switch语句中消除多级缩进的首选的方式是让“switch”和从属于它的“case”标签对齐于同 -一列，而不要“两次缩进”“case”标签。比如： +在 switch 语句中消除多级缩进的首选的方式是让 “switch” 和从属于它的 “case” 标签 +对齐于同一列，而不要 “两次缩进” “case” 标签。比如： switch (suffix) { case 'G': @@ -70,7 +69,6 @@ Documentation/CodingStyle的中文翻译 break; } - 不要把多个语句放在一行里，除非你有什么东西要隐藏： if (condition) do_this; @@ -79,7 +77,7 @@ Documentation/CodingStyle的中文翻译 也不要在一行里放多个赋值语句。内核代码风格超级简单。就是避免可能导致别人误读的表 达式。 -除了注释、文档和Kconfig之外，不要使用空格来缩进，前面的例子是例外，是有意为之。 +除了注释、文档和 Kconfig 之外，不要使用空格来缩进，前面的例子是例外，是有意为之。 选用一个好的编辑器，不要在行尾留空格。 @@ -88,27 +86,18 @@ Documentation/CodingStyle的中文翻译 代码风格的意义就在于使用平常使用的工具来维持代码的可读性和可维护性。 -每一行的长度的限制是80列，我们强烈建议您遵守这个惯例。 +每一行的长度的限制是 80 列，我们强烈建议您遵守这个惯例。 -长于80列的语句要打散成有意义的片段。每个片段要明显短于原来的语句，而且放置的位置 -也明显的靠右。同样的规则也适用于有很长参数列表的函数头。长字符串也要打散成较短的 -字符串。唯一的例外是超过80列可以大幅度提高可读性并且不会隐藏信息的情况。 - -void fun(int a, int b, int c) -{ - if (condition) - printk(KERN_WARNING "Warning this is a long printk with " - "3 parameters a: %u b: %u " - "c: %u \n", a, b, c); - else - next_statement; -} +长于 80 列的语句要打散成有意义的片段。除非超过 80 列能显著增加可读性，并且不会隐藏 +信息。子片段要明显短于母片段，并明显靠右。这同样适用于有着很长参数列表的函数头。 +然而，绝对不要打散对用户可见的字符串，例如 printk 信息，因为这将导致无法 grep 这些 +信息。 第三章：大括号和空格的放置 C语言风格中另外一个常见问题是大括号的放置。和缩进大小不同，选择或弃用某种放置策 -略并没有多少技术上的原因，不过首选的方式，就像Kernighan和Ritchie展示给我们的，是 -把起始大括号放在行尾，而把结束大括号放在行首，所以： +略并没有多少技术上的原因，不过首选的方式，就像 Kernighan 和 Ritchie 展示给我们的， +是把起始大括号放在行尾，而把结束大括号放在行首，所以： if (x is true) { we do y @@ -134,12 +123,12 @@ C语言风格中另外一个常见问题是大括号的放置。和缩进大小 body of function } -全世界的异端可能会抱怨这个不一致性是……呃……不一致的，不过所有思维健全的人都知道（ -a）K&R是_正确的_，并且（b）K&R是正确的。此外，不管怎样函数都是特殊的（在C语言中 -，函数是不能嵌套的）。 +全世界的异端可能会抱怨这个不一致性是……呃……不一致的，不过所有思维健全的人都知道 +(a) K&R 是 _正确的_，并且 (b) K&R 是正确的。此外，不管怎样函数都是特殊的（C +函数是不能嵌套的）。 -注意结束大括号独自占据一行，除非它后面跟着同一个语句的剩余部分，也就是do语句中的 -“while”或者if语句中的“else”，像这样： +注意结束大括号独自占据一行，除非它后面跟着同一个语句的剩余部分，也就是 do 语句中的 +“while” 或者 if 语句中的 “else”，像这样： do { body of do-loop @@ -158,41 +147,50 @@ a）K&R是_正确的_，并且（b）K&R是正确的。此外，不管怎样函 理由：K&R。 也请注意这种大括号的放置方式也能使空（或者差不多空的）行的数量最小化，同时不失可 -读性。因此，由于你的屏幕上的新行是不可再生资源（想想25行的终端屏幕），你将会有更 +读性。因此，由于你的屏幕上的新行是不可再生资源（想想 25 行的终端屏幕），你将会有更 多的空行来放置注释。 当只有一个单独的语句的时候，不用加不必要的大括号。 -if (condition) - action(); + if (condition) + action(); + +和 + + if (condition) + do_this(); + else + do_that(); -这点不适用于本身为某个条件语句的一个分支的单独语句。这时需要在两个分支里都使用大 -括号。 +这并不适用于只有一个条件分支是单语句的情况；这时所有分支都要使用大括号： -if (condition) { - do_this(); - do_that(); -} else { - otherwise(); -} + if (condition) { + do_this(); + do_that(); + } else { + otherwise(); + } 3.1：空格 -Linux内核的空格使用方式（主要）取决于它是用于函数还是关键字。（大多数）关键字后 -要加一个空格。值得注意的例外是sizeof、typeof、alignof和__attribute__，这些关键字 -某些程度上看起来更像函数（它们在Linux里也常常伴随小括号而使用，尽管在C语言里这样 -的小括号不是必需的，就像“struct fileinfo info”声明过后的“sizeof info”）。 +Linux 内核的空格使用方式（主要）取决于它是用于函数还是关键字。（大多数）关键字后 +要加一个空格。值得注意的例外是 sizeof、typeof、alignof 和 __attribute__，这些 +关键字某些程度上看起来更像函数（它们在 Linux 里也常常伴随小括号而使用，尽管在 C 里 +这样的小括号不是必需的，就像 “struct fileinfo info” 声明过后的 “sizeof info”）。 所以在这些关键字之后放一个空格： + if, switch, case, for, do, while -但是不要在sizeof、typeof、alignof或者__attribute__这些关键字之后放空格。例如， + +但是不要在 sizeof、typeof、alignof 或者 __attribute__ 这些关键字之后放空格。例如， + s = sizeof(struct file); 不要在小括号里的表达式两侧加空格。这是一个反例： s = sizeof( struct file ); -当声明指针类型或者返回指针类型的函数时，“*”的首选使用方式是使之靠近变量名或者函 +当声明指针类型或者返回指针类型的函数时，“*” 的首选使用方式是使之靠近变量名或者函 数名，而不是靠近类型名。例子： char *linux_banner; @@ -204,15 +202,18 @@ Linux内核的空格使用方式（主要）取决于它是用于函数还是关 = + - < > * / % | & ^ <= >= == != ? : 但是一元操作符后不要加空格： + & * + - ~ ! sizeof typeof alignof __attribute__ defined 后缀自加和自减一元操作符前不加空格： + ++ -- 前缀自加和自减一元操作符后不加空格： + ++ -- -“.”和“->”结构体成员操作符前后不加空格。 +‘.’ 和 “->” 结构体成员操作符前后不加空格。 不要在行尾留空白。有些可以自动缩进的编辑器会在新行的行首加入适量的空白，然后你 就可以直接在那一行输入代码。不过假如你最后没有在那一行输入代码，有些编辑器就不 @@ -225,23 +226,23 @@ Linux内核的空格使用方式（主要）取决于它是用于函数还是关 第四章：命名 -C是一个简朴的语言，你的命名也应该这样。和Modula-2和Pascal程序员不同，C程序员不使 -用类似ThisVariableIsATemporaryCounter这样华丽的名字。C程序员会称那个变量为“tmp” -，这样写起来会更容易，而且至少不会令其难于理解。 +C是一个简朴的语言，你的命名也应该这样。和 Modula-2 和 Pascal 程序员不同，C 程序员 +不使用类似 ThisVariableIsATemporaryCounter 这样华丽的名字。C 程序员会称那个变量 +为 “tmp”，这样写起来会更容易，而且至少不会令其难于理解。 不过，虽然混用大小写的名字是不提倡使用的，但是全局变量还是需要一个具描述性的名字 -。称一个全局函数为“foo”是一个难以饶恕的错误。 +。称一个全局函数为 “foo” 是一个难以饶恕的错误。 全局变量（只有当你真正需要它们的时候再用它）需要有一个具描述性的名字，就像全局函 -数。如果你有一个可以计算活动用户数量的函数，你应该叫它“count_active_users()”或者 -类似的名字，你不应该叫它“cntuser()”。 +数。如果你有一个可以计算活动用户数量的函数，你应该叫它 “count_active_users()” +或者类似的名字，你不应该叫它 “cntuser()”。 在函数名中包含函数类型（所谓的匈牙利命名法）是脑子出了问题——编译器知道那些类型而 且能够检查那些类型，这样做只能把程序员弄糊涂了。难怪微软总是制造出有问题的程序。 本地变量名应该简短，而且能够表达相关的含义。如果你有一些随机的整数型的循环计数器 -，它应该被称为“i”。叫它“loop_counter”并无益处，如果它没有被误解的可能的话。类似 -的，“tmp”可以用来称呼任意类型的临时变量。 +，它应该被称为 “i”。叫它 “loop_counter” 并无益处，如果它没有被误解的可能的话。 +类似的，“tmp” 可以用来称呼任意类型的临时变量。 如果你怕混淆了你的本地变量名，你就遇到另一个问题了，叫做函数增长荷尔蒙失衡综合症 。请看第六章（函数）。 @@ -249,9 +250,9 @@ C是一个简朴的语言，你的命名也应该这样。和Modula-2和Pascal 第五章：Typedef -不要使用类似“vps_t”之类的东西。 +不要使用类似 “vps_t” 之类的东西。 -对结构体和指针使用typedef是一个错误。当你在代码里看到： +对结构体和指针使用 typedef 是一个错误。当你在代码里看到： vps_t a; @@ -261,91 +262,91 @@ C是一个简朴的语言，你的命名也应该这样。和Modula-2和Pascal struct virtual_container *a; -你就知道“a”是什么了。 +你就知道 “a” 是什么了。 -很多人认为typedef“能提高可读性”。实际不是这样的。它们只在下列情况下有用： +很多人认为 typedef “能提高可读性”。实际不是这样的。它们只在下列情况下有用： - (a) 完全不透明的对象（这种情况下要主动使用typedef来隐藏这个对象实际上是什么）。 + (a) 完全不透明的对象（这种情况下要主动使用 typedef 来隐藏这个对象实际上是什么）。 - 例如：“pte_t”等不透明对象，你只能用合适的访问函数来访问它们。 + 例如：“pte_t” 等不透明对象，你只能用合适的访问函数来访问它们。 - 注意！不透明性和“访问函数”本身是不好的。我们使用pte_t等类型的原因在于真的是 + 注意！不透明性和“访问函数”本身是不好的。我们使用 pte_t 等类型的原因在于真的是 完全没有任何共用的可访问信息。 - (b) 清楚的整数类型，如此，这层抽象就可以帮助消除到底是“int”还是“long”的混淆。 + (b) 清楚的整数类型，如此，这层抽象就可以帮助消除到底是 “int” 还是 “long” 的混淆。 - u8/u16/u32是完全没有问题的typedef，不过它们更符合类别(d)而不是这里。 + u8/u16/u32 是完全没有问题的 typedef，不过它们更符合类别 (d) 而不是这里。 - 再次注意！要这样做，必须事出有因。如果某个变量是“unsigned long“，那么没有必要 + 再次注意！要这样做，必须事出有因。如果某个变量是 “unsigned long“，那么没有必要 typedef unsigned long myflags_t; - 不过如果有一个明确的原因，比如它在某种情况下可能会是一个“unsigned int”而在 - 其他情况下可能为“unsigned long”，那么就不要犹豫，请务必使用typedef。 + 不过如果有一个明确的原因，比如它在某种情况下可能会是一个 “unsigned int” 而在 + 其他情况下可能为 “unsigned long”，那么就不要犹豫，请务必使用 typedef。 (c) 当你使用sparse按字面的创建一个新类型来做类型检查的时候。 (d) 和标准C99类型相同的类型，在某些例外的情况下。 - 虽然让眼睛和脑筋来适应新的标准类型比如“uint32_t”不需要花很多时间，可是有些 + 虽然让眼睛和脑筋来适应新的标准类型比如 “uint32_t” 不需要花很多时间，可是有些 人仍然拒绝使用它们。 - 因此，Linux特有的等同于标准类型的“u8/u16/u32/u64”类型和它们的有符号类型是被 + 因此，Linux 特有的等同于标准类型的 “u8/u16/u32/u64” 类型和它们的有符号类型是被 允许的——尽管在你自己的新代码中，它们不是强制要求要使用的。 当编辑已经使用了某个类型集的已有代码时，你应该遵循那些代码中已经做出的选择。 (e) 可以在用户空间安全使用的类型。 - 在某些用户空间可见的结构体里，我们不能要求C99类型而且不能用上面提到的“u32” - 类型。因此，我们在与用户空间共享的所有结构体中使用__u32和类似的类型。 + 在某些用户空间可见的结构体里，我们不能要求C99类型而且不能用上面提到的 “u32” + 类型。因此，我们在与用户空间共享的所有结构体中使用 __u32 和类似的类型。 -可能还有其他的情况，不过基本的规则是永远不要使用typedef，除非你可以明确的应用上 +可能还有其他的情况，不过基本的规则是永远不要使用 typedef，除非你可以明确的应用上 述某个规则中的一个。 总的来说，如果一个指针或者一个结构体里的元素可以合理的被直接访问到，那么它们就不 -应该是一个typedef。 +应该是一个 typedef。 第六章：函数 函数应该简短而漂亮，并且只完成一件事情。函数应该可以一屏或者两屏显示完（我们都知 -道ISO/ANSI屏幕大小是80x24），只做一件事情，而且把它做好。 +道 ISO/ANSI 屏幕大小是 80x24），只做一件事情，而且把它做好。 一个函数的最大长度是和该函数的复杂度和缩进级数成反比的。所以，如果你有一个理论上 -很简单的只有一个很长（但是简单）的case语句的函数，而且你需要在每个case里做很多很 -小的事情，这样的函数尽管很长，但也是可以的。 +很简单的只有一个很长（但是简单）的 case 语句的函数，而且你需要在每个 case 里做 +很多很小的事情，这样的函数尽管很长，但也是可以的。 不过，如果你有一个复杂的函数，而且你怀疑一个天分不是很高的高中一年级学生可能甚至 搞不清楚这个函数的目的，你应该严格的遵守前面提到的长度限制。使用辅助函数，并为之 取个具描述性的名字（如果你觉得它们的性能很重要的话，可以让编译器内联它们，这样的 效果往往会比你写一个复杂函数的效果要好。） -函数的另外一个衡量标准是本地变量的数量。此数量不应超过5－10个，否则你的函数就有 +函数的另外一个衡量标准是本地变量的数量。此数量不应超过 5－10 个，否则你的函数就有 问题了。重新考虑一下你的函数，把它分拆成更小的函数。人的大脑一般可以轻松的同时跟 -踪7个不同的事物，如果再增多的话，就会糊涂了。即便你聪颖过人，你也可能会记不清你2 -个星期前做过的事情。 +踪 7 个不同的事物，如果再增多的话，就会糊涂了。即便你聪颖过人，你也可能会记不清你 +2 个星期前做过的事情。 -在源文件里，使用空行隔开不同的函数。如果该函数需要被导出，它的EXPORT*宏应该紧贴 +在源文件里，使用空行隔开不同的函数。如果该函数需要被导出，它的 EXPORT* 宏应该紧贴 在它的结束大括号之下。比如： -int system_is_up(void) -{ - return system_state == SYSTEM_RUNNING; -} -EXPORT_SYMBOL(system_is_up); + int system_is_up(void) + { + return system_state == SYSTEM_RUNNING; + } + EXPORT_SYMBOL(system_is_up); -在函数原型中，包含函数名和它们的数据类型。虽然C语言里没有这样的要求，在Linux里这 +在函数原型中，包含函数名和它们的数据类型。虽然C语言里没有这样的要求，在 Linux 里这 是提倡的做法，因为这样可以很简单的给读者提供更多的有价值的信息。 第七章：集中的函数退出途径 -虽然被某些人声称已经过时，但是goto语句的等价物还是经常被编译器所使用，具体形式是 +虽然被某些人声称已经过时，但是 goto 语句的等价物还是经常被编译器所使用，具体形式是 无条件跳转指令。 -当一个函数从多个位置退出并且需要做一些通用的清理工作的时候，goto的好处就显现出来 -了。 +当一个函数从多个位置退出，并且需要做一些类似清理的常见操作时，goto 语句就很方便了。 +如果并不需要清理操作，那么直接 return 即可。 理由是： @@ -354,26 +355,37 @@ EXPORT_SYMBOL(system_is_up); - 可以避免由于修改时忘记更新某个单独的退出点而导致的错误 - 减轻了编译器的工作，无需删除冗余代码;) -int fun(int a) -{ - int result = 0; - char *buffer = kmalloc(SIZE); - - if (buffer == NULL) - return -ENOMEM; - - if (condition1) { - while (loop1) { - ... + int fun(int a) + { + int result = 0; + char *buffer; + + buffer = kmalloc(SIZE, GFP_KERNEL); + if (!buffer) + return -ENOMEM; + + if (condition1) { + while (loop1) { + ... + } + result = 1; + goto out_buffer; } - result = 1; - goto out; + ... + out_buffer: + kfree(buffer); + return result; } - ... -out: - kfree(buffer); - return result; -} + +一个需要注意的常见错误是“一个 err 错误”，就像这样： + + err: + kfree(foo->bar); + kfree(foo); + return ret; + +这段代码的错误是，在某些退出路径上 “foo” 是 NULL。通常情况下，通过把它分离成两个 +错误标签 “err_bar:” 和 “err_foo:” 来修复这个错误。 第八章：注释 @@ -386,10 +398,10 @@ out: 加太多。你应该做的，是把注释放在函数的头部，告诉人们它做了什么，也可以加上它做这 些事情的原因。 -当注释内核API函数时，请使用kernel-doc格式。请看 -Documentation/kernel-doc-nano-HOWTO.txt和scripts/kernel-doc以获得详细信息。 +当注释内核API函数时，请使用 kernel-doc 格式。请看 +Documentation/kernel-documentation.rst和scripts/kernel-doc 以获得详细信息。 -Linux的注释风格是C89“/* ... */”风格。不要使用C99风格“// ...”注释。 +Linux的注释风格是 C89 “/* ... */” 风格。不要使用 C99 风格 “// ...” 注释。 长（多行）的首选注释风格是： @@ -402,6 +414,15 @@ Linux的注释风格是C89“/* ... */”风格。不要使用C99风格“// ... * with beginning and ending almost-blank lines. */ +对于在 net/ 和 drivers/net/ 的文件，首选的长（多行）注释风格有些不同。 + + /* The preferred comment style for files in net/ and drivers/net + * looks like this. + * + * It is nearly the same as the generally preferred comment style, + * but there is no initial almost-blank line. + */ + 注释数据也是很重要的，不管是基本类型还是衍生类型。为了方便实现这一点，每一行应只 声明一个数据（不要使用逗号来一次声明多个数据）。这样你就有空间来为每个数据写一段 小注释来解释它们的用途了。 @@ -409,49 +430,63 @@ Linux的注释风格是C89“/* ... */”风格。不要使用C99风格“// ... 第九章：你已经把事情弄糟了 -这没什么，我们都是这样。可能你的使用了很长时间Unix的朋友已经告诉你“GNU emacs”能 -自动帮你格式化C源代码，而且你也注意到了，确实是这样，不过它所使用的默认值和我们 -想要的相去甚远（实际上，甚至比随机打的还要差——无数个猴子在GNU emacs里打字永远不 -会创造出一个好程序）（译注：请参考Infinite Monkey Theorem） - -所以你要么放弃GNU emacs，要么改变它让它使用更合理的设定。要采用后一个方案，你可 -以把下面这段粘贴到你的.emacs文件里。 - -(defun linux-c-mode () - "C mode with adjusted defaults for use with the Linux kernel." - (interactive) - (c-mode) - (c-set-style "K&R") - (setq tab-width 8) - (setq indent-tabs-mode t) - (setq c-basic-offset 8)) - -这样就定义了M-x linux-c-mode命令。当你hack一个模块的时候，如果你把字符串 --*- linux-c -*-放在头两行的某个位置，这个模式将会被自动调用。如果你希望在你修改 -/usr/src/linux里的文件时魔术般自动打开linux-c-mode的话，你也可能需要添加 - -(setq auto-mode-alist (cons '("/usr/src/linux.*/.*\\.[ch]$" . linux-c-mode) - auto-mode-alist)) - -到你的.emacs文件里。 - -不过就算你尝试让emacs正确的格式化代码失败了，也并不意味着你失去了一切：还可以用“ -indent”。 - -不过，GNU indent也有和GNU emacs一样有问题的设定，所以你需要给它一些命令选项。不 -过，这还不算太糟糕，因为就算是GNU indent的作者也认同K&R的权威性（GNU的人并不是坏 -人，他们只是在这个问题上被严重的误导了），所以你只要给indent指定选项“-kr -i8” -（代表“K&R，8个字符缩进”），或者使用“scripts/Lindent”，这样就可以以最时髦的方式 +这没什么，我们都是这样。可能你的使用了很长时间 Unix 的朋友已经告诉你 “GNU emacs” 能 +自动帮你格式化 C 源代码，而且你也注意到了，确实是这样，不过它所使用的默认值和我们 +想要的相去甚远（实际上，甚至比随机打的还要差——无数个猴子在 GNU emacs 里打字永远不 +会创造出一个好程序）（译注：请参考 Infinite Monkey Theorem） + +所以你要么放弃 GNU emacs，要么改变它让它使用更合理的设定。要采用后一个方案，你可 +以把下面这段粘贴到你的 .emacs 文件里。 + +(defun c-lineup-arglist-tabs-only (ignored) + "Line up argument lists by tabs, not spaces" + (let* ((anchor (c-langelem-pos c-syntactic-element)) + (column (c-langelem-2nd-pos c-syntactic-element)) + (offset (- (1+ column) anchor)) + (steps (floor offset c-basic-offset))) + (* (max steps 1) + c-basic-offset))) + +(add-hook 'c-mode-common-hook + (lambda () + ;; Add kernel style + (c-add-style + "linux-tabs-only" + '("linux" (c-offsets-alist + (arglist-cont-nonempty + c-lineup-gcc-asm-reg + c-lineup-arglist-tabs-only)))))) + +(add-hook 'c-mode-hook + (lambda () + (let ((filename (buffer-file-name))) + ;; Enable kernel mode for the appropriate files + (when (and filename + (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"))))) + +这会让 emacs 在 ~/src/linux-trees 目录下的 C 源文件获得更好的内核代码风格。 + +不过就算你尝试让 emacs 正确的格式化代码失败了，也并不意味着你失去了一切：还可以用 +“indent”。 + +不过，GNU indent 也有和 GNU emacs 一样有问题的设定，所以你需要给它一些命令选项。不 +过，这还不算太糟糕，因为就算是 GNU indent 的作者也认同 K&R 的权威性（GNU 的人并不是 +坏人，他们只是在这个问题上被严重的误导了），所以你只要给 indent 指定选项 “-kr -i8” +（代表 “K&R，8 个字符缩进”），或者使用 “scripts/Lindent”，这样就可以以最时髦的方式 缩进源代码。 -“indent”有很多选项，特别是重新格式化注释的时候，你可能需要看一下它的手册页。不过 -记住：“indent”不能修正坏的编程习惯。 +“indent” 有很多选项，特别是重新格式化注释的时候，你可能需要看一下它的手册页。不过 +记住：“indent” 不能修正坏的编程习惯。 - 第十章：Kconfig配置文件 + 第十章：Kconfig 配置文件 -对于遍布源码树的所有Kconfig*配置文件来说，它们缩进方式与C代码相比有所不同。紧挨 -在“config”定义下面的行缩进一个制表符，帮助信息则再多缩进2个空格。比如： +对于遍布源码树的所有 Kconfig* 配置文件来说，它们缩进方式与 C 代码相比有所不同。紧挨 +在 “config” 定义下面的行缩进一个制表符，帮助信息则再多缩进 2 个空格。比如： config AUDIT bool "Auditing support" @@ -470,7 +505,7 @@ config ADFS_FS_RW depends on ADFS_FS ... -要查看配置文件的完整文档，请看Documentation/kbuild/kconfig-language.txt。 +要查看配置文件的完整文档，请看 Documentation/kbuild/kconfig-language.txt。 第十一章：数据结构 @@ -489,11 +524,11 @@ config ADFS_FS_RW 很多数据结构实际上有2级引用计数，它们通常有不同“类”的用户。子类计数器统计子类用 户的数量，每当子类计数器减至零时，全局计数器减一。 -这种“多级引用计数”的例子可以在内存管理（“struct mm_struct”：mm_users和mm_count） +这种“多级引用计数”的例子可以在内存管理（“struct mm_struct”：mm_users 和 mm_count） 和文件系统（“struct super_block”：s_count和s_active）中找到。 记住：如果另一个执行线索可以找到你的数据结构，但是这个数据结构没有引用计数器，这 -里几乎肯定是一个bug。 +里几乎肯定是一个 bug。 第十二章：宏，枚举和RTL @@ -508,102 +543,128 @@ config ADFS_FS_RW 一般的，如果能写成内联函数就不要写成像函数的宏。 -含有多个语句的宏应该被包含在一个do-while代码块里： +含有多个语句的宏应该被包含在一个 do-while 代码块里： -#define macrofun(a, b, c) \ - do { \ - if (a == 5) \ - do_this(b, c); \ - } while (0) + #define macrofun(a, b, c) \ + do { \ + if (a == 5) \ + do_this(b, c); \ + } while (0) 使用宏的时候应避免的事情： 1) 影响控制流程的宏： -#define FOO(x) \ - do { \ - if (blah(x) < 0) \ - return -EBUGGERED; \ - } while(0) + #define FOO(x) \ + do { \ + if (blah(x) < 0) \ + return -EBUGGERED; \ + } while (0) 非常不好。它看起来像一个函数，不过却能导致“调用”它的函数退出；不要打乱读者大脑里 的语法分析器。 2) 依赖于一个固定名字的本地变量的宏： -#define FOO(val) bar(index, val) + #define FOO(val) bar(index, val) 可能看起来像是个不错的东西，不过它非常容易把读代码的人搞糊涂，而且容易导致看起来 不相关的改动带来错误。 -3) 作为左值的带参数的宏： FOO(x) = y；如果有人把FOO变成一个内联函数的话，这种用 +3) 作为左值的带参数的宏： FOO(x) = y；如果有人把 FOO 变成一个内联函数的话，这种用 法就会出错了。 4) 忘记了优先级：使用表达式定义常量的宏必须将表达式置于一对小括号之内。带参数的 宏也要注意此类问题。 -#define CONSTANT 0x4000 -#define CONSTEXP (CONSTANT | 3) + #define CONSTANT 0x4000 + #define CONSTEXP (CONSTANT | 3) + +5) 在宏里定义类似函数的本地变量时命名冲突： -cpp手册对宏的讲解很详细。Gcc internals手册也详细讲解了RTL（译注：register + #define FOO(x) \ + ({ \ + typeof(x) ret; \ + ret = calc_ret(x); \ + (ret); \ + }) + +ret 是本地变量的通用名字 - __foo_ret 更不容易与一个已存在的变量冲突。 + +cpp 手册对宏的讲解很详细。gcc internals 手册也详细讲解了 RTL（译注：register transfer language），内核里的汇编语言经常用到它。 第十三章：打印内核消息 内核开发者应该是受过良好教育的。请一定注意内核信息的拼写，以给人以好的印象。不要 -用不规范的单词比如“dont”，而要用“do not”或者“don't”。保证这些信息简单、明了、无 -歧义。 +用不规范的单词比如 “dont”，而要用 “do not”或者 “don't”。保证这些信息简单、明了、 +无歧义。 内核信息不必以句号（译注：英文句号，即点）结束。 -在小括号里打印数字(%d)没有任何价值，应该避免这样做。 +在小括号里打印数字 (%d) 没有任何价值，应该避免这样做。 -<linux/device.h>里有一些驱动模型诊断宏，你应该使用它们，以确保信息对应于正确的 -设备和驱动，并且被标记了正确的消息级别。这些宏有：dev_err(), dev_warn(), -dev_info()等等。对于那些不和某个特定设备相关连的信息，<linux/kernel.h>定义了 -pr_debug()和pr_info()。 +<linux/device.h> 里有一些驱动模型诊断宏，你应该使用它们，以确保信息对应于正确的 +设备和驱动，并且被标记了正确的消息级别。这些宏有：dev_err()，dev_warn()， +dev_info() 等等。对于那些不和某个特定设备相关连的信息，<linux/printk.h> 定义了 +pr_notice()，pr_info()，pr_warn()，pr_err() 和其他。 -写出好的调试信息可以是一个很大的挑战；当你写出来之后，这些信息在远程除错的时候 -就会成为极大的帮助。当DEBUG符号没有被定义的时候，这些信息不应该被编译进内核里 -（也就是说，默认地，它们不应该被包含在内）。如果你使用dev_dbg()或者pr_debug()， -就能自动达到这个效果。很多子系统拥有Kconfig选项来启用-DDEBUG。还有一个相关的惯例 -是使用VERBOSE_DEBUG来添加dev_vdbg()消息到那些已经由DEBUG启用的消息之上。 +写出好的调试信息可以是一个很大的挑战；一旦你写出后，这些信息在远程除错时能提供极大 +的帮助。然而打印调试信息的处理方式同打印非调试信息不同。其他 pr_XXX() 函数能无条件地 +打印，pr_debug() 却不；默认情况下它不会被编译，除非定义了 DEBUG 或设定了 +CONFIG_DYNAMIC_DEBUG。实际这同样是为了 dev_dbg()，一个相关约定是在一个已经开启了 +DEBUG 时，使用 VERBOSE_DEBUG 来添加 dev_vdbg()。 + +许多子系统拥有 Kconfig 调试选项来开启 -DDEBUG 在对应的 Makefile 里面；在其他 +情况下，特殊文件使用 #define DEBUG。当一条调试信息需要被无条件打印时，例如，如果 +已经包含一个调试相关的 #ifdef 条件，printk(KERN_DEBUG ...) 就可被使用。 第十四章：分配内存 -内核提供了下面的一般用途的内存分配函数：kmalloc()，kzalloc()，kcalloc()和 -vmalloc()。请参考API文档以获取有关它们的详细信息。 +内核提供了下面的一般用途的内存分配函数： +kmalloc()，kzalloc()，kmalloc_array()，kcalloc()，vmalloc() 和 vzalloc()。 +请参考 API 文档以获取有关它们的详细信息。 传递结构体大小的首选形式是这样的： p = kmalloc(sizeof(*p), ...); -另外一种传递方式中，sizeof的操作数是结构体的名字，这样会降低可读性，并且可能会引 -入bug。有可能指针变量类型被改变时，而对应的传递给内存分配函数的sizeof的结果不变。 +另外一种传递方式中，sizeof 的操作数是结构体的名字，这样会降低可读性，并且可能会引 +入 bug。有可能指针变量类型被改变时，而对应的传递给内存分配函数的 sizeof 的结果不变。 -强制转换一个void指针返回值是多余的。C语言本身保证了从void指针到其他任何指针类型 +强制转换一个 void 指针返回值是多余的。C 语言本身保证了从 void 指针到其他任何指针类型 的转换是没有问题的。 +分配一个数组的首选形式是这样的： + + p = kmalloc_array(n, sizeof(...), ...); + +分配一个零长数组的首选形式是这样的： + + p = kcalloc(n, sizeof(...), ...); + +两种形式检查分配大小 n * sizeof(...) 的溢出，如果溢出返回 NULL。 + 第十五章：内联弊病 -有一个常见的误解是内联函数是gcc提供的可以让代码运行更快的一个选项。虽然使用内联 +有一个常见的误解是内联函数是 gcc 提供的可以让代码运行更快的一个选项。虽然使用内联 函数有时候是恰当的（比如作为一种替代宏的方式，请看第十二章），不过很多情况下不是 -这样。inline关键字的过度使用会使内核变大，从而使整个系统运行速度变慢。因为大内核 +这样。inline 关键字的过度使用会使内核变大，从而使整个系统运行速度变慢。因为大内核 会占用更多的指令高速缓存（译注：一级缓存通常是指令缓存和数据缓存分开的）而且会导 -致pagecache的可用内存减少。想象一下，一次pagecache未命中就会导致一次磁盘寻址，将 -耗时5毫秒。5毫秒的时间内CPU能执行很多很多指令。 +致 pagecache 的可用内存减少。想象一下，一次pagecache未命中就会导致一次磁盘寻址， +将耗时 5 毫秒。5 毫秒的时间内 CPU 能执行很多很多指令。 -一个基本的原则是如果一个函数有3行以上，就不要把它变成内联函数。这个原则的一个例 +一个基本的原则是如果一个函数有 3 行以上，就不要把它变成内联函数。这个原则的一个例 外是，如果你知道某个参数是一个编译时常量，而且因为这个常量你确定编译器在编译时能 -优化掉你的函数的大部分代码，那仍然可以给它加上inline关键字。kmalloc()内联函数就 +优化掉你的函数的大部分代码，那仍然可以给它加上 inline 关键字。kmalloc() 内联函数就 是一个很好的例子。 -人们经常主张给static的而且只用了一次的函数加上inline，如此不会有任何损失，因为没 -有什么好权衡的。虽然从技术上说这是正确的，但是实际上这种情况下即使不加inline gcc -也可以自动使其内联。而且其他用户可能会要求移除inline，由此而来的争论会抵消inline +人们经常主张给 static 的而且只用了一次的函数加上 inline，如此不会有任何损失，因为没 +有什么好权衡的。虽然从技术上说这是正确的，但是实际上这种情况下即使不加 inline gcc +也可以自动使其内联。而且其他用户可能会要求移除 inline，由此而来的争论会抵消 inline 自身的潜在价值，得不偿失。 @@ -613,37 +674,37 @@ vmalloc()。请参考API文档以获取有关它们的详细信息。 的一个值可以表示为一个错误代码整数（-Exxx＝失败，0＝成功）或者一个“成功”布尔值（ 0＝失败，非0＝成功）。 -混合使用这两种表达方式是难于发现的bug的来源。如果C语言本身严格区分整形和布尔型变 -量，那么编译器就能够帮我们发现这些错误……不过C语言不区分。为了避免产生这种bug，请 +混合使用这两种表达方式是难于发现的 bug 的来源。如果 C 语言本身严格区分整形和布尔型变 +量，那么编译器就能够帮我们发现这些错误……不过 C 语言不区分。为了避免产生这种 bug，请 遵循下面的惯例： 如果函数的名字是一个动作或者强制性的命令，那么这个函数应该返回错误代码整 数。如果是一个判断，那么函数应该返回一个“成功”布尔值。 -比如，“add work”是一个命令，所以add_work()函数在成功时返回0，在失败时返回-EBUSY。 -类似的，因为“PCI device present”是一个判断，所以pci_dev_present()函数在成功找到 -一个匹配的设备时应该返回1，如果找不到时应该返回0。 +比如，“add work” 是一个命令，所以 add_work() 函数在成功时返回 0，在失败时返回 -EBUSY。 +类似的，因为 “PCI device present” 是一个判断，所以 pci_dev_present() 函数在成功找到 +一个匹配的设备时应该返回 1，如果找不到时应该返回 0。 所有导出（译注：EXPORT）的函数都必须遵守这个惯例，所有的公共函数也都应该如此。私 有（static）函数不需要如此，但是我们也推荐这样做。 返回值是实际计算结果而不是计算是否成功的标志的函数不受此惯例的限制。一般的，他们 通过返回一些正常值范围之外的结果来表示出错。典型的例子是返回指针的函数，他们使用 -NULL或者ERR_PTR机制来报告错误。 +NULL 或者 ERR_PTR 机制来报告错误。 第十七章：不要重新发明内核宏 -头文件include/linux/kernel.h包含了一些宏，你应该使用它们，而不要自己写一些它们的 +头文件 include/linux/kernel.h 包含了一些宏，你应该使用它们，而不要自己写一些它们的 变种。比如，如果你需要计算一个数组的长度，使用这个宏 - #define ARRAY_SIZE(x) (sizeof(x) / sizeof((x)[0])) + #define ARRAY_SIZE(x) (sizeof(x) / sizeof((x)[0])) 类似的，如果你要计算某结构体成员的大小，使用 - #define FIELD_SIZEOF(t, f) (sizeof(((t*)0)->f)) + #define FIELD_SIZEOF(t, f) (sizeof(((t*)0)->f)) -还有可以做严格的类型检查的min()和max()宏，如果你需要可以使用它们。你可以自己看看 +还有可以做严格的类型检查的 min() 和 max() 宏，如果你需要可以使用它们。你可以自己看看 那个头文件里还定义了什么你可以拿来用的东西，如果有定义的话，你就不应在你的代码里 自己重新定义。 @@ -653,42 +714,100 @@ NULL或者ERR_PTR机制来报告错误。 有一些编辑器可以解释嵌入在源文件里的由一些特殊标记标明的配置信息。比如，emacs 能够解释被标记成这样的行： --*- mode: c -*- + -*- mode: c -*- 或者这样的： -/* -Local Variables: -compile-command: "gcc -DMAGIC_DEBUG_FLAG foo.c" -End: -*/ + /* + Local Variables: + compile-command: "gcc -DMAGIC_DEBUG_FLAG foo.c" + End: + */ -Vim能够解释这样的标记： +Vim 能够解释这样的标记： -/* vim:set sw=8 noet */ + /* vim:set sw=8 noet */ 不要在源代码中包含任何这样的内容。每个人都有他自己的编辑器配置，你的源文件不应 该覆盖别人的配置。这包括有关缩进和模式配置的标记。人们可以使用他们自己定制的模 式，或者使用其他可以产生正确的缩进的巧妙方法。 + 第十九章：内联汇编 + +在特定架构的代码中，你也许需要内联汇编来使用 CPU 接口和平台相关功能。在需要 +这么做时，不要犹豫。然而，当 C 可以完成工作时，不要无端地使用内联汇编。如果 +可能，你可以并且应该用 C 和硬件交互。 + +考虑去写通用一点的内联汇编作为简明的辅助函数，而不是重复写下它们的细节。记住 +内联汇编可以使用 C 参数。 + +大而特殊的汇编函数应该放在 .S 文件中，对应 C 的原型定义在 C 头文件中。汇编 +函数的 C 原型应该使用 “asmlinkage”。 + +你可能需要将你的汇编语句标记为 volatile，来阻止 GCC 在没发现任何副作用后就 +移除了它。你不必总是这样做，虽然，这样可以限制不必要的优化。 + +在写一个包含多条指令的单个内联汇编语句时，把每条指令用引号字符串分离，并写在 +单独一行，在每个字符串结尾，除了 \n\t 结尾之外，在汇编输出中适当地缩进下 +一条指令： + + asm ("magic %reg1, #42\n\t" + "more_magic %reg2, %reg3" + : /* outputs */ : /* inputs */ : /* clobbers */); + + + 第二十章：条件编译 + +只要可能，就不要在 .c 文件里面使用预处理条件；这样做让代码更难阅读并且逻辑难以 +跟踪。替代方案是，在头文件定义函数在这些 .c 文件中使用这类的条件表达式，提供空 +操作的桩版本（译注：桩程序，是指用来替换一部分功能的程序段）在 #else 情况下， +再从 .c 文件中无条件地调用这些函数。编译器会避免生成任何桩调用的代码，产生一致 +的结果，但逻辑将更加清晰。 + +宁可编译整个函数，而不是部分函数或部分表达式。而不是在一个表达式添加 ifdef， +解析部分或全部表达式到一个单独的辅助函数，并应用条件到该函数内。 + +如果你有一个在特定配置中可能是未使用的函数或变量，编译器将警告它定义了但未使用， +标记这个定义为 __maybe_unused 而不是将它包含在一个预处理条件中。（然而，如果 +一个函数或变量总是未使用的，就直接删除它。） + +在代码中，可能的情况下，使用 IS_ENABLED 宏来转化某个 Kconfig 标记为 C 的布尔 +表达式，并在正常的 C 条件中使用它： + + if (IS_ENABLED(CONFIG_SOMETHING)) { + ... + } + +编译器会无条件地做常数合并，就像使用 #ifdef 那样，包含或排除代码块，所以这不会 +带来任何运行时开销。然而，这种方法依旧允许 C 编译器查看块内的代码，并检查它的正确 +性（语法，类型，符号引用，等等）。因此，如果条件不满足，代码块内的引用符号将不存在， +你必须继续使用 #ifdef。 + +在任何有意义的 #if 或 #ifdef 块的末尾（超过几行），在 #endif 同一行的后面写下 +注释，指出该条件表达式被使用。例如： + + #ifdef CONFIG_SOMETHING + ... + #endif /* CONFIG_SOMETHING */ + 附录 I：参考 -The C Programming Language, 第二版, 作者Brian W. Kernighan和Denni -M. Ritchie. Prentice Hall, Inc., 1988. ISBN 0-13-110362-8 (软皮), -0-13-110370-9 (硬皮). URL: http://cm.bell-labs.com/cm/cs/cbook/ +The C Programming Language, 第二版 +作者：Brian W. Kernighan 和 Denni M. Ritchie. +Prentice Hall, Inc., 1988. +ISBN 0-13-110362-8 (软皮), 0-13-110370-9 (硬皮). -The Practice of Programming 作者Brian W. Kernighan和Rob Pike. Addison-Wesley, -Inc., 1999. ISBN 0-201-61586-X. URL: http://cm.bell-labs.com/cm/cs/tpop/ +The Practice of Programming +作者：Brian W. Kernighan 和 Rob Pike. +Addison-Wesley, Inc., 1999. +ISBN 0-201-61586-X. -cpp，gcc，gcc internals和indent的GNU手册——和K&R及本文相符合的部分，全部可以在 -http://www.gnu.org/manual/找到 +GNU 手册 - 遵循 K&R 标准和此文本 - cpp, gcc, gcc internals and indent, +都可以从 http://www.gnu.org/manual/ 找到 WG14是C语言的国际标准化工作组，URL: http://www.open-std.org/JTC1/SC22/WG14/ -Kernel CodingStyle，作者greg@kroah.com发表于OLS 2002： +Kernel CodingStyle，作者 greg@kroah.com 发表于OLS 2002： http://www.kroah.com/linux/talks/ols_2002_kernel_codingstyle_talk/html/ - --- -最后更新于2007年7月13日。 |